hvp-shared 6.39.0 → 6.41.0

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

@@ -1,48 +1,38 @@
+import { ReconciliationStatus } from '../../types/cash-reconciliation.types';
 /**
- * Create Cash Reconciliation Request
+ * One-shot reconciliation request.
+ * Creates a fully closed reconciliation linked to a QVET closing.
  *
- * Submitted when a user reconciles a QVET closing.
- * Most fields are auto-calculated; user provides actualCashInDrawer and optionally
- * cardTerminalTotal and observations.
- *
- * @example POST /api/cash-reconciliations
+ * @example POST /api/cash-reconciliations/reconcile
  */
-export interface CreateCashReconciliationRequest {
-    qvetClosingNumber: number;
-    actualCashInDrawer: number;
-    cardTerminalTotal?: number | null;
+export interface ReconcileRequest {
+    branchId: string;
+    closingNumber: number;
+    reportedCashInDrawer: number;
+    cardTerminalTotal?: number;
     observations?: string;
 }
 /**
- * Update Cash Reconciliation Request
- *
- * Only observations can be updated after creation.
+ * Admin update request.
+ * Recalculates derived fields (cashDifference, warnings, etc.) on save.
  *
  * @example PATCH /api/cash-reconciliations/:id
  */
-export interface UpdateCashReconciliationRequest {
-    observations?: string;
+export interface AdminUpdateReconciliationRequest {
+    reportedCashInDrawer?: number;
     cardTerminalTotal?: number | null;
+    observations?: string;
 }
 /**
  * Query parameters for listing reconciliations.
  *
- * @example GET /api/cash-reconciliations?branchId=xxx&status=discrepancy
+ * @example GET /api/cash-reconciliations?branchId=xxx&status=closed&startDate=2026-01-01&endDate=2026-01-31
  */
 export interface CashReconciliationQueryParams {
     branchId?: string;
-    status?: string;
+    status?: ReconciliationStatus;
     startDate?: string;
     endDate?: string;
-    closingNumber?: number;
     limit?: number;
     page?: number;
 }
-/**
- * Update branch cash config request.
- *
- * @example PATCH /api/branches/:id/cash-config
- */
-export interface UpdateBranchCashConfigRequest {
-    baseCashAmount: number;
-}

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

@@ -1,149 +1,104 @@
-import { CashReconciliationWarning, QvetPaymentBreakdown, ReconciliationStatus, BranchCashConfig } from '../../types/cash-reconciliation.types';
+import { CashReconciliationWarning, QvetPaymentBreakdown, ReconciliationStatus } from '../../types/cash-reconciliation.types';
 /**
- * Cash Reconciliation Response
- *
- * Full reconciliation record linking a QVET closing to verified cash/card amounts.
+ * 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: Reconciliation detail view, history table rows.
+ * 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;
-    qvetClosingNumber: number;
-    qvetClosingDate: string;
-    qvetPreviousClosingDate: string;
-    qvetCashRegister: string;
-    qvetStaffName: string;
-    qvetPayments: QvetPaymentBreakdown;
-    qvetClosingTotal: number;
-    qvetCollectedAmount: number;
-    qvetDayCollections: number;
-    qvetCashOut: number;
-    cashInFlows: number;
-    cashOutFlows: number;
+    status: ReconciliationStatus;
     baseCashAmount: number;
     cashInDrawerStart: number;
     expectedCashInDrawer: number;
-    actualCashInDrawer: number;
-    cashDiscrepancy: number;
-    cashTransferAmount: number;
-    closingCash: number;
+    reportedCashInDrawer: number | null;
+    cashDifference: number | null;
+    qvet: QvetClosingData | null;
+    cashTransferAmount: number | null;
+    closingCash: number | null;
     cardTerminalTotal: number | null;
-    qvetCardTotalThisClosing: number;
-    cardAmountVerifiedPrior: number;
-    cardExpectedForThisClosing: number;
+    cardTerminalPriorAmount: number | null;
     cardDiscrepancy: number | null;
-    status: ReconciliationStatus;
-    warnings: CashReconciliationWarning[];
     observations: string;
-    reconciledBy: string;
-    reconciledByName: string;
-    reconciledAt: string;
-    createdAt: string;
-    updatedAt: string;
+    warnings: CashReconciliationWarning[];
+    hasWarnings: boolean;
+    collaborator: string | null;
+    collaboratorName: string;
+    createdBy: string | null;
+    createdByName: string;
+    updatedBy: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
 }
 /**
- * Summary row for reconciliation list/history tables.
- *
- * Used for: History page table, branch reconciliation page.
+ * Pre-closing cash calculation for a branch.
  *
- * @example GET /api/cash-reconciliations
+ * @example GET /api/cash-reconciliations/expected-cash/:branchId
  */
-export interface CashReconciliationSummary {
-    id: string;
+export interface ExpectedCashResponse {
     branchId: string;
     branchName: string;
-    qvetClosingNumber: number;
-    qvetClosingDate: string;
-    qvetStaffName: string;
-    qvetClosingTotal: number;
-    actualCashInDrawer: number;
-    cashDiscrepancy: number;
-    cardDiscrepancy: number | null;
-    status: ReconciliationStatus;
-    warningCount: number;
-    reconciledByName: string;
-    reconciledAt: string;
-}
-/**
- * Pending QVET closing that hasn't been reconciled yet.
- *
- * Used for: Pending closings table on branch page.
- *
- * @example GET /api/cash-reconciliations/pending?branchId=xxx
- */
-export interface PendingClosingResponse {
-    closingNumber: number;
-    closingDate: string;
-    previousClosingDate: string;
-    cashRegister: string;
-    branch: string;
-    staffName: string;
-    closingTotal: number;
-    collectedAmount: number;
-    dayCollections: number;
-    cashOut: number;
-    payments: QvetPaymentBreakdown;
+    baseCashAmount: number;
+    cashInDrawerStart: number;
+    cashPaymentsSinceLastClosing: number;
+    expectedCashInDrawer: number;
+    lastClosedAt: string | null;
 }
 /**
- * Dashboard card data per branch.
- *
- * Used for: Dashboard branch status cards.
+ * Dashboard status card for a single branch.
  *
  * @example GET /api/cash-reconciliations/branch-status
  */
-export interface BranchReconciliationStatus {
+export interface BranchReconciliationStatusResponse {
     branchId: string;
     branchName: string;
-    pendingClosingsCount: number;
-    hasDiscrepancies: boolean;
-    lastReconciled: {
-        qvetClosingDate: string;
-        closingCash: number;
+    baseCashAmount: number;
+    activeReconciliation: {
+        id: string;
         status: ReconciliationStatus;
-        reconciledAt: string;
+        expectedCash: number;
+        reportedCashInDrawer: number | null;
+        cashDifference: number | null;
+        createdAt: string | null;
     } | null;
-    todayCardVerification: {
-        cardTerminalTotal: number | null;
-        totalQvetCards: number;
-        closingsReconciled: number;
-        totalClosingsToday: number;
-    };
-    cashConfig: BranchCashConfig;
-}
-/**
- * Daily card summary for a branch.
- *
- * Used for: Card terminal verification within reconciliation form.
- *
- * @example GET /api/cash-reconciliations/daily-summary/:branchId/:date
- */
-export interface DailyCardSummary {
-    branchId: string;
-    date: string;
-    cardTerminalTotal: number | null;
-    reconciliations: Array<{
+    lastClosed: {
         id: string;
-        qvetClosingNumber: number;
-        qvetCardTotalThisClosing: number;
-        reconciledAt: string;
-    }>;
-    totalQvetCardsReconciled: number;
-    totalQvetCardsToday: number;
-    cardDiscrepancy: number | null;
+        closingCash: number | null;
+        closedAt: string | null;
+        qvetClosingNumber: number | null;
+        hasWarnings: boolean;
+    } | null;
 }
 /**
- * Branch cash config response with branch info.
- *
- * Used for: Settings page, branch cash config listing.
+ * QVET closing not yet linked to a reconciliation.
  *
- * @example GET /api/branches/cash-config
+ * @example GET /api/cash-reconciliations/unlinked-closings/:branchId
  */
-export interface BranchCashConfigResponse {
-    branchId: string;
-    branchName: string;
-    cashConfig: BranchCashConfig;
+export interface UnlinkedClosingResponse {
+    closingNumber: number;
+    closingDate: string;
+    previousClosingDate: string;
+    cashRegister: string;
+    staffName: string;
+    closingTotal: number;
+    payments: QvetPaymentBreakdown;
 }

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

@@ -4,27 +4,21 @@
  * Shared types for the cash reconciliation system that verifies
  * QVET cash closings against actual cash and card terminal totals.
  */
-export declare enum ReconciliationStatus {
-    PENDING = "pending",
-    RECONCILED = "reconciled",
-    DISCREPANCY = "discrepancy"
-}
-export declare enum ReconciliationWarningCode {
-    CASH_MISMATCH = "CASH_MISMATCH",
-    CASH_MINOR_MISMATCH = "CASH_MINOR_MISMATCH",
-    CARD_MISMATCH = "CARD_MISMATCH",
-    WRONG_PERSON = "WRONG_PERSON",
-    LATE_RECONCILIATION = "LATE_RECONCILIATION",
-    MISSING_CARD_VERIFICATION = "MISSING_CARD_VERIFICATION",
-    PREVIOUS_UNRECONCILED = "PREVIOUS_UNRECONCILED"
-}
-export declare enum ReconciliationWarningSeverity {
-    INFO = "info",
-    WARNING = "warning",
-    ERROR = "error"
-}
+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
+ * - EXPIRED_UNRECONCILED: QVET closing was not reconciled within 24h and was auto-closed by the system
+ */
+export type ReconciliationWarningCode = 'CASH_MISMATCH' | 'STAFF_MISMATCH' | 'STALE_CLOSING' | 'MISSING_CARD_VERIFICATION' | 'MIGRATED_NO_QVET' | 'EXPIRED_UNRECONCILED';
 export interface CashReconciliationWarning {
-    code: ReconciliationWarningCode;
+    code: string;
     severity: ReconciliationWarningSeverity;
     message: string;
 }

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

@@ -6,29 +6,3 @@
  * QVET cash closings against actual cash and card terminal totals.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ReconciliationWarningSeverity = exports.ReconciliationWarningCode = exports.ReconciliationStatus = void 0;
-// ─────────────────────────────────────────────────────────────────────────────
-// Enums
-// ─────────────────────────────────────────────────────────────────────────────
-var ReconciliationStatus;
-(function (ReconciliationStatus) {
-    ReconciliationStatus["PENDING"] = "pending";
-    ReconciliationStatus["RECONCILED"] = "reconciled";
-    ReconciliationStatus["DISCREPANCY"] = "discrepancy";
-})(ReconciliationStatus || (exports.ReconciliationStatus = ReconciliationStatus = {}));
-var ReconciliationWarningCode;
-(function (ReconciliationWarningCode) {
-    ReconciliationWarningCode["CASH_MISMATCH"] = "CASH_MISMATCH";
-    ReconciliationWarningCode["CASH_MINOR_MISMATCH"] = "CASH_MINOR_MISMATCH";
-    ReconciliationWarningCode["CARD_MISMATCH"] = "CARD_MISMATCH";
-    ReconciliationWarningCode["WRONG_PERSON"] = "WRONG_PERSON";
-    ReconciliationWarningCode["LATE_RECONCILIATION"] = "LATE_RECONCILIATION";
-    ReconciliationWarningCode["MISSING_CARD_VERIFICATION"] = "MISSING_CARD_VERIFICATION";
-    ReconciliationWarningCode["PREVIOUS_UNRECONCILED"] = "PREVIOUS_UNRECONCILED";
-})(ReconciliationWarningCode || (exports.ReconciliationWarningCode = ReconciliationWarningCode = {}));
-var ReconciliationWarningSeverity;
-(function (ReconciliationWarningSeverity) {
-    ReconciliationWarningSeverity["INFO"] = "info";
-    ReconciliationWarningSeverity["WARNING"] = "warning";
-    ReconciliationWarningSeverity["ERROR"] = "error";
-})(ReconciliationWarningSeverity || (exports.ReconciliationWarningSeverity = ReconciliationWarningSeverity = {}));

package/package.json

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