@smileid/usesmileid 12.1.1 → 12.2.1-SNAPSHOT.44

package/CHANGELOG.md

@@ -1,15 +1,17 @@
 Full release notes: [Smile ID docs](https://docs.usesmileid.com/developer-resources/sdks/mobile/release-notes/react-native-expo).
 
+## 12.2.0
+
+See the repository CHANGELOG for the 12.2.0 release notes.
+
 ## 12.1.1
 
 See the repository CHANGELOG for the 12.1.1 release notes.
 
-
 ## 12.1.0
 
 See the repository CHANGELOG for the 12.1.0 release notes.
 
-
 ## 12.0.2
 
 See the repository CHANGELOG for the 12.0.2 release notes.

package/README.md

@@ -32,7 +32,7 @@ Sizes are measured on every push to `main` and updated automatically by CI.
 - Xcode (latest stable) — iOS 16.4 deployment target (set by Expo SDK 56's modules; the Smile ID iOS SDK itself supports iOS 15)
 - Android Gradle Plugin 8.11.1+ — `compileSdk` 36 or newer (React Native's default; nothing to set) and `minSdk` 24, matching the native Smile ID SDK and the kamera engine. The ML Kit config plugins set the Kotlin and KSP versions the AARs were compiled with. The 12.0.0–12.0.2 AARs required compileSdk 37 and `minSdk` 26 instead; on those releases, install platform 37 before Gradle runs (on EAS, an `eas-build-pre-install` script: `yes | sdkmanager --licenses >/dev/null; sdkmanager "platforms;android-37.0"`).
 
-`12.1.1` is built and verified against Expo SDK 57 and React Native 0.86. The floors above are the supported minimum and keep working.
+`12.2.0` is built and verified against Expo SDK 57 and React Native 0.86. The floors above are the supported minimum and keep working.
 
 ## Installation
 
@@ -143,7 +143,7 @@ export default function VerificationScreen() {
 
 ## Full Builder Reference
 
-`useSmileIDBuilder` takes a callback that receives a mutable builder. Top-level mutable properties (`consentInformation`, `enhancedKYCParams`, `biometricKYCParams`, `documentVerificationParams`, `enhancedDocumentVerificationParams`, `userDetails`, `localizations`, `onResult`, `onAnalyticsEvent`) are property-assigned. Nested blocks (`config`, `theme`, `network`, `ml`, `screens`) take closures.
+`useSmileIDBuilder` takes a callback that receives a mutable builder. Top-level mutable properties (`consentInformation`, `enhancedKYCParams`, `biometricKYCParams`, `documentVerificationParams`, `enhancedDocumentVerificationParams`, `residencyDocumentVerificationParams`, `userDetails`, `localizations`, `onResult`, `onAnalyticsEvent`) are property-assigned. Nested blocks (`config`, `theme`, `network`, `ml`, `screens`) take closures.
 
 The server issues `userId` and `jobId` and returns them in the submission response — partners receive both via `onResult`. Don't construct them client-side.
 
@@ -153,6 +153,7 @@ The server issues `userId` and `jobId` and returns them in the submission respon
 b.config((c) => {
   c.enableDebugMode = false;
   c.allowOfflineMode = false;
+  c.skipApiSubmission = false;
   c.enableCrashReporting = true;
   c.showAttribution = true;
 });
@@ -162,6 +163,7 @@ b.config((c) => {
 | ---------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `enableDebugMode`      | `boolean` | `false` | Shows a validation error screen on build failure                                                                                                                |
 | `allowOfflineMode`     | `boolean` | `false` | Allows the flow to run without a network connection                                                                                                             |
+| `skipApiSubmission`    | `boolean` | `false` | Captures the job and hands it back as `{ status: "captured", job }` instead of submitting it. The files stay on disk for you to forward and delete              |
 | `enableCrashReporting` | `boolean` | `true`  | Enables Sentry crash reporting for the SDK. Set to `false` if your app runs its own Sentry                                                                      |
 | `showAttribution`      | `boolean` | `true`  | Shows the "Powered by Smile ID" mark on every screen that carries it. Set to `false` to hide it across the whole journey. Document capture never shows the mark |
 
@@ -246,7 +248,7 @@ b.network((n) => {
     c.onTokenExpired = async (previous) => fetchFreshToken();
     c.partnerConfig((p) => {
       p.partnerId = "your-partner-id";
-      p.callbackUrl = "https://example.com/callback";
+      p.callbackUrl = "https://your-registered-domain/webhook";
       p.useSandbox = false;
     });
     c.logging((l) => {
@@ -268,7 +270,7 @@ b.network((n) => {
     i.add(i.gzip());
     i.add(
       i.logging((l) => {
-        l.level = LogLevel.body;
+        l.level = LogLevel.body; // bodies in a development build only
       }),
     );
     i.add(myCustomInterceptor); // partner-supplied
@@ -286,12 +288,12 @@ b.network((n) => {
 
 #### `partnerConfig` block
 
-| Property        | Type                      | Default     | Description                                                                                                                          |
-| --------------- | ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `partnerId`     | `string`                  | `""`        | Your Smile ID partner ID                                                                                                             |
-| `callbackUrl`   | `string`                  | `""`        | Webhook URL for job results                                                                                                          |
-| `useSandbox`    | `boolean`                 | `false`     | Route requests to the sandbox environment                                                                                            |
-| `partnerParams` | `Record<string, string>?` | `undefined` | Optional partner-defined key/value pairs forwarded as the `partner_params` JSON multipart part on Enhanced/Biometric KYC submissions |
+| Property        | Type                      | Default     | Description                                                                                                                                   |
+| --------------- | ------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `partnerId`     | `string`                  | `""`        | Your Smile ID partner ID                                                                                                                      |
+| `callbackUrl`   | `string`                  | `""`        | Webhook URL for job results. Sent on every product when non-empty; blank omits it and the job uses the account's default for that environment |
+| `useSandbox`    | `boolean`                 | `false`     | Route requests to the sandbox environment                                                                                                     |
+| `partnerParams` | `Record<string, string>?` | `undefined` | Optional partner-defined key/value pairs forwarded as the `partner_params` JSON multipart part on Enhanced/Biometric KYC submissions          |
 
 #### `logging` block
 
@@ -458,10 +460,10 @@ Calling `useFlowNavigation()` outside `<UseSmileIDBuilder>` throws — the misus
 
 ## Top-level builder callbacks
 
-| Property           | Type                                                        | Description                                               |
-| ------------------ | ----------------------------------------------------------- | --------------------------------------------------------- |
-| `onResult`         | `(result: UseSmileIDResult<JobSubmissionResponse>) => void` | Called once when the flow finishes (success or failure)   |
-| `onAnalyticsEvent` | `((event: UseSmileIDAnalyticsEvent) => void) \| undefined`  | Optional. Called for each analytics event during the flow |
+| Property           | Type                                                        | Description                                                                                                  |
+| ------------------ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `onResult`         | `(result: UseSmileIDResult<JobSubmissionResponse>) => void` | Called once when the flow finishes (success, failure, cancelled, or captured when `skipApiSubmission` is on) |
+| `onAnalyticsEvent` | `((event: UseSmileIDAnalyticsEvent) => void) \| undefined`  | Optional. Called for each analytics event during the flow                                                    |
 
 ---
 
@@ -469,12 +471,13 @@ Calling `useFlowNavigation()` outside `<UseSmileIDBuilder>` throws — the misus
 
 Each job type that needs identity fields reads them from a top-level builder property. The shared `user_details` part (`b.userDetails`) is required by every KYC and document job; `country` is the ISO 3166-1 alpha-2 code.
 
-| Job type                               | Builder property                       | Required fields                 | Notes                                                                    |
-| -------------------------------------- | -------------------------------------- | ------------------------------- | ------------------------------------------------------------------------ |
-| `JobType.enhancedKyc`                  | `b.enhancedKYCParams`                  | `idType`, `idNumber`, `country` | Optional `bankCode`, `mobileOperator`                                    |
-| `JobType.biometricKyc`                 | `b.biometricKYCParams`                 | `idType`, `idNumber`, `country` | `useEnrolledImage` toggles the enrolled-image path                       |
-| `JobType.documentVerification`         | `b.documentVerificationParams`         | `country`                       | `idType` **optional** — omit it to let the backend classify the document |
-| `JobType.enhancedDocumentVerification` | `b.enhancedDocumentVerificationParams` | `country`, `idType`             | `idType` **required** — drives the ID-authority cross-check              |
+| Job type                                | Builder property                        | Required fields                 | Notes                                                                                                                                                                                                                     |
+| --------------------------------------- | --------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `JobType.enhancedKyc`                   | `b.enhancedKYCParams`                   | `idType`, `idNumber`, `country` | Optional `bankCode`, `mobileOperator`                                                                                                                                                                                     |
+| `JobType.biometricKyc`                  | `b.biometricKYCParams`                  | `idType`, `idNumber`, `country` | `useEnrolledImage` toggles the enrolled-image path                                                                                                                                                                        |
+| `JobType.documentVerification`          | `b.documentVerificationParams`          | `country`                       | `idType` **optional** — omit it to let the backend classify the document                                                                                                                                                  |
+| `JobType.enhancedDocumentVerification`  | `b.enhancedDocumentVerificationParams`  | `country`, `idType`             | `idType` **required** — drives the ID-authority cross-check                                                                                                                                                               |
+| `JobType.residencyDocumentVerification` | `b.residencyDocumentVerificationParams` | `country`, `idType`             | `idType` must be `"PASSPORT"` (exported as `RESIDENCY_ID_TYPE`); passport data page plus a mandatory visa page from one document capture step; the step must use `DocumentType.Passport`, and `allowSkipBack` is rejected |
 
 ```ts
 // Document Verification — idType optional
@@ -492,8 +495,18 @@ b.userDetails = {
   lastName: "Doe",
   phoneNumber: "+254700000000",
 };
+
+// Residency Document Verification — passport data page, then a mandatory visa page
+b.residencyDocumentVerificationParams = { country: "AE", idType: "PASSPORT" };
+b.userDetails = {
+  givenNames: "Jane",
+  lastName: "Doe",
+  email: "jane@example.com",
+};
 ```
 
+`DocumentSide` (exported from `@smileid/usesmileid`) gains `Visa` (`"visa"`) for the residency visa page, so an exhaustive `switch` over it needs the new case.
+
 `user_details` requires non-blank `givenNames` and `lastName` plus at least one of `email` / `phoneNumber`. Pre-flight any payload with `b.validateDocumentVerificationParams(...)`, `b.validateEnhancedDocumentVerificationParams(...)`, or `b.validateUserDetails(...)` before assigning.
 
 ---
@@ -511,13 +524,44 @@ b.onResult = (result) => {
     case "failure":
       console.error("flow failed:", result.error);
       break;
+    case "cancelled":
+      console.log("user exited before finishing");
+      break;
+    case "captured":
+      console.log(
+        `captured ${result.job.jobType}; forward ${result.job.sessionDirectory}`,
+      );
+      break;
   }
 };
 ```
 
 The success branch carries a `JobSubmissionResponse` with `jobId`, `userId`, `status`, `message`, and an optional `createdAt`. Partner-supplied inputs (captured frames, identity fields, consent) are not echoed back — keep references at the call site if you need them after the flow.
 
-`UseSmileIDResult<T>` is a discriminated union — `result.status` narrows it, no `try` / `catch` needed.
+`UseSmileIDResult<T>` is a discriminated union — `result.status` narrows it, no `try` / `catch` needed. The statuses are `"success"`, `"failure"`, `"cancelled"` (the user left before finishing — nothing was submitted) and `"captured"`, delivered only when `c.skipApiSubmission = true`.
+
+A `"captured"` result carries a `CapturedJob`:
+
+| Field                           | Type                               | Description                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `jobType`                       | `JobType`                          | The configured job type                                                                                                                                                                                                                                                                                                                                                                                        |
+| `sessionId`                     | `string`                           | The flow's session id, also on every analytics event                                                                                                                                                                                                                                                                                                                                                           |
+| `sessionDirectory`              | `string \| undefined`              | The session folder the SDK kept for this job. In this mode the SDK deletes neither it nor the files, so once you have forwarded the job, delete every file listed here, then this folder and everything left in it. Absent when the files don't share one of the SDK's session folders (a document job's selfie and document come from separate capture sessions), or the job captured no files (Enhanced KYC) |
+| `selfieImage`                   | `string \| undefined`              | Selfie file URI for selfie-bearing jobs                                                                                                                                                                                                                                                                                                                                                                        |
+| `livenessImages`                | `readonly string[]`                | Liveness frame URIs for selfie-bearing jobs                                                                                                                                                                                                                                                                                                                                                                    |
+| `frontDocument`, `backDocument` | `string \| undefined`              | Document side URIs for document jobs                                                                                                                                                                                                                                                                                                                                                                           |
+| `visaDocument`                  | `string \| undefined`              | The visa page URI, for Residency Document Verification                                                                                                                                                                                                                                                                                                                                                         |
+| `headers`                       | `Readonly<Record<string, string>>` | `smileid-token`, `smileid-source-sdk` and `smileid-source-sdk-version`, to send as request headers                                                                                                                                                                                                                                                                                                             |
+| `encryptedPackage`              | `string`                           | The rest of the request, sealed for Smile ID; send it as the `encrypted_package` form field                                                                                                                                                                                                                                                                                                                    |
+| `packageNonce`, `packageTag`    | `string`                           | The package's nonce and tag; send them as the `package_nonce` and `package_tag` form fields                                                                                                                                                                                                                                                                                                                    |
+
+To forward the job, send the job type's `/v3` request with `headers`, the images as their usual form parts, and the three package fields. The package holds everything else the SDK would have sent (the consent record, the metadata and the request signature), encrypted with AES-256-GCM for Smile ID. Forward it as is: the server rejects a package that was changed. Forward the image files byte-for-byte too: they carry an integrity seal that re-encoding invalidates. A document imported from the gallery or taken with the manual shutter is kept in the app's cache, which the OS may clear under storage pressure, so forward such a job promptly.
+
+Send each file under the form part the SDK would have used: `selfieImage` as `selfie_image`, `livenessImages` as `liveness_images` in the list's order, `frontDocument` as `document`, `backDocument` as `document_back` and `visaDocument` as `visa`. The request signature in the package covers the images by part name and order, so the server rejects a job sent any other way. Forward the job soon after the flow ends: the package carries the access token and the request timestamp from the capture, which the server checks and which can't be refreshed without capturing again.
+
+On iOS the system can move the app's data container between launches, for example across an app update, so don't save these absolute URIs. To forward a job in a later launch, save each path relative to the container and rebuild it then.
+
+The processing screen keeps its spinner after the hand-over, because nothing was submitted, so unmount the flow in `onResult`, as for every other result.
 
 ### Forwarding failures to a crash reporter
 
@@ -576,7 +620,7 @@ Every event automatically includes `session_id` and `timestamp` (epoch milliseco
 | `screen_viewed`     | Each screen becomes active         | `screen_name`                                                                     |
 | `consent_captured`  | User grants consent                | `decision: "granted"`                                                             |
 | `selfie_captured`   | Selfie + liveness captured         | `liveness_image_count`                                                            |
-| `document_captured` | Document image captured            | `document_side: "front"` or `"both"`                                              |
+| `document_captured` | Document image captured            | `document_side: "front"`, `"back"` or `"visa"`, one event per image               |
 | `retake_requested`  | User navigates back to redo a step | —                                                                                 |
 | `job_submitted`     | API submission begins              | `job_type`, `attempt`                                                             |
 | `flow_completed`    | Flow finishes                      | `result: "success"` or `"failure"`, `job_id` (success), `error_message` (failure) |
@@ -690,7 +734,7 @@ export function DocumentVerificationScreen({
               c.token = "your-v3-token";
               c.partnerConfig((p) => {
                 p.partnerId = "your-partner-id";
-                p.callbackUrl = "https://example.com/callback";
+                p.callbackUrl = "https://your-registered-domain/webhook";
                 p.useSandbox = true;
               });
               c.logging((l) => {

package/dist/camera/bounding_box_metering_region.d.ts

@@ -0,0 +1,10 @@
+import type { KameraRegion } from "@smileid/kamera";
+import type { BoundingBox } from "@smileid/usesmileid_bridge";
+/**
+ * `box` as the region kamera meters exposure on, in the frame as displayed: flipped first when
+ * `flipped`, because the detector saw the unmirrored frame, then clamped to the frame. Null when
+ * none of it is inside.
+ */
+export declare function meteringRegion(box: Pick<BoundingBox, "left" | "top" | "width" | "height">, flipped: boolean): KameraRegion | null;
+/** The largest of `faces` by area, or null when there are none. */
+export declare function largestFace<T extends Pick<BoundingBox, "width" | "height">>(faces: readonly T[]): T | null;

package/dist/camera/bounding_box_metering_region.js

@@ -0,0 +1 @@
+"use strict";export function meteringRegion(t,n){const e=n?1-t.left-t.width:t.left,h=i(e),r=i(t.top),c=i(e+t.width),l=i(t.top+t.height);return c<=h||l<=r?null:{x:h,y:r,width:c-h,height:l-r}}export function largestFace(t){let n=null;for(const e of t)(n===null||e.width*e.height>n.width*n.height)&&(n=e);return n}function i(t){return Math.min(1,Math.max(0,t))}

package/dist/camera/document_image_pipeline.d.ts

@@ -1,6 +1,15 @@
 import { DocumentSide } from "@smileid/usesmileid_bridge";
 export { computeDocumentResizeTarget } from "./document_resize_target";
-/** Canonical per-side artifact basename, matching the auto-capture naming. */
+/**
+ * Imported document image pipeline — brings a manual-shutter still or gallery
+ * image onto the SAME byte policy as the native auto-capture artifact: longest
+ * edge downscaled to {@link CameraDefaults.documentMaxDimension} at
+ * {@link CameraDefaults.documentJpegQuality}, written under the canonical
+ * per-side filename. The Smile EXIF `UserComment` tag is stamped downstream by
+ * `SmileExifTagger.finalize`, so every upload is byte-policy-identical
+ * regardless of capture path.
+ */
+/** Canonical per-image artifact basename, matching the auto-capture naming. */
 export declare function documentArtifactFileName(side: DocumentSide): string;
 /** Source image for an imported document capture (manual shutter or gallery). */
 export type ImportedDocumentSource = {

package/dist/camera/document_image_pipeline.js

@@ -1 +1 @@
-"use strict";import{Directory as c,File as i,Paths as m}from"expo-file-system";import{ImageManipulator as s,SaveFormat as u}from"expo-image-manipulator";import{DocumentSide as d,UseSmileIDCrashReporting as p}from"@smileid/usesmileid_bridge";import{CameraDefaults as o}from"./camera_defaults";import{computeDocumentResizeTarget as f}from"./document_resize_target";export{computeDocumentResizeTarget}from"./document_resize_target";const l="usesmileid_documents";export function documentArtifactFileName(e){return e===d.Back?"document_back.jpg":"document_front.jpg"}export async function resampleImportedDocument(e,n){const t=e.width!==void 0&&e.height!==void 0?f(e.width,e.height,o.documentMaxDimension):null,r=s.manipulate(e.uri);t&&r.resize(t);const a=await(await r.renderAsync()).saveAsync({compress:o.documentJpegQuality,format:u.JPEG});return g(a.uri,n)}function g(e,n){try{const t=new c(m.cache,l);t.exists||t.create({intermediates:!0});const r=new i(t,documentArtifactFileName(n));return r.exists&&r.delete(),new i(e).move(r),r.uri}catch(t){return p.captureException(t instanceof Error?t:new Error(String(t))),e}}
+"use strict";import{File as i}from"expo-file-system";import{ImageManipulator as m,SaveFormat as s}from"expo-image-manipulator";import{DocumentSide as o,UseSmileIDCrashReporting as u}from"@smileid/usesmileid_bridge";import{CameraDefaults as a}from"./camera_defaults";import{computeDocumentResizeTarget as d}from"./document_resize_target";import{newImportedDocumentFolder as p}from"./imported_document_folder";export{computeDocumentResizeTarget}from"./document_resize_target";export function documentArtifactFileName(t){switch(t){case o.Back:return"document_back.jpg";case o.Visa:return"document_visa.jpg";default:return"document_front.jpg"}}export async function resampleImportedDocument(t,n){const r=t.width!==void 0&&t.height!==void 0?d(t.width,t.height,a.documentMaxDimension):null,e=m.manipulate(t.uri);r&&e.resize(r);const c=await(await e.renderAsync()).saveAsync({compress:a.documentJpegQuality,format:s.JPEG});return f(c.uri,n)}function f(t,n){const r=p();try{r.exists||r.create({intermediates:!0});const e=new i(r,documentArtifactFileName(n));return e.exists&&e.delete(),new i(t).move(e),e.uri}catch(e){u.captureException(e instanceof Error?e:new Error(String(e)));try{r.exists&&r.delete()}catch{}return t}}

package/dist/camera/imported_document_folder.d.ts

@@ -0,0 +1,15 @@
+import { Directory } from "expo-file-system";
+/** Subdirectory under the cache directory holding imported document artifacts. */
+export declare const IMPORT_SUBDIRECTORY = "usesmileid_documents";
+/**
+ * A new `<cache>/usesmileid_documents/<id>/` folder for one import. Each import
+ * gets its own: a skip-submission hand-over gives the partner the path to
+ * forward later, so a later flow must never overwrite or delete it.
+ */
+export declare function newImportedDocumentFolder(): Directory;
+/**
+ * Delete an imported document together with the folder it was written into. A
+ * no-op for any other file, such as a camera capture, so a caller can pass
+ * every document path it drops.
+ */
+export declare function deleteImportedDocument(uri: string): void;

package/dist/camera/imported_document_folder.js

@@ -0,0 +1 @@
+"use strict";import{Directory as r,File as c,Paths as u}from"expo-file-system";import{generateSessionId as s}from"../metadata/use_smile_id_metadata_factory";export const IMPORT_SUBDIRECTORY="usesmileid_documents";export function newImportedDocumentFolder(){return new r(o(),s())}function o(){return new r(u.cache,IMPORT_SUBDIRECTORY)}function n(e){return e.replace(/\/+$/,"")}export function deleteImportedDocument(e){try{const t=new c(e).parentDirectory,i=n(o().uri);if(n(t.parentDirectory.uri)!==i)return;t.exists&&t.delete()}catch{}}

package/dist/camera/kamera_config_factory.d.ts

@@ -1,7 +1,17 @@
 import type { KameraConfig, Lens } from "@smileid/kamera";
 import { CaptureType } from "../core/models/ml_config";
 import { CameraLens } from "./camera_lens";
-/** Maps the SDK's capture inputs onto a kamera `KameraConfig` via the tuned kamera presets. */
+/**
+ * The selfie's analysis interval: 30 frames a second, which its 0.2 s
+ * reference window and the settling counted inside each 350 ms interval assume.
+ */
+export declare const SELFIE_ANALYSIS_INTERVAL_MS = 33;
+/**
+ * Maps the SDK's capture inputs onto a kamera `KameraConfig` via the tuned kamera presets. A selfie
+ * analyses every {@link SELFIE_ANALYSIS_INTERVAL_MS} and asks for each frame's device motion (the
+ * shake gate), as the native screens do; on iOS it also asks for kamera's face tracking (ARKit on a
+ * TrueDepth front camera, whose tracked face the selfie reads).
+ */
 export declare const KameraConfigFactory: {
     readonly create: (captureType: CaptureType, lens: CameraLens) => KameraConfig;
 };

package/dist/camera/kamera_config_factory.js

@@ -1 +1 @@
-"use strict";import{KameraDefaults as t}from"@smileid/kamera";import{CaptureType as a}from"../core/models/ml_config";import{CameraLens as m}from"./camera_lens";export const KameraConfigFactory={create(e,o){const r=toKameraLens(o);return e===a.document?t.document(r):t.selfie(r)}};export function toKameraLens(e){return e===m.back?"back":"front"}
+"use strict";import{Platform as n}from"react-native";import{KameraDefaults as o}from"@smileid/kamera";import{CaptureType as m}from"../core/models/ml_config";import{CameraLens as i}from"./camera_lens";export const SELFIE_ANALYSIS_INTERVAL_MS=33,KameraConfigFactory={create(e,a){const r=toKameraLens(a);if(e===m.document)return o.document(r);const t=o.selfie(r);return{...t,analysis:{...t.analysis,minIntervalMs:SELFIE_ANALYSIS_INTERVAL_MS,deviceMotion:!0,...n.OS==="ios"?{faceTracking:!0}:{}}}}};export function toKameraLens(e){return e===i.back?"back":"front"}

package/dist/camera/use_smile_id_frame_stream.js

@@ -1 +1 @@
-"use strict";import{useCallback as E,useEffect as i,useMemo as d,useRef as c}from"react";import{documentScanResultSchema as y,faceScanResultSchema as S,FrameProcessingException as p}from"@smileid/usesmileid_bridge";export function useSmileIDFrameStream(e,r,t){const f=c(e),o=c(r),u=c(t?.onError),a=c(!1),s=c(!0);i(()=>{f.current=e},[e]),i(()=>{o.current=r},[r]),i(()=>{u.current=t?.onError},[t?.onError]),i(()=>(s.current=!0,()=>{s.current=!1}),[]);const n=E(l=>{const m=u.current;dispatchFrameResult({raw:l,analyzer:f.current,isBusy:()=>a.current,setBusy:R=>{a.current=R},isMounted:()=>s.current,onResult:o.current,...m!==void 0?{onError:m}:{}})},[]);return d(()=>({onFrameResult:n}),[n])}function h(e){if(e===null||typeof e!="object")return null;const r=e.error;return typeof r=="string"?r:null}const _=new Set(["no_frame","session_not_configured"]);export function dispatchFrameResult(e){const{raw:r,analyzer:t,isBusy:f,setBusy:o,isMounted:u,onResult:a,onError:s}=e;if(t&&!f()){o(!0);try{const n=h(r);if(n!==null){if(_.has(n))return;throw new p({reason:n})}const l=t.kind==="face"?S.parse(r):y.parse(r);if(!u())return;a(l)}catch(n){if(!u())return;s?.(n)}finally{o(!1)}}}
+"use strict";import{useCallback as y,useEffect as l,useMemo as E,useRef as a}from"react";import{documentScanResultSchema as S,faceScanResultSchema as h,FrameProcessingException as B}from"@smileid/usesmileid_bridge";import{isDevelopmentBuild as p}from"../core/is_development_build";import{UseSmileIDDebugTap as R}from"../debug/use_smile_id_debug_tap";export function useSmileIDFrameStream(e,r,o){const i=a(e),s=a(r),u=a(o?.onError),c=a(!1),f=a(!0);l(()=>{i.current=e},[e]),l(()=>{s.current=r},[r]),l(()=>{u.current=o?.onError},[o?.onError]),l(()=>(f.current=!0,()=>{f.current=!1}),[]);const n=y(t=>{const m=u.current;dispatchFrameResult({raw:t,analyzer:i.current,isBusy:()=>c.current,setBusy:d=>{c.current=d},isMounted:()=>f.current,onResult:s.current,...m!==void 0?{onError:m}:{}})},[]);return E(()=>({onFrameResult:n}),[n])}function D(e){if(e===null||typeof e!="object")return null;const r=e.error;return typeof r=="string"?r:null}const _=new Set(["no_frame","session_not_configured"]);export function dispatchFrameResult(e){const{raw:r,analyzer:o,isBusy:i,setBusy:s,isMounted:u,onResult:c,onError:f}=e;if(o&&!i()){s(!0);try{const n=D(r);if(n!==null){if(_.has(n))return;throw new B({reason:n})}if(o.kind==="face"){const t=h.parse(r);if(!u())return;c(t),p()&&R.analyzedFace(t.output)}else{const t=S.parse(r);if(!u())return;c(t),p()&&R.analyzedDocument(t.output)}}catch(n){if(!u())return;f?.(n)}finally{s(!1)}}}

package/dist/camera/use_smile_id_kamera_camera_system.d.ts

@@ -1,11 +1,23 @@
 import type { KameraCapabilities, KameraCaptureResult, KameraEvent } from "@smileid/kamera";
 import { KameraSession } from "@smileid/kamera";
+import { type BoundingBox, type DocumentGuide } from "@smileid/usesmileid_bridge";
 import { CameraLens } from "./camera_lens";
 import type { CameraConfiguration, CameraSystemState } from "./camera_configuration";
 import type { FocusPoint, FocusState } from "./focus_state";
 type Listener = (state: CameraSystemState, focus: FocusState) => void;
-/** The kamera session surface this system drives; structural so tests can inject an in-memory fake. */
-export type KameraSessionLike = Pick<KameraSession, "start" | "stop" | "capture" | "setZoomRatio" | "setTorch" | "tapToFocus" | "setExposureCompensation" | "capabilities" | "release" | "addEventListener">;
+/**
+ * The kamera session surface this system drives; structural so tests can inject an in-memory fake.
+ * `setMeteringRegion` is optional so a session built against the earlier surface still fits; without
+ * it the selfie meters the whole frame.
+ */
+export type KameraSessionLike = Pick<KameraSession, "start" | "stop" | "capture" | "setZoomRatio" | "setTorch" | "tapToFocus" | "setExposureCompensation" | "capabilities" | "release" | "addEventListener"> & Partial<Pick<KameraSession, "setMeteringRegion" | "setDocumentGuide" | "setMetricsEnabled">>;
+/**
+ * Turns kamera's perf metrics on or off from the next camera start; they arrive as `metric`
+ * events. Internal: the capture screen calls it for the perf trace.
+ */
+export declare function setKameraMetricsWanted(enabled: boolean): void;
+/** Test seam: forgets what was sent to kamera. */
+export declare function resetKameraMetricsForTesting(): void;
 /**
  * Kamera-backed orchestrator: drives the native session and republishes its state via `subscribe()`.
  * Pixels never cross the bridge — frame analysis and still capture run in the native cores.
@@ -28,6 +40,12 @@ export declare class UseSmileIDKameraCameraSystem {
     get focusState(): FocusState;
     /** Device/session capabilities, available once running. */
     get capabilities(): KameraCapabilities | null;
+    /**
+     * The upright preview's width over its height on a portrait screen: the configured session's
+     * preview ratio with its short side across. kamera binds the analysis stream to the same ratio,
+     * so it is also the analysed frame's.
+     */
+    get uprightPreviewAspect(): number;
     /**
      * The active session, for `UseSmileIDKameraPreview` only — drive it through this class's API.
      * Null until `start()` succeeds.
@@ -45,6 +63,33 @@ export declare class UseSmileIDKameraCameraSystem {
     capture(): Promise<KameraCaptureResult>;
     /** Sets zoom, clamped to the session's capability range. */
     setZoomRatio(ratio: number): Promise<void>;
+    /** The guide last asked for: what the camera should hold. */
+    private _documentGuide;
+    /** Whether the current session confirmed `_documentGuide`. */
+    private _documentGuideApplied;
+    /** The session a guide is being sent to, so only one send is in flight. */
+    private _documentGuideSendingTo;
+    private _documentGuideFailureReported;
+    /**
+     * Sets what the document guide frames, so the camera zooms only as far as
+     * the document filling the guide needs to stay in focus. Null clears it and
+     * leaves the camera's default close-focus floor.
+     *
+     * Called on every frame: a repeat sends nothing, and only one guide is in
+     * flight at a time, the latest one asked for following it. A guide set
+     * before the camera starts reaches it once it does. A guide the camera
+     * refuses is sent again on the next call; the first refusal is reported to
+     * crash reporting. Never rejects.
+     */
+    setDocumentGuide(guide: DocumentGuide | null): Promise<void>;
+    /**
+     * Sends the guide asked for to the current session until it holds the
+     * latest one, one send at a time; stops at a refusal, which the next call
+     * retries, or when the session changes, whose start sends the guide itself.
+     */
+    private _applyDocumentGuide;
+    /** Sends `guide` to `session`; false when the session refuses it. */
+    private _sendDocumentGuide;
     /** Toggles the torch; a no-op without a flash unit. */
     setTorch(enabled: boolean): Promise<void>;
     /**
@@ -52,6 +97,11 @@ export declare class UseSmileIDKameraCameraSystem {
      * Drives the reticle running → success → unspecified on the standard cadence.
      */
     tapToFocus(point: FocusPoint): Promise<void>;
+    /**
+     * Meters exposure on `face`, a box from the face analyzer, or on the whole frame when null.
+     * kamera decides when the camera actually re-meters, so it is called on every analysed frame.
+     */
+    meterExposure(face: BoundingBox | null): void;
     /** Releases the native session. The system is unusable afterwards. */
     release(): Promise<void>;
     private _onKameraEvent;

package/dist/camera/use_smile_id_kamera_camera_system.js

@@ -1 +1 @@
-"use strict";import{KameraSession as u}from"@smileid/kamera";import{CaptureType as o}from"../core/models/ml_config";import{CameraDefaults as c}from"./camera_defaults";import{CameraLens as r}from"./camera_lens";import{FocusStates as i}from"./focus_state";import{KameraConfigFactory as _}from"./kamera_config_factory";export class UseSmileIDKameraCameraSystem{_createSession;_session=null;_removeEventListener=null;_state;_focusState=i.unspecified();_listeners=new Set;_eventListeners=new Set;_capabilities=null;_config={};_released=!1;_focusRunningTimeout=null;_focusSettledTimeout=null;constructor(e=r.front,t=()=>new u){this._createSession=t,this._state={isCameraRunning:!1,isStreaming:!1,currentLens:e,hasPermission:!1}}get state(){return this._state}get focusState(){return this._focusState}get capabilities(){return this._capabilities}get session(){return this._session}subscribe(e){return this._listeners.add(e),()=>this._listeners.delete(e)}addEventListener(e){return this._eventListeners.add(e),()=>this._eventListeners.delete(e)}configure(e){this._config=e,e.lens&&e.lens!==this._state.currentLens&&this._setState({...this._state,currentLens:e.lens})}async start(){if(this._released)throw new Error("UseSmileIDKameraCameraSystem.start() after release() \u2014 create a new system.");await this._teardownSession();const e=this._createSession(),t=e.addEventListener(n=>this._onKameraEvent(n)),s=this._config.captureType??o.selfie,a=this._config.lens??(s===o.document?r.back:r.front);try{await e.start(_.create(s,a)),this._capabilities=await e.capabilities()}catch(n){throw t(),await e.release(),n}this._removeEventListener=t,this._session=e,this._setState({...this._state,isCameraRunning:!0,isStreaming:!0,currentLens:a,hasPermission:!0})}async stop(){await this._session?.stop(),this._setState({...this._state,isCameraRunning:!1,isStreaming:!1})}async capture(){const e=this._session;if(!e)throw new Error("Cannot capture: camera is not initialised.");return e.capture()}async setZoomRatio(e){const t=this._session;if(!t)return;const s=this._capabilities,a=s?Math.min(s.maxZoomRatio,Math.max(s.minZoomRatio,e)):e;await t.setZoomRatio(a)}async setTorch(e){await this._session?.setTorch(e)}async tapToFocus(e){const t=this._session;t&&(this._clearFocusTimers(),this._setFocusState(i.running(e)),t.tapToFocus(e.x,e.y).catch(()=>{this._clearFocusTimers(),this._setFocusState(i.unspecified())}),this._focusRunningTimeout=setTimeout(()=>{this._setFocusState(i.success(e)),this._focusSettledTimeout=setTimeout(()=>{this._setFocusState(i.unspecified())},c.focusSettledDurationMs)},c.focusRunningDurationMs))}async release(){this._released=!0,this._clearFocusTimers(),await this._teardownSession(),this._setState({...this._state,isCameraRunning:!1,isStreaming:!1})}_onKameraEvent(e){for(const t of[...this._eventListeners])t(e);e.type==="error"&&this._setState({...this._state,isStreaming:!1})}async _teardownSession(){this._removeEventListener?.(),this._removeEventListener=null;const e=this._session;this._session=null,this._capabilities=null,e&&await e.release()}_clearFocusTimers(){this._focusRunningTimeout&&clearTimeout(this._focusRunningTimeout),this._focusSettledTimeout&&clearTimeout(this._focusSettledTimeout),this._focusRunningTimeout=null,this._focusSettledTimeout=null}_setState(e){this._state=e,this._notify()}_setFocusState(e){this._focusState=e,this._notify()}_notify(){for(const e of[...this._listeners])e(this._state,this._focusState)}}
+"use strict";import{AspectRatio as f,KameraSession as p}from"@smileid/kamera";import{UseSmileIDCrashReporting as l}from"@smileid/usesmileid_bridge";import{Platform as S}from"react-native";import{CaptureType as c}from"../core/models/ml_config";import{captureDebugBoxesMirrored as g}from"../debug/capture_debug_geometry";import{meteringRegion as w}from"./bounding_box_metering_region";import{CameraDefaults as h}from"./camera_defaults";import{CameraLens as a}from"./camera_lens";import{FocusStates as n}from"./focus_state";import{KameraConfigFactory as _}from"./kamera_config_factory";let m=!1,o=null;export function setKameraMetricsWanted(i){m=i}async function y(i){const e=m;if(e===o)return;o=e;const t=Promise.resolve().then(()=>i.setMetricsEnabled?.(e)).catch(s=>{o=null,l.captureException(s instanceof Error?s:new Error(String(s)))});e&&await t}export function resetKameraMetricsForTesting(){m=!1,o=null}export class UseSmileIDKameraCameraSystem{_createSession;_session=null;_removeEventListener=null;_state;_focusState=n.unspecified();_listeners=new Set;_eventListeners=new Set;_capabilities=null;_config={};_released=!1;_focusRunningTimeout=null;_focusSettledTimeout=null;constructor(e=a.front,t=()=>new p){this._createSession=t,this._state={isCameraRunning:!1,isStreaming:!1,currentLens:e,hasPermission:!1}}get state(){return this._state}get focusState(){return this._focusState}get capabilities(){return this._capabilities}get uprightPreviewAspect(){const e=this._config.captureType??c.selfie;return _.create(e,this._state.currentLens).preview.aspectRatio===f.Ratio16x9?9/16:3/4}get session(){return this._session}subscribe(e){return this._listeners.add(e),()=>this._listeners.delete(e)}addEventListener(e){return this._eventListeners.add(e),()=>this._eventListeners.delete(e)}configure(e){this._config=e,e.lens&&e.lens!==this._state.currentLens&&this._setState({...this._state,currentLens:e.lens})}async start(){if(this._released)throw new Error("UseSmileIDKameraCameraSystem.start() after release() \u2014 create a new system.");await this._teardownSession();const e=this._createSession(),t=e.addEventListener(u=>this._onKameraEvent(u)),s=this._config.captureType??c.selfie,r=this._config.lens??(s===c.document?a.back:a.front);try{await y(e),await e.start(_.create(s,r)),this._capabilities=await e.capabilities()}catch(u){throw t(),await e.release(),u}this._removeEventListener=t,this._session=e,this._documentGuideApplied=this._documentGuide===null,await this._applyDocumentGuide(),this._setState({...this._state,isCameraRunning:!0,isStreaming:!0,currentLens:r,hasPermission:!0})}async stop(){await this._session?.stop(),this._setState({...this._state,isCameraRunning:!1,isStreaming:!1})}async capture(){const e=this._session;if(!e)throw new Error("Cannot capture: camera is not initialised.");return e.capture()}async setZoomRatio(e){const t=this._session;if(!t)return;const s=this._capabilities,r=s?Math.min(s.maxZoomRatio,Math.max(s.minZoomRatio,e)):e;await t.setZoomRatio(r)}_documentGuide=null;_documentGuideApplied=!0;_documentGuideSendingTo=null;_documentGuideFailureReported=!1;async setDocumentGuide(e){d(e,this._documentGuide)||(this._documentGuide=e,this._documentGuideApplied=!1),await this._applyDocumentGuide()}async _applyDocumentGuide(){const e=this._session;if(!(e===null||this._documentGuideApplied||this._documentGuideSendingTo===e)){this._documentGuideSendingTo=e;try{for(;!this._documentGuideApplied&&this._session===e;){const t=this._documentGuide;if(!await this._sendDocumentGuide(e,t))return;this._session===e&&d(t,this._documentGuide)&&(this._documentGuideApplied=!0)}}finally{this._documentGuideSendingTo===e&&(this._documentGuideSendingTo=null)}}}async _sendDocumentGuide(e,t){try{return await e.setDocumentGuide?.(t?.widthMm??0,t?.frameWidthFraction??0),!0}catch(s){return this._documentGuideFailureReported||(this._documentGuideFailureReported=!0,l.captureException(s instanceof Error?s:new Error(String(s)))),!1}}async setTorch(e){await this._session?.setTorch(e)}async tapToFocus(e){const t=this._session;t&&(this._clearFocusTimers(),this._setFocusState(n.running(e)),t.tapToFocus(e.x,e.y).catch(()=>{this._clearFocusTimers(),this._setFocusState(n.unspecified())}),this._focusRunningTimeout=setTimeout(()=>{this._setFocusState(n.success(e)),this._focusSettledTimeout=setTimeout(()=>{this._setFocusState(n.unspecified())},h.focusSettledDurationMs)},h.focusRunningDurationMs))}meterExposure(e){const t=this._session;if(!t)return;const s=e?w(e,g(this._state.currentLens===a.front,S.OS==="android")):null;t.setMeteringRegion?.(s).catch(()=>{})}async release(){this._released=!0,this._clearFocusTimers(),await this._teardownSession(),this._setState({...this._state,isCameraRunning:!1,isStreaming:!1})}_onKameraEvent(e){for(const t of[...this._eventListeners])t(e);e.type==="error"&&this._setState({...this._state,isStreaming:!1})}async _teardownSession(){this._removeEventListener?.(),this._removeEventListener=null;const e=this._session;this._session=null,this._capabilities=null,e&&await e.release()}_clearFocusTimers(){this._focusRunningTimeout&&clearTimeout(this._focusRunningTimeout),this._focusSettledTimeout&&clearTimeout(this._focusSettledTimeout),this._focusRunningTimeout=null,this._focusSettledTimeout=null}_setState(e){this._state=e,this._notify()}_setFocusState(e){this._focusState=e,this._notify()}_notify(){for(const e of[...this._listeners])e(this._state,this._focusState)}}function d(i,e){return i?.widthMm===e?.widthMm&&i?.frameWidthFraction===e?.frameWidthFraction}

package/dist/core/exception/invalid_job_type_screen_config_exception.js

@@ -1 +1 @@
-"use strict";import{JobType as e}from"../../core/models/job_type";import{UseSmileIDBuilderException as i}from"./use_smile_id_builder_exception";import{UseSmileIDErrorCode as r}from"./use_smile_id_error_code";export class InvalidJobTypeScreenConfigException extends i{errorCode=r.Builder.InvalidJobTypeScreenConfig;constructor(n){super({message:n.message,suggestedFix:n.suggestedFix??"Adjust the screens block to match the configured jobType."})}static forJob(n){const t=jobTypeName(n.jobType);return new InvalidJobTypeScreenConfigException({message:`Invalid configuration for ${t}: ${n.reason}`,suggestedFix:n.suggestedFix})}}const c=new Map([[e.biometricKyc,"BiometricKyc"],[e.smartSelfieAuthentication,"SmartSelfieAuthentication"],[e.smartSelfieEnrollment,"SmartSelfieEnrollment"],[e.enhancedKyc,"EnhancedKyc"],[e.documentVerification,"DocumentVerification"],[e.bvn,"BVN"],[e.enhancedDocumentVerification,"EnhancedDocumentVerification"],[e.unknown,"Unknown"]]);export function jobTypeName(o){return c.get(o)??"Unknown"}
+"use strict";import{JobType as e}from"../../core/models/job_type";import{UseSmileIDBuilderException as i}from"./use_smile_id_builder_exception";import{UseSmileIDErrorCode as r}from"./use_smile_id_error_code";export class InvalidJobTypeScreenConfigException extends i{errorCode=r.Builder.InvalidJobTypeScreenConfig;constructor(n){super({message:n.message,suggestedFix:n.suggestedFix??"Adjust the screens block to match the configured jobType."})}static forJob(n){const t=jobTypeName(n.jobType);return new InvalidJobTypeScreenConfigException({message:`Invalid configuration for ${t}: ${n.reason}`,suggestedFix:n.suggestedFix})}}const c=new Map([[e.biometricKyc,"BiometricKyc"],[e.smartSelfieAuthentication,"SmartSelfieAuthentication"],[e.smartSelfieEnrollment,"SmartSelfieEnrollment"],[e.enhancedKyc,"EnhancedKyc"],[e.documentVerification,"DocumentVerification"],[e.bvn,"BVN"],[e.enhancedDocumentVerification,"EnhancedDocumentVerification"],[e.residencyDocumentVerification,"ResidencyDocumentVerification"],[e.unknown,"Unknown"]]);export function jobTypeName(o){return c.get(o)??"Unknown"}

package/dist/core/exception/missing_partner_config_exception.d.ts

@@ -18,4 +18,6 @@ export declare class MissingPartnerConfigException extends UseSmileIDBuilderExce
     static controlCharacterPartnerId(): MissingPartnerConfigException;
     /** The auth `token` contains a control character (usually a pasted newline). */
     static controlCharacterAuthToken(): MissingPartnerConfigException;
+    /** The `callbackUrl` is a value the server could not resolve. */
+    static unresolvableCallbackUrl(): MissingPartnerConfigException;
 }

package/dist/core/exception/missing_partner_config_exception.js

@@ -1 +1 @@
-"use strict";import{UseSmileIDBuilderException as r}from"./use_smile_id_builder_exception";import{UseSmileIDErrorCode as t}from"./use_smile_id_error_code";export class MissingPartnerConfigException extends r{errorCode=t.Builder.InvalidConfiguration;constructor(e){super({message:e.message,suggestedFix:`Configure the missing field '${e.fieldName}' in the network config block.`,errorDetails:{fieldName:e.fieldName}})}static missingPartnerId(){return new MissingPartnerConfigException({message:"Partner ID is required but was not configured",fieldName:"partnerId"})}static missingAuthToken(){return new MissingPartnerConfigException({message:"Auth token is required but was not configured",fieldName:"authToken"})}static controlCharacterPartnerId(){return new MissingPartnerConfigException({message:"Partner ID must not contain control characters",fieldName:"partnerId"})}static controlCharacterAuthToken(){return new MissingPartnerConfigException({message:"Auth token must not contain control characters",fieldName:"authToken"})}}
+"use strict";import{UseSmileIDBuilderException as t}from"./use_smile_id_builder_exception";import{UseSmileIDErrorCode as r}from"./use_smile_id_error_code";export class MissingPartnerConfigException extends t{errorCode=r.Builder.InvalidConfiguration;constructor(e){super({message:e.message,suggestedFix:`Configure the missing field '${e.fieldName}' in the network config block.`,errorDetails:{fieldName:e.fieldName}})}static missingPartnerId(){return new MissingPartnerConfigException({message:"Partner ID is required but was not configured",fieldName:"partnerId"})}static missingAuthToken(){return new MissingPartnerConfigException({message:"Auth token is required but was not configured",fieldName:"authToken"})}static controlCharacterPartnerId(){return new MissingPartnerConfigException({message:"Partner ID must not contain control characters",fieldName:"partnerId"})}static controlCharacterAuthToken(){return new MissingPartnerConfigException({message:"Auth token must not contain control characters",fieldName:"authToken"})}static unresolvableCallbackUrl(){return new MissingPartnerConfigException({message:"Callback URL must be left unset, an absolute http or https URL, or a callback ID",fieldName:"callbackUrl"})}}

package/dist/core/exception/unused_job_params_exception.js

@@ -1 +1 @@
-"use strict";import{JobType as o}from"../../core/models/job_type";import{jobTypeName as n}from"./invalid_job_type_screen_config_exception";import{IssueSeverity as t}from"./issue_severity";import{UseSmileIDBuilderException as a}from"./use_smile_id_builder_exception";import{UseSmileIDErrorCode as d}from"./use_smile_id_error_code";export const JOB_PARAMS_OWNERS=[{fieldName:"enhancedKYCParams",owner:o.enhancedKyc},{fieldName:"biometricKYCParams",owner:o.biometricKyc},{fieldName:"documentVerificationParams",owner:o.documentVerification},{fieldName:"enhancedDocumentVerificationParams",owner:o.enhancedDocumentVerification}];function s(i){return JOB_PARAMS_OWNERS.find(e=>e.fieldName===i)?.owner}export class UnusedJobParamsException extends a{errorCode=d.Builder.UnusedJobParams;fieldName;constructor(e){const r=s(e.fieldName),m=r===void 0?`Remove builder.${e.fieldName} \u2014 the configured job type does not read it`:`Remove builder.${e.fieldName} \u2014 it belongs to ${n(r)} jobs`;super({message:`${e.fieldName} is set but ${n(e.jobType)} jobs never read it`,severity:t.warning,suggestedFix:m}),this.fieldName=e.fieldName}}
+"use strict";import{JobType as i}from"../../core/models/job_type";import{jobTypeName as n}from"./invalid_job_type_screen_config_exception";import{IssueSeverity as t}from"./issue_severity";import{UseSmileIDBuilderException as a}from"./use_smile_id_builder_exception";import{UseSmileIDErrorCode as d}from"./use_smile_id_error_code";export const JOB_PARAMS_OWNERS=[{fieldName:"enhancedKYCParams",owner:i.enhancedKyc},{fieldName:"biometricKYCParams",owner:i.biometricKyc},{fieldName:"documentVerificationParams",owner:i.documentVerification},{fieldName:"enhancedDocumentVerificationParams",owner:i.enhancedDocumentVerification},{fieldName:"residencyDocumentVerificationParams",owner:i.residencyDocumentVerification}];function c(o){return JOB_PARAMS_OWNERS.find(e=>e.fieldName===o)?.owner}export class UnusedJobParamsException extends a{errorCode=d.Builder.UnusedJobParams;fieldName;constructor(e){const r=c(e.fieldName),m=r===void 0?`Remove builder.${e.fieldName} \u2014 the configured job type does not read it`:`Remove builder.${e.fieldName} \u2014 it belongs to ${n(r)} jobs`;super({message:`${e.fieldName} is set but ${n(e.jobType)} jobs never read it`,severity:t.warning,suggestedFix:m}),this.fieldName=e.fieldName}}

package/dist/core/exception/use_smile_id_error_code.d.ts

@@ -56,6 +56,7 @@ export declare const UseSmileIDErrorCode: {
         readonly NotFound: "NETWORK_NOT_FOUND";
         readonly RateLimit: "NETWORK_RATE_LIMIT";
         readonly ServerError: "NETWORK_SERVER_ERROR";
+        readonly CallbackUrlRequired: "NETWORK_CALLBACK_URL_REQUIRED";
     };
     /** Generic input / state validation. */
     readonly Validation: {

package/dist/core/exception/use_smile_id_error_code.js

@@ -1 +1 @@
-"use strict";export const UseSmileIDErrorCode={Builder:{ValidationError:"BUILDER_VALIDATION_ERROR",InvalidConfiguration:"BUILDER_INVALID_CONFIG",MissingRequiredField:"BUILDER_MISSING_FIELD",InvalidConsentConfig:"BUILDER_INVALID_CONSENT_CONFIG",MissingCaptureType:"BUILDER_MISSING_CAPTURE_TYPE",EmptyScreensBlock:"BUILDER_EMPTY_SCREENS",MissingScreenConfiguration:"BUILDER_MISSING_SCREEN_CONFIG",DuplicateScreenType:"BUILDER_DUPLICATE_SCREEN",InvalidSelfieCaptureConfig:"BUILDER_INVALID_SELFIE_CONFIG",AgentModeWithEnhancedLiveness:"BUILDER_AGENT_MODE_WITH_ENHANCED_LIVENESS",InvalidDocumentCaptureConfig:"BUILDER_INVALID_DOCUMENT_CONFIG",MissingMLConfiguration:"BUILDER_MISSING_ML_CONFIG",MissingNetworkConfiguration:"BUILDER_MISSING_NETWORK_CONFIG",MissingJobType:"BUILDER_MISSING_JOB_TYPE",MissingCaptureForPreview:"BUILDER_MISSING_CAPTURE_FOR_PREVIEW",InvalidScreenOrder:"BUILDER_INVALID_SCREEN_ORDER",ConfigurationBlockFailed:"BUILDER_CONFIG_BLOCK_FAILED",InvalidConsentInformation:"BUILDER_INVALID_CONSENT_INFORMATION",InvalidJobTypeScreenConfig:"BUILDER_INVALID_JOB_TYPE_SCREEN_CONFIG",UnusedJobParams:"BUILDER_UNUSED_JOB_PARAMS"},Camera:{InitializationFailed:"CAMERA_INIT_FAILED",PermissionDenied:"CAMERA_PERMISSION_DENIED",CaptureFailed:"CAMERA_CAPTURE_FAILED",UseCaseNotSupported:"CAMERA_USE_CASE_NOT_SUPPORTED",VideoCaptureDisabled:"CAMERA_VIDEO_DISABLED",Unknown:"CAMERA_UNKNOWN_ERROR"},Network:{ConnectionFailed:"NETWORK_CONNECTION_FAILED",Timeout:"NETWORK_TIMEOUT",RequestFailed:"NETWORK_REQUEST_FAILED",ResponseParseError:"NETWORK_PARSE_ERROR",Unauthorized:"NETWORK_UNAUTHORIZED",Forbidden:"NETWORK_FORBIDDEN",NotFound:"NETWORK_NOT_FOUND",RateLimit:"NETWORK_RATE_LIMIT",ServerError:"NETWORK_SERVER_ERROR"},Validation:{InvalidInput:"VALIDATION_INVALID_INPUT",InvalidState:"VALIDATION_INVALID_STATE",ConstraintViolation:"VALIDATION_CONSTRAINT_VIOLATION"},General:{Unknown:"GENERAL_UNKNOWN_ERROR",InvalidState:"GENERAL_INVALID_STATE",OperationFailed:"GENERAL_OPERATION_FAILED"}};const I=new Set([UseSmileIDErrorCode.Camera.CaptureFailed,UseSmileIDErrorCode.Network.ConnectionFailed,UseSmileIDErrorCode.Network.Timeout,UseSmileIDErrorCode.Network.RequestFailed,UseSmileIDErrorCode.Network.RateLimit,UseSmileIDErrorCode.Network.ServerError]),e=new Set(Object.values(UseSmileIDErrorCode.Network));export function isRetryableErrorCode(E){return I.has(E)}export function isNetworkErrorCode(E){return e.has(E)}
+"use strict";export const UseSmileIDErrorCode={Builder:{ValidationError:"BUILDER_VALIDATION_ERROR",InvalidConfiguration:"BUILDER_INVALID_CONFIG",MissingRequiredField:"BUILDER_MISSING_FIELD",InvalidConsentConfig:"BUILDER_INVALID_CONSENT_CONFIG",MissingCaptureType:"BUILDER_MISSING_CAPTURE_TYPE",EmptyScreensBlock:"BUILDER_EMPTY_SCREENS",MissingScreenConfiguration:"BUILDER_MISSING_SCREEN_CONFIG",DuplicateScreenType:"BUILDER_DUPLICATE_SCREEN",InvalidSelfieCaptureConfig:"BUILDER_INVALID_SELFIE_CONFIG",AgentModeWithEnhancedLiveness:"BUILDER_AGENT_MODE_WITH_ENHANCED_LIVENESS",InvalidDocumentCaptureConfig:"BUILDER_INVALID_DOCUMENT_CONFIG",MissingMLConfiguration:"BUILDER_MISSING_ML_CONFIG",MissingNetworkConfiguration:"BUILDER_MISSING_NETWORK_CONFIG",MissingJobType:"BUILDER_MISSING_JOB_TYPE",MissingCaptureForPreview:"BUILDER_MISSING_CAPTURE_FOR_PREVIEW",InvalidScreenOrder:"BUILDER_INVALID_SCREEN_ORDER",ConfigurationBlockFailed:"BUILDER_CONFIG_BLOCK_FAILED",InvalidConsentInformation:"BUILDER_INVALID_CONSENT_INFORMATION",InvalidJobTypeScreenConfig:"BUILDER_INVALID_JOB_TYPE_SCREEN_CONFIG",UnusedJobParams:"BUILDER_UNUSED_JOB_PARAMS"},Camera:{InitializationFailed:"CAMERA_INIT_FAILED",PermissionDenied:"CAMERA_PERMISSION_DENIED",CaptureFailed:"CAMERA_CAPTURE_FAILED",UseCaseNotSupported:"CAMERA_USE_CASE_NOT_SUPPORTED",VideoCaptureDisabled:"CAMERA_VIDEO_DISABLED",Unknown:"CAMERA_UNKNOWN_ERROR"},Network:{ConnectionFailed:"NETWORK_CONNECTION_FAILED",Timeout:"NETWORK_TIMEOUT",RequestFailed:"NETWORK_REQUEST_FAILED",ResponseParseError:"NETWORK_PARSE_ERROR",Unauthorized:"NETWORK_UNAUTHORIZED",Forbidden:"NETWORK_FORBIDDEN",NotFound:"NETWORK_NOT_FOUND",RateLimit:"NETWORK_RATE_LIMIT",ServerError:"NETWORK_SERVER_ERROR",CallbackUrlRequired:"NETWORK_CALLBACK_URL_REQUIRED"},Validation:{InvalidInput:"VALIDATION_INVALID_INPUT",InvalidState:"VALIDATION_INVALID_STATE",ConstraintViolation:"VALIDATION_CONSTRAINT_VIOLATION"},General:{Unknown:"GENERAL_UNKNOWN_ERROR",InvalidState:"GENERAL_INVALID_STATE",OperationFailed:"GENERAL_OPERATION_FAILED"}};const I=new Set([UseSmileIDErrorCode.Camera.CaptureFailed,UseSmileIDErrorCode.Network.ConnectionFailed,UseSmileIDErrorCode.Network.Timeout,UseSmileIDErrorCode.Network.RateLimit,UseSmileIDErrorCode.Network.ServerError]),e=new Set(Object.values(UseSmileIDErrorCode.Network));export function isRetryableErrorCode(E){return I.has(E)}export function isNetworkErrorCode(E){return e.has(E)}

package/dist/core/exception/use_smile_id_network_exception.d.ts

@@ -34,20 +34,25 @@ export declare abstract class UseSmileIDNetworkException extends UseSmileIDExcep
 export declare class NetworkServerException extends UseSmileIDNetworkException {
     readonly errorCode: NetworkCode;
     readonly statusCode: number;
-    constructor({ statusCode, cause, message, errorDetails, }: {
+    constructor({ statusCode, cause, message, errorDetails, errorCode, }: {
         readonly statusCode: number;
         readonly cause?: unknown;
         readonly message?: string;
         readonly errorDetails?: Readonly<Record<string, unknown>>;
+        readonly errorCode?: NetworkCode;
     });
 }
-/** Network reachability / DNS / TLS / socket failure — never reached the server. */
+/**
+ * Network reachability / DNS / TLS / socket failure — never reached the server. A cancelled
+ * request carries `NETWORK_REQUEST_FAILED`, which isn't retried.
+ */
 export declare class NetworkTransportException extends UseSmileIDNetworkException {
     readonly errorCode: NetworkCode;
-    constructor({ cause, message, errorDetails, }?: {
+    constructor({ cause, message, errorDetails, errorCode, }?: {
         readonly cause?: unknown;
         readonly message?: string;
         readonly errorDetails?: Readonly<Record<string, unknown>>;
+        readonly errorCode?: NetworkCode;
     });
 }
 /** Request exceeded the configured timeout. Specialised transport failure. */
@@ -106,11 +111,14 @@ export declare class NetworkUnknownException extends UseSmileIDNetworkException
  *   server).
  * - `AxiosError` with `response` → [NetworkServerException] carrying
  *   the wire status code; status routing via [statusToErrorCode]
- *   covers 401/403/404/429/5xx + a generic fallback.
+ *   covers 401/403/404/408/429/5xx + a generic fallback. A 408 keeps this
+ *   type, with its `statusCode`, and carries `NETWORK_TIMEOUT`.
  * - Already-typed [UseSmileIDNetworkException] → pass-through so the
  *   mapper is safe to call idempotently across retry / wrap paths.
  * - Anything else → [NetworkUnknownException] with the underlying
  *   value preserved as `cause` for triage.
  */
 export declare function mapAxiosError(error: unknown): UseSmileIDNetworkException;
+/** axios's code for a request aborted through a signal or cancel token. */
+export declare const CANCELED = "ERR_CANCELED";
 export {};

package/dist/core/exception/use_smile_id_network_exception.js

@@ -1 +1 @@
-"use strict";import{isAxiosError as i}from"axios";import{UseSmileIDErrorCode as o}from"./use_smile_id_error_code";import{UseSmileIDException as a}from"./use_smile_id_exception";export class UseSmileIDNetworkException extends a{}export class NetworkServerException extends UseSmileIDNetworkException{errorCode;statusCode;constructor({statusCode:t,cause:s,message:r,errorDetails:n}){super({message:r??`HTTP ${t}`,suggestedFix:"Inspect the server response body and retry if the failure is transient.",cause:s,errorDetails:n}),this.statusCode=t,this.errorCode=c(t)}}export class NetworkTransportException extends UseSmileIDNetworkException{errorCode=o.Network.ConnectionFailed;constructor({cause:t,message:s="Network transport failure.",errorDetails:r}={}){super({message:s,suggestedFix:"Check the device's network connection and verify the configured base URL is reachable.",cause:t,errorDetails:r})}}export class NetworkTimeoutException extends UseSmileIDNetworkException{errorCode=o.Network.Timeout;constructor({cause:t,message:s="The request timed out.",errorDetails:r}={}){super({message:s,suggestedFix:"Increase the timeout via `n.timeouts(...)` if appropriate, or retry once connectivity recovers.",cause:t,errorDetails:r})}}export class NetworkResponseParseException extends UseSmileIDNetworkException{errorCode=o.Network.ResponseParseError;constructor({cause:t,message:s="Failed to parse response body.",errorDetails:r}={}){super({message:s,suggestedFix:"Confirm the SDK version matches the backend's response schema.",cause:t,errorDetails:r})}}export class NetworkRequestBuildException extends UseSmileIDNetworkException{errorCode=o.Network.RequestFailed;constructor({cause:t,message:s="Failed to build request.",errorDetails:r}={}){super({message:s,suggestedFix:"Verify the request payload satisfies the multipart / URL contract before submission.",cause:t,errorDetails:r})}}export class NetworkUnknownException extends UseSmileIDNetworkException{errorCode=o.Network.RequestFailed;constructor({cause:t,message:s="Unknown network error.",errorDetails:r}={}){super({message:s,suggestedFix:"Log the wrapped `cause` for triage \u2014 anything reaching this branch represents a gap in error mapping.",cause:t,errorDetails:r})}}function c(e){return e===401?o.Network.Unauthorized:e===403?o.Network.Forbidden:e===404?o.Network.NotFound:e===429?o.Network.RateLimit:e>=500&&e<600?o.Network.ServerError:o.Network.RequestFailed}export function mapAxiosError(e){return e instanceof UseSmileIDNetworkException?e:i(e)?u(e):e instanceof Error?new NetworkUnknownException({message:e.message,cause:e}):new NetworkUnknownException({message:String(e),cause:e})}function u(e){if(e.code==="ERR_BAD_OPTION"||e.code==="ERR_BAD_OPTION_VALUE"||e.code==="ERR_INVALID_URL")return new NetworkRequestBuildException({message:e.message,cause:e});if(e.code==="ECONNABORTED")return new NetworkTimeoutException({message:e.message,cause:e});if(!e.response)return new NetworkTransportException({message:e.message,cause:e});const t=e.response.status,s=e.response.data;return new NetworkServerException({statusCode:t,message:s?.message??`HTTP ${t}: ${e.message}`,cause:e})}
+"use strict";import{isAxiosError as a}from"axios";import{UseSmileIDErrorCode as r}from"./use_smile_id_error_code";import{UseSmileIDException as c}from"./use_smile_id_exception";export class UseSmileIDNetworkException extends c{}export class NetworkServerException extends UseSmileIDNetworkException{errorCode;statusCode;constructor({statusCode:t,cause:s,message:o,errorDetails:n,errorCode:i}){super({message:o??`HTTP ${t}`,suggestedFix:"Inspect the server response body and retry if the failure is transient.",cause:s,errorDetails:n}),this.statusCode=t,this.errorCode=i??u(t)}}export class NetworkTransportException extends UseSmileIDNetworkException{errorCode;constructor({cause:t,message:s="Network transport failure.",errorDetails:o,errorCode:n=r.Network.ConnectionFailed}={}){super({message:s,suggestedFix:"Check the device's network connection and verify the configured base URL is reachable.",cause:t,errorDetails:o}),this.errorCode=n}}export class NetworkTimeoutException extends UseSmileIDNetworkException{errorCode=r.Network.Timeout;constructor({cause:t,message:s="The request timed out.",errorDetails:o}={}){super({message:s,suggestedFix:"Increase the timeout via `n.timeouts(...)` if appropriate, or retry once connectivity recovers.",cause:t,errorDetails:o})}}export class NetworkResponseParseException extends UseSmileIDNetworkException{errorCode=r.Network.ResponseParseError;constructor({cause:t,message:s="Failed to parse response body.",errorDetails:o}={}){super({message:s,suggestedFix:"Confirm the SDK version matches the backend's response schema.",cause:t,errorDetails:o})}}export class NetworkRequestBuildException extends UseSmileIDNetworkException{errorCode=r.Network.RequestFailed;constructor({cause:t,message:s="Failed to build request.",errorDetails:o}={}){super({message:s,suggestedFix:"Verify the request payload satisfies the multipart / URL contract before submission.",cause:t,errorDetails:o})}}export class NetworkUnknownException extends UseSmileIDNetworkException{errorCode=r.Network.RequestFailed;constructor({cause:t,message:s="Unknown network error.",errorDetails:o}={}){super({message:s,suggestedFix:"Log the wrapped `cause` for triage \u2014 anything reaching this branch represents a gap in error mapping.",cause:t,errorDetails:o})}}function u(e){return e===401?r.Network.Unauthorized:e===403?r.Network.Forbidden:e===404?r.Network.NotFound:e===408?r.Network.Timeout:e===429?r.Network.RateLimit:e>=500&&e<600?r.Network.ServerError:r.Network.RequestFailed}export function mapAxiosError(e){return e instanceof UseSmileIDNetworkException?e:a(e)?d(e):e instanceof Error?new NetworkUnknownException({message:e.message,cause:e}):new NetworkUnknownException({message:String(e),cause:e})}function d(e){if(e.code==="ERR_BAD_OPTION"||e.code==="ERR_BAD_OPTION_VALUE"||e.code==="ERR_INVALID_URL")return new NetworkRequestBuildException({message:e.message,cause:e});if(e.code===CANCELED)return new NetworkTransportException({message:e.message,cause:e,errorCode:r.Network.RequestFailed});if(e.code==="ECONNABORTED")return new NetworkTimeoutException({message:e.message,cause:e});if(!e.response)return new NetworkTransportException({message:e.message,cause:e});const t=e.response.status,s=e.response.data;return new NetworkServerException({statusCode:t,message:s?.message??`HTTP ${t}: ${e.message}`,cause:e,...s?.message?.trim()===p?{errorCode:r.Network.CallbackUrlRequired}:{}})}export const CANCELED="ERR_CANCELED";const p="A valid callback_url is required in the request or a default callback URL must be configured in the portal.";

package/dist/core/is_development_build.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Whether this is a development build. `__DEV__` is bundler-injected and
+ * absent outside Metro-like environments, where a bare reference throws
+ * rather than reading falsy. @internal
+ */
+export declare function isDevelopmentBuild(): boolean;

package/dist/core/is_development_build.js

@@ -0,0 +1 @@
+"use strict";export function isDevelopmentBuild(){return typeof __DEV__<"u"&&__DEV__}

package/dist/core/models/config.d.ts

@@ -33,6 +33,12 @@ export type ConfigOptions = {
      * `docs/Architecture.md § Rollout`.
      */
     readonly allowOfflineMode: boolean;
+    /**
+     * Hand the captured job back through `onResult` as `{ status: "captured" }`
+     * instead of submitting it. The captured files are kept on disk for you to
+     * forward and delete. Absent reads as `false`.
+     */
+    readonly skipApiSubmission?: boolean;
     /**
      * Journey-wide "Powered by Smile ID" branding; document capture never shows
      * it. Defaults to `true`.

package/dist/core/models/document_type.d.ts

@@ -35,7 +35,7 @@ export declare const DocumentType: {
     readonly SouthAfricaGreenBook: {
         readonly kind: "southAfricaGreenBook";
     } & DocumentTypeFields;
-    /** Passport — landscape data page followed by a back-side capture. */
+    /** Passport — landscape data page. */
     readonly Passport: {
         readonly kind: "passport";
     } & DocumentTypeFields;