platform-types 1.10.728 → 1.10.730

package/dist/cjs/workItem.js

@@ -22,7 +22,7 @@
  * returned to the store's operators, and is never logged.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WORK_ITEM_TEXT_MAX = exports.WORK_ITEM_PAGE_MAX = exports.WORK_ITEM_HISTORY_KINDS = exports.WORK_ITEM_SOURCE_VERDICTS = exports.WORK_ITEM_AVAILABILITIES = exports.WORK_ITEM_STATUSES = exports.WORK_ITEM_FAMILIES = void 0;
+exports.WORK_ITEM_ERROR_CODES = exports.WORK_ITEM_TEXT_MAX = exports.WORK_ITEM_PAGE_MAX = exports.WORK_ITEM_HISTORY_KINDS = exports.WORK_ITEM_SOURCE_VERDICTS = exports.WORK_ITEM_AVAILABILITIES = exports.WORK_ITEM_STATUSES = exports.WORK_ITEM_FAMILIES = void 0;
 exports.WORK_ITEM_FAMILIES = [
     'order-create',
     'collection',
@@ -41,3 +41,65 @@ exports.WORK_ITEM_HISTORY_KINDS = ['reported', 'handover-requested', 'accepted',
 exports.WORK_ITEM_PAGE_MAX = 100;
 /** Upper bound on `summary` and on a `correct` note, in characters. */
 exports.WORK_ITEM_TEXT_MAX = 500;
+/**
+ * Refusals from `/work-items` — `stacks/lambdas/workItems/*.ts` (`_get`,
+ * `_post`). EVERYTHING those files can answer, not a selection.
+ *
+ * ⚠️ Completeness is asserted mechanically:
+ * `tests/unit/workItemPublishedContract.test.ts` reads those source files off
+ * disk and fails on any literal `error: '…'` code missing from this tuple, and
+ * on any member here that no source (or named shared helper) can answer.
+ *
+ * - `WORK_ITEM_NOT_FOUND` · 404 — no such item in this store. Payload-free.
+ * - `WORK_ITEM_NOT_OPEN` · 409 — a transition on a `resolved`/`corrected`
+ *   item, by a caller with authority over it; `data` is
+ *   {@link WorkItemStateConflictData}. Authority is checked BEFORE state, so a
+ *   caller without it gets its mode's refusal instead (`handover`/`resolve`:
+ *   `WORK_ITEM_NOT_RESPONSIBLE`; `accept`: `WORK_ITEM_NO_PENDING_HANDOVER`,
+ *   since a close strips the handover) — never read either as "still open".
+ * - `WORK_ITEM_VERSION_CONFLICT` · 409 — `expectedVersion` is stale, or the
+ *   write lost its compare-and-swap; `data` is {@link WorkItemStateConflictData}
+ *   when the item could be re-read, else absent.
+ * - `WORK_ITEM_NOT_RESPONSIBLE` · 403 — `handover`/`resolve` by someone who is
+ *   neither the responsible user nor ADMIN-tier.
+ * - `WORK_ITEM_HANDOVER_TO_SELF` · 400 — `toUserId` already holds the item.
+ * - `WORK_ITEM_TARGET_USER_NOT_FOUND` · 404 — `toUserId` is not a live operator
+ *   of this store.
+ * - `WORK_ITEM_NO_PENDING_HANDOVER` · 409 — `accept` with no handover pending,
+ *   including on an item that has since been closed. Payload-free.
+ * - `WORK_ITEM_NOT_HANDOVER_TARGET` · 403 — `accept` by anyone but the named
+ *   receiver.
+ * - `WORK_ITEM_UNRESOLVED_AT_SOURCE` · 409 — `resolve` whose source read is not
+ *   authoritative; `data` is {@link WorkItemUnresolvedAtSourceData}.
+ * - `WORK_ITEM_SOURCE_REF_INVALID` · 400 — an `order-create` report whose
+ *   `attemptKey` was not minted for this store and caller.
+ * - `WORK_ITEM_CAPTURED_AT_AHEAD` · 400 — `capturedAt` beyond the server's
+ *   skew allowance.
+ * - `ROLE_FORBIDDEN` · 403 — `GET ?scope=store` or `correct` by a non-ADMIN-tier
+ *   caller.
+ * - `INVALID_CURSOR` · 400 — a `?startKey=` that does not decode, or decodes to
+ *   a key outside this store's open-item range. Restart from the first page.
+ *   Read path only.
+ * - `VALIDATION_FAILED` · 400 — `stacks/helpers/validateRequest.ts`, on every
+ *   leg (including a family's missing required `sourceRef` field).
+ *
+ * ⚠️ `UNHANDLED_ERROR` is deliberately NOT here: it is `tryCatch`'s generic
+ * envelope for an unexpected throw and belongs to no endpoint. Cross-cutting
+ * refusals are NOT repeated here — check `GATING_ERROR_CODES` as well.
+ */
+exports.WORK_ITEM_ERROR_CODES = [
+    'WORK_ITEM_NOT_FOUND',
+    'WORK_ITEM_NOT_OPEN',
+    'WORK_ITEM_VERSION_CONFLICT',
+    'WORK_ITEM_NOT_RESPONSIBLE',
+    'WORK_ITEM_HANDOVER_TO_SELF',
+    'WORK_ITEM_TARGET_USER_NOT_FOUND',
+    'WORK_ITEM_NO_PENDING_HANDOVER',
+    'WORK_ITEM_NOT_HANDOVER_TARGET',
+    'WORK_ITEM_UNRESOLVED_AT_SOURCE',
+    'WORK_ITEM_SOURCE_REF_INVALID',
+    'WORK_ITEM_CAPTURED_AT_AHEAD',
+    'ROLE_FORBIDDEN',
+    'INVALID_CURSOR',
+    'VALIDATION_FAILED',
+];

package/dist/marketing.d.ts

@@ -74,11 +74,16 @@ declare global {
      * `'queued'` — accepted for delivery, not yet handed to the transport.
      * `'sent'` — the transport ACCEPTED it; acceptance is never proof of inbox
      * placement. `'failed'` — the transport refused or errored. `'skipped'` — the
-     * segment matched the recipient but the recipient was not eligible at send
-     * time (no marketing consent for the channel, or a suppressed address).
+     * segment matched the recipient but the send was withheld at send time: the
+     * recipient was not eligible (no marketing consent for the channel, no
+     * address, a suppressed address, a customer that no longer exists), the
+     * campaign was cancelled, or the store had its Marketing module switched off
+     * (`reason: 'MODULE_OFF'`). `CampaignRecipient.reason` carries which.
      *
      * ⚠️ `'skipped'` is a REFUSAL that was honoured, not a delivery problem:
-     * never retry it, and never roll it into a failure rate.
+     * never retry it, and never roll it into a failure rate. A `'MODULE_OFF'`
+     * skip is the STORE'S choice, not the customer's — group on `reason` before
+     * reading a skip as a consent refusal.
      */
     type CampaignRecipientStatus = 'queued' | 'sent' | 'failed' | 'skipped';
     /**
@@ -548,8 +553,9 @@ declare global {
     /**
      * `'queued'` — accepted, not yet handed to a transport. `'sent'` — handed
      * over. `'failed'` — the transport refused or errored. `'skipped'` — the rule
-     * matched but the send was withheld, by the frequency cap or by a live
-     * consent re-check.
+     * matched but the send was withheld, by the frequency cap, by a live
+     * consent re-check, or because the store had its Marketing module switched
+     * off (`reason: 'MODULE_OFF'`, a store choice rather than a customer's).
      *
      * Deliberately the same four values as {@link CampaignRecipientStatus}, and
      * deliberately a SEPARATE type rather than an alias: the two vocabularies

package/dist/store.d.ts

@@ -917,7 +917,7 @@ declare global {
              * `409 STORE_MODULE_BALANCE_CHECK_INCOMPLETE` when the bounded read could
              * not finish).
              *
-             * Enforced on the server for four modules only:
+             * Enforced on the server for six modules only:
              * - `promotions` — applying one is refused `PROMOTION_NOT_ACTIVE` (the
              *   existing promotion refusal, not `STORE_MODULE_DISABLED`), a grant already
              *   frozen on a cart stays on the row but derives no money (its
@@ -934,6 +934,11 @@ declare global {
              * - `multiWarehouse` — every sale resolves to the primary depósito (a
              *   scoped operator's sale to their own home depósito when the primary is
              *   outside their scope), and only the primary feeds MercadoLibre.
+             * - `loyalty` — the automatic earn credits nothing (the `loyalty-earn`
+             *   worker skips it, including one queued before the switch). The
+             *   operator's `POST /loyalty/earn` and every read stay reachable.
+             * - `marketing` — automation and campaign sends go out to nobody: each is
+             *   settled `'skipped'` with reason `MODULE_OFF` at its send worker.
              * Every other module is hide-only: its endpoints stay reachable. Public
              * reads carry only `appointments`, `surveys`, `promotions` and
              * `customerAccounts`. `PUT /platform/stores/{storeId}` refuses the leaf.

package/dist/workItem.d.ts

@@ -169,6 +169,27 @@ declare global {
         openCount: number;
         availability: Record<WorkItemFamily, WorkItemAvailability>;
     }
+    /**
+     * `data` of a state-bearing `409` — `WORK_ITEM_NOT_OPEN` (always) and
+     * `WORK_ITEM_VERSION_CONFLICT` (when the item could be re-read; a lost
+     * compare-and-swap whose re-read finds nothing answers with no `data`).
+     * `current` is the item as the server holds it now. The pre-write refusals
+     * are answered only past the mode's authority gate. ⚠️ The post-commit
+     * conflict (a compare-and-swap lost after that gate passed) re-reads the item
+     * and returns it WITHOUT re-checking authority, so its `current` can reflect
+     * a responsibility or handover that moved in the race.
+     */
+    interface WorkItemStateConflictData {
+        current: WorkItem;
+    }
+    /**
+     * `data` of `409 WORK_ITEM_UNRESOLVED_AT_SOURCE` — the source read that did
+     * not decide the item. `verdict.verdict` is `pending` or `unknown`, never an
+     * authoritative one.
+     */
+    interface WorkItemUnresolvedAtSourceData {
+        verdict: WorkItemSourceVerdict;
+    }
     /** The `workItems` socket frame's `data` — refetch, never patch from it. */
     interface WorkItemFrameData {
         itemId: string;
@@ -186,3 +207,51 @@ export declare const WORK_ITEM_HISTORY_KINDS: readonly ["reported", "handover-re
 export declare const WORK_ITEM_PAGE_MAX = 100;
 /** Upper bound on `summary` and on a `correct` note, in characters. */
 export declare const WORK_ITEM_TEXT_MAX = 500;
+/**
+ * Refusals from `/work-items` — `stacks/lambdas/workItems/*.ts` (`_get`,
+ * `_post`). EVERYTHING those files can answer, not a selection.
+ *
+ * ⚠️ Completeness is asserted mechanically:
+ * `tests/unit/workItemPublishedContract.test.ts` reads those source files off
+ * disk and fails on any literal `error: '…'` code missing from this tuple, and
+ * on any member here that no source (or named shared helper) can answer.
+ *
+ * - `WORK_ITEM_NOT_FOUND` · 404 — no such item in this store. Payload-free.
+ * - `WORK_ITEM_NOT_OPEN` · 409 — a transition on a `resolved`/`corrected`
+ *   item, by a caller with authority over it; `data` is
+ *   {@link WorkItemStateConflictData}. Authority is checked BEFORE state, so a
+ *   caller without it gets its mode's refusal instead (`handover`/`resolve`:
+ *   `WORK_ITEM_NOT_RESPONSIBLE`; `accept`: `WORK_ITEM_NO_PENDING_HANDOVER`,
+ *   since a close strips the handover) — never read either as "still open".
+ * - `WORK_ITEM_VERSION_CONFLICT` · 409 — `expectedVersion` is stale, or the
+ *   write lost its compare-and-swap; `data` is {@link WorkItemStateConflictData}
+ *   when the item could be re-read, else absent.
+ * - `WORK_ITEM_NOT_RESPONSIBLE` · 403 — `handover`/`resolve` by someone who is
+ *   neither the responsible user nor ADMIN-tier.
+ * - `WORK_ITEM_HANDOVER_TO_SELF` · 400 — `toUserId` already holds the item.
+ * - `WORK_ITEM_TARGET_USER_NOT_FOUND` · 404 — `toUserId` is not a live operator
+ *   of this store.
+ * - `WORK_ITEM_NO_PENDING_HANDOVER` · 409 — `accept` with no handover pending,
+ *   including on an item that has since been closed. Payload-free.
+ * - `WORK_ITEM_NOT_HANDOVER_TARGET` · 403 — `accept` by anyone but the named
+ *   receiver.
+ * - `WORK_ITEM_UNRESOLVED_AT_SOURCE` · 409 — `resolve` whose source read is not
+ *   authoritative; `data` is {@link WorkItemUnresolvedAtSourceData}.
+ * - `WORK_ITEM_SOURCE_REF_INVALID` · 400 — an `order-create` report whose
+ *   `attemptKey` was not minted for this store and caller.
+ * - `WORK_ITEM_CAPTURED_AT_AHEAD` · 400 — `capturedAt` beyond the server's
+ *   skew allowance.
+ * - `ROLE_FORBIDDEN` · 403 — `GET ?scope=store` or `correct` by a non-ADMIN-tier
+ *   caller.
+ * - `INVALID_CURSOR` · 400 — a `?startKey=` that does not decode, or decodes to
+ *   a key outside this store's open-item range. Restart from the first page.
+ *   Read path only.
+ * - `VALIDATION_FAILED` · 400 — `stacks/helpers/validateRequest.ts`, on every
+ *   leg (including a family's missing required `sourceRef` field).
+ *
+ * ⚠️ `UNHANDLED_ERROR` is deliberately NOT here: it is `tryCatch`'s generic
+ * envelope for an unexpected throw and belongs to no endpoint. Cross-cutting
+ * refusals are NOT repeated here — check `GATING_ERROR_CODES` as well.
+ */
+export declare const WORK_ITEM_ERROR_CODES: readonly ["WORK_ITEM_NOT_FOUND", "WORK_ITEM_NOT_OPEN", "WORK_ITEM_VERSION_CONFLICT", "WORK_ITEM_NOT_RESPONSIBLE", "WORK_ITEM_HANDOVER_TO_SELF", "WORK_ITEM_TARGET_USER_NOT_FOUND", "WORK_ITEM_NO_PENDING_HANDOVER", "WORK_ITEM_NOT_HANDOVER_TARGET", "WORK_ITEM_UNRESOLVED_AT_SOURCE", "WORK_ITEM_SOURCE_REF_INVALID", "WORK_ITEM_CAPTURED_AT_AHEAD", "ROLE_FORBIDDEN", "INVALID_CURSOR", "VALIDATION_FAILED"];
+export type WorkItemErrorCode = (typeof WORK_ITEM_ERROR_CODES)[number];

package/dist/workItem.js

@@ -38,3 +38,65 @@ export const WORK_ITEM_HISTORY_KINDS = ['reported', 'handover-requested', 'accep
 export const WORK_ITEM_PAGE_MAX = 100;
 /** Upper bound on `summary` and on a `correct` note, in characters. */
 export const WORK_ITEM_TEXT_MAX = 500;
+/**
+ * Refusals from `/work-items` — `stacks/lambdas/workItems/*.ts` (`_get`,
+ * `_post`). EVERYTHING those files can answer, not a selection.
+ *
+ * ⚠️ Completeness is asserted mechanically:
+ * `tests/unit/workItemPublishedContract.test.ts` reads those source files off
+ * disk and fails on any literal `error: '…'` code missing from this tuple, and
+ * on any member here that no source (or named shared helper) can answer.
+ *
+ * - `WORK_ITEM_NOT_FOUND` · 404 — no such item in this store. Payload-free.
+ * - `WORK_ITEM_NOT_OPEN` · 409 — a transition on a `resolved`/`corrected`
+ *   item, by a caller with authority over it; `data` is
+ *   {@link WorkItemStateConflictData}. Authority is checked BEFORE state, so a
+ *   caller without it gets its mode's refusal instead (`handover`/`resolve`:
+ *   `WORK_ITEM_NOT_RESPONSIBLE`; `accept`: `WORK_ITEM_NO_PENDING_HANDOVER`,
+ *   since a close strips the handover) — never read either as "still open".
+ * - `WORK_ITEM_VERSION_CONFLICT` · 409 — `expectedVersion` is stale, or the
+ *   write lost its compare-and-swap; `data` is {@link WorkItemStateConflictData}
+ *   when the item could be re-read, else absent.
+ * - `WORK_ITEM_NOT_RESPONSIBLE` · 403 — `handover`/`resolve` by someone who is
+ *   neither the responsible user nor ADMIN-tier.
+ * - `WORK_ITEM_HANDOVER_TO_SELF` · 400 — `toUserId` already holds the item.
+ * - `WORK_ITEM_TARGET_USER_NOT_FOUND` · 404 — `toUserId` is not a live operator
+ *   of this store.
+ * - `WORK_ITEM_NO_PENDING_HANDOVER` · 409 — `accept` with no handover pending,
+ *   including on an item that has since been closed. Payload-free.
+ * - `WORK_ITEM_NOT_HANDOVER_TARGET` · 403 — `accept` by anyone but the named
+ *   receiver.
+ * - `WORK_ITEM_UNRESOLVED_AT_SOURCE` · 409 — `resolve` whose source read is not
+ *   authoritative; `data` is {@link WorkItemUnresolvedAtSourceData}.
+ * - `WORK_ITEM_SOURCE_REF_INVALID` · 400 — an `order-create` report whose
+ *   `attemptKey` was not minted for this store and caller.
+ * - `WORK_ITEM_CAPTURED_AT_AHEAD` · 400 — `capturedAt` beyond the server's
+ *   skew allowance.
+ * - `ROLE_FORBIDDEN` · 403 — `GET ?scope=store` or `correct` by a non-ADMIN-tier
+ *   caller.
+ * - `INVALID_CURSOR` · 400 — a `?startKey=` that does not decode, or decodes to
+ *   a key outside this store's open-item range. Restart from the first page.
+ *   Read path only.
+ * - `VALIDATION_FAILED` · 400 — `stacks/helpers/validateRequest.ts`, on every
+ *   leg (including a family's missing required `sourceRef` field).
+ *
+ * ⚠️ `UNHANDLED_ERROR` is deliberately NOT here: it is `tryCatch`'s generic
+ * envelope for an unexpected throw and belongs to no endpoint. Cross-cutting
+ * refusals are NOT repeated here — check `GATING_ERROR_CODES` as well.
+ */
+export const WORK_ITEM_ERROR_CODES = [
+    'WORK_ITEM_NOT_FOUND',
+    'WORK_ITEM_NOT_OPEN',
+    'WORK_ITEM_VERSION_CONFLICT',
+    'WORK_ITEM_NOT_RESPONSIBLE',
+    'WORK_ITEM_HANDOVER_TO_SELF',
+    'WORK_ITEM_TARGET_USER_NOT_FOUND',
+    'WORK_ITEM_NO_PENDING_HANDOVER',
+    'WORK_ITEM_NOT_HANDOVER_TARGET',
+    'WORK_ITEM_UNRESOLVED_AT_SOURCE',
+    'WORK_ITEM_SOURCE_REF_INVALID',
+    'WORK_ITEM_CAPTURED_AT_AHEAD',
+    'ROLE_FORBIDDEN',
+    'INVALID_CURSOR',
+    'VALIDATION_FAILED',
+];

package/package.json

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