platform-types 1.10.716 → 1.10.718

package/dist/auth.d.ts

@@ -326,6 +326,8 @@ declare global {
         accessToken: string;
         /** Transport-conditional exactly as `AuthUser.refreshToken` — absent on the default cookie path. */
         refreshToken?: string;
+        /** As `AuthUser.effectiveCapabilities` — the gate's own answer for the session just issued. */
+        effectiveCapabilities: UserCapability[];
     }
     /**
      * One row of `GET /auth?mode=sessions` — a storefront customer's own

package/dist/cash.d.ts

@@ -468,7 +468,11 @@ declare global {
 }
 /**
  * Refusals from the cash-shift surface — `stacks/lambdas/shifts/*.ts`
- * (`_get`, `_post`, `_patchClose`, `_postMovement`, `_patchReconcile`).
+ * (`_get`, `_post`, `_patchClose`, `_postMovement`, `_patchReconcile`) — plus
+ * the shared drawer write's own `CASH_DRAWER_BUSY`, which `POST /cash`,
+ * `POST`/`DELETE /account` and a cash return answer. A tender or seña does
+ * not: a tender's drawer collision is `SHIFT_NOT_OPEN` or `422 CURRENCY_MISMATCH`,
+ * a seña's `SHIFT_NOT_OPEN` or `409 DEPOSIT_CURRENCY_MISMATCH`.
  *
  * - `INVALID_SHIFT_ID` · 400 · `SHIFT_NOT_FOUND` · 404
  * - `SHIFT_ALREADY_OPEN` · 409 — one open shift per cashier.
@@ -489,15 +493,24 @@ declare global {
  * - `SHIFT_EVENTS_TRUNCATED` · 503 — the event log could not be read in full, so
  *   the totals behind a close or a reconcile would be computed from a partial
  *   ledger.
+ * - `CASH_DRAWER_BUSY` · 409 — emitted by the shared drawer write
+ *   (`drawerWriteRefusal`, `stacks/services/shifts.ts`), not by a `/shifts`
+ *   route: `POST /account` and `POST /cash` answer it when their transaction is
+ *   cancelled by a pure conflict on any item it writes (most often the drawer
+ *   row), as do `DELETE /account` and `POST /orders { mode: 'return' }` on a
+ *   cash leg. Nothing was written; retry the same request.
  * - `SELF_APPROVAL_FORBIDDEN` · 403 — segregation of duties: the cashier who
  *   closed a shift cannot reconcile it.
  * - `INVALID_DENOMINATION` · 400 · `INVALID_CURSOR` · 400
+ * - `WAREHOUSE_NOT_FOUND` · 404 — `GET /shifts?warehouseId=` naming a depósito
+ *   the store does not have (`resolveReportWarehouseFilter`).
  * - `ROLE_FORBIDDEN` · 403 · `VALIDATION_FAILED` · 400
  *
  * ⚠️ Cross-cutting refusals are NOT repeated here — check `GATING_ERROR_CODES`
- * as well.
+ * as well, and `TERMINAL_ELEVATION_ERROR_CODES` for a money-out movement's PIN
+ * elevation.
  */
-export declare const SHIFT_ERROR_CODES: readonly ["INVALID_SHIFT_ID", "SHIFT_NOT_FOUND", "SHIFT_ALREADY_OPEN", "SHIFT_NOT_OPEN", "SHIFT_NOT_CLOSED", "SHIFT_OWNER_MISMATCH", "CURRENCY_MISMATCH", "BUCKET_COUNTS_INVALID", "BUCKET_REVIEW_INVALID", "BUCKET_COUNT_MISSING", "SHIFT_CHANGED", "SHIFT_EVENTS_TRUNCATED", "SELF_APPROVAL_FORBIDDEN", "INVALID_DENOMINATION", "INVALID_CURSOR", "ROLE_FORBIDDEN", "VALIDATION_FAILED"];
+export declare const SHIFT_ERROR_CODES: readonly ["INVALID_SHIFT_ID", "SHIFT_NOT_FOUND", "SHIFT_ALREADY_OPEN", "SHIFT_NOT_OPEN", "SHIFT_NOT_CLOSED", "SHIFT_OWNER_MISMATCH", "CURRENCY_MISMATCH", "BUCKET_COUNTS_INVALID", "BUCKET_REVIEW_INVALID", "BUCKET_COUNT_MISSING", "SHIFT_CHANGED", "SHIFT_EVENTS_TRUNCATED", "CASH_DRAWER_BUSY", "SELF_APPROVAL_FORBIDDEN", "INVALID_DENOMINATION", "INVALID_CURSOR", "WAREHOUSE_NOT_FOUND", "ROLE_FORBIDDEN", "VALIDATION_FAILED"];
 export type ShiftErrorCode = (typeof SHIFT_ERROR_CODES)[number];
 /**
  * Where a {@link ShiftMethodTotal}'s `label` came from.

package/dist/cash.js

@@ -1,6 +1,10 @@
 /**
  * Refusals from the cash-shift surface — `stacks/lambdas/shifts/*.ts`
- * (`_get`, `_post`, `_patchClose`, `_postMovement`, `_patchReconcile`).
+ * (`_get`, `_post`, `_patchClose`, `_postMovement`, `_patchReconcile`) — plus
+ * the shared drawer write's own `CASH_DRAWER_BUSY`, which `POST /cash`,
+ * `POST`/`DELETE /account` and a cash return answer. A tender or seña does
+ * not: a tender's drawer collision is `SHIFT_NOT_OPEN` or `422 CURRENCY_MISMATCH`,
+ * a seña's `SHIFT_NOT_OPEN` or `409 DEPOSIT_CURRENCY_MISMATCH`.
  *
  * - `INVALID_SHIFT_ID` · 400 · `SHIFT_NOT_FOUND` · 404
  * - `SHIFT_ALREADY_OPEN` · 409 — one open shift per cashier.
@@ -21,13 +25,22 @@
  * - `SHIFT_EVENTS_TRUNCATED` · 503 — the event log could not be read in full, so
  *   the totals behind a close or a reconcile would be computed from a partial
  *   ledger.
+ * - `CASH_DRAWER_BUSY` · 409 — emitted by the shared drawer write
+ *   (`drawerWriteRefusal`, `stacks/services/shifts.ts`), not by a `/shifts`
+ *   route: `POST /account` and `POST /cash` answer it when their transaction is
+ *   cancelled by a pure conflict on any item it writes (most often the drawer
+ *   row), as do `DELETE /account` and `POST /orders { mode: 'return' }` on a
+ *   cash leg. Nothing was written; retry the same request.
  * - `SELF_APPROVAL_FORBIDDEN` · 403 — segregation of duties: the cashier who
  *   closed a shift cannot reconcile it.
  * - `INVALID_DENOMINATION` · 400 · `INVALID_CURSOR` · 400
+ * - `WAREHOUSE_NOT_FOUND` · 404 — `GET /shifts?warehouseId=` naming a depósito
+ *   the store does not have (`resolveReportWarehouseFilter`).
  * - `ROLE_FORBIDDEN` · 403 · `VALIDATION_FAILED` · 400
  *
  * ⚠️ Cross-cutting refusals are NOT repeated here — check `GATING_ERROR_CODES`
- * as well.
+ * as well, and `TERMINAL_ELEVATION_ERROR_CODES` for a money-out movement's PIN
+ * elevation.
  */
 export const SHIFT_ERROR_CODES = [
     'INVALID_SHIFT_ID',
@@ -42,9 +55,11 @@ export const SHIFT_ERROR_CODES = [
     'BUCKET_COUNT_MISSING',
     'SHIFT_CHANGED',
     'SHIFT_EVENTS_TRUNCATED',
+    'CASH_DRAWER_BUSY',
     'SELF_APPROVAL_FORBIDDEN',
     'INVALID_DENOMINATION',
     'INVALID_CURSOR',
+    'WAREHOUSE_NOT_FOUND',
     'ROLE_FORBIDDEN',
     'VALIDATION_FAILED',
 ];

package/dist/cjs/cash.js

@@ -3,7 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.METHOD_LABEL_SOURCES = exports.SHIFT_ERROR_CODES = void 0;
 /**
  * Refusals from the cash-shift surface — `stacks/lambdas/shifts/*.ts`
- * (`_get`, `_post`, `_patchClose`, `_postMovement`, `_patchReconcile`).
+ * (`_get`, `_post`, `_patchClose`, `_postMovement`, `_patchReconcile`) — plus
+ * the shared drawer write's own `CASH_DRAWER_BUSY`, which `POST /cash`,
+ * `POST`/`DELETE /account` and a cash return answer. A tender or seña does
+ * not: a tender's drawer collision is `SHIFT_NOT_OPEN` or `422 CURRENCY_MISMATCH`,
+ * a seña's `SHIFT_NOT_OPEN` or `409 DEPOSIT_CURRENCY_MISMATCH`.
  *
  * - `INVALID_SHIFT_ID` · 400 · `SHIFT_NOT_FOUND` · 404
  * - `SHIFT_ALREADY_OPEN` · 409 — one open shift per cashier.
@@ -24,13 +28,22 @@ exports.METHOD_LABEL_SOURCES = exports.SHIFT_ERROR_CODES = void 0;
  * - `SHIFT_EVENTS_TRUNCATED` · 503 — the event log could not be read in full, so
  *   the totals behind a close or a reconcile would be computed from a partial
  *   ledger.
+ * - `CASH_DRAWER_BUSY` · 409 — emitted by the shared drawer write
+ *   (`drawerWriteRefusal`, `stacks/services/shifts.ts`), not by a `/shifts`
+ *   route: `POST /account` and `POST /cash` answer it when their transaction is
+ *   cancelled by a pure conflict on any item it writes (most often the drawer
+ *   row), as do `DELETE /account` and `POST /orders { mode: 'return' }` on a
+ *   cash leg. Nothing was written; retry the same request.
  * - `SELF_APPROVAL_FORBIDDEN` · 403 — segregation of duties: the cashier who
  *   closed a shift cannot reconcile it.
  * - `INVALID_DENOMINATION` · 400 · `INVALID_CURSOR` · 400
+ * - `WAREHOUSE_NOT_FOUND` · 404 — `GET /shifts?warehouseId=` naming a depósito
+ *   the store does not have (`resolveReportWarehouseFilter`).
  * - `ROLE_FORBIDDEN` · 403 · `VALIDATION_FAILED` · 400
  *
  * ⚠️ Cross-cutting refusals are NOT repeated here — check `GATING_ERROR_CODES`
- * as well.
+ * as well, and `TERMINAL_ELEVATION_ERROR_CODES` for a money-out movement's PIN
+ * elevation.
  */
 exports.SHIFT_ERROR_CODES = [
     'INVALID_SHIFT_ID',
@@ -45,9 +58,11 @@ exports.SHIFT_ERROR_CODES = [
     'BUCKET_COUNT_MISSING',
     'SHIFT_CHANGED',
     'SHIFT_EVENTS_TRUNCATED',
+    'CASH_DRAWER_BUSY',
     'SELF_APPROVAL_FORBIDDEN',
     'INVALID_DENOMINATION',
     'INVALID_CURSOR',
+    'WAREHOUSE_NOT_FOUND',
     'ROLE_FORBIDDEN',
     'VALIDATION_FAILED',
 ];

package/dist/order.d.ts

@@ -1867,6 +1867,39 @@ declare global {
          */
         cancellation?: OrderCancellability;
     }
+    /**
+     * `POST /orders { mode: 'tender' }` — ring one or more tender legs against an
+     * EXISTING order (the append counterpart of the create leg's
+     * {@link CreateOrderRequest.tenders}). Any operator but PRINTER or ACCOUNTANT
+     * (`403 ROLE_FORBIDDEN`).
+     *
+     * `shiftId` attributes the legs to a drawer. An EXPLICIT value must be the
+     * caller's own OPEN shift — anything else is `409 SHIFT_NOT_AVAILABLE`, never
+     * a silent drop. OMITTED resolves the caller's own open drawer; with none, a
+     * cash leg lands on the store's default drawer. At commit the drawer is
+     * re-asserted: one that closed mid-request is `409 SHIFT_NOT_OPEN`, one that
+     * did not declare the order's currency `422 CURRENCY_MISMATCH`.
+     *
+     * The opt-in `Idempotency-Key` and the lost-reply recovery through
+     * `mode: 'collection-attempt'` follow the money-write rule documented on
+     * {@link ORDER_ERROR_CODES} (and {@link OrderCollectionAttemptLookupRequest});
+     * it is not restated here. Every refusal specific to this mode is in that
+     * tuple; a body the schema rejects is `400 VALIDATION_FAILED`, and the
+     * cross-cutting refusals (`ROLE_FORBIDDEN`, `IMPERSONATION_READONLY`, …) are
+     * in `GATING_ERROR_CODES`.
+     *
+     * Tied to its validator (`tenderModeSchema`, `stacks/lambdas/orders/_tender.ts`)
+     * by `AssertOrderTenderRequestMatchesSchema` — `mode` is the router's key.
+     */
+    interface OrderTenderRequest {
+        mode: 'tender';
+        /** `ORD` followed by 6–10 digits. */
+        orderId: string;
+        /** RAW legs — see {@link TenderLegInput}. */
+        tenders: TenderLegInput[];
+        /** 1–100 chars; the caller's own OPEN shift. Omit to use the caller's open drawer. */
+        shiftId?: string;
+    }
     /**
      * `POST /orders { mode: 'deposit' }` — record a SEÑA (a sales deposit) on an
      * existing, undelivered order, as one {@link OrderTender} leg carrying
@@ -1925,7 +1958,7 @@ declare global {
         change?: number;
         /** Required, never defaulted. `true` needs an authorized factura on the order first. */
         freezesPrice: boolean;
-        /** Same semantics as `mode: 'tender'`'s. */
+        /** Same semantics as {@link OrderTenderRequest.shiftId}. */
         shiftId?: string;
     }
     /**

package/dist/user.d.ts

@@ -66,8 +66,16 @@ declare global {
      * consumer that models the row as `Omit<User, 'totp'>` throws away the only
      * signal that 2FA is enrolled. Unlike an auth body's `AuthUserTotp`, it
      * carries no `recoveryCodesRemaining`.
+     *
+     * `effectiveCapabilities` is present on the caller's OWN row only — the same
+     * answer as {@link AuthUser.effectiveCapabilities}, resolved from this
+     * request's token roles — and absent on every colleague's row, on the
+     * `POST /users` echo and on the `users` socket frame. A client keeps the list
+     * from its auth body or its own row here; a frame that omits it changes nothing.
      */
-    type PublicUserRow = Omit<User, 'accessToken' | 'search' | 'login' | 'photoData' | 'removePhotoURL' | 'warnings'>;
+    type PublicUserRow = Omit<User, 'accessToken' | 'search' | 'login' | 'photoData' | 'removePhotoURL' | 'warnings'> & {
+        effectiveCapabilities?: UserCapability[];
+    };
     /**
      * Write shape for user create/update — carries the transient photo controls
      * and the plaintext password.
@@ -345,7 +353,31 @@ declare global {
          * Absent/false means no, for a plain USER only.
          */
         percepciones?: boolean;
+        /**
+         * May issue a nota de crédito — `POST /invoices` with `cbte_numero`, and
+         * the retry of a return's credit note (`POST /orders {mode:'return-credit-note'}`).
+         *
+         * ⚠️ **Role-implied** (ADMIN, SUPERVISOR, MANAGER hold it without the flag),
+         * for the reason `percepciones` gives: every elevated operator already issues
+         * NCs, and the granted class would withdraw that on deploy. A plain USER needs
+         * `creditNote: true` on their STORED row together with the server-stamped
+         * grant marker an admin's `POST /users` writes when it turns the flag on; a
+         * flag stored without that marker grants nothing, and nothing in a request
+         * grants it.
+         * Routine factura issuance is NOT gated by it.
+         *
+         * A client never derives this from `roles` — it reads
+         * `AuthUser.effectiveCapabilities`. Absent/false means no, for a plain USER only.
+         */
+        creditNote?: boolean;
     };
+    /**
+     * A key the server's capability gate decides — every `UserPermissions` key
+     * but the reserved, unread `accountant`. A refusal names one in
+     * `403 CAPABILITY_REQUIRED`'s `data.capability`, and
+     * `AuthUser.effectiveCapabilities` lists the ones a session holds.
+     */
+    type UserCapability = Exclude<keyof UserPermissions, 'accountant'>;
     /**
      * Wire error codes for the paths that create or update a USER row:
      * `POST /users` (create AND update — one handler serves both) and
@@ -389,6 +421,24 @@ declare global {
          * absent `totp` means the user never enrolled.
          */
         totp?: AuthUserTotp;
+        /**
+         * The capabilities this session holds, resolved by the SAME server function
+         * that gates each request (`@helpers/capabilityGate`), from the minted
+         * token's roles and the stored `permissions`. Clients read it —
+         * `effectiveCapabilities.includes('creditNote')` — and never compute it
+         * from `roles`, so the role-implied/granted split stays a server decision.
+         *
+         * ⚠️ A snapshot at token issue: a grant changed afterwards is enforced on
+         * the next request at once, but shows here only on the next refresh. A
+         * `403 CAPABILITY_REQUIRED` is the authoritative answer.
+         *
+         * PRINTER and ACCOUNTANT claims carry `[]`: neither is an operator acting on
+         * the store's authority, and the credit-note routes (`POST /invoices` with
+         * `cbte_numero`, the return credit-note retry) refuse them by role before
+         * consulting it. Not every capability-gated route does: `POST /cash` reads a
+         * PRINTER's stored flag.
+         */
+        effectiveCapabilities: UserCapability[];
         /**
          * ⚠️ Delivered in the body ONLY under the body refresh transport — the
          * native-mobile opt-in. The DEFAULT is cookie transport, where the token

package/package.json

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