platform-types 1.10.828 → 1.10.829

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