platform-types 1.10.828 → 1.10.830

package/dist/cjs/purchaseWithdrawal.js

@@ -28,8 +28,15 @@ exports.PURCHASE_WITHDRAWAL_VERIFICATION_FAILED = exports.SHOPPER_REQUEST_INTENT
  *   Terminal.
  * - `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). Moves
+ * - `awaiting-goods` — after fulfilment, the goods are on their way back. Its
+ *   refund obligations wait `awaiting-goods` too. At the collection deadline
+ *   (`collectByAt` on its RMA) the hourly refund sweep opens them, due
+ *   `refundObligationDueDays` after that deadline, whether or not the goods
+ *   came back, and moves the withdrawal to `refund-pending` when one is owed.
+ *   Nothing writes this state yet: the hand-off that does is still to ship.
+ * - `refund-pending` — money is owed back (an open refund obligation): reached
+ *   from `awaiting-goods` at the collection deadline, or from `completed` by a
+ *   late capture. 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

package/dist/purchaseWithdrawal.d.ts

@@ -25,8 +25,15 @@
  *   Terminal.
  * - `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). Moves
+ * - `awaiting-goods` — after fulfilment, the goods are on their way back. Its
+ *   refund obligations wait `awaiting-goods` too. At the collection deadline
+ *   (`collectByAt` on its RMA) the hourly refund sweep opens them, due
+ *   `refundObligationDueDays` after that deadline, whether or not the goods
+ *   came back, and moves the withdrawal to `refund-pending` when one is owed.
+ *   Nothing writes this state yet: the hand-off that does is still to ship.
+ * - `refund-pending` — money is owed back (an open refund obligation): reached
+ *   from `awaiting-goods` at the collection deadline, or from `completed` by a
+ *   late capture. 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
@@ -141,10 +148,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/purchaseWithdrawal.js

@@ -25,8 +25,15 @@
  *   Terminal.
  * - `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). Moves
+ * - `awaiting-goods` — after fulfilment, the goods are on their way back. Its
+ *   refund obligations wait `awaiting-goods` too. At the collection deadline
+ *   (`collectByAt` on its RMA) the hourly refund sweep opens them, due
+ *   `refundObligationDueDays` after that deadline, whether or not the goods
+ *   came back, and moves the withdrawal to `refund-pending` when one is owed.
+ *   Nothing writes this state yet: the hand-off that does is still to ship.
+ * - `refund-pending` — money is owed back (an open refund obligation): reached
+ *   from `awaiting-goods` at the collection deadline, or from `completed` by a
+ *   late capture. 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

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.828",
+	"version": "1.10.830",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",