platform-types 1.10.818 → 1.10.820

package/dist/cjs/purchaseWithdrawal.js

@@ -20,7 +20,7 @@
  * `status`, `revisedAt` replaces `updatedAt`, and there is no `dated`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PURCHASE_WITHDRAWAL_VERIFICATION_FAILED = exports.PURCHASE_WITHDRAWAL_GUEST_INTENTS = exports.PURCHASE_WITHDRAWAL_CODE_DUE_MS = exports.PURCHASE_WITHDRAWAL_CODE_DUE_SOURCE = exports.PURCHASE_WITHDRAWAL_WINDOW_SOURCE = exports.PURCHASE_WITHDRAWAL_WINDOW_DAYS = exports.PURCHASE_WITHDRAWAL_LINES_MAX = exports.PURCHASE_WITHDRAWAL_NOTE_MAX = exports.PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS = exports.PURCHASE_WITHDRAWAL_ACTION_MODES = exports.PURCHASE_WITHDRAWAL_RELAY_CHANNELS = exports.PURCHASE_WITHDRAWAL_DECLINE_REASONS = exports.PURCHASE_WITHDRAWAL_SOURCES = exports.PURCHASE_WITHDRAWAL_LIST_FILTERS = exports.PURCHASE_WITHDRAWAL_STATES = void 0;
+exports.PURCHASE_WITHDRAWAL_VERIFICATION_FAILED = exports.PURCHASE_WITHDRAWAL_GUEST_INTENTS = exports.PURCHASE_WITHDRAWAL_CODE_DUE_MS = exports.PURCHASE_WITHDRAWAL_CODE_DUE_SOURCE = exports.PURCHASE_WITHDRAWAL_WINDOW_SOURCE = exports.PURCHASE_WITHDRAWAL_WINDOW_DAYS = exports.PURCHASE_WITHDRAWAL_LINES_MAX = exports.PURCHASE_WITHDRAWAL_NOTE_MAX = exports.PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT_CAUSES = exports.PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS = exports.PURCHASE_WITHDRAWAL_ACTION_MODES = exports.PURCHASE_WITHDRAWAL_RELAY_CHANNELS = exports.PURCHASE_WITHDRAWAL_DECLINE_REASONS = exports.PURCHASE_WITHDRAWAL_SOURCES = exports.PURCHASE_WITHDRAWAL_LIST_FILTERS = exports.PURCHASE_WITHDRAWAL_STATES = void 0;
 /**
  * - `requested` — submitted, the code minted, the order's dispatch locked
  *   (`purchase-withdrawal-pending`) until an operator decides.
@@ -29,9 +29,12 @@ exports.PURCHASE_WITHDRAWAL_VERIFICATION_FAILED = exports.PURCHASE_WITHDRAWAL_GU
  * - `accepted` — an operator accepted it. The order's cancellation (before
  *   fulfilment) or its return authorisation (after it) follows from here.
  * - `awaiting-goods` — after fulfilment, the goods are on their way back.
- * - `refund-pending` — money is owed back (an open refund obligation).
+ * - `refund-pending` — money is owed back (an open refund obligation). Moves
+ *   to `completed` with the closure of its last open obligation, never while
+ *   another one is open.
  * - `completed` — nothing is owed any more. Not final while money can still
- *   arrive: a late capture moves it back to `refund-pending`.
+ *   arrive: a late capture (a new payment approval the order's payment
+ *   attempt refused to settle) moves it back to `refund-pending`.
  */
 exports.PURCHASE_WITHDRAWAL_STATES = [
     'requested',
@@ -88,6 +91,20 @@ exports.PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS = [
     'line-unavailable',
     'nothing-to-withdraw',
 ];
+/**
+ * Why accepting a withdrawal before fulfilment is refused
+ * `409 PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT` (`data.cause`) — a factura is in
+ * flight on the order, so cancelling it now could leave a voucher on a
+ * withdrawn order:
+ *
+ * - `in-progress` — a factura issuance holds the order's fence right now.
+ *   Retry once it ends.
+ * - `uncertain` — an earlier factura issuance was interrupted and its outcome
+ *   at ARCA is not confirmed. Retryable only after support reconciles it.
+ * - `stranded` — a voucher ARCA authorised could not be recorded on the order.
+ *   Retryable only after support records it.
+ */
+exports.PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT_CAUSES = ['in-progress', 'uncertain', 'stranded'];
 /** The longest decline or relay `note`, in characters after trimming. */
 exports.PURCHASE_WITHDRAWAL_NOTE_MAX = 500;
 /** The most lines one request may name. */

package/dist/order.d.ts

@@ -1269,7 +1269,11 @@ declare global {
          * All four fields are absent on a non-cancelled order.
          */
         cancelledAt?: number;
-        /** Who cancelled: the customerId for a self-cancellation, the operator's userId for an operator cancellation. */
+        /**
+         * Who cancelled: the customerId for a self-cancellation, the operator's
+         * userId for an operator cancellation and for a purchase-withdrawal one
+         * (the operator who accepted it), `'system'` for the payment-hold expiry.
+         */
         cancelledBy?: string;
         cancellationSource?: OrderCancellationSource;
         /**
@@ -1380,8 +1384,14 @@ declare global {
      * (`services/orderSystemCancellation.ts`, run by the payment-attempt sweep),
      * which cancels an order whose online payment attempt lapsed unpaid; its
      * `cancelledBy` is `'system'`, never a user id.
+     *
+     * `purchase-withdrawal` is written only by the purchase-withdrawal door
+     * (`lambdas/orders/_purchaseWithdrawalCancel.ts`): the order cancelled
+     * because an operator accepted the shopper's purchase withdrawal before
+     * fulfilment. Its `cancelledBy` is the accepting operator's userId (the
+     * commit is the operator's act), and it carries no `cancellationReason`.
      */
-    type OrderCancellationSource = 'customer' | 'operator' | 'system';
+    type OrderCancellationSource = 'customer' | 'operator' | 'system' | 'purchase-withdrawal';
     /**
      * Machine-readable reason an order is locked against a mutation — the
      * payload of `409 ORDER_LOCKED` (on the customer cancellation's `409 ORDER_CANCELLATION_LOCKED` it rides in `message` as `reason: <r>` and that body has no `reason` key; the operator cancellation's carries both), and the

package/dist/purchaseWithdrawal.d.ts

@@ -26,9 +26,12 @@
  * - `accepted` — an operator accepted it. The order's cancellation (before
  *   fulfilment) or its return authorisation (after it) follows from here.
  * - `awaiting-goods` — after fulfilment, the goods are on their way back.
- * - `refund-pending` — money is owed back (an open refund obligation).
+ * - `refund-pending` — money is owed back (an open refund obligation). Moves
+ *   to `completed` with the closure of its last open obligation, never while
+ *   another one is open.
  * - `completed` — nothing is owed any more. Not final while money can still
- *   arrive: a late capture moves it back to `refund-pending`.
+ *   arrive: a late capture (a new payment approval the order's payment
+ *   attempt refused to settle) moves it back to `refund-pending`.
  */
 export declare const PURCHASE_WITHDRAWAL_STATES: readonly ["requested", "declined", "accepted", "awaiting-goods", "refund-pending", "completed"];
 /**
@@ -63,6 +66,20 @@ export declare const PURCHASE_WITHDRAWAL_ACTION_MODES: readonly ["accept", "decl
  * - `nothing-to-withdraw` — every line is already withdrawn or returned.
  */
 export declare const PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS: readonly ["order-cancelled", "no-customer", "partial-before-fulfilment", "line-not-on-order", "line-unavailable", "nothing-to-withdraw"];
+/**
+ * Why accepting a withdrawal before fulfilment is refused
+ * `409 PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT` (`data.cause`) — a factura is in
+ * flight on the order, so cancelling it now could leave a voucher on a
+ * withdrawn order:
+ *
+ * - `in-progress` — a factura issuance holds the order's fence right now.
+ *   Retry once it ends.
+ * - `uncertain` — an earlier factura issuance was interrupted and its outcome
+ *   at ARCA is not confirmed. Retryable only after support reconciles it.
+ * - `stranded` — a voucher ARCA authorised could not be recorded on the order.
+ *   Retryable only after support records it.
+ */
+export declare const PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT_CAUSES: readonly ["in-progress", "uncertain", "stranded"];
 /** The longest decline or relay `note`, in characters after trimming. */
 export declare const PURCHASE_WITHDRAWAL_NOTE_MAX = 500;
 /** The most lines one request may name. */
@@ -97,6 +114,7 @@ declare global {
     type PurchaseWithdrawalActionMode = (typeof PURCHASE_WITHDRAWAL_ACTION_MODES)[number];
     type PurchaseWithdrawalIneligibleReason = (typeof PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS)[number];
     type PurchaseWithdrawalGuestIntent = (typeof PURCHASE_WITHDRAWAL_GUEST_INTENTS)[number];
+    type PurchaseWithdrawalFiscalInFlightCause = (typeof PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT_CAUSES)[number];
     /** One withdrawn order line, by its index in `Order.items`. */
     interface PurchaseWithdrawalLine {
         orderItemIndex: number;
@@ -386,6 +404,13 @@ declare global {
         decision?: PurchaseWithdrawalDecision;
         declineReason?: PurchaseWithdrawalDeclineReason;
     }
+    /**
+     * `data` of `409 PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT`: why the order's
+     * cancellation must wait on its fiscal state. Nothing was written.
+     */
+    interface PurchaseWithdrawalFiscalInFlightData {
+        cause: PurchaseWithdrawalFiscalInFlightCause;
+    }
     /** `data` of `409 PURCHASE_WITHDRAWAL_CHANGED`: the withdrawal as it now stands — review it and resend. */
     interface PurchaseWithdrawalChangedData {
         purchaseWithdrawal: PurchaseWithdrawal;

package/dist/purchaseWithdrawal.js

@@ -26,9 +26,12 @@
  * - `accepted` — an operator accepted it. The order's cancellation (before
  *   fulfilment) or its return authorisation (after it) follows from here.
  * - `awaiting-goods` — after fulfilment, the goods are on their way back.
- * - `refund-pending` — money is owed back (an open refund obligation).
+ * - `refund-pending` — money is owed back (an open refund obligation). Moves
+ *   to `completed` with the closure of its last open obligation, never while
+ *   another one is open.
  * - `completed` — nothing is owed any more. Not final while money can still
- *   arrive: a late capture moves it back to `refund-pending`.
+ *   arrive: a late capture (a new payment approval the order's payment
+ *   attempt refused to settle) moves it back to `refund-pending`.
  */
 export const PURCHASE_WITHDRAWAL_STATES = [
     'requested',
@@ -85,6 +88,20 @@ export const PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS = [
     'line-unavailable',
     'nothing-to-withdraw',
 ];
+/**
+ * Why accepting a withdrawal before fulfilment is refused
+ * `409 PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT` (`data.cause`) — a factura is in
+ * flight on the order, so cancelling it now could leave a voucher on a
+ * withdrawn order:
+ *
+ * - `in-progress` — a factura issuance holds the order's fence right now.
+ *   Retry once it ends.
+ * - `uncertain` — an earlier factura issuance was interrupted and its outcome
+ *   at ARCA is not confirmed. Retryable only after support reconciles it.
+ * - `stranded` — a voucher ARCA authorised could not be recorded on the order.
+ *   Retryable only after support records it.
+ */
+export const PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT_CAUSES = ['in-progress', 'uncertain', 'stranded'];
 /** The longest decline or relay `note`, in characters after trimming. */
 export const PURCHASE_WITHDRAWAL_NOTE_MAX = 500;
 /** The most lines one request may name. */

package/package.json

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