platform-types 1.10.725 → 1.10.726

package/dist/cjs/index.js

@@ -121,5 +121,6 @@ __exportStar(require("./valuation.js"), exports);
 __exportStar(require("./webhook.js"), exports);
 __exportStar(require("./wire.js"), exports);
 __exportStar(require("./whatsapp.js"), exports);
+__exportStar(require("./workItem.js"), exports);
 __exportStar(require("./zone.js"), exports);
 __exportStar(require("./provinces.js"), exports);

package/dist/cjs/socket.js

@@ -654,6 +654,19 @@ exports.SOCKET_ACTIONS = [
      * `POST /transfers` request log should expect both actions.
      */
     'stockTransfers',
+    /**
+     * BE → the store's OPERATOR sockets on every work-item write: report (a new
+     * item, never a replay), handover, accept, resolve and correct. Carries
+     * `WorkItemFrameData` — `{ itemId, status, responsibleUserId }` and nothing
+     * else — so a receiving device REFETCHES `GET /work-items` rather than
+     * patching from the frame.
+     *
+     * ⚠️ Operator-only — `wsPostStore(..., { audience: 'operator' })`. The row
+     * carries the tenant's free-text `summary`, which is why the frame does not:
+     * an id-only refetch signal reaches every operator socket, and the read is
+     * where the role and scope gates sit.
+     */
+    'workItems',
 ];
 /** Runtime guard — narrows an untrusted string to a known action. */
 const isSocketAction = (value) => typeof value === 'string' && exports.SOCKET_ACTIONS.includes(value);

package/dist/cjs/workItem.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Work items — a minimal, durable record of an UNRESOLVED transaction outcome
+ * that someone in the store is accountable for, over the existing domain
+ * records. Not a workflow engine and not a second ledger: a work-item write
+ * never mutates the business row it points at.
+ *
+ * Phase 1 is REPORT-ONLY: the phone reports device-originated uncertainty
+ * (`POST /work-items { mode: 'report' }`) — an order create whose reply was
+ * lost, cash taken but unconfirmed, a delivery outcome it cannot see. The
+ * server does not yet open items from its own handlers.
+ *
+ * Lifecycle: `open` → `resolved` (only on an AUTHORITATIVE verdict the server
+ * re-reads from the family's own source) or `corrected` (ADMIN-tier, with a
+ * recorded note). A responsibility transfer is two acts — `handover` names the
+ * receiver, and only the receiver's `accept` moves `responsibleUserId` — each
+ * under a compare-and-swap on `version`. Accountability never moves: whoever
+ * holds an item, the store's ADMIN-tier sees every open item through
+ * `GET /work-items?scope=store`.
+ *
+ * ⚠️ `summary` is the tenant's own free text. It is stored on the row and
+ * 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_FAMILIES = [
+    'order-create',
+    'collection',
+    'delivery',
+    'invoice',
+    'receipt',
+    'service-draft',
+    'count-draft',
+];
+exports.WORK_ITEM_STATUSES = ['open', 'resolved', 'corrected'];
+exports.WORK_ITEM_AVAILABILITIES = ['supported', 'unavailable'];
+/** `committed` / `not-written` are authoritative and resolve; `pending` / `unknown` never do. */
+exports.WORK_ITEM_SOURCE_VERDICTS = ['committed', 'not-written', 'pending', 'unknown'];
+exports.WORK_ITEM_HISTORY_KINDS = ['reported', 'handover-requested', 'accepted', 'resolved', 'corrected'];
+/** The `GET /work-items` page-size ceiling. */
+exports.WORK_ITEM_PAGE_MAX = 100;
+/** Upper bound on `summary` and on a `correct` note, in characters. */
+exports.WORK_ITEM_TEXT_MAX = 500;

package/dist/index.d.ts

@@ -97,5 +97,6 @@ export * from './valuation.ts';
 export * from './webhook.ts';
 export * from './wire.ts';
 export * from './whatsapp.ts';
+export * from './workItem.ts';
 export * from './zone.ts';
 export * from './provinces.ts';

package/dist/index.js

@@ -105,5 +105,6 @@ export * from "./valuation.js";
 export * from "./webhook.js";
 export * from "./wire.js";
 export * from "./whatsapp.js";
+export * from "./workItem.js";
 export * from "./zone.js";
 export * from "./provinces.js";

package/dist/socket.d.ts

@@ -26,7 +26,7 @@
  * A client must ignore actions it does not own rather than assume it
  * receives all of them.
  */
-export declare const SOCKET_ACTIONS: readonly ["account", "appointments", "appointmentWaitlist", "attendance", "attributes", "automation-rules", "baskets", "cart", "brands", "cash", "catalogOperation", "categories", "campaigns", "customers", "customerNote", "customerAddress", "customerContact", "deliveries", "globals", "inventory", "invoices", "literals", "loyalty", "orders", "presupuestos", "products", "promotions", "segments", "returns", "rma", "templates", "services", "service-templates", "shifts", "stores", "suppliers", "supplier-invoice", "support", "surveys", "users", "warehouses", "zones", "favorites", "webhooks", "account-delete", "baskets-delete", "cart-delete", "log-delete", "notifications", "support-message", "whatsapp-order-draft", "whatsapp-order-confirmation", "payment_received", "mp_payment_status_changed", "payment_linked", "payment_unlinked", "mercadopago", "mercadopago_dynamic_qr_created", "mercadopago_static_qr_created", "mp_hook_log_appended", "mp_ipn_log_appended", "stripe", "subscription", "caea", "print", "print-order", "print-invoice", "print-product", "print-tag", "print_job_failed", "request_printers", "printers_changed", "agent_status_changed", "print_rules_changed", "printers_active", "agent_command", "maintenance", "currency_auto_updated", "drain_progress", "integration_event_appended", "userActivityRecorded", "mercadolibre_settlement_period", "customDomain", "purchaseOrders", "cycleCounts", "stockTransfers"];
+export declare const SOCKET_ACTIONS: readonly ["account", "appointments", "appointmentWaitlist", "attendance", "attributes", "automation-rules", "baskets", "cart", "brands", "cash", "catalogOperation", "categories", "campaigns", "customers", "customerNote", "customerAddress", "customerContact", "deliveries", "globals", "inventory", "invoices", "literals", "loyalty", "orders", "presupuestos", "products", "promotions", "segments", "returns", "rma", "templates", "services", "service-templates", "shifts", "stores", "suppliers", "supplier-invoice", "support", "surveys", "users", "warehouses", "zones", "favorites", "webhooks", "account-delete", "baskets-delete", "cart-delete", "log-delete", "notifications", "support-message", "whatsapp-order-draft", "whatsapp-order-confirmation", "payment_received", "mp_payment_status_changed", "payment_linked", "payment_unlinked", "mercadopago", "mercadopago_dynamic_qr_created", "mercadopago_static_qr_created", "mp_hook_log_appended", "mp_ipn_log_appended", "stripe", "subscription", "caea", "print", "print-order", "print-invoice", "print-product", "print-tag", "print_job_failed", "request_printers", "printers_changed", "agent_status_changed", "print_rules_changed", "printers_active", "agent_command", "maintenance", "currency_auto_updated", "drain_progress", "integration_event_appended", "userActivityRecorded", "mercadolibre_settlement_period", "customDomain", "purchaseOrders", "cycleCounts", "stockTransfers", "workItems"];
 /** Union of every server→client data-frame action. */
 export type SocketAction = (typeof SOCKET_ACTIONS)[number];
 /**

package/dist/socket.js

@@ -651,6 +651,19 @@ export const SOCKET_ACTIONS = [
      * `POST /transfers` request log should expect both actions.
      */
     'stockTransfers',
+    /**
+     * BE → the store's OPERATOR sockets on every work-item write: report (a new
+     * item, never a replay), handover, accept, resolve and correct. Carries
+     * `WorkItemFrameData` — `{ itemId, status, responsibleUserId }` and nothing
+     * else — so a receiving device REFETCHES `GET /work-items` rather than
+     * patching from the frame.
+     *
+     * ⚠️ Operator-only — `wsPostStore(..., { audience: 'operator' })`. The row
+     * carries the tenant's free-text `summary`, which is why the frame does not:
+     * an id-only refetch signal reaches every operator socket, and the read is
+     * where the role and scope gates sit.
+     */
+    'workItems',
 ];
 /** Runtime guard — narrows an untrusted string to a known action. */
 export const isSocketAction = (value) => typeof value === 'string' && SOCKET_ACTIONS.includes(value);

package/dist/workItem.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Work items — a minimal, durable record of an UNRESOLVED transaction outcome
+ * that someone in the store is accountable for, over the existing domain
+ * records. Not a workflow engine and not a second ledger: a work-item write
+ * never mutates the business row it points at.
+ *
+ * Phase 1 is REPORT-ONLY: the phone reports device-originated uncertainty
+ * (`POST /work-items { mode: 'report' }`) — an order create whose reply was
+ * lost, cash taken but unconfirmed, a delivery outcome it cannot see. The
+ * server does not yet open items from its own handlers.
+ *
+ * Lifecycle: `open` → `resolved` (only on an AUTHORITATIVE verdict the server
+ * re-reads from the family's own source) or `corrected` (ADMIN-tier, with a
+ * recorded note). A responsibility transfer is two acts — `handover` names the
+ * receiver, and only the receiver's `accept` moves `responsibleUserId` — each
+ * under a compare-and-swap on `version`. Accountability never moves: whoever
+ * holds an item, the store's ADMIN-tier sees every open item through
+ * `GET /work-items?scope=store`.
+ *
+ * ⚠️ `summary` is the tenant's own free text. It is stored on the row and
+ * returned to the store's operators, and is never logged.
+ */
+declare global {
+    /** One of {@link WORK_ITEM_FAMILIES} — which domain source decides the item. */
+    type WorkItemFamily = (typeof WORK_ITEM_FAMILIES)[number];
+    /** One of {@link WORK_ITEM_STATUSES}. */
+    type WorkItemStatus = (typeof WORK_ITEM_STATUSES)[number];
+    /** One of {@link WORK_ITEM_AVAILABILITIES}. */
+    type WorkItemAvailability = (typeof WORK_ITEM_AVAILABILITIES)[number];
+    /** One of {@link WORK_ITEM_SOURCE_VERDICTS}. */
+    type WorkItemSourceVerdictKind = (typeof WORK_ITEM_SOURCE_VERDICTS)[number];
+    /** One of {@link WORK_ITEM_HISTORY_KINDS}. */
+    type WorkItemHistoryKind = (typeof WORK_ITEM_HISTORY_KINDS)[number];
+    /**
+     * The exact domain ids the item points at, plus the client's attempt key.
+     *
+     * `attemptKey` is REQUIRED on every report: the order-create `attemptKey`
+     * for `order-create`, the write's `Idempotency-Key` for every other family —
+     * so a remote item matches the phone's local attempt one-to-one, and
+     * `(storeId, family, attemptKey)` is the report's idempotency key.
+     *
+     * Which ids the server reads per family when resolving:
+     * - `order-create` — `attemptKey` (the create-attempt row). Run
+     *   `POST /orders { mode: 'create-attempt' }` first: only its tombstone
+     *   makes `not-written` provable.
+     * - `collection` — `operation`, `orderId`, `attemptKey` (the write's
+     *   idempotency marker, as `POST /orders { mode: 'collection-attempt' }`).
+     * - `delivery` — `deliveryId` + `attemptKey` (the event's attempt row; run
+     *   the delivery attempt lookup first, for the same reason).
+     * - `invoice` — `invoiceId` (that invoice's own fiscal status).
+     * - `receipt`, `service-draft`, `count-draft` — `unavailable`: no write in
+     *   these families leaves evidence bound to the attempt key, so an item of
+     *   theirs closes only through an ADMIN-tier `correct`. `receiptId`,
+     *   `serviceOrderId` and `cycleCountId` are kept for the operator's context.
+     */
+    interface WorkItemSourceRef {
+        attemptKey: string;
+        orderId?: string;
+        operation?: OrderCollectionAttemptOperation;
+        deliveryId?: string;
+        invoiceId?: string;
+        receiptId?: string;
+        serviceOrderId?: string;
+        cycleCountId?: string;
+    }
+    /** A pending responsibility transfer — set by `handover`, consumed by `accept`. */
+    interface WorkItemPendingHandover {
+        fromUserId: string;
+        toUserId: string;
+        requestedBy: string;
+        requestedAt: number;
+    }
+    /**
+     * What the server read at the source when it resolved the item. Only
+     * `committed` and `not-written` resolve; `pending` and `unknown` are refused
+     * `409 WORK_ITEM_UNRESOLVED_AT_SOURCE` with this verdict as `data.verdict`.
+     * `reason` is a machine code naming what decided it (or why nothing did).
+     */
+    interface WorkItemSourceVerdict {
+        verdict: WorkItemSourceVerdictKind;
+        reason: string;
+    }
+    /** One append-only history entry. The original actor stays on the item itself. */
+    interface WorkItemHistoryEntry {
+        kind: WorkItemHistoryKind;
+        at: number;
+        byUserId: string;
+        fromUserId?: string;
+        toUserId?: string;
+        verdict?: WorkItemSourceVerdict;
+        note?: string;
+    }
+    /** One work item as the API answers it. */
+    interface WorkItem {
+        itemId: string;
+        storeId: string;
+        family: WorkItemFamily;
+        sourceRef: WorkItemSourceRef;
+        /** Tenant free text. Never logged. */
+        summary: string;
+        /** Who reported it. Never changes — a handover moves responsibility, not provenance. */
+        originalActorId: string;
+        /** Device clock (epoch ms) when the phone captured the uncertainty. Informational. */
+        capturedAt: number;
+        /** Server clock (epoch ms) when the report landed. */
+        reportedAt: number;
+        status: WorkItemStatus;
+        responsibleUserId: string;
+        pendingHandover?: WorkItemPendingHandover;
+        history: WorkItemHistoryEntry[];
+        /** Compare-and-swap token: every transition is conditioned on it and bumps it (`handover`, `accept` and `correct` also take it as `expectedVersion`). */
+        version: number;
+        resolution?: WorkItemSourceVerdict;
+        createdAt: number;
+        updatedAt: number;
+    }
+    /** `POST /work-items { mode: 'report' }` — staffToken. */
+    interface WorkItemReportRequest {
+        mode: 'report';
+        family: WorkItemFamily;
+        sourceRef: WorkItemSourceRef;
+        summary: string;
+        capturedAt: number;
+    }
+    /** `POST /work-items { mode: 'handover' }` — the responsible user or ADMIN-tier. */
+    interface WorkItemHandoverRequest {
+        mode: 'handover';
+        itemId: string;
+        toUserId: string;
+        expectedVersion: number;
+    }
+    /** `POST /work-items { mode: 'accept' }` — only the pending handover's `toUserId`. */
+    interface WorkItemAcceptRequest {
+        mode: 'accept';
+        itemId: string;
+        expectedVersion: number;
+    }
+    /** `POST /work-items { mode: 'resolve' }` — the responsible user or ADMIN-tier. */
+    interface WorkItemResolveRequest {
+        mode: 'resolve';
+        itemId: string;
+    }
+    /** `POST /work-items { mode: 'correct' }` — ADMIN-tier only; `note` is recorded. */
+    interface WorkItemCorrectRequest {
+        mode: 'correct';
+        itemId: string;
+        note: string;
+        expectedVersion: number;
+    }
+    /**
+     * `data` of a `200` from `GET /work-items?scope=mine|store|offered`.
+     *
+     * - `items` — OPEN items only, newest first. `mine`: responsible to the
+     *   caller. `offered`: a pending handover names the caller. `store`
+     *   (ADMIN-tier): every open item.
+     * - `openCount` — from a per-store counter row (`mine`/`offered`: the
+     *   caller's own responsible count), so a badge needs no page walk. Never
+     *   negative.
+     * - `availability` — EVERY family, `supported` when the server can read its
+     *   source verdict. An `unavailable` family means its items cannot be
+     *   resolved from evidence yet — never read its absence from `items` as an
+     *   all-clear.
+     *
+     * Paging sits beside `data`: `truncated` and, when a next page exists,
+     * an opaque `LastEvaluatedKey` to send back as `?startKey=`.
+     */
+    interface WorkItemListData {
+        items: WorkItem[];
+        openCount: number;
+        availability: Record<WorkItemFamily, WorkItemAvailability>;
+    }
+    /** The `workItems` socket frame's `data` — refetch, never patch from it. */
+    interface WorkItemFrameData {
+        itemId: string;
+        status: WorkItemStatus;
+        responsibleUserId: string;
+    }
+}
+export declare const WORK_ITEM_FAMILIES: readonly ["order-create", "collection", "delivery", "invoice", "receipt", "service-draft", "count-draft"];
+export declare const WORK_ITEM_STATUSES: readonly ["open", "resolved", "corrected"];
+export declare const WORK_ITEM_AVAILABILITIES: readonly ["supported", "unavailable"];
+/** `committed` / `not-written` are authoritative and resolve; `pending` / `unknown` never do. */
+export declare const WORK_ITEM_SOURCE_VERDICTS: readonly ["committed", "not-written", "pending", "unknown"];
+export declare const WORK_ITEM_HISTORY_KINDS: readonly ["reported", "handover-requested", "accepted", "resolved", "corrected"];
+/** The `GET /work-items` page-size ceiling. */
+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;

package/dist/workItem.js

@@ -0,0 +1,40 @@
+/**
+ * Work items — a minimal, durable record of an UNRESOLVED transaction outcome
+ * that someone in the store is accountable for, over the existing domain
+ * records. Not a workflow engine and not a second ledger: a work-item write
+ * never mutates the business row it points at.
+ *
+ * Phase 1 is REPORT-ONLY: the phone reports device-originated uncertainty
+ * (`POST /work-items { mode: 'report' }`) — an order create whose reply was
+ * lost, cash taken but unconfirmed, a delivery outcome it cannot see. The
+ * server does not yet open items from its own handlers.
+ *
+ * Lifecycle: `open` → `resolved` (only on an AUTHORITATIVE verdict the server
+ * re-reads from the family's own source) or `corrected` (ADMIN-tier, with a
+ * recorded note). A responsibility transfer is two acts — `handover` names the
+ * receiver, and only the receiver's `accept` moves `responsibleUserId` — each
+ * under a compare-and-swap on `version`. Accountability never moves: whoever
+ * holds an item, the store's ADMIN-tier sees every open item through
+ * `GET /work-items?scope=store`.
+ *
+ * ⚠️ `summary` is the tenant's own free text. It is stored on the row and
+ * returned to the store's operators, and is never logged.
+ */
+export const WORK_ITEM_FAMILIES = [
+    'order-create',
+    'collection',
+    'delivery',
+    'invoice',
+    'receipt',
+    'service-draft',
+    'count-draft',
+];
+export const WORK_ITEM_STATUSES = ['open', 'resolved', 'corrected'];
+export const WORK_ITEM_AVAILABILITIES = ['supported', 'unavailable'];
+/** `committed` / `not-written` are authoritative and resolve; `pending` / `unknown` never do. */
+export const WORK_ITEM_SOURCE_VERDICTS = ['committed', 'not-written', 'pending', 'unknown'];
+export const WORK_ITEM_HISTORY_KINDS = ['reported', 'handover-requested', 'accepted', 'resolved', 'corrected'];
+/** The `GET /work-items` page-size ceiling. */
+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;

package/package.json

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