hvp-shared 6.38.0 → 6.40.0

package/dist/contracts/cash-reconciliation/index.d.ts

@@ -0,0 +1,2 @@
+export * from './requests';
+export * from './responses';

package/dist/contracts/cash-reconciliation/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./requests"), exports);
+__exportStar(require("./responses"), exports);

package/dist/contracts/cash-reconciliation/requests.d.ts

@@ -0,0 +1,38 @@
+import { ReconciliationStatus } from '../../types/cash-reconciliation.types';
+/**
+ * One-shot reconciliation request.
+ * Creates a fully closed reconciliation linked to a QVET closing.
+ *
+ * @example POST /api/cash-reconciliations/reconcile
+ */
+export interface ReconcileRequest {
+    branchId: string;
+    closingNumber: number;
+    reportedCashInDrawer: number;
+    cardTerminalTotal?: number;
+    observations?: string;
+}
+/**
+ * Admin update request.
+ * Recalculates derived fields (cashDifference, warnings, etc.) on save.
+ *
+ * @example PATCH /api/cash-reconciliations/:id
+ */
+export interface AdminUpdateReconciliationRequest {
+    reportedCashInDrawer?: number;
+    cardTerminalTotal?: number | null;
+    observations?: string;
+}
+/**
+ * Query parameters for listing reconciliations.
+ *
+ * @example GET /api/cash-reconciliations?branchId=xxx&status=closed&startDate=2026-01-01&endDate=2026-01-31
+ */
+export interface CashReconciliationQueryParams {
+    branchId?: string;
+    status?: ReconciliationStatus;
+    startDate?: string;
+    endDate?: string;
+    limit?: number;
+    page?: number;
+}

package/dist/contracts/cash-reconciliation/requests.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/cash-reconciliation/responses.d.ts

@@ -0,0 +1,104 @@
+import { CashReconciliationWarning, QvetPaymentBreakdown, ReconciliationStatus } from '../../types/cash-reconciliation.types';
+/**
+ * QVET closing data grouped in the reconciliation response.
+ * Null when no QVET closing is linked (e.g. zero-closings, orphans).
+ */
+export interface QvetClosingData {
+    closingNumber: number;
+    closingDate: string | null;
+    staffName: string | null;
+    payments: QvetPaymentBreakdown | null;
+    closingTotal: number | null;
+    collectedAmount: number | null;
+    dayCollections: number | null;
+    cashOut: number | null;
+    cardTotal: number | null;
+}
+/**
+ * Full reconciliation record returned by the API.
+ *
+ * Used for: detail dialog, history table rows, admin edit.
+ *
+ * @example GET /api/cash-reconciliations/:id
+ * @example GET /api/cash-reconciliations (list — array of these)
+ */
+export interface CashReconciliationResponse {
+    id: string;
+    branchId: string;
+    branchName: string;
+    status: ReconciliationStatus;
+    baseCashAmount: number;
+    cashInDrawerStart: number;
+    expectedCashInDrawer: number;
+    reportedCashInDrawer: number | null;
+    cashDifference: number | null;
+    qvet: QvetClosingData | null;
+    cashTransferAmount: number | null;
+    closingCash: number | null;
+    cardTerminalTotal: number | null;
+    cardTerminalPriorAmount: number | null;
+    cardDiscrepancy: number | null;
+    observations: string;
+    warnings: CashReconciliationWarning[];
+    hasWarnings: boolean;
+    collaborator: string | null;
+    collaboratorName: string;
+    createdBy: string | null;
+    createdByName: string;
+    updatedBy: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+}
+/**
+ * Pre-closing cash calculation for a branch.
+ *
+ * @example GET /api/cash-reconciliations/expected-cash/:branchId
+ */
+export interface ExpectedCashResponse {
+    branchId: string;
+    branchName: string;
+    baseCashAmount: number;
+    cashInDrawerStart: number;
+    cashPaymentsSinceLastClosing: number;
+    expectedCashInDrawer: number;
+    lastClosedAt: string | null;
+}
+/**
+ * Dashboard status card for a single branch.
+ *
+ * @example GET /api/cash-reconciliations/branch-status
+ */
+export interface BranchReconciliationStatusResponse {
+    branchId: string;
+    branchName: string;
+    baseCashAmount: number;
+    activeReconciliation: {
+        id: string;
+        status: ReconciliationStatus;
+        expectedCash: number;
+        reportedCashInDrawer: number | null;
+        cashDifference: number | null;
+        createdAt: string | null;
+    } | null;
+    lastClosed: {
+        id: string;
+        closingCash: number | null;
+        closedAt: string | null;
+        qvetClosingNumber: number | null;
+        hasWarnings: boolean;
+    } | null;
+}
+/**
+ * QVET closing not yet linked to a reconciliation.
+ *
+ * @example GET /api/cash-reconciliations/unlinked-closings/:branchId
+ */
+export interface UnlinkedClosingResponse {
+    closingNumber: number;
+    closingDate: string;
+    previousClosingDate: string;
+    cashRegister: string;
+    staffName: string;
+    closingTotal: number;
+    payments: QvetPaymentBreakdown;
+}

package/dist/contracts/cash-reconciliation/responses.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/index.d.ts

@@ -7,3 +7,4 @@ export * from './catalog-item';
 export * from './order-planning';
 export * from './qvet';
 export * from './stock-calculation';
+export * from './cash-reconciliation';

package/dist/contracts/index.js

@@ -23,3 +23,4 @@ __exportStar(require("./catalog-item"), exports);
 __exportStar(require("./order-planning"), exports);
 __exportStar(require("./qvet"), exports);
 __exportStar(require("./stock-calculation"), exports);
+__exportStar(require("./cash-reconciliation"), exports);

package/dist/types/cash-reconciliation.types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Cash Reconciliation Types
+ *
+ * Shared types for the cash reconciliation system that verifies
+ * QVET cash closings against actual cash and card terminal totals.
+ */
+export type ReconciliationStatus = 'open' | 'pending-sync' | 'pending-cards' | 'closed';
+export type ReconciliationWarningSeverity = 'info' | 'warning' | 'error';
+/**
+ * Warning codes emitted by the reconciliation service.
+ *
+ * - CASH_MISMATCH: reported cash differs from expected (> $1 tolerance)
+ * - STAFF_MISMATCH: reconciler differs from QVET cashier
+ * - STALE_CLOSING: QVET closing is older than 30 minutes
+ * - MISSING_CARD_VERIFICATION: QVET has card payments but no terminal total entered
+ * - MIGRATED_NO_QVET: historical record migrated without a matching QVET closing
+ */
+export type ReconciliationWarningCode = 'CASH_MISMATCH' | 'STAFF_MISMATCH' | 'STALE_CLOSING' | 'MISSING_CARD_VERIFICATION' | 'MIGRATED_NO_QVET';
+export interface CashReconciliationWarning {
+    code: string;
+    severity: ReconciliationWarningSeverity;
+    message: string;
+}
+export interface QvetPaymentBreakdown {
+    cash: number;
+    debitCard: number;
+    creditCard: number;
+    amex: number;
+    transfer: number;
+    other: number;
+}
+/**
+ * Branch cash configuration for base cash amounts.
+ * Stored as a sub-document in the Branch model.
+ */
+export interface BranchCashConfig {
+    baseCashAmount: number;
+    updatedBy?: string;
+    updatedAt?: string;
+}

package/dist/types/cash-reconciliation.types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Cash Reconciliation Types
+ *
+ * Shared types for the cash reconciliation system that verifies
+ * QVET cash closings against actual cash and card terminal totals.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/index.d.ts

@@ -11,3 +11,4 @@ export * from './catalog-item.types';
 export * from './qvet.types';
 export * from './background-job.types';
 export * from './payroll-v2.types';
+export * from './cash-reconciliation.types';

package/dist/types/index.js

@@ -27,3 +27,4 @@ __exportStar(require("./catalog-item.types"), exports);
 __exportStar(require("./qvet.types"), exports);
 __exportStar(require("./background-job.types"), exports);
 __exportStar(require("./payroll-v2.types"), exports);
+__exportStar(require("./cash-reconciliation.types"), exports);

package/package.json

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