@sekyro/web 0.0.0-stage → 0.1.0-rc.2

package/dist/hosted-client-BpvBqu9f.d.ts

@@ -0,0 +1,408 @@
+/** Session lifecycle status (spec §4 two-field status/outcome model). */
+type SessionStatus = "created" | "in_progress" | "review_pending" | "completed" | "expired" | "failed";
+/** Terminal verdict, orthogonal to `status`; `null` until terminal/review. */
+type SessionOutcome = "approved" | "review" | "rejected";
+/** Per-check seven-state machine (spec §4.3). */
+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";
+/**
+ * phone_otp reasons (Task 13). All transient — the caller fixes them by
+ * re-entering / resending: `otp_mismatch` (wrong or missing code),
+ * `otp_expired` (code lapsed or no active send), `otp_send_failed` (the OTP
+ * service was unreachable / a send returned no token).
+ */
+type PhoneOtpReason = "otp_mismatch" | "otp_expired" | "otp_send_failed";
+/**
+ * Any frozen reason code. The backend declares the field `string`, but the
+ * taxonomy is frozen (do-not-drift) — the union IS the contract. NB: liveness
+ * and face_match both carry `review_band`.
+ */
+type CheckReason = LivenessReason | PopulationReason | FaceMatchReason | DocReason | PhoneOtpReason;
+/**
+ * phone_otp DISPLAY-SAFE surface (Task 16). The backend stashes the OTP
+ * service `verifToken` on the check's persisted outputs (the doc_ocr partial
+ * mechanism), but that token is NEVER projected here — only the fields the
+ * hosted OTP step renders. `numberSource` (org-authored config) drives the
+ * send-phase UI (prefilled display vs entry); the rest appear ONLY once a send
+ * has parked the check (`sentToMasked` present ⇒ verify phase).
+ */
+interface HostedOtpView {
+    /**
+     * Per-step `config.numberSource` — drives the send-phase UI (prefilled
+     * display vs entry). Narrowed to the frontend contract; the backend field is
+     * `string` (dynamic config) but the projection only ever emits these three.
+     */
+    numberSource?: "prefilled" | "user_entered" | "prefilled_or_entered";
+    /** Masked target the last send went to (e.g. `+222 ** ** 34 56`); absent pre-send. */
+    sentToMasked?: string;
+    /** Delivery channel of the last send. */
+    channel?: "sms" | "whatsapp";
+    /** ISO-8601 OTP expiry from the last send — drives the verify-phase countdown. */
+    expiresAt?: string;
+}
+/**
+ * Per-check projection in a {@link HostedSessionView} — the spec'd hosted step
+ * shape. NEVER carries `calibratedScore` or the raw check `outputs`; the only
+ * output-derived data is the phone_otp `HostedOtpView` display subset
+ * (masked number/channel/expiry — never the verifToken).
+ */
+interface HostedStepView {
+    checkType: CheckType;
+    state: CheckState;
+    /** Frozen-taxonomy reason code explaining a `failed`/`review` state. */
+    reason?: CheckReason;
+    /**
+     * Submissions the page may still make for this check (`max(0, cap - attempts)`).
+     * Meaningful only while the check is executable — a finalized check may still
+     * report more than 0, but re-submitting it 409s regardless.
+     */
+    attemptsRemaining: number;
+    /** doc_ocr only: sides already accepted into the partial accumulator (['recto'] or ['verso']). */
+    acceptedSides?: ("recto" | "verso")[];
+    /** phone_otp only: the display-safe OTP send/config surface (never the verifToken). */
+    otp?: HostedOtpView;
+}
+/**
+ * Token-addressed hosted-page bootstrap (`GET /hosted/session`). A separate
+ * shape from the partner `SessionView`: `sessionId` instead of `id`,
+ * hosted step hints, the consent flag, and the org display name (may be `''`
+ * when the org lookup degrades).
+ */
+interface HostedSessionView {
+    sessionId: string;
+    status: SessionStatus;
+    outcome: SessionOutcome | null;
+    steps: HostedStepView[];
+    /** ISO-8601 timestamp (Date on the server, string on the wire). */
+    expiresAt: string;
+    consentRecorded: boolean;
+    orgName: string;
+    /**
+     * The FIRST allowlisted web-SDK origin of the owning org (Task 12), or null
+     * when none is registered. The hosted page posts the SDK popup postMessage
+     * events (event name + sessionId ONLY) to exactly this origin — never `'*'`.
+     * The backend declares it required (`string | null`); optional here so
+     * pre-Task-12 consumers/fixtures stay valid (additive field, always on the
+     * wire from Task 12 onward).
+     */
+    sdkOrigin?: string | null;
+    /**
+     * Cloudflare Turnstile site key the browser must solve an execute-mode
+     * challenge against before submitting `liveness` (Plan A Task 5): the org's
+     * own widget key when the request origin is one of the org's allowlisted SDK
+     * origins, else the hosted widget key, else `null`. `null` means the session
+     * cannot be attested from the browser — the SDK sends `{sandbox: true}`,
+     * which the backend honours ONLY on sandbox sessions (fails closed on live).
+     */
+    turnstileSiteKey: string | null;
+    /**
+     * The session was minted with a server-bound NNI (`POST /sessions`
+     * `input.nni`, Plan A Task 2): `population_registry` is submitted with an
+     * EMPTY input and the backend reads the sealed value. `false` means the
+     * person must supply the NNI (hosted population form); the SDK never submits
+     * the registry check on an unbound session. The VALUE is never exposed. The
+     * backend declares it required; optional here so pre-Task-8 fixtures stay
+     * valid (additive field, always on the wire from Task 8 onward).
+     */
+    nniBound?: boolean;
+}
+/** `POST /hosted/consent` result — 201 on first record, 200 `{alreadyRecorded: true}` on replay. */
+interface RecordConsentResult {
+    alreadyRecorded: boolean;
+}
+/** Consent locale — the page's `[locale]` URL segment echoed back (HostedConsentSchema picklist). */
+type ConsentLocale = "ar" | "fr" | "en";
+/** Per-check projection in a {@link SessionView} — enum/id only, never civil data. */
+interface SessionStepView {
+    checkType: CheckType;
+    state: CheckState;
+    reason?: CheckReason;
+    calibratedScore?: number;
+}
+/**
+ * Client-facing session projection returned by
+ * `POST /sessions/:id/checks/:checkType`. Whitelist-only — never the client token.
+ */
+interface SessionView {
+    id: string;
+    status: SessionStatus;
+    outcome: SessionOutcome | null;
+    steps: SessionStepView[];
+    /** ISO-8601 timestamp (Date on the server, string on the wire). */
+    expiresAt: string;
+    /** ISO-8601 timestamp (Date on the server, string on the wire). */
+    createdAt?: string;
+}
+/** Media class — selects size cap, MIME allowlist and promoted prefix (media.policy.ts). */
+type MediaKind = "image" | "clip";
+/**
+ * Body of `POST /sessions/:id/media`. `contentType`/`contentLength` are the
+ * exact values SIGNED into the presigned PUT — the PUT must send them verbatim.
+ * Allowlists (media.policy.ts): image → image/jpeg | image/png (5 MB cap);
+ * clip → video/webm | video/mp4 (15 MB cap). BARE types only — no `;codecs=` params.
+ */
+interface PresignRequest {
+    kind: MediaKind;
+    contentType: string;
+    contentLength: number;
+}
+/** Result of a presign — the presigned PUT URL plus the pending object key. */
+interface PresignUploadResult {
+    key: string;
+    uploadUrl: string;
+    /** Presign TTL in seconds (900 = 15 min). */
+    expiresIn: number;
+}
+/** Result of `POST /sessions/:id/media/complete` — the PROMOTED (class-prefixed) key. */
+interface CompleteMediaResult {
+    ready: true;
+    /** e.g. `clips/{sessionId}/{uuid}` or `doc-images/{sessionId}/{uuid}` — submit THIS key, not the pending one. */
+    key: string;
+}
+/**
+ * Liveness attestation bag (attestation-verifier.service.ts). The web SDK sends
+ * `{channel: 'hosted_web', siteKey, turnstileToken}` — `siteKey` echoes the
+ * `HostedSessionView.turnstileSiteKey` the challenge was rendered with, so the
+ * backend picks the matching widget secret deterministically (Turnstile tokens
+ * are single-use: siteverify runs exactly once, never "org then global").
+ * `sandbox: true` is honored only on sandbox sessions; `signature` is the
+ * future native-SDK channel.
+ */
+interface AttestationInput {
+    sandbox?: boolean;
+    signature?: string;
+    channel?: "hosted_web";
+    turnstileToken?: string;
+    /** The Turnstile site key the token was minted with (selects the verifying secret). */
+    siteKey?: string;
+}
+/** liveness executor input: a promoted `clips/…` key + optional attestation. */
+interface LivenessInput {
+    clipKey: string;
+    attestation?: AttestationInput;
+    /** Declared capture channel — the liveness band is mobile-calibrated, so the
+     *  backend clamps non-mobile verdicts to review (uncalibrated_capture_channel).
+     *  Client-declared by design (not a security boundary); absent = legacy
+     *  clients, treated as mobile server-side during the rollout window. */
+    captureChannel?: 'mobile' | 'desktop';
+}
+/**
+ * population_registry adapter input. `nni` is the 10-digit NNI for an UNBOUND
+ * session; a session minted with a server-side `input.nni` is BOUND to it
+ * (Plan A Task 2) — the browser submits `{}` and the backend reads the sealed
+ * value. Sending a DIFFERENT nni on a bound session answers 409 `nni_locked`.
+ */
+interface PopulationInput {
+    nni?: string;
+}
+/** face_match executor input: a promoted `doc-images/…` key (the source selfie frame). */
+interface FaceMatchInput {
+    imageKey: string;
+}
+/** Document side (docs.types.ts DocSide). */
+type DocSide = "recto" | "verso" | "single";
+/** doc_ocr executor input: a promoted `doc-images/…` key + which side it shows. */
+interface DocOcrInput {
+    imageKey: string;
+    side: DocSide;
+}
+/**
+ * phone_otp executor input (Task 13): a two-phase check. `send` dispatches (or
+ * resends) an OTP — resolving the number from the trusted server-side prefill
+ * or the user-entered `phone` per the step's `numberSource`; `verify` checks
+ * the entered `code` against the parked token. `phone` is IGNORED for a
+ * `prefilled` step (a client number is never trusted as "prefilled").
+ */
+interface PhoneOtpInput {
+    /** Phase selector: `send` dispatches/resends, `verify` checks the code. Defaults to `send`. */
+    action: "send" | "verify";
+    /** USER-entered E.164 number (`user_entered` / `prefilled_or_entered` sends only). */
+    phone?: string;
+    /** The code the user typed — `verify` only. */
+    code?: string;
+    /** Delivery channel override for `send` (default `sms`). */
+    channel?: "sms" | "whatsapp";
+    /** OTP message locale override for `send`. */
+    locale?: "ar" | "fr" | "en";
+}
+/** Per-check-type submission input shapes, keyed by the frozen vocabulary. */
+interface CheckInputByType {
+    liveness: LivenessInput;
+    face_match: FaceMatchInput;
+    doc_ocr: DocOcrInput;
+    population_registry: PopulationInput;
+    phone_otp: PhoneOtpInput;
+}
+/**
+ * Body of `POST /sessions/:id/checks/:checkType` (SubmitCheckSchema).
+ * `forceOutcome` is SANDBOX-ONLY (plan D-C) — a live session rejects it with
+ * 403 `force_outcome_forbidden`.
+ */
+interface SubmitCheckBody {
+    input?: Record<string, unknown>;
+    forceOutcome?: "pass" | "fail";
+}
+
+/**
+ * Strip MIME parameters: `video/webm;codecs=vp8,opus` → `video/webm`.
+ *
+ * The capture engine (Task 4) emits `clipMimeType` WITH codec parameters, but
+ * the presign allowlist holds BARE types only (['video/webm','video/mp4'] /
+ * ['image/jpeg','image/png']) and the presigned PUT signs the exact declared
+ * Content-Type. Exported so pages can normalize once and stay byte-consistent
+ * between presign and PUT.
+ */
+declare function stripMimeParams(contentType: string): string;
+/** Media-bearing check types → the input field the promoted key goes into. */
+declare const MEDIA_INPUT_FIELD: {
+    readonly liveness: "clipKey";
+    readonly face_match: "imageKey";
+    readonly doc_ocr: "imageKey";
+};
+/** Check types that take an uploaded media key (population_registry does not). */
+type MediaCheckType = keyof typeof MEDIA_INPUT_FIELD;
+interface SubmitOptions {
+    /**
+     * Sent as `x-idempotency-key` (the header IdempotencyInterceptor reads).
+     * One key per LOGICAL submit — a flaky-network retry with the same key
+     * replays the first response without burning another attempt.
+     */
+    idempotencyKey?: string;
+    /** SANDBOX-ONLY deterministic override (plan D-C); a live session 403s it. */
+    forceOutcome?: "pass" | "fail";
+}
+interface UploadMedia {
+    kind: MediaKind;
+    blob: Blob;
+    /** May carry codec params (engine `clipMimeType`) — stripped before presign AND PUT. */
+    contentType: string;
+}
+interface HostedClientOptions {
+    /** API origin, e.g. `https://api.sekyro.ai` — paths are `${apiOrigin}/api/v2/...`. */
+    apiOrigin: string;
+    /** The raw session token from the hosted URL (short code; legacy `cst_` during its TTL) — sent as `x-session-token` on every API call. */
+    sessionToken: string;
+    /** Injection seam (tests / non-window contexts). Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Per-request timeout for API calls (NOT the Spaces PUT). Default 30 000 ms. */
+    requestTimeoutMs?: number;
+    /**
+     * Tuning for the ONLY automatic retry the client performs: 409
+     * `idempotency_in_progress` (a concurrent identical request is mid-flight
+     * server-side; the real response lands once it finishes). `attempts` counts
+     * retries AFTER the first try. Defaults: 5 × 400 ms.
+     */
+    inProgressRetry?: {
+        attempts?: number;
+        delayMs?: number;
+    };
+}
+/**
+ * Hand-authored typed client for the five session-token endpoints:
+ *
+ *   GET  /api/v2/hosted/session                     → {@link getSession}
+ *   POST /api/v2/hosted/consent                     → {@link recordConsent}
+ *   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}
+ *
+ * plus the bare presigned Spaces PUT ({@link uploadToSpaces}) and the
+ * presign→PUT→complete→submit composition ({@link uploadAndSubmit}).
+ *
+ * Envelopes (verified against sessions-docs.e2e-spec.ts):
+ *  - success: `{success: true, data}` — unwrapped here, methods return the payload;
+ *  - error: flat `{code, message}` → thrown as {@link HostedApiError}.
+ *
+ * The media/checks routes are `:id`-addressed while the token itself is the
+ * only credential the page starts with — the client learns its sessionId from
+ * `GET /hosted/session` (token-addressed) and lazily bootstraps it when a
+ * `:id` route is called first.
+ *
+ * No automatic retry EXCEPT bounded short-delay retry on 409
+ * `idempotency_in_progress`. Everything else — including 429 with its parsed
+ * `retryAfterSeconds` — is surfaced to the page to handle.
+ */
+declare class HostedClient {
+    private readonly apiOrigin;
+    private readonly sessionToken;
+    private readonly fetchImpl;
+    private readonly requestTimeoutMs;
+    private readonly retryAttempts;
+    private readonly retryDelayMs;
+    private sessionId;
+    private bootstrap;
+    constructor(opts: HostedClientOptions);
+    /** Token-addressed bootstrap — the hosted page's first call. Caches the sessionId. */
+    getSession(): Promise<HostedSessionView>;
+    /**
+     * Record consent once (201; an idempotent replay answers 200 with
+     * `alreadyRecorded: true`). Until recorded, media presign/complete AND check
+     * submission answer 409 `consent_required`.
+     */
+    recordConsent(locale: ConsentLocale): Promise<RecordConsentResult>;
+    /**
+     * Presign a Spaces PUT for a new pending object. `contentType` is stripped of
+     * MIME parameters defensively (the allowlist holds bare types; the engine's
+     * `clipMimeType` carries codec params) — PUT with the SAME bare type, or the
+     * signed-header check rejects the upload.
+     */
+    presign(kind: MediaKind, contentType: string, contentLength: number): Promise<PresignUploadResult>;
+    /**
+     * Bare PUT to the presigned Spaces URL: EXACTLY the signed headers — the
+     * declared Content-Type and the blob body. NO `x-session-token` (the
+     * signature IS the credential; an extra header breaks nothing but leaks the
+     * token to a third-party host) and no JSON envelope.
+     *
+     * `contentType` is param-stripped here too (idempotent for bare types): the
+     * presign strips internally, so a caller composing manually with the engine's
+     * parameterful `clipMimeType` would otherwise sign `video/webm` but PUT
+     * `video/webm;codecs=…` — a signed-header mismatch S3 rejects at runtime.
+     *
+     * Timeout: 15 min (`AbortSignal.timeout(900_000)`, matching the presign TTL)
+     * rather than the API calls' 30 s — a 15 MB clip on a slow link legitimately
+     * exceeds 30 s, but a stalled in-flight socket must still be bounded (the TTL
+     * alone only bounds when a PUT can START).
+     *
+     * Failures are ALWAYS typed: non-2xx throws {@link HostedApiError} with the
+     * client-synthesized `upload_failed` (message carries a truncated S3 body
+     * snippet — e.g. SignatureDoesNotMatch); a mid-transfer drop → `network_error`;
+     * the timeout → `timeout`.
+     */
+    uploadToSpaces(uploadUrl: string, blob: Blob, contentType: string): Promise<void>;
+    /** Finalize an upload: the backend sniffs + promotes; returns the PROMOTED key to submit. */
+    completeMedia(key: string): Promise<CompleteMediaResult>;
+    /**
+     * Submit one check. Sends `{input, forceOutcome?}` (SubmitCheckSchema) and the
+     * optional `x-idempotency-key` header. Returns the whitelisted SessionView.
+     */
+    submitCheck<T extends CheckType>(checkType: T, input: CheckInputByType[T], opts?: SubmitOptions): Promise<SessionView>;
+    /**
+     * Convenience composition: presign → PUT → complete → submit, passing the
+     * PROMOTED key (from complete's response — never the pending presign key)
+     * into the check's media input field (`clipKey` for liveness, `imageKey` for
+     * face_match/doc_ocr). `extraInput` carries the remaining input fields
+     * (liveness `attestation`, doc_ocr `side`). The media content type is
+     * param-stripped ONCE and used for both presign and PUT, so the signed
+     * header always matches.
+     */
+    uploadAndSubmit<T extends MediaCheckType>(checkType: T, media: UploadMedia, extraInput: Omit<CheckInputByType[T], (typeof MEDIA_INPUT_FIELD)[T]>, opts?: SubmitOptions): Promise<SessionView>;
+    /** The token's own sessionId — cached from getSession(), lazily bootstrapped. */
+    private ensureSessionId;
+    /**
+     * One API request: `${apiOrigin}/api/v2${path}`, `x-session-token` always,
+     * AbortSignal timeout (30 s default), `{success, data}` unwrap on 2xx, flat
+     * `{code, message}` → {@link HostedApiError} on non-2xx. EVERY failure is
+     * typed: a rejected fetch → `network_error`, the timeout → `timeout`, an
+     * unparseable 2xx body → `unknown_error` — the page never sees a raw
+     * TypeError/DOMException. The ONLY automatic retry is 409
+     * `idempotency_in_progress` (bounded, short delay).
+     */
+    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 LivenessInput as p, type MediaKind as q, type PhoneOtpInput as r, type PopulationInput as s, type PresignRequest as t, type PresignUploadResult as u, type SessionStepView as v, type SubmitCheckBody as w, type SubmitOptions as x, stripMimeParams as y };