@dashai/sdk 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DashWise
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,377 @@
+# @dashai/sdk
+
+Runtime client for DashWise: typed data access + auth helpers for modules.
+
+This package is used by:
+
+- **AI-built modules** — generated typed wrappers (`db.tasks`, `db.notes`, ...) import from this runtime.
+- **Hand-authored modules** — same as AI-built; the CLI runs `dashwise module generate` to emit the typed wrappers.
+- **Custom modules** — full Next.js App Router apps depend on this for both data + auth.
+- **External tools** — ETL scripts, integration tests, monitoring — `npm install @dashai/sdk` and use the generic `db<Row>(slug)` shape.
+
+## Status
+
+`0.6.x` — data plane + auth (SSO + session) + **Module RBAC** (P12.4) + **Query Plane v1** (Phases 1–6 shipped 2026-05-20: typed `qb` builder, cross-module reads, joins, views, streaming, observability). Stable enough for module authors; SemVer-bump on breaking changes only.
+
+## Install
+
+```bash
+npm install @dashai/sdk
+```
+
+Requires Node 20+ (or any modern browser).
+
+## Usage — data plane
+
+### Generic (no codegen)
+
+```ts
+import { createClient, type BaseRow } from '@dashai/sdk';
+
+interface TaskRow extends BaseRow {
+  title: string;
+  done: boolean;
+}
+
+const client = createClient({
+  baseUrl: 'https://api.dashwise.io',
+  installationId: 42,
+  getToken: () => process.env.DASHWISE_TOKEN ?? null,
+});
+
+const page = await client.db<TaskRow>('tasks').list({
+  filter: { done: false, title: { contains: 'urgent' } },
+  sort: [{ field: 'order', dir: 'asc' }],
+  limit: 50,
+});
+
+console.log(page.rows, page.total);
+```
+
+### Typed (with codegen)
+
+After running `dashwise module generate`:
+
+```ts
+import { db } from '@dashai/generated';
+
+const page = await db.tasks.list({ filter: { done: false } });
+//      ^^^^ fully typed against your manifest
+```
+
+For the richer query surface (joins, aggregations, cross-module reads, streaming), use the typed `qb` factory — see **Query plane** below.
+
+## Query plane
+
+The typed query builder lives under the `@dashai/sdk/query` subpath. Import the runtime factory directly, or use the codegen-emitted `qb` from `@dashai/generated/qb` (recommended — full IntelliSense against your manifest).
+
+> Migrating from `client.db<Row>('slug').list({...})`? See [`docs/migration-to-qb.md`](../../docs/migration-to-qb.md) for a side-by-side translation guide. `client.db()` stays permanently supported — `qb` is additive.
+>
+> Building queries from a non-TS client (Python, Go, ETL script)? See [`docs/query-ast-v1.md`](../../docs/query-ast-v1.md) — the wire-format AST reference. The SDK's `qb` produces the same JSON; any client can build it by hand.
+
+### Basic queries
+
+```ts
+import { qb } from '@dashai/generated';
+
+// Owned table reads
+const page = await qb.tasks
+  .where({ done: false, due_date: { date_before: '2026-06-01' } })
+  .orderBy([{ field: 'due_date', dir: 'asc' }])
+  .select(['id', 'title', 'due_date'])
+  .limit(50)
+  .execute();
+//      → Page<{ id, title, due_date }>
+
+// Counts + aggregations
+const stats = await qb.tasks
+  .where({ done: true })
+  .groupBy(['assignee_id'])
+  .agg({ total: 'count', overdue_days: { kind: 'avg', field: 'overdue_days' } })
+  .execute();
+```
+
+### Joins (same module)
+
+`.join()` / `.leftJoin()` with link-field-derived `on`:
+
+```ts
+const tasksWithAssignee = await qb.tasks
+  .leftJoin('assignee')          // on-clause inferred from the link_row field
+  .where({ done: false })
+  .execute();
+// → Page<{ id, title, done, assignee: { id, email } | null }>
+
+// Flat-row mode (advanced):
+const flat = await qb.tasks.leftJoin('assignee').flatten().execute();
+// → Page<{ id, title, 'assignee.id': number, 'assignee.email': string }>
+```
+
+### Cross-module reads
+
+Reads against another module's tables (gated by manifest `uses` ↔ provider's `exposes`):
+
+```ts
+const contacts = await qb.deps.crm.contacts
+  .where({ archived: false })
+  .select(['name', 'email'])
+  .execute();
+
+// Cross-module joins (≤2 modules per query in v1):
+const tasksByContact = await qb.tasks
+  .join('deps.crm.contacts', { on: { 'tasks.contact_id': 'contacts.id' } })
+  .execute();
+```
+
+### Views
+
+Manifest-declared views appear under `qb.views.<slug>`:
+
+```ts
+const overdue = await qb.views.overdue_tasks.execute();
+```
+
+### Streaming
+
+`.stream()` returns an async iterator for large result sets — backend pushes rows via SSE; cursor pushdown means memory stays bounded:
+
+```ts
+const controller = new AbortController();
+
+for await (const row of qb.tasks.where({ done: false }).stream({ signal: controller.signal })) {
+  process(row);
+  if (shouldStop) controller.abort();   // Clean cancellation
+}
+```
+
+`.stream()` is available on `Query`, `JoinedQuery`, and `AggQuery`. The 1000-row clamp is lifted on the streaming path (cap is `STREAM_MAX_ROWS = 100_000`).
+
+### EXPLAIN
+
+`.explain()` returns the Postgres plan envelope for any query that supports it (joined queries fully; bare own/dep/view paths surfacing a typed `EXPLAIN_NOT_SUPPORTED_YET` until Phase 5+):
+
+```ts
+const plan = await qb.tasks.leftJoin('assignee').where({ done: false }).explain();
+console.log(plan.nodes, plan.estimated_cost);
+```
+
+CLI shortcut: `dashwise query --explain --file ./query.mjs`.
+
+### React hook — `useQuery`
+
+`@dashai/sdk/react` exposes a `useQuery` hook that takes a `Query<Row>` / `JoinedQuery<Row>` / `AggQuery` and tracks loading + result + error state:
+
+```tsx
+'use client';
+import { useQuery } from '@dashai/sdk/react';
+import { qb } from '@dashai/generated';
+
+export function TaskList() {
+  const { data, isLoading, error, refetch } = useQuery(
+    qb.tasks.where({ done: false }).orderBy([{ field: 'due_date', dir: 'asc' }]),
+  );
+  if (isLoading) return <Spinner />;
+  if (error) return <ErrorBanner error={error} />;
+  return <ul>{data?.rows.map((t) => <li key={t.id}>{t.title}</li>)}</ul>;
+}
+```
+
+The hook compiles the AST + uses the client behind the scenes; it does NOT cache across components — pair with SWR / react-query if you need cross-component cache. (Same lean philosophy as `useTable` / `useRecord`.)
+
+### Cross-module reads — generic shape
+
+For untyped or external-tool usage, the generic `client.deps(slug).db<Row>(table)` accessor is available (subpath `@dashai/sdk/deps`):
+
+```ts
+import { type Deps } from '@dashai/sdk/deps';
+
+const contacts = await client.deps('crm').db<ContactRow>('contacts').list({ filter: { archived: false } });
+```
+
+The codegen-emitted `qb.deps.<slug>.<table>` surface is the recommended typed path.
+
+## Configuration
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `baseUrl` | `string` | _(required)_ | DashWise API root, no trailing slash. |
+| `installationId` | `number \| 'sandbox' \| 'local'` | _(required)_ | Scope all calls to this installation. |
+| `getToken` | `() => string \| null \| Promise<...>` | `undefined` | Token resolver. Called once per request. |
+| `fetch` | `typeof fetch` | `globalThis.fetch` | Custom fetch implementation. |
+| `timeoutMs` | `number` | `30_000` | Per-request timeout. |
+| `headers` | `Record<string, string>` | `undefined` | Extra headers added to every request. |
+| `onSlowQuery` | `(info: SlowQueryInfo) => void` | `undefined` | Fires for each query whose round-trip wall time exceeds `slowQueryThresholdMs`. Use for client-side observability — e.g. send to Sentry, log to a dashboard. |
+| `slowQueryThresholdMs` | `number` | `500` | Threshold for `onSlowQuery`. Ignored when `onSlowQuery` is unset (no work is done). |
+
+## Error model
+
+Every method rejects with a typed `DashwiseError` (or subclass) on failure:
+
+```ts
+import {
+  DashwiseError,
+  NetworkError,
+  TimeoutError,
+  UnauthenticatedError,
+  ForbiddenError,
+  RowNotFoundError,
+  ContractViolationError,
+  ValidationError,
+} from '@dashai/sdk';
+
+try {
+  await client.db<TaskRow>('tasks').get(99);
+} catch (err) {
+  if (err instanceof RowNotFoundError) {
+    // 404 path
+  } else if (err instanceof UnauthenticatedError) {
+    // token missing / expired
+  } else if (err instanceof DashwiseError) {
+    // anything else; inspect `err.code` for the specific code
+  } else {
+    throw err;
+  }
+}
+```
+
+Inspect `err.code` for codes that don't have a dedicated subclass. The full list of curated codes lives in `DashwiseErrorCode`.
+
+### Request correlation
+
+Every `DashwiseError` carries a `.requestId` (string or `null`) — the same value the backend logs into `module_query_log`. Surface it in your error UI so support can cross-reference a user complaint with the server-side trace:
+
+```ts
+catch (err) {
+  if (err instanceof DashwiseError) {
+    showToast(`Something went wrong (id: ${err.requestId ?? 'unknown'})`);
+  }
+}
+```
+
+## Auth — Module RBAC (P12.4)
+
+Modules declare roles + permissions in their `module.json`'s `rbac` block (see
+[`module-rbac-design.md`](../../../dashwise-devops-docs/plans/module-rbac-design.md)).
+The SDK exposes those grants to your app via session enrichment + helpers.
+
+### Server-side (Route Handlers, RSC, Server Actions)
+
+```ts
+import {
+  getServerSession,
+  hasPermission,
+  requirePermission,
+  requireAnyPermission,
+  requireRole,
+} from '@dashai/sdk/auth/server';
+
+// Sync check from an already-loaded session
+const session = await getServerSession();
+if (!session?.rbacPermissions?.includes('tasks-app:tasks:delete')) {
+  return new Response('Forbidden', { status: 403 });
+}
+
+// Throw-on-denial pattern (returns the session on success):
+export default async function DeletePanel() {
+  const session = await requirePermission('tasks:delete'); // bare form OK
+  return <DeleteForm userEmail={session.user.email} />;
+}
+
+// Any-of:
+const session = await requireAnyPermission(['tasks:bulk_delete', 'tasks:delete']);
+```
+
+### Route-handler wrappers (App Router `route.ts`)
+
+```ts
+import { withPermission, withAnyPermission } from '@dashai/sdk/auth/middleware';
+
+// Returns 401 (no session) or 403 (forbidden) automatically.
+export const POST = withPermission('tasks:create')(async (req, _ctx, session) => {
+  const body = await req.json();
+  return Response.json({ ok: true, createdBy: session.user.id });
+});
+
+// Allow either of two permissions:
+export const DELETE = withAnyPermission(['tasks:delete', 'tasks:bulk_delete'])(
+  async (req) => Response.json({ deleted: true }),
+);
+```
+
+### Client-side (Client Components)
+
+```tsx
+'use client';
+import {
+  useHasPermission,
+  useHasRole,
+  usePermissions,
+  useHasAnyPermission,
+} from '@dashai/sdk/auth/client';
+
+export function DeleteButton({ taskId }: { taskId: number }) {
+  const canDelete = useHasPermission('tasks:delete'); // bare or namespaced
+  if (!canDelete) return null;
+  return <button onClick={() => deleteTask(taskId)}>Delete</button>;
+}
+
+export function AdminMenu() {
+  const isAdmin = useHasRole('admin');
+  if (!isAdmin) return null;
+  return <Settings />;
+}
+```
+
+`AuthProvider` fetches the resolved RBAC slice from
+`/api/installations/:id/rbac/me` in parallel with the session on mount;
+all client hooks are then sync set-membership checks (no network per
+call).
+
+### Key matching: bare vs namespaced
+
+The backend stores namespaced keys (`<module_slug>:<key>`) so the
+JWT shape supports multi-install in the future. From inside your own
+module, write **bare** keys:
+
+```ts
+useHasPermission('tasks:delete')   // ✓ matches 'tasks-app:tasks:delete'
+useHasRole('editor')                // ✓ matches 'tasks-app:editor'
+useHasPermission('tasks-app:tasks:delete')  // ✓ explicit form also works
+```
+
+Cross-module checks (rare in v1) MUST use the namespaced form.
+
+### Error model
+
+`requirePermission` and friends throw `DashwiseError`:
+
+- `PERMISSION_DENIED` (HTTP 403) — session present but lacks the requested key
+- `RBAC_UNAVAILABLE` (HTTP 401) — no session present at all (sign-in needed)
+
+The route-handler wrappers (`withPermission` etc.) translate the same
+two cases into 401/403 JSON responses automatically; pass `onDeny` to
+override.
+
+## SemVer policy
+
+Every named export from the package root is part of the SemVer-stable API. Breaking changes require a major bump.
+
+Stable since `0.1.0`:
+
+- `createClient`
+- `DashwiseError` + subclasses (`NetworkError`, `TimeoutError`, `UnauthenticatedError`, `ForbiddenError`, `RowNotFoundError`, `ContractViolationError`, `ValidationError`)
+- `DashwiseErrorCode` (additive; new codes are non-breaking)
+- Types: `BaseRow`, `BaseInsert`, `BaseUpdate`, `Client`, `ClientConfig`, `TableClient`, `Where<Row>`, `FilterOps`, `FilterValue<V>`, `ListOpts<Row>`, `Page<Row>`, `SortClause<Row>`, `SortDir`, `FileRef`, `TokenResolver`, `FetchImpl`
+
+Stable since `0.4.0` (Query Plane v1):
+
+- `@dashai/sdk/query` subpath: `makeQb`, `CURRENT_QUERY_AST_VERSION`, `isQueryAst`; types `Qb`, `Query<Row>`, `JoinedQuery<Row>`, `AggQuery`, `QueryResult`, `ExplainResult`, `QbDepRef`, `QbViewRef`, `JoinOpts`, `QueryAst`, `QueryAstVersion`, `OrderClause`, `SelectExpr`, `AggExpr`, `JoinNode`, `FieldRef`, `TableRef`
+- `@dashai/sdk/deps` subpath: `makeDeps`, `DependencyContractError`, `OperationNotAllowedByProviderError`, `ProviderTableMissingError`; types `Deps`, `ReadOnlyTableClient`
+- `@dashai/sdk/react` adds `useQuery` (alongside the existing `useTable` / `useRecord`)
+- `ClientConfig.onSlowQuery` + `slowQueryThresholdMs`
+- `DashwiseError.requestId`
+- `Client.streamRaw(method, path, body, signal?)` — low-level SSE helper that powers `.stream()`
+
+## License
+
+MIT

package/dist/auth/client.cjs

@@ -0,0 +1,185 @@
+'use client';
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/auth/rbac.ts
+function permissionGranted(rbac, key) {
+  if (!rbac || !rbac.permissions) return false;
+  return matchKey(rbac.permissions, key);
+}
+function roleGranted(rbac, roleKey) {
+  if (!rbac || !rbac.roles) return false;
+  return matchKey(rbac.roles, roleKey);
+}
+function rbacOf(session) {
+  if (!session) return null;
+  return {
+    roles: session.rbacRoles ?? [],
+    permissions: session.rbacPermissions ?? []
+  };
+}
+function matchKey(stored, queryKey) {
+  if (stored.length === 0) return false;
+  for (const s of stored) {
+    if (s === queryKey) return true;
+    if (s.endsWith(":" + queryKey)) return true;
+  }
+  return false;
+}
+var SessionContext = react.createContext({
+  session: null,
+  status: "loading",
+  refresh: async () => {
+  }
+});
+function AuthProvider({
+  children,
+  apiBaseUrl,
+  initialSession
+}) {
+  const [session, setSession] = react.useState(initialSession ?? null);
+  const [status, setStatus] = react.useState(
+    initialSession === void 0 ? "loading" : initialSession ? "authenticated" : "unauthenticated"
+  );
+  const refresh = react.useCallback(async () => {
+    setStatus("loading");
+    try {
+      const base = apiBaseUrl ?? "";
+      const res = await fetch(`${base}/api/auth/sessions/me`, {
+        method: "GET",
+        credentials: "include",
+        headers: { Accept: "application/json" }
+      });
+      if (!res.ok) {
+        setSession(null);
+        setStatus("unauthenticated");
+        return;
+      }
+      const data = await res.json().catch(() => null);
+      if (!data) {
+        setSession(null);
+        setStatus("unauthenticated");
+        return;
+      }
+      let enriched = data;
+      if (typeof data.installationId === "number") {
+        const rbacRes = await fetch(
+          `${base}/api/installations/${data.installationId}/rbac/me`,
+          {
+            method: "GET",
+            credentials: "include",
+            headers: { Accept: "application/json" }
+          }
+        ).catch(() => null);
+        if (rbacRes && rbacRes.ok) {
+          const rbac = await rbacRes.json().catch(() => null);
+          if (rbac && Array.isArray(rbac.roles) && Array.isArray(rbac.permissions)) {
+            enriched = {
+              ...data,
+              rbacRoles: rbac.roles.filter(
+                (r) => typeof r === "string"
+              ),
+              rbacPermissions: rbac.permissions.filter(
+                (p) => typeof p === "string"
+              )
+            };
+          }
+        }
+      }
+      setSession(enriched);
+      setStatus("authenticated");
+    } catch {
+      setSession(null);
+      setStatus("unauthenticated");
+    }
+  }, [apiBaseUrl]);
+  react.useEffect(() => {
+    if (initialSession !== void 0) return;
+    void refresh();
+  }, []);
+  const value = react.useMemo(
+    () => ({ session, status, refresh }),
+    [session, status, refresh]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(SessionContext.Provider, { value, children });
+}
+function useSession() {
+  return react.useContext(SessionContext);
+}
+function SignOutButton({
+  children = "Sign out",
+  redirectTo = "/",
+  className,
+  apiBaseUrl
+}) {
+  const { refresh } = useSession();
+  const onClick = react.useCallback(async () => {
+    try {
+      const base = apiBaseUrl ?? "";
+      await fetch(`${base}/api/auth/sign-out`, {
+        method: "POST",
+        credentials: "include"
+      });
+    } catch {
+    }
+    await refresh();
+    if (redirectTo !== null && typeof window !== "undefined") {
+      window.location.href = redirectTo;
+    }
+  }, [apiBaseUrl, redirectTo, refresh]);
+  return /* @__PURE__ */ jsxRuntime.jsx("button", { type: "button", onClick, className, children });
+}
+function SignInLink({
+  children = "Sign in",
+  className,
+  href = "/api/auth/sign-in",
+  returnTo
+}) {
+  const target = react.useMemo(() => {
+    const computedReturnTo = returnTo ?? (typeof window !== "undefined" ? window.location.pathname + window.location.search : "/");
+    const url = new URL(href, typeof window !== "undefined" ? window.location.origin : "http://x");
+    url.searchParams.set("return_to", computedReturnTo);
+    return url.pathname + url.search;
+  }, [href, returnTo]);
+  return /* @__PURE__ */ jsxRuntime.jsx("a", { href: target, className, children });
+}
+function useHasPermission(permissionKey) {
+  const { session } = useSession();
+  return permissionGranted(rbacOf(session), permissionKey);
+}
+function useHasRole(roleKey) {
+  const { session } = useSession();
+  return roleGranted(rbacOf(session), roleKey);
+}
+function usePermissions() {
+  const { session } = useSession();
+  return session?.rbacPermissions ?? [];
+}
+function useRoles() {
+  const { session } = useSession();
+  return session?.rbacRoles ?? [];
+}
+function useHasAnyPermission(permissionKeys) {
+  const perms = usePermissions();
+  if (perms.length === 0) return false;
+  for (const key of permissionKeys) {
+    for (const p of perms) {
+      if (p === key || p.endsWith(":" + key)) return true;
+    }
+  }
+  return false;
+}
+
+exports.AuthProvider = AuthProvider;
+exports.SignInLink = SignInLink;
+exports.SignOutButton = SignOutButton;
+exports.useHasAnyPermission = useHasAnyPermission;
+exports.useHasPermission = useHasPermission;
+exports.useHasRole = useHasRole;
+exports.usePermissions = usePermissions;
+exports.useRoles = useRoles;
+exports.useSession = useSession;
+//# sourceMappingURL=client.cjs.map
+//# sourceMappingURL=client.cjs.map

package/dist/auth/client.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/auth/rbac.ts","../../src/auth/client.tsx"],"names":["createContext","useState","useCallback","useEffect","useMemo","jsx","useContext"],"mappings":"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","file":"client.cjs","sourcesContent":["/**\n * Module RBAC helpers — shared between server-side (`auth/server.ts`),\n * middleware (`auth/middleware.ts`), and client-side (`auth/client.tsx`).\n *\n * The design lives at\n * `dashwise-devops-docs/plans/module-rbac-design.md` (Locked\n * 2026-05-17). This file implements the **runtime-side resolution**\n * — the actual check against a resolved permission/role set.\n *\n * **Where the resolved set comes from** depends on the caller:\n *   - Server-side: `getServerSession()` fetches `/api/installations/:id/rbac/me`\n *     in parallel with `/api/auth/sessions/me` and merges into the\n *     returned `Session`.\n *   - Client-side: `AuthProvider` does the same on mount, exposes via\n *     React context.\n *\n * **Bare vs namespaced keys.** Internally we store namespaced keys\n * (`<module_slug>:<key>`) so the JWT shape supports multi-install in\n * the future. Authors write BARE keys (`tasks:delete`, `editor`) from\n * inside their own module — the helpers transparently match either.\n *\n * The bare-key match is `endsWith(':' + bareKey)` — safe because role\n * keys can't contain colons (enforced by the parser regex in P12.1)\n * and permission keys use colons as namespace separators within a\n * fixed shape. Cross-module references must use the full namespaced\n * form explicitly.\n */\n\nimport type { RbacMeResponse, Session } from './types.js';\n\n/**\n * Does the caller's resolved permission set contain `key`? Accepts\n * either the bare form (`tasks:delete`) or the fully-namespaced form\n * (`tasks-app:tasks:delete`).\n *\n * Pure function over a `RbacMeResponse`-shaped object — usable from\n * any context. Returns `false` if the set is missing/undefined (the\n * default-deny floor); never throws.\n */\nexport function permissionGranted(\n  rbac: Pick<RbacMeResponse, 'permissions'> | null | undefined,\n  key: string,\n): boolean {\n  if (!rbac || !rbac.permissions) return false;\n  return matchKey(rbac.permissions, key);\n}\n\n/**\n * Does the caller hold `roleKey` (bare or namespaced) in their role\n * set? Returns false if no RBAC data present.\n */\nexport function roleGranted(\n  rbac: Pick<RbacMeResponse, 'roles'> | null | undefined,\n  roleKey: string,\n): boolean {\n  if (!rbac || !rbac.roles) return false;\n  return matchKey(rbac.roles, roleKey);\n}\n\n/**\n * Does the resolved set contain ANY of the requested permissions?\n * Used by `withAnyPermission()` middleware + the `any: [...]` rule\n * shape in `withAuth.permissionRules`.\n */\nexport function anyPermissionGranted(\n  rbac: Pick<RbacMeResponse, 'permissions'> | null | undefined,\n  keys: readonly string[],\n): boolean {\n  return keys.some((k) => permissionGranted(rbac, k));\n}\n\n/**\n * Does the resolved set contain ALL of the requested permissions?\n * Used by `withAllPermissions()` middleware.\n */\nexport function allPermissionsGranted(\n  rbac: Pick<RbacMeResponse, 'permissions'> | null | undefined,\n  keys: readonly string[],\n): boolean {\n  return keys.every((k) => permissionGranted(rbac, k));\n}\n\n/**\n * Extract just the RBAC slice from a `Session`. Tiny helper for\n * helpers that want to pass either a Session or a `RbacMeResponse`\n * shape uniformly.\n */\nexport function rbacOf(session: Session | null | undefined):\n  | Pick<RbacMeResponse, 'roles' | 'permissions'>\n  | null {\n  if (!session) return null;\n  return {\n    roles: session.rbacRoles ?? [],\n    permissions: session.rbacPermissions ?? [],\n  };\n}\n\n// ── Private match helper ───────────────────────────────────────────\n\n/**\n * Bare-or-namespaced match against a stored key set.\n *\n *   exact match            → granted\n *   key ends with `:bare`  → granted (namespaced match)\n *\n * The `:` prefix on the suffix check prevents `'admin'` from\n * matching a stored `'super-admin'`. Role + permission keys never\n * start with `:` and never contain it un-namespaced, so this match\n * is safe across both kinds.\n */\nfunction matchKey(stored: readonly string[], queryKey: string): boolean {\n  if (stored.length === 0) return false;\n  for (const s of stored) {\n    if (s === queryKey) return true;\n    if (s.endsWith(':' + queryKey)) return true;\n  }\n  return false;\n}\n","'use client';\n\n/**\n * Client-side React helpers — used from Client Components in Next.js\n * App Router or in any React 18+ app that wants to read the current\n * DashWise session.\n *\n * Consumers:\n *   import { AuthProvider, useSession, SignOutButton } from '@dashai/sdk/auth/client';\n *\n * Wire `<AuthProvider>` once at the root of your app (typically in\n * `app/layout.tsx`); any descendant Client Component can then call\n * `useSession()` to read the session reactively.\n *\n * Session fetching is lazy: the provider performs a single GET\n * against `/api/auth/sessions/me` on mount. To force a re-fetch\n * (e.g. after a `signOut()` + sign-in flow), call `refresh()` on the\n * context.\n */\n\nimport {\n  createContext,\n  type ReactElement,\n  type ReactNode,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useState,\n} from 'react';\n\nimport type { RbacMeResponse, Session, SessionStatus } from './types.js';\nimport {\n  permissionGranted,\n  rbacOf,\n  roleGranted,\n} from './rbac.js';\n\n// ── Context ────────────────────────────────────────────────────────────\n\nexport interface SessionContextValue {\n  session: Session | null;\n  status: SessionStatus;\n  /** Force-refetch the session. Useful after a sign-in or sign-out. */\n  refresh: () => Promise<void>;\n}\n\nconst SessionContext = createContext<SessionContextValue>({\n  session: null,\n  status: 'loading',\n  refresh: async () => {\n    // No-op outside a provider. Consumers should always render\n    // `<AuthProvider>` at the root.\n  },\n});\n\n// ── Provider ──────────────────────────────────────────────────────────\n\nexport interface AuthProviderProps {\n  children: ReactNode;\n  /**\n   * Where to call `/api/auth/sessions/me`. Defaults to relative URL\n   * (same origin as the page) — that's the right default for custom\n   * Next.js modules where the backend is proxied through the same\n   * host. Pass an absolute URL to fetch from a cross-origin API.\n   */\n  apiBaseUrl?: string;\n  /**\n   * Optional initial session — useful for hydrating from a server\n   * render. When passed, the provider skips its initial fetch and\n   * starts in `authenticated` (or `unauthenticated` if null was\n   * explicitly passed and the consumer wants to opt out of the\n   * mount-time fetch).\n   */\n  initialSession?: Session | null;\n}\n\n/**\n * React Context provider that loads the current session on mount and\n * makes it available to descendant `useSession()` callers.\n */\nexport function AuthProvider({\n  children,\n  apiBaseUrl,\n  initialSession,\n}: AuthProviderProps): ReactElement {\n  const [session, setSession] = useState<Session | null>(initialSession ?? null);\n  const [status, setStatus] = useState<SessionStatus>(\n    initialSession === undefined ? 'loading' : initialSession ? 'authenticated' : 'unauthenticated',\n  );\n\n  const refresh = useCallback(async () => {\n    setStatus('loading');\n    try {\n      const base = apiBaseUrl ?? '';\n      const res = await fetch(`${base}/api/auth/sessions/me`, {\n        method: 'GET',\n        credentials: 'include',\n        headers: { Accept: 'application/json' },\n      });\n      if (!res.ok) {\n        setSession(null);\n        setStatus('unauthenticated');\n        return;\n      }\n      const data = (await res.json().catch(() => null)) as Session | null;\n      if (!data) {\n        setSession(null);\n        setStatus('unauthenticated');\n        return;\n      }\n\n      // P12.4: fetch the RBAC slice for the current installation in\n      // parallel. Failure is non-fatal — the session still renders;\n      // `useHasPermission` will simply return false for everything\n      // until a successful re-fetch (the default-deny floor).\n      let enriched: Session = data;\n      if (typeof data.installationId === 'number') {\n        const rbacRes = await fetch(\n          `${base}/api/installations/${data.installationId}/rbac/me`,\n          {\n            method: 'GET',\n            credentials: 'include',\n            headers: { Accept: 'application/json' },\n          },\n        ).catch(() => null);\n\n        if (rbacRes && rbacRes.ok) {\n          const rbac = (await rbacRes.json().catch(() => null)) as\n            | RbacMeResponse\n            | null;\n          if (\n            rbac &&\n            Array.isArray(rbac.roles) &&\n            Array.isArray(rbac.permissions)\n          ) {\n            enriched = {\n              ...data,\n              rbacRoles: rbac.roles.filter(\n                (r: unknown): r is string => typeof r === 'string',\n              ),\n              rbacPermissions: rbac.permissions.filter(\n                (p: unknown): p is string => typeof p === 'string',\n              ),\n            };\n          }\n        }\n      }\n      setSession(enriched);\n      setStatus('authenticated');\n    } catch {\n      setSession(null);\n      setStatus('unauthenticated');\n    }\n  }, [apiBaseUrl]);\n\n  useEffect(() => {\n    if (initialSession !== undefined) return; // skip mount-time fetch\n    void refresh();\n    // We deliberately don't depend on `refresh` directly — the\n    // useCallback handles staleness; we only want to fire on mount.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  const value = useMemo<SessionContextValue>(\n    () => ({ session, status, refresh }),\n    [session, status, refresh],\n  );\n\n  return <SessionContext.Provider value={value}>{children}</SessionContext.Provider>;\n}\n\n// ── Hook ──────────────────────────────────────────────────────────────\n\n/**\n * Read the current session reactively. Returns `{ session, status,\n * refresh }`. Always renders synchronously; the consumer should gate\n * on `status === 'loading'` for the initial fetch.\n *\n * @example\n *   function Header() {\n *     const { session, status } = useSession();\n *     if (status === 'loading') return <Spinner />;\n *     if (!session) return <a href=\"/api/auth/sign-in\">Sign in</a>;\n *     return <span>Hi {session.user.email}</span>;\n *   }\n */\nexport function useSession(): SessionContextValue {\n  return useContext(SessionContext);\n}\n\n// ── Components ────────────────────────────────────────────────────────\n\nexport interface SignOutButtonProps {\n  children?: ReactNode;\n  /**\n   * Where to redirect after sign-out. Defaults to `/`. Pass `null`\n   * to disable redirect (useful when the parent wants to handle\n   * navigation itself, e.g. inside a modal).\n   */\n  redirectTo?: string | null;\n  /** Optional className for styling. */\n  className?: string;\n  /** Apply to the underlying <button>. */\n  apiBaseUrl?: string;\n}\n\n/**\n * Button that POSTs to `/api/auth/sign-out` and redirects on success.\n * Pure plumbing — style/behavior tweaks via children + className.\n *\n * @example\n *   <SignOutButton className=\"text-sm text-gray-500\">Log out</SignOutButton>\n */\nexport function SignOutButton({\n  children = 'Sign out',\n  redirectTo = '/',\n  className,\n  apiBaseUrl,\n}: SignOutButtonProps): ReactElement {\n  const { refresh } = useSession();\n  const onClick = useCallback(async () => {\n    try {\n      const base = apiBaseUrl ?? '';\n      await fetch(`${base}/api/auth/sign-out`, {\n        method: 'POST',\n        credentials: 'include',\n      });\n    } catch {\n      // Best-effort. Even if the request fails, clear local session\n      // state below so the UI reflects \"signed out\".\n    }\n    await refresh();\n    if (redirectTo !== null && typeof window !== 'undefined') {\n      window.location.href = redirectTo;\n    }\n  }, [apiBaseUrl, redirectTo, refresh]);\n\n  return (\n    <button type=\"button\" onClick={onClick} className={className}>\n      {children}\n    </button>\n  );\n}\n\nexport interface SignInLinkProps {\n  children?: ReactNode;\n  className?: string;\n  /**\n   * Path to send the user to. Defaults to `/api/auth/sign-in`, which\n   * the SDK's route-handler counterpart redirects through the SSO\n   * flow. Pass an absolute URL to override.\n   */\n  href?: string;\n  /**\n   * Where to return after sign-in completes. Defaults to the current\n   * path (read from `window.location`). Pass an explicit string to\n   * route the user elsewhere.\n   */\n  returnTo?: string;\n}\n\n/**\n * Link that initiates the sign-in flow. Preserves the current page\n * as the post-sign-in destination via `?return_to=`.\n */\nexport function SignInLink({\n  children = 'Sign in',\n  className,\n  href = '/api/auth/sign-in',\n  returnTo,\n}: SignInLinkProps): ReactElement {\n  const target = useMemo(() => {\n    const computedReturnTo =\n      returnTo ??\n      (typeof window !== 'undefined' ? window.location.pathname + window.location.search : '/');\n    const url = new URL(href, typeof window !== 'undefined' ? window.location.origin : 'http://x');\n    url.searchParams.set('return_to', computedReturnTo);\n    // Return relative path for in-app navigation when possible.\n    return url.pathname + url.search;\n  }, [href, returnTo]);\n\n  return (\n    <a href={target} className={className}>\n      {children}\n    </a>\n  );\n}\n\n// ── Module RBAC hooks (P12.4) ─────────────────────────────────────────\n//\n// Reads the resolved RBAC slice (`rbacRoles` / `rbacPermissions`) from\n// the session populated by `AuthProvider`. All hooks are sync after\n// the initial session fetch — no network calls per check.\n//\n// Accept either the BARE form (`tasks:delete`, `editor`) or the\n// NAMESPACED form (`tasks-app:tasks:delete`). Authors writing inside\n// their own module should use the bare form for ergonomics.\n\n/**\n * Does the current session hold `permissionKey`? Returns false during\n * loading or when no session exists (default-deny floor).\n *\n * @example\n *   const canDelete = useHasPermission('tasks:delete');\n *   if (!canDelete) return null;\n *   return <button onClick={onDelete}>Delete</button>;\n */\nexport function useHasPermission(permissionKey: string): boolean {\n  const { session } = useSession();\n  return permissionGranted(rbacOf(session), permissionKey);\n}\n\n/**\n * Same as `useHasPermission` but for roles.\n */\nexport function useHasRole(roleKey: string): boolean {\n  const { session } = useSession();\n  return roleGranted(rbacOf(session), roleKey);\n}\n\n/**\n * Return the full permission list. Useful for complex conditional\n * rendering across many checkboxes / toolbar items. Returns an empty\n * array during loading.\n */\nexport function usePermissions(): string[] {\n  const { session } = useSession();\n  return session?.rbacPermissions ?? [];\n}\n\n/**\n * Return the full role list. Useful for showing/hiding sections\n * based on coarse role membership.\n */\nexport function useRoles(): string[] {\n  const { session } = useSession();\n  return session?.rbacRoles ?? [];\n}\n\n/**\n * Convenience: check if ANY of the given permissions is held.\n */\nexport function useHasAnyPermission(permissionKeys: readonly string[]): boolean {\n  const perms = usePermissions();\n  if (perms.length === 0) return false;\n  for (const key of permissionKeys) {\n    for (const p of perms) {\n      if (p === key || p.endsWith(':' + key)) return true;\n    }\n  }\n  return false;\n}\n"]}