platform-types 1.10.714 → 1.10.715

package/dist/cjs/delivery.js

@@ -1,2 +1,50 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DELIVERY_ERROR_CODES = void 0;
+/**
+ * Every refusal code the delivery handlers (`POST /deliveries`,
+ * `POST /deliveries/{id}/events`, `GET /deliveries`, `GET /deliveries/{id}`)
+ * put on the wire, beyond the platform-wide set (`VALIDATION_FAILED`,
+ * `ROLE_FORBIDDEN`, `tryCatch`'s generic `UNHANDLED_ERROR`). Pinned against
+ * the handler sources by `tests/unit/deliveryErrorCodesPublished.test.ts`.
+ *
+ * - `INVALID_DELIVERY_ID` · 400 — no delivery id in the path.
+ * - `DELIVERY_NOT_FOUND` · 404 — unknown id, or another tenant's.
+ * - `DELIVERY_NOT_ASSIGNED` · 403 — the delivery names a platform courier
+ *   (`courier.userId`) and the caller is neither that user nor ADMIN-tier.
+ * - `DELIVERY_TERMINAL` · 409 — the delivery is already `'delivered'` or
+ *   `'failed'`; a failed delivery is re-dispatched through `POST /deliveries`.
+ * - `INVALID_IDEMPOTENCY_KEY` · 400 — the key is not ≤200 chars of
+ *   `[A-Za-z0-9._:-]`.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — the key was used with a different body.
+ * - `IDEMPOTENCY_KEY_FAILED` · 409 — the attempt under the key failed after it
+ *   may have written proof, or the attempt lookup fenced the key; ask the
+ *   lookup, then use a new key.
+ * - `IDEMPOTENCY_IN_PROGRESS` · 409 — the same key is still running.
+ * - `IDEMPOTENCY_LOCK_CONTENTION` · 409 — the key's marker could not be
+ *   claimed; retry under the SAME key.
+ * - `INVALID_CURSOR` · 400 — a `?mine=true` `startKey` that is malformed or
+ *   names another store's partition.
+ * - `IMPERSONATION_READONLY` · 403 — the attempt lookup, under a support
+ *   session, could answer only by fencing the key (`op: 'delivery.attemptFence'`).
+ * - `INVALID_BASE64` · 400, `CONTENT_TOO_LARGE` · 413,
+ *   `UNSUPPORTED_MEDIA_TYPE` · 415 — the inline proof payload was refused
+ *   before anything was stored.
+ */
+exports.DELIVERY_ERROR_CODES = [
+    'DELIVERY_NOT_FOUND',
+    'DELIVERY_NOT_ASSIGNED',
+    'DELIVERY_TERMINAL',
+    'INVALID_DELIVERY_ID',
+    'INVALID_IDEMPOTENCY_KEY',
+    'IDEMPOTENCY_KEY_REUSE',
+    'IDEMPOTENCY_KEY_FAILED',
+    'IDEMPOTENCY_IN_PROGRESS',
+    'IDEMPOTENCY_LOCK_CONTENTION',
+    'INVALID_CURSOR',
+    'IMPERSONATION_READONLY',
+    // The proof payload gate (`deliveryAttachmentValidation.ts`).
+    'INVALID_BASE64',
+    'CONTENT_TOO_LARGE',
+    'UNSUPPORTED_MEDIA_TYPE',
+];

package/dist/delivery.d.ts

@@ -84,8 +84,9 @@ declare global {
     }
     /**
      * One append-only entry in a delivery's timeline. Never overwritten and never
-     * deleted: a correction is a NEW event, so a `'delivered'` later contradicted
-     * by a `'failed'` leaves both on the record.
+     * deleted. `'delivered'` and `'failed'` are TERMINAL: nothing is appended
+     * after either (`409 DELIVERY_TERMINAL`), and a failed delivery is
+     * re-dispatched as a new delivery through `POST /deliveries`.
      *
      * PK `DELIVERY#{storeId}#{deliveryId}`, SK `EVENT#{createdAt}#{eventId}` —
      * the storeId segment is load-bearing, exactly as it is for `CashEvent`:
@@ -108,6 +109,18 @@ declare global {
         proof?: DeliveryProofAsset[];
         /** Set only on a `'failed'` event. */
         failureReason?: DeliveryFailureReason;
+        /**
+         * The `Idempotency-Key` the actor appended this event under — what lets a
+         * client match its own attempt exactly instead of guessing from type, time
+         * or photo count.
+         *
+         * ⚠️ Actor-scoped on the wire: `GET /deliveries/{id}` returns it only when
+         * the reader is this event's `actorUserId` or an ADMIN-tier role, and omits
+         * it otherwise. Absent on an event appended WITHOUT a key (still accepted —
+         * see `DeliveryEventAppendRequest`), on one written before keys existed, and
+         * on the opening `'assigned'` event `POST /deliveries` writes.
+         */
+        idempotencyKey?: string;
     }
     /**
      * A `DeliveryProofAsset` carrying the read-time-only `downloadUrl` minted by
@@ -126,5 +139,125 @@ declare global {
     type DeliveryEventWithProofUrls = Omit<DeliveryEvent, 'proof'> & {
         proof?: DeliveryProofAssetWithUrl[];
     };
+    /**
+     * Body of `POST /deliveries/{id}/events`. The `Idempotency-Key` header is
+     * OPTIONAL for now and strongly recommended — the key, not the body, is what
+     * makes a retry safe. It becomes REQUIRED in a later change, once the courier
+     * app sends it.
+     *
+     * ⚠️ WITHOUT a key the append is NOT idempotent: every call writes a new
+     * event, so a resend after a lost response records the event twice. Same
+     * validation, assignee scoping and terminal refusal; no replay protection and
+     * no attempt lookup.
+     *
+     * WITH a key, resend the SAME key with the byte-identical body after a lost
+     * response: a committed attempt answers its original event
+     * (`Idempotent-Replayed: true`), a changed body under that key is
+     * `422 IDEMPOTENCY_KEY_REUSE`.
+     *
+     * A transient fault answers `tryCatch`'s generic `400 UNHANDLED_ERROR`. A
+     * same-key resend then replays the attempt if it committed, RE-RUNS only if
+     * DynamoDB cancelled its transaction (nothing applied), and otherwise answers
+     * `409 IDEMPOTENCY_KEY_FAILED` — the attempt may have stored proof or
+     * committed, so the key is sealed. On that 409, ask
+     * `GET /deliveries/{id}?idempotencyKey=` (`DeliveryEventAttemptLookup`) and
+     * mint a new key only when it answers `'not-committed'`.
+     *
+     * The server sets `actorUserId`, `createdAt`, `gps.receivedAt` and the proof
+     * object keys; none of them is accepted here.
+     *
+     * Held to its schema by `AssertDeliveryEventAppendRequestMatchesSchema`.
+     */
+    interface DeliveryEventAppendRequest {
+        type: DeliveryEventType;
+        /** ≤ 1000 characters. */
+        note?: string;
+        gps?: Omit<DeliveryGpsFix, 'receivedAt'>;
+        /**
+         * Inline base64 proof, at most 5 assets (`MAX_PROOF_ASSETS_PER_EVENT`). Stored
+         * under a name derived from the delivery, the key, the asset's position and
+         * its bytes, written create-only — a retry can never replace an object.
+         */
+        proof?: Array<{
+            kind: DeliveryProofAsset['kind'];
+            contentType: string;
+            data: string;
+        }>;
+        /** Only on a `'failed'` event — anything else is `400 VALIDATION_FAILED`. */
+        failureReason?: DeliveryFailureReason;
+    }
+    /**
+     * What `GET /deliveries/{id}?idempotencyKey=<key>` answers about the
+     * CALLER'S OWN attempt under that key on THAT delivery — the authoritative
+     * recovery read, unlike the bounded (`truncated`) timeline, which can never
+     * prove absence.
+     *
+     * - `'committed'` — the attempt's event exists; `event` is that exact
+     *   original. Never append again for it.
+     * - `'pending'` — a request under the key is still in flight. Re-ask after
+     *   `retryAfterMs`; nothing was fenced.
+     * - `'not-committed'` — nothing was appended under the key, and the key is
+     *   FENCED: a durable tombstone (written by this read, or an earlier one, at
+     *   `fencedAt`) makes every later commit under it refuse. Only now may the
+     *   client mint a NEW key for the same intent; the old key answers
+     *   `409 IDEMPOTENCY_KEY_FAILED` forever.
+     *
+     * ⚠️ This read can WRITE: when the key is neither committed nor in flight it
+     * writes the tombstone before answering `'not-committed'`, so asking is itself
+     * a decision to give the key up. A client that would rather keep it resends
+     * under the same key instead.
+     *
+     * Attempt evidence is durable (no TTL), so both `'committed'` and
+     * `'not-committed'` stay answerable for the life of the delivery.
+     *
+     * The lookup takes the append's own authority bar: on a delivery that names
+     * a platform courier, a caller who is neither that courier nor ADMIN-tier is
+     * `403 DELIVERY_NOT_ASSIGNED`, before anything is read or written. Under an
+     * impersonated support session it answers only from stored state, and is
+     * `403 IMPERSONATION_READONLY` (`op: 'delivery.attemptFence'`) exactly where
+     * answering would need the tombstone.
+     */
+    interface DeliveryEventAttemptLookup {
+        idempotencyKey: string;
+        verdict: 'committed' | 'pending' | 'not-committed';
+        /** Present only on `'committed'`. */
+        event?: DeliveryEventWithProofUrls;
+        /** Present only on `'pending'`. */
+        retryAfterMs?: number;
+        /** Present only on `'not-committed'` — ms epoch the tombstone was written. */
+        fencedAt?: number;
+    }
 }
+/**
+ * Every refusal code the delivery handlers (`POST /deliveries`,
+ * `POST /deliveries/{id}/events`, `GET /deliveries`, `GET /deliveries/{id}`)
+ * put on the wire, beyond the platform-wide set (`VALIDATION_FAILED`,
+ * `ROLE_FORBIDDEN`, `tryCatch`'s generic `UNHANDLED_ERROR`). Pinned against
+ * the handler sources by `tests/unit/deliveryErrorCodesPublished.test.ts`.
+ *
+ * - `INVALID_DELIVERY_ID` · 400 — no delivery id in the path.
+ * - `DELIVERY_NOT_FOUND` · 404 — unknown id, or another tenant's.
+ * - `DELIVERY_NOT_ASSIGNED` · 403 — the delivery names a platform courier
+ *   (`courier.userId`) and the caller is neither that user nor ADMIN-tier.
+ * - `DELIVERY_TERMINAL` · 409 — the delivery is already `'delivered'` or
+ *   `'failed'`; a failed delivery is re-dispatched through `POST /deliveries`.
+ * - `INVALID_IDEMPOTENCY_KEY` · 400 — the key is not ≤200 chars of
+ *   `[A-Za-z0-9._:-]`.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — the key was used with a different body.
+ * - `IDEMPOTENCY_KEY_FAILED` · 409 — the attempt under the key failed after it
+ *   may have written proof, or the attempt lookup fenced the key; ask the
+ *   lookup, then use a new key.
+ * - `IDEMPOTENCY_IN_PROGRESS` · 409 — the same key is still running.
+ * - `IDEMPOTENCY_LOCK_CONTENTION` · 409 — the key's marker could not be
+ *   claimed; retry under the SAME key.
+ * - `INVALID_CURSOR` · 400 — a `?mine=true` `startKey` that is malformed or
+ *   names another store's partition.
+ * - `IMPERSONATION_READONLY` · 403 — the attempt lookup, under a support
+ *   session, could answer only by fencing the key (`op: 'delivery.attemptFence'`).
+ * - `INVALID_BASE64` · 400, `CONTENT_TOO_LARGE` · 413,
+ *   `UNSUPPORTED_MEDIA_TYPE` · 415 — the inline proof payload was refused
+ *   before anything was stored.
+ */
+export declare const DELIVERY_ERROR_CODES: readonly ["DELIVERY_NOT_FOUND", "DELIVERY_NOT_ASSIGNED", "DELIVERY_TERMINAL", "INVALID_DELIVERY_ID", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_KEY_REUSE", "IDEMPOTENCY_KEY_FAILED", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_LOCK_CONTENTION", "INVALID_CURSOR", "IMPERSONATION_READONLY", "INVALID_BASE64", "CONTENT_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE"];
+export type DeliveryErrorCode = (typeof DELIVERY_ERROR_CODES)[number];
 export {};

package/dist/delivery.js

@@ -1 +1,47 @@
-export {};
+/**
+ * Every refusal code the delivery handlers (`POST /deliveries`,
+ * `POST /deliveries/{id}/events`, `GET /deliveries`, `GET /deliveries/{id}`)
+ * put on the wire, beyond the platform-wide set (`VALIDATION_FAILED`,
+ * `ROLE_FORBIDDEN`, `tryCatch`'s generic `UNHANDLED_ERROR`). Pinned against
+ * the handler sources by `tests/unit/deliveryErrorCodesPublished.test.ts`.
+ *
+ * - `INVALID_DELIVERY_ID` · 400 — no delivery id in the path.
+ * - `DELIVERY_NOT_FOUND` · 404 — unknown id, or another tenant's.
+ * - `DELIVERY_NOT_ASSIGNED` · 403 — the delivery names a platform courier
+ *   (`courier.userId`) and the caller is neither that user nor ADMIN-tier.
+ * - `DELIVERY_TERMINAL` · 409 — the delivery is already `'delivered'` or
+ *   `'failed'`; a failed delivery is re-dispatched through `POST /deliveries`.
+ * - `INVALID_IDEMPOTENCY_KEY` · 400 — the key is not ≤200 chars of
+ *   `[A-Za-z0-9._:-]`.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — the key was used with a different body.
+ * - `IDEMPOTENCY_KEY_FAILED` · 409 — the attempt under the key failed after it
+ *   may have written proof, or the attempt lookup fenced the key; ask the
+ *   lookup, then use a new key.
+ * - `IDEMPOTENCY_IN_PROGRESS` · 409 — the same key is still running.
+ * - `IDEMPOTENCY_LOCK_CONTENTION` · 409 — the key's marker could not be
+ *   claimed; retry under the SAME key.
+ * - `INVALID_CURSOR` · 400 — a `?mine=true` `startKey` that is malformed or
+ *   names another store's partition.
+ * - `IMPERSONATION_READONLY` · 403 — the attempt lookup, under a support
+ *   session, could answer only by fencing the key (`op: 'delivery.attemptFence'`).
+ * - `INVALID_BASE64` · 400, `CONTENT_TOO_LARGE` · 413,
+ *   `UNSUPPORTED_MEDIA_TYPE` · 415 — the inline proof payload was refused
+ *   before anything was stored.
+ */
+export const DELIVERY_ERROR_CODES = [
+    'DELIVERY_NOT_FOUND',
+    'DELIVERY_NOT_ASSIGNED',
+    'DELIVERY_TERMINAL',
+    'INVALID_DELIVERY_ID',
+    'INVALID_IDEMPOTENCY_KEY',
+    'IDEMPOTENCY_KEY_REUSE',
+    'IDEMPOTENCY_KEY_FAILED',
+    'IDEMPOTENCY_IN_PROGRESS',
+    'IDEMPOTENCY_LOCK_CONTENTION',
+    'INVALID_CURSOR',
+    'IMPERSONATION_READONLY',
+    // The proof payload gate (`deliveryAttachmentValidation.ts`).
+    'INVALID_BASE64',
+    'CONTENT_TOO_LARGE',
+    'UNSUPPORTED_MEDIA_TYPE',
+];

package/package.json

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