platform-types 1.10.716 → 1.10.717

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/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.717",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",