hvp-shared 6.11.0 → 6.13.0

package/dist/contracts/qvet/responses.d.ts

@@ -1,11 +1,31 @@
 /**
  * QVET API Response Types
  *
- * Response interfaces for QVET data endpoints.
- * Used by frontend to consume synced QVET data.
+ * Item types and data payloads for QVET endpoints.
+ *
+ * ## Response Pattern
+ *
+ * Backend uses standard ApiResponse types from hvp-shared:
+ * - Lists: `ApiListSuccessResponse<QvetSaleResponse[]>` with meta/links
+ * - Single: `ApiSingleSuccessResponse<QvetSalesSummaryData>`
+ * - Arrays (no pagination): `ApiSingleSuccessResponse<QvetSalesBySectionItem[]>`
+ *
+ * Frontend receives standard format:
+ * ```json
+ * {
+ *   "ok": true,
+ *   "status_code": 200,
+ *   "resource": "qvet-sales",
+ *   "operation": "all",
+ *   "data": [...],
+ *   "meta": { "total": 100, "page": 1, "limit": 25, "totalPages": 4, "itemsOnPage": 25 },
+ *   "links": { "current": "...", "next": "...", ... }
+ * }
+ * ```
  */
 /**
- * Standard pagination info for QVET endpoints
+ * @deprecated No longer used. Backend uses standard ApiListSuccessResponse with meta.
+ * Kept for backward compatibility during migration.
  */
 export interface QvetPagination {
     total: number;
@@ -14,16 +34,8 @@ export interface QvetPagination {
     hasMore: boolean;
 }
 /**
- * Generic paginated response for QVET list endpoints
- * Use this for all QVET list endpoints to ensure consistent pagination format.
- *
- * @example
- * // Backend returns this structure:
- * {
- *   ok: true,
- *   data: [...],
- *   pagination: { total: 100, limit: 25, skip: 0, hasMore: true }
- * }
+ * @deprecated No longer used. Backend uses ApiListSuccessResponse<T[]> directly.
+ * Kept for backward compatibility during migration.
  */
 export interface QvetPaginatedResponse<T> {
     ok: boolean;
@@ -65,29 +77,34 @@ export interface QvetSaleResponse {
     syncedAt: string;
 }
 /**
- * Paginated list of sales
- * Uses generic QvetPaginatedResponse for consistent pagination format.
+ * @deprecated Use ApiListSuccessResponse<QvetSaleResponse[]> instead.
  */
 export type QvetSalesListResponse = QvetPaginatedResponse<QvetSaleResponse>;
 /**
- * Sales summary statistics for a period
+ * Sales summary statistics data for a period.
+ * Backend wraps with: ApiSingleSuccessResponse<QvetSalesSummaryData>
+ */
+export interface QvetSalesSummaryData {
+    totalRecords: number;
+    totalSales: number;
+    totalSubtotal: number;
+    totalTax: number;
+    totalDiscount: number;
+    totalQuantity: number;
+    avgTicket: number;
+    uniqueCustomers: number;
+    uniqueProducts: number;
+}
+/**
+ * @deprecated Use QvetSalesSummaryData with ApiSingleSuccessResponse.
  */
 export interface QvetSalesSummaryResponse {
     ok: boolean;
-    data: {
-        totalRecords: number;
-        totalSales: number;
-        totalSubtotal: number;
-        totalTax: number;
-        totalDiscount: number;
-        totalQuantity: number;
-        avgTicket: number;
-        uniqueCustomers: number;
-        uniqueProducts: number;
-    };
+    data: QvetSalesSummaryData;
 }
 /**
- * Sales by section aggregation
+ * Sales by section aggregation item.
+ * Backend returns: ApiSingleSuccessResponse<QvetSalesBySectionItem[]>
  */
 export interface QvetSalesBySectionItem {
     section: string;
@@ -95,10 +112,6 @@ export interface QvetSalesBySectionItem {
     totalQuantity: number;
     recordCount: number;
 }
-export interface QvetSalesBySectionResponse {
-    ok: boolean;
-    data: QvetSalesBySectionItem[];
-}
 /**
  * Query parameters for sales endpoint
  */
@@ -114,6 +127,7 @@ export interface QvetSalesQueryParams {
     qvetCode?: number;
     customerName?: string;
     limit?: number;
+    page?: number;
     skip?: number;
     sort?: string;
 }
@@ -151,29 +165,34 @@ export interface QvetPurchaseResponse {
     syncedAt: string;
 }
 /**
- * Paginated list of purchases
- * Uses generic QvetPaginatedResponse for consistent pagination format.
+ * @deprecated Use ApiListSuccessResponse<QvetPurchaseResponse[]> instead.
  */
 export type QvetPurchasesListResponse = QvetPaginatedResponse<QvetPurchaseResponse>;
 /**
- * Purchases summary statistics for a period
+ * Purchases summary statistics data for a period.
+ * Backend wraps with: ApiSingleSuccessResponse<QvetPurchasesSummaryData>
+ */
+export interface QvetPurchasesSummaryData {
+    totalRecords: number;
+    totalPurchases: number;
+    totalSubtotal: number;
+    totalTax: number;
+    totalDiscount: number;
+    totalQuantity: number;
+    avgPurchase: number;
+    uniqueSuppliers: number;
+    uniqueProducts: number;
+}
+/**
+ * @deprecated Use QvetPurchasesSummaryData with ApiSingleSuccessResponse.
  */
 export interface QvetPurchasesSummaryResponse {
     ok: boolean;
-    data: {
-        totalRecords: number;
-        totalPurchases: number;
-        totalSubtotal: number;
-        totalTax: number;
-        totalDiscount: number;
-        totalQuantity: number;
-        avgPurchase: number;
-        uniqueSuppliers: number;
-        uniqueProducts: number;
-    };
+    data: QvetPurchasesSummaryData;
 }
 /**
- * Purchases by supplier aggregation
+ * Purchases by supplier aggregation item.
+ * Backend returns: ApiSingleSuccessResponse<QvetPurchasesBySupplierItem[]>
  */
 export interface QvetPurchasesBySupplierItem {
     supplier: string;
@@ -181,10 +200,6 @@ export interface QvetPurchasesBySupplierItem {
     totalQuantity: number;
     recordCount: number;
 }
-export interface QvetPurchasesBySupplierResponse {
-    ok: boolean;
-    data: QvetPurchasesBySupplierItem[];
-}
 /**
  * Query parameters for purchases endpoint
  */
@@ -200,6 +215,7 @@ export interface QvetPurchasesQueryParams {
     supplier?: string;
     qvetCode?: number;
     limit?: number;
+    page?: number;
     skip?: number;
     sort?: string;
 }
@@ -230,26 +246,34 @@ export interface QvetMovementResponse {
     syncedAt: string;
 }
 /**
- * Paginated list of movements
- * Uses generic QvetPaginatedResponse for consistent pagination format.
+ * @deprecated Use ApiListSuccessResponse<QvetMovementResponse[]> instead.
  */
 export type QvetMovementsListResponse = QvetPaginatedResponse<QvetMovementResponse>;
 /**
- * Movements summary statistics for a period
+ * Movement type breakdown item.
+ */
+export interface MovementTypeBreakdown {
+    type: string;
+    count: number;
+    totalQuantity: number;
+}
+/**
+ * Movements summary statistics data for a period.
+ * Backend wraps with: ApiSingleSuccessResponse<QvetMovementsSummaryData>
+ */
+export interface QvetMovementsSummaryData {
+    totalRecords: number;
+    totalQuantityIn: number;
+    totalQuantityOut: number;
+    uniqueProducts: number;
+    byMovementType: MovementTypeBreakdown[];
+}
+/**
+ * @deprecated Use QvetMovementsSummaryData with ApiSingleSuccessResponse.
  */
 export interface QvetMovementsSummaryResponse {
     ok: boolean;
-    data: {
-        totalRecords: number;
-        totalQuantityIn: number;
-        totalQuantityOut: number;
-        uniqueProducts: number;
-        byMovementType: Array<{
-            type: string;
-            count: number;
-            totalQuantity: number;
-        }>;
-    };
+    data: QvetMovementsSummaryData;
 }
 /**
  * Query parameters for movements endpoint
@@ -267,6 +291,7 @@ export interface QvetMovementsQueryParams {
     family?: string;
     qvetCode?: number;
     limit?: number;
+    page?: number;
     skip?: number;
     sort?: string;
 }
@@ -296,23 +321,27 @@ export interface QvetTransferResponse {
     syncedAt: string;
 }
 /**
- * Paginated list of transfers
- * Uses generic QvetPaginatedResponse for consistent pagination format.
+ * @deprecated Use ApiListSuccessResponse<QvetTransferResponse[]> instead.
  */
 export type QvetTransfersListResponse = QvetPaginatedResponse<QvetTransferResponse>;
 /**
- * Transfers summary statistics for a period
+ * Transfers summary statistics data for a period.
+ * Backend wraps with: ApiSingleSuccessResponse<QvetTransfersSummaryData>
+ */
+export interface QvetTransfersSummaryData {
+    totalRecords: number;
+    totalQuantity: number;
+    totalValue: number;
+    uniqueProducts: number;
+    sourceWarehouses: number;
+    targetWarehouses: number;
+}
+/**
+ * @deprecated Use QvetTransfersSummaryData with ApiSingleSuccessResponse.
  */
 export interface QvetTransfersSummaryResponse {
     ok: boolean;
-    data: {
-        totalRecords: number;
-        totalQuantity: number;
-        totalValue: number;
-        uniqueProducts: number;
-        sourceWarehouses: number;
-        targetWarehouses: number;
-    };
+    data: QvetTransfersSummaryData;
 }
 /**
  * Query parameters for transfers endpoint
@@ -327,9 +356,16 @@ export interface QvetTransfersQueryParams {
     targetWarehouse?: string;
     productName?: string;
     limit?: number;
+    page?: number;
     skip?: number;
     sort?: string;
 }
+/**
+ * Status of a consolidated transfer
+ * - completed: Both exit and entry legs exist
+ * - pending: Only exit leg exists (transfer in transit)
+ */
+export type ConsolidatedTransferStatus = 'completed' | 'pending';
 /**
  * Single item within a consolidated transfer
  */
@@ -349,26 +385,128 @@ export interface ConsolidatedTransferItem {
  *
  * @example
  * Original in QVET:
- *   ID 3206: MONTEJO → COLABORADOR-URBAN (exit)
- *   ID 3207: COLABORADOR-URBAN → URBAN CENTER (entry)
+ *   Exit:  ID 3206 @ 14:42 - MONTEJO → COLABORADOR-URBAN
+ *   Entry: ID 3207 @ 15:01 - COLABORADOR-URBAN → URBAN CENTER
  *
  * Consolidated:
+ *   exitDate: "2025-01-23T14:42:00.000Z"
+ *   entryDate: "2025-01-23T15:01:00.000Z"
  *   realSource: "MONTEJO"
  *   realTarget: "URBAN CENTER"
- *   transferIds: [3206, 3207]
+ *   status: "completed"
+ *   exitTransferIds: [3206]
+ *   entryTransferIds: [3207]
+ *
+ * If only exit exists (pending):
+ *   entryDate: null
+ *   realTarget: null
+ *   status: "pending"
+ *   entryTransferIds: []
  */
 export interface ConsolidatedTransfer {
-    date: string;
+    /** When items left the source warehouse */
+    exitDate: string;
+    /** When items arrived at destination (null if pending) */
+    entryDate: string | null;
+    /** Real source warehouse (not COLABORADOR) */
     realSource: string;
-    realTarget: string;
+    /** Real target warehouse (null if pending/unknown) */
+    realTarget: string | null;
+    /** Transfer status */
+    status: ConsolidatedTransferStatus;
+    /** Notes/observations from the transfer (combined from all items) */
+    notes: string;
+    /** Items in this transfer */
     items: ConsolidatedTransferItem[];
+    /** Number of distinct items */
     totalItems: number;
+    /** Sum of all quantities */
     totalQuantity: number;
+    /** Sum of all item values */
     totalValue: number;
-    transferIds: number[];
+    /** QVET transfer IDs for exit leg */
+    exitTransferIds: number[];
+    /** QVET transfer IDs for entry leg */
+    entryTransferIds: number[];
 }
 /**
- * Paginated list of consolidated transfers
- * Uses generic QvetPaginatedResponse for consistent pagination format.
+ * @deprecated Use ApiListSuccessResponse<ConsolidatedTransfer[]> instead.
  */
 export type ConsolidatedTransfersResponse = QvetPaginatedResponse<ConsolidatedTransfer>;
+/**
+ * Single collection (cobro) record from QVET
+ * Represents a payment transaction - used for reception bonus calculations
+ *
+ * Field presence analysis (9787 rows from 2025):
+ * - 100%: amount, type, branch
+ * - 99%+: collectorName, cashRegister, paymentMethod
+ * - 96%: date, time, company
+ * - 87-92%: customerName, saleDate, sellerName, deliveryNoteNumber, invoice info
+ * - 40%: state, city, postalCode
+ */
+export interface QvetCollectionResponse {
+    id: string;
+    amount: number;
+    type: string;
+    branch: string;
+    collectorName?: string;
+    cashRegister?: string;
+    paymentMethod?: string;
+    date?: string;
+    time?: string;
+    company?: string;
+    customerName?: string;
+    saleDate?: string;
+    sellerName?: string;
+    deliveryNoteNumber?: number;
+    invoiceDate?: string;
+    invoiceNumber?: string;
+    state?: string;
+    city?: string;
+    postalCode?: string;
+    address?: string;
+    syncedAt: string;
+}
+/**
+ * Collections summary statistics data.
+ * Backend wraps with: ApiSingleSuccessResponse<QvetCollectionsSummaryData>
+ */
+export interface QvetCollectionsSummaryData {
+    totalRecords: number;
+    totalAmount: number;
+    avgAmount: number;
+}
+/**
+ * Collections grouped by collector - for reception bonus calculations.
+ * Backend returns: ApiSingleSuccessResponse<QvetCollectionsByCollectorItem[]>
+ */
+export interface QvetCollectionsByCollectorItem {
+    collectorName: string;
+    totalAmount: number;
+    recordCount: number;
+    branches: string[];
+}
+/**
+ * Collections grouped by payment method.
+ * Backend returns: ApiSingleSuccessResponse<QvetCollectionsByPaymentMethodItem[]>
+ */
+export interface QvetCollectionsByPaymentMethodItem {
+    paymentMethod: string;
+    totalAmount: number;
+    recordCount: number;
+}
+/**
+ * Query parameters for collections endpoint
+ */
+export interface QvetCollectionsQueryParams {
+    year?: number;
+    month?: number;
+    halfMonth?: 1 | 2;
+    branch?: string;
+    collectorName?: string;
+    paymentMethod?: string;
+    type?: string;
+    limit?: number;
+    page?: number;
+    skip?: number;
+}

package/dist/contracts/qvet/responses.js

@@ -2,7 +2,26 @@
 /**
  * QVET API Response Types
  *
- * Response interfaces for QVET data endpoints.
- * Used by frontend to consume synced QVET data.
+ * Item types and data payloads for QVET endpoints.
+ *
+ * ## Response Pattern
+ *
+ * Backend uses standard ApiResponse types from hvp-shared:
+ * - Lists: `ApiListSuccessResponse<QvetSaleResponse[]>` with meta/links
+ * - Single: `ApiSingleSuccessResponse<QvetSalesSummaryData>`
+ * - Arrays (no pagination): `ApiSingleSuccessResponse<QvetSalesBySectionItem[]>`
+ *
+ * Frontend receives standard format:
+ * ```json
+ * {
+ *   "ok": true,
+ *   "status_code": 200,
+ *   "resource": "qvet-sales",
+ *   "operation": "all",
+ *   "data": [...],
+ *   "meta": { "total": 100, "page": 1, "limit": 25, "totalPages": 4, "itemsOnPage": 25 },
+ *   "links": { "current": "...", "next": "...", ... }
+ * }
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hvp-shared",
-  "version": "6.11.0",
+  "version": "6.13.0",
   "description": "Shared types and utilities for HVP backend and frontend",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",