@checktiv/sdk-web 1.0.0 → 1.2.0

package/README.md

@@ -1,39 +1,41 @@
 # @checktiv/sdk-web
 
-Customer-embed Web SDK for the Checktiv identity verification platform. Published on
-npm as `@checktiv/sdk-web`; the internal workspace name is `@rf/sdk-web`.
+The customer-embed Web SDK for the Checktiv identity verification platform. Embed
+identity verification, fraud-signal collection, and custom intake forms directly in
+your own web app, with full control over look, feel, and journey.
 
-Two surfaces ship from this package:
+Two ways to use it ship from one package:
 
-- **ESM npm package** (`@checktiv/sdk-web` and subpaths) - tree-shakeable ESM
-  modules for bundler-based apps. React peer dependency is optional; `react`/`react-dom`
-  are not bundled.
-- **CDN IIFE** (`window.Checktiv`) - the self-contained bundle served by `sdk-cdn`
-  at `https://sdk.<region>.<apex>/v1/sdk.js`. Includes all modules eagerly so a single
-  `<script>` tag is sufficient. A legacy `window.AutohostKyc` alias is kept for
-  existing customer snippets; auto-discover attributes `[data-checktiv]` (preferred)
-  and `[data-autohost-kyc]` (back-compat) work on both the CDN and npm paths.
+- **ESM npm package** (`@checktiv/sdk-web` and its subpaths) - tree-shakeable ESM
+  modules for bundler-based apps (Vite, webpack, Rollup, Next.js, and friends). The
+  React wrapper is an optional subpath; `react` / `react-dom` are never bundled.
+- **CDN `<script>` tag** (`window.Checktiv`) - a self-contained bundle. A single
+  script tag is enough: every module is included, so no build step is required.
 
-## Install (npm)
+## Install
 
 ```bash
 npm install @checktiv/sdk-web
 # or: pnpm add @checktiv/sdk-web
+# or: yarn add @checktiv/sdk-web
 ```
 
-`react` and `react-dom` are **optional peer dependencies**. Install them only when
-using the `./react` subpath.
+`react` and `react-dom` are **optional peer dependencies**. Install them only if you
+use the `./react` subpath. Everything else works without React.
 
-## CDN snippet
+## CDN usage
+
+Load the moving pointer for the latest release:
 
 ```html
-<!-- Moving pointer - always the latest release. No SRI: content changes on every release. -->
+<!-- Moving pointer - always the latest release. -->
 <script src="https://sdk.us.checktiv.com/v1/sdk.js" crossorigin="anonymous"></script>
 ```
 
-This loads the latest release. SRI is not usable on the moving `/v1/sdk.js` pointer
-because its content changes on every release. For production, pin to the immutable
-versioned URL and include a Subresource Integrity hash from the release notes:
+The moving `/v1/sdk.js` pointer always serves the newest release, so its bytes change
+over time. That means a Subresource Integrity (SRI) hash cannot be used on it. For
+production, pin to the immutable versioned URL and add the SRI hash published in the
+release notes, so the exact bytes your page loads are locked and verified:
 
 ```html
 <script
@@ -43,71 +45,145 @@ versioned URL and include a Subresource Integrity hash from the release notes:
 ></script>
 ```
 
-## The two-line surface
+Use the region host that matches your account (for example `sdk.us.checktiv.com` or
+`sdk.eu.checktiv.com`). The CDN bundle exposes the same API as the npm package on the
+`window.Checktiv` global.
+
+## Quickstart: the two-line surface
 
 ```js
 import { init } from '@checktiv/sdk-web';
-import '@checktiv/sdk-web/idv'; // self-registers the IDV module
+import '@checktiv/sdk-web/idv'; // self-registers the managed IDV module
 
 const client = init({
   publishableKey: 'ah_pk_us_test_...',
   getSessionToken: async (ctx) => {
+    // Your server exchanges its secret key for a short-lived browser token.
     const res = await fetch('/api/checktiv/token', {
       method: 'POST',
-      body: JSON.stringify({ reason: ctx.reason }),
       headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ reason: ctx.reason }),
     });
     return (await res.json()).token;
   },
 });
 
 // Server-driven: renders whatever modules the session declares.
-client.mountProvisioned({
+const handle = client.mountProvisioned({
   target: document.getElementById('checktiv-container'),
   onEvent: (event) => console.log(event),
 });
+
+// Later, when navigating away:
+// handle.destroy();
 ```
 
-`init()` never makes a network request. `mountProvisioned()` reads the
-server-declared modules from the session (`GET /sdk/v1/sessions/me`) and renders
-each one. Your secret key never appears in client code.
+Key properties of this design:
+
+- `init()` makes **no network call**. It only sets up the client and the token
+  callback.
+- Your **secret key never touches client code**. `getSessionToken` returns a
+  short-lived browser token that your server mints; the SDK only ever holds that
+  token.
+- **The server drives composition.** `mountProvisioned()` reads the modules the
+  session declares and renders each one, so you can change the journey server-side
+  without shipping new client code.
 
 ## Published subpaths
 
-All subpaths below are part of the published API
-(`publishConfig.exports` in `package.json`):
-
-| Subpath                   | Purpose                                                                                                                 |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `.` / `@checktiv/sdk-web` | `Checktiv.init(opts)` substrate. Returns a `ChecktivClient`. No Zod at runtime; safe for tree-shaking.                  |
-| `./idv`                   | Managed IDV module. Import for its self-registration side effect so `mountProvisioned` / `mount('idv')` can resolve it. |
-| `./fraud`                 | Consent-gated fraud signal collection. Import for its self-registration side effect.                                    |
-| `./custom-form`           | Custom form module (server-authored field definitions). Import for self-registration.                                   |
-| `./custom-form/style.css` | Stylesheet for the custom-form module. `<link>` or `import` this in the host page.                                      |
-| `./react`                 | React wrapper: `ChecktivProvider`, `useChecktiv()`, `ChecktivIdv`. Requires `react`/`react-dom` peer dependencies.      |
-| `./capture`               | Headless host-side IDV capture controller (`createCaptureController`). Tier-1 - no default UI.                          |
-| `./capture-ui`            | Batteries-included capture renderer (`mount()`). Tier-2 built on `./capture`.                                           |
-| `./cross-device`          | Cross-device QR/copy-link handoff overlay.                                                                              |
-| `./idv/cross-device`      | IDV-specific cross-device wiring.                                                                                       |
-| `./agents`                | Machine-readable agent steering manifest (`dist/agents/manifest.json`).                                                 |
-
-The `./agent` subpath is **workspace-only** (not published) - it is omitted from
-`publishConfig.exports`.
+Every entry below is part of the published API. Import a module subpath (like
+`./idv`) once anywhere in your app: importing it runs a one-time self-registration
+side effect so `mountProvisioned()` and `mount('idv')` can resolve that module. If a
+session needs a module you did not import, the SDK throws a clear, actionable error
+telling you which subpath to add, instead of failing silently.
+
+| Subpath                   | Purpose                                                                                                                               |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `.` / `@checktiv/sdk-web` | Core entry: `init(opts)` returns a `ChecktivClient`. Tree-shakeable and lightweight.                                                  |
+| `./idv`                   | Managed identity-verification module. Import for its self-registration side effect so `mountProvisioned` / `mount('idv')` resolve it. |
+| `./fraud`                 | Consent-gated fraud-signal collection. Import for its self-registration side effect.                                                  |
+| `./custom-form`           | Custom intake-form module (server-authored field definitions). Import for its self-registration side effect.                          |
+| `./custom-form/style.css` | Stylesheet for the custom-form module. `<link>` or `import` this into the host page.                                                  |
+| `./react`                 | React wrapper: `ChecktivProvider`, `useChecktiv()`, `ChecktivIdv`. Requires the `react` / `react-dom` peer dependencies.              |
+| `./capture`               | Advanced: headless host-side capture controller (`createCaptureController`). No default UI.                                           |
+| `./capture-ui`            | Advanced: batteries-included capture renderer (`mount()`), built on `./capture`.                                                      |
+| `./cross-device`          | Cross-device QR / copy-link handoff overlay (`mountCrossDevice`).                                                                     |
+| `./idv/cross-device`      | Cross-device wiring for the managed IDV module.                                                                                       |
+| `./agents`                | Machine-readable steering manifest (JSON) for coding-agent tooling.                                                                   |
+
+## Managed IDV module (`./idv`)
+
+The managed IDV module renders the full identity-verification capture experience for
+you. Import it for its registration side effect, then let the provisioned session
+render it, or mount it explicitly:
 
-## Back-compat surface
+```js
+import { init } from '@checktiv/sdk-web';
+import '@checktiv/sdk-web/idv';
+
+const client = init({ publishableKey: 'ah_pk_us_live_...', getSessionToken });
+
+const idv = client.mount('idv', {
+  target: '#checktiv-container',
+  onEvent: (event) => {
+    // Events are named `checktiv.idv.*`, for example `checktiv.idv.ready`.
+    console.log(event.type);
+  },
+});
+
+// idv.destroy() when you are done.
+```
 
-The following identifiers are kept for existing customer integrations and will not be
-removed without a major version bump:
+Events are `checktiv.<module>.<name>`. The event stream is forward-open: new event
+types can appear over time, so handle the ones you care about and ignore the rest -
+do not write an exhaustive switch that assumes a fixed set.
 
-- `window.AutohostKyc` CDN global alias (alongside `window.Checktiv`)
-- `[data-autohost-kyc]` auto-discover attribute (alongside `[data-checktiv]`)
-- `autohost.kyc.complete` postMessage completion event name
+## Fraud module (`./fraud`)
 
-## React usage
+Fraud-signal collection is **consent-gated and default-deny**: it collects nothing
+until your `onConsent` callback resolves truthy.
+
+```js
+import { init } from '@checktiv/sdk-web';
+import '@checktiv/sdk-web/fraud';
+
+const client = init({ publishableKey: 'ah_pk_us_live_...', getSessionToken });
+
+const fraud = client.mount('fraud', {
+  target: '#checktiv-container',
+  onConsent: () => userHasConsented(), // boolean or Promise<boolean>
+  onEvent: (event) => console.log(event), // `checktiv.fraud.*`
+});
+
+// fraud.destroy() when you are done.
+```
+
+## Custom-form module (`./custom-form`)
+
+Renders a server-authored intake form and owns the whole submit. The host resolves
+the form config and copy (from your own localization), then passes them in. Import
+the stylesheet so the field controls are styled in your page:
+
+```js
+import '@checktiv/sdk-web/custom-form';
+import '@checktiv/sdk-web/custom-form/style.css';
+```
+
+The module always renders a continue control (even for a content-only screen) so the
+journey can advance, and emits `checktiv.custom_form.submitted` when the applicant
+completes it. When you use `mountProvisioned`, pass `customFormConfig` and
+`customFormCopy` alongside `target`.
+
+## React integration (`./react`)
+
+The React wrapper provides `ChecktivProvider`, the `useChecktiv()` hook, and the
+`ChecktivIdv` component. It is SSR-safe (it renders `null` on the server and only
+initializes in the browser), and `react` / `react-dom` are supplied by your app as
+optional peers, so there is a single React instance.
 
 ```tsx
 import { ChecktivProvider, ChecktivIdv } from '@checktiv/sdk-web/react';
-import '@checktiv/sdk-web/idv'; // register the IDV module
+import '@checktiv/sdk-web/idv'; // register the managed IDV module
 
 export function App() {
   return (
@@ -121,61 +197,61 @@ export function App() {
 }
 ```
 
-See the React guide in the docs for the full SSR-safe / Next.js pattern.
+`ChecktivIdv` mounts the managed IDV module and tears it down on unmount. Read the
+hosted developer docs for the full SSR-safe integration pattern.
 
-## Architecture notes
+## Advanced: host-side capture (`./capture`, `./capture-ui`)
 
-- **No PII, no private API key in the SDK.** The publishable key is operator config,
-  not PII. Your server mints `bt_*` browser tokens; the SDK only ever holds those.
-- **Module-load seam.** The `.` entry does not statically import the IDV or fraud
-  modules. Each module self-registers via a top-level side effect when its subpath is
-  imported. Without the import, `mount('idv')` fails with a clear `sdk_load_failed`
-  error message.
-- **Event surface.** Events are `checktiv.<module>.<name>`. The stream is
-  forward-open: do not exhaustively switch on `event.type` - unknown types may be
-  added without a major bump.
-- **Bundle budget.** The CDN `sdk.js` is gated at 100 KiB gzip by CI.
+Most integrations should use the managed `./idv` module above, which renders the
+capture experience for you. The `./capture` and `./capture-ui` subpaths are lower
+level escape hatches for hosts that need to own the capture surface themselves:
 
-## Build
+- `./capture` exports `createCaptureController`, a framework-agnostic, headless
+  capture controller with no default UI. You inject token and submit functions and
+  drive the state machine yourself.
+- `./capture-ui` exports `mount(element, options)`, a batteries-included default
+  renderer built on `./capture` that returns a `{ destroy }` handle.
 
-```bash
-pnpm --filter @rf/sdk-web build
-# emits dist/ (ESM) and services/sdk-cdn/public/v1/sdk.js (CDN IIFE)
-```
+## Cross-device handoff (`./cross-device`)
 
-No sourcemaps ship in the npm tarball or the CDN bundle. Maps are CI-only build
-artifacts (they contain internal module names).
+`./cross-device` exports `mountCrossDevice`, an overlay that hands off a verification
+to another device via a QR code or copy-link. `./idv/cross-device` wires the same
+handoff into the managed IDV module.
 
-## Bundle size checks
+## Back-compat surface
 
-```bash
-pnpm --filter @rf/sdk-web size           # CDN sdk.js (100 KiB gate)
-pnpm --filter @rf/sdk-web size:host-capture     # capture.js
-pnpm --filter @rf/sdk-web size:host-capture-ui  # capture-ui.js
-pnpm --filter @rf/sdk-web size:cross-device     # cross-device chunk
-pnpm --filter @rf/sdk-web size:npm       # per-entry npm tarball sizes
-```
+These identifiers are kept for existing integrations that were built against the
+previous product name, and will not be removed without a major version bump. They are
+literal API identifiers (like a stable route path), so use them verbatim if you are
+migrating an older snippet:
 
-The canonical gate for CI is `pnpm audit:bundle-sizes` (runs all four budgets).
+- `window.AutohostKyc` - CDN global alias (alongside `window.Checktiv`).
+- `[data-autohost-kyc]` - auto-discover attribute (alongside `[data-checktiv]`).
+- `autohost.kyc.complete` - completion event name.
 
-## Publish validation
+## TypeScript
 
-```bash
-pnpm --filter @rf/sdk-web validate:publint   # publint --strict
-pnpm --filter @rf/sdk-web validate:attw      # are the types wrong?
-pnpm --filter @rf/sdk-web validate:tarball   # publish-boundary gate
+The package ships self-contained type declarations. Import types from the root:
+
+```ts
+import type { ChecktivClient, ChecktivEvent, ChecktivIdvEvent } from '@checktiv/sdk-web';
 ```
 
-The publish-boundary gate (`scripts/audit-sdk-publish-boundary.mjs`) checks for
-internal `@rf/` specifier leaks, vendor names, internal settings sentinels, and
-dependency hygiene in the packed tarball.
+The `ChecktivEvent` union is forward-open, so a handler typed against it keeps
+compiling as new modules and phases are added.
 
-## Testing
+## Versioning and support
 
-```bash
-pnpm --filter @rf/sdk-web test
-pnpm --filter @rf/sdk-web typecheck
-```
+The package follows semantic versioning. The back-compat identifiers listed above are
+preserved across minor and patch releases. Pin the CDN URL to an immutable versioned
+path (with its SRI hash) for production, as shown in the CDN section.
+
+## Documentation
+
+Full guides, the API reference, and framework-specific integration walkthroughs live
+in the Checktiv developer docs, Web SDK section, at
+[https://docs.checktiv.com](https://docs.checktiv.com).
+
+## License
 
-Tests run under jsdom. Real camera capture and the CDN IIFE are verified against a
-deployed dev cell before each release.
+Apache-2.0

package/dist/agents/AGENTS.md

@@ -7,49 +7,44 @@ runnable recipes. Read both.
 
 ## Rules
 
-1. **The server mints the session, never the browser.** Your backend calls the public API `POST /v1/sessions` with your secret key (`ah_sk_*`) and receives the session. The secret key is server-only: NEVER put `ah_sk_*` in browser code. To hand control to the frontend, your backend mints a short-lived browser token (`bt_*`) by calling `POST /sdk/v1/sessions/:sessionId/browser-token` with the same `ah_sk_*`; that route returns `{ data: { browserToken, expiresAt, modules, scopes } }`. Only the `bt_*` string crosses to the browser.
+1. **Prefer the zero-lifecycle Checktiv.mount entry.** The simplest integration is two pieces of code. (1) On YOUR backend, call `sessions.create({ templateId, applicant }, { idempotencyKey })` - a thin wrapper over `POST /v1/sessions` with your `ah_sk_*` secret key - and return ONLY the resulting `clientToken` to the browser. (2) In the browser, call `Checktiv.mount(target, { fetchToken, onComplete })`, where `fetchToken` returns that `clientToken`. `fetchToken` runs ONCE for the cold / new-device start, NOT on every expiry: the SDK exchanges the durable `clientToken` for a short-lived working token and refreshes it internally, so you write NO token-refresh endpoint, NO expiration handler, and NO resume endpoint. Key `sessions.create` idempotently per user or reservation so retries and new-device re-entry never double-bill. The legacy `Checktiv.init({ ... }).mountProvisioned({ target })` with a `getSessionToken` browser-token callback stays fully supported for existing integrations.
 
-2. **Use mountProvisioned as the default path.** Call `Checktiv.init({ ... }).mountProvisioned({ target })`. It reads the server-declared `session.modules` from `GET /sdk/v1/sessions/me` and renders exactly what the server composed, so the server drives composition. `mount('idv')` / `mount('fraud')` is the explicit override / escape hatch, not the first choice.
+2. **The server mints the session, never the browser.** Your backend calls the public API `POST /v1/sessions` with your secret key (`ah_sk_*`) and receives the session. The secret key is server-only: NEVER put `ah_sk_*` in browser code. To hand control to the frontend, your backend mints a short-lived browser token (`bt_*`) by calling `POST /v1/sessions/{id}/browser_token` with the same `ah_sk_*`; that route returns `{ data: { browser_token, expires_at } }`. Only the `bt_*` string crosses to the browser.
 
-3. **Completion is not a verdict: trust the signed webhook.** The client event `checktiv.idv.submitted` is terminal-for-capture only; it means the applicant finished the capture step, NOT that they passed. The decision arrives on your server through the signed `kyc.session.*` webhook. Trust the signed webhook as the only outcome anchor; never infer a pass/fail from a client event.
+3. **Use mountProvisioned as the default path.** Call `Checktiv.init({ ... }).mountProvisioned({ target })`. It reads the server-declared `session.modules` from `GET /sdk/v1/sessions/me` and renders exactly what the server composed, so the server drives composition. `mount('idv')` / `mount('fraud')` is the explicit override / escape hatch, not the first choice.
 
-4. **Satisfy each applicant-info requirement once, through any one path.** When a session declares applicant-info requirements (name, date of birth, address, and similar fields), each requirement is satisfied by ANY ONE of the supported collection paths, not by all of them. Supply a field through one path and the SDK treats that requirement as met; do not double-collect the same field. Let the server-declared session decide which fields are required rather than hard-coding a form.
+4. **Completion is not a verdict: trust the signed webhook.** The client event `checktiv.idv.submitted` is terminal-for-capture only; it means the applicant finished the capture step, NOT that they passed. The decision arrives on your server through the signed `kyc.session.*` webhook. Trust the signed webhook as the only outcome anchor; never infer a pass/fail from a client event.
 
-5. **Develop local-first with the synthetic driver.** Use a **test-mode publishable key** (`ah_pk_<region>_test_*`) PLUS the synthetic opt-in. Test mode is selected by the key itself, not by a `mode` property on `init`. A test-mode key without the synthetic option renders a BLANK embed on a local origin because the capture license is domain-bound, whereas the synthetic path runs the full `checktiv.idv.*` flow locally with no camera, no license, and no deployed environment. Ensure your own session-mint backend and token endpoint are running before the SDK calls `getSessionToken`. Build and verify locally with the synthetic driver, then graduate to a deployed environment for real capture and ship through the standard npm / CDN path.
+5. **Satisfy each applicant-info requirement once, through any one path.** When a session declares applicant-info requirements (name, date of birth, address, and similar fields), each requirement is satisfied by ANY ONE of the supported collection paths, not by all of them. Supply a field through one path and the SDK treats that requirement as met; do not double-collect the same field. Let the server-declared session decide which fields are required rather than hard-coding a form.
 
-6. **getSessionToken supplies a fresh bt_* on demand.** `getSessionToken` is `string | ((ctx: { sessionId; reason: 'initial' | 'expired' | '401' }) => Promise<string>)`. The SDK calls it on mount and again on expiry or a 401, then retries the failed request once. Always return a freshly minted `bt_*` from your backend; never hold a long-lived credential in the browser. If your callback rejects, the SDK emits `token_expired` with `recovery: 'refresh_session'` and halts cleanly.
+6. **Develop local-first with the synthetic driver.** Use a **test-mode publishable key** (`ah_pk_<region>_test_*`) PLUS the synthetic opt-in. Test mode is selected by the key itself, not by a `mode` property on `init`. A test-mode key without the synthetic option renders a BLANK embed on a local origin because the capture license is domain-bound, whereas the synthetic path runs the full `checktiv.idv.*` flow locally with no camera, no license, and no deployed environment. Ensure your own session-mint backend and token endpoint are running before the SDK calls `getSessionToken`. Build and verify locally with the synthetic driver, then graduate to a deployed environment for real capture and ship through the standard npm / CDN path.
 
-7. **Add your frontend origin to the publishable key allowlist first.** Each publishable key carries an origin allowlist that you set in the console / dashboard. Your frontend's origin MUST be on that allowlist before the first mount, or EVERY mount fails with `origin_not_allowed` (the `bt_*` data-plane routes reject an off-allowlist `Origin`). Add your origin to the publishable key allowlist before you integrate.
+7. **getSessionToken supplies a fresh bt_* on demand.** `getSessionToken` is `string | ((ctx: { sessionId; reason: 'initial' | 'expired' | '401' }) => Promise<string>)`. The SDK calls it on mount and again on expiry or a 401, then retries the failed request once. Always return a freshly minted `bt_*` from your backend; never hold a long-lived credential in the browser. If your callback rejects, the SDK emits `token_expired` with `recovery: 'refresh_session'` and halts cleanly.
 
-8. **The SDK adds X-Publishable-Key itself on the customer path.** Pass `publishableKey` to `Checktiv.init(...)` and stop there. On the customer (pk-present) path the managed transport attaches the `X-Publishable-Key` header to its own `bt_*` data-plane calls internally. Do NOT also hand-add an `X-Publishable-Key` header yourself; double-adding it is wrong. (The first-party hosted path used internally by the verify app carries no publishable key and sends none.)
+8. **Add your frontend origin to the publishable key allowlist first.** Each publishable key carries an origin allowlist that you set in the console / dashboard. Your frontend's origin MUST be on that allowlist before the first mount, or EVERY mount fails with `origin_not_allowed` (the `bt_*` data-plane routes reject an off-allowlist `Origin`). Add your origin to the publishable key allowlist before you integrate.
 
-9. **Wire cross-device QR handoff via openCrossDeviceOverlay.** Cross-device handoff is wired via STANDALONE exports from the `@checktiv/sdk-web/idv/cross-device` subpath (NOT via an option on `IdvMountOptions` / `mountProvisioned`). Import: `import { openCrossDeviceOverlay, preloadCrossDeviceChunk } from '@checktiv/sdk-web/idv/cross-device';`
+9. **The SDK adds X-Publishable-Key itself on the customer path.** Pass `publishableKey` to `Checktiv.init(...)` and stop there. On the customer (pk-present) path the managed transport attaches the `X-Publishable-Key` header to its own `bt_*` data-plane calls internally. Do NOT also hand-add an `X-Publishable-Key` header yourself; double-adding it is wrong. (The first-party hosted path used internally by the verify app carries no publishable key and sends none.)
 
-`openCrossDeviceOverlay(opts: CrossDeviceOverlayOptions)` opens the overlay. Key fields on `CrossDeviceOverlayOptions`:
-  • `target: HTMLElement`: the module's root container element.
-  • `onOpenCrossDevice: CrossDeviceHandoffHook`: HOST-supplied mint hook. Type: `() => Promise<{ kind: 'ok'; url: string } | { kind: 'unavailable' }>`. Your host calls its own OTL-mint BFF and returns `{ kind: 'ok', url }` with the journey URL, or `{ kind: 'unavailable' }` if the mint fails. The URL MUST be `https:` (the SDK validates this and collapses `javascript:`, `http:`, and `data:` schemes to `'unavailable'`). The hook is re-callable (the overlay has a "refresh link" affordance); cap re-mints with a per-overlay counter on your host.
-  • `copy: CrossDeviceCopy`: host-injected copy map; no hardcoded strings.
-  • `isMobile: boolean`: `true` suppresses the QR (same-device scan is circular).
-  • `emit: (e: ChecktivIdvEvent) => void`: forward to the host's `onEvent` handler.
-  • `onClose?: () => void`: called when the applicant closes the overlay or `destroy()` is called.
+10. **Cross-device QR handoff is built into the managed IDV module.** Cross-device handoff (a desktop applicant finishes on their phone via a QR + copy-link overlay) is OWNED BY THE MANAGED IDV MODULE. Render it with `client.mount('idv', { crossDeviceCopy, onEvent })` and the returned handle exposes `openCrossDevice()`: calling it opens the overlay OVER the still-live capture frame, runs the completion poll, and emits `checktiv.idv.submitted` when the phone finishes so your host reloads. You MUST `import '@checktiv/sdk-web/idv/cross-device';` to enable the overlay (the CDN script-tag bundle already includes it); without that import `openCrossDevice()` is a graceful, actionable no-op, as it also is before the applicant verification resolves or when no `crossDeviceCopy` was supplied. `IdvMountOptions` carries `crossDeviceCopy` (host-injected strings; the `unavailableMessage` key is required so no arm renders blank) and the OPTIONAL `onOpenCrossDevice` mint override; `IdvHandle` exposes `openCrossDevice?()`, so call it as `handle.openCrossDevice?.()`. NOTE: `mountProvisioned` and the zero-lifecycle `Checktiv.mount` entry do NOT expose the overlay: use the explicit `mount('idv', ...)` call when you need `openCrossDevice()`.
 
-Returns `CrossDeviceOverlayHandle` with:
-  • `setCompleting()`: marks the session completing (phone finished; overlay stays mounted with a waiting label instead of disappearing).
-  • `destroy()`: tears down the overlay. Idempotent.
+Who mints the one-time handoff link depends on the token plane:
+  • Working-token plane: the module mints the link ITSELF (it calls its own handoff endpoint `POST /sdk/v1/sessions/me/handoff`, authenticated by the applicant's short-lived working token, and caps the per-overlay "refresh link" re-mints). Supply `onOpenCrossDevice` ONLY to point the mint at your own backend instead.
+  • Browser-token (`bt_*`) plane: the SDK CANNOT self-mint (the handoff route rejects a `bt_*` bearer), so you MUST supply `onOpenCrossDevice` backed by a server-held credential.
 
-`preloadCrossDeviceChunk()`: fire-and-forget preload of the lazy CDN chunk. Call it when the IDV module becomes active to reduce perceived latency on open.
+`onOpenCrossDevice: CrossDeviceHandoffHook` is `() => Promise<{ kind: 'ok'; url: string } | { kind: 'unavailable' }>`. Return `{ kind: 'ok', url }` with the journey URL (which MUST be `https:`: the SDK collapses `javascript:`, `http:`, and `data:` schemes to `'unavailable'`) or `{ kind: 'unavailable' }` when the mint fails. The hook is re-callable for the overlay's "refresh link" affordance; the SDK caps re-mints per overlay.
 
-Events (both are token-free, NEVER contain the url/OTL/short-code):
-  • `checktiv.idv.cross_device_opened`: hook returned `ok`, overlay shown.
-  • `checktiv.idv.cross_device_unavailable`: hook returned `unavailable` or URL validation failed.
-There is NO `cross_device_completed` event. Completion is the HOST's responsibility: poll your own `/api/idv/cross-device-status` BFF (returns `{ advanced: boolean }`) and call `window.location.reload()` exactly once when `advanced: true`. The SDK module NEVER writes `window.location`. Use `setCompleting()` on the returned handle before reloading so the overlay shows a completing state rather than disappearing abruptly.
+For a FULLY CUSTOM IDV renderer built on `@checktiv/sdk-web/capture` (NOT the managed module), the STANDALONE exports drive the overlay yourself and you always supply the mint hook: `@checktiv/sdk-web/idv/cross-device` (`openCrossDeviceOverlay(opts)` opens the overlay, `preloadCrossDeviceChunk()` warms the lazy chunk) and `@checktiv/sdk-web/cross-device` (`mountCrossDevice(target, props)` renders the bare panel on a screen you fully control). `openCrossDeviceOverlay` takes `{ target, onOpenCrossDevice, copy, isMobile, emit, onClose }` plus an optional `poll` config, and returns a handle with `setCompleting()` (keep the QR mounted with a waiting label while your page reloads) and `destroy()` (idempotent). Set `isMobile: true` to suppress the QR on a phone (a same-device scan is circular). The SDK NEVER writes `window.location`; navigation is always the host's, off the emitted event.
 
-The browser SDK CANNOT self-mint: `bt_*` bearers are rejected at the OTL-mint route. The host must own a server-side BFF that holds a `vt_*` cookie (HttpOnly, SameSite=Lax) and calls the sdk-api OTL-mint endpoint to produce the handoff URL.
+Three token-free overlay events (NONE carries the url / OTL / short-code / expiry hint):
+  • `checktiv.idv.cross_device_opened`: the mint returned `ok` and the overlay is shown.
+  • `checktiv.idv.cross_device_unavailable`: the mint returned `unavailable` or URL validation failed.
+  • `checktiv.idv.cross_device_capped`: the completion poll hit its total time cap without the phone finishing. NOT an error and NOT a verdict: the QR panel stays mounted so the applicant can still finish on their phone.
 
 ## Runnable recipes
 
 Full, copy-pasteable code for each step is in `manifest.json` under `recipes`:
 
+- **(e) Zero-lifecycle: sessions.create on the backend, Checktiv.mount on the frontend**
 - **(a) Backend: mint a session with your secret key**
 - **(b) Backend: mint a bt_* browser token and hand it to the frontend**
 - **(c) Frontend: init and mountProvisioned**

package/dist/agents/manifest.json

@@ -26,10 +26,15 @@
     }
   },
   "rules": [
+    {
+      "id": "zero-lifecycle-mount-is-preferred",
+      "title": "Prefer the zero-lifecycle Checktiv.mount entry",
+      "body": "The simplest integration is two pieces of code. (1) On YOUR backend, call `sessions.create({ templateId, applicant }, { idempotencyKey })` - a thin wrapper over `POST /v1/sessions` with your `ah_sk_*` secret key - and return ONLY the resulting `clientToken` to the browser. (2) In the browser, call `Checktiv.mount(target, { fetchToken, onComplete })`, where `fetchToken` returns that `clientToken`. `fetchToken` runs ONCE for the cold / new-device start, NOT on every expiry: the SDK exchanges the durable `clientToken` for a short-lived working token and refreshes it internally, so you write NO token-refresh endpoint, NO expiration handler, and NO resume endpoint. Key `sessions.create` idempotently per user or reservation so retries and new-device re-entry never double-bill. The legacy `Checktiv.init({ ... }).mountProvisioned({ target })` with a `getSessionToken` browser-token callback stays fully supported for existing integrations."
+    },
     {
       "id": "server-mints-the-session",
       "title": "The server mints the session, never the browser",
-      "body": "Your backend calls the public API `POST /v1/sessions` with your secret key (`ah_sk_*`) and receives the session. The secret key is server-only: NEVER put `ah_sk_*` in browser code. To hand control to the frontend, your backend mints a short-lived browser token (`bt_*`) by calling `POST /sdk/v1/sessions/:sessionId/browser-token` with the same `ah_sk_*`; that route returns `{ data: { browserToken, expiresAt, modules, scopes } }`. Only the `bt_*` string crosses to the browser."
+      "body": "Your backend calls the public API `POST /v1/sessions` with your secret key (`ah_sk_*`) and receives the session. The secret key is server-only: NEVER put `ah_sk_*` in browser code. To hand control to the frontend, your backend mints a short-lived browser token (`bt_*`) by calling `POST /v1/sessions/{id}/browser_token` with the same `ah_sk_*`; that route returns `{ data: { browser_token, expires_at } }`. Only the `bt_*` string crosses to the browser."
     },
     {
       "id": "mount-provisioned-is-the-default",
@@ -68,11 +73,17 @@
     },
     {
       "id": "cross-device-handoff-hook",
-      "title": "Wire cross-device QR handoff via openCrossDeviceOverlay",
-      "body": "Cross-device handoff is wired via STANDALONE exports from the `@checktiv/sdk-web/idv/cross-device` subpath (NOT via an option on `IdvMountOptions` / `mountProvisioned`). Import: `import { openCrossDeviceOverlay, preloadCrossDeviceChunk } from '@checktiv/sdk-web/idv/cross-device';`\n\n`openCrossDeviceOverlay(opts: CrossDeviceOverlayOptions)` opens the overlay. Key fields on `CrossDeviceOverlayOptions`:\n  • `target: HTMLElement`: the module's root container element.\n  • `onOpenCrossDevice: CrossDeviceHandoffHook`: HOST-supplied mint hook. Type: `() => Promise<{ kind: 'ok'; url: string } | { kind: 'unavailable' }>`. Your host calls its own OTL-mint BFF and returns `{ kind: 'ok', url }` with the journey URL, or `{ kind: 'unavailable' }` if the mint fails. The URL MUST be `https:` (the SDK validates this and collapses `javascript:`, `http:`, and `data:` schemes to `'unavailable'`). The hook is re-callable (the overlay has a \"refresh link\" affordance); cap re-mints with a per-overlay counter on your host.\n  • `copy: CrossDeviceCopy`: host-injected copy map; no hardcoded strings.\n  • `isMobile: boolean`: `true` suppresses the QR (same-device scan is circular).\n  • `emit: (e: ChecktivIdvEvent) => void`: forward to the host's `onEvent` handler.\n  • `onClose?: () => void`: called when the applicant closes the overlay or `destroy()` is called.\n\nReturns `CrossDeviceOverlayHandle` with:\n  • `setCompleting()`: marks the session completing (phone finished; overlay stays mounted with a waiting label instead of disappearing).\n  • `destroy()`: tears down the overlay. Idempotent.\n\n`preloadCrossDeviceChunk()`: fire-and-forget preload of the lazy CDN chunk. Call it when the IDV module becomes active to reduce perceived latency on open.\n\nEvents (both are token-free, NEVER contain the url/OTL/short-code):\n  • `checktiv.idv.cross_device_opened`: hook returned `ok`, overlay shown.\n  • `checktiv.idv.cross_device_unavailable`: hook returned `unavailable` or URL validation failed.\nThere is NO `cross_device_completed` event. Completion is the HOST's responsibility: poll your own `/api/idv/cross-device-status` BFF (returns `{ advanced: boolean }`) and call `window.location.reload()` exactly once when `advanced: true`. The SDK module NEVER writes `window.location`. Use `setCompleting()` on the returned handle before reloading so the overlay shows a completing state rather than disappearing abruptly.\n\nThe browser SDK CANNOT self-mint: `bt_*` bearers are rejected at the OTL-mint route. The host must own a server-side BFF that holds a `vt_*` cookie (HttpOnly, SameSite=Lax) and calls the sdk-api OTL-mint endpoint to produce the handoff URL."
+      "title": "Cross-device QR handoff is built into the managed IDV module",
+      "body": "Cross-device handoff (a desktop applicant finishes on their phone via a QR + copy-link overlay) is OWNED BY THE MANAGED IDV MODULE. Render it with `client.mount('idv', { crossDeviceCopy, onEvent })` and the returned handle exposes `openCrossDevice()`: calling it opens the overlay OVER the still-live capture frame, runs the completion poll, and emits `checktiv.idv.submitted` when the phone finishes so your host reloads. You MUST `import '@checktiv/sdk-web/idv/cross-device';` to enable the overlay (the CDN script-tag bundle already includes it); without that import `openCrossDevice()` is a graceful, actionable no-op, as it also is before the applicant verification resolves or when no `crossDeviceCopy` was supplied. `IdvMountOptions` carries `crossDeviceCopy` (host-injected strings; the `unavailableMessage` key is required so no arm renders blank) and the OPTIONAL `onOpenCrossDevice` mint override; `IdvHandle` exposes `openCrossDevice?()`, so call it as `handle.openCrossDevice?.()`. NOTE: `mountProvisioned` and the zero-lifecycle `Checktiv.mount` entry do NOT expose the overlay: use the explicit `mount('idv', ...)` call when you need `openCrossDevice()`.\n\nWho mints the one-time handoff link depends on the token plane:\n  • Working-token plane: the module mints the link ITSELF (it calls its own handoff endpoint `POST /sdk/v1/sessions/me/handoff`, authenticated by the applicant's short-lived working token, and caps the per-overlay \"refresh link\" re-mints). Supply `onOpenCrossDevice` ONLY to point the mint at your own backend instead.\n  • Browser-token (`bt_*`) plane: the SDK CANNOT self-mint (the handoff route rejects a `bt_*` bearer), so you MUST supply `onOpenCrossDevice` backed by a server-held credential.\n\n`onOpenCrossDevice: CrossDeviceHandoffHook` is `() => Promise<{ kind: 'ok'; url: string } | { kind: 'unavailable' }>`. Return `{ kind: 'ok', url }` with the journey URL (which MUST be `https:`: the SDK collapses `javascript:`, `http:`, and `data:` schemes to `'unavailable'`) or `{ kind: 'unavailable' }` when the mint fails. The hook is re-callable for the overlay's \"refresh link\" affordance; the SDK caps re-mints per overlay.\n\nFor a FULLY CUSTOM IDV renderer built on `@checktiv/sdk-web/capture` (NOT the managed module), the STANDALONE exports drive the overlay yourself and you always supply the mint hook: `@checktiv/sdk-web/idv/cross-device` (`openCrossDeviceOverlay(opts)` opens the overlay, `preloadCrossDeviceChunk()` warms the lazy chunk) and `@checktiv/sdk-web/cross-device` (`mountCrossDevice(target, props)` renders the bare panel on a screen you fully control). `openCrossDeviceOverlay` takes `{ target, onOpenCrossDevice, copy, isMobile, emit, onClose }` plus an optional `poll` config, and returns a handle with `setCompleting()` (keep the QR mounted with a waiting label while your page reloads) and `destroy()` (idempotent). Set `isMobile: true` to suppress the QR on a phone (a same-device scan is circular). The SDK NEVER writes `window.location`; navigation is always the host's, off the emitted event.\n\nThree token-free overlay events (NONE carries the url / OTL / short-code / expiry hint):\n  • `checktiv.idv.cross_device_opened`: the mint returned `ok` and the overlay is shown.\n  • `checktiv.idv.cross_device_unavailable`: the mint returned `unavailable` or URL validation failed.\n  • `checktiv.idv.cross_device_capped`: the completion poll hit its total time cap without the phone finishing. NOT an error and NOT a verdict: the QR panel stays mounted so the applicant can still finish on their phone."
     }
   ],
   "recipes": [
+    {
+      "id": "zero-lifecycle-mount",
+      "title": "(e) Zero-lifecycle: sessions.create on the backend, Checktiv.mount on the frontend",
+      "language": "ts",
+      "code": "// ---- YOUR BACKEND: the ONE lifecycle call. ah_sk_* stays server-only. ----\nimport { sessions } from '@checktiv/sdk-web';\n\napp.post('/kyc/session', async (req, res) => {\n  const session = await sessions.create(\n    { templateId: 'wt_...', applicant: { externalId: req.user.id } },\n    {\n      apiBase: `https://api.${process.env.CHECKTIV_REGION ?? \"us\"}.checktiv.com`,\n      secretKey: process.env.CHECKTIV_SECRET_KEY, // ah_sk_* - NEVER in the browser\n      idempotencyKey: req.user.id, // same user maps to the same session, no double-mint\n    },\n  );\n  res.json({ clientToken: session.clientToken }); // low-privilege, resume-only\n});\n\n// ---- YOUR FRONTEND: mount and forget. No refresh endpoint, no expiry branch. ----\nimport { mount } from '@checktiv/sdk-web';\nimport '@checktiv/sdk-web/idv'; // self-registers each module mount may render\nimport '@checktiv/sdk-web/fraud';\n\nmount('#checktiv', {\n  publishableKey: import.meta.env.PUBLIC_CHECKTIV_PK, // ah_pk_* - safe in the browser\n  // Called ONCE for the cold start (and only for a new-device start), NOT on expiry.\n  fetchToken: () => fetch('/kyc/session', { method: 'POST' })\n    .then((r) => r.json()).then((x) => x.clientToken),\n  onComplete: (result) => showThankYou(result), // capture submitted; verdict via webhook\n});"
+    },
     {
       "id": "backend-session-mint",
       "title": "(a) Backend: mint a session with your secret key",
@@ -83,7 +94,7 @@
       "id": "backend-browser-token-mint",
       "title": "(b) Backend: mint a bt_* browser token and hand it to the frontend",
       "language": "ts",
-      "code": "// Your own endpoint that getSessionToken (recipe c) fetches. It mints a\n// fresh, short-lived bt_* for a session you already own server-side and\n// returns ONLY the bt_* string. ah_sk_* never leaves the server.\nimport express from 'express';\nconst app = express();\n\napp.post('/checktiv/browser-token', async (req, res) => {\n  // Resolve the session id from YOUR session/auth, not from the client body.\n  const sessionId = await resolveSessionIdForUser(req);\n  const region = process.env.CHECKTIV_REGION ?? \"us\";\n  const minted = await fetch(\n    `https://api.${region}.checktiv.com/sdk/v1/sessions/${sessionId}/browser-token`,\n    {\n      method: 'POST',\n      headers: { Authorization: `Bearer ${process.env.CHECKTIV_SECRET_KEY}` },\n    },\n  );\n  const { data } = await minted.json(); // { browserToken, expiresAt, modules, scopes }\n  res.json({ browserToken: data.browserToken }); // return only the bt_* string\n});"
+      "code": "// Your own endpoint that getSessionToken (recipe c) fetches. It mints a\n// fresh, short-lived bt_* for a session you already own server-side and\n// returns ONLY the bt_* string. ah_sk_* never leaves the server.\nimport express from 'express';\nconst app = express();\n\napp.post('/checktiv/browser-token', async (req, res) => {\n  // Resolve the session id from YOUR session/auth, not from the client body.\n  const sessionId = await resolveSessionIdForUser(req);\n  const region = process.env.CHECKTIV_REGION ?? \"us\";\n  const minted = await fetch(\n    `https://api.${region}.checktiv.com/v1/sessions/${sessionId}/browser_token`,\n    {\n      method: 'POST',\n      headers: { Authorization: `Bearer ${process.env.CHECKTIV_SECRET_KEY}` },\n    },\n  );\n  const { data } = await minted.json(); // { browser_token, expires_at }\n  res.json({ browserToken: data.browser_token }); // return only the bt_* string\n});"
     },
     {
       "id": "frontend-init-mount-provisioned",