nazar-salary 1.7.2 → 2.0.1

package/index.d.ts

@@ -57,6 +57,114 @@ 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 UpdateUserData {
     first_name?: string;
     last_name?: string;
@@ -515,6 +623,9 @@ 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>;
 
     // Teacher endpoints
     getTeacherLanguages(): Promise<TeacherLanguagesResponse>;

package/index.js

@@ -177,6 +177,50 @@ class SalaryAPI {
     return await this.client.delete(`/api/v1/admin/manager/${managerId}`);
   }
 
+  /**
+   * Upload bank receipt Excel file for verification (Admin only)
+   * Supports Kaspi, Halyk, Jusan and other bank statements
+   * 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/${logId}`);
+  }
+
   // ===== TEACHER ENDPOINTS =====
 
   /**

package/package.json

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