hvp-shared 14.5.0 → 14.6.0

package/dist/constants/index.d.ts

@@ -25,6 +25,7 @@ export * from './hris.constants';
 export * from './payroll-features.constants';
 export * from './inventory-session.enums';
 export * from './shift-checklist.enums';
+export * from './supplier-payments.enums';
 export * from './documentation.enums';
 export * from './document.enums';
 export * from './settlement.enums';

package/dist/constants/index.js

@@ -41,6 +41,7 @@ __exportStar(require("./hris.constants"), exports);
 __exportStar(require("./payroll-features.constants"), exports);
 __exportStar(require("./inventory-session.enums"), exports);
 __exportStar(require("./shift-checklist.enums"), exports);
+__exportStar(require("./supplier-payments.enums"), exports);
 __exportStar(require("./documentation.enums"), exports);
 __exportStar(require("./document.enums"), exports);
 __exportStar(require("./settlement.enums"), exports);

package/dist/constants/supplier-payments.enums.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Supplier Payments Enums ("Próximos pagos a proveedores")
+ *
+ * Unifies the payment obligations a payer must settle each period across several
+ * sources: QVET credit invoices (vencimientos), recurring monthly obligations,
+ * and sporadic ad-hoc payments — plus generic per-supplier discount rules.
+ *
+ * See design doc: resources/research/20260701-supplier-payments-platform.md
+ */
+/**
+ * Where a payment obligation comes from.
+ *
+ * - `qvet_credit` (Crédito QVET): a supplier invoice paid by transfer that has a
+ *   vencimiento (due date) in QVET report 718.
+ * - `recurring`   (Recurrente): a known monthly obligation not in QVET
+ *   (Petco, QVET, Medam, SAT, IMSS, Anilab, Yi Health, Península).
+ * - `adhoc`       (Esporádico): a one-off payment captured manually.
+ */
+export declare enum PaymentType {
+    qvet_credit = "qvet_credit",
+    recurring = "recurring",
+    adhoc = "adhoc"
+}
+export declare const PAYMENT_TYPE_LABELS: Record<PaymentType, string>;
+/**
+ * Settlement status of a single payment obligation.
+ *
+ * - `pending`   (Pendiente): not yet paid.
+ * - `paid`      (Pagado): settled.
+ * - `scheduled` (Programado): planned for a future pay day but not yet paid.
+ * - `cancelled` (Cancelado): no longer owed.
+ */
+export declare enum PaymentStatus {
+    pending = "pending",
+    paid = "paid",
+    scheduled = "scheduled",
+    cancelled = "cancelled"
+}
+export declare const PAYMENT_STATUS_LABELS: Record<PaymentStatus, string>;
+/**
+ * Whether a recurring payment has a fixed amount or a variable one entered each month.
+ */
+export declare enum RecurringAmountType {
+    fixed = "fixed",
+    variable = "variable"
+}
+export declare const RECURRING_AMOUNT_TYPE_LABELS: Record<RecurringAmountType, string>;
+/**
+ * Kind of per-supplier discount arrangement.
+ *
+ * - `percentage` (Porcentaje): e.g. Telvet 5%.
+ * - `fixed`      (Monto fijo): a flat discount amount.
+ */
+export declare enum DiscountRuleType {
+    percentage = "percentage",
+    fixed = "fixed"
+}
+export declare const DISCOUNT_RULE_TYPE_LABELS: Record<DiscountRuleType, string>;
+/**
+ * What base a discount rule applies to.
+ *
+ * - `period_total` (Total del periodo): applied over the SUM of the supplier's
+ *   invoices for the period (how Telvet 5% works today).
+ */
+export declare enum DiscountAppliesTo {
+    period_total = "period_total"
+}
+export declare const DISCOUNT_APPLIES_TO_LABELS: Record<DiscountAppliesTo, string>;
+/** Default pay day (day of month) when a payment doesn't specify one. */
+export declare const DEFAULT_PAY_DAY = 1;

package/dist/constants/supplier-payments.enums.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Supplier Payments Enums ("Próximos pagos a proveedores")
+ *
+ * Unifies the payment obligations a payer must settle each period across several
+ * sources: QVET credit invoices (vencimientos), recurring monthly obligations,
+ * and sporadic ad-hoc payments — plus generic per-supplier discount rules.
+ *
+ * See design doc: resources/research/20260701-supplier-payments-platform.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PAY_DAY = exports.DISCOUNT_APPLIES_TO_LABELS = exports.DiscountAppliesTo = exports.DISCOUNT_RULE_TYPE_LABELS = exports.DiscountRuleType = exports.RECURRING_AMOUNT_TYPE_LABELS = exports.RecurringAmountType = exports.PAYMENT_STATUS_LABELS = exports.PaymentStatus = exports.PAYMENT_TYPE_LABELS = exports.PaymentType = void 0;
+// --- Payment type (the source of the obligation) ---
+/**
+ * Where a payment obligation comes from.
+ *
+ * - `qvet_credit` (Crédito QVET): a supplier invoice paid by transfer that has a
+ *   vencimiento (due date) in QVET report 718.
+ * - `recurring`   (Recurrente): a known monthly obligation not in QVET
+ *   (Petco, QVET, Medam, SAT, IMSS, Anilab, Yi Health, Península).
+ * - `adhoc`       (Esporádico): a one-off payment captured manually.
+ */
+var PaymentType;
+(function (PaymentType) {
+    PaymentType["qvet_credit"] = "qvet_credit";
+    PaymentType["recurring"] = "recurring";
+    PaymentType["adhoc"] = "adhoc";
+})(PaymentType || (exports.PaymentType = PaymentType = {}));
+exports.PAYMENT_TYPE_LABELS = {
+    [PaymentType.qvet_credit]: "Crédito QVET",
+    [PaymentType.recurring]: "Recurrente",
+    [PaymentType.adhoc]: "Esporádico",
+};
+// --- Payment status ---
+/**
+ * Settlement status of a single payment obligation.
+ *
+ * - `pending`   (Pendiente): not yet paid.
+ * - `paid`      (Pagado): settled.
+ * - `scheduled` (Programado): planned for a future pay day but not yet paid.
+ * - `cancelled` (Cancelado): no longer owed.
+ */
+var PaymentStatus;
+(function (PaymentStatus) {
+    PaymentStatus["pending"] = "pending";
+    PaymentStatus["paid"] = "paid";
+    PaymentStatus["scheduled"] = "scheduled";
+    PaymentStatus["cancelled"] = "cancelled";
+})(PaymentStatus || (exports.PaymentStatus = PaymentStatus = {}));
+exports.PAYMENT_STATUS_LABELS = {
+    [PaymentStatus.pending]: "Pendiente",
+    [PaymentStatus.paid]: "Pagado",
+    [PaymentStatus.scheduled]: "Programado",
+    [PaymentStatus.cancelled]: "Cancelado",
+};
+// --- Recurring amount kind ---
+/**
+ * Whether a recurring payment has a fixed amount or a variable one entered each month.
+ */
+var RecurringAmountType;
+(function (RecurringAmountType) {
+    RecurringAmountType["fixed"] = "fixed";
+    RecurringAmountType["variable"] = "variable";
+})(RecurringAmountType || (exports.RecurringAmountType = RecurringAmountType = {}));
+exports.RECURRING_AMOUNT_TYPE_LABELS = {
+    [RecurringAmountType.fixed]: "Fijo",
+    [RecurringAmountType.variable]: "Variable",
+};
+// --- Discount rule ---
+/**
+ * Kind of per-supplier discount arrangement.
+ *
+ * - `percentage` (Porcentaje): e.g. Telvet 5%.
+ * - `fixed`      (Monto fijo): a flat discount amount.
+ */
+var DiscountRuleType;
+(function (DiscountRuleType) {
+    DiscountRuleType["percentage"] = "percentage";
+    DiscountRuleType["fixed"] = "fixed";
+})(DiscountRuleType || (exports.DiscountRuleType = DiscountRuleType = {}));
+exports.DISCOUNT_RULE_TYPE_LABELS = {
+    [DiscountRuleType.percentage]: "Porcentaje",
+    [DiscountRuleType.fixed]: "Monto fijo",
+};
+/**
+ * What base a discount rule applies to.
+ *
+ * - `period_total` (Total del periodo): applied over the SUM of the supplier's
+ *   invoices for the period (how Telvet 5% works today).
+ */
+var DiscountAppliesTo;
+(function (DiscountAppliesTo) {
+    DiscountAppliesTo["period_total"] = "period_total";
+})(DiscountAppliesTo || (exports.DiscountAppliesTo = DiscountAppliesTo = {}));
+exports.DISCOUNT_APPLIES_TO_LABELS = {
+    [DiscountAppliesTo.period_total]: "Total del periodo",
+};
+/** Default pay day (day of month) when a payment doesn't specify one. */
+exports.DEFAULT_PAY_DAY = 1;

package/dist/contracts/index.d.ts

@@ -25,4 +25,5 @@ export * from './external-study';
 export * from './pending-dashboard';
 export * from './document';
 export * from './supplier-orders';
+export * from './supplier-payments';
 export * from './commission-reconciliation';

package/dist/contracts/index.js

@@ -41,4 +41,5 @@ __exportStar(require("./external-study"), exports);
 __exportStar(require("./pending-dashboard"), exports);
 __exportStar(require("./document"), exports);
 __exportStar(require("./supplier-orders"), exports);
+__exportStar(require("./supplier-payments"), exports);
 __exportStar(require("./commission-reconciliation"), exports);

package/dist/contracts/supplier-payments/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Supplier Payments API Contracts ("Próximos pagos a proveedores")
+ */
+export * from "./types";
+export * from "./requests";
+export * from "./responses";

package/dist/contracts/supplier-payments/index.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Supplier Payments API Contracts ("Próximos pagos a proveedores")
+ */
+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("./types"), exports);
+__exportStar(require("./requests"), exports);
+__exportStar(require("./responses"), exports);

package/dist/contracts/supplier-payments/requests.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Supplier Payments — request contracts
+ */
+import { DiscountAppliesTo, DiscountRuleType, PaymentStatus, PaymentType, RecurringAmountType } from "../../constants/supplier-payments.enums";
+/**
+ * Query params for the unified payments list / summary.
+ * @example GET /api/supplier-payments?year=2026&month=6&status=pending
+ */
+export interface SupplierPaymentsQueryParams {
+    year?: number;
+    month?: number;
+    /** Alternative to year/month: explicit ISO range. */
+    fromDate?: string;
+    toDate?: string;
+    supplier?: string;
+    status?: PaymentStatus;
+    type?: PaymentType;
+    /** Include per-item detail inside each supplier summary. */
+    includeItems?: boolean;
+}
+/**
+ * Mark a payment paid/pending (writes the HVP overlay; never touches QVET).
+ * @example PATCH /api/supplier-payments/:id/status
+ */
+export interface MarkPaymentStatusRequest {
+    status: PaymentStatus;
+    /** ISO timestamp; defaults to now when marking paid. */
+    paidAt?: string;
+    paymentMethod?: string;
+    notes?: string;
+}
+export interface CreateRecurringPaymentRequest {
+    supplier: string;
+    concept: string;
+    amountType: RecurringAmountType;
+    /** Required when amountType = fixed. */
+    amount?: number;
+    /** Day of month to pay (default 1). */
+    payDay?: number;
+    isActive?: boolean;
+}
+export type UpdateRecurringPaymentRequest = Partial<CreateRecurringPaymentRequest>;
+export interface CreateAdhocPaymentRequest {
+    supplier: string;
+    concept: string;
+    amount: number;
+    /** ISO date it's due / to be paid. */
+    dueDate?: string;
+    payDay?: number;
+    status?: PaymentStatus;
+    notes?: string;
+}
+export type UpdateAdhocPaymentRequest = Partial<CreateAdhocPaymentRequest>;
+export interface CreateSupplierDiscountRuleRequest {
+    supplier: string;
+    type: DiscountRuleType;
+    /** Percentage (e.g. 5 for 5%) or fixed amount, per `type`. */
+    value: number;
+    appliesTo?: DiscountAppliesTo;
+    isActive?: boolean;
+}
+export type UpdateSupplierDiscountRuleRequest = Partial<CreateSupplierDiscountRuleRequest>;

package/dist/contracts/supplier-payments/requests.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Supplier Payments — request contracts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/supplier-payments/responses.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Supplier Payments — response contracts
+ */
+import { DiscountAppliesTo, DiscountRuleType, PaymentStatus, RecurringAmountType } from "../../constants/supplier-payments.enums";
+import { SupplierPaymentSummary } from "./types";
+/**
+ * The main "próximos pagos" response: per-supplier totals + grand totals.
+ * @example GET /api/supplier-payments/summary
+ */
+export interface SupplierPaymentsSummaryResponse {
+    bySupplier: SupplierPaymentSummary[];
+    /** Grand totals across all suppliers. */
+    grossTotal: number;
+    discountTotal: number;
+    netTotal: number;
+    pendingTotal: number;
+    paidTotal: number;
+    supplierCount: number;
+}
+/** A configured recurring monthly payment (HVP-owned). */
+export interface RecurringPaymentResponse {
+    id: string;
+    supplier: string;
+    concept: string;
+    amountType: RecurringAmountType;
+    amount?: number;
+    payDay: number;
+    isActive: boolean;
+    createdAt: string;
+    updatedAt: string;
+    createdBy?: string;
+    updatedBy?: string;
+}
+/** A sporadic one-off payment (HVP-owned). */
+export interface AdhocPaymentResponse {
+    id: string;
+    supplier: string;
+    concept: string;
+    amount: number;
+    dueDate?: string;
+    payDay?: number;
+    status: PaymentStatus;
+    paidAt?: string;
+    paidById?: string;
+    notes?: string;
+    createdAt: string;
+    updatedAt: string;
+    createdBy?: string;
+    updatedBy?: string;
+}
+/** A per-supplier discount rule (HVP-owned). */
+export interface SupplierDiscountRuleResponse {
+    id: string;
+    supplier: string;
+    type: DiscountRuleType;
+    value: number;
+    appliesTo: DiscountAppliesTo;
+    isActive: boolean;
+    createdAt: string;
+    updatedAt: string;
+    createdBy?: string;
+    updatedBy?: string;
+}

package/dist/contracts/supplier-payments/responses.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Supplier Payments — response contracts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/supplier-payments/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Supplier Payments — shared types
+ *
+ * The unified line item and per-supplier summary the "próximos pagos" view is built on.
+ */
+import { PaymentStatus, PaymentType } from "../../constants/supplier-payments.enums";
+/**
+ * A single payment obligation, unified across sources (QVET credit / recurring / ad-hoc).
+ *
+ * Amounts are already net of nothing here — the discount is applied at the summary level
+ * (over the supplier's period total), see `SupplierPaymentSummary`.
+ */
+export interface SupplierPaymentItem {
+    /** Stable id. For QVET credit this is derived from the invoice; for others it's the record id. */
+    id: string;
+    type: PaymentType;
+    supplier: string;
+    /** Free-text concept (e.g. "Renta Petco", "IMSS junio"). Optional for QVET invoices. */
+    concept?: string;
+    amount: number;
+    /** ISO date the payment is due (QVET dueDate, or recurring/ad-hoc target). */
+    dueDate?: string;
+    /** Target day of month to pay (default 1; Petco 16). */
+    payDay?: number;
+    status: PaymentStatus;
+    /** ISO timestamp when it was marked paid. */
+    paidAt?: string;
+    /** Collaborator id who marked it paid. */
+    paidById?: string;
+    paymentMethod?: string;
+    /** True when the status came from the automatic premarca (QVET), not a user action. */
+    isPremarked?: boolean;
+    /** QVET credit: the invoice this payment settles (grouped by qvetInvoiceId). */
+    qvetInvoiceId?: number;
+    invoiceNumber?: string;
+    ownNumber?: string;
+    /** Recurring: the recurring-payment config id. */
+    recurringPaymentId?: string;
+    /** Ad-hoc: the ad-hoc payment id. */
+    adhocPaymentId?: string;
+    notes?: string;
+}
+/**
+ * Per-supplier rollup: "cuánto pagar a este proveedor" for the period.
+ *
+ * `netTotal` is what to actually pay: `grossTotal - discountTotal`.
+ */
+export interface SupplierPaymentSummary {
+    supplier: string;
+    itemCount: number;
+    grossTotal: number;
+    /** Discount applied over the period total (e.g. Telvet 5%); 0 when no rule. */
+    discountTotal: number;
+    /** grossTotal - discountTotal — the amount to pay. */
+    netTotal: number;
+    pendingTotal: number;
+    paidTotal: number;
+    /** Present when the caller requests item-level detail. */
+    items?: SupplierPaymentItem[];
+}

package/dist/contracts/supplier-payments/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Supplier Payments — shared types
+ *
+ * The unified line item and per-supplier summary the "próximos pagos" view is built on.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

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