platform-types 1.10.827 → 1.10.829

package/dist/cjs/return.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RETURN_REASON_FLOWS = exports.RETURN_FLOWS = exports.RETURN_LINE_DISPOSITIONS = void 0;
+exports.RETURN_SERVER_CREDIT_NOTE_FLOWS = exports.RETURN_REASON_FLOWS = exports.RETURN_FLOWS = exports.RETURN_LINE_DISPOSITIONS = void 0;
 /**
  * Every state a returned line's physical disposition can be in, as a runtime
  * value so the api's Zod enum, the app's picker and the union below derive
@@ -33,3 +33,15 @@ exports.RETURN_REASON_FLOWS = {
     billing_error: 'administrative',
     other: 'administrative',
 };
+/**
+ * The flows in which the SERVER decides a return's credit note: every flow but
+ * `administrative`. Each of them is a refund of value, so on an order holding a
+ * live domestic factura with credit left to give the note is required — see
+ * {@link CreateReturnRequest.emitCreditNote}. `administrative` keeps the
+ * client's flag.
+ */
+exports.RETURN_SERVER_CREDIT_NOTE_FLOWS = [
+    'purchase-withdrawal',
+    'change-of-mind',
+    'warranty',
+];

package/dist/purchaseWithdrawal.d.ts

@@ -141,10 +141,23 @@ declare global {
      * How the identification code reached the shopper. `shownAt` is when the
      * `201` carried it on screen (the same medium as the request); the
      * `purchase-withdrawal-received` mail is queued after the commit and
-     * stamps `emailQueuedAt`, and the mail worker records `emailStatus`:
-     * `sent`, or `not-sent` when the order's customer has no address to mail
-     * or the send was refused for good (a suppressed address included), or
-     * when an operator decided the request before the mail went out.
+     * stamps `emailQueuedAt`, and the mail worker records `emailStatus: 'sent'`
+     * once the mail went out. `emailStatus: 'not-sent'` is written when:
+     *
+     * - the mail was never queued — platform email sending was off at the
+     *   request, or the queue write (or the `emailQueuedAt` stamp) failed. This
+     *   stamp never replaces a verdict the worker already recorded;
+     * - the worker found no address on the order's customer row;
+     * - the sender did not deliver it — an address suppressed after a bounce, a
+     *   demo store, or the sender refusing the message;
+     * - the send failed for good (a permanent rejection);
+     * - an operator decided the request before the mail went out.
+     *
+     * Each verdict the worker records reaches operator sockets as the record's
+     * frame. `emailQueuedAt` with no `emailStatus` is not proof of a mail in
+     * flight: some worker exits stamp nothing (a transient send failure whose
+     * retries run out, a batch dropped because platform email sending was
+     * switched off after the request).
      */
     interface PurchaseWithdrawalAcknowledgement {
         /** Unix ms. */

package/dist/return.d.ts

@@ -17,8 +17,87 @@ export declare const RETURN_FLOWS: readonly ["purchase-withdrawal", "change-of-m
 export declare const RETURN_REASON_FLOWS: {
     readonly [R in ReturnReason]: Exclude<ReturnFlow, 'purchase-withdrawal'>;
 };
+/**
+ * The flows in which the SERVER decides a return's credit note: every flow but
+ * `administrative`. Each of them is a refund of value, so on an order holding a
+ * live domestic factura with credit left to give the note is required — see
+ * {@link CreateReturnRequest.emitCreditNote}. `administrative` keeps the
+ * client's flag.
+ */
+export declare const RETURN_SERVER_CREDIT_NOTE_FLOWS: readonly ["purchase-withdrawal", "change-of-mind", "warranty"];
 declare global {
     type ReturnFlow = (typeof RETURN_FLOWS)[number];
+    /**
+     * Why `409 RETURN_FISCAL_IN_FLIGHT` asks the return to wait. No return was
+     * written (one answered at commit, when a factura took the fence after the
+     * read, has burned a return id); the same request (same `requestId`) may be
+     * resent. Checked on
+     * every server-decided flow (`RETURN_SERVER_CREDIT_NOTE_FLOWS`), whether or not
+     * the order holds a factura yet — the order's first factura is exactly the one
+     * still in flight.
+     *
+     * - `pending-cae` — a factura entry of the order has `fiscalStatus`
+     *   `pending_cae` (sent to ARCA, no CAE yet). Retry once the pending-invoice
+     *   drain settles it.
+     * - `in-progress` — a factura is being issued for this order right now (also
+     *   when one took the fence between the read and the commit). Retry once it
+     *   ends.
+     * - `uncertain` — an earlier factura issuance of this order was interrupted
+     *   and its outcome at ARCA is not confirmed. Retry only after support
+     *   reconciles it.
+     * - `stranded` — ARCA authorized a voucher for this order that could not be
+     *   recorded on it. Retry only after support records it.
+     */
+    type ReturnFiscalInFlightCause = 'pending-cae' | 'in-progress' | 'uncertain' | 'stranded';
+    /**
+     * Why `409 RETURN_CREDIT_NOTE_UNALLOCATABLE` cannot attach the required
+     * credit note to one factura. Nothing was written. An operator data problem,
+     * not retryable as it stands.
+     *
+     * - `multiple-facturas` — the order holds more than one live domestic factura
+     *   (credited or not). Product scope, not a data fault: the credit-note
+     *   pipeline cannot attribute a note to one of several facturas
+     *   (`NC_MULTI_FAC_UNSUPPORTED`), so the return is refused before it commits
+     *   rather than leaving a note that will be rejected.
+     * - `missing-invoice-id` — the order's factura entry names no `invoiceId`, so
+     *   its fiscal row cannot be read.
+     * - `unnumbered-factura` — a live factura entry carries no valid voucher
+     *   number (and is not `pending_cae`), or a live entry carries no
+     *   `invoiceType` at all and is counted as a factura, failing closed.
+     */
+    type ReturnCreditNoteUnallocatableCause = 'multiple-facturas' | 'missing-invoice-id' | 'unnumbered-factura';
+    /**
+     * `data` of `409 RETURN_CREDIT_NOTE_REQUIRED`: the request sent
+     * `emitCreditNote: false` for a return whose `flow` requires the credit note
+     * on this order. Nothing was written. Resend without the flag (or `true`).
+     */
+    interface ReturnCreditNoteRequiredData {
+        flow: ReturnFlow;
+    }
+    /** `data` of `409 RETURN_FISCAL_IN_FLIGHT` — see {@link ReturnFiscalInFlightCause}. */
+    interface ReturnFiscalInFlightData {
+        flow: ReturnFlow;
+        cause: ReturnFiscalInFlightCause;
+    }
+    /** `data` of `409 RETURN_CREDIT_NOTE_UNALLOCATABLE` — see {@link ReturnCreditNoteUnallocatableCause}. */
+    interface ReturnCreditNoteUnallocatableData {
+        flow: ReturnFlow;
+        cause: ReturnCreditNoteUnallocatableCause;
+    }
+    /**
+     * `data` of `409 RETURN_LEDGER_BASIS_UNAVAILABLE` when the SERVER required the
+     * credit note: the factura's fiscal row cannot carry it — the row is missing
+     * or has no lines, a returned line does not map to a billed one, an earlier
+     * return cannot be read, or the voucher's currency or IVA is not allocatable.
+     * Nothing was written. An operator data problem, not retryable as it stands.
+     * Ranked after `RETURN_CREDIT_NOTE_UNALLOCATABLE` and before
+     * `RETURN_CREDIT_NOTE_REQUIRED`. The same code's other uses (an
+     * `administrative` return that asked for the note, a moved ledger basis at
+     * commit) carry no `data`.
+     */
+    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';
     /** Return planning refusals: invalid selected lines, too many return summaries, or more than 100 transaction items. */
@@ -186,6 +265,16 @@ declare global {
          */
         owedReduction?: number;
         reason: ReturnReason;
+        /**
+         * The legal track this return followed, derived by the server when it is
+         * committed: `RETURN_REASON_FLOWS[reason]`. It decides the credit note (see
+         * {@link CreateReturnRequest.emitCreditNote}). Never client-settable.
+         * Operator-only.
+         *
+         * ⚠️ OPTIONAL PERMANENTLY. Absent on every return written before it existed;
+         * nothing backfills it and no reader derives it from `reason`.
+         */
+        flow?: ReturnFlow;
         notes?: string;
         userId: string;
         /**
@@ -412,8 +501,9 @@ declare global {
      */
     type ReturnDirection = 'customer' | 'supplier';
     /**
-     * Credit-note state machine for a return: `not_requested` (no NC asked
-     * for), `pending` (outcome not yet settled — an attempt is in flight, or its
+     * Credit-note state machine for a return: `not_requested` (no NC issued:
+     * none asked for on an `administrative` return, or none owed on a
+     * server-decided flow — no live domestic factura with credit left), `pending` (outcome not yet settled — an attempt is in flight, or its
      * outcome is unknown: a submit whose answer never came back, or a
      * `pending_cae` voucher), `authorized` (ARCA granted; `creditNoteId`
      * stamped), `rejected` (refused; retryable via return-credit-note mode
@@ -627,6 +717,11 @@ declare global {
         /** Mirrors Return.owedReduction: the unpaid part of a walk-in return, which lowered what the order owes. */
         owedReduction?: number;
         reason: ReturnReason;
+        /**
+         * Mirrors `Return.flow`, written in the same transaction. Operator-only:
+         * stripped from every customer surface. Absent on legacy summaries.
+         */
+        flow?: ReturnFlow;
         ncStatus?: ReturnCreditNoteStatus;
         creditNoteId?: string;
         /**
@@ -758,6 +853,39 @@ declare global {
         items: CreateReturnRequestItem[];
         reason: ReturnReason;
         notes?: string;
+        /**
+         * Whether the return issues a credit note. Who decides depends on the
+         * return's flow (`RETURN_REASON_FLOWS[reason]`):
+         *
+         * - `administrative`: this flag, omission meaning `false`.
+         * - `warranty`, `change-of-mind`, `purchase-withdrawal`
+         *   (`RETURN_SERVER_CREDIT_NOTE_FLOWS`): the server. When the order holds a
+         *   live domestic factura (`pending_cae` included, or a live entry with no
+         *   `invoiceType`) that still has credit left to give, the note is REQUIRED
+         *   and issued whether or not this flag is sent. Otherwise no note is
+         *   issued, whatever it says — a factura already credited in full owes
+         *   none. An order whose only live factura is an export or FCE one also
+         *   commits with no note, and files one `RETURN_CREDIT_NOTE_MANUAL`
+         *   operator row: that credit note must be issued by hand. Each refusal
+         *   below writes nothing:
+         *   1. `409 RETURN_FISCAL_IN_FLIGHT` (`ReturnFiscalInFlightData`) while a
+         *      factura is `pending_cae`, being issued, uncertain or stranded —
+         *      checked on every server-decided flow, factura or not;
+         *   2. `409 RETURN_CREDIT_NOTE_UNALLOCATABLE`
+         *      (`ReturnCreditNoteUnallocatableData`) when the note cannot be
+         *      attached to exactly one factura;
+         *   3. `409 RETURN_LEDGER_BASIS_UNAVAILABLE`
+         *      (`ReturnLedgerBasisUnavailableData`) when that factura's fiscal row
+         *      cannot carry it;
+         *   4. `409 RETURN_CREDIT_NOTE_REQUIRED` (`ReturnCreditNoteRequiredData`)
+         *      when this flag is an explicit `false`.
+         *
+         *   On these flows the commit also asserts that no factura was appended and
+         *   no factura issuance took the fence since the read: a factura landing in
+         *   between answers `409 ORDER_VERSION_CONFLICT`, a fence taken in between
+         *   `409 RETURN_FISCAL_IN_FLIGHT` (`in-progress` unless the re-read says
+         *   otherwise).
+         */
         emitCreditNote?: boolean;
         sendEmail?: boolean;
         /**

package/dist/return.js

@@ -30,3 +30,15 @@ export const RETURN_REASON_FLOWS = {
     billing_error: 'administrative',
     other: 'administrative',
 };
+/**
+ * The flows in which the SERVER decides a return's credit note: every flow but
+ * `administrative`. Each of them is a refund of value, so on an order holding a
+ * live domestic factura with credit left to give the note is required — see
+ * {@link CreateReturnRequest.emitCreditNote}. `administrative` keeps the
+ * client's flag.
+ */
+export const RETURN_SERVER_CREDIT_NOTE_FLOWS = [
+    'purchase-withdrawal',
+    'change-of-mind',
+    'warranty',
+];

package/dist/rma.d.ts

@@ -229,11 +229,17 @@ declare global {
     type ShopperReturnRequestFlow = Extract<ReturnFlow, 'warranty' | 'change-of-mind'>;
     /**
      * A shopper return request's acknowledgement — the purchase withdrawal's
-     * shape: `shownAt` (the `201` showed the request number), `emailQueuedAt`
-     * (the `return-request-received` mail was queued) and `emailStatus` (`sent`,
-     * or `not-sent` when the customer has no address, the send was refused for
-     * good, or an operator decided the request before the mail went out). The operator reads an undelivered acknowledgement off it; the
-     * shopper's view never carries it.
+     * shape and rules ({@link PurchaseWithdrawalAcknowledgement}): `shownAt` (the
+     * `201` showed the request number), `emailQueuedAt` (the
+     * `return-request-received` mail was queued) and `emailStatus` — `sent`, or
+     * `not-sent` when the mail was never queued (platform email sending off, or
+     * the queue write or its stamp failing — never over a verdict the worker
+     * already recorded), the customer row has no address, the sender did not
+     * deliver it (an address suppressed after a bounce, a demo store, or a
+     * refused message), the send failed for good, or an operator decided the
+     * request before the mail went out. The operator reads an undelivered
+     * acknowledgement off it, on `GET /rma` and the `rma` frame each recorded
+     * verdict sends; the shopper's view never carries it.
      */
     type ReturnRequestAcknowledgement = PurchaseWithdrawalAcknowledgement;
     /** The change-of-mind terms snapshotted onto a request, so a later policy edit does not rewrite them. */

package/package.json

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