nazar-salary 3.4.6 → 3.4.8

package/index.d.ts

@@ -453,6 +453,74 @@ declare module 'nazar-salary' {
     prices: Price[];
   }
 
+  /** Price with aggregated student/revenue stats — returned by getPricesList() only */
+  export interface PriceWithStats extends Price {
+    /** Gross sales attributed to this tariff (purchase_amount, before bank commission, verified and not) */
+    total_amount: number;
+    /** Distinct students with at least one active course on this tariff */
+    active_students: number;
+    /** Distinct students whose courses on this tariff are all closed */
+    inactive_students: number;
+  }
+
+  export interface PricesListResponse {
+    prices: PriceWithStats[];
+  }
+
+  export interface PriceStudent {
+    price_id: number;
+    price_name: string;
+    student_id: number;
+    first_name: string;
+    last_name: string;
+    phone: string;
+    completed_lessons: number;
+    total_lessons: number;
+    remaining_lessons: number;
+    /** Enrollment length in months */
+    enrollment_months: number;
+    /** Current tariff rate per lesson */
+    rate_per_lesson: number;
+    /** Gross payments attributed to this student on this tariff */
+    purchase_amount: number;
+    teacher_id: number | null;
+    teacher_name: string | null;
+    /** Owner of the student (student_history.owned_by) */
+    manager_id: number | null;
+    manager_name: string | null;
+    manager_role: 'manager' | 'admin' | null;
+    /** Whether the course itself is active */
+    is_active: boolean;
+    /** Student-level status, independent of the course */
+    student_status: 'active' | 'waiting' | 'cancelled';
+    group_name: string | null;
+    main_course: string;
+    student_history_id: number;
+    /** Course start date, ms timestamp */
+    created_at: number;
+    /** Student sale/registration date (students.created_at) — what created_from/created_to filter on */
+    student_created_at: number;
+  }
+
+  export interface PriceStudentsResponse {
+    price: {
+      id: number;
+      name: string;
+      format: PriceFormat;
+      lesson_type: LessonType;
+      lessons_per_month: number;
+      duration_minutes: number;
+      rate_per_lesson: number;
+    };
+    pagination: {
+      page: number;
+      limit: number;
+      total: number;
+      pages: number;
+    };
+    students: PriceStudent[];
+  }
+
   export interface PriceHistoryItem {
     id: number;
     format: PriceFormat;
@@ -1703,7 +1771,9 @@ declare module 'nazar-salary' {
     updatePrice(priceId: number, data: UpdatePriceData): Promise<Price>;
     getPriceHistory(priceId: number): Promise<PriceHistoryResponse>;
     deletePrice(priceId: number): Promise<void>;
-    getPricesList(): Promise<PricesResponse>;
+    getPricesList(): Promise<PricesListResponse>;
+    getPriceStudents(priceId: number, params?: { status?: 'active' | 'inactive'; created_from?: string; created_to?: string; page?: number; limit?: number }): Promise<PriceStudentsResponse>;
+    exportPriceStudents(prices?: number[] | string, options?: { status?: 'active' | 'inactive'; created_from?: string; created_to?: string }): Promise<ArrayBuffer>;
 
     // Student endpoints
     createStudent(data: CreateStudentData): Promise<CreateStudentResponse>;

package/index.js

@@ -527,13 +527,32 @@ class SalaryAPI {
 
   /**
    * Get list of all prices (requireAuth - for managers)
-   * Returns prices with latest history data
-   * @returns {Promise<{prices: array}>}
+   * Returns prices with latest history data plus per-tariff stats:
+   * total_amount (gross sales), active_students, inactive_students
+   * @returns {Promise<PricesListResponse>}
    */
   async getPricesList() {
     return await this.client.get("/api/v1/price/");
   }
 
+  /**
+   * Get students of a tariff (requireAuth - for managers)
+   * One row per student — their latest course on that tariff
+   * @param {number} priceId - Price/tariff ID
+   * @param {object} [params]
+   * @param {'active'|'inactive'} [params.status] - Filter by course state
+   * @param {string} [params.created_from] - Student sale date from, YYYY-MM-DD or ISO 8601
+   * @param {string} [params.created_to] - Student sale date to, inclusive
+   * @param {number} [params.page=1]
+   * @param {number} [params.limit=30] - Max 200
+   * @returns {Promise<PriceStudentsResponse>}
+   */
+  async getPriceStudents(priceId, params = {}) {
+    return await this.client.get(`/api/v1/price/${priceId}/students`, {
+      params,
+    });
+  }
+
   // ===== STUDENT ENDPOINTS =====
 
   /**
@@ -1050,6 +1069,30 @@ class SalaryAPI {
     });
   }
 
+  /**
+   * Export students of selected tariffs as an Excel file (requireAuth)
+   * Single sheet, one row per student, with a tariff name column
+   * @param {number[]|string} [prices] - Tariff IDs, e.g. [1,2,3] or "1,2,3". Omit for all tariffs
+   * @param {object} [options]
+   * @param {'active'|'inactive'} [options.status] - Filter by course state
+   * @param {string} [options.created_from] - Student sale date from, YYYY-MM-DD or ISO 8601
+   * @param {string} [options.created_to] - Student sale date to, inclusive
+   * @returns {Promise<ArrayBuffer>} Excel file
+   */
+  async exportPriceStudents(prices, options = {}) {
+    const params = {};
+    if (prices !== undefined && prices !== null) {
+      params.prices = Array.isArray(prices) ? prices.join(",") : prices;
+    }
+    if (options.status !== undefined) params.status = options.status;
+    if (options.created_from !== undefined) params.created_from = options.created_from;
+    if (options.created_to !== undefined) params.created_to = options.created_to;
+    return await this.client.get("/api/v1/price/students/export", {
+      params,
+      responseType: "arraybuffer",
+    });
+  }
+
   /**
    * Export students by manager as Excel file (Admin only)
    * @param {number} managerId - Manager (МЗК) ID (required)

package/package.json

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