@smileid/usesmileid 12.2.0 → 12.3.0

package/CHANGELOG.md

@@ -1,10 +1,14 @@
 Full release notes: [Smile ID docs](https://docs.usesmileid.com/developer-resources/sdks/mobile/release-notes/react-native-expo).
 
+## 12.3.0
+
+See the repository CHANGELOG for the 12.3.0 release notes.
+
+
 ## 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.

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.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.
+`12.3.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
 
@@ -53,7 +53,7 @@ npx expo install expo-brightness expo-file-system expo-font expo-haptics \
                  expo-image-manipulator expo-image-picker expo-keep-awake expo-screen-orientation
 ```
 
-(Use `@smileid/usesmileid_huawei_{face,document}` instead of mlkit on no-GMS Android targets.)
+(For Android phones without Google Play services, use `@smileid/usesmileid_huawei_{face,document}` instead of the ML Kit packages in the build you ship to those phones, such as your AppGallery build. Your Google Play build keeps ML Kit.)
 
 Everything above except the `@smileid/*` packages is a **required peer dependency**, and must be installed in your app directly: React Native autolinking only links native modules declared in the app's own `package.json`, not a library's transitive ones. `expo`, `expo-modules-core`, `react` and `react-native` are omitted because they ship with your app.
 
@@ -124,11 +124,17 @@ export default function VerificationScreen() {
         b.onResult = (result) => {
           switch (result.status) {
             case "success":
-              console.log("Captured:", result.value);
+              console.log("Submitted job", result.value.jobId);
               break;
             case "failure":
               console.error("Error:", result.error);
               break;
+            case "cancelled":
+              console.log("The user left the flow");
+              break;
+            case "captured":
+              console.log("Captured", result.job.jobType);
+              break;
           }
         };
       }}
@@ -153,6 +159,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 +169,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 |
 
@@ -268,7 +276,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
@@ -444,13 +452,13 @@ function ExitButton() {
 
 The hook returns the active `FlowNavigationManager`:
 
-| Member              | Behaviour                                                                                                                   |
-| ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `navigateToNext()`  | Advance to the next screen. From the last step, calls `onResult({ status: 'success', ... })`.                               |
-| `navigateBack()`    | Pop the active screen. From the first step, calls `onResult({ status: 'failure', error: ... })` with `cancelled` semantics. |
-| `navigateToStart()` | Reset the path to the first screen — a flow restart after a terminal failure.                                               |
-| `exit(reason?)`     | Exit immediately — useful for "abort" buttons. Defaults to `cancelled`.                                                     |
-| `captured`          | Snapshot of artifacts collected so far (`selfiePath`, `livenessPaths`, `frontDocumentPath`, etc).                           |
+| Member              | Behaviour                                                                                         |
+| ------------------- | ------------------------------------------------------------------------------------------------- |
+| `navigateToNext()`  | Advance to the next screen. From the last step, calls `onResult({ status: 'success', ... })`.     |
+| `navigateBack()`    | Pop the active screen. From the first step, calls `onResult({ status: 'cancelled' })`.            |
+| `navigateToStart()` | Reset the path to the first screen — a flow restart after a terminal failure.                     |
+| `exit(reason?)`     | Exit immediately — useful for "abort" buttons. Defaults to `cancelled`.                           |
+| `captured`          | Snapshot of artifacts collected so far (`selfiePath`, `livenessPaths`, `frontDocumentPath`, etc). |
 
 Calling `useFlowNavigation()` outside `<UseSmileIDBuilder>` throws — the misuse is loud at first render rather than silently no-op-ing.
 
@@ -458,16 +466,16 @@ 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                                                    |
 
 ---
 
 ## Job-specific parameters
 
-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.
+Each job type that needs identity fields reads them from a top-level builder property. The shared `user_details` part (`b.userDetails`) is optional: the SDK checks none of its fields, and the API reports any a job needs. `country` is the ISO 3166-1 alpha-2 code.
 
 | Job type                                | Builder property                        | Required fields                 | Notes                                                                                                                                                                                                                     |
 | --------------------------------------- | --------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -505,7 +513,7 @@ b.userDetails = {
 
 `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.
+Pre-flight any payload with `b.validateDocumentVerificationParams(...)` or `b.validateEnhancedDocumentVerificationParams(...)` before assigning.
 
 ---
 
@@ -522,13 +530,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 before its access token expires: `headers` carries the token from the capture, and the server rejects the job once that token has expired.
+
+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
 

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/camera_defaults.d.ts

@@ -16,8 +16,6 @@ export declare const CameraDefaults: {
         readonly width: 1280;
         readonly height: 720;
     };
-    /** How long a streaming capture waits for its first analyzed frame before reporting the camera unavailable. */
-    readonly firstFrameTimeoutMs: 10000;
     /** Longest-edge ceiling (px) for an imported document image; downscale-only. */
     readonly documentMaxDimension: 1600;
     /** JPEG quality (0–1) for imported document images. */

package/dist/camera/camera_defaults.js

@@ -1 +1 @@
-"use strict";export const CameraDefaults={focusRunningDurationMs:600,focusSettledDurationMs:500,analysisTargetFps:30,analysisTargetResolution:{width:640,height:480},documentAnalysisResolution:{width:1280,height:720},firstFrameTimeoutMs:1e4,documentMaxDimension:1600,documentJpegQuality:.85,minGalleryDocumentDimensionPx:600,selfieJpegTargetWidth:480,selfieJpegTargetHeight:640};
+"use strict";export const CameraDefaults={focusRunningDurationMs:600,focusSettledDurationMs:500,analysisTargetFps:30,analysisTargetResolution:{width:640,height:480},documentAnalysisResolution:{width:1280,height:720},documentMaxDimension:1600,documentJpegQuality:.85,minGalleryDocumentDimensionPx:600,selfieJpegTargetWidth:480,selfieJpegTargetHeight:640};

package/dist/camera/document_image_pipeline.d.ts

@@ -1,5 +1,14 @@
 import { DocumentSide } from "@smileid/usesmileid_bridge";
 export { computeDocumentResizeTarget } from "./document_resize_target";
+/**
+ * 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). */

package/dist/camera/document_image_pipeline.js

@@ -1 +1 @@
-"use strict";import{Directory as m,File as i,Paths as s}from"expo-file-system";import{ImageManipulator as u,SaveFormat as d}from"expo-image-manipulator";import{DocumentSide as o,UseSmileIDCrashReporting as p}from"@smileid/usesmileid_bridge";import{CameraDefaults as a}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){switch(e){case o.Back:return"document_back.jpg";case o.Visa:return"document_visa.jpg";default:return"document_front.jpg"}}export async function resampleImportedDocument(e,n){const t=e.width!==void 0&&e.height!==void 0?f(e.width,e.height,a.documentMaxDimension):null,r=u.manipulate(e.uri);t&&r.resize(t);const c=await(await r.renderAsync()).saveAsync({compress:a.documentJpegQuality,format:d.JPEG});return g(c.uri,n)}function g(e,n){try{const t=new m(s.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 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{isDevBuild as R}from"../debug/use_smile_id_debug";import{UseSmileIDDebugTap as d}from"../debug/use_smile_id_debug_tap";export function useSmileIDFrameStream(e,r,u){const i=a(e),s=a(r),o=a(u?.onError),c=a(!1),f=a(!0);l(()=>{i.current=e},[e]),l(()=>{s.current=r},[r]),l(()=>{o.current=u?.onError},[u?.onError]),l(()=>(f.current=!0,()=>{f.current=!1}),[]);const n=y(t=>{const m=o.current;dispatchFrameResult({raw:t,analyzer:i.current,isBusy:()=>c.current,setBusy:p=>{c.current=p},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:u,isBusy:i,setBusy:s,isMounted:o,onResult:c,onError:f}=e;if(u&&!i()){s(!0);try{const n=D(r);if(n!==null){if(_.has(n))return;throw new B({reason:n})}if(u.kind==="face"){const t=h.parse(r);if(!o())return;c(t),R()&&d.analyzedFace(t.output)}else{const t=S.parse(r);if(!o())return;c(t),R()&&d.analyzedDocument(t.output)}}catch(n){if(!o())return;f?.(n)}finally{s(!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.
@@ -51,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>;
     /**
@@ -58,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{AspectRatio as _,KameraSession as h}from"@smileid/kamera";import{CaptureType as r}from"../core/models/ml_config";import{CameraDefaults as c}from"./camera_defaults";import{CameraLens as o}from"./camera_lens";import{FocusStates as i}from"./focus_state";import{KameraConfigFactory as u}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=o.front,t=()=>new h){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??r.selfie;return u.create(e,this._state.currentLens).preview.aspectRatio===_.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(n=>this._onKameraEvent(n)),s=this._config.captureType??r.selfie,a=this._config.lens??(s===r.document?o.back:o.front);try{await e.start(u.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/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",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.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

@@ -42,13 +42,17 @@ export declare class NetworkServerException extends UseSmileIDNetworkException {
         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. */
@@ -107,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 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=r.Network.ConnectionFailed;constructor({cause:t,message:s="Network transport failure.",errorDetails:o}={}){super({message:s,suggestedFix:"Check the device's network connection and verify the configured base URL is reachable.",cause:t,errorDetails:o})}}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===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==="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}:{}})}const p="A valid callback_url is required in the request or a default callback URL must be configured in the portal.";
+"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/ml_config.d.ts

@@ -29,7 +29,7 @@ export type AnalyzerRegistry = {
     readonly selfie?: FaceAnalyzer;
     /**
      * Wire-shape `FaceConfig` built from the DSL scope (analyzer key,
-     * ScanPerformanceProfile, FaceDetectorConfig). Falls back to native
+     * FaceDetectorConfig). Falls back to native
      * platform defaults when omitted.
      */
     readonly selfieConfig?: FaceConfig;

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

@@ -24,7 +24,10 @@ export declare enum LogLevel {
     basic = "basic",
     /** `basic` + request/response headers (pre-redaction applied). */
     headers = "headers",
-    /** `headers` + request/response bodies. Verbose — partner-debug only. */
+    /**
+     * `headers` + request/response bodies, in a development build (`__DEV__`) only. A job's body
+     * carries the images, consent and device metadata, so any other build logs `headers`.
+     */
     body = "body"
 }
 export type NetworkLoggingConfig = {

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

@@ -16,17 +16,19 @@ export type ConsentInformation = {
 };
 /**
  * Subject's personal details, sent as the `user_details` JSON part.
- * Requires non-blank `givenNames` and `lastName`, plus at least one of
- * `email` or `phoneNumber`.
+ * The SDK checks none of these fields: it submits them as given, empty
+ * included, and the API rejects a job that lacks one it needs, naming the
+ * field. Which fields a job needs is the API's call, per partner and
+ * product: `GET /v3/services/config` lists them.
  */
 export type UserDetails = {
-    /** Subject's given / first names. Required, non-blank. */
+    /** Subject's given / first names. */
     readonly givenNames: string;
-    /** Subject's family / last name. Required, non-blank. */
+    /** Subject's family / last name. */
     readonly lastName: string;
-    /** Optional email address. */
+    /** Email address. */
     readonly email?: string;
-    /** Optional phone number in international format (leading `+`). */
+    /** Phone number in international format (leading `+`). */
     readonly phoneNumber?: string;
 };
 /**

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

@@ -1,3 +1,4 @@
+import type { CapturedJob } from "../../data/model/captured_job";
 /**
  * The outcome of an SDK operation: success with a value, failure with an
  * error, or cancellation when the user exits the flow. Surfaced to
@@ -16,6 +17,15 @@ export type UseSmileIDResult<T> = {
     readonly error: unknown;
 } | {
     readonly status: "cancelled";
+}
+/**
+ * The flow captured everything the job needs and stopped short of
+ * submitting it, because `c.skipApiSubmission = true`. `job` holds the
+ * files and metadata to forward.
+ */
+ | {
+    readonly status: "captured";
+    readonly job: CapturedJob;
 };
 /** A successful outcome carrying the resulting value. */
 export declare function success<T>(value: T): UseSmileIDResult<T>;
@@ -27,3 +37,4 @@ export declare function failure<T>(error: unknown): UseSmileIDResult<T>;
  * so cancellation can be handled separately.
  */
 export declare function cancelled<T>(): UseSmileIDResult<T>;
+export declare function captured<T>(job: CapturedJob): UseSmileIDResult<T>;

package/dist/core/models/result.js

@@ -1 +1 @@
-"use strict";export function success(t){return{status:"success",value:t}}export function failure(t){return{status:"failure",error:t}}export function cancelled(){return{status:"cancelled"}}
+"use strict";export function success(t){return{status:"success",value:t}}export function failure(t){return{status:"failure",error:t}}export function cancelled(){return{status:"cancelled"}}export function captured(t){return{status:"captured",job:t}}