platform-types 1.10.800 → 1.10.802

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/literals.d.ts

@@ -10,6 +10,13 @@ declare global {
     interface ResolvedStorefrontLiterals {
         values: Record<string, string>;
         provenance: Record<string, 'default' | 'GLOBAL' | 'WEB' | `WEB#${string}`>;
+        /**
+         * The compiled storefront default of each key, before any layer is applied: what a
+         * revert restores, and the text whose `{tokens}` an override must keep. No stored
+         * layer changes it. A key the catalog generator excludes has no entry, so a missing
+         * entry means "default unknown"; the six blanked payment keys are `''`.
+         */
+        defaults: Record<string, string>;
     }
     /**
      * One scope's literals, unmerged.

package/dist/platform.d.ts

@@ -227,9 +227,72 @@ export interface PlatformLiteralsBody extends PlatformOperatorReason {
     literals: Record<string, string | null>;
     /**
      * Must equal the store id inside a per-tenant scope; absent or wrong there is
-     * `400 CONFIRMATION_MISMATCH`. Ignored on a global scope, which names no tenant.
+     * `400 CONFIRMATION_MISMATCH`. Ignored on a global scope, which names no tenant,
+     * and ignored on a dry run.
      */
     confirm?: string;
+    /**
+     * `true` judges each key on its own and writes nothing: no row, no activity
+     * row, no audit row. The answer is `PlatformLiteralsDryRunResult`. A bad
+     * scope, an empty map or a bad reason is still a request-level 400. The
+     * legacy `WEB#` write conflicts happen only at commit and are not predicted.
+     */
+    dryRun?: boolean;
+}
+/** Why a dry run says one key would be refused. */
+export type PlatformLiteralDryRunError = 'RESERVED_KEY' | 'INVALID_KEY' | 'VALUE_TOO_LONG' | 'LITERAL_KEY_NOT_ALLOWED';
+/**
+ * One key of a dry run: what the write would do (`set` a new value, `remove` a
+ * stored one, or leave it `unchanged`), or the code that would refuse it.
+ */
+export type PlatformLiteralDryRunKeyResult = {
+    key: string;
+    verdict: 'set' | 'remove' | 'unchanged';
+} | {
+    key: string;
+    error: PlatformLiteralDryRunError;
+};
+/** `POST /platform/literals { dryRun: true }` → `200 { message, data }`, one result per body key. */
+export interface PlatformLiteralsDryRunResult {
+    results: PlatformLiteralDryRunKeyResult[];
+}
+/**
+ * One change on `GET /platform/literals/{scope}/{key}/history`. `before` and
+ * `after` are the stored values on each side of the change, `''` for a key the
+ * scope does not hold. `actorStoreId` is the acting manager's own store, since
+ * `actorId` is numbered per store. `actorName` is absent when the actor's
+ * activity row can no longer be read; `reason` is absent when none was sent.
+ */
+export interface PlatformLiteralHistoryEntry {
+    at: string;
+    actorId: string;
+    actorStoreId?: string;
+    actorName?: string;
+    before: string;
+    after: string;
+    reason?: string;
+}
+/** `GET /platform/literals/{scope}/{key}/history`: newest first; send `cursor` back as `?cursor=`. */
+export interface PlatformLiteralHistoryResponse {
+    data: PlatformLiteralHistoryEntry[];
+    cursor?: string;
+}
+/** One store's own value for a key, on its `APP#{storeId}` or `WEB#{storeId}` row. */
+export interface PlatformLiteralOverride {
+    storeId: string;
+    /** Absent when the store row has no name, or can no longer be read. */
+    storeName?: string;
+    scope: `APP#${string}` | `WEB#${string}`;
+    value: string;
+}
+/**
+ * `GET /platform/literals/overrides?key=K`. `truncated` is `true` when the read
+ * stopped at its bound before reaching every tenant row, so the list may be
+ * incomplete.
+ */
+export interface PlatformLiteralOverridesResponse {
+    data: PlatformLiteralOverride[];
+    truncated?: true;
 }
 /** `POST /platform/operations { mode: 'mp-recover-payment' }`. */
 /** Tracked non-money refresh returned inside the standard response data envelope. */

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/dist/userActivity.d.ts

@@ -1027,6 +1027,7 @@ declare global {
         key: string;
         before: string;
         after: string;
+        reason?: string;
     }
     interface SupportTicketCreatedEvent extends UserActivityEventBase {
         event: 'Support Ticket Created';

package/package.json

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