@susilkumar006/widgets-test 1.0.0

package/README.md

@@ -0,0 +1,445 @@
+# @facepe/widgets
+
+The FacePe SDK: a reusable React + TypeScript library that a host application
+installs and compiles into its own bundle. It is **not** a standalone app — it
+has no page, no dev server and nothing to run on its own.
+
+FacePe components will be exported from this package. At this stage it contains
+only the package foundation and a minimal public entry point
+(`SDK_VERSION`).
+
+## React comes from your application
+
+`react` and `react-dom` are **peer dependencies** (React 18 or 19). The SDK does
+not ship its own copy: the build leaves every `react` / `react-dom` import
+external, so the host's React is the only one in the final bundle. A second copy
+would break hooks.
+
+## Install dependencies
+
+```bash
+cd facepe-sdk
+npm install
+```
+
+This also installs React as a dev dependency, used only for type checking and
+building the SDK itself.
+
+## Build
+
+```bash
+npm run build
+```
+
+This runs these steps, and stops at the first failure:
+
+1. `lint-css` checks the stylesheets against the styling contract.
+2. `vite build` compiles `src/` in library mode to JavaScript.
+3. `tsc` generates the TypeScript declaration files (and `emit-cjs-types` their CommonJS copies).
+4. `emit-schemas` generates the JSON Schemas of the payload types.
+
+Type check without building:
+
+```bash
+npm run typecheck
+```
+
+## Build output
+
+Everything is written to `dist/`, which is the only folder that is published:
+
+| File | Purpose |
+| --- | --- |
+| `dist/index.js` | ES module build (`import`) |
+| `dist/index.cjs` | CommonJS build (`require`) |
+| `dist/index.d.ts` / `dist/index.d.cts` | TypeScript declarations (ESM / CommonJS) |
+| `dist/styles.css` | Component styles, published as `@facepe/widgets/styles.css` |
+| `dist/schemas/*.schema.json` | JSON Schemas of the payloads, published as `@facepe/widgets/schemas/…` |
+| `*.map` | Source maps (with sources embedded) |
+
+## Using it from a React app
+
+```tsx
+import { FacePeProvider, FacePeForm } from '@facepe/widgets';
+import '@facepe/widgets/styles.css'; // once, anywhere in the app
+
+<FacePeProvider config={{ mode: 'edit', locale: 'en-IN' }}>
+  <FacePeForm onSubmit={(event) => save(event.payload)} />
+</FacePeProvider>
+```
+
+### Who can use FacePe: the access flow
+
+Access is granted top-down, and every level is checked on every request:
+
+```text
+Super admin   creates the company, enables "FacePe SDK" and/or "FacePe API" for it,
+              and grants it avatars
+Company admin creates users, assigns each user avatar_ids, and gives a user
+              SDK/API access: Dashboard → Users → SDK / API → access key + secret key
+User's app    its SERVER exchanges the keys for a 5-minute token; the SDK (or the
+              app's own API calls) use that token
+Every call    company allowed? → user allowed? → this avatar_id assigned? → allowed
+```
+
+Revoking or regenerating a user's keys, disabling the user, or switching the
+company's access off takes effect on the next request, not when tokens expire.
+
+### The avatar: `<FacePeAvatar />`
+
+The same avatar experience as on the FacePe website: the same avatar, trained
+prompt, voice and features, embedded in your page. The minimum setup:
+
+```tsx
+import '@facepe/widgets/styles.css';
+import { FacePeProvider, FacePeAvatar } from '@facepe/widgets';
+
+<FacePeProvider
+  config={{}}
+  apiBaseUrl="https://api.facepe.com/api/v1/sdk"
+  getToken={({ forceRefresh }) =>                                  // YOUR server, below
+    fetch(forceRefresh ? '/facepe-token?refresh=1' : '/facepe-token')
+      .then((r) => (r.ok ? r.text() : Promise.reject(new Error(`token ${r.status}`))))}
+>
+  <FacePeAvatar />
+</FacePeProvider>
+```
+
+No avatar_id is needed: with only the user's keys (on your server), the
+component loads the avatars assigned to that user and shows them to choose
+from (the first is selected; with one avatar there is no choice to make). To
+show one particular avatar instead, pass its `avatarId` to the provider or
+the component.
+
+`<FacePeAvatar>` shows the avatar's portrait and a **Start conversation**
+button (browsers allow sound and the microphone only after a click). It then
+streams the avatar's video and voice, listens to the user's microphone, and
+shows captions; **Mute** and **End** control the session. Props: `avatarId`
+(optional; overrides the provider's), `language` (`'en'`, `'hi'`, …), `autoStart`,
+`captions`, plus the usual `emphasis`, `size`, `density`. Events:
+`onSessionStart`, `onSessionEnd`, `onTranscript`, `onOrderUpdate`, `onError`.
+Handle: `start()`, `end()`, `setMuted(muted)`, `focus()`. Slot: `controls`
+replaces the built-in buttons.
+
+The connection libraries are installed with the package and loaded in their
+own chunks only when an avatar is shown, so they cost nothing on other pages.
+An avatar is described only by its name, gender, portrait, description and
+languages: where it comes from is never part of the API or the SDK.
+
+### Connecting: keys on your server, a token in the browser
+
+The secret key must never be in browser code. Your server exchanges the keys
+and hands the browser only the short-lived token:
+
+```ts
+// Your server (e.g. Express), with the keys from the FacePe dashboard in env vars.
+// Reuse the token for its 5 minutes; fetch a new one only near expiry or on ?refresh=1.
+let cached = { token: null, expiresAt: 0 };
+app.get('/facepe-token', async (req, res) => {
+  if (req.query.refresh !== '1' && cached.token && cached.expiresAt - Date.now() > 30_000) {
+    return res.type('text').send(cached.token);
+  }
+  const r = await fetch('https://api.facepe.com/api/v1/sdk/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      accessKey: process.env.FACEPE_ACCESS_KEY,
+      secretKey: process.env.FACEPE_SECRET_KEY,
+      channel: 'sdk',                       // 'api' for direct API use
+    }),
+  });
+  const body = await r.json();
+  if (!r.ok) return res.status(r.status).json(body.error); // e.g. access switched off
+  cached = { token: body.data.token, expiresAt: Date.now() + body.data.expiresIn * 1000 };
+  res.type('text').send(cached.token);
+});
+```
+
+- `apiBaseUrl` is the FacePe gateway, `…/api/v1/sdk`. The SDK calls nothing else.
+- **Cache the token** for its lifetime (`expiresIn`, 5 minutes) in `getToken`
+  and fetch a new one only when it is about to expire or `forceRefresh` is
+  true; the SDK asks for a token on every request, and a fresh exchange each
+  time adds a round trip to every call.
+- `getToken` receives `{ audience: 'app-b', forceRefresh }` and returns a string
+  or a Promise. After a 401 it is called again with `forceRefresh: true` and
+  the request is retried once. If the retry is refused too, `onSessionExpired` fires.
+- Every request carries `X-Request-Id` (correlation) and `X-FacePe-SDK-Version`.
+
+### Using the API directly (no SDK)
+
+Exchange the keys with `"channel": "api"` (the company needs API access), then
+call the gateway with `Authorization: Bearer <token>`:
+
+| Request | Returns |
+| --- | --- |
+| `POST /api/v1/sdk/token` `{ accessKey, secretKey, channel }` | `{ token, expiresIn, channel }` |
+| `GET /api/v1/sdk/session` | the company, the user, the user's `avatarIds` |
+| `GET /api/v1/sdk/avatars` | the avatars assigned to the user |
+| `GET /api/v1/sdk/avatars/:avatarId` | one avatar (403 if not assigned) |
+| `POST /api/v1/sdk/avatars/:avatarId/sessions` `{ language? }` | how to connect: `connection` (`{ type: 'room', url, token }` or `{ type: 'stream', token, greeting }`), and a `usageId` |
+| `POST /api/v1/sdk/avatar-sessions/:usageId/end` | closes the session (usage minutes) |
+
+Refusals: `401` for missing, invalid, expired or revoked credentials; `403`
+when the company's access is off, the user is disabled, or the avatar is not
+assigned to the user; `429` when one access key exceeds its rate limit
+(`SDK_RATE_LIMIT_PER_MIN`, default 120 per minute).
+
+### Data: pass an id, or pass the data
+
+Each component either shows data the host passes in, or, given only an
+`entityId`, fetches it through the gateway (architecture §7.5):
+
+| Component | Host passes | Or `entityId` = | Fetched from |
+| --- | --- | --- | --- |
+| `FacePeTimeline` | `items` | an order id | `GET /orders/:id/timeline`, the order's status history |
+| `FacePePicker` | `options` | a location id | `GET /locations/:id/categories`, its menu categories |
+| `FacePeForm` | `initialValues` | an order id | `GET /orders/:id/customer`; Submit saves with `PUT` |
+
+Data passed by the host always wins; nothing is fetched then. While loading,
+a component shows a loading state; a failed load raises `onError` with the
+gateway's error code. Payloads are validated on arrival, and unknown fields
+are ignored.
+
+`entityId` can also be set once on the provider's `config`. It then applies
+to every component, so set it per component when they show different
+entities (an order and a location).
+
+JSON Schemas of every payload ship in the package:
+`@facepe/widgets/schemas/FacePeTimelinePayload.schema.json`, and likewise
+`FacePePickerOptionsPayload`, `FacePeCustomerPayload`, `FacePeTimelineItem`,
+`FacePePickerOption`, `FacePeFormValues`, `FacePeEventMeta`, `FacePeError`,
+`FacePeNavigationRequest` and `FacePeTelemetryEvent`.
+
+### Telemetry
+
+Pass your own sink; the SDK makes no analytics calls of its own:
+
+```tsx
+<FacePeProvider config={config} telemetry={{ track: (e) => analytics.log(e) }}>
+```
+
+`track` receives one record per component event (`name` = the event type)
+and one per API call (`name` = `'api.request'`, with `method`, `path`,
+`status`, `outcome` and `durationMs`). Every record carries the `sdkVersion`
+and the `correlationId` (the same as the event's, or the request's
+`X-Request-Id`). Event payloads are never included, since they can hold what
+the user typed; `error` events carry only the error code. A sink that throws
+is reported and ignored.
+
+### Placement: inline, page, overlay
+
+The host decides where an experience appears; the component inside is the same.
+
+```tsx
+<FacePeForm />                                   {/* inline: inside an existing page */}
+<FacePePage><FacePeTimeline items={items} /></FacePePage>         {/* full view */}
+<FacePeOverlay open={open} label="Edit" onClose={() => setOpen(false)}>
+  <FacePeForm onCancel={() => setOpen(false)} />
+</FacePeOverlay>                                  {/* modal dialog */}
+<FacePeOverlay variant="drawer" open={open} label="Details" onClose={close}>
+  …
+</FacePeOverlay>                                  {/* side drawer */}
+```
+
+Titles, breadcrumbs, routing and action bars stay with the host.
+
+### Navigation
+
+Components never change the URL. They raise `navigate` events with a
+`{ to, params?, replace? }` request; wire them to your router once on the
+provider (or per component):
+
+```tsx
+<FacePeProvider config={config} onNavigate={(e) => router.navigate(e.payload.to)}>
+```
+
+### Events
+
+Every `on…` callback receives `{ type, payload, meta }`. `meta` carries
+`schemaVersion` (1), `correlationId`, `timestamp`, `sdkVersion`, `source`
+(the component) and, when the component has one, `entityId`. Events never
+contain credentials.
+
+### Errors
+
+Each component has its own error boundary: a failure inside it does not take
+your page down. It raises `onError` with code `RENDER_FAILED` and shows the
+`fallback` slot (or a short message). Remount it (e.g. a new `key`) to retry.
+
+### Imperative handles
+
+Reach them with a `ref`. Every method returns a `Promise<Result>` and never throws.
+
+| Component | Methods |
+| --- | --- |
+| `FacePeForm` | `focus`, `validate`, `reset` |
+| `FacePePicker` | `focus`, `reset` |
+| `FacePeTimeline` | `focus`, `reset`, `scrollToSection(id)` |
+
+Submitting, selecting and cancelling are user actions; they reach you as
+events (`onSubmit`, `onSelect`, `onCancel`), not as handle methods.
+
+### Customization
+
+The package hard-codes no colours and no fonts. With nothing set, a component
+inherits the host page's text colour, font and size, has a transparent
+surface, and derives borders and muted text from the text colour. You choose
+the look, from the least to the most effort:
+
+1. **Design tokens (L1)** on the provider: `theme={{ colorSurface,
+   colorSurfaceMuted, colorText, colorMuted, colorBorder, colorAccent,
+   colorOnAccent, colorDanger, colorSuccess, fontFamily, fontSize, spacing,
+   radius, shadow }}`. For dark mode pass `darkTheme` too, and set
+   `colorScheme="light" | "dark"` from your own app's setting: dark tokens
+   override the main ones per token. The SDK never reads the system preference
+   itself.
+2. **Variants (L2)** on every component: `emphasis="subtle" | "default" |
+   "strong"`, `size="small" | "medium" | "large"`, `density`; per component,
+   `variant` — `FacePeForm`: `"stacked" | "inline"`, `FacePePicker`:
+   `"list" | "grid"`.
+3. **Slots (L3)**: `FacePeForm` — `header`, `actions` (render function given
+   `{ submit, cancel, submitting, readOnly }`), `footer`; `FacePePicker` —
+   `header`, `option` (render function given `{ option, selected, disabled }`),
+   `emptyState`; `FacePeTimeline` — `item`, `emptyState`; all — `fallback`.
+4. **CSS variables (L4)**, documented; set them on any ancestor:
+
+| Variable | Default when unset |
+| --- | --- |
+| `--fp-color-surface` | transparent (the host's background) |
+| `--fp-color-surface-muted` | a light tint of the text colour |
+| `--fp-color-text` | inherited from the host |
+| `--fp-color-muted` | the text colour, partly transparent |
+| `--fp-color-border` | the text colour, mostly transparent |
+| `--fp-color-accent` | the text colour (the primary action is outlined) |
+| `--fp-color-on-accent` | inherited text colour |
+| `--fp-color-danger` | the text colour |
+| `--fp-color-success` | the text colour |
+| `--fp-font-family` | inherited from the host |
+| `--fp-font-size` | inherited from the host |
+| `--fp-spacing` | `0.25rem` (gaps and padding are multiples) |
+| `--fp-radius` | `0.375rem` (frames use 1.5×) |
+| `--fp-shadow` | a soft shadow tinted from the text colour (`emphasis="strong"`) |
+| `--fp-content-max-width` | `32rem` (form, picker; `none` in page/overlay) |
+
+Components adapt to the width of their container (container queries), not
+the viewport, so they fit a sidebar or a full page alike.
+
+`npm run lint:css` (also run by `npm run build`) fails the build if a
+stylesheet hard-codes a colour or font, sets a `--fp-*` token, or uses an
+unscoped selector.
+
+### Using the SDK in a Tailwind app
+
+It works as is: the SDK's classes are scoped, so Tailwind and the SDK cannot
+clash, and its buttons keep their look under Tailwind's Preflight reset.
+Style it with Tailwind through the documented variables (arbitrary
+properties) and through slots — not by targeting the SDK's internal class
+names, which change with every build.
+
+```jsx
+<div className="[--fp-color-accent:theme(colors.violet.600)] [--fp-color-on-accent:white] [--fp-radius:theme(borderRadius.xl)]">
+  <FacePeForm slots={{ header: <h3 className="text-lg font-semibold">Contact us</h3> }} />
+</div>
+```
+
+With Tailwind v4, use its CSS variables instead of `theme()`:
+`[--fp-color-accent:var(--color-violet-600)]`.
+
+Component styles are scoped (CSS Modules) and ship as one stylesheet,
+`@facepe/widgets/styles.css`. Import it once; without it the components render
+unstyled.
+
+Until the package is published to a registry, a local app can install it
+straight from this folder:
+
+```bash
+npm install ../facepe-sdk
+```
+
+Everything public is imported from the package root. Deeper paths such as
+`@facepe/widgets/dist/...` are blocked by the package `exports` map, so
+internal files can change without breaking your app.
+
+## Compatibility
+
+| | Supported | Verified with |
+| --- | --- | --- |
+| React (peer dependency) | 18 and 19 | 18.3 (test suites) |
+| TypeScript consumers | 5.x; `bundler`, `node16` ESM and `node16` CommonJS resolution | 5.9, all three resolution modes |
+| Bundlers | any that reads `exports` and CSS imports | Vite 7 (SDK build), webpack 5 (`tests/webpack.test.mjs`) |
+| Browsers | Chrome / Edge 111+, Safari 16.2+, Firefox 113+ (needs container queries, `<dialog>`, `color-mix()`) | Chrome (automated checks) |
+
+Report an incompatibility rather than working around it in your app.
+
+## Testing
+
+```bash
+npm test                 # build, then every suite in tests/
+npm run test:only picker # suites whose file name contains "picker" (needs a build)
+npm run api:check        # public API unchanged vs etc/widgets.api.md
+npm run size             # bundle budget (150 KB gzip) and no bundled React
+```
+
+The suites test the built package the way a host consumes it: behaviour of
+each component in jsdom, the TypeScript contract in three module setups,
+telemetry and gateway data against a fake gateway, and a webpack 5 host build.
+
+When you change the public API on purpose, run `npm run api:update` and
+commit `etc/widgets.api.md` with the change; reviewers see exactly what changed
+in the contract, and the version bump (major for a breaking change) follows
+from it. CI (`.github/workflows/sdk.yml`) runs all of the above on every pull
+request, plus the gateway tests.
+
+## Releasing
+
+Only CI publishes (`npm publish` refuses anywhere else):
+
+1. Bump `version` in `package.json` and move the `[Unreleased]` notes in
+   `CHANGELOG.md` under a `## [x.y.z]` heading.
+2. Merge to `main`, then push the tag: `git tag widgets-vx.y.z && git push origin widgets-vx.y.z`.
+3. The "SDK release" workflow re-runs every check, signs a build-provenance
+   attestation, writes an SBOM, publishes the tarball, and creates a GitHub
+   release with the tarball, SBOM and notes.
+
+Support: the current and previous minor lines get security and critical
+fixes (N-1). Deprecated exports, slots and tokens keep working, with a
+warning in the changelog, for at least one minor release before removal.
+
+## Upgrading host apps
+
+Host apps get an upgrade pull request for each release from Renovate by
+extending the preset in this folder:
+
+```json
+{ "extends": ["github>Dharun4242/Facepe//facepe-sdk/renovate-host-preset"] }
+```
+
+Pin the version (the preset does), keep the lockfile committed, and let the
+host's CI and visual regression run on the PR. To roll back, revert to the
+previous pinned version.
+
+## Adding to the public API
+
+`src/index.ts` is the only public entry point and holds exports only. Add each
+new public component, hook or type there by name (`export { X } from ...`,
+`export type { Y } from ...`), never with `export *`. Anything not listed there
+is internal.
+
+## Project layout
+
+```
+facepe-sdk/
+├── src/
+│   ├── index.ts       public entry point: the only file consumers import from
+│   ├── components/    FacePe components (Form/, Picker/, Timeline/, Placement/)
+│   ├── context/       FacePeProvider and useFacePe
+│   ├── types/         public TypeScript contracts
+│   ├── events/        event emitter shared by components (not public)
+│   ├── api/           API client, one per provider (not public)
+│   ├── version.ts     SDK_VERSION
+│   └── globals.d.ts   build-time constants and CSS Module typings
+├── scripts/           build helpers (CommonJS declarations)
+├── package.json       package metadata, exports, peer dependencies
+├── tsconfig.json      strict TypeScript, declaration output
+└── vite.config.ts     library-mode build, React kept external
+```

package/dist/api/FacePeApiClient.d.cts

@@ -0,0 +1,74 @@
+import type { FacePeTelemetryReporter } from '../events/telemetry.cjs';
+import type { AsyncResult, FacePeSessionExpiredPayload, FacePeTokenProvider, JsonValue, Result } from '../types/index.cjs';
+/** Request header carrying the correlation id (the gateway's agreed name). */
+export declare const CORRELATION_HEADER = "X-Request-Id";
+/** Request header carrying the SDK version, for the gateway's per-version metrics. */
+export declare const SDK_VERSION_HEADER = "X-FacePe-SDK-Version";
+/** The audience every token is requested for (architecture §7.4: the FacePe service). */
+export declare const TOKEN_AUDIENCE = "app-b";
+/** Per-attempt timeout when neither the provider nor the call sets one. */
+export declare const DEFAULT_TIMEOUT_MS = 15000;
+/** Provider settings, read afresh on every request. */
+export type FacePeApiSettings = {
+    readonly baseUrl?: string;
+    readonly getToken?: FacePeTokenProvider;
+    readonly timeoutMs?: number;
+};
+export type FacePeApiClientOptions = {
+    readonly settings: () => FacePeApiSettings;
+    /** Called once a request is refused even after a fresh token. */
+    readonly onSessionExpired?: (payload: FacePeSessionExpiredPayload) => void;
+    /** Receives one `api.request` telemetry record per call. */
+    readonly onTelemetry?: FacePeTelemetryReporter;
+};
+/** Turns response data into the type a caller expects, or a Failure if it does not fit. */
+export type FacePeDecoder<T> = (data: JsonValue) => Result<T>;
+export type FacePeQuery = Readonly<Record<string, string | number | boolean | null | undefined>>;
+export type FacePeRequestOptions = {
+    /** Query-string parameters; `null`/`undefined` ones are left out. */
+    readonly query?: FacePeQuery;
+    /** Overrides the provider's per-attempt timeout for this call. */
+    readonly timeoutMs?: number;
+    /** Lets the caller cancel (e.g. on unmount); resolves to Failure ABORTED. */
+    readonly signal?: AbortSignal;
+    /** Let the request outlive the page (e.g. ending a session as the tab closes). */
+    readonly keepalive?: boolean;
+};
+type Decoded<T> = FacePeRequestOptions & {
+    readonly decode: FacePeDecoder<T>;
+};
+export declare class FacePeApiClient {
+    private readonly options;
+    /** The last token getToken returned (memory only), for keepalive requests. */
+    private lastToken;
+    constructor(options: FacePeApiClientOptions);
+    /**
+     * A full address for an asset the API returned as a path (e.g. an avatar's
+     * picture, "/avatars/aria.jpg"): resolved against the API's address, not
+     * the host page's. Absolute URLs are returned unchanged.
+     */
+    assetUrl(url: string | null | undefined): string | null;
+    get(path: string, options?: FacePeRequestOptions): AsyncResult<JsonValue>;
+    get<T>(path: string, options: Decoded<T>): AsyncResult<T>;
+    post(path: string, body?: JsonValue, options?: FacePeRequestOptions): AsyncResult<JsonValue>;
+    post<T>(path: string, body: JsonValue | undefined, options: Decoded<T>): AsyncResult<T>;
+    put(path: string, body?: JsonValue, options?: FacePeRequestOptions): AsyncResult<JsonValue>;
+    put<T>(path: string, body: JsonValue | undefined, options: Decoded<T>): AsyncResult<T>;
+    patch(path: string, body?: JsonValue, options?: FacePeRequestOptions): AsyncResult<JsonValue>;
+    patch<T>(path: string, body: JsonValue | undefined, options: Decoded<T>): AsyncResult<T>;
+    delete(path: string, options?: FacePeRequestOptions): AsyncResult<JsonValue>;
+    delete<T>(path: string, options: Decoded<T>): AsyncResult<T>;
+    private send;
+    private perform;
+    /** The token to send, or `null` when the provider has no token provider. */
+    private token;
+    /** One HTTP attempt, response body included, under one timeout. */
+    private attempt;
+    /**
+     * Parses the body. The FacePe backend answers `{ success: true, data }` or
+     * `{ success: false, error: { code, message } }`; the envelope is unwrapped
+     * and its error code kept. Any other JSON body is taken as the data itself.
+     */
+    private read;
+}
+export {};

package/dist/api/FacePeApiClient.d.ts

@@ -0,0 +1,74 @@
+import type { FacePeTelemetryReporter } from '../events/telemetry.js';
+import type { AsyncResult, FacePeSessionExpiredPayload, FacePeTokenProvider, JsonValue, Result } from '../types/index.js';
+/** Request header carrying the correlation id (the gateway's agreed name). */
+export declare const CORRELATION_HEADER = "X-Request-Id";
+/** Request header carrying the SDK version, for the gateway's per-version metrics. */
+export declare const SDK_VERSION_HEADER = "X-FacePe-SDK-Version";
+/** The audience every token is requested for (architecture §7.4: the FacePe service). */
+export declare const TOKEN_AUDIENCE = "app-b";
+/** Per-attempt timeout when neither the provider nor the call sets one. */
+export declare const DEFAULT_TIMEOUT_MS = 15000;
+/** Provider settings, read afresh on every request. */
+export type FacePeApiSettings = {
+    readonly baseUrl?: string;
+    readonly getToken?: FacePeTokenProvider;
+    readonly timeoutMs?: number;
+};
+export type FacePeApiClientOptions = {
+    readonly settings: () => FacePeApiSettings;
+    /** Called once a request is refused even after a fresh token. */
+    readonly onSessionExpired?: (payload: FacePeSessionExpiredPayload) => void;
+    /** Receives one `api.request` telemetry record per call. */
+    readonly onTelemetry?: FacePeTelemetryReporter;
+};
+/** Turns response data into the type a caller expects, or a Failure if it does not fit. */
+export type FacePeDecoder<T> = (data: JsonValue) => Result<T>;
+export type FacePeQuery = Readonly<Record<string, string | number | boolean | null | undefined>>;
+export type FacePeRequestOptions = {
+    /** Query-string parameters; `null`/`undefined` ones are left out. */
+    readonly query?: FacePeQuery;
+    /** Overrides the provider's per-attempt timeout for this call. */
+    readonly timeoutMs?: number;
+    /** Lets the caller cancel (e.g. on unmount); resolves to Failure ABORTED. */
+    readonly signal?: AbortSignal;
+    /** Let the request outlive the page (e.g. ending a session as the tab closes). */
+    readonly keepalive?: boolean;
+};
+type Decoded<T> = FacePeRequestOptions & {
+    readonly decode: FacePeDecoder<T>;
+};
+export declare class FacePeApiClient {
+    private readonly options;
+    /** The last token getToken returned (memory only), for keepalive requests. */
+    private lastToken;
+    constructor(options: FacePeApiClientOptions);
+    /**
+     * A full address for an asset the API returned as a path (e.g. an avatar's
+     * picture, "/avatars/aria.jpg"): resolved against the API's address, not
+     * the host page's. Absolute URLs are returned unchanged.
+     */
+    assetUrl(url: string | null | undefined): string | null;
+    get(path: string, options?: FacePeRequestOptions): AsyncResult<JsonValue>;
+    get<T>(path: string, options: Decoded<T>): AsyncResult<T>;
+    post(path: string, body?: JsonValue, options?: FacePeRequestOptions): AsyncResult<JsonValue>;
+    post<T>(path: string, body: JsonValue | undefined, options: Decoded<T>): AsyncResult<T>;
+    put(path: string, body?: JsonValue, options?: FacePeRequestOptions): AsyncResult<JsonValue>;
+    put<T>(path: string, body: JsonValue | undefined, options: Decoded<T>): AsyncResult<T>;
+    patch(path: string, body?: JsonValue, options?: FacePeRequestOptions): AsyncResult<JsonValue>;
+    patch<T>(path: string, body: JsonValue | undefined, options: Decoded<T>): AsyncResult<T>;
+    delete(path: string, options?: FacePeRequestOptions): AsyncResult<JsonValue>;
+    delete<T>(path: string, options: Decoded<T>): AsyncResult<T>;
+    private send;
+    private perform;
+    /** The token to send, or `null` when the provider has no token provider. */
+    private token;
+    /** One HTTP attempt, response body included, under one timeout. */
+    private attempt;
+    /**
+     * Parses the body. The FacePe backend answers `{ success: true, data }` or
+     * `{ success: false, error: { code, message } }`; the envelope is unwrapped
+     * and its error code kept. Any other JSON body is taken as the data itself.
+     */
+    private read;
+}
+export {};

package/dist/api/FacePeApiContext.d.cts

@@ -0,0 +1,8 @@
+import type { FacePeApiClient } from './FacePeApiClient.cjs';
+/**
+ * Internal: the API client of the nearest `<FacePeProvider>`. Kept apart from
+ * the public context so `useFacePe()` and `FacePeContextValue` are unchanged.
+ */
+export declare const FacePeApiContext: import("react").Context<FacePeApiClient | null>;
+/** The API client of the nearest `<FacePeProvider>`, for SDK components. */
+export declare function useFacePeApi(): FacePeApiClient;

package/dist/api/FacePeApiContext.d.ts

@@ -0,0 +1,8 @@
+import type { FacePeApiClient } from './FacePeApiClient.js';
+/**
+ * Internal: the API client of the nearest `<FacePeProvider>`. Kept apart from
+ * the public context so `useFacePe()` and `FacePeContextValue` are unchanged.
+ */
+export declare const FacePeApiContext: import("react").Context<FacePeApiClient | null>;
+/** The API client of the nearest `<FacePeProvider>`, for SDK components. */
+export declare function useFacePeApi(): FacePeApiClient;

package/dist/api/decoders.d.cts

@@ -0,0 +1,48 @@
+/**
+ * Internal: runtime validation of gateway payloads — the trust boundary, the
+ * one place types are checked at runtime (architecture §7.5). Each decoder
+ * accepts the documented shape, ignores unknown fields (forward
+ * compatibility) and turns anything else into Failure INVAL_RESPONSE-style
+ * `INVALID_PAYLOAD`, never an exception.
+ */
+import type { FacePeAvatarInfo, FacePeFormValues, FacePePickerOption, FacePeTimelineItem } from '../types/index.cjs';
+import type { FacePeDecoder } from './FacePeApiClient.cjs';
+/** GET /orders/:id/timeline → `{ items: FacePeTimelineItem[] }`. */
+export declare const decodeTimeline: FacePeDecoder<readonly FacePeTimelineItem[]>;
+/** GET /locations/:id/categories → `{ options: FacePePickerOption[] }`. */
+export declare const decodePickerOptions: FacePeDecoder<readonly FacePePickerOption[]>;
+/** GET/PUT /orders/:id/customer → `{ name, email, notes }`. */
+export declare const decodeFormValues: FacePeDecoder<FacePeFormValues>;
+/** GET /avatars/:avatarId → `{ avatar }`. */
+export declare const decodeAvatar: FacePeDecoder<FacePeAvatarInfo>;
+/** GET /avatars → `{ avatars }`: the avatars the signed-in user may use. Entries that do not decode are skipped. */
+export declare const decodeAvatarList: FacePeDecoder<readonly FacePeAvatarInfo[]>;
+/**
+ * What POST /avatars/:avatarId/sessions returns: how to connect. The gateway
+ * never says where an avatar comes from, only the kind of connection:
+ * `room` (join a media room) or `stream` (a hosted stream).
+ */
+export type FacePeAvatarConnection = {
+    readonly type: 'stream';
+    readonly usageId: string | null;
+    readonly avatar: FacePeAvatarInfo;
+    readonly token: string;
+    readonly greeting: string | null;
+} | {
+    readonly type: 'room';
+    readonly usageId: string | null;
+    readonly avatar: FacePeAvatarInfo;
+    readonly url: string;
+    readonly token: string;
+};
+export declare const decodeAvatarConnection: FacePeDecoder<FacePeAvatarConnection>;
+/** Gateway paths, one per component (entity ids are path-encoded). */
+export declare const gatewayPath: {
+    readonly avatars: "/avatars";
+    readonly avatar: (avatarId: string) => string;
+    readonly avatarSessions: (avatarId: string) => string;
+    readonly endAvatarSession: (usageId: string) => string;
+    readonly timeline: (orderId: string) => string;
+    readonly pickerOptions: (locationId: string) => string;
+    readonly customer: (orderId: string) => string;
+};