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