@lessly/sdk-app 61.0.2 → 61.2.0

package/dist/react/index.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+var react = require('react');
+
+// src/react/index.ts
+function useAccess(app) {
+  const { access } = app;
+  const subscribe = react.useCallback((cb) => access.subscribe(cb), [access]);
+  const getState = react.useCallback(() => access.state, [access]);
+  const state = react.useSyncExternalStore(subscribe, getState, getState);
+  react.useEffect(() => {
+    void access.load().catch(() => {
+    });
+  }, [access]);
+  const reload = react.useCallback(() => {
+    access.invalidate();
+    return access.load();
+  }, [access]);
+  return { state, role: access.role, access, reload };
+}
+function useCan(app, op) {
+  const { state, access } = useAccess(app);
+  return state === "ready" && access.can(op);
+}
+
+exports.useAccess = useAccess;
+exports.useCan = useCan;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/react/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/index.ts"],"names":["useCallback","useSyncExternalStore","useEffect"],"mappings":";;;;;AA4BO,SAAS,UAAU,GAAA,EAA+B;AACvD,EAAA,MAAM,EAAE,QAAO,GAAI,GAAA;AACnB,EAAA,MAAM,SAAA,GAAYA,iBAAA,CAAY,CAAC,EAAA,KAAmB,MAAA,CAAO,UAAU,EAAE,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AAGhF,EAAA,MAAM,WAAWA,iBAAA,CAAY,MAAM,OAAO,KAAA,EAAO,CAAC,MAAM,CAAC,CAAA;AACzD,EAAA,MAAM,KAAA,GAAQC,0BAAA,CAAqB,SAAA,EAAW,QAAA,EAAU,QAAQ,CAAA;AAEhE,EAAAC,eAAA,CAAU,MAAM;AAId,IAAA,KAAK,MAAA,CAAO,IAAA,EAAK,CAAE,KAAA,CAAM,MAAM;AAAA,IAAC,CAAC,CAAA;AAAA,EACnC,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AAEX,EAAA,MAAM,MAAA,GAASF,kBAAY,MAAM;AAC/B,IAAA,MAAA,CAAO,UAAA,EAAW;AAClB,IAAA,OAAO,OAAO,IAAA,EAAK;AAAA,EACrB,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AAEX,EAAA,OAAO,EAAE,KAAA,EAAO,IAAA,EAAM,MAAA,CAAO,IAAA,EAAM,QAAQ,MAAA,EAAO;AACpD;AASO,SAAS,MAAA,CAAO,KAAc,EAAA,EAAiC;AACpE,EAAA,MAAM,EAAE,KAAA,EAAO,MAAA,EAAO,GAAI,UAAU,GAAG,CAAA;AACvC,EAAA,OAAO,KAAA,KAAU,OAAA,IAAW,MAAA,CAAO,GAAA,CAAI,EAAE,CAAA;AAC3C","file":"index.cjs","sourcesContent":["import { useCallback, useEffect, useSyncExternalStore } from 'react';\nimport type { Access, AccessApi, AccessState } from '../runtime/access';\nimport type { Operation } from '../runtime/types';\n\n/**\n * The only thing these hooks need from a client — so a test double is one object literal, and\n * (deliberately) no React type appears in any exported signature: `react` is an OPTIONAL peer,\n * so the published declarations must typecheck for a consumer who has not installed it.\n */\nexport interface AppLike {\n  readonly access: AccessApi;\n}\n\nexport interface UseAccessResult {\n  state: AccessState;\n  role: string | undefined;\n  access: AccessApi;\n  reload: () => Promise<Access>;\n}\n\n/**\n * Subscribe a component to the client's access snapshot, loading it once on mount.\n *\n * `useSyncExternalStore` rather than `useState` + an effect: the snapshot lives outside React\n * (several components share one `AccessApi`), and this is the hook that is safe against tearing\n * under concurrent rendering. `load()` is de-duplicated inside `createAccess`, so every component\n * may call this without coordinating — two components produce one request.\n */\nexport function useAccess(app: AppLike): UseAccessResult {\n  const { access } = app;\n  const subscribe = useCallback((cb: () => void) => access.subscribe(cb), [access]);\n  // Server snapshot is the same getter: there is nothing to hydrate, an unloaded AccessApi\n  // reports 'idle' on both sides.\n  const getState = useCallback(() => access.state, [access]);\n  const state = useSyncExternalStore(subscribe, getState, getState);\n\n  useEffect(() => {\n    // The rejection is already reflected in `state === 'error'`; swallowing it here only stops an\n    // unhandled rejection from reaching the page. A caller who wants the error awaits load()\n    // (or reload()) itself.\n    void access.load().catch(() => {});\n  }, [access]);\n\n  const reload = useCallback(() => {\n    access.invalidate();\n    return access.load();\n  }, [access]);\n\n  return { state, role: access.role, access, reload };\n}\n\n/**\n * True iff the caller is PREDICTED to be allowed to perform `op`. False until the snapshot is\n * ready — so a control wired to this starts disabled and enables itself, never the reverse.\n *\n * Loads on mount through `useAccess`, so a component may use it without the App having called\n * `load()` anywhere. This is a hint for the UI, never authorisation: see APP-012.\n */\nexport function useCan(app: AppLike, op: Operation | string): boolean {\n  const { state, access } = useAccess(app);\n  return state === 'ready' && access.can(op);\n}\n"]}

package/dist/react/index.d.cts

@@ -0,0 +1 @@
+export * from '../_types/react/index.js';

package/dist/react/index.d.ts

@@ -0,0 +1 @@
+export * from '../_types/react/index.js';

package/dist/react/index.js

@@ -0,0 +1,26 @@
+import { useCallback, useSyncExternalStore, useEffect } from 'react';
+
+// src/react/index.ts
+function useAccess(app) {
+  const { access } = app;
+  const subscribe = useCallback((cb) => access.subscribe(cb), [access]);
+  const getState = useCallback(() => access.state, [access]);
+  const state = useSyncExternalStore(subscribe, getState, getState);
+  useEffect(() => {
+    void access.load().catch(() => {
+    });
+  }, [access]);
+  const reload = useCallback(() => {
+    access.invalidate();
+    return access.load();
+  }, [access]);
+  return { state, role: access.role, access, reload };
+}
+function useCan(app, op) {
+  const { state, access } = useAccess(app);
+  return state === "ready" && access.can(op);
+}
+
+export { useAccess, useCan };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/index.ts"],"names":[],"mappings":";;;AA4BO,SAAS,UAAU,GAAA,EAA+B;AACvD,EAAA,MAAM,EAAE,QAAO,GAAI,GAAA;AACnB,EAAA,MAAM,SAAA,GAAY,WAAA,CAAY,CAAC,EAAA,KAAmB,MAAA,CAAO,UAAU,EAAE,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AAGhF,EAAA,MAAM,WAAW,WAAA,CAAY,MAAM,OAAO,KAAA,EAAO,CAAC,MAAM,CAAC,CAAA;AACzD,EAAA,MAAM,KAAA,GAAQ,oBAAA,CAAqB,SAAA,EAAW,QAAA,EAAU,QAAQ,CAAA;AAEhE,EAAA,SAAA,CAAU,MAAM;AAId,IAAA,KAAK,MAAA,CAAO,IAAA,EAAK,CAAE,KAAA,CAAM,MAAM;AAAA,IAAC,CAAC,CAAA;AAAA,EACnC,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AAEX,EAAA,MAAM,MAAA,GAAS,YAAY,MAAM;AAC/B,IAAA,MAAA,CAAO,UAAA,EAAW;AAClB,IAAA,OAAO,OAAO,IAAA,EAAK;AAAA,EACrB,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AAEX,EAAA,OAAO,EAAE,KAAA,EAAO,IAAA,EAAM,MAAA,CAAO,IAAA,EAAM,QAAQ,MAAA,EAAO;AACpD;AASO,SAAS,MAAA,CAAO,KAAc,EAAA,EAAiC;AACpE,EAAA,MAAM,EAAE,KAAA,EAAO,MAAA,EAAO,GAAI,UAAU,GAAG,CAAA;AACvC,EAAA,OAAO,KAAA,KAAU,OAAA,IAAW,MAAA,CAAO,GAAA,CAAI,EAAE,CAAA;AAC3C","file":"index.js","sourcesContent":["import { useCallback, useEffect, useSyncExternalStore } from 'react';\nimport type { Access, AccessApi, AccessState } from '../runtime/access';\nimport type { Operation } from '../runtime/types';\n\n/**\n * The only thing these hooks need from a client — so a test double is one object literal, and\n * (deliberately) no React type appears in any exported signature: `react` is an OPTIONAL peer,\n * so the published declarations must typecheck for a consumer who has not installed it.\n */\nexport interface AppLike {\n  readonly access: AccessApi;\n}\n\nexport interface UseAccessResult {\n  state: AccessState;\n  role: string | undefined;\n  access: AccessApi;\n  reload: () => Promise<Access>;\n}\n\n/**\n * Subscribe a component to the client's access snapshot, loading it once on mount.\n *\n * `useSyncExternalStore` rather than `useState` + an effect: the snapshot lives outside React\n * (several components share one `AccessApi`), and this is the hook that is safe against tearing\n * under concurrent rendering. `load()` is de-duplicated inside `createAccess`, so every component\n * may call this without coordinating — two components produce one request.\n */\nexport function useAccess(app: AppLike): UseAccessResult {\n  const { access } = app;\n  const subscribe = useCallback((cb: () => void) => access.subscribe(cb), [access]);\n  // Server snapshot is the same getter: there is nothing to hydrate, an unloaded AccessApi\n  // reports 'idle' on both sides.\n  const getState = useCallback(() => access.state, [access]);\n  const state = useSyncExternalStore(subscribe, getState, getState);\n\n  useEffect(() => {\n    // The rejection is already reflected in `state === 'error'`; swallowing it here only stops an\n    // unhandled rejection from reaching the page. A caller who wants the error awaits load()\n    // (or reload()) itself.\n    void access.load().catch(() => {});\n  }, [access]);\n\n  const reload = useCallback(() => {\n    access.invalidate();\n    return access.load();\n  }, [access]);\n\n  return { state, role: access.role, access, reload };\n}\n\n/**\n * True iff the caller is PREDICTED to be allowed to perform `op`. False until the snapshot is\n * ready — so a control wired to this starts disabled and enables itself, never the reverse.\n *\n * Loads on mount through `useAccess`, so a component may use it without the App having called\n * `load()` anywhere. This is a hint for the UI, never authorisation: see APP-012.\n */\nexport function useCan(app: AppLike, op: Operation | string): boolean {\n  const { state, access } = useAccess(app);\n  return state === 'ready' && access.can(op);\n}\n"]}

package/docs/README.md

@@ -73,6 +73,7 @@ you need to touch it directly.
 | `rules.md` | Always — normative `APP-*` rules. Read this first, before writing any code. |
 | `recipes/sdk-usage.md` | You need to call the platform API: creating the SDK client, handling `LesslyApiError`, using the generated `*QueryOptions`/`*MutationOptions` factories. |
 | `recipes/federation.md` | You're touching the Module Federation setup: shared singletons, the dual-mode build, or the dual-mode CSS graph (the federation vs standalone stylesheets). |
+| `recipes/access.md` | You're gating UI on the caller's permissions: `app.access`, `useCan`, and rendering a 403 as an empty state rather than an error (APP-012). |
 | `recipes/local-dev.md` | You're running the app locally: the dev proxy, device-code login, `.env.local`, or composing your app under a local shell. |
 
 ## Keeping this guide current

package/docs/recipes/access.md

@@ -0,0 +1,177 @@
+# Recipe: reflecting the caller's access in the UI
+
+Some of your users cannot do some of the things your App offers. This recipe
+shows how to grey out those controls and how to render the refusal you will
+still occasionally get — without ever making your App the authority on who is
+allowed to do what.
+
+**The one rule everything here rests on:** `can()` is a *prediction*, the server
+is the authority. See APP-012 in `../rules.md`.
+
+---
+
+## What `app.access` is
+
+Every client from `createLesslyApp` carries an `access` object:
+
+```ts
+import { createLesslyApp } from '@lessly/sdk-app';
+
+const app = createLesslyApp({ baseUrl: '/api', productId });
+
+await app.access.load();          // one GET; cached; concurrent calls share it
+app.access.role;                  // 'owner' | 'admin' | 'member' | a custom role name
+app.access.state;                 // 'idle' | 'loading' | 'ready' | 'error'
+app.access.can('mail_domain_create');   // boolean, synchronous
+app.access.invalidate();          // drop the cache; the next load() refetches
+app.access.subscribe(() => {});   // fires on every state change
+```
+
+`load()` fetches the caller's own membership of the active product — their role
+and their allow/deny grant patterns — and `can()` answers from that snapshot
+using the *same matcher the gateway uses to decide*. That is the only reason a
+client-side prediction is worth anything.
+
+`can()` is **false whenever the snapshot is not ready**: before `load()`, while
+it is in flight, after a failure, and after `invalidate()`. So anything you
+render from it must start in the disabled state and enable itself — never the
+reverse. A control that starts enabled and greys out a moment later is worse
+than one that never greyed out at all.
+
+You can pass either a tool id or a generated method, which carries its own
+identity:
+
+```ts
+app.access.can('mail_domain_create');   // a tool id
+app.access.can(app.mail.domain.create); // the method itself — no id to keep in sync
+```
+
+Prefer the second form. The accessor path is a lossy view of the tool id (a
+hyphenated resource joins several id segments), so a hand-written string can
+drift from the method it is meant to describe; the method cannot.
+
+---
+
+## 1. Load once at app mount
+
+```tsx
+// src/App.tsx
+import { useEffect } from 'react';
+import { createLesslyApp } from '@lessly/sdk-app';
+
+export default function App({ productId }: { productId: string }) {
+  const app = useMemo(() => createLesslyApp({ baseUrl: '/api', productId }), [productId]);
+
+  useEffect(() => {
+    // Fire and forget: a failure is reflected in app.access.state, and every consumer of
+    // can() is already fail-closed.
+    void app.access.load().catch(() => {});
+  }, [app]);
+
+  return <Routes app={app} />;
+}
+```
+
+You do not have to do this. `useAccess`/`useCan` load on mount themselves, and
+`load()` is de-duplicated inside the client — ten components mounting at once
+produce **one** request. Loading at the root is just the cheapest way to have
+the snapshot ready before the first screen paints.
+
+Call `app.access.invalidate()` after anything that can change the caller's own
+grants (they accepted an invitation, an admin changed their role in a settings
+screen you own). Nothing else invalidates it: the snapshot is deliberately not
+refetched on a timer.
+
+---
+
+## 2. `useCan` on primary actions — disable, don't hide
+
+```tsx
+import { useCan } from '@lessly/sdk-app/react';
+
+function AddDomainButton({ app, onClick }: { app: App; onClick: () => void }) {
+  const canCreate = useCan(app, app.mail.domain.create);
+
+  return (
+    <button
+      onClick={onClick}
+      disabled={!canCreate}
+      title={canCreate ? undefined : 'Your role cannot add domains. Ask an admin of this product.'}
+    >
+      Add domain
+    </button>
+  );
+}
+```
+
+**Disable, with a hint. Do not hide.** A user who cannot see the button cannot
+tell their admin which permission they are missing — they file a "the app is
+broken" ticket instead, and the admin who could have fixed it in ten seconds
+never hears about it. The greyed-out control with a one-line reason *is* the
+support channel.
+
+`useAccess` gives you the same information plus the role, for the cases where
+one flag is not enough:
+
+```tsx
+const { state, role, reload } = useAccess(app);
+
+if (state === 'loading') return <Spinner />;
+if (state === 'error') return <p>Could not load your permissions. <button onClick={reload}>Retry</button></p>;
+```
+
+React is an **optional peer** of this package: `@lessly/sdk-app/react` is only
+loaded if you import it, and installing the SDK does not pull React in.
+
+---
+
+## 3. `isAccessDenied` in the shared query state — a neutral empty state
+
+A prediction is not a guarantee, so keep handling the real refusal. Grants can
+change between the load and the click, and a screen can always be reached
+before the snapshot is.
+
+```tsx
+import { isAccessDenied } from '@lessly/sdk-app';
+import { useQuery } from '@tanstack/react-query';
+import { mailDomainListQueryOptions } from '@lessly/sdk-app/mail';
+
+function DomainList({ app }: { app: App }) {
+  const { data, error, isPending } = useQuery(mailDomainListQueryOptions(app, {}));
+
+  if (isPending) return <Spinner />;
+
+  // A permission boundary is a NORMAL condition, not a failure of your App.
+  if (isAccessDenied(error)) {
+    return <EmptyState title="You don't have access to domains" body="Ask an admin of this product to grant it." />;
+  }
+
+  if (error) return <ErrorState error={error} />;   // red, retryable — real failures only
+
+  return <Table rows={data.domains} />;
+}
+```
+
+Put that branch in your shared query-state component once, rather than in every
+screen. `isAccessDenied` is true for exactly the three gateway codes that mean
+*the caller's access was the reason* — `role_denied`,
+`operation_uncatalogued`, `no_tool_permission` — and false for every other 403.
+A `tenant_blocked` 403 is not a permission problem and must not be rendered as
+one: it sends the user to an admin who can do nothing about it.
+
+**Never render an access denial in red.** A permission boundary is expected,
+frequent and not the user's mistake. Painting it as a crash teaches people to
+ignore the colour you need for real failures.
+
+---
+
+## What not to do
+
+| Don't | Why |
+| --- | --- |
+| Skip the call because `can()` returned false | The snapshot can be stale or simply not loaded. Let the server answer; handle the 403. |
+| Treat `can() === true` as authorisation | It is a prediction. The gateway may still refuse, and only the gateway's answer is a fact. |
+| Drop the `isAccessDenied` branch because every button is gated | A screen can be deep-linked, and grants change mid-session. |
+| Hide controls the caller cannot use | Makes the missing permission unreportable. Disable with a reason instead. |
+| Rebuild a tool id from the accessor path | The path is a lossy view of the id. Pass the method: `app.mail.domain.create`. |
+| Poll `load()` on a timer | The snapshot changes when a role changes; call `invalidate()` then, and only then. |

package/docs/rules.md

@@ -331,3 +331,36 @@ validates the top-level surface and `nav.icon` only; it neither rejects nor
 warns on `nav.sections`, and it will not catch a malformed one. The platform's
 registration validation is the authority — a menu that lints clean locally can
 still fail registration.
+
+### APP-012 (SHOULD) — Reflect access in the UI, but never enforce it there
+
+An App SHOULD reflect the caller's access in its UI: **disable, with a reason**
+(not hide) a primary action the caller cannot perform, using `useCan` from
+`@lessly/sdk-app/react` or `app.access.can()` directly, and render a 403 that
+`isAccessDenied()` recognises as a **neutral empty state** rather than an error.
+
+An App MUST NOT treat that prediction as enforcement. `can()` answers from a
+snapshot fetched once from the `organization_product_me` tool; the gateway is
+the only authority, grants can change between the load and the click, and the
+prediction is `false` for a caller whose snapshot simply has not loaded yet.
+Concretely: never skip a call because `can()` returned false, never present
+`can() === true` to the user as authorisation, and never drop the
+`isAccessDenied` branch from a screen because every button on it is gated.
+
+Two failure modes are worth naming, because both ship regularly:
+
+- **Hiding rather than disabling.** A user who cannot see the button cannot ask
+  their admin for the permission; they report the App as broken instead, and
+  the admin who could have granted it in seconds never hears about it.
+- **Painting a denial red.** A permission boundary is a normal, expected
+  condition and not the user's mistake. Rendering it as a crash trains people
+  to ignore the colour reserved for real failures. `isAccessDenied()` is true
+  for exactly the three gateway codes that mean the caller's access was the
+  reason (`role_denied`, `operation_uncatalogued`, `no_tool_permission`) and
+  false for every other 403 — a `tenant_blocked` is not a permission problem.
+
+Pass the generated method rather than a hand-written tool id
+(`app.access.can(app.mail.domain.create)`): the accessor path is a lossy view
+of the tool id, so a literal string can silently drift from the call it gates.
+
+See `recipes/access.md` for the load-once pattern and the empty-state shape.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessly/sdk-app",
-  "version": "61.0.2",
+  "version": "61.2.0",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -27,13 +27,26 @@
     "test": "vitest run"
   },
   "devDependencies": {
+    "@testing-library/react": "^16.3.3",
     "@types/node": "^20.0.0",
+    "@types/react": "^18.3.31",
+    "jsdom": "^25.0.1",
     "json-schema-to-typescript": "^15.0.3",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "tsup": "^8.3.0",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"
   },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "exports": {
     ".": {
       "import": {
@@ -45,6 +58,16 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./react": {
+      "import": {
+        "types": "./dist/react/index.d.ts",
+        "default": "./dist/react/index.js"
+      },
+      "require": {
+        "types": "./dist/react/index.d.cts",
+        "default": "./dist/react/index.cjs"
+      }
+    },
     "./analytics": {
       "import": {
         "types": "./dist/analytics/index.d.ts",