@sekyro/web 0.1.0-rc.5 → 0.1.0-rc.7

package/dist/{hosted-client-DWzCRYJK.d.ts → hosted-client-kBeq-mnJ.d.cts}

@@ -6,10 +6,26 @@ type SessionOutcome = "approved" | "review" | "rejected";
 type CheckState = "pending" | "input_required" | "processing" | "passed" | "failed" | "review" | "skipped";
 /** The frozen check-type vocabulary (CHECK_TYPES). `phone_otp` joined in Task 13. */
 type CheckType = "liveness" | "face_match" | "doc_ocr" | "population_registry" | "phone_otp";
-type LivenessReason = "no_face" | "media_unreadable" | "clip_too_short" | "spoof_detected" | "review_band";
-type PopulationReason = "nni_not_found" | "nni_invalid" | "registry_unavailable" | "result_from_cache";
-type FaceMatchReason = "no_face_source" | "no_face_reference" | "low_quality_reference" | "below_threshold" | "review_band";
-type DocReason = "side_missing" | "mrz_checksum_failed" | "unreadable" | "expired_document" | "authenticity_review" | "registry_mismatch";
+type LivenessReason = "no_face" | "media_unreadable" | "clip_too_short" | "spoof_detected" | "review_band" | "liveness_inconclusive" | "mobile_required" | "uncalibrated_capture_channel";
+type PopulationReason = "nni_not_found" | "nni_invalid" | "registry_unavailable" | "result_from_cache" | "nationality_not_allowed" | "underage" | "age_unverifiable" | "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch";
+type FaceMatchReason = "no_face_source" | "no_face_reference" | "low_quality_reference" | "below_threshold" | "review_band" | "match_inconclusive";
+type DocReason = "side_missing" | "mrz_checksum_failed" | "unreadable" | "expired_document" | "authenticity_review" | "document_authenticity" | "registry_mismatch" | "document_nni_mismatch" | "document_type_not_accepted" | "nationality_not_allowed" | "underage" | "age_unverifiable" | "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch" | "document_number_mismatch";
+/**
+ * Profile v2 step 3 matching reasons: a field the partner sent at session
+ * create (`subject`) differs from the reference identity (document or
+ * registry). All four are final. `document_number_mismatch` is `doc_ocr` only.
+ */
+type MatchReason = "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch" | "document_number_mismatch";
+/**
+ * Profile v2 step 4 decision-mode reasons (the app decides automatically
+ * instead of sending the case to human review). These park the step at
+ * `input_required` while attempts remain: `liveness_inconclusive` /
+ * `match_inconclusive` (middle score band) and `document_authenticity`
+ * (retake the original card). `mobile_required` is kept for compatibility:
+ * the backend now answers a non-phone capture with a request-level
+ * `409 mobile_required` (continue on a phone; nothing used, not billed).
+ */
+type DecisionReason = "liveness_inconclusive" | "match_inconclusive" | "document_authenticity" | "mobile_required";
 /**
  * phone_otp reasons (Task 13). All transient — the caller fixes them by
  * re-entering / resending: `otp_mismatch` (wrong or missing code),
@@ -23,6 +39,49 @@ type PhoneOtpReason = "otp_mismatch" | "otp_expired" | "otp_send_failed";
  * and face_match both carry `review_band`.
  */
 type CheckReason = LivenessReason | PopulationReason | FaceMatchReason | DocReason | PhoneOtpReason;
+/**
+ * Session-level failure reasons: the session was stopped by a policy gate,
+ * not by a failed check. All are terminal (no retry on this session):
+ *  - `location_not_allowed` / `anonymizer_blocked` (profile v2 step 2): the
+ *    person's IP location is not allowed, or an anonymizer (VPN / proxy / Tor)
+ *    was detected while the app blocks them;
+ *  - `capture_tampered` (step 4): the device reported a tampered capture
+ *    (virtual camera, hooking, emulator…) while the app blocks it;
+ *  - `device_velocity_exceeded` (step 4): this device already verified too
+ *    many different people while the app blocks it;
+ *  - `device_cooldown` (step 4): this device had too many rejected sessions —
+ *    {@link HostedSessionView.retryAfter} says when it may try again.
+ */
+type SessionFailureReason = "location_not_allowed" | "anonymizer_blocked" | "capture_tampered" | "device_velocity_exceeded" | "device_cooldown";
+/**
+ * The profile-v2 policy reasons a session can end on: the two session-level
+ * reasons plus the failed check's policy reasons (`document_type_not_accepted`,
+ * `nationality_not_allowed`, `underage`, `age_unverifiable`,
+ * `document_nni_mismatch`).
+ */
+type PolicyFailureReason = SessionFailureReason | "document_type_not_accepted" | "nationality_not_allowed" | "underage" | "age_unverifiable" | "document_nni_mismatch";
+/**
+ * How the person proves their identity when the app makes the document
+ * optional for registry nationals (profile v2 step 3): type their national
+ * number (NNI) and skip the document, or photograph their document.
+ */
+type IdentityMethod = "national_number" | "document_photo";
+/**
+ * The identity-method choice of a session (`HostedSessionView.methodChoice`).
+ * While `available && selected === null` no check can be submitted (409
+ * `method_required`): the page asks first and sends the answer with
+ * `POST /hosted/method` ({@link HostedClient.selectMethod}).
+ */
+interface MethodChoiceView {
+    /** The session offers the choice (the app's document mode is `optional`). */
+    available: boolean;
+    /** The chosen method, or `null` while the person has not chosen. */
+    selected: IdentityMethod | null;
+    /** The methods to offer, in display order. */
+    options: IdentityMethod[];
+}
+/** A document type the backend reads today (kyc-docs-v2 vocabulary). */
+type AcceptedDocumentType = "carte_identite" | "passport";
 /**
  * phone_otp DISPLAY-SAFE surface (Task 16). The backend stashes the OTP
  * service `verifToken` on the check's persisted outputs (the doc_ocr partial
@@ -66,6 +125,67 @@ interface HostedStepView {
     acceptedSides?: ("recto" | "verso")[];
     /** phone_otp only: the display-safe OTP send/config surface (never the verifToken). */
     otp?: HostedOtpView;
+    /**
+     * The check failed after using all of its attempts — no retry is left.
+     * Absent on older APIs (treat absent as `false`).
+     */
+    attemptsExhausted?: boolean;
+    /**
+     * population_registry only: the session is not bound to an NNI, but the
+     * document step already read a valid one — the page submits the registry
+     * check with an EMPTY input (no NNI field) and the backend uses the
+     * document's number. Absent on older APIs.
+     */
+    nniFromDocument?: boolean;
+    /**
+     * liveness / face_match (profile v2 step 4, decision mode `automatic`): the
+     * capture must come from a phone — the liveness band is calibrated on
+     * mobile captures only. A desktop page hands the person off to their phone
+     * instead of capturing (a desktop submission answers `mobile_required`).
+     * Absent on older APIs and in `review` mode.
+     */
+    requiresMobile?: boolean;
+}
+/** A locale the Sekyro AI-hosted voice clips are recorded in. */
+type HostedVoiceLocale = "ar" | "fr" | "en";
+/**
+ * The session's Sekyro AI-hosted voice-guidance clips (the active clip set).
+ *
+ * `clips[locale]` maps a voice key (`fcv3.*`, the `@sekyro/react` voice-key
+ * namespace) to an ABSOLUTE URL on the Sekyro AI assets host
+ * (`https://assets.sekyro.ai/voice/<setId>/<locale>/<name>.mp3`; staging:
+ * `assets-staging.sekyro.ai`). URLs are immutable per `setId`. A locale or key
+ * may be missing — the player falls back to the device voice for it.
+ *
+ * A page with a Content-Security-Policy must allow the assets origin in
+ * `media-src` for the clips to play (see the partner web-SDK guide, CSP note).
+ */
+interface HostedVoiceView {
+    /** Identifier of the active clip set (part of every clip URL). */
+    setId: string;
+    /** Per-locale map of voice key (`fcv3.*`) → absolute clip URL. */
+    clips: {
+        readonly [L in HostedVoiceLocale]?: Readonly<Record<string, string>>;
+    };
+}
+/** A branding colour key (each value is `#rrggbb`). */
+type HostedBrandingColorKey = "brand" | "brandFg" | "bg" | "surface" | "fg" | "fgMuted" | "danger" | "success" | "warning";
+/**
+ * The org / app branding of a session (`HostedSessionView.branding`): only the
+ * fields set in the dashboard, merged per field (app over org). A field the
+ * org and app left unset is ABSENT — keep your default for it; the whole
+ * object is absent when nothing is set. `logoUrl` is a short-lived signed URL
+ * (15 minutes).
+ */
+interface HostedBranding {
+    /** Signed URL of the logo (PNG or sanitized SVG); absent when none is set. */
+    logoUrl?: string;
+    /** Colours as `#rrggbb`. */
+    colors?: Partial<Record<HostedBrandingColorKey, string>>;
+    /** Corner radius step. */
+    radius?: "none" | "sm" | "md" | "lg" | "full";
+    /** Font choice (system fallbacks when the font is not installed). */
+    fontFamily?: "system" | "inter" | "ibm-plex-sans-arabic" | "noto-sans-arabic" | "roboto";
 }
 /**
  * Token-addressed hosted-page bootstrap (`GET /hosted/session`). A separate
@@ -110,6 +230,41 @@ interface HostedSessionView {
      * valid (additive field, always on the wire from Task 8 onward).
      */
     nniBound?: boolean;
+    /**
+     * The Sekyro AI-hosted voice-guidance clips of this session, or `null` when no
+     * clip set is active (the device voice is used). Optional: older APIs omit
+     * the field — treat absent like `null`.
+     */
+    voice?: HostedVoiceView | null;
+    /**
+     * Why the session ended, when a profile-v2 policy stopped it: a
+     * {@link SessionFailureReason}, or the failed check's reason when it is a
+     * policy reason (eligibility, or `document_nni_mismatch`). Absent otherwise
+     * (and on older APIs).
+     */
+    failureReason?: PolicyFailureReason;
+    /**
+     * The document types the person may pick (resolved for issuer `MR`). Absent
+     * on older APIs — treat absent as every type (`carte_identite`, `passport`).
+     */
+    acceptedDocumentTypes?: AcceptedDocumentType[];
+    /**
+     * The identity-method choice (profile v2 step 3). Absent when the session
+     * has no choice (and on older APIs). While `available && selected === null`
+     * every check submission answers 409 `method_required`.
+     */
+    methodChoice?: MethodChoiceView;
+    /**
+     * ISO-8601 time from which this device may verify again — set with
+     * `failureReason: 'device_cooldown'` (profile v2 step 4). Absent otherwise
+     * (and on older APIs).
+     */
+    retryAfter?: string;
+    /**
+     * The org / app branding (settings spec §5.1). Absent on older APIs — keep
+     * the default theme. Map it with `brandingToTheme()` from `@sekyro/react`.
+     */
+    branding?: HostedBranding;
 }
 /** `POST /hosted/consent` result — 201 on first record, 200 `{alreadyRecorded: true}` on replay. */
 interface RecordConsentResult {
@@ -123,6 +278,8 @@ interface SessionStepView {
     state: CheckState;
     reason?: CheckReason;
     calibratedScore?: number;
+    /** The check failed after using all of its attempts. Absent on older APIs. */
+    attemptsExhausted?: boolean;
 }
 /**
  * Client-facing session projection returned by
@@ -132,6 +289,8 @@ interface SessionView {
     id: string;
     status: SessionStatus;
     outcome: SessionOutcome | null;
+    /** Profile-v2 policy stop reason; absent on ordinary failures and older APIs. */
+    failureReason?: PolicyFailureReason;
     steps: SessionStepView[];
     /** ISO-8601 timestamp (Date on the server, string on the wire). */
     expiresAt: string;
@@ -181,7 +340,14 @@ interface AttestationInput {
     /** The Turnstile site key the token was minted with (selects the verifying secret). */
     siteKey?: string;
 }
-/** liveness executor input: a promoted `clips/…` key + optional attestation. */
+/**
+ * liveness executor input: a promoted `clips/…` key + optional attestation.
+ * `faceMatch` (v2 latency §3.2) carries the already-promoted `doc-images/…`
+ * keyframe so the backend can run face_match IN THE SAME submission when its
+ * bundle flag is on and `face_match` is the next pending step. Backends that
+ * do not bundle ignore it (the input bag is an open record) — the SDK then
+ * submits `face_match` itself with the same key (see liveness-flow.ts).
+ */
 interface LivenessInput {
     clipKey: string;
     attestation?: AttestationInput;
@@ -193,6 +359,10 @@ interface LivenessInput {
     /** Capture metadata (engine, dimensions, clip length, face-capture timing)
      *  — the backend's allowlisted, non-PII `capture` block (session insights). */
     capture?: LivenessCaptureInput;
+    /** The promoted face_match probe key, for a bundled liveness + face_match run. */
+    faceMatch?: {
+        imageKey: string;
+    };
 }
 /** `LivenessInput.capture`: what the SDK's `captured` event measured. All ms are whole, ≥ 0. */
 interface LivenessCaptureInput {
@@ -213,7 +383,10 @@ interface LivenessCaptureInput {
 interface PopulationInput {
     nni?: string;
 }
-/** face_match executor input: a promoted `doc-images/…` key (the source selfie frame). */
+/**
+ * face_match executor input: a promoted `doc-images/…` key (the source selfie frame).
+ * The same key may already have ridden along as {@link LivenessInput.faceMatch}.
+ */
 interface FaceMatchInput {
     imageKey: string;
 }
@@ -320,6 +493,7 @@ interface HostedClientOptions {
  *
  *   GET  /api/v2/hosted/session                     → {@link getSession}
  *   POST /api/v2/hosted/consent                     → {@link recordConsent}
+ *   POST /api/v2/hosted/method                      → {@link selectMethod}
  *   POST /api/v2/sessions/:id/media                 → {@link presign}
  *   POST /api/v2/sessions/:id/media/complete        → {@link completeMedia}
  *   POST /api/v2/sessions/:id/checks/:checkType     → {@link submitCheck}
@@ -358,6 +532,13 @@ declare class HostedClient {
      * submission answer 409 `consent_required`.
      */
     recordConsent(locale: ConsentLocale): Promise<RecordConsentResult>;
+    /**
+     * Send the person's identity method (profile v2 step 3) when the view offers
+     * a choice (`methodChoice.available`). Returns the updated hosted view —
+     * continue from it. 409 `method_locked` when the method can no longer
+     * change (a check of the chosen method was already submitted).
+     */
+    selectMethod(method: IdentityMethod): Promise<HostedSessionView>;
     /**
      * Presign a Spaces PUT for a new pending object. `contentType` is stripped of
      * MIME parameters defensively (the allowlist holds bare types; the engine's
@@ -418,4 +599,4 @@ declare class HostedClient {
     private api;
 }
 
-export { type AttestationInput as A, type CheckReason as C, type DocReason as D, type FaceMatchReason as F, type HostedOtpView as H, type LivenessReason as L, type MediaCheckType as M, type PhoneOtpReason as P, type RecordConsentResult as R, type SessionOutcome as S, type UploadMedia as U, type CheckState as a, type CheckType as b, type HostedSessionView as c, type HostedStepView as d, type PopulationReason as e, type SessionStatus as f, HostedClient as g, type SessionView as h, type CheckInputByType as i, type CompleteMediaResult as j, type ConsentLocale as k, type DocOcrInput as l, type DocSide as m, type FaceMatchInput as n, type HostedClientOptions as o, type LivenessCaptureInput as p, type LivenessInput as q, type MediaKind as r, type PhoneOtpInput as s, type PopulationInput as t, type PresignRequest as u, type PresignUploadResult as v, type SessionStepView as w, type SubmitCheckBody as x, type SubmitOptions as y, stripMimeParams as z };
+export { type AcceptedDocumentType as A, type MediaCheckType as B, type CheckReason as C, type DecisionReason as D, type MediaKind as E, type FaceMatchReason as F, type PhoneOtpInput as G, type HostedBranding as H, type IdentityMethod as I, type PopulationInput as J, type PresignRequest as K, type LivenessReason as L, type MatchReason as M, type PresignUploadResult as N, type SessionStepView as O, type PhoneOtpReason as P, type SubmitCheckBody as Q, type RecordConsentResult as R, type SessionFailureReason as S, type SubmitOptions as T, type UploadMedia as U, stripMimeParams as V, type CheckState as a, type CheckType as b, type DocReason as c, type HostedBrandingColorKey as d, type HostedOtpView as e, type HostedSessionView as f, type HostedStepView as g, type HostedVoiceLocale as h, type HostedVoiceView as i, type MethodChoiceView as j, type PolicyFailureReason as k, type PopulationReason as l, type SessionOutcome as m, type SessionStatus as n, HostedClient as o, type AttestationInput as p, type SessionView as q, type CheckInputByType as r, type CompleteMediaResult as s, type ConsentLocale as t, type DocOcrInput as u, type DocSide as v, type FaceMatchInput as w, type HostedClientOptions as x, type LivenessCaptureInput as y, type LivenessInput as z };

package/dist/{hosted-client-DWzCRYJK.d.cts → hosted-client-kBeq-mnJ.d.ts}

@@ -6,10 +6,26 @@ type SessionOutcome = "approved" | "review" | "rejected";
 type CheckState = "pending" | "input_required" | "processing" | "passed" | "failed" | "review" | "skipped";
 /** The frozen check-type vocabulary (CHECK_TYPES). `phone_otp` joined in Task 13. */
 type CheckType = "liveness" | "face_match" | "doc_ocr" | "population_registry" | "phone_otp";
-type LivenessReason = "no_face" | "media_unreadable" | "clip_too_short" | "spoof_detected" | "review_band";
-type PopulationReason = "nni_not_found" | "nni_invalid" | "registry_unavailable" | "result_from_cache";
-type FaceMatchReason = "no_face_source" | "no_face_reference" | "low_quality_reference" | "below_threshold" | "review_band";
-type DocReason = "side_missing" | "mrz_checksum_failed" | "unreadable" | "expired_document" | "authenticity_review" | "registry_mismatch";
+type LivenessReason = "no_face" | "media_unreadable" | "clip_too_short" | "spoof_detected" | "review_band" | "liveness_inconclusive" | "mobile_required" | "uncalibrated_capture_channel";
+type PopulationReason = "nni_not_found" | "nni_invalid" | "registry_unavailable" | "result_from_cache" | "nationality_not_allowed" | "underage" | "age_unverifiable" | "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch";
+type FaceMatchReason = "no_face_source" | "no_face_reference" | "low_quality_reference" | "below_threshold" | "review_band" | "match_inconclusive";
+type DocReason = "side_missing" | "mrz_checksum_failed" | "unreadable" | "expired_document" | "authenticity_review" | "document_authenticity" | "registry_mismatch" | "document_nni_mismatch" | "document_type_not_accepted" | "nationality_not_allowed" | "underage" | "age_unverifiable" | "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch" | "document_number_mismatch";
+/**
+ * Profile v2 step 3 matching reasons: a field the partner sent at session
+ * create (`subject`) differs from the reference identity (document or
+ * registry). All four are final. `document_number_mismatch` is `doc_ocr` only.
+ */
+type MatchReason = "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch" | "document_number_mismatch";
+/**
+ * Profile v2 step 4 decision-mode reasons (the app decides automatically
+ * instead of sending the case to human review). These park the step at
+ * `input_required` while attempts remain: `liveness_inconclusive` /
+ * `match_inconclusive` (middle score band) and `document_authenticity`
+ * (retake the original card). `mobile_required` is kept for compatibility:
+ * the backend now answers a non-phone capture with a request-level
+ * `409 mobile_required` (continue on a phone; nothing used, not billed).
+ */
+type DecisionReason = "liveness_inconclusive" | "match_inconclusive" | "document_authenticity" | "mobile_required";
 /**
  * phone_otp reasons (Task 13). All transient — the caller fixes them by
  * re-entering / resending: `otp_mismatch` (wrong or missing code),
@@ -23,6 +39,49 @@ type PhoneOtpReason = "otp_mismatch" | "otp_expired" | "otp_send_failed";
  * and face_match both carry `review_band`.
  */
 type CheckReason = LivenessReason | PopulationReason | FaceMatchReason | DocReason | PhoneOtpReason;
+/**
+ * Session-level failure reasons: the session was stopped by a policy gate,
+ * not by a failed check. All are terminal (no retry on this session):
+ *  - `location_not_allowed` / `anonymizer_blocked` (profile v2 step 2): the
+ *    person's IP location is not allowed, or an anonymizer (VPN / proxy / Tor)
+ *    was detected while the app blocks them;
+ *  - `capture_tampered` (step 4): the device reported a tampered capture
+ *    (virtual camera, hooking, emulator…) while the app blocks it;
+ *  - `device_velocity_exceeded` (step 4): this device already verified too
+ *    many different people while the app blocks it;
+ *  - `device_cooldown` (step 4): this device had too many rejected sessions —
+ *    {@link HostedSessionView.retryAfter} says when it may try again.
+ */
+type SessionFailureReason = "location_not_allowed" | "anonymizer_blocked" | "capture_tampered" | "device_velocity_exceeded" | "device_cooldown";
+/**
+ * The profile-v2 policy reasons a session can end on: the two session-level
+ * reasons plus the failed check's policy reasons (`document_type_not_accepted`,
+ * `nationality_not_allowed`, `underage`, `age_unverifiable`,
+ * `document_nni_mismatch`).
+ */
+type PolicyFailureReason = SessionFailureReason | "document_type_not_accepted" | "nationality_not_allowed" | "underage" | "age_unverifiable" | "document_nni_mismatch";
+/**
+ * How the person proves their identity when the app makes the document
+ * optional for registry nationals (profile v2 step 3): type their national
+ * number (NNI) and skip the document, or photograph their document.
+ */
+type IdentityMethod = "national_number" | "document_photo";
+/**
+ * The identity-method choice of a session (`HostedSessionView.methodChoice`).
+ * While `available && selected === null` no check can be submitted (409
+ * `method_required`): the page asks first and sends the answer with
+ * `POST /hosted/method` ({@link HostedClient.selectMethod}).
+ */
+interface MethodChoiceView {
+    /** The session offers the choice (the app's document mode is `optional`). */
+    available: boolean;
+    /** The chosen method, or `null` while the person has not chosen. */
+    selected: IdentityMethod | null;
+    /** The methods to offer, in display order. */
+    options: IdentityMethod[];
+}
+/** A document type the backend reads today (kyc-docs-v2 vocabulary). */
+type AcceptedDocumentType = "carte_identite" | "passport";
 /**
  * phone_otp DISPLAY-SAFE surface (Task 16). The backend stashes the OTP
  * service `verifToken` on the check's persisted outputs (the doc_ocr partial
@@ -66,6 +125,67 @@ interface HostedStepView {
     acceptedSides?: ("recto" | "verso")[];
     /** phone_otp only: the display-safe OTP send/config surface (never the verifToken). */
     otp?: HostedOtpView;
+    /**
+     * The check failed after using all of its attempts — no retry is left.
+     * Absent on older APIs (treat absent as `false`).
+     */
+    attemptsExhausted?: boolean;
+    /**
+     * population_registry only: the session is not bound to an NNI, but the
+     * document step already read a valid one — the page submits the registry
+     * check with an EMPTY input (no NNI field) and the backend uses the
+     * document's number. Absent on older APIs.
+     */
+    nniFromDocument?: boolean;
+    /**
+     * liveness / face_match (profile v2 step 4, decision mode `automatic`): the
+     * capture must come from a phone — the liveness band is calibrated on
+     * mobile captures only. A desktop page hands the person off to their phone
+     * instead of capturing (a desktop submission answers `mobile_required`).
+     * Absent on older APIs and in `review` mode.
+     */
+    requiresMobile?: boolean;
+}
+/** A locale the Sekyro AI-hosted voice clips are recorded in. */
+type HostedVoiceLocale = "ar" | "fr" | "en";
+/**
+ * The session's Sekyro AI-hosted voice-guidance clips (the active clip set).
+ *
+ * `clips[locale]` maps a voice key (`fcv3.*`, the `@sekyro/react` voice-key
+ * namespace) to an ABSOLUTE URL on the Sekyro AI assets host
+ * (`https://assets.sekyro.ai/voice/<setId>/<locale>/<name>.mp3`; staging:
+ * `assets-staging.sekyro.ai`). URLs are immutable per `setId`. A locale or key
+ * may be missing — the player falls back to the device voice for it.
+ *
+ * A page with a Content-Security-Policy must allow the assets origin in
+ * `media-src` for the clips to play (see the partner web-SDK guide, CSP note).
+ */
+interface HostedVoiceView {
+    /** Identifier of the active clip set (part of every clip URL). */
+    setId: string;
+    /** Per-locale map of voice key (`fcv3.*`) → absolute clip URL. */
+    clips: {
+        readonly [L in HostedVoiceLocale]?: Readonly<Record<string, string>>;
+    };
+}
+/** A branding colour key (each value is `#rrggbb`). */
+type HostedBrandingColorKey = "brand" | "brandFg" | "bg" | "surface" | "fg" | "fgMuted" | "danger" | "success" | "warning";
+/**
+ * The org / app branding of a session (`HostedSessionView.branding`): only the
+ * fields set in the dashboard, merged per field (app over org). A field the
+ * org and app left unset is ABSENT — keep your default for it; the whole
+ * object is absent when nothing is set. `logoUrl` is a short-lived signed URL
+ * (15 minutes).
+ */
+interface HostedBranding {
+    /** Signed URL of the logo (PNG or sanitized SVG); absent when none is set. */
+    logoUrl?: string;
+    /** Colours as `#rrggbb`. */
+    colors?: Partial<Record<HostedBrandingColorKey, string>>;
+    /** Corner radius step. */
+    radius?: "none" | "sm" | "md" | "lg" | "full";
+    /** Font choice (system fallbacks when the font is not installed). */
+    fontFamily?: "system" | "inter" | "ibm-plex-sans-arabic" | "noto-sans-arabic" | "roboto";
 }
 /**
  * Token-addressed hosted-page bootstrap (`GET /hosted/session`). A separate
@@ -110,6 +230,41 @@ interface HostedSessionView {
      * valid (additive field, always on the wire from Task 8 onward).
      */
     nniBound?: boolean;
+    /**
+     * The Sekyro AI-hosted voice-guidance clips of this session, or `null` when no
+     * clip set is active (the device voice is used). Optional: older APIs omit
+     * the field — treat absent like `null`.
+     */
+    voice?: HostedVoiceView | null;
+    /**
+     * Why the session ended, when a profile-v2 policy stopped it: a
+     * {@link SessionFailureReason}, or the failed check's reason when it is a
+     * policy reason (eligibility, or `document_nni_mismatch`). Absent otherwise
+     * (and on older APIs).
+     */
+    failureReason?: PolicyFailureReason;
+    /**
+     * The document types the person may pick (resolved for issuer `MR`). Absent
+     * on older APIs — treat absent as every type (`carte_identite`, `passport`).
+     */
+    acceptedDocumentTypes?: AcceptedDocumentType[];
+    /**
+     * The identity-method choice (profile v2 step 3). Absent when the session
+     * has no choice (and on older APIs). While `available && selected === null`
+     * every check submission answers 409 `method_required`.
+     */
+    methodChoice?: MethodChoiceView;
+    /**
+     * ISO-8601 time from which this device may verify again — set with
+     * `failureReason: 'device_cooldown'` (profile v2 step 4). Absent otherwise
+     * (and on older APIs).
+     */
+    retryAfter?: string;
+    /**
+     * The org / app branding (settings spec §5.1). Absent on older APIs — keep
+     * the default theme. Map it with `brandingToTheme()` from `@sekyro/react`.
+     */
+    branding?: HostedBranding;
 }
 /** `POST /hosted/consent` result — 201 on first record, 200 `{alreadyRecorded: true}` on replay. */
 interface RecordConsentResult {
@@ -123,6 +278,8 @@ interface SessionStepView {
     state: CheckState;
     reason?: CheckReason;
     calibratedScore?: number;
+    /** The check failed after using all of its attempts. Absent on older APIs. */
+    attemptsExhausted?: boolean;
 }
 /**
  * Client-facing session projection returned by
@@ -132,6 +289,8 @@ interface SessionView {
     id: string;
     status: SessionStatus;
     outcome: SessionOutcome | null;
+    /** Profile-v2 policy stop reason; absent on ordinary failures and older APIs. */
+    failureReason?: PolicyFailureReason;
     steps: SessionStepView[];
     /** ISO-8601 timestamp (Date on the server, string on the wire). */
     expiresAt: string;
@@ -181,7 +340,14 @@ interface AttestationInput {
     /** The Turnstile site key the token was minted with (selects the verifying secret). */
     siteKey?: string;
 }
-/** liveness executor input: a promoted `clips/…` key + optional attestation. */
+/**
+ * liveness executor input: a promoted `clips/…` key + optional attestation.
+ * `faceMatch` (v2 latency §3.2) carries the already-promoted `doc-images/…`
+ * keyframe so the backend can run face_match IN THE SAME submission when its
+ * bundle flag is on and `face_match` is the next pending step. Backends that
+ * do not bundle ignore it (the input bag is an open record) — the SDK then
+ * submits `face_match` itself with the same key (see liveness-flow.ts).
+ */
 interface LivenessInput {
     clipKey: string;
     attestation?: AttestationInput;
@@ -193,6 +359,10 @@ interface LivenessInput {
     /** Capture metadata (engine, dimensions, clip length, face-capture timing)
      *  — the backend's allowlisted, non-PII `capture` block (session insights). */
     capture?: LivenessCaptureInput;
+    /** The promoted face_match probe key, for a bundled liveness + face_match run. */
+    faceMatch?: {
+        imageKey: string;
+    };
 }
 /** `LivenessInput.capture`: what the SDK's `captured` event measured. All ms are whole, ≥ 0. */
 interface LivenessCaptureInput {
@@ -213,7 +383,10 @@ interface LivenessCaptureInput {
 interface PopulationInput {
     nni?: string;
 }
-/** face_match executor input: a promoted `doc-images/…` key (the source selfie frame). */
+/**
+ * face_match executor input: a promoted `doc-images/…` key (the source selfie frame).
+ * The same key may already have ridden along as {@link LivenessInput.faceMatch}.
+ */
 interface FaceMatchInput {
     imageKey: string;
 }
@@ -320,6 +493,7 @@ interface HostedClientOptions {
  *
  *   GET  /api/v2/hosted/session                     → {@link getSession}
  *   POST /api/v2/hosted/consent                     → {@link recordConsent}
+ *   POST /api/v2/hosted/method                      → {@link selectMethod}
  *   POST /api/v2/sessions/:id/media                 → {@link presign}
  *   POST /api/v2/sessions/:id/media/complete        → {@link completeMedia}
  *   POST /api/v2/sessions/:id/checks/:checkType     → {@link submitCheck}
@@ -358,6 +532,13 @@ declare class HostedClient {
      * submission answer 409 `consent_required`.
      */
     recordConsent(locale: ConsentLocale): Promise<RecordConsentResult>;
+    /**
+     * Send the person's identity method (profile v2 step 3) when the view offers
+     * a choice (`methodChoice.available`). Returns the updated hosted view —
+     * continue from it. 409 `method_locked` when the method can no longer
+     * change (a check of the chosen method was already submitted).
+     */
+    selectMethod(method: IdentityMethod): Promise<HostedSessionView>;
     /**
      * Presign a Spaces PUT for a new pending object. `contentType` is stripped of
      * MIME parameters defensively (the allowlist holds bare types; the engine's
@@ -418,4 +599,4 @@ declare class HostedClient {
     private api;
 }
 
-export { type AttestationInput as A, type CheckReason as C, type DocReason as D, type FaceMatchReason as F, type HostedOtpView as H, type LivenessReason as L, type MediaCheckType as M, type PhoneOtpReason as P, type RecordConsentResult as R, type SessionOutcome as S, type UploadMedia as U, type CheckState as a, type CheckType as b, type HostedSessionView as c, type HostedStepView as d, type PopulationReason as e, type SessionStatus as f, HostedClient as g, type SessionView as h, type CheckInputByType as i, type CompleteMediaResult as j, type ConsentLocale as k, type DocOcrInput as l, type DocSide as m, type FaceMatchInput as n, type HostedClientOptions as o, type LivenessCaptureInput as p, type LivenessInput as q, type MediaKind as r, type PhoneOtpInput as s, type PopulationInput as t, type PresignRequest as u, type PresignUploadResult as v, type SessionStepView as w, type SubmitCheckBody as x, type SubmitOptions as y, stripMimeParams as z };
+export { type AcceptedDocumentType as A, type MediaCheckType as B, type CheckReason as C, type DecisionReason as D, type MediaKind as E, type FaceMatchReason as F, type PhoneOtpInput as G, type HostedBranding as H, type IdentityMethod as I, type PopulationInput as J, type PresignRequest as K, type LivenessReason as L, type MatchReason as M, type PresignUploadResult as N, type SessionStepView as O, type PhoneOtpReason as P, type SubmitCheckBody as Q, type RecordConsentResult as R, type SessionFailureReason as S, type SubmitOptions as T, type UploadMedia as U, stripMimeParams as V, type CheckState as a, type CheckType as b, type DocReason as c, type HostedBrandingColorKey as d, type HostedOtpView as e, type HostedSessionView as f, type HostedStepView as g, type HostedVoiceLocale as h, type HostedVoiceView as i, type MethodChoiceView as j, type PolicyFailureReason as k, type PopulationReason as l, type SessionOutcome as m, type SessionStatus as n, HostedClient as o, type AttestationInput as p, type SessionView as q, type CheckInputByType as r, type CompleteMediaResult as s, type ConsentLocale as t, type DocOcrInput as u, type DocSide as v, type FaceMatchInput as w, type HostedClientOptions as x, type LivenessCaptureInput as y, type LivenessInput as z };