platform-types 1.10.832 → 1.10.833

package/dist/cjs/refundObligation.js

@@ -3,14 +3,17 @@
  * 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
+ * An obligation is created inside the transaction of whatever made the money owed —
+ * a purchase withdrawal's hand-off (`awaiting-goods`, at a provisional amount), a
+ * `Return` paid by `provider` (which opens it, or re-amounts the hand-off's), 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. 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 one ledger write is the in-transit debit of a linked payment's credit
+ * ({@link RefundObligationLedgerCredit}), written by the `Return` that settles the
+ * obligation's parent (a `provider` one, or any withdrawal-bound one) — the only writer —
+ * for every obligation of that parent that carries one, closed included.
  *
  * ⚠️ The stored row carries none of the main table's index-key attributes
  * (`status`, `customerId`, `dated`, `updatedAt`, `terminalId`, `inboxKey`), so it
@@ -55,6 +58,9 @@ exports.REFUND_OBLIGATION_HOLD_REASONS = ['dispute-open', 'reimbursed'];
  * - `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).
+ * - `account-credit` — settled by the `Return`'s `DEVOLUCION` account credit: an `offline` obligation of a seña
+ *   order's withdrawal, closed in that `Return`'s own transaction (the delivery netted the seña out of its
+ *   debit, so the credit IS the seña's refund). No drawer event, no `ACCOUNT#` row of its own.
  */
 exports.REFUND_OBLIGATION_CLOSED_BY = [
     'detected-refund',
@@ -62,6 +68,7 @@ exports.REFUND_OBLIGATION_CLOSED_BY = [
     'operator',
     'chargeback',
     'api-refund',
+    'account-credit',
 ];
 /** Where a {@link StatutoryInstant} came from: the platform global it was computed with. */
 exports.REFUND_OBLIGATION_DUE_SOURCE = 'global:refundObligationDueDays';

package/dist/refundObligation.d.ts

@@ -2,14 +2,17 @@
  * 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
+ * An obligation is created inside the transaction of whatever made the money owed —
+ * a purchase withdrawal's hand-off (`awaiting-goods`, at a provisional amount), a
+ * `Return` paid by `provider` (which opens it, or re-amounts the hand-off's), 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. 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 one ledger write is the in-transit debit of a linked payment's credit
+ * ({@link RefundObligationLedgerCredit}), written by the `Return` that settles the
+ * obligation's parent (a `provider` one, or any withdrawal-bound one) — the only writer —
+ * for every obligation of that parent that carries one, closed included.
  *
  * ⚠️ The stored row carries none of the main table's index-key attributes
  * (`status`, `customerId`, `dated`, `updatedAt`, `terminalId`, `inboxKey`), so it
@@ -52,8 +55,11 @@ export declare const REFUND_OBLIGATION_HOLD_REASONS: readonly ["dispute-open", "
  * - `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).
+ * - `account-credit` — settled by the `Return`'s `DEVOLUCION` account credit: an `offline` obligation of a seña
+ *   order's withdrawal, closed in that `Return`'s own transaction (the delivery netted the seña out of its
+ *   debit, so the credit IS the seña's refund). No drawer event, no `ACCOUNT#` row of its own.
  */
-export declare const REFUND_OBLIGATION_CLOSED_BY: readonly ["detected-refund", "resolution-refunded", "operator", "chargeback", "api-refund"];
+export declare const REFUND_OBLIGATION_CLOSED_BY: readonly ["detected-refund", "resolution-refunded", "operator", "chargeback", "api-refund", "account-credit"];
 /** 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. */
@@ -81,8 +87,8 @@ declare global {
     }
     /**
      * 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.
+     * still holds it as a credit, so the `Return` that settles the obligation's parent debits the share being
+     * refunded ("in transit") in its own transaction, one `ACCOUNT#` row per obligation (`RIT#{obligationId}`).
      */
     interface RefundObligationLedgerCredit {
         /** The `ACCOUNT#{storeId}` credit row's SK — the per-source payment row's `accountId`. */
@@ -115,6 +121,12 @@ declare global {
         actor?: string;
         /** The operator's own words, for `operator`. */
         reason?: string;
+        /**
+         * For `operator`: the money went back from the operator's till (`payout: 'drawer'`) in the closure's own
+         * transaction. A seña's `Return` excludes that amount from its `DEVOLUCION` credit. Absent on a closure that
+         * recorded no payout, and on one written before the payout was recorded on the closure.
+         */
+        payout?: (typeof REFUND_OBLIGATION_PAYOUTS)[number];
         /** For `detected-refund`: the ids of the payment's `refunds[]` dated at or after `createdAt`. */
         providerRefundIds?: string[];
     }
@@ -122,7 +134,10 @@ declare global {
         /** The row's sort key: `{orderId}#{parentId}#{kind}#{paymentId | 'till'}`. */
         obligationId: string;
         orderId: string;
-        /** The withdrawal or RMA that made the money owed. */
+        /**
+         * What made the money owed: the purchase withdrawal (`ARR…`) — the hand-off's and its `Return`'s — else the
+         * RMA (`RMA…`) a `provider` `Return` settles, else that `Return` itself (`RET…`).
+         */
         parentId: string;
         kind: RefundObligationKind;
         /** The Mercado Pago payment the money came in on. Absent for `offline`. */

package/dist/refundObligation.js

@@ -2,14 +2,17 @@
  * 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
+ * An obligation is created inside the transaction of whatever made the money owed —
+ * a purchase withdrawal's hand-off (`awaiting-goods`, at a provisional amount), a
+ * `Return` paid by `provider` (which opens it, or re-amounts the hand-off's), 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. 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 one ledger write is the in-transit debit of a linked payment's credit
+ * ({@link RefundObligationLedgerCredit}), written by the `Return` that settles the
+ * obligation's parent (a `provider` one, or any withdrawal-bound one) — the only writer —
+ * for every obligation of that parent that carries one, closed included.
  *
  * ⚠️ The stored row carries none of the main table's index-key attributes
  * (`status`, `customerId`, `dated`, `updatedAt`, `terminalId`, `inboxKey`), so it
@@ -52,6 +55,9 @@ export const REFUND_OBLIGATION_HOLD_REASONS = ['dispute-open', 'reimbursed'];
  * - `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).
+ * - `account-credit` — settled by the `Return`'s `DEVOLUCION` account credit: an `offline` obligation of a seña
+ *   order's withdrawal, closed in that `Return`'s own transaction (the delivery netted the seña out of its
+ *   debit, so the credit IS the seña's refund). No drawer event, no `ACCOUNT#` row of its own.
  */
 export const REFUND_OBLIGATION_CLOSED_BY = [
     'detected-refund',
@@ -59,6 +65,7 @@ export const REFUND_OBLIGATION_CLOSED_BY = [
     'operator',
     'chargeback',
     'api-refund',
+    'account-credit',
 ];
 /** Where a {@link StatutoryInstant} came from: the platform global it was computed with. */
 export const REFUND_OBLIGATION_DUE_SOURCE = 'global:refundObligationDueDays';

package/dist/return.d.ts

@@ -98,8 +98,28 @@ declare global {
     interface ReturnLedgerBasisUnavailableData {
         flow: ReturnFlow;
     }
-    /** Where a customer return's value is paid. Omission on a request or legacy row means account. */
-    type ReturnRefundMethod = 'account' | 'cash';
+    /**
+     * Where a customer return's value is paid. Omission on a request or legacy row means account.
+     *
+     * - `account` — a `DEVOLUCION` credit on the customer's account.
+     * - `cash` — paid out of the till.
+     * - `provider` — the money goes back through the payments it came in on: the same `DEVOLUCION` credit as
+     *   `account`, plus one refund obligation per payment bucket (`RefundObligation`, parent the withdrawal the
+     *   return settles, else its RMA, else the return itself), opened at the amount the server re-derives. An
+     *   `applyCredit`-linked payment's link credit is debited in transit (`RIT#{obligationId}`) in the same
+     *   transaction, so the account credit is never spendable — as on any withdrawal-bound return, whatever its
+     *   method, for every obligation of the withdrawal carrying one. Needs no `acknowledgeNoProviderRefund`.
+     */
+    type ReturnRefundMethod = 'account' | 'cash' | 'provider';
+    /**
+     * `data` of `409 RETURN_WITHDRAWAL_HOLDS_LINE`: a return with no `rmaId` named a quantity a live purchase
+     * withdrawal holds — its `requested`/`accepted` lines, or the approved lines of its open
+     * `purchase-withdrawal` RMA (`rmaId`). Settle that withdrawal through its own RMA instead.
+     */
+    interface ReturnWithdrawalHoldsLineData {
+        withdrawalId: string;
+        rmaId?: string;
+    }
     /** Return planning refusals: invalid selected lines, too many return summaries, or more than 100 transaction items. */
     type ReturnPlanFailureCode = 'RETURN_INVALID_SUBSET' | 'RETURN_LIMIT_REACHED' | 'RETURN_TRANSACTION_TOO_LARGE' | 'UNIT_QUANTITY_NOT_WHOLE' | 'UNIT_QUANTITY_UNREPRESENTABLE';
     /**
@@ -275,6 +295,11 @@ declare global {
          * nothing backfills it and no reader derives it from `reason`.
          */
         flow?: ReturnFlow;
+        /**
+         * The RMA this return settled (`CreateReturnRequest.rmaId`), moved `received → settled` in the return's own
+         * transaction. Operator-only. Absent on a return that bound none, and on every return written before it existed.
+         */
+        rmaId?: string;
         notes?: string;
         userId: string;
         /**
@@ -722,6 +747,8 @@ declare global {
          * stripped from every customer surface. Absent on legacy summaries.
          */
         flow?: ReturnFlow;
+        /** Mirrors `Return.rmaId`. Operator-only: stripped from every customer surface. */
+        rmaId?: string;
         ncStatus?: ReturnCreditNoteStatus;
         creditNoteId?: string;
         /**
@@ -843,8 +870,37 @@ declare global {
      */
     interface CreateReturnRequest {
         mode: 'return';
-        /** Omission credits the customer account. Cash pays the full server-calculated return total; no provider refund. A walk-in order (the system customer) is always refunded in cash, whatever is sent, but only up to what the order was paid; the unpaid rest lowers what the order still owes. */
+        /**
+         * Omission credits the customer account. Cash pays the full server-calculated return total; no provider
+         * refund. A walk-in order (the system customer) is always refunded in cash, whatever is sent, but only up to
+         * what the order was paid; the unpaid rest lowers what the order still owes.
+         *
+         * `provider` opens the refund obligations (see {@link ReturnRefundMethod}). A return bound to a
+         * purchase-withdrawal RMA defaults to `provider` while the re-derived amount owed is above 0, and any other
+         * method is then `409 RETURN_REFUND_METHOD_PROVIDER_REQUIRED`; with nothing owed (an unpaid order) it
+         * defaults to `account`. `provider` on an order with no linked payment, no approved attempt payment and no
+         * till leg is `409 RETURN_PROVIDER_NO_PAYMENT`; one whose payments owe nothing is
+         * `409 RETURN_PROVIDER_NOTHING_OWED`. A payment in a currency the order cannot convert at its frozen rate is
+         * `409 RETURN_PROVIDER_CURRENCY_MISMATCH`; a link credit the in-transit debit cannot vet is
+         * `409 RETURN_LEDGER_BASIS_UNAVAILABLE`; an obligation still owed that the re-derived amount gives nothing
+         * is `409 RETURN_OBLIGATION_RECONCILE_REQUIRED`. Each writes nothing and one ERROR row.
+         */
         refundMethod?: ReturnRefundMethod;
+        /**
+         * The RMA this return settles. Read strongly; it must be this order's and `received`, else `404
+         * RMA_NOT_FOUND`, `409 RETURN_RMA_ORDER_MISMATCH` or `409 RETURN_RMA_NOT_RECEIVED`. The return's lines must
+         * EQUAL a `purchase-withdrawal` RMA's approved lines (index and quantity), and stay within any other RMA's
+         * approved quantity on the lines it names, else `409 RETURN_RMA_LINES_MISMATCH`. The return then takes its
+         * flow from the RMA (`purchase-withdrawal` for that source, else `Rma.flow`, else the reason's), stores
+         * `rmaId`, and settles the RMA (`received → settled`, `settledReturnId`) in its own transaction; a
+         * withdrawal-bound return also moves the withdrawal (`refund-pending` while an obligation is owed, else
+         * `completed`).
+         *
+         * Absent: a return that names a quantity a live purchase withdrawal holds is
+         * `409 RETURN_WITHDRAWAL_HOLDS_LINE` (`ReturnWithdrawalHoldsLineData`); a truncated read of the order's open
+         * RMAs is `503 RETURN_REQUESTS_UNAVAILABLE`.
+         */
+        rmaId?: string;
         /** Client-minted UUID; the idempotency key. A replay returns the original outcome. */
         requestId: string;
         orderId: string;
@@ -889,9 +945,10 @@ declare global {
         emitCreditNote?: boolean;
         sendEmail?: boolean;
         /**
-         * Required when the order has a non-empty `linkedPayments` map: the
-         * operator acknowledges SINFACTURA does NOT refund or unlink the provider
-         * payment. The return pays by refundMethod (account by default; always cash on a walk-in order).
+         * Required when the order has a non-empty `linkedPayments` map and the
+         * return pays by `account` or `cash`: the operator acknowledges SINFACTURA
+         * does NOT refund or unlink the provider payment. `provider` needs none.
+         * The return pays by refundMethod (account by default; always cash on a walk-in order).
          */
         acknowledgeNoProviderRefund?: boolean;
         /**

package/dist/rma.d.ts

@@ -301,8 +301,9 @@ declare global {
             refundAs: ChangeOfMindRefundAs;
         };
         /**
-         * The refunds owed on this request, as on a withdrawal. No writer links a
-         * refund to a shopper request yet, so it is absent today.
+         * The refunds owed on this request, as on a withdrawal: one per refund
+         * obligation whose `parentId` is this RMA, which the `provider` `Return`
+         * settling it opens. Absent while there is none.
          */
         refunds?: OrderPurchaseWithdrawalRefundView[];
     }

package/package.json

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