@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.

Two surfaces ship from this 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.

Install (npm)

npm install @checktiv/sdk-web
# or: pnpm add @checktiv/sdk-web

react and react-dom are optional peer dependencies. Install them only when using the ./react subpath.

CDN snippet

<!-- Moving pointer - always the latest release. No SRI: content changes on every 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:

<script
  src="https://sdk.us.checktiv.com/sdk/1.2.3/sdk.js"
  integrity="sha384-<hash-from-release-notes>"
  crossorigin="anonymous"
></script>

The two-line surface

import { init } from '@checktiv/sdk-web';
import '@checktiv/sdk-web/idv'; // self-registers the IDV module

const client = init({
  publishableKey: 'ah_pk_us_test_...',
  getSessionToken: async (ctx) => {
    const res = await fetch('/api/checktiv/token', {
      method: 'POST',
      body: JSON.stringify({ reason: ctx.reason }),
      headers: { 'Content-Type': 'application/json' },
    });
    return (await res.json()).token;
  },
});

// Server-driven: renders whatever modules the session declares.
client.mountProvisioned({
  target: document.getElementById('checktiv-container'),
  onEvent: (event) => console.log(event),
});

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.

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.

Back-compat surface

The following identifiers are kept for existing customer integrations and will not be removed without a major version bump:

• window.AutohostKyc CDN global alias (alongside window.Checktiv)
• [data-autohost-kyc] auto-discover attribute (alongside [data-checktiv])
• autohost.kyc.complete postMessage completion event name

React usage

import { ChecktivProvider, ChecktivIdv } from '@checktiv/sdk-web/react';
import '@checktiv/sdk-web/idv'; // register the IDV module

export function App() {
  return (
    <ChecktivProvider
      publishableKey="ah_pk_us_test_..."
      getSessionToken={async (ctx) => fetchToken(ctx)}
    >
      <ChecktivIdv onEvent={(e) => console.log(e)} />
    </ChecktivProvider>
  );
}

See the React guide in the docs for the full SSR-safe / Next.js pattern.

Architecture notes

• 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.

Build

pnpm --filter @rf/sdk-web build
# emits dist/ (ESM) and services/sdk-cdn/public/v1/sdk.js (CDN IIFE)

No sourcemaps ship in the npm tarball or the CDN bundle. Maps are CI-only build artifacts (they contain internal module names).

Bundle size checks

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

The canonical gate for CI is pnpm audit:bundle-sizes (runs all four budgets).

Publish validation

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 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.

Testing

pnpm --filter @rf/sdk-web test
pnpm --filter @rf/sdk-web typecheck

Tests run under jsdom. Real camera capture and the CDN IIFE are verified against a deployed dev cell before each release.