platform-types 1.10.803 → 1.10.804

package/dist/account.d.ts

@@ -183,6 +183,11 @@ declare global {
          */
         paymentRefSource?: PaymentReceivedSource;
         paymentRefId?: string;
+        /**
+         * On a refund obligation's in-transit debit (SK `RIT#{obligationId}`, `paymentRef*` naming the linked
+         * payment): the obligation whose refund the debit books. Absent on every other row.
+         */
+        refundObligationId?: string;
     }
     /**
      * `POST /account` — a new customer-ledger movement. Mirrors the request side of

package/dist/audit.d.ts

@@ -164,6 +164,19 @@ declare global {
      * words stay on the attempt row.
      */
      | 'payment_attempt_resolved'
+    /**
+     * An operator closed one of the order's refund obligations (`POST /refund-obligations { mode: 'close' }`).
+     * `before`: `obligationId`, `state`, `holdReason?`. `after`: `obligationId`, `state` (`'closed'`), `by`
+     * (`'operator'`), `payout` (`'drawer'` | `'none'`) and the operator's reason as `'[present]'` |
+     * `'[absent]'` — presence only, the words stay on the obligation's `closure`.
+     */
+     | 'refund_obligation_closed'
+    /**
+     * An operator reopened one of the order's refund obligations held behind a `reimbursed` chargeback
+     * (`POST /refund-obligations { mode: 'reopen' }`). `before`: `obligationId`, `state` (`'held'`),
+     * `holdReason`. `after`: `obligationId`, `state`, `refundDueAt?` and the reason by presence only.
+     */
+     | 'refund_obligation_reopened'
     /** HISTORICAL: written only by the removed outbound MercadoPago refund; kept so old timeline rows still parse. */
      | 'payment_refunded'
     /** At least one till tender leg was appended (an absorbed replay writes none). */

package/dist/cjs/refundObligation.js

@@ -8,15 +8,16 @@
  * 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.
+ * reopens it. Closure moves no money and writes no ledger row: it records a fact.
+ * The one ledger write is the creator's in-transit debit of a linked payment's
+ * credit ({@link RefundObligationLedgerCredit}), at creation.
  *
  * ⚠️ 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;
+exports.REFUND_OBLIGATION_PAYOUTS = exports.REFUND_OBLIGATION_ACTION_MODES = exports.REFUND_OBLIGATION_LIST_FILTERS = exports.REFUND_OBLIGATION_REASON_MAX = 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).
@@ -40,7 +41,8 @@ exports.REFUND_OBLIGATION_STATES = ['awaiting-goods', 'open', 'overdue', 'held',
  * 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`.
+ * as `dispute-open`. Once the operator reopened a `reimbursed` hold
+ * (`reimbursedDecision`), that chargeback no longer holds the obligation.
  */
 exports.REFUND_OBLIGATION_HOLD_REASONS = ['dispute-open', 'reimbursed'];
 /**
@@ -63,3 +65,14 @@ exports.REFUND_OBLIGATION_CLOSED_BY = [
 ];
 /** Where a {@link StatutoryInstant} came from: the platform global it was computed with. */
 exports.REFUND_OBLIGATION_DUE_SOURCE = 'global:refundObligationDueDays';
+/** The longest operator `reason` `POST /refund-obligations` accepts, in characters after trimming. */
+exports.REFUND_OBLIGATION_REASON_MAX = 500;
+/**
+ * The `state` filter of `GET /refund-obligations`: one {@link RefundObligationState}, or `pending` — every
+ * state but `closed`, the operator's working queue.
+ */
+exports.REFUND_OBLIGATION_LIST_FILTERS = [...exports.REFUND_OBLIGATION_STATES, 'pending'];
+/** The modes of `POST /refund-obligations`. */
+exports.REFUND_OBLIGATION_ACTION_MODES = ['close', 'reopen'];
+/** The one payout `POST /refund-obligations { mode: 'close' }` can record: cash from the operator's till. */
+exports.REFUND_OBLIGATION_PAYOUTS = ['drawer'];

package/dist/refundObligation.d.ts

@@ -7,8 +7,9 @@
  * 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.
+ * reopens it. Closure moves no money and writes no ledger row: it records a fact.
+ * The one ledger write is the creator's in-transit debit of a linked payment's
+ * credit ({@link RefundObligationLedgerCredit}), at creation.
  *
  * ⚠️ The stored row carries none of the main table's index-key attributes
  * (`status`, `customerId`, `dated`, `updatedAt`, `terminalId`, `inboxKey`), so it
@@ -37,7 +38,8 @@ export declare const REFUND_OBLIGATION_STATES: readonly ["awaiting-goods", "open
  * 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`.
+ * as `dispute-open`. Once the operator reopened a `reimbursed` hold
+ * (`reimbursedDecision`), that chargeback no longer holds the obligation.
  */
 export declare const REFUND_OBLIGATION_HOLD_REASONS: readonly ["dispute-open", "reimbursed"];
 /**
@@ -54,6 +56,17 @@ export declare const REFUND_OBLIGATION_HOLD_REASONS: readonly ["dispute-open", "
 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";
+/** The longest operator `reason` `POST /refund-obligations` accepts, in characters after trimming. */
+export declare const REFUND_OBLIGATION_REASON_MAX = 500;
+/**
+ * The `state` filter of `GET /refund-obligations`: one {@link RefundObligationState}, or `pending` — every
+ * state but `closed`, the operator's working queue.
+ */
+export declare const REFUND_OBLIGATION_LIST_FILTERS: readonly ["awaiting-goods", "open", "overdue", "held", "closed", "pending"];
+/** The modes of `POST /refund-obligations`. */
+export declare const REFUND_OBLIGATION_ACTION_MODES: readonly ["close", "reopen"];
+/** The one payout `POST /refund-obligations { mode: 'close' }` can record: cash from the operator's till. */
+export declare const REFUND_OBLIGATION_PAYOUTS: readonly ["drawer"];
 declare global {
     type RefundObligationKind = (typeof REFUND_OBLIGATION_KINDS)[number];
     type RefundObligationState = (typeof REFUND_OBLIGATION_STATES)[number];
@@ -66,12 +79,32 @@ declare global {
         /** 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. */
+    /**
+     * The payment-link credit an obligation's money was booked to, when there is one: the customer's ledger
+     * still holds it as a credit, so the creator debits the share being refunded ("in transit") in its own
+     * transaction, one `ACCOUNT#` row per obligation.
+     */
     interface RefundObligationLedgerCredit {
-        /** The `ACCOUNT#{storeId}` row's SK. */
+        /** The `ACCOUNT#{storeId}` credit row's SK — the per-source payment row's `accountId`. */
         accountId: string;
         /** The customer whose balance the credit moved. */
         customerId: string;
+        /** The partition of the payment the credit came from. */
+        source: PaymentReceivedSource;
+        /** The payment the credit came from: the per-source row's SK. */
+        paymentId: string;
+    }
+    /**
+     * The operator's decision that a `reimbursed` chargeback does not discharge the obligation (`POST
+     * /refund-obligations { mode: 'reopen' }`). While it stands, the payment's `reimbursed` chargeback no
+     * longer holds the obligation; a later hold (a new dispute) removes it.
+     */
+    interface RefundObligationReimbursedDecision {
+        by: 'operator';
+        /** Unix ms. */
+        at: number;
+        /** The store user who decided. */
+        actor?: string;
     }
     /** How an obligation was closed. */
     interface RefundObligationClosure {
@@ -111,6 +144,8 @@ declare global {
         holdReason?: RefundObligationHoldReason;
         /** The state a hold came from; a reopen returns to it (`overdue` returns to `open`). */
         heldFrom?: Exclude<RefundObligationState, 'held' | 'closed'>;
+        /** Set by the operator's reopen of a `reimbursed` hold; removed by any later hold. */
+        reimbursedDecision?: RefundObligationReimbursedDecision;
         /** 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. */
@@ -123,5 +158,75 @@ declare global {
         /** Unix ms of the last move. */
         revisedAt: number;
     }
+    type RefundObligationListFilter = (typeof REFUND_OBLIGATION_LIST_FILTERS)[number];
+    /**
+     * The query of `GET /refund-obligations` (App host, `staffToken`, the `payments` capability). Reads the
+     * token's store only, in obligation-id order (`orderId` first).
+     */
+    interface RefundObligationListQuery {
+        state?: RefundObligationListFilter;
+        /** Only this order's obligations (`ORD` plus 6–10 digits). */
+        orderId?: string;
+        /** Rows EVALUATED per page, 1–100 (default 25): a page can be short or empty with `nextCursor` present. */
+        limit?: number;
+        /** The previous page's `nextCursor`, bound to the store and to `state` + `orderId`. */
+        cursor?: string;
+    }
+    /**
+     * `data` of `GET /refund-obligations`. Page on `nextCursor`'s presence, never on the page's length. A
+     * `held` row always carries `holdReason` (a stored row with none reads as `dispute-open`): an open dispute
+     * offers no action; a `reimbursed` one awaits the operator's close or reopen.
+     */
+    interface RefundObligationListResponse {
+        obligations: RefundObligation[];
+        /** Opaque. Absent on the last page. */
+        nextCursor?: string;
+    }
+    /**
+     * `POST /refund-obligations` (App host, `adminToken`, the `payments` capability). Strict body.
+     *
+     * - `close` — the operator settled it: `closure.by: 'operator'`. From `open`, `overdue`, `awaiting-goods`
+     *   or a `reimbursed` hold; never from a `dispute-open` hold. `reason` is required for an `offline` one
+     *   and stored on `closure`. `payout: 'drawer'` (an `offline` one only) records the cash leaving the
+     *   operator's till as one drawer `refund` event in the same transaction.
+     * - `reopen` — a `reimbursed` hold the operator decides is still owed: back to the state it was held
+     *   from, with a fresh `refundDueAt` when that is `open`, and `reimbursedDecision` recorded so the same
+     *   `reimbursed` chargeback never holds it again.
+     *
+     * `expectedRevision` is the `revision` of the row the operator acted on.
+     */
+    type RefundObligationActionRequest = {
+        mode: 'close';
+        /** The obligation's `obligationId`: `{orderId}#{parentId}#{kind}#{paymentId | 'till'}`, else 400. */
+        obligationId: string;
+        expectedRevision: number;
+        /** 1–{@link REFUND_OBLIGATION_REASON_MAX} characters after trimming. Required for `offline`. */
+        reason?: string;
+        payout?: (typeof REFUND_OBLIGATION_PAYOUTS)[number];
+    } | {
+        mode: 'reopen';
+        /** The obligation's `obligationId`: `{orderId}#{parentId}#{kind}#{paymentId | 'till'}`, else 400. */
+        obligationId: string;
+        expectedRevision: number;
+        /** 1–{@link REFUND_OBLIGATION_REASON_MAX} characters after trimming. Recorded by presence only. */
+        reason?: string;
+    };
+    /** `data` of a successful `POST /refund-obligations`: the obligation as it now stands. */
+    interface RefundObligationActionResponse {
+        obligation: RefundObligation;
+    }
+    /** `data` of `409 REFUND_OBLIGATION_CHANGED`: the obligation as it now stands — review it and resend. */
+    interface RefundObligationChangedData {
+        obligation: RefundObligation;
+    }
+    /**
+     * `data` of `409 REFUND_OBLIGATION_NOT_ACTIONABLE`: the state that refuses the mode — `closed` (with its
+     * `closure`, so a replay after success reads what it did), or `held` with its `holdReason`.
+     */
+    interface RefundObligationNotActionableData {
+        state: RefundObligationState;
+        holdReason?: RefundObligationHoldReason;
+        closure?: RefundObligationClosure;
+    }
 }
 export {};

package/dist/refundObligation.js

@@ -7,8 +7,9 @@
  * 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.
+ * reopens it. Closure moves no money and writes no ledger row: it records a fact.
+ * The one ledger write is the creator's in-transit debit of a linked payment's
+ * credit ({@link RefundObligationLedgerCredit}), at creation.
  *
  * ⚠️ The stored row carries none of the main table's index-key attributes
  * (`status`, `customerId`, `dated`, `updatedAt`, `terminalId`, `inboxKey`), so it
@@ -37,7 +38,8 @@ export const REFUND_OBLIGATION_STATES = ['awaiting-goods', 'open', 'overdue', 'h
  * 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`.
+ * as `dispute-open`. Once the operator reopened a `reimbursed` hold
+ * (`reimbursedDecision`), that chargeback no longer holds the obligation.
  */
 export const REFUND_OBLIGATION_HOLD_REASONS = ['dispute-open', 'reimbursed'];
 /**
@@ -60,3 +62,14 @@ export const REFUND_OBLIGATION_CLOSED_BY = [
 ];
 /** Where a {@link StatutoryInstant} came from: the platform global it was computed with. */
 export const REFUND_OBLIGATION_DUE_SOURCE = 'global:refundObligationDueDays';
+/** The longest operator `reason` `POST /refund-obligations` accepts, in characters after trimming. */
+export const REFUND_OBLIGATION_REASON_MAX = 500;
+/**
+ * The `state` filter of `GET /refund-obligations`: one {@link RefundObligationState}, or `pending` — every
+ * state but `closed`, the operator's working queue.
+ */
+export const REFUND_OBLIGATION_LIST_FILTERS = [...REFUND_OBLIGATION_STATES, 'pending'];
+/** The modes of `POST /refund-obligations`. */
+export const REFUND_OBLIGATION_ACTION_MODES = ['close', 'reopen'];
+/** The one payout `POST /refund-obligations { mode: 'close' }` can record: cash from the operator's till. */
+export const REFUND_OBLIGATION_PAYOUTS = ['drawer'];

package/package.json

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