platform-types 1.10.800 → 1.10.801

package/dist/cjs/index.js

@@ -93,6 +93,7 @@ __exportStar(require("./productGroup.js"), exports);
 __exportStar(require("./purchaseOrder.js"), exports);
 __exportStar(require("./purchaseReceipt.js"), exports);
 __exportStar(require("./pushDevice.js"), exports);
+__exportStar(require("./refundObligation.js"), exports);
 __exportStar(require("./reminder.js"), exports);
 __exportStar(require("./report.js"), exports);
 __exportStar(require("./return.js"), exports);

package/dist/cjs/refundObligation.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Refund obligations — money the store owes a customer back, tracked until it is
+ * proven returned.
+ *
+ * An obligation is created inside the transaction of whatever made the money owed
+ * (a purchase withdrawal's cancellation, a return, a late capture on a withdrawn
+ * order) and closes on its own when Mercado Pago reports the refund, when an
+ * operator closes a payment attempt's resolution as `refunded`, or when a
+ * chargeback settled the money back. An open dispute holds it; a lifted dispute
+ * reopens it. Nothing here moves money or writes a ledger row: closure records a
+ * fact.
+ *
+ * ⚠️ The stored row carries none of the main table's index-key attributes
+ * (`status`, `customerId`, `dated`, `updatedAt`, `terminalId`, `inboxKey`), so it
+ * joins no GSI: `state` replaces `status`, `revisedAt` replaces `updatedAt`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REFUND_OBLIGATION_DUE_SOURCE = exports.REFUND_OBLIGATION_CLOSED_BY = exports.REFUND_OBLIGATION_HOLD_REASONS = exports.REFUND_OBLIGATION_STATES = exports.REFUND_OBLIGATION_KINDS = void 0;
+/**
+ * - `provider` — paid through Mercado Pago; closes when the provider reports the
+ *   refund (`paymentId` is set).
+ * - `offline` — paid by other means (cash, transfer); has no `paymentId` and
+ *   closes only by an operator.
+ * - `late-capture` — an approval that arrived after the order no longer wanted
+ *   it; closes when the provider reports the refund or when the attempt's
+ *   resolution is closed `refunded` after it was created — never because the
+ *   attempt reached `refunded`.
+ */
+exports.REFUND_OBLIGATION_KINDS = ['provider', 'offline', 'late-capture'];
+/**
+ * - `awaiting-goods` — owed once the goods are back; no due date yet.
+ * - `open` — owed, with a `refundDueAt`.
+ * - `overdue` — past `refundDueAt` and still owed.
+ * - `held` — a dispute on the payment holds it (`holdReason`); no due pointer.
+ * - `closed` — settled; `closure` says how. Terminal.
+ */
+exports.REFUND_OBLIGATION_STATES = ['awaiting-goods', 'open', 'overdue', 'held', 'closed'];
+/**
+ * Why an obligation is `held`. `dispute-open` reopens on its own once the
+ * dispute is lifted; `reimbursed` (Mercado Pago covered the seller) never does —
+ * only an operator's decision moves it. A stored row with no `holdReason` reads
+ * as `dispute-open`.
+ */
+exports.REFUND_OBLIGATION_HOLD_REASONS = ['dispute-open', 'reimbursed'];
+/**
+ * What closed an obligation.
+ *
+ * - `detected-refund` — Mercado Pago's cumulative refunded amount, net of what
+ *   was refunded before the obligation existed, covers it.
+ * - `resolution-refunded` — an operator closed the payment attempt's resolution
+ *   as `refunded` after the obligation was created.
+ * - `operator` — an operator closed it by hand.
+ * - `chargeback` — a settled chargeback took the money back.
+ * - `api-refund` — a refund the api itself made (reserved; no writer yet).
+ */
+exports.REFUND_OBLIGATION_CLOSED_BY = [
+    'detected-refund',
+    'resolution-refunded',
+    'operator',
+    'chargeback',
+    'api-refund',
+];
+/** Where a {@link StatutoryInstant} came from: the platform global it was computed with. */
+exports.REFUND_OBLIGATION_DUE_SOURCE = 'global:refundObligationDueDays';

package/dist/index.d.ts

@@ -69,6 +69,7 @@ export * from './productGroup.ts';
 export * from './purchaseOrder.ts';
 export * from './purchaseReceipt.ts';
 export * from './pushDevice.ts';
+export * from './refundObligation.ts';
 export * from './reminder.ts';
 export * from './report.ts';
 export * from './return.ts';

package/dist/index.js

@@ -77,6 +77,7 @@ export * from "./productGroup.js";
 export * from "./purchaseOrder.js";
 export * from "./purchaseReceipt.js";
 export * from "./pushDevice.js";
+export * from "./refundObligation.js";
 export * from "./reminder.js";
 export * from "./report.js";
 export * from "./return.js";

package/dist/refundObligation.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Refund obligations — money the store owes a customer back, tracked until it is
+ * proven returned.
+ *
+ * An obligation is created inside the transaction of whatever made the money owed
+ * (a purchase withdrawal's cancellation, a return, a late capture on a withdrawn
+ * order) and closes on its own when Mercado Pago reports the refund, when an
+ * operator closes a payment attempt's resolution as `refunded`, or when a
+ * chargeback settled the money back. An open dispute holds it; a lifted dispute
+ * reopens it. Nothing here moves money or writes a ledger row: closure records a
+ * fact.
+ *
+ * ⚠️ The stored row carries none of the main table's index-key attributes
+ * (`status`, `customerId`, `dated`, `updatedAt`, `terminalId`, `inboxKey`), so it
+ * joins no GSI: `state` replaces `status`, `revisedAt` replaces `updatedAt`.
+ */
+/**
+ * - `provider` — paid through Mercado Pago; closes when the provider reports the
+ *   refund (`paymentId` is set).
+ * - `offline` — paid by other means (cash, transfer); has no `paymentId` and
+ *   closes only by an operator.
+ * - `late-capture` — an approval that arrived after the order no longer wanted
+ *   it; closes when the provider reports the refund or when the attempt's
+ *   resolution is closed `refunded` after it was created — never because the
+ *   attempt reached `refunded`.
+ */
+export declare const REFUND_OBLIGATION_KINDS: readonly ["provider", "offline", "late-capture"];
+/**
+ * - `awaiting-goods` — owed once the goods are back; no due date yet.
+ * - `open` — owed, with a `refundDueAt`.
+ * - `overdue` — past `refundDueAt` and still owed.
+ * - `held` — a dispute on the payment holds it (`holdReason`); no due pointer.
+ * - `closed` — settled; `closure` says how. Terminal.
+ */
+export declare const REFUND_OBLIGATION_STATES: readonly ["awaiting-goods", "open", "overdue", "held", "closed"];
+/**
+ * Why an obligation is `held`. `dispute-open` reopens on its own once the
+ * dispute is lifted; `reimbursed` (Mercado Pago covered the seller) never does —
+ * only an operator's decision moves it. A stored row with no `holdReason` reads
+ * as `dispute-open`.
+ */
+export declare const REFUND_OBLIGATION_HOLD_REASONS: readonly ["dispute-open", "reimbursed"];
+/**
+ * What closed an obligation.
+ *
+ * - `detected-refund` — Mercado Pago's cumulative refunded amount, net of what
+ *   was refunded before the obligation existed, covers it.
+ * - `resolution-refunded` — an operator closed the payment attempt's resolution
+ *   as `refunded` after the obligation was created.
+ * - `operator` — an operator closed it by hand.
+ * - `chargeback` — a settled chargeback took the money back.
+ * - `api-refund` — a refund the api itself made (reserved; no writer yet).
+ */
+export declare const REFUND_OBLIGATION_CLOSED_BY: readonly ["detected-refund", "resolution-refunded", "operator", "chargeback", "api-refund"];
+/** Where a {@link StatutoryInstant} came from: the platform global it was computed with. */
+export declare const REFUND_OBLIGATION_DUE_SOURCE = "global:refundObligationDueDays";
+declare global {
+    type RefundObligationKind = (typeof REFUND_OBLIGATION_KINDS)[number];
+    type RefundObligationState = (typeof REFUND_OBLIGATION_STATES)[number];
+    type RefundObligationHoldReason = (typeof REFUND_OBLIGATION_HOLD_REASONS)[number];
+    type RefundObligationClosedBy = (typeof REFUND_OBLIGATION_CLOSED_BY)[number];
+    /** A deadline and the rule that set it. */
+    interface StatutoryInstant {
+        /** Unix ms. */
+        at: number;
+        /** The rule it was computed from, e.g. `global:refundObligationDueDays`. */
+        source: string;
+    }
+    /** The link credit an obligation's money was booked to, when there is one. */
+    interface RefundObligationLedgerCredit {
+        /** The `ACCOUNT#{storeId}` row's SK. */
+        accountId: string;
+        /** The customer whose balance the credit moved. */
+        customerId: string;
+    }
+    /** How an obligation was closed. */
+    interface RefundObligationClosure {
+        by: RefundObligationClosedBy;
+        /** Unix ms. */
+        at: number;
+        /** The store user who closed it, for `operator`. */
+        actor?: string;
+        /** The operator's own words, for `operator`. */
+        reason?: string;
+        /** For `detected-refund`: the ids of the payment's `refunds[]` dated at or after `createdAt`. */
+        providerRefundIds?: string[];
+    }
+    interface RefundObligation {
+        /** The row's sort key: `{orderId}#{parentId}#{kind}#{paymentId | 'till'}`. */
+        obligationId: string;
+        orderId: string;
+        /** The withdrawal or RMA that made the money owed. */
+        parentId: string;
+        kind: RefundObligationKind;
+        /** The Mercado Pago payment the money came in on. Absent for `offline`. */
+        paymentId?: string;
+        /** Decimal, in `currency`. */
+        amount: number;
+        /** The payment's own currency: creation refuses another one the payment's observation names. */
+        currency: string;
+        /** The payment's refunded amount when the obligation was created, so an earlier refund never closes it. */
+        refundedAtCreation?: number;
+        /**
+         * The payment had no observation when the obligation was created: its baseline
+         * is then the payment's `approved` refunds dated before `createdAt`.
+         */
+        observationAbsentAtCreation?: boolean;
+        ledgerCredit?: RefundObligationLedgerCredit;
+        state: RefundObligationState;
+        /** Set while `held`. */
+        holdReason?: RefundObligationHoldReason;
+        /** The state a hold came from; a reopen returns to it (`overdue` returns to `open`). */
+        heldFrom?: Exclude<RefundObligationState, 'held' | 'closed'>;
+        /** Bumped by every move, for a compare-and-set. */
+        revision: number;
+        /** When the refund is due. Set by the move to `open`; removed by a hold. */
+        refundDueAt?: StatutoryInstant;
+        /** The SK of the obligation's due pointer, while it has one. */
+        duePointerSK?: string;
+        closure?: RefundObligationClosure;
+        /** Unix ms. */
+        createdAt: number;
+        /** Unix ms of the last move. */
+        revisedAt: number;
+    }
+}
+export {};

package/dist/refundObligation.js

@@ -0,0 +1,62 @@
+/**
+ * Refund obligations — money the store owes a customer back, tracked until it is
+ * proven returned.
+ *
+ * An obligation is created inside the transaction of whatever made the money owed
+ * (a purchase withdrawal's cancellation, a return, a late capture on a withdrawn
+ * order) and closes on its own when Mercado Pago reports the refund, when an
+ * operator closes a payment attempt's resolution as `refunded`, or when a
+ * chargeback settled the money back. An open dispute holds it; a lifted dispute
+ * reopens it. Nothing here moves money or writes a ledger row: closure records a
+ * fact.
+ *
+ * ⚠️ The stored row carries none of the main table's index-key attributes
+ * (`status`, `customerId`, `dated`, `updatedAt`, `terminalId`, `inboxKey`), so it
+ * joins no GSI: `state` replaces `status`, `revisedAt` replaces `updatedAt`.
+ */
+/**
+ * - `provider` — paid through Mercado Pago; closes when the provider reports the
+ *   refund (`paymentId` is set).
+ * - `offline` — paid by other means (cash, transfer); has no `paymentId` and
+ *   closes only by an operator.
+ * - `late-capture` — an approval that arrived after the order no longer wanted
+ *   it; closes when the provider reports the refund or when the attempt's
+ *   resolution is closed `refunded` after it was created — never because the
+ *   attempt reached `refunded`.
+ */
+export const REFUND_OBLIGATION_KINDS = ['provider', 'offline', 'late-capture'];
+/**
+ * - `awaiting-goods` — owed once the goods are back; no due date yet.
+ * - `open` — owed, with a `refundDueAt`.
+ * - `overdue` — past `refundDueAt` and still owed.
+ * - `held` — a dispute on the payment holds it (`holdReason`); no due pointer.
+ * - `closed` — settled; `closure` says how. Terminal.
+ */
+export const REFUND_OBLIGATION_STATES = ['awaiting-goods', 'open', 'overdue', 'held', 'closed'];
+/**
+ * Why an obligation is `held`. `dispute-open` reopens on its own once the
+ * dispute is lifted; `reimbursed` (Mercado Pago covered the seller) never does —
+ * only an operator's decision moves it. A stored row with no `holdReason` reads
+ * as `dispute-open`.
+ */
+export const REFUND_OBLIGATION_HOLD_REASONS = ['dispute-open', 'reimbursed'];
+/**
+ * What closed an obligation.
+ *
+ * - `detected-refund` — Mercado Pago's cumulative refunded amount, net of what
+ *   was refunded before the obligation existed, covers it.
+ * - `resolution-refunded` — an operator closed the payment attempt's resolution
+ *   as `refunded` after the obligation was created.
+ * - `operator` — an operator closed it by hand.
+ * - `chargeback` — a settled chargeback took the money back.
+ * - `api-refund` — a refund the api itself made (reserved; no writer yet).
+ */
+export const REFUND_OBLIGATION_CLOSED_BY = [
+    'detected-refund',
+    'resolution-refunded',
+    'operator',
+    'chargeback',
+    'api-refund',
+];
+/** Where a {@link StatutoryInstant} came from: the platform global it was computed with. */
+export const REFUND_OBLIGATION_DUE_SOURCE = 'global:refundObligationDueDays';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "platform-types",
-	"version": "1.10.800",
+	"version": "1.10.801",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",