@b1-road/react 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 B1 Produtos Digitais Ltda
+
+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,300 @@
+# @b1-road/react
+
+The official React toolkit for integrating with Road — components, hooks,
+and helpers for embedding Road IAM into platform apps.
+
+See [`docs/plans/done/03-road-react-package-plan.md`](../../../docs/plans/done/03-road-react-package-plan.md)
+for the predecessor plan (public API surface, hooks taxonomy, packaging)
+and [`docs/plans/10-react-cookie-mode-spec.md`](../../../docs/plans/10-react-cookie-mode-spec.md)
+for the cookie-mode default.
+
+## Status
+
+First public alpha. Cookie mode is the default. Bearer mode remains
+available behind `authMode="bearer"` for headless / mobile / partner
+integrations.
+
+If you're coming from a bearer-first setup, opt in explicitly by adding
+one prop (`authMode="bearer"`). See [Coming from a bearer-first setup](#coming-from-a-bearer-first-setup)
+below.
+
+## Install
+
+```bash
+npm install @b1-road/react@alpha
+```
+
+> Published under the `alpha` dist-tag while the Road API contract is in alpha —
+> install with the explicit `@alpha` tag (there is no `latest` release yet).
+
+## Quick start (cookie mode — recommended)
+
+You are probably here because you're behind a Laravel or NestJS BFF
+(`b1-road/laravel` or `@b1-road/nestjs`) that proxies your app to the
+Road API. The BFF holds the Auth Server JWT server-side; the browser
+ships a session cookie. The React SDK never sees a token.
+
+```tsx
+import {
+  RoadProvider,
+  BusinessUnitSwitcher,
+  BusinessUnitsMgmt,
+} from "@b1-road/react";
+import "@b1-road/react/style.css";
+
+export function App() {
+  return (
+    <RoadProvider
+      apiBaseUrl="/road-api"
+      onUnauthenticated={() => window.location.assign("/auth/road/login")}
+    >
+      <BusinessUnitSwitcher />
+      <BusinessUnitsMgmt />
+    </RoadProvider>
+  );
+}
+```
+
+That's the whole integration. The SDK:
+
+- Sends requests with `credentials: 'include'`, no `Authorization`
+  header. The BFF attaches the bearer server-side.
+- Echoes the `XSRF-TOKEN` cookie into `X-XSRF-TOKEN` on every mutation
+  (Laravel's convention; the NestJS BFF adopts the same names).
+- Calls `onUnauthenticated` on terminal 401 with a 1s debounce so
+  parallel React Query refetches trigger one redirect, not a stampede.
+
+### Required: `onUnauthenticated`
+
+Cookie mode requires `onUnauthenticated`. Without it the SDK logs a
+one-time `console.warn` and 401s become silent. The handler typically
+redirects to the BFF's login URL.
+
+### Optional cookie-mode knobs
+
+```tsx
+<RoadProvider
+  apiBaseUrl="/road-api"
+  onUnauthenticated={...}
+  csrfCookieName="XSRF-TOKEN"      // default — matches Laravel + NestJS BFFs
+  csrfHeaderName="X-XSRF-TOKEN"    // default
+  withCredentials={false}           // set true only for cross-origin BFFs
+/>
+```
+
+Defaults are tuned for the same-origin BFF deployment that the Laravel
+and NestJS plans ship.
+
+## Bearer mode (advanced / opt-out)
+
+For headless apps, React Native, partner integrations, or any
+deployment where the host actually holds the JWT in JS:
+
+```tsx
+<RoadProvider
+  apiBaseUrl="https://api.road.b1.app"
+  authMode="bearer"
+  jwt={() => getToken()}
+>
+  ...
+</RoadProvider>
+```
+
+`jwt` accepts either a static string or a getter (`() => string |
+Promise<string>`). **Prefer the getter** — Auth Server access tokens
+are short-lived (15–60 minutes); the getter re-resolves per request so
+host-side rotation works without re-mounting the provider.
+
+The trade-offs vs cookie mode, honestly stated:
+
+- **XSS surface.** A token in JS reachable from JS-evaluated XSS is
+  fundamentally weaker than a `HttpOnly` session cookie. Cookie mode
+  removes this surface entirely.
+- **Refresh complexity.** Bearer-mode integrators own token rotation;
+  cookie-mode BFFs do it server-side.
+- **IETF BCP.** The IETF *OAuth 2.0 for Browser-Based Applications*
+  BCP (draft -26) ranks BFF first; PKCE-in-browser is the fallback.
+
+## Coming from a bearer-first setup
+
+If your app holds the JWT in JS and looks like:
+
+```tsx
+<RoadProvider apiBaseUrl="https://api.road.b1.app" jwt={() => getToken()}>
+```
+
+…opt into bearer mode explicitly by adding one prop:
+
+```tsx
+<RoadProvider
+  apiBaseUrl="https://api.road.b1.app"
+  authMode="bearer"
+  jwt={() => getToken()}
+>
+```
+
+The provider throws a loud, actionable error at boot if `authMode`
+is omitted but `jwt` is provided — so the failure mode is "won't
+mount in dev" rather than "401 in production." The error message
+contains the diff above.
+
+## Why two modes
+
+Cookie mode and bearer mode exist because no single deployment shape
+fits every Road consumer. Cookie mode covers same-origin BFFs (Laravel
++ Inertia + React, NestJS BFF + React SPA); bearer mode covers
+headless / mobile / partner integrations where the host genuinely owns
+the JWT.
+
+This is the same pattern Auth0 ships (`@auth0/auth0-react` bearer-only
+plus `@auth0/nextjs-auth0` cookie BFF), Clerk ships (cookie-based
+session with a bearer fallback), and WorkOS AuthKit ships (cookie-only
+authkit-react). Plan
+[10-react-cookie-mode-spec.md](../../../docs/plans/10-react-cookie-mode-spec.md)
+has the detailed rationale.
+
+## Permission-gated UI
+
+Widgets gate themselves. For your own UI, `useCan(buId)` returns a
+callable that checks the current user's effective permissions for that
+business unit (read from the server, cached in React Query):
+
+```tsx
+import { useCan } from "@b1-road/react";
+
+function InviteButton({ buId }: { buId: string }) {
+  const can = useCan(buId); // omit buId to read the BU from <BusinessUnitSwitcher />
+  return can("manage:Member") ? <button>Invite member</button> : null;
+}
+```
+
+`"manage:Member"` is compile-time-checked against Road's permission
+algebra (`RoadPermission` — `${action}:${Subject}` plus `"*"`);
+platform-specific permission strings pass through too. For several
+checks in one render, `useCanMany([...])` resolves them in a single
+batch. This is a UI hint, not a security boundary — see
+[Security model](#security-model).
+
+## Errors
+
+Every failed call rejects with a typed subclass of `RoadApiError`
+carrying the ids you need to find it in Road's logs:
+
+```tsx
+import { RoadForbiddenError, RoadValidationError } from "@b1-road/react";
+
+try {
+  await client.createRole(buId, { name, permissions });
+} catch (err) {
+  if (err instanceof RoadValidationError) {
+    err.fieldErrors; // { name: ["already taken"] }
+  } else if (err instanceof RoadForbiddenError) {
+    err.requestId;   // correlates to the Road API log line
+    err.traceId;     // W3C trace id, when the API emits one
+  }
+}
+```
+
+React errors are deliberately thinner than the server SDKs' — the full
+authorization `DecisionTrace` is surfaced **server-side**, and appended
+to the 403 response body in non-prod via the debug header (see
+[Security model](#security-model)). It is not rehydrated onto the
+browser error object; the browser gets the correlation ids and asks the
+server for the rest.
+
+## Testing
+
+The SDK ships its own in-memory client — no Auth Server, no mock-fetch
+boilerplate, no fake JWTs. Assemble state with the fluent builder and
+hand it to the provider's `client` override:
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import {
+  RoadProvider,
+  BusinessUnitsMgmt,
+  mockClientBuilder,
+} from "@b1-road/react";
+
+const client = mockClientBuilder()
+  .withBusinessUnit({ name: "Acme", role: "Owner" }) // current user is Owner (wildcard)
+  .withMember("Acme", { name: "Alex", email: "alex@x.com", role: "Admin" })
+  .withInvitation("Acme", { email: "pending@x.com", roleName: "Member" })
+  .build();
+
+render(
+  <RoadProvider client={client}>
+    <BusinessUnitsMgmt />
+  </RoadProvider>,
+);
+
+expect(await screen.findByText("Acme")).toBeInTheDocument();
+```
+
+`createMockClient({ empty, latency, failWith })` is the one-liner for
+happy-path / empty / slow-network cases; `mockClientBuilder()` is for
+curated state. Drive error and unauthenticated paths with a scenario:
+
+```tsx
+const client = mockClientBuilder()
+  .withScenario("auth-error") // also: "network-error" | "rate-limit" | "server-error"
+  .withCookieMode({ onUnauthenticated: redirectSpy })
+  .build();
+```
+
+**Scope.** The in-memory client exercises the SDK's hooks, widgets, and
+React Query wiring — not its HTTP transport. It has no `fetch`, so it
+can't assert cookie-mode wire behavior (`credentials: 'include'`, the
+`XSRF-TOKEN` echo, the omitted `Authorization` header). For those, stub
+`globalThis.fetch` against `HttpRoadClient` directly.
+
+## Security model
+
+**Authorization is server-side authoritative.** Every data call goes
+through the Road API, which validates the JWT signature against the
+configured Auth Server's JWKS and rejects forged, expired, or revoked
+tokens. The toolkit's `useCan`/`useCanMany` hooks are a UI hint — they
+read the server's effective-permissions response cached in React Query.
+A user who tampers with their session client-side gets a 401 on the
+first data call, not a privilege escalation.
+
+**Identity in cookie mode.** `getCurrentUser()` calls `GET /me/profile`
+on the Road API. The API resolves the user from the bearer the BFF
+attaches; the SDK never decodes claims locally.
+
+**Identity in bearer mode.** `getCurrentUser()` decodes `sub`,
+`email`, `name`, `picture` from the JWT payload without signature
+verification — a cosmetic-only trust model (a tampered token still
+gets rejected on the next data call). Bearer-mode integrators who
+need server-authoritative identity can call the API's `/me/profile`
+endpoint directly.
+
+## Theming
+
+All widget styles live under a `.road-ui` scope — tokens never leak into the host page's `:root`. Override via `appearance.variables`; the supported keys map to internal CSS variables:
+
+| Variable                 | CSS var                  |
+| ------------------------ | ------------------------ |
+| `colorPrimary`           | `--primary`              |
+| `colorPrimaryForeground` | `--primary-foreground`   |
+| `colorBackground`        | `--background`           |
+| `colorForeground`        | `--foreground`           |
+| `colorMuted`             | `--muted`                |
+| `colorAccent`            | `--accent`               |
+| `colorDanger`            | `--destructive`          |
+| `colorBorder`            | `--border`               |
+| `borderRadius`           | `--radius`               |
+| `fontFamily`             | `--font-family`          |
+
+Accepts any valid CSS color (hex, rgb, hsl, oklch) and CSS lengths.
+
+## Local development
+
+```bash
+npm install
+npm run dev      # opens the playground at http://localhost:5174
+npm run build    # library build → dist/
+npm run typecheck
+```
+
+The playground (`playground/`) mounts the widget against mocked data — no Road API required.

package/dist/__tests__/a11y.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/contract-replay.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/create-role-dialog.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/form-errors.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/pending-invitations.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/api/client.d.ts

@@ -0,0 +1,253 @@
+import { BusinessUnitDetail, CreateBusinessUnitInput, CreateInvitationInput, CreateRoleInput, CurrentUser, Invitation, Member, MyBusinessUnits, MyPermissions, PaginatedList, PaginationInput, Permission, Role, UpdateBusinessUnitInput, UpdateRoleInput } from './types';
+import { RoadApiError } from './errors';
+export interface RoadClient {
+    getCurrentUser(): Promise<CurrentUser>;
+    getMyBusinessUnits(): Promise<MyBusinessUnits>;
+    getMyPermissions(): Promise<MyPermissions>;
+    getBusinessUnit(buId: string): Promise<BusinessUnitDetail>;
+    createBusinessUnit(input: CreateBusinessUnitInput): Promise<BusinessUnitDetail>;
+    updateBusinessUnit(buId: string, input: UpdateBusinessUnitInput): Promise<BusinessUnitDetail>;
+    listMembers(buId: string, pagination?: PaginationInput): Promise<PaginatedList<Member>>;
+    suspendMember(buId: string, memberId: string): Promise<void>;
+    reinstateMember(buId: string, memberId: string): Promise<void>;
+    removeMember(buId: string, memberId: string): Promise<void>;
+    listInvitations(buId: string, pagination?: PaginationInput): Promise<PaginatedList<Invitation>>;
+    createInvitation(buId: string, input: CreateInvitationInput): Promise<Invitation>;
+    cancelInvitation(buId: string, invitationId: string): Promise<void>;
+    resendInvitation(buId: string, invitationId: string): Promise<void>;
+    acceptInvitation(invitationId: string): Promise<void>;
+    rejectInvitation(invitationId: string): Promise<void>;
+    listRoles(buId: string, pagination?: PaginationInput): Promise<PaginatedList<Role>>;
+    getRole(buId: string, roleId: string): Promise<Role>;
+    createRole(buId: string, input: CreateRoleInput): Promise<Role>;
+    updateRole(buId: string, roleId: string, input: UpdateRoleInput): Promise<Role>;
+    deleteRole(buId: string, roleId: string): Promise<void>;
+    listPermissions(buId: string): Promise<Permission[]>;
+    /**
+     * Authoritative batch permission check — calls the IAM engine and
+     * returns a record from permission code → allowed boolean. Honors
+     * the engine's full evaluation (manage → CRUD expansion, wildcards,
+     * scope inheritance) — strictly more accurate than the string-match
+     * useCan does over the cached useMyPermissions map.
+     */
+    authorizeBatch(buId: string, permissions: readonly string[]): Promise<Record<string, boolean>>;
+}
+/**
+ * JWT-source contract. A plain string is accepted for backward-compat,
+ * but integrators should pass a getter so token rotation in the host's
+ * auth state is picked up on every request without forcing a re-render
+ * of <RoadProvider>.
+ */
+export type JwtSource = string | (() => string | Promise<string> | null | undefined);
+/**
+ * How the SDK authenticates against the Road API.
+ *
+ * - `'cookie'` — true BFF mode. The browser holds an opaque session
+ *   cookie; the BFF (Laravel / NestJS) proxies requests to Road and
+ *   attaches the Auth Server JWT server-side. The SDK sends
+ *   `credentials: 'include'` and **no** `Authorization` header. On
+ *   non-GETs the SDK echoes a CSRF token from a cookie into the
+ *   matching header. This is the default and the recommended path per
+ *   the IETF OAuth-for-Browser-Apps BCP.
+ * - `'bearer'` — the host holds the JWT in JS (legacy SPAs, mobile
+ *   webviews, headless / partner integrations). The SDK reads it from
+ *   the `jwt` source and sends `Authorization: Bearer …` on every
+ *   request. No cookie semantics.
+ *
+ * Picking the mode is a deployment-shape decision, not a runtime
+ * switch — flipping it mid-app changes nothing useful and breaks the
+ * server-side auth pipeline.
+ */
+export type RoadAuthMode = "cookie" | "bearer";
+export interface RetryConfig {
+    /** Max attempts including the first try. Default 3. */
+    maxAttempts?: number;
+    /** Base delay in ms for the exponential backoff. Default 250. */
+    baseDelay?: number;
+}
+export interface TelemetryHooks {
+    /** Fires after a request completes successfully. */
+    onRequest?: (event: TelemetryRequestEvent) => void;
+    /** Fires after a request fails (after retries are exhausted). */
+    onError?: (error: RoadApiError, event: TelemetryRequestEvent) => void;
+}
+export interface TelemetryRequestEvent {
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+    /** From the Road response's `x-request-id` header; undefined when the call never reached Road. */
+    requestId?: string;
+    /** From the Road response's `traceparent` header; undefined when absent or the call never reached Road. */
+    traceId?: string;
+    /** Total attempts made before resolving (1 when no retries occurred). */
+    attempts: number;
+}
+export interface HttpClientConfig {
+    apiBaseUrl: string;
+    /**
+     * Transport shape. Defaults to `'cookie'` — the BFF holds the JWT and
+     * the browser ships a session cookie. Pass `'bearer'` only when the
+     * host actually holds the JWT (mobile/headless/partner integrations).
+     */
+    authMode?: RoadAuthMode;
+    /** Required iff `authMode === 'bearer'`. Ignored in cookie mode. */
+    jwt?: JwtSource;
+    /**
+     * Fired once per terminal 401 with a 1s debounce. In cookie mode the
+     * BFF owns refresh; the SDK can't recover and the handler should
+     * redirect to the BFF's login URL. In bearer mode this fires after the
+     * existing rotation attempt (if any) also fails.
+     */
+    onUnauthenticated?: () => void;
+    /**
+     * Cookie name the SDK reads to source a CSRF token on cookie-mode
+     * mutations. Default: `'XSRF-TOKEN'` (Laravel's convention; the
+     * NestJS BFF adopts the same).
+     */
+    csrfCookieName?: string;
+    /**
+     * Header name the SDK writes the CSRF token into on cookie-mode
+     * mutations. Default: `'X-XSRF-TOKEN'`.
+     */
+    csrfHeaderName?: string;
+    /**
+     * Cross-origin opt-in for cookie mode. Default `false` — same-origin
+     * is the recommended deployment. When `true` the BFF must respond
+     * with `Access-Control-Allow-Credentials: true` and matching CORS.
+     * Ignored in bearer mode.
+     */
+    withCredentials?: boolean;
+    /** Per-call retry policy for idempotent (GET) + idempotency-keyed requests. */
+    retry?: RetryConfig;
+    /** Observability hooks for the host app. */
+    telemetry?: TelemetryHooks;
+}
+export declare class HttpRoadClient implements RoadClient {
+    private readonly config;
+    /**
+     * buId → iamScopeId cache. Populated lazily by resolveScopeId(); the
+     * IAM role / permission endpoints are scope-keyed, but the SDK exposes
+     * BU-keyed APIs to integrators — this map bridges the two without
+     * forcing every call site to fetch the BU detail first.
+     */
+    private readonly scopeIdByBuId;
+    /**
+     * Timestamp of the last terminal-401 callback. Used to debounce
+     * `onUnauthenticated` so parallel in-flight requests that all 401 at
+     * once trigger a single redirect rather than a stampede.
+     */
+    private lastUnauthAt;
+    constructor(config: HttpClientConfig);
+    /**
+     * Fire the integrator's onUnauthenticated handler at most once per
+     * 1 second. The window is intentionally short — long enough to absorb
+     * parallel request bursts, short enough that the next manual user
+     * action sees a fresh callback if needed. The handler runs inside a
+     * try/catch so a broken integrator callback can't break the SDK.
+     */
+    private notifyUnauthenticated;
+    /**
+     * Resolve the JWT for this request. Supports the legacy `string`
+     * form for backward-compat, plus the recommended getter form so the
+     * host can rotate tokens without re-mounting <RoadProvider>.
+     */
+    private resolveJwt;
+    private request;
+    private executeRequest;
+    /** Fetch & unwrap a `{ data: T }` envelope. */
+    private fetchData;
+    /**
+     * Fetch a paginated list from a `{ data: T[], meta: { pagination } }`
+     * response. The RequestIdInterceptor on the API side moves the
+     * controller's top-level `pagination` field into `meta` so every
+     * paginated endpoint converges on a single response shape — this
+     * helper centralizes the unwrap.
+     *
+     * Falls back to a single-page response (cursor=null, hasMore=false)
+     * when the response has no pagination metadata, so callers that hit
+     * legacy endpoints still get a valid `PaginatedList<T>`.
+     */
+    private fetchPaginated;
+    /** Resolve buId → iamScopeId, fetching the BU detail once and caching. */
+    private resolveScopeId;
+    /**
+     * Cookie mode calls Road's canonical `GET /me/profile` (the single
+     * server-authoritative profile endpoint). Bearer mode instead decodes the
+     * profile from the JWT's payload claims — the Auth Server's JWT already
+     * carries sub / email / name / picture, so we read them client-side and
+     * avoid an unnecessary round-trip. The id is the JWT `sub` (the stable
+     * Auth Server user id, which matches Road's user references everywhere).
+     *
+     * **Trust model — read carefully (bearer mode).** This path does NOT verify
+     * the JWT signature. The claims are decoded with `atob` and returned as-is.
+     * A tampered token can produce a `CurrentUser` with arbitrary
+     * `name`/`email`/`avatarUrl` — but cannot perform any action against Road,
+     * because the API validates the signature on every data call via the Auth
+     * Server's JWKS endpoint and rejects forged tokens with 401. The risk is
+     * purely cosmetic (the switcher / member rows might display a wrong identity
+     * label).
+     *
+     * If your security review requires server-authoritative identity in bearer
+     * mode too, call `GET /me/profile` directly instead of this method.
+     *
+     * See the SDK README "Security model" section for the full discussion.
+     */
+    getCurrentUser(): Promise<CurrentUser>;
+    /** GET /me/business-units — server wraps in `{data}` like every other endpoint. */
+    getMyBusinessUnits(): Promise<MyBusinessUnits>;
+    /**
+     * Effective permissions across every membership the user has. Issues a
+     * single bulk request to `GET /iam/authorization/me/permissions?scopes=`
+     * — the API returns `{ [scopeId]: PermissionTuple[] }` which we flatten
+     * into the SDK's `Record<buId, string[]>` shape that useCan /
+     * useMyPermissions consume.
+     *
+     * The mutator already server-side-expands `manage` into the CRUD set,
+     * so each BU's list is complete. Wildcards (`*:*`) collapse to `"*"`
+     * for compatibility with useCan's wildcard-short-circuit.
+     *
+     * Resolving every BU's iamScopeId still requires a getBusinessUnit
+     * fetch per BU (cached after first call), but that runs in parallel —
+     * total round-trips: N parallel BU details + 1 batched permissions.
+     * The pre-bulk implementation needed 2N sequential calls.
+     */
+    getMyPermissions(): Promise<MyPermissions>;
+    getBusinessUnit(buId: string): Promise<BusinessUnitDetail>;
+    createBusinessUnit(input: CreateBusinessUnitInput): Promise<BusinessUnitDetail>;
+    updateBusinessUnit(buId: string, input: UpdateBusinessUnitInput): Promise<BusinessUnitDetail>;
+    /**
+     * GET .../members — cursor-paginated. Returns `{ items, pagination }` so
+     * callers can drive infinite scroll. The API ships paginated lists as
+     * `{ data: Member[], meta: { pagination: Pagination, … } }` (the
+     * RequestIdInterceptor absorbs the controller's top-level `pagination`
+     * into `meta`). We normalize that into the SDK's `PaginatedList<T>`.
+     */
+    listMembers(buId: string, pagination?: PaginationInput): Promise<PaginatedList<Member>>;
+    suspendMember(buId: string, memberId: string): Promise<void>;
+    reinstateMember(buId: string, memberId: string): Promise<void>;
+    removeMember(buId: string, memberId: string): Promise<void>;
+    listInvitations(buId: string, pagination?: PaginationInput): Promise<PaginatedList<Invitation>>;
+    createInvitation(buId: string, input: CreateInvitationInput): Promise<Invitation>;
+    cancelInvitation(buId: string, invitationId: string): Promise<void>;
+    resendInvitation(buId: string, invitationId: string): Promise<void>;
+    acceptInvitation(invitationId: string): Promise<void>;
+    rejectInvitation(invitationId: string): Promise<void>;
+    listRoles(buId: string, pagination?: PaginationInput): Promise<PaginatedList<Role>>;
+    getRole(buId: string, roleId: string): Promise<Role>;
+    createRole(buId: string, input: CreateRoleInput): Promise<Role>;
+    updateRole(buId: string, roleId: string, input: UpdateRoleInput): Promise<Role>;
+    deleteRole(buId: string, roleId: string): Promise<void>;
+    listPermissions(buId: string): Promise<Permission[]>;
+    authorizeBatch(buId: string, permissions: readonly string[]): Promise<Record<string, boolean>>;
+}
+/**
+ * Decode a JWT's payload claims without signature verification — used only
+ * to surface the user's identity claims to the widget UI. The actual auth
+ * decisions are made server-side; a tampered token will be rejected by
+ * Road's API on any data call.
+ *
+ * Uses `atob` because the React SDK is browser-only. A node-targeted SDK
+ * would swap this for a Buffer-based implementation.
+ */
+export declare function decodeJwtPayload(jwt: string | undefined): Record<string, unknown> | null;

package/dist/api/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/api/cookie-mode.test.d.ts

@@ -0,0 +1 @@
+export {};