@lessly/sdk-app 61.0.2 → 61.2.0

package/dist/_types/index.d.ts

@@ -1,7 +1,8 @@
 export { createLesslyApp } from './runtime/createLesslyApp.js';
 export type { LesslyClientBase } from './runtime/createLesslyApp.js';
 export { connectStream } from './runtime/connectStream.js';
-export { LesslyApiError } from './runtime/errors.js';
+export { LesslyApiError, isAccessDenied } from './runtime/errors.js';
 export type { LesslyAppOptions, HttpMethod, Binding, BindingsMap, ParamSpec, ParamIn, ToolLevel, Operation, } from './runtime/types.js';
 export type { WsBinding, WsBindingsMap, LesslyStream, LesslyStreamOpener, StreamCloseInfo, StreamData, WebSocketCtor, WebSocketLike, } from './runtime/types.js';
+export type { Access, AccessState, AccessApi } from './runtime/access.js';
 export type { GeneratedClient } from './gen/client.gen.js';

package/dist/_types/react/index.d.ts

@@ -0,0 +1,33 @@
+import type { Access, AccessApi, AccessState } from '../runtime/access.js';
+import type { Operation } from '../runtime/types.js';
+/**
+ * The only thing these hooks need from a client — so a test double is one object literal, and
+ * (deliberately) no React type appears in any exported signature: `react` is an OPTIONAL peer,
+ * so the published declarations must typecheck for a consumer who has not installed it.
+ */
+export interface AppLike {
+    readonly access: AccessApi;
+}
+export interface UseAccessResult {
+    state: AccessState;
+    role: string | undefined;
+    access: AccessApi;
+    reload: () => Promise<Access>;
+}
+/**
+ * Subscribe a component to the client's access snapshot, loading it once on mount.
+ *
+ * `useSyncExternalStore` rather than `useState` + an effect: the snapshot lives outside React
+ * (several components share one `AccessApi`), and this is the hook that is safe against tearing
+ * under concurrent rendering. `load()` is de-duplicated inside `createAccess`, so every component
+ * may call this without coordinating — two components produce one request.
+ */
+export declare function useAccess(app: AppLike): UseAccessResult;
+/**
+ * True iff the caller is PREDICTED to be allowed to perform `op`. False until the snapshot is
+ * ready — so a control wired to this starts disabled and enables itself, never the reverse.
+ *
+ * Loads on mount through `useAccess`, so a component may use it without the App having called
+ * `load()` anywhere. This is a hint for the UI, never authorisation: see APP-012.
+ */
+export declare function useCan(app: AppLike, op: Operation | string): boolean;

package/dist/_types/runtime/access.d.ts

@@ -0,0 +1,40 @@
+import type { LesslyAppOptions, BindingsMap, Binding, ToolLevel, Operation } from './types.js';
+/** Where the access snapshot is in its lifecycle. `can()` is true-capable only in `ready`. */
+export type AccessState = 'idle' | 'loading' | 'ready' | 'error';
+/** The caller's own membership of the active product, exactly as `/me` returns it (flat). */
+export interface Access {
+    role: string;
+    roleId: string | null;
+    roleName: string | null;
+    roleType: 'system' | 'custom' | null;
+    allow: string[];
+    deny: string[];
+}
+export interface AccessApi {
+    /** Fetches once and caches. Concurrent calls share a single request. Rejects on failure. */
+    load(): Promise<Access>;
+    /** Synchronous PREDICTION of the gateway's answer. False whenever state !== 'ready'. */
+    can(op: Operation | string): boolean;
+    readonly role: string | undefined;
+    readonly state: AccessState;
+    /** Drops the cache and returns to `idle`; the next `load()` hits the network. */
+    invalidate(): void;
+    /** Fires on every state change. Returns an unsubscribe function. */
+    subscribe(cb: () => void): () => void;
+}
+/** The catalog tool this whole surface is built on. */
+export declare const ME_OPERATION_KEY = "organization_product_me";
+/**
+ * The route to `/me`, as a `Binding`, for the window in which the SDK ships BEFORE the production
+ * catalog carries `organization_product_me`. `src/gen` is regenerated from the production catalog
+ * and must never be hand-edited, so without this constant `load()` would need a second SDK
+ * release to start working after Workspace deploys the endpoint.
+ *
+ * Rooted exactly as every other `organization_*` tool is in the real `bindings.gen`
+ * (`organization_product_list-members` -> `/governance/api/v1/products/:productId/members`). The
+ * generated binding WINS whenever it exists — the catalog is the authority, this is the stopgap —
+ * and `access.test.ts` pins the constant against `fixtures/catalog.sample.json` so the day the
+ * catalog does carry the tool, a divergence fails a test instead of 404-ing in a browser.
+ */
+export declare const ME_ROUTE: Binding;
+export declare function createAccess(opts: LesslyAppOptions, bindings: BindingsMap, operations: Record<string, ToolLevel>): AccessApi;

package/dist/_types/runtime/createLesslyApp.d.ts

@@ -1,6 +1,10 @@
 import type { LesslyAppOptions, LesslyStreamOpener } from './types.js';
+import type { AccessApi } from './access.js';
 import type { GeneratedClient } from '../gen/client.gen.js';
 export interface LesslyClientBase extends LesslyStreamOpener {
     call(toolName: string, input?: Record<string, unknown>): Promise<unknown>;
+    /** The caller's own access to the active product — a PREDICTION of the gateway's answer,
+     * never a substitute for it. See `createAccess`. */
+    readonly access: AccessApi;
 }
 export declare function createLesslyApp(opts: LesslyAppOptions): GeneratedClient & LesslyClientBase;

package/dist/_types/runtime/errors.d.ts

@@ -2,6 +2,17 @@ export declare class LesslyApiError extends Error {
     readonly status: number;
     readonly code: string | null;
     readonly body: unknown;
+    /** True iff this is the gateway refusing the call over the caller's access. See ACCESS_DENIED_CODES. */
+    readonly accessDenied: boolean;
     constructor(status: number, code: string | null, message: string, body: unknown);
 }
 export declare function parseErrorBody(body: unknown, status: number): LesslyApiError;
+/**
+ * True iff `err` is the gateway refusing a call over the caller's access.
+ *
+ * Deliberately structural after the `instanceof` fast path: an App is composed into the shell
+ * through Module Federation and `@lessly/sdk-app` is not a shared singleton, so the error a
+ * caller catches is routinely an instance of the OTHER copy's class. `instanceof` alone would
+ * report false there and an App would render a red crash for an ordinary permission refusal.
+ */
+export declare function isAccessDenied(err: unknown): boolean;

package/dist/_types/runtime/permission-match.d.ts

@@ -0,0 +1,62 @@
+/**
+ * VERBATIM COPY of lessly-workspace `packages/sdk-governance/src/permission-match.ts`.
+ *
+ * `@lessly/sdk-governance` is private on GAR and `@lessly/sdk-app` is public on npmjs, so this
+ * SDK cannot depend on it — and `can()` is only useful if it predicts the gateway's answer with
+ * the gateway's own code. Everything below this header is byte-identical to the original.
+ *
+ * CHANGE ONLY TOGETHER WITH THE ORIGINAL. `permission-match.cases.json` is the shared corpus both
+ * repositories run; a change that makes the two files disagree makes `can()` lie.
+ */
+/**
+ * Pure, segment-aware permission matcher — the single source of truth for RBAC
+ * grant semantics.
+ *
+ * Operation keys are `{slug}_{entity}_{action}` split on `_` (depth-agnostic).
+ * `*` is a wildcard only as a complete segment. Interior/leading `*` matches
+ * exactly one segment; a trailing `*` matches one-or-more remaining segments.
+ */
+/** Coarse sensitivity band an operation can declare. */
+export type ToolLevel = 'read' | 'write' | 'admin';
+/**
+ * An operation to authorize: its key, plus the optional level it declares.
+ * An operation with no `level` is reachable only through key patterns.
+ */
+export interface Operation {
+    key: string;
+    level?: ToolLevel;
+}
+/**
+ * True iff `p` is exactly `level:read`, `level:write` or `level:admin` — the
+ * complete set of level patterns. Anything else (`level:*`, `level:owner`,
+ * `level:`) is not one.
+ */
+export declare function isLevelPattern(p: string): boolean;
+/**
+ * Returns true iff at least one grant pattern matches the operation.
+ * Allow-list semantics, default-deny. O(grants × segments), no backtracking.
+ *
+ * A bare string operation carries no level, so level patterns never match it.
+ * An `Operation` is matched by key patterns on `op.key` exactly as a string
+ * would be, and additionally by `level:X` iff `op.level === X`.
+ */
+export declare function matchPermission(op: string | Operation, grants: readonly string[]): boolean;
+/** Allow/deny permission set. Both lists use the same wildcard semantics. */
+export interface Permissions {
+    allow: readonly string[];
+    deny: readonly string[];
+}
+/**
+ * Allow/deny decision: allowed iff some `allow` grant matches AND no `deny`
+ * grant matches. Deny overrides allow (even `allow: ['*']`). Default-deny is
+ * inherited from `matchPermission`: empty allow ⇒ false; empty deny ⇒ allow
+ * decides; blank key ⇒ false.
+ */
+export declare function evaluate(op: string | Operation, perms: Permissions): boolean;
+/**
+ * Structural validator for grant patterns (for UI/API input validation, e.g.
+ * custom-role CRUD). Valid iff non-empty, no whitespace, no empty segments, and
+ * every segment is either exactly `*` or a literal with no `*`. Does NOT enforce
+ * a character set — tool-id grants may use arbitrary segment characters.
+ */
+export declare function isValidPattern(pattern: string): boolean;