nazar-salary 1.7.2 → 2.1.1

package/index.d.ts

@@ -57,6 +57,194 @@ declare module 'nazar-salary' {
     new_password?: string;
   }
 
+  export interface BankReceiptUploadResponse {
+    status: 'processing';
+    log_id: number;
+    message: string;
+  }
+
+  export interface BankReceiptStatusResponse {
+    status: 'processing' | 'completed' | 'failed';
+    log_id: number;
+    file_name: string;
+    uploaded_by: string;
+    uploaded_at: number;
+    completed_at?: number;
+    summary?: BankReceiptSummary;
+    details?: {
+      verified_students: VerifiedStudent[];
+      discrepancies: PaymentDiscrepancy[];
+      orphan_payments: OrphanPayment[];
+    };
+    error_message?: string;
+  }
+
+  export interface BankReceiptListItem {
+    log_id: number;
+    file_name: string;
+    status: 'processing' | 'completed' | 'failed';
+    uploaded_by: string;
+    uploaded_at: number;
+    completed_at?: number;
+    summary?: {
+      total_transactions: number;
+      verified: number;
+      discrepancies: number;
+      orphan_payments: number;
+    };
+    error_message?: string;
+  }
+
+  export interface BankReceiptsListParams {
+    page?: number;
+    limit?: number;
+    status?: 'processing' | 'completed' | 'failed';
+  }
+
+  export interface BankReceiptsListResponse {
+    receipts: BankReceiptListItem[];
+    pagination: Pagination;
+  }
+
+  export interface BankReceiptSummary {
+    total_transactions: number;
+    processed_transactions: number;
+    verified_count: number;
+    discrepancies_count: number;
+    orphan_payments_count: number;
+    skipped_count: number;
+    skipped_non_purchase: number;
+    skipped_amount_too_low: number;
+  }
+
+  export interface VerifiedStudent {
+    student_purchase_id: number;
+    student_id: number;
+    student_name: string;
+    manager_name: string;
+    amount: number;
+    commission: number;
+    net_amount: number;
+    manager_commission: number;
+    payment_method: string;
+    transaction_date: string;
+    operation_number: string;
+  }
+
+  export interface PaymentDiscrepancy {
+    student_purchase_id: number;
+    student_id: number;
+    student_name: string;
+    manager_name: string;
+    system_amount: number;
+    bank_amount: number;
+    discrepancy: number;
+    operation_number: string;
+  }
+
+  export interface OrphanPayment {
+    store_address: string;
+    operation_date: string;
+    operation_time: string;
+    amount: number;
+    commission: number;
+    payment_method: string;
+    operation_number: string;
+    purchase_details: string;
+  }
+
+  export interface BankReceiptResponse {
+    summary: BankReceiptSummary;
+    verified_students: VerifiedStudent[];
+    discrepancies: PaymentDiscrepancy[];
+    orphan_payments: OrphanPayment[];
+  }
+
+  export interface UploadBankReceiptOptions {
+    period_from?: string;
+    period_to?: string;
+  }
+
+  export interface ManualPaymentData {
+    operation_number: string;
+    bank_id: string;
+    payment_method: string;
+    amount: number;
+    transaction_date?: string;
+    transaction_time?: string;
+    comment?: string;
+  }
+
+  export interface ManualPaymentStudent {
+    id: number;
+    first_name: string;
+    last_name: string;
+    phone?: string;
+    manager_name?: string;
+    purchase_amount?: number;
+    is_verified: boolean;
+    verified_at?: string;
+  }
+
+  export interface ManualPaymentDetails {
+    operation_number: string;
+    amount: number;
+    bank_commission?: number;
+    net_amount?: number;
+    manager_commission?: number;
+    discrepancy_amount?: number;
+    payment_method?: string;
+    manual_verification?: boolean;
+    verified_by?: number;
+  }
+
+  export interface ManualPaymentResponse {
+    status: 'success' | 'error';
+    result: 'verified' | 'discrepancy' | 'orphan';
+    message: string;
+    student?: ManualPaymentStudent;
+    payment: ManualPaymentDetails;
+    code?: string;
+    details?: any;
+  }
+
+  export interface OrphanPaymentItem {
+    id: number;
+    operation_number: string;
+    amount: number;
+    bank_name: string;
+    payment_method: string;
+    commission_rate: number;
+    bank_commission: number;
+    net_amount: number;
+    transaction_date?: string;
+    transaction_time?: string;
+    comment?: string;
+    created_by: string;
+    created_at: string;
+  }
+
+  export interface OrphanPaymentsResponse {
+    orphan_payments: OrphanPaymentItem[];
+    pagination: Pagination;
+  }
+
+  export interface PaymentMethod {
+    payment_method_id: string;
+    payment_method_name: string;
+    commission_rate: number;
+  }
+
+  export interface BankConfig {
+    bank_id: string;
+    bank_name: string;
+    payment_methods: PaymentMethod[];
+  }
+
+  export interface BanksConfigResponse {
+    banks: BankConfig[];
+  }
+
   export interface UpdateUserData {
     first_name?: string;
     last_name?: string;
@@ -515,6 +703,12 @@ declare module 'nazar-salary' {
     getManagers(): Promise<ManagersResponse>;
     updateManager(managerId: number, data: UpdateManagerData): Promise<UpdateManagerResponse>;
     deleteManager(managerId: number): Promise<void>;
+    uploadKaspiReceipt(file: File | Buffer, options?: UploadBankReceiptOptions): Promise<BankReceiptUploadResponse>;
+    getReceiptsList(params?: BankReceiptsListParams): Promise<BankReceiptsListResponse>;
+    getReceiptStatus(logId: number): Promise<BankReceiptStatusResponse>;
+    addManualPayment(data: ManualPaymentData): Promise<ManualPaymentResponse>;
+    getOrphanPayments(params?: { page?: number; limit?: number }): Promise<OrphanPaymentsResponse>;
+    getBanksConfig(): Promise<BanksConfigResponse>;
 
     // Teacher endpoints
     getTeacherLanguages(): Promise<TeacherLanguagesResponse>;

package/index.js

@@ -177,6 +177,85 @@ class SalaryAPI {
     return await this.client.delete(`/api/v1/admin/manager/${managerId}`);
   }
 
+  /**
+   * Upload bank receipt Excel file for verification (Admin only)
+   * Supports Kaspi only
+   * Processing happens asynchronously, use getReceiptStatus to check progress
+   * @param {File|Buffer} file - Excel file (.xlsx) with bank statement
+   * @param {object} [options] - Upload options
+   * @param {string} [options.period_from] - Period start date (YYYY-MM-DD)
+   * @param {string} [options.period_to] - Period end date (YYYY-MM-DD)
+   * @returns {Promise<{status: string, log_id: number, message: string}>}
+   */
+  async uploadKaspiReceipt(file, options = {}) {
+    const formData = new FormData();
+    formData.append('file', file);
+    if (options.period_from) formData.append('period_from', options.period_from);
+    if (options.period_to) formData.append('period_to', options.period_to);
+
+    return await this.client.post("/api/v1/admin/receipts/upload", formData, {
+      headers: {
+        'Content-Type': 'multipart/form-data',
+      },
+    });
+  }
+
+  /**
+   * Get list of all receipt uploads (Admin only)
+   * @param {object} [params] - Query parameters
+   * @param {number} [params.page=1] - Page number
+   * @param {number} [params.limit=20] - Items per page
+   * @param {string} [params.status] - Filter by status (processing, completed, failed)
+   * @returns {Promise<{receipts: array, pagination: object}>}
+   */
+  async getReceiptsList(params = {}) {
+    return await this.client.get("/api/v1/admin/receipts/", { params });
+  }
+
+  /**
+   * Get bank receipt processing status (Admin only)
+   * @param {number} logId - Receipt log ID from uploadKaspiReceipt
+   * @returns {Promise<{status: string, log_id: number, file_name: string, summary?: object, details?: object, error_message?: string}>}
+   */
+  async getReceiptStatus(logId) {
+    return await this.client.get(`/api/v1/admin/receipts/logs/${logId}`);
+  }
+
+  /**
+   * Manually add payment from non-Kaspi banks (Admin only)
+   * @param {object} data - Payment data
+   * @param {string} data.operation_number - 11-digit operation number
+   * @param {string} data.bank_id - Bank ID (halyk, forte, jusan, freedom, centercredit)
+   * @param {string} data.payment_method - Payment method ID
+   * @param {number} data.amount - Payment amount (2000-10000000 KZT)
+   * @param {string} [data.transaction_date] - Transaction date
+   * @param {string} [data.transaction_time] - Transaction time
+   * @param {string} [data.comment] - Comment (max 500 chars)
+   * @returns {Promise<{status: string, result: string, message: string, student?: object, payment: object}>}
+   */
+  async addManualPayment(data) {
+    return await this.client.post("/api/v1/admin/receipts/manual-add", data);
+  }
+
+  /**
+   * Get list of orphan (unused) payments (Admin only)
+   * @param {object} [params] - Query parameters
+   * @param {number} [params.page=1] - Page number
+   * @param {number} [params.limit=30] - Items per page
+   * @returns {Promise<{orphan_payments: array, pagination: object}>}
+   */
+  async getOrphanPayments(params = {}) {
+    return await this.client.get("/api/v1/admin/receipts/orphan", { params });
+  }
+
+  /**
+   * Get available banks and payment methods configuration (Admin only)
+   * @returns {Promise<{banks: array}>}
+   */
+  async getBanksConfig() {
+    return await this.client.get("/api/v1/admin/receipts/banks");
+  }
+
   // ===== TEACHER ENDPOINTS =====
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nazar-salary",
-  "version": "1.7.2",
+  "version": "2.1.1",
   "description": "Frontend library for Nazar Salary API",
   "main": "index.js",
   "types": "index.d.ts",