truescene-face-id-capture-sdk 1.0.0 → 1.0.1

package/README.md

@@ -2,7 +2,9 @@
 
 Framework-agnostic video capture and ID verification delivered as a Web Component,
 with a thin React wrapper for React apps. The SDK performs the capture flow and
-calls `/comparev2` using a session token you provide.
+calls `https://{region}.api.truescene.ai/comparev2` using a session token you
+provide to obtain a verification code. Your app can use that code to request a
+verification status from your backend.
 
 ## Install
 
@@ -21,31 +23,60 @@ Import the SDK once to register the custom element, then render it anywhere.
 
 <truescene-capture
   session-token="YOUR_SESSION_TOKEN"
-  compare-url="/comparev2"
+  region="us"
   auto-start
 ></truescene-capture>
 ```
 
+### Listening for events
+
+```html
+<truescene-capture id="capture" session-token="YOUR_SESSION_TOKEN"></truescene-capture>
+<script>
+  const el = document.getElementById('capture')
+  el.addEventListener('verification-code', (event) => {
+    console.log('Verification code:', event.detail)
+  })
+  el.addEventListener('verification-error', (event) => {
+    console.log('Verification error:', event.detail)
+  })
+  el.addEventListener('metrics-change', (event) => {
+    console.log('Metrics:', event.detail)
+  })
+  el.addEventListener('capture', (event) => {
+    console.log('Images:', event.detail)
+  })
+</script>
+```
+
 ### Attributes
 
 - `session-token` (required): token from your backend.
-- `compare-url` (optional): defaults to `/comparev2`.
-- `token-header` (optional): header name for the token, default `Authorization`.
-- `token-prefix` (optional): header prefix, default `Bearer`.
-- `token-field` (optional): body field name for the token, default `session_token`.
+- `region` (required): `eu`, `us`, or `sandbox`. The SDK calls `https://{region}.api.truescene.ai/comparev2`.
+- `compare-timeout-ms` (optional): request timeout in milliseconds, default `20000` (`0` disables).
 - `auto-start` (optional): start immediately when token is present.
-- `show-debug` (optional): show debug panel by default.
-- `debug-toggle` (optional): show the debug toggle button.
+- `show-header` (optional): show the SDK header block, default `true`.
+- `show-instructions` (optional): show the instructions paragraph, default `true`.
+- `show-status` (optional): show the status pills, default `true`.
+- `header-eyebrow` (optional): override the eyebrow label.
+- `header-title` (optional): override the main title line.
+- `header-subtitle` (optional): override the secondary title line.
+- `instructions` (optional): override the instruction copy.
 
 ### Events
 
-- `ready-change` → `{ faceReady, idReady }`
-- `step-change` → `CaptureStep`
-- `metrics-change` → `FaceAndIdCaptureMetrics`
-- `capture` → `{ faceImage, idImage, fullImage }`
-- `compare-result` → `CompareResult | null`
-- `compare-error` → `string | null`
-- `error` → `string`
+- `ready-change` -> `{ faceReady, idReady }`
+- `step-change` -> `CaptureStep`
+- `metrics-change` -> `FaceAndIdCaptureMetrics`
+- `capture` -> `{ faceImage, idImage, fullImage }`
+- `verification-code` -> `VerificationCodeResponse | null`
+- `verification-error` -> `VerificationError | null`
+- `error` -> `string`
+
+`verification-code` emits `null` when a compare request starts, then emits the
+final code (or `verification-error`) once the request finishes.
+Requests are aborted when the component unmounts, and timeouts trigger
+`REQUEST_TIMEOUT`.
 
 ## React wrapper
 
@@ -56,12 +87,53 @@ import TrueSceneCapture from 'truescene-face-capture/react'
 
 <TrueSceneCapture
   sessionToken={sessionToken}
-  compareUrl="/comparev2"
+  region="us"
+  compareTimeoutMs={20000}
   autoStart
-  onCompareResult={(result) => console.log(result)}
+  showHeader
+  showInstructions
+  showStatus
+  onVerificationCode={(result) => console.log(result)}
+  onMetricsChange={(metrics) => console.log(metrics)}
+  onCapture={(images) => console.log(images)}
 />
 ```
 
+### Debug metrics (demo-only)
+
+The SDK emits capture metrics through `metrics-change`. If you want a debug
+panel or capture preview cards, build them in your app (as the demo does)
+instead of inside the SDK.
+
+### Verification errors
+
+`verification-error` provides a stable error object:
+
+```ts
+{ code: string; message: string; status?: number }
+```
+
+Codes:
+
+- `MISSING_TOKEN`
+- `MISSING_REGION`
+- `HTTP_ERROR`
+- `NETWORK_ERROR`
+- `INVALID_RESPONSE`
+- `REQUEST_TIMEOUT`
+
+To hide the built-in header/instructions/status UI in the SDK:
+
+```html
+<truescene-capture
+  session-token="YOUR_SESSION_TOKEN"
+  region="us"
+  show-header="false"
+  show-instructions="false"
+  show-status="false"
+></truescene-capture>
+```
+
 ## Session token flow
 
 1. Your backend issues a session token (after authenticating the end user).
@@ -70,8 +142,28 @@ import TrueSceneCapture from 'truescene-face-capture/react'
    - `Authorization: Bearer <token>` header (configurable), and
    - `session_token` field in the request body (configurable).
 
-## Development
+## Verification status (demo only)
+
+The SDK only emits `verification_code`. Use that code in your app (or backend)
+to request the verification status. For example:
+
+```ts
+await fetch('https://verification.truescene.site/internal/verification/v1/verification/status', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-TRUESCENE-API-KEY': 'YOUR_API_KEY',
+  },
+  body: JSON.stringify({
+    verification_code,
+    include_extracted_data: true,
+  }),
+})
+```
+
+In production, do this exchange on your backend to avoid exposing API keys in
+the browser.
+
+## Contributing
 
-- `npm run dev` runs the demo app.
-- `npm run build:demo` builds the demo app to `dist-demo/`.
-- `npm run build` builds the SDK to `dist/`.
+See `CONTRIBUTING.md` for local development and build workflows.

package/dist/_redirects

@@ -1,3 +0,0 @@
-/comparev2    http://13.60.232.144:3031/comparev2    200
-/comparev2/*  http://13.60.232.144:3031/:splat       200
-/compare/*    http://13.60.232.144:3031/:splat       200