@kyciris/core 0.1.1 → 1.0.0

package/dist/index.d.ts

@@ -1,402 +1,1452 @@
 /**
- * Pluggable, platform-agnostic key/value storage used to persist the verification
- * session so a paused flow survives the app being closed.
+ * The largest upload the gateway accepts (MAX_IMAGE_FILE_SIZE). Checked here
+ * too, when the SDK can see the bytes, so an 8MB upload fails instantly
+ * instead of after the whole body has gone over the wire.
+ */
+declare const MAX_IMAGE_FILE_SIZE: number;
+/** The only image types the gateway accepts, decided by magic bytes. */
+type ImageMimeType = 'image/jpeg' | 'image/png';
+/**
+ * An image to upload, in whichever form the host platform produces.
  *
- * Inject a concrete implementation: AsyncStorage on React Native, or an adapter
- * around localStorage on web. Methods may be sync or async; results are awaited.
+ * - `Blob` / `File` — browsers, and Node 18+ (`new Blob([bytes])`).
+ * - `{ uri }` — React Native: a `file://`, `content://`, `ph://` or `data:` URI
+ *   from the camera or image picker.
+ * - `{ data }` — raw bytes, e.g. `fs.readFileSync()` in Node.
+ * - `string` — a `data:` URI, a bare base64 payload, or a React Native file URI.
  */
-interface KYCStorage {
-    /** Returns the stored value for a key, or null if absent */
-    getItem(key: string): string | null | Promise<string | null>;
-    /** Persists a value for a key */
-    setItem(key: string, value: string): void | Promise<void>;
-    /** Removes a stored key */
-    removeItem(key: string): void | Promise<void>;
+type FileInput = Blob | {
+    uri: string;
+    name?: string;
+    type?: string;
+} | {
+    data: ArrayBuffer | ArrayBufferView;
+    name?: string;
+    type?: string;
+} | string | NormalizedFile;
+/** A file ready to be appended to FormData on this platform. */
+interface NormalizedFile {
+    /** Blob on web/Node, `{ uri, name, type }` on React Native. */
+    value: unknown;
+    filename: string;
+    /** Sniffed from the bytes where possible, otherwise the caller's hint. */
+    mimeType: string;
 }
+/** True when `value` has already been through {@link normalizeFile}. */
+declare function isNormalizedFile(value: unknown): value is NormalizedFile;
 /**
- * The persisted verification session, used to resume an in-flight verification.
+ * React Native's FormData takes `{ uri, name, type }` and streams the file
+ * itself; it has no filesystem access from JS to turn that URI into a Blob.
+ * Everywhere else, Blob is the portable choice.
  */
-interface KYCSession {
-    /** Identity ID owning the verification */
-    identityId: string;
-    /** Verification ID being completed */
-    verificationId: string;
-    /** External reference ID provided when starting (if any) */
-    externalId?: string;
-    /** Document type for the verification */
-    documentType?: 'IDENTITY_CARD' | 'DRIVING_LICENSE';
+declare function isReactNative(): boolean;
+/**
+ * The real image type, from the first bytes.
+ *
+ * The gateway sniffs the same way and ignores the declared Content-Type, so a
+ * caller who mislabels a PNG as image/jpeg still succeeds — and one who
+ * uploads a PDF renamed to .jpg still fails. Doing it here just moves that
+ * answer earlier.
+ */
+declare function detectImageMimeType(bytes: Uint8Array): ImageMimeType | null;
+/** Decodes base64 using whichever primitive the runtime provides. */
+declare function decodeBase64(input: string): Uint8Array;
+/** Encodes bytes as base64 using whichever primitive the runtime provides. */
+declare function encodeBase64(bytes: Uint8Array): string;
+/**
+ * Turns whatever the caller has into something FormData can carry on this
+ * platform, validating the bytes first whenever they are visible.
+ *
+ * A React Native `file://` URI is the one case where they are not: the file
+ * lives on disk and only the native layer reads it, so type and size are left
+ * to the gateway to enforce.
+ *
+ * @param input The image, in any supported form
+ * @param defaultName Filename to use when the input does not carry one
+ */
+declare function normalizeFile(input: FileInput, defaultName: string): NormalizedFile;
+/**
+ * {@link normalizeFile}, but able to read a Blob's first bytes.
+ *
+ * This is what the upload path uses. A file chosen from an `<input>` arrives
+ * as a Blob whose `type` is whatever the operating system guessed from the
+ * extension, so a PDF renamed `.jpg` claims to be `image/jpeg` — and the
+ * synchronous path has to take that on trust. Reading eight bytes settles it
+ * before megabytes go over a phone connection, using the same magic-byte test
+ * the gateway applies on arrival.
+ *
+ * Every other input form is already validated synchronously, so it is simply
+ * delegated.
+ */
+declare function prepareFile(input: FileInput, defaultName: string): Promise<NormalizedFile>;
+
+/**
+ * Metadata the gateway attaches to every response, success or error.
+ *
+ * `requestId` is also returned as the X-Request-Id header and is the value to
+ * quote when reporting a problem — it correlates the call with the gateway's
+ * own logs.
+ */
+interface ApiMeta {
+    requestId: string;
+    timestamp: string;
+    /** The gateway's API version, not the SDK's. */
+    version: string;
+}
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+}
+/** A successful response, unwrapped. */
+interface ApiResult<T> {
+    data: T;
+    meta: ApiMeta;
+    /** Present only on list endpoints. */
+    pagination?: PaginationMeta;
+}
+/** A page of results: the rows, plus the pagination block that came with them. */
+interface Page<T> {
+    items: T[];
+    pagination: PaginationMeta;
 }
 /**
- * Credentials required to initialize the KYC SDK
+ * Turns an unwrapped list response into a Page.
+ *
+ * The gateway sends the rows as `data` and the counts as a sibling
+ * `pagination` block; a caller wants them together. When the endpoint returned
+ * no pagination block (or an unpaginated array), the totals are derived from
+ * the rows so the shape stays uniform.
  */
-interface KYCCredentials {
-    /** API key for authentication */
-    apiKey: string;
-    /** Base URL of the KYC API */
+declare function toPage<T>(result: ApiResult<T[]>): Page<T>;
+
+/** Returns a verification token, refreshing it if the cached one has expired. */
+type VerificationTokenProvider = () => string | Promise<string>;
+/** The subset of `fetch` the SDK uses, so a custom implementation can stand in. */
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** Which credential an endpoint accepts. */
+type AuthMode = 'api-key' | 'token' | 'any' | 'none';
+interface HttpClientConfig {
+    /** Origin of the gateway, e.g. `https://api.kyciris.com`. */
     baseUrl: string;
     /**
-     * Optional storage adapter. When provided, the SDK persists the verification
-     * session on startVerification and reads it back to resume a paused flow.
+     * Project API key. A project-wide credential — server-side only. Passing it
+     * from a browser or React Native app throws CREDENTIAL_MISUSE.
+     */
+    apiKey?: string;
+    /**
+     * Verification token, scoped to one end user. This is the credential a
+     * client app should hold: mint it on your server with
+     * `client.verifications.createToken(externalId)` and hand it out.
+     *
+     * A function is called before each request, so a token can be refreshed
+     * without rebuilding the client.
+     */
+    verificationToken?: string | VerificationTokenProvider;
+    /** URI version segment. Defaults to `v1`. */
+    apiVersion?: string;
+    /** Per-attempt timeout in ms. Defaults to 30000. */
+    timeoutMs?: number;
+    /** Retries for a failed attempt. Defaults to 2 (three attempts in total). */
+    maxRetries?: number;
+    /** Custom fetch (tests, proxies, a Node agent). Defaults to global fetch. */
+    fetch?: FetchLike;
+    /** Extra headers on every request. Cannot override the auth headers. */
+    headers?: Record<string, string>;
+    /**
+     * Allows an `http://` baseUrl to a non-loopback host.
+     *
+     * Off by default: the requests carry a project API key or a verification
+     * token and the responses carry identity-document data, none of which may
+     * cross a plaintext connection.
+     */
+    allowInsecureBaseUrl?: boolean;
+    /**
+     * Allows `apiKey` in a browser or React Native app.
+     *
+     * Only for a trusted first-party context (an internal operations console
+     * behind a login). Anything shipped to end users must use a verification
+     * token: an API key in a client bundle is extractable and grants the whole
+     * project, every identity in it included.
+     */
+    allowApiKeyInUntrustedClient?: boolean;
+}
+interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Path below the version segment, e.g. `/verification/start`. */
+    path: string;
+    query?: Record<string, unknown>;
+    /** JSON request body. Mutually exclusive with `form`. */
+    body?: unknown;
+    /** Multipart body. Values typed `FileInput` are normalized per platform. */
+    form?: Record<string, string | FileInput | undefined>;
+    /** Field names in `form` that hold a file. */
+    fileFields?: string[];
+    auth?: AuthMode;
+    signal?: AbortSignal;
+    /** Overrides the client's timeout for this call. */
+    timeoutMs?: number;
+    /**
+     * Whether a failed attempt may be repeated.
+     *
+     * Defaults to true for GET and false for everything else: a POST that timed
+     * out may well have been processed, and re-sending an upload would emit a
+     * second pipeline event. A 429 is retried regardless of method, because the
+     * gateway rejected it before doing any work.
      */
-    storage?: KYCStorage;
+    retry?: boolean;
 }
 /**
- * Parameters required to start a verification session
+ * True in a context where the bundle is delivered to an end user and anything
+ * inside it is readable by them: a browser page or a React Native app.
  */
+declare function isUntrustedClient(): boolean;
+/**
+ * The gateway's HTTP transport: URL and auth assembly, timeouts, retries, and
+ * translation of the `{ data, meta }` / `{ error, meta }` envelopes into
+ * values and KycirisErrors.
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiVersion;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    private readonly extraHeaders;
+    private readonly apiKey?;
+    private readonly tokenSource?;
+    constructor(config: HttpClientConfig);
+    /** True when the client holds a project API key. */
+    hasApiKey(): boolean;
+    /** True when the client holds (or can fetch) a verification token. */
+    hasVerificationToken(): boolean;
+    buildUrl(path: string, query?: Record<string, unknown>): string;
+    private authHeaders;
+    private resolveToken;
+    private buildForm;
+    /** Runs a request, retrying where the method and failure allow it. */
+    request<T>(options: RequestOptions): Promise<ApiResult<T>>;
+    private attempt;
+    /**
+     * Streams a response body instead of parsing it — the media download
+     * endpoint returns an image, not an envelope.
+     */
+    requestRaw(options: RequestOptions): Promise<Response>;
+}
+
+/**
+ * Domain types mirroring the KYCiris gateway's public contract.
+ *
+ * Everything here is derived from the gateway's DTOs and constants; where the
+ * gateway is the authority for a set of values (document catalog, statuses,
+ * webhook events) the list is reproduced verbatim rather than widened to
+ * `string`, so a typo fails at compile time instead of at runtime with a 422.
+ */
+/**
+ * The (country, documentType) pairs the pipeline can actually process.
+ *
+ * Mirrors DOCUMENT_CATALOG in the gateway, which in turn mirrors the OCR
+ * worker's handler registry — a pair is only real once something knows how to
+ * read it. Starting a verification for a pair outside this list is rejected by
+ * the gateway with VALIDATION_ERROR.
+ */
+declare const DOCUMENT_CATALOG: readonly [{
+    readonly country: "AO";
+    readonly documentType: "ID_CARD";
+}, {
+    readonly country: "AO";
+    readonly documentType: "DRIVING_LICENSE";
+}, {
+    readonly country: "MZ";
+    readonly documentType: "ID_CARD";
+}];
+type DocumentCatalogEntry = (typeof DOCUMENT_CATALOG)[number];
+/** ISO 3166-1 alpha-2 codes present in the catalog. */
+type CatalogCountry = DocumentCatalogEntry['country'];
+/** Document type codes present in the catalog. */
+type DocumentType = DocumentCatalogEntry['documentType'];
+/** True when the gateway can process this pair. */
+declare function isSupportedDocumentPair(country: string, documentType: string): boolean;
+/** The countries in the catalog, deduplicated. */
+declare function supportedCountries(): CatalogCountry[];
+/** The document types the catalog supports for `country`. */
+declare function supportedDocumentTypes(country: string): DocumentType[];
+/** The pipeline's state machine, as written by the gateway and its workers. */
+declare const VERIFICATION_STATUSES: readonly ["PENDING", "PROCESSING", "REVIEW", "APPROVED", "REJECTED"];
+type VerificationStatus = (typeof VERIFICATION_STATUSES)[number];
+/**
+ * What a verification *means* operationally, derived by the gateway from the
+ * status and rejection code.
+ *
+ * The distinction that `status` alone cannot make: REJECTED is written both
+ * when the rules genuinely said no and when our own OCR choked on a valid
+ * document. Those want opposite handling — the first is an answer for the end
+ * user, the second is a retry for us.
+ */
+declare const VERIFICATION_OUTCOMES: readonly ["APPROVED", "REJECTED", "FAILED_TECHNICAL", "NEEDS_REVIEW"];
+type VerificationOutcome = (typeof VERIFICATION_OUTCOMES)[number];
+/** Statuses from which the pipeline will not move on its own. */
+declare const TERMINAL_VERIFICATION_STATUSES: readonly ["APPROVED", "REJECTED"];
+/** True when the pipeline has reached a decision for this status. */
+declare function isTerminalStatus(status: string): boolean;
+/** A step the end user has to complete before the pipeline can decide. */
+type VerificationStep = 'document_front' | 'document_back' | 'selfie';
+/** The side of an identity document being uploaded. */
+type DocumentSide = 'front' | 'back';
+/** Files a verification can hold, as named by the gateway's media endpoints. */
+type MediaResource = 'selfie' | 'document-front' | 'document-back' | 'document-face';
 interface StartVerificationParams {
-    /** Type of document to verify (e.g., IDENTITY_CARD, DRIVING_LICENSE) */
-    documentType: 'IDENTITY_CARD' | 'DRIVING_LICENSE';
-    /** Country code (e.g., MZ, AO, PT) */
-    country: string;
-    /** Optional existing identity ID to link verification to */
+    /** Must form a supported pair with `country` (see DOCUMENT_CATALOG). */
+    documentType: DocumentType | (string & {});
+    /** ISO 3166-1 alpha-2 country code. */
+    country: CatalogCountry | (string & {});
+    /** Link to an existing identity instead of creating a new one. */
     identityId?: string;
-    /** Optional external reference ID */
+    /**
+     * Your own reference for this end user.
+     *
+     * Ignored when the client authenticates with a verification token: that token
+     * is already bound to one externalId, and the gateway treats the token's
+     * value as authoritative so a token cannot create a verification under
+     * someone else's reference.
+     */
     externalId?: string;
+    /**
+     * Name of the verification level (policy) to run under. Required.
+     *
+     * The level is what says which documents the project accepts and whether a
+     * selfie is needed, so the gateway has no verification without one: a start
+     * that names no level, or names one that is not active on the project, is
+     * rejected (422 / 404). Levels are created from your backend with
+     * `client.levels.create()` -- a project can verify nobody until it has one.
+     */
+    levelName: string;
 }
-interface FaceMatchVerificationParams {
-    /** The identity ID to perform face match on */
-    identityId: string;
-    /** Base64 encoded image data, data URI, or file:// URI */
-    file: string;
-    /** MIME type of the image (default: image/jpeg) */
-    mimeType?: string;
-}
-interface FaceMatchStatusParams {
-    /** The identity ID to check face match status for */
-    identityId: string;
-    /** The face check ID from the face match verification response */
-    faceCheckId: string;
-    /** Polling interval in milliseconds (default: 3000) */
-    interval?: number;
-    /** Maximum time to wait in milliseconds (default: 120000) */
-    timeout?: number;
-}
-/**
- * Response from starting a verification session
- */
 interface VerificationSession {
-    /** Unique verification ID */
     verificationId: string;
-    /** Linked identity ID (if exists) */
     identityId?: string;
-    /** Current verification status */
-    status: string;
+    status: VerificationStatus;
 }
-/**
- * Parameters for uploading a selfie image
- */
-interface UploadSelfieParams {
-    /** Verification ID to attach the selfie to */
-    verificationId: string;
-    /** Base64 encoded image data, data URI, or file:// URI (React Native) */
-    imageData: string;
-    /** MIME type of the image (default: image/jpeg) */
-    mimeType?: string;
+/** OCR output. Fields present depend on the document; unread fields are null. */
+interface OcrData {
+    country?: string | null;
+    documentType?: string | null;
+    fullName?: string | null;
+    idNumber?: string | null;
+    birthDate?: string | null;
+    validFrom?: string | null;
+    validUntil?: string | null;
+    gender?: string | null;
+    height?: number | null;
+    address?: string | null;
+    mrz?: string | null;
+    maritalStatus?: string | null;
+    [field: string]: unknown;
 }
-/**
- * Parameters for uploading a document image
- */
-interface UploadDocumentParams {
-    /** Verification ID to attach the document to */
+interface VerificationStatusResponse {
     verificationId: string;
-    /** Type of document (front or back) */
-    type: 'front' | 'back';
-    /** Base64 encoded image data, data URI, or file:// URI (React Native) */
-    imageData: string;
-    /** MIME type of the image (default: image/jpeg) */
-    mimeType?: string;
-}
-/** Result of an upload operation */
+    status: VerificationStatus;
+    /** Null while still PENDING/PROCESSING — no outcome exists yet. */
+    outcome: VerificationOutcome | null;
+    /** 0-1 similarity between selfie and document photo; null until computed. */
+    faceMatchScore: number | null;
+    /** Null until the document front has been processed. */
+    ocrData: OcrData | null;
+    /** A gateway ERROR_CODE naming why, when the pipeline stopped or refused. */
+    rejectionType: string | null;
+    rejectionReason: string | null;
+    /** An operator's email, "system", or null. */
+    decidedBy: string | null;
+    decidedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
 interface UploadResult {
-    /** Response message */
     message: string;
-    /** Current status after upload */
-    status: string;
-    /** True when the step was already uploaded and the call was a no-op */
-    skipped?: boolean;
+    status: VerificationStatus;
 }
+/** One row of the operations list. Deliberately free of OCR data and paths. */
+interface VerificationListItem {
+    id: string;
+    externalId: string | null;
+    status: VerificationStatus;
+    outcome: VerificationOutcome | null;
+    /** True when it has sat in flight past the gateway's stall threshold. */
+    stalled: boolean;
+    country: string | null;
+    documentType: string | null;
+    faceMatchScore: number | null;
+    rejectionType: string | null;
+    rejectionReason: string | null;
+    decidedBy: string | null;
+    decidedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ListVerificationsParams {
+    page?: number;
+    /** 1-100; the gateway rejects anything larger. */
+    limit?: number;
+    status?: VerificationStatus[];
+    outcome?: VerificationOutcome;
+    /** Only stalled (true) or only healthy (false). Omit for both. */
+    stalled?: boolean;
+    country?: string;
+    documentType?: string;
+    /** Exact match on your own reference. */
+    externalId?: string;
+    /** ISO 8601 instant. */
+    createdAfter?: string;
+    /** ISO 8601 instant. */
+    createdBefore?: string;
+    order?: 'ASC' | 'DESC';
+}
+interface VerificationSummary {
+    byStatus: Partial<Record<VerificationStatus, number>>;
+    byOutcome: Partial<Record<VerificationOutcome, number>>;
+    needsAttention: {
+        stalled: number;
+        failedTechnical: number;
+        needsReview: number;
+        parkedMessages: number;
+    };
+}
+/** What kind of thing one history entry records. */
+declare const PIPELINE_EVENT_KINDS: readonly ["CREATED", "STATUS_CHANGED", "REPROCESSED", "JOB_PARKED", "JOB_RESENT", "JOB_DISCARDED"];
+type PipelineEventKind = (typeof PIPELINE_EVENT_KINDS)[number];
 /**
- * Parameters for uploading a single verification step in a resume-aware way.
+ * One entry in a verification's history, appended and never updated.
+ *
+ * The verification row keeps only the last decision, so this is the only place
+ * the sequence survives. Entries that predate the history simply do not exist —
+ * a verification from before it shows its creation and last decision and
+ * nothing between.
  */
-interface UploadStepParams {
-    /** The step to upload */
-    step: VerificationStep;
-    /** Base64 encoded image data, data URI, or file:// URI (React Native) */
-    imageData: string;
-    /** Verification ID to attach to; falls back to the persisted session */
-    verificationId?: string;
-    /** Identity ID used to skip already-uploaded steps; falls back to the persisted session */
-    identityId?: string;
-    /** MIME type of the image (default: image/jpeg) */
-    mimeType?: string;
+interface PipelineEvent {
+    id: string;
+    kind: PipelineEventKind | (string & {});
+    fromStatus: string | null;
+    toStatus: string | null;
+    /**
+     * Who did it, as a label frozen at the time — an operator's email, or
+     * "system". A snapshot, so it stays true after the person is renamed or
+     * removed.
+     */
+    actorLabel: string;
+    actorUserId: string | null;
+    /** The one thing worth reading beside the transition. */
+    detail: string | null;
+    createdAt: string;
+    [field: string]: unknown;
 }
-/** Current status of a verification session */
-interface VerificationStatus {
-    /** Verification ID */
-    verificationId: string;
-    /** Current status: PENDING, PROCESSING, APPROVED, or REJECTED */
-    status: 'PENDING' | 'PROCESSING' | 'APPROVED' | 'REJECTED';
-    /** Face match similarity score (0-1) */
-    faceMatchScore?: number;
-    /** OCR extracted data from document */
-    ocrData?: {
-        /** Full name extracted from document */
-        fullName?: string;
-        /** ID number extracted from document */
-        idNumber?: string;
-        /** Birth date extracted from document */
-        birthDate?: string;
-        /** Expiry date extracted from document */
-        expiryDate?: string;
-        /** Additional extracted fields */
-        [key: string]: any;
-    };
-    /** When the verification was created */
+interface ReviewDecision {
+    decision: 'APPROVED' | 'REJECTED';
+    /** Stored when rejecting. */
+    reason?: string;
+}
+interface IdentityDocumentStep {
+    step: 'IDENTITY_DOCUMENT';
+    required: true;
+    documents: {
+        country: string;
+        types: string[];
+    }[];
+}
+interface SelfieStep {
+    step: 'SELFIE';
+    required: boolean;
+    /** Accepted but not enforced by the gateway yet. */
+    liveness?: boolean;
+}
+type VerificationLevelStep = IdentityDocumentStep | SelfieStep;
+interface VerificationLevelDefinition {
+    requiredSteps: VerificationLevelStep[];
+}
+interface VerificationLevel {
+    id: string;
+    name: string;
+    isActive: boolean;
+    definition: VerificationLevelDefinition;
     createdAt: string;
-    /** When the verification was last updated */
     updatedAt: string;
 }
-/** A single verification record as stored under an identity */
-interface VerificationRecord {
-    /** Verification ID */
+interface IdentityFields {
+    mrz?: string;
+    gender?: string;
+    height?: number;
+    address?: string;
+    country?: string;
+    fullName?: string;
+    idNumber?: string;
+    birthDate?: string;
+    maritalStatus?: string;
+}
+interface IdentitySummary extends IdentityFields {
     id: string;
-    /** Current verification status */
-    status: string;
-    /** External reference ID (if provided when starting) */
-    externalId: string | null;
-    /** Type of document being verified */
-    documentType: 'IDENTITY_CARD' | 'DRIVING_LICENSE';
-    /** Country code */
+    createdAt: string;
+    updatedAt: string;
+}
+interface Identity extends IdentitySummary {
+    verifications?: VerificationListItem[];
+    [field: string]: unknown;
+}
+interface ListIdentitiesParams {
+    page?: number;
+    limit?: number;
+    /** Partial match. */
+    fullName?: string;
+    country?: string;
+    idNumber?: string;
+}
+/** Fields the gateway can group duplicate identities by. */
+declare const DUPLICATE_FIELDS: readonly ["fullName", "idNumber", "mrz", "gender", "country", "birthDate"];
+type DuplicateField = (typeof DUPLICATE_FIELDS)[number];
+interface FaceCheck {
+    id: string;
+    status: 'PENDING' | 'APPROVED' | 'REJECTED';
+}
+type OcrProcessStatus = 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED';
+interface OcrProcess {
+    id: string;
+    status: OcrProcessStatus;
+    documentType: string;
     country: string;
-    /** Face match similarity score (0-1) */
-    faceMatchScore: number | null;
-    /** OCR extracted data from document */
-    ocrData: Record<string, any> | null;
-    /** Stored path of the uploaded selfie, or null if not uploaded yet */
-    selfiePath: string | null;
-    /** Stored path of the uploaded document front, or null if not uploaded yet */
-    documentFrontPath: string | null;
-    /** Stored path of the uploaded document back, or null if not uploaded yet */
-    documentBackPath: string | null;
-    /** Stored path of the document face crop, or null if not available */
-    documentFacePath: string | null;
-    /** Reason for rejection, if rejected */
-    rejectionReason: string | null;
-    /** Type of rejection, if rejected */
-    rejectionType: string | null;
-    /** When the verification was created */
     createdAt: string;
-    /** When the verification was last updated */
+}
+interface OcrProcessStatusResponse {
+    id: string;
+    status: OcrProcessStatus;
+    /** Present once COMPLETED. */
+    ocrResult?: OcrData;
+    documentPath?: string;
+    createdAt: string;
     updatedAt: string;
 }
-/** An identity with its associated verifications */
-interface Identity {
-    /** Unique identity ID */
+declare const WEBHOOK_EVENT_TYPES: readonly ["VERIFICATION_STARTED", "VERIFICATION_COMPLETED", "VERIFICATION_APPROVED", "VERIFICATION_REJECTED", "VERIFICATION_REVIEW_REQUIRED", "OCR_COMPLETED", "OCR_FAILED"];
+type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
+/**
+ * Subscribes to every event, including ones added after the endpoint was
+ * registered. Prefer it over listing all seven when the intent is "mirror my
+ * verification lifecycle" — a literal list silently stops being complete.
+ */
+declare const ALL_WEBHOOK_EVENTS = "*";
+type WebhookSubscription = WebhookEventType | typeof ALL_WEBHOOK_EVENTS;
+interface Webhook {
     id: string;
-    /** Verifications linked to this identity */
-    verifications: VerificationRecord[];
-    /** When the identity was created */
+    url: string;
+    eventTypes: WebhookSubscription[];
+    isActive: boolean;
+    headers?: Record<string, string> | null;
+    maxRetries?: number | null;
     createdAt: string;
-    /** When the identity was last updated */
     updatedAt: string;
-    /** Additional OCR / identity fields */
-    [key: string]: any;
 }
-/** A single step a user must complete in a verification flow */
-type VerificationStep = 'selfie' | 'document_front' | 'document_back';
-/** Computed progress of an in-flight verification, used to resume a paused flow */
-interface VerificationProgress {
-    /** Verification ID the progress refers to */
-    verificationId: string;
-    /** Document type for this verification */
-    documentType: 'IDENTITY_CARD' | 'DRIVING_LICENSE';
-    /** Current verification status */
+interface CreateWebhookParams {
+    /** Must be https:// with a public hostname — the gateway refuses anything else. */
+    url: string;
+    eventTypes: WebhookSubscription[];
+    headers?: Record<string, string>;
+    maxRetries?: number;
+}
+interface UpdateWebhookParams {
+    url?: string;
+    /** Replaces the current list entirely. */
+    eventTypes?: WebhookSubscription[];
+    isActive?: boolean;
+    headers?: Record<string, string>;
+    maxRetries?: number;
+}
+/**
+ * The result of replaying a delivery.
+ *
+ * A failed send is a value, not an exception: the gateway records a FAILED row
+ * for the attempt either way, so the caller almost always wants to show why
+ * beside the delivery it belongs to rather than catch around it.
+ */
+type WebhookResendResult = {
+    success: true;
+} | {
+    success: false;
+    error: string;
+};
+interface WebhookLogEntry {
+    id: string;
+    url: string;
     status: string;
-    /** Whether the selfie has already been uploaded */
-    selfieUploaded: boolean;
-    /** Whether the document front has already been uploaded */
-    documentFrontUploaded: boolean;
-    /** Whether the document back has already been uploaded (always false for single-sided docs) */
-    documentBackUploaded: boolean;
-    /** Steps still required to finish, in the order they should be collected */
-    missingSteps: VerificationStep[];
-    /** True when no steps remain to be uploaded */
-    isComplete: boolean;
+    responseStatus?: number | null;
+    responseBody?: string | null;
+    payload?: Record<string, unknown>;
+    headers?: Record<string, string> | null;
+    retries?: number | null;
+    createdAt: string;
+    updatedAt: string;
+    [field: string]: unknown;
 }
-/** Event emitted when KYC status changes */
-interface KYCStatusEvent {
-    /** Type of event: statusChanged or error */
-    type: 'statusChanged' | 'error';
-    /** New status (for statusChanged events) */
-    status?: string;
-    /** Error message (for error events) */
-    error?: string;
+interface AnalyticsSeries {
+    change_percentage: number;
+    /** Keyed by month, e.g. "2026-07". */
+    monthly: Record<string, number>;
+    total: number;
+}
+interface Analytics {
+    identity: AnalyticsSeries;
+    verification: AnalyticsSeries;
+}
+
+/** Monthly identity and verification counts, with month-over-month change. */
+declare class AnalyticsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    get(options?: {
+        signal?: AbortSignal;
+    }): Promise<Analytics>;
+}
+
+interface PollOptions {
+    /** Delay between attempts, in ms. Defaults to 3000. */
+    intervalMs?: number;
+    /** Give up after this long, in ms. Defaults to 120000. */
+    timeoutMs?: number;
+    /** Cancels the poll; the promise rejects with code ABORTED. */
+    signal?: AbortSignal;
+}
+interface PollCallbacks<T> {
+    /** Called with every intermediate value, before the done check. */
+    onUpdate?: (value: T) => void;
 }
-/** Callback function for handling KYC status events */
-type KYCEventCallback = (event: KYCStatusEvent) => void;
 /**
- * Custom error class for KYC SDK errors
+ * Calls `fetchOnce` until `isDone` accepts the result, the timeout elapses, or
+ * the caller aborts.
+ *
+ * Written as a loop with an awaited delay rather than a self-scheduling
+ * setTimeout so that a cancelled poll actually stops: the previous
+ * implementation left a pending timer behind after rejecting, which in React
+ * Native keeps the JS context awake and warns about a setState on an unmounted
+ * component.
+ *
+ * The timeout is checked before sleeping as well as after, so a poll never
+ * waits out one final interval it has no time left to use.
  */
-declare class KYCSdkError extends Error {
-    /** Error code for programmatic error handling */
-    code: string;
-    /** HTTP status code if available */
-    statusCode?: number;
+declare function pollUntil<T>(fetchOnce: (signal?: AbortSignal) => Promise<T>, isDone: (value: T) => boolean, options?: PollOptions & PollCallbacks<T>, description?: string): Promise<T>;
+
+interface DuplicateGroup {
+    value: string;
+    count: number;
+    identities: IdentitySummary[];
+}
+interface DuplicatesByField {
+    field: string;
+    totalDuplicateGroups: number;
+    totalDuplicateIdentities: number;
+    duplicates: DuplicateGroup[];
+}
+interface DuplicatesByFields {
+    fields: string[];
+    results: Record<string, DuplicatesByField>;
+}
+/**
+ * The identity records behind verifications — the person, as opposed to any
+ * one attempt to verify them.
+ *
+ * Every endpoint here needs the project API key. A verification token is
+ * scoped to a single end user's flow and is refused, which is deliberate: an
+ * identity record holds the full extracted document data, and a client app has
+ * no business reading the project's identities.
+ */
+declare class IdentitiesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Registers an identity independently of any verification. */
+    create(fields: IdentityFields, options?: {
+        signal?: AbortSignal;
+    }): Promise<Identity>;
+    /** A page of identity summaries. Read one identity for the full record. */
+    list(params?: ListIdentitiesParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<Page<IdentitySummary>>;
+    /** The full record, including its verification history. */
+    get(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Identity>;
+    /** This identity's verifications, without embeddings or storage paths. */
+    verifications(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<VerificationListItem[]>;
+    update(id: string, fields: IdentityFields, options?: {
+        signal?: AbortSignal;
+    }): Promise<Identity>;
+    /** Deletes the identity, its verifications, and the stored images. */
+    delete(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
     /**
-     * Creates a new KYC SDK error
-     * @param message Human-readable error message
-     * @param code Error code for handling
-     * @param statusCode Optional HTTP status code
+     * Groups identities that share a value, to find duplicate registrations.
+     *
+     * Passing one field returns a single grouping; passing several returns one
+     * per field, which is why the return type is a union.
+     */
+    findDuplicates(params?: {
+        field?: DuplicateField | DuplicateField[];
+        id?: string;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<DuplicatesByField | DuplicatesByFields>;
+    /**
+     * Folds duplicates into a primary identity, moving their verifications
+     * across and deleting them. Requires the admin role on a user token; an API
+     * key is a project credential and carries no role.
      */
-    constructor(message: string, code: string, statusCode?: number);
+    merge(id: string, duplicateIds: string[], options?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+    /**
+     * Compares a fresh photo against the face already on file for an identity —
+     * a re-authentication check, separate from the verification flow.
+     *
+     * Asynchronous: the returned check starts PENDING. Poll it with
+     * `faceCheckStatus`, or use `waitForFaceCheck`.
+     */
+    faceMatch(id: string, file: FileInput, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<FaceCheck>;
+    /** The result of a face-match check started with `faceMatch`. */
+    faceCheckStatus(id: string, faceCheckId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<FaceCheck>;
+    /** Polls a face-match check until it is APPROVED or REJECTED. */
+    waitForFaceCheck(id: string, faceCheckId: string, options?: PollOptions & PollCallbacks<FaceCheck>): Promise<FaceCheck>;
+}
+
+interface CreateLevelParams {
+    /** Unique within the project. */
+    name: string;
+    definition: VerificationLevelDefinition;
+    isActive?: boolean;
+}
+interface UpdateLevelParams {
+    name?: string;
+    /** Replaces the required steps entirely. */
+    definition?: VerificationLevelDefinition;
+    isActive?: boolean;
+}
+/**
+ * Verification levels: named, reusable policies saying which steps a
+ * verification requires and which documents it accepts.
+ *
+ * Every verification names one at start time (`levelName`), and there is no
+ * default: a project can verify nobody until it has at least one active level,
+ * and a definition must include an IDENTITY_DOCUMENT step saying which
+ * (country, documentType) pairs it accepts.
+ *
+ * API key only, and creating or changing one needs the admin role when acting
+ * as a user. Deleting is a soft delete, so verifications that already ran keep
+ * the rules they ran under.
+ */
+declare class LevelsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    create(params: CreateLevelParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<VerificationLevel>;
+    list(options?: {
+        signal?: AbortSignal;
+    }): Promise<VerificationLevel[]>;
+    get(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<VerificationLevel>;
+    update(id: string, params: UpdateLevelParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<VerificationLevel>;
+    delete(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+
+interface DownloadToken {
+    token: string;
+    /** Lifetime in seconds. The gateway fixes it at 60. */
+    expiresIn: number;
 }
 /**
- * Core KYC SDK client for interacting with the verification API
+ * Access to the images behind a verification: the selfie, both document pages,
+ * and the face the OCR worker cropped out of the document.
+ *
+ * Downloads are two calls on purpose. The first, authenticated with the project
+ * API key, issues a token for exactly one file; the second exchanges it for the
+ * bytes. The token lives 60 seconds, is invalidated the first time it is used,
+ * and every use is written to the gateway's media access log — so an image URL
+ * that leaks into a browser history, a screenshot or a support ticket is worth
+ * nothing by the time anyone finds it.
  */
-declare class KYCCore {
-    private client;
-    private credentials;
-    private eventCallbacks;
-    private storage?;
-    /** Storage key under which the active verification session is persisted */
-    private static readonly SESSION_KEY;
+declare class MediaResourceApi {
+    private readonly http;
+    constructor(http: HttpClient);
     /**
-     * Creates a new KYC Core instance
-     * @param credentials API credentials (apiKey, baseUrl, and optional storage)
+     * Issues a single-use, 60-second token for one file of one verification.
+     *
+     * Useful on its own when the bytes should be fetched somewhere else — hand
+     * the token to a browser and let it call the download URL directly, without
+     * the API key ever leaving your server.
      */
-    constructor(credentials: KYCCredentials);
+    createDownloadToken(verificationId: string, resource: MediaResource, options?: {
+        signal?: AbortSignal;
+    }): Promise<DownloadToken>;
     /**
-     * Persists the active verification session via the injected storage adapter.
-     * No-op when no storage was provided.
+     * The URL that exchanges a download token for the file.
+     *
+     * Treat it as a credential: the token is the whole authorization, so the URL
+     * grants the image to whoever holds it, once.
      */
-    private saveSession;
+    downloadUrl(token: string): string;
     /**
-     * Reads the persisted verification session, or null if none exists or no
-     * storage adapter was provided.
+     * Fetches a file, taking care of both steps.
+     *
+     * Returns the raw Response so a caller can stream it (to disk, or straight
+     * into an HTTP response) instead of holding an identity document in memory.
      */
-    getSession(): Promise<KYCSession | null>;
+    download(verificationId: string, resource: MediaResource, options?: {
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    /** Fetches a file and buffers it. Convenient; holds the image in memory. */
+    downloadBytes(verificationId: string, resource: MediaResource, options?: {
+        signal?: AbortSignal;
+    }): Promise<Uint8Array>;
+}
+
+interface RunOcrParams {
+    documentType: DocumentType | (string & {});
+    country: CatalogCountry | (string & {});
+    /** Your own reference, for correlating the result. */
+    externalId?: string;
+}
+/**
+ * Standalone document reading, with no verification attached.
+ *
+ * The same OCR pipeline the verification flow uses, addressed directly: upload
+ * a document, get the structured fields back. Nothing is decided and no
+ * identity is created — for that, run a verification.
+ */
+declare class OcrResource {
+    private readonly http;
+    constructor(http: HttpClient);
     /**
-     * Clears the persisted verification session. Call this once a verification is
-     * fully complete so the next flow starts fresh.
+     * Queues a document for extraction.
+     *
+     * Returns as soon as the job is accepted; the fields arrive later, via
+     * `getStatus` or `waitForResult`.
      */
-    clearSession(): Promise<void>;
+    run(file: FileInput, params: RunOcrParams, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<OcrProcess>;
+    /** Status of a queued job, with the extracted fields once COMPLETED. */
+    getStatus(ocrId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<OcrProcessStatusResponse>;
+    /** Polls until the job is COMPLETED or FAILED. */
+    waitForResult(ocrId: string, options?: PollOptions & PollCallbacks<OcrProcessStatusResponse>): Promise<OcrProcessStatusResponse>;
+}
+
+/**
+ * Pluggable key/value storage, so a verification that was interrupted can be
+ * picked up again after the app is closed.
+ *
+ * Inject AsyncStorage on React Native, or an adapter around localStorage on
+ * web. Methods may be synchronous or asynchronous; results are awaited either
+ * way.
+ */
+interface KycirisStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+/** Versioned, so a future change of shape cannot read an old record wrongly. */
+declare const SESSION_STORAGE_KEY = "kyciris:session:v1";
+/**
+ * What the SDK remembers about an in-flight verification.
+ *
+ * Deliberately holds no credential. The verification token is a bearer
+ * credential for one end user and persisting it would leave it in
+ * AsyncStorage/localStorage long after the flow ended, readable by anything
+ * else in the app; the host application decides where — and whether — to keep
+ * it. Only identifiers live here, and all of them are already known to the
+ * client that fetched them.
+ */
+interface StoredSession {
+    verificationId: string;
+    identityId?: string;
+    externalId?: string;
+    documentType?: DocumentType | (string & {});
+    country?: CatalogCountry | (string & {});
+    levelName?: string;
+    /** ISO 8601 instant the verification was started. */
+    startedAt: string;
+}
+/**
+ * Reads and writes the resumable session.
+ *
+ * Every operation is best-effort: storage can be full, disabled (Safari private
+ * browsing), or simply absent. Losing the ability to resume is a degraded flow;
+ * throwing here would break a verification that is otherwise proceeding fine.
+ */
+declare class SessionStore {
+    private readonly storage?;
+    constructor(storage?: KycirisStorage | undefined);
+    /** True when a storage adapter was configured. */
+    get enabled(): boolean;
+    save(session: StoredSession): Promise<void>;
+    read(): Promise<StoredSession | null>;
+    clear(): Promise<void>;
+}
+/**
+ * A storage adapter backed by a plain Map.
+ *
+ * For tests, and for a flow that should not outlive the process.
+ */
+declare function createMemoryStorage(): KycirisStorage;
+
+interface VerificationToken {
+    token: string;
+    /** The lifetime the gateway chose, e.g. "8h". The caller does not pick it. */
+    expiresIn: string;
+}
+interface AvailableMedia {
+    available: MediaResource[];
+}
+interface UploadOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+interface VerificationProgress {
+    verificationId: string;
+    status: VerificationStatusResponse['status'];
+    outcome: VerificationStatusResponse['outcome'];
+    uploaded: Record<VerificationStep, boolean>;
+    /** The steps still to collect, in the order they should be asked for. */
+    missingSteps: VerificationStep[];
+    /** True when nothing is left to upload. */
+    isComplete: boolean;
+}
+interface ProgressOptions {
     /**
-     * Registers a callback for KYC status events
-     * @param callback Function to call when status changes
-     * @returns Unsubscribe function to remove the callback
+     * Whether the flow asks for a selfie. Defaults to true, matching the
+     * gateway's own default when no verification level is set.
+     *
+     * A client authenticated with a verification token cannot read the level it
+     * is running under — `/verification-levels` needs the project API key — so
+     * when a level makes the selfie optional, say so here.
      */
-    onEvent(callback: KYCEventCallback): () => void;
+    selfieRequired?: boolean;
+    signal?: AbortSignal;
+}
+interface UploadStepParams {
+    step: VerificationStep;
+    file: FileInput;
+    /** Defaults to the stored session's verification. */
+    verificationId?: string;
+    /** See ProgressOptions.selfieRequired. */
+    selfieRequired?: boolean;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+interface UploadStepResult extends UploadResult {
+    /** True when the step was already uploaded and nothing was sent. */
+    skipped: boolean;
+}
+interface WaitForResultOptions extends PollOptions, PollCallbacks<VerificationStatusResponse> {
     /**
-     * Emits a status event to all registered callbacks
-     * @param event The event to emit
+     * Whether REVIEW ends the wait. Defaults to true.
+     *
+     * REVIEW means the automated pipeline has finished and handed the
+     * verification to a person, which can take hours. Polling through it almost
+     * always ends in POLL_TIMEOUT; subscribe to the VERIFICATION_APPROVED /
+     * VERIFICATION_REJECTED webhooks for the human's decision instead.
      */
-    private emitEvent;
+    stopOnReview?: boolean;
+}
+/**
+ * The end-user verification flow, plus the review and operations endpoints
+ * that sit behind the project API key.
+ *
+ * Everything up to and including `getStatus` works with either credential; the
+ * list, summary, history and decision calls are API-key only and say so.
+ */
+declare class VerificationsResource {
+    private readonly http;
+    private readonly session;
+    constructor(http: HttpClient, session: SessionStore);
     /**
-     * Creates a verification token for secure API access
-     * @param externalId External reference ID
-     * @param expiry Token expiry in hours (default: 3)
-     * @returns Object containing the token and its expiration time
+     * Mints a verification token for one end user.
+     *
+     * Call this on **your server**, with the project API key, and hand the token
+     * to the client app. The token authorizes exactly the flow below (start,
+     * upload, status) for the given `externalId` and nothing else, which is what
+     * keeps the project-wide API key out of a bundle an end user can read.
+     *
+     * The gateway owns the lifetime (VERIFICATION_TOKEN_TTL, 8h by default) — a
+     * client cannot ask for a longer one.
+     *
+     * @param externalId Your own reference for the end user
      */
-    createVerificationToken(externalId: string, expiry?: string): Promise<{
-        token: string;
-        expiresIn: string;
-    }>;
+    createToken(externalId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<VerificationToken>;
     /**
-     * Starts a new verification session
-     * @param params Parameters including documentType, country, identityId, and externalId
-     * @returns Verification session with verificationId and status
+     * Starts a verification and, when a storage adapter is configured, records
+     * it so an interrupted flow can be resumed.
+     *
+     * The (country, documentType) pair and the level name are checked here before
+     * the request goes out: the gateway rejects an unsupported pair with a 422
+     * that names neither what is supported nor why, and a missing level with a
+     * validation error that reads like a typo in your code rather than a policy
+     * you have not created yet.
      */
-    startVerification(params: StartVerificationParams): Promise<VerificationSession>;
+    start(params: StartVerificationParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<VerificationSession>;
+    /** Uploads the end user's selfie. Triggers face matching once OCR has run. */
+    uploadSelfie(verificationId: string, file: FileInput, options?: UploadOptions): Promise<UploadResult>;
     /**
-     * Uploads a selfie image for face verification
-     * @param params Parameters including verificationId, imageData, and optional mimeType
-     * @returns Upload result with status
+     * Uploads one side of the identity document.
+     *
+     * OCR is queued once both sides are present, so a flow that collects only
+     * the front never starts processing.
      */
-    uploadSelfie(params: UploadSelfieParams): Promise<UploadResult>;
+    uploadDocument(verificationId: string, side: DocumentSide, file: FileInput, options?: UploadOptions): Promise<UploadResult>;
+    /** Current status, face-match score and extracted document data. */
+    getStatus(verificationId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<VerificationStatusResponse>;
     /**
-     * Uploads a document image (front or back)
-     * @param params Parameters including verificationId, type, imageData, and optional mimeType
-     * @returns Upload result with status
+     * Which files exist for a verification.
+     *
+     * This is the credential-safe way to tell what an end user has already
+     * uploaded: it works with a verification token, whereas the identity record
+     * that used to serve the same purpose is API-key only.
      */
-    uploadDocument(params: UploadDocumentParams): Promise<UploadResult>;
+    listMedia(verificationId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<MediaResource[]>;
     /**
-     * Gets the current status of a verification session
-     * @param verificationId The verification ID to check
-     * @returns Current verification status including OCR data and face match score
+     * Re-runs OCR and face matching from the files already uploaded.
+     *
+     * The remedy for a verification that failed technically (outcome
+     * FAILED_TECHNICAL) or stalled. Clears the previous extraction and decision,
+     * so it is not a read-only operation.
+     *
+     * Only the document front is required, which is why this also works for a
+     * verification that never got as far as the selfie.
      */
-    getStatus(verificationId: string): Promise<VerificationStatus>;
+    reanalyze(verificationId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<UploadResult>;
+    /** The stored session, or null when there is none. */
+    getSession(): Promise<StoredSession | null>;
     /**
-     * Fetches an identity along with all of its verification records.
-     * @param identityId The identity ID to fetch
-     * @returns The identity, including the verifications array with upload paths
+     * Forgets the stored session. Call it once a verification is finished, so
+     * the next one starts clean.
      */
-    getIdentity(identityId: string): Promise<Identity>;
+    clearSession(): Promise<void>;
     /**
-     * Returns the required steps for a given document type, in collection order.
-     * ID cards require both sides; driving licenses are single-sided.
+     * What the end user has uploaded and what is still missing.
+     *
+     * Derived from the files that actually exist server-side rather than from
+     * anything the client remembers, so it is correct after a reinstall, on a
+     * second device, or when a previous attempt failed mid-upload.
      */
-    private getRequiredSteps;
+    getProgress(verificationId?: string, options?: ProgressOptions): Promise<VerificationProgress>;
     /**
-     * Computes which steps a user has already completed and which are still missing
-     * for a verification, so a paused flow can be resumed without re-uploading.
+     * Uploads one step, skipping it when the file is already there.
      *
-     * Both arguments are optional: when omitted they fall back to the persisted
-     * session (see the storage adapter). Pass a verificationId to target a specific
-     * verification; otherwise the most recently updated verification is used.
+     * The call a resumable UI should make: it never re-sends a step the end user
+     * already completed, which matters most on a retry after a dropped
+     * connection, where the upload may well have succeeded.
+     */
+    uploadStep(params: UploadStepParams): Promise<UploadStepResult>;
+    /**
+     * Polls the status until the verification is decided.
      *
-     * @param identityId Identity ID owning the verification (defaults to the session)
-     * @param verificationId Verification ID to target (defaults to the session)
-     * @returns Progress describing uploaded steps and the steps still required
+     * Stops at APPROVED, REJECTED and — unless `stopOnReview` is false — REVIEW.
+     * For anything longer than a user is willing to watch a spinner, use the
+     * webhooks: polling burns a request every few seconds and still gives up
+     * after `timeoutMs`.
      */
-    getVerificationProgress(identityId?: string, verificationId?: string): Promise<VerificationProgress>;
+    waitForResult(verificationId?: string, options?: WaitForResultOptions): Promise<VerificationStatusResponse>;
+    private resolveVerificationId;
     /**
-     * Returns whether every required step of a verification has already been
-     * uploaded (both document sides where applicable, plus the selfie).
+     * A page of the project's verifications, newest first.
      *
-     * This is the reliable way to tell a user who has fully submitted their
-     * documents (verification is now processing on the KYC backend) apart from one
-     * who paused mid-flow with steps still missing — both look "PENDING" from the
-     * outside. Derived purely from the identity's verification records.
+     * Carries no OCR data or storage paths by design — a 20-row page is not the
+     * place for identity-document PII. Read one verification for those.
+     */
+    list(params?: ListVerificationsParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<Page<VerificationListItem>>;
+    /** Counts per status and outcome, plus what needs an operator's attention. */
+    summary(options?: {
+        signal?: AbortSignal;
+    }): Promise<VerificationSummary>;
+    /**
+     * A verification's recorded history, oldest first.
      *
-     * Returns `false` (rather than throwing) when the identity has no verification
-     * records yet, so callers can treat "nothing uploaded" as "documents missing".
+     * The verification row keeps only the last decision, so this is the only
+     * place the sequence survives.
+     */
+    events(verificationId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<PipelineEvent[]>;
+    /** Moves a PENDING verification to REVIEW so a person can look at it. */
+    sendToReview(verificationId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        verificationId: string;
+        status: string;
+        message?: string;
+    }>;
+    /**
+     * Records a reviewer's decision and fires the matching webhook.
      *
-     * @param identityId Identity ID owning the verification (defaults to the session)
-     * @param verificationId Verification ID to target (defaults to the most recently updated)
-     * @returns True when no steps remain to be uploaded
+     * Repeating the decision a verification already has is refused with 409 —
+     * that is the gateway making a second webhook impossible, not a transient
+     * failure. Changing a decision (rejected in error, then approved) is allowed.
+     */
+    decide(verificationId: string, decision: ReviewDecision, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        verificationId: string;
+        status: string;
+    }>;
+}
+
+/**
+ * Where the gateway sends verification events.
+ *
+ * Webhooks are the right way to learn a verification's outcome: polling costs
+ * a request every few seconds and still gives up, while a REVIEW can sit with
+ * a human for hours. Subscribe with `["*"]` when the intent is "mirror my
+ * verification lifecycle" — a literal list of today's events silently stops
+ * being complete the day an eighth one exists.
+ *
+ * The URL must be https with a public hostname; the gateway refuses anything
+ * else, localhost included.
+ */
+declare class WebhooksResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    create(params: CreateWebhookParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<Webhook>;
+    list(options?: {
+        signal?: AbortSignal;
+    }): Promise<Webhook[]>;
+    get(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Webhook>;
+    update(id: string, params: UpdateWebhookParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<Webhook>;
+    delete(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Delivery attempts, newest first — what was sent, what came back, how many
+     * retries it took. The place to look when an endpoint stops receiving events.
      */
-    hasAllDocuments(identityId?: string, verificationId?: string): Promise<boolean>;
+    logs(params?: {
+        page?: number;
+        limit?: number;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<Page<WebhookLogEntry>>;
+    /** One delivery attempt. */
+    log(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<WebhookLogEntry>;
     /**
-     * Uploads a single verification step (selfie, document front, or document back)
-     * in a resume-aware way: it resolves the verification from the persisted session
-     * when not given, and skips the upload if that step is already complete.
+     * Sends a recorded delivery again, to the endpoint it originally went to.
      *
-     * @param params The step, image data, and optional verification/identity overrides
-     * @returns The upload result; `skipped` is true when the step was already uploaded
+     * Synchronous: the result says whether it arrived this time. A failure comes
+     * back as `{ success: false, error }` rather than throwing, because the
+     * gateway has already written a FAILED row either way and the caller usually
+     * wants to show the reason beside the delivery it belongs to. A missing
+     * delivery (404) or a deleted endpoint (409) still throw -- those are not
+     * outcomes of the send.
+     *
+     * Not retried: a resend that timed out may well have arrived.
      */
-    uploadStep(params: UploadStepParams): Promise<UploadResult>;
-    faceMatchVerification(params: FaceMatchVerificationParams): Promise<any>;
-    faceMatchStatus({ identityId, faceCheckId, interval, timeout, }: FaceMatchStatusParams): Promise<VerificationStatus>;
+    resendLog(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<WebhookResendResult>;
+}
+
+interface KycirisClientConfig extends HttpClientConfig {
     /**
-     * Polls for verification status until completion or timeout
-     * @param verificationId The verification ID to check
-     * @param interval Polling interval in milliseconds (default: 3000)
-     * @param timeout Maximum time to wait in milliseconds (default: 120000)
-     * @returns Final verification status when approved or rejected
+     * Where to remember an in-flight verification, so a flow interrupted by the
+     * app closing can be resumed. AsyncStorage on React Native, an adapter around
+     * localStorage on web. No credential is ever written to it.
      */
-    pollStatus(verificationId: string, interval?: number, timeout?: number): Promise<VerificationStatus>;
+    storage?: KycirisStorage;
+}
+/**
+ * The KYCiris API client.
+ *
+ * Two credentials, two audiences:
+ *
+ * - **`apiKey`** is the project's key. It reaches every endpoint, including
+ *   every identity in the project, and belongs on your server only.
+ * - **`verificationToken`** is scoped to one end user and authorizes exactly
+ *   the verification flow. Mint it on your server with
+ *   `verifications.createToken(externalId)` and hand it to the client app.
+ *
+ * Constructing a client with `apiKey` inside a browser or React Native app
+ * throws, because a key in a shipped bundle is a key the end user has.
+ *
+ * ```ts
+ * // Your server
+ * const server = createKycirisClient({ baseUrl, apiKey: process.env.KYCIRIS_API_KEY });
+ * const { token } = await server.verifications.createToken('user-123');
+ *
+ * // Your app, with that token
+ * const client = createKycirisClient({ baseUrl, verificationToken: token, storage });
+ * const { verificationId } = await client.verifications.start({
+ *   country: 'AO',
+ *   documentType: 'ID_CARD',
+ * });
+ * ```
+ */
+declare class KycirisClient {
+    /** The end-user flow, plus review and operations reads. */
+    readonly verifications: VerificationsResource;
+    /** Identity records and re-authentication face checks. API key only. */
+    readonly identities: IdentitiesResource;
+    /** Verification levels (step policies). API key only. */
+    readonly levels: LevelsResource;
+    /** Single-use downloads of verification images. API key only. */
+    readonly media: MediaResourceApi;
+    /** Standalone document reading, outside the verification flow. */
+    readonly ocr: OcrResource;
+    /** Event subscriptions and their delivery log. API key only. */
+    readonly webhooks: WebhooksResource;
+    /** Monthly counts. API key only. */
+    readonly analytics: AnalyticsResource;
+    private readonly http;
+    constructor(config: KycirisClientConfig);
+    /**
+     * Whether this client holds the project API key, and so can reach the
+     * server-side endpoints.
+     *
+     * Worth checking in code that runs in both places, rather than letting a
+     * MISSING_CREDENTIAL error be the way you find out.
+     */
+    get isServerSide(): boolean;
+}
+/** Creates a KYCiris client. See {@link KycirisClient}. */
+declare function createKycirisClient(config: KycirisClientConfig): KycirisClient;
+
+/**
+ * Every error the SDK throws is a KycirisError, so a caller can branch on
+ * `code` instead of parsing messages.
+ *
+ * Codes come from two places. Gateway codes are the `error.code` value in the
+ * API's error envelope (`{ error: { code, message, details }, meta }`) and are
+ * kept in step with the gateway's own ERROR_CODE enum. SDK codes are raised
+ * client-side, before or instead of a request.
+ */
+/**
+ * Error codes produced by the gateway itself.
+ *
+ * Mirrors `ERROR_CODE` in kyc-gateway (src/common/enums/error-codes.ts). Codes
+ * the SDK does not recognise are still surfaced verbatim on `KycirisError.code`
+ * — the list is for autocomplete and exhaustiveness, not for filtering.
+ */
+declare const GATEWAY_ERROR_CODES: readonly ["INVALID_OCR_DATA", "OCR_EXTRACTION_ERROR", "DOCUMENT_EXPIRED", "INVALID_DOCUMENT_QUALITY", "FACE_MISMATCH", "LOW_FACE_MATCH_SCORE", "NO_FACE", "MANUAL_REJECTION", "BAD_PAYLOAD", "UNSUPPORTED_DOCUMENT", "BAD_IMAGE", "ACCOUNT_SUSPENDED", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "RESOURCE_ALREADY_EXISTS", "RATE_LIMIT_EXCEEDED", "INTERNAL_SERVER_ERROR"];
+type GatewayErrorCode = (typeof GATEWAY_ERROR_CODES)[number];
+/** Error codes raised by the SDK without (or before) a gateway response. */
+declare const SDK_ERROR_CODES: readonly ["CONFIG_ERROR", "CREDENTIAL_MISUSE", "MISSING_CREDENTIAL", "NETWORK_ERROR", "TIMEOUT", "ABORTED", "INVALID_RESPONSE", "INVALID_FILE", "POLL_TIMEOUT", "SESSION_NOT_FOUND"];
+type SdkErrorCode = (typeof SDK_ERROR_CODES)[number];
+/** Any code that can land on a KycirisError. Open-ended by design. */
+type KycirisErrorCode = GatewayErrorCode | SdkErrorCode | (string & {});
+interface KycirisErrorInit {
+    code: KycirisErrorCode;
+    /** HTTP status, when the error came from a response. */
+    status?: number;
+    /** `meta.requestId` from the response envelope — quote it in bug reports. */
+    requestId?: string;
+    /** `error.details` from the envelope, e.g. per-field validation failures. */
+    details?: unknown;
+    /** Whether retrying the same request could plausibly succeed. */
+    retryable?: boolean;
+    /** The underlying error, when this one wraps a lower-level failure. */
+    cause?: unknown;
+}
+/**
+ * The single error type the SDK throws.
+ *
+ * It deliberately carries no request/response objects: those hold the
+ * Authorization and X-API-Key headers, and an error is the thing most likely to
+ * be logged verbatim or shipped to an error tracker.
+ */
+declare class KycirisError extends Error {
+    readonly name = "KycirisError";
+    readonly code: KycirisErrorCode;
+    readonly status?: number;
+    readonly requestId?: string;
+    readonly details?: unknown;
+    readonly retryable: boolean;
+    constructor(message: string, init: KycirisErrorInit);
+    /** True when this is a KycirisError, across bundle/realm boundaries. */
+    static isKycirisError(value: unknown): value is KycirisError;
+}
+/** Convenience guard, equivalent to `KycirisError.isKycirisError`. */
+declare function isKycirisError(value: unknown): value is KycirisError;
+/**
+ * HTTP statuses worth retrying: the request either never ran (429) or failed
+ * for a reason that is plausibly momentary.
+ */
+declare function isRetryableStatus(status: number): boolean;
+
+/** Where the end user is in the flow. */
+type FlowPhase = 
+/** Nothing started yet. */
+'idle'
+/** Creating the verification. */
+ | 'starting'
+/** Waiting for the user to supply the current step's image. */
+ | 'collecting'
+/** Uploading an image. */
+ | 'uploading'
+/** Everything submitted; the pipeline is deciding. */
+ | 'processing'
+/** A decision was reached, or a human was asked for one. */
+ | 'finished'
+/** The flow stopped on an error. `error` says which. */
+ | 'failed';
+interface FlowState {
+    phase: FlowPhase;
+    verificationId: string | null;
+    /** The step to ask the user for now, or null when none is outstanding. */
+    currentStep: VerificationStep | null;
+    /** Every step still to collect, in order. */
+    missingSteps: VerificationStep[];
+    uploaded: Record<VerificationStep, boolean>;
+    status: VerificationStatus | null;
+    outcome: VerificationOutcome | null;
+    /** Why the pipeline stopped, when it did. */
+    rejectionReason: string | null;
+    error: KycirisError | null;
+    /** True while a request is in flight, for disabling a capture button. */
+    busy: boolean;
+}
+interface FlowOptions {
+    country: CatalogCountry | (string & {});
+    documentType: DocumentType | (string & {});
+    /** Verification level to run under. Required: the gateway has no default. */
+    levelName: string;
+    /** Your reference for the user. Ignored when a verification token is used. */
+    externalId?: string;
     /**
-     * Static factory method to create a KYC client instance
-     * @param credentials API credentials (apiKey and baseUrl)
-     * @returns Configured KYCCore instance
+     * Whether the level asks for a selfie. Defaults to true.
+     *
+     * A client holding a verification token cannot read its own level, so a
+     * document-only level has to be declared here.
      */
-    static createClient(credentials: KYCCredentials): KYCCore;
+    selfieRequired?: boolean;
+    /** Poll for the decision once everything is uploaded. Defaults to true. */
+    waitForDecision?: boolean;
+    /** How long to poll before giving up, in ms. Defaults to 120000. */
+    decisionTimeoutMs?: number;
+    /** Called on every state change. */
+    onStateChange?: (state: FlowState) => void;
 }
 /**
- * Factory function to create a KYC client instance
- * @param credentials API credentials (apiKey and baseUrl)
- * @returns Configured KYCCore instance
+ * The end-user verification flow as a state machine, with no UI attached.
+ *
+ * The React Native and web components are both thin wrappers around this, so
+ * the sequencing — which step comes next, what a resumed flow skips, when the
+ * decision is polled for — is written and tested once.
+ *
+ * Every transition is observable through `subscribe`, and every method is safe
+ * to call from a button handler: failures land in `state.error` rather than
+ * rejecting, so a component never has to wrap calls in try/catch.
+ *
+ * ```ts
+ * const flow = new VerificationFlow(client, { country: 'AO', documentType: 'ID_CARD' });
+ * flow.subscribe(render);
+ * await flow.start();
+ * // then, per captured image:
+ * await flow.submit(image);
+ * ```
  */
-declare function createKYCClient(credentials: KYCCredentials): KYCCore;
+declare class VerificationFlow {
+    private readonly client;
+    private readonly options;
+    private state;
+    private listeners;
+    private aborter;
+    constructor(client: KycirisClient, options: FlowOptions);
+    getState(): FlowState;
+    /** Observes state changes. Returns an unsubscribe function. */
+    subscribe(listener: (state: FlowState) => void): () => void;
+    /**
+     * Starts a verification, or picks up the one already in storage.
+     *
+     * Resuming is the default because it is almost always what the user wants:
+     * an app killed between the document and the selfie should carry on, not
+     * ask for the document again. Pass `{ fresh: true }` to start over.
+     */
+    start(options?: {
+        fresh?: boolean;
+    }): Promise<FlowState>;
+    /**
+     * Re-reads what the gateway holds.
+     *
+     * Worth calling when a component remounts, or after an upload whose response
+     * never arrived: the file may well have landed, and this is what notices.
+     */
+    refresh(): Promise<FlowState>;
+    /**
+     * Uploads an image for the current step and advances.
+     *
+     * A step that turns out to be already uploaded is skipped rather than sent
+     * again, so retrying after a dropped connection cannot duplicate work.
+     */
+    submit(file: FileInput): Promise<FlowState>;
+    /**
+     * Waits for the pipeline's decision.
+     *
+     * Called automatically once the last step is uploaded, unless
+     * `waitForDecision` is false. Stops at REVIEW, which is a person's queue and
+     * not something worth holding a spinner for.
+     */
+    waitForDecision(): Promise<FlowState>;
+    /**
+     * Cancels whatever is in flight.
+     *
+     * A component's unmount should call this, so a poll does not keep running
+     * against a screen that is gone.
+     */
+    cancel(): void;
+    /** Cancels, forgets the stored session, and returns to `idle`. */
+    reset(): Promise<FlowState>;
+    /**
+     * Reads progress and derives the next phase from it.
+     *
+     * Returns a patch rather than applying one, so `guard` stays the single
+     * place that publishes a state change.
+     */
+    private loadProgress;
+    /**
+     * Runs one transition: marks the flow busy, applies the resulting patch, and
+     * turns any failure into `state.error` instead of a rejected promise.
+     *
+     * The awkward part it exists to contain is that reaching `processing` should
+     * flow straight on into polling — but only when the caller asked for it, and
+     * only once.
+     */
+    private guard;
+    private fail;
+    private patch;
+}
 
-export { type FaceMatchStatusParams, type FaceMatchVerificationParams, type Identity, KYCCore, type KYCCredentials, type KYCEventCallback, KYCSdkError, type KYCSession, type KYCStatusEvent, type KYCStorage, type StartVerificationParams, type UploadDocumentParams, type UploadResult, type UploadSelfieParams, type UploadStepParams, type VerificationProgress, type VerificationRecord, type VerificationSession, type VerificationStatus, type VerificationStep, createKYCClient };
+export { ALL_WEBHOOK_EVENTS, type Analytics, AnalyticsResource, type AnalyticsSeries, type ApiMeta, type ApiResult, type AuthMode, type AvailableMedia, type CatalogCountry, type CreateLevelParams, type CreateWebhookParams, DOCUMENT_CATALOG, DUPLICATE_FIELDS, type DocumentCatalogEntry, type DocumentSide, type DocumentType, type DownloadToken, type DuplicateField, type DuplicateGroup, type DuplicatesByField, type DuplicatesByFields, type FaceCheck, type FetchLike, type FileInput, type FlowOptions, type FlowPhase, type FlowState, GATEWAY_ERROR_CODES, type GatewayErrorCode, HttpClient, type HttpClientConfig, IdentitiesResource, type Identity, type IdentityDocumentStep, type IdentityFields, type IdentitySummary, type ImageMimeType, KycirisClient, type KycirisClientConfig, KycirisError, type KycirisErrorCode, type KycirisErrorInit, type KycirisStorage, LevelsResource, type ListIdentitiesParams, type ListVerificationsParams, MAX_IMAGE_FILE_SIZE, type MediaResource, MediaResourceApi, type NormalizedFile, type OcrData, type OcrProcess, type OcrProcessStatus, type OcrProcessStatusResponse, OcrResource, PIPELINE_EVENT_KINDS, type Page, type PaginationMeta, type PipelineEvent, type PipelineEventKind, type PollCallbacks, type PollOptions, type ProgressOptions, type RequestOptions, type ReviewDecision, type RunOcrParams, SDK_ERROR_CODES, SESSION_STORAGE_KEY, type SdkErrorCode, type SelfieStep, SessionStore, type StartVerificationParams, type StoredSession, TERMINAL_VERIFICATION_STATUSES, type UpdateLevelParams, type UpdateWebhookParams, type UploadOptions, type UploadResult, type UploadStepParams, type UploadStepResult, VERIFICATION_OUTCOMES, VERIFICATION_STATUSES, VerificationFlow, type VerificationLevel, type VerificationLevelDefinition, type VerificationLevelStep, type VerificationListItem, type VerificationOutcome, type VerificationProgress, type VerificationSession, type VerificationStatus, type VerificationStatusResponse, type VerificationStep, type VerificationSummary, type VerificationToken, type VerificationTokenProvider, VerificationsResource, WEBHOOK_EVENT_TYPES, type WaitForResultOptions, type Webhook, type WebhookEventType, type WebhookLogEntry, type WebhookResendResult, type WebhookSubscription, WebhooksResource, createKycirisClient, createMemoryStorage, decodeBase64, detectImageMimeType, encodeBase64, isKycirisError, isNormalizedFile, isReactNative, isRetryableStatus, isSupportedDocumentPair, isTerminalStatus, isUntrustedClient, normalizeFile, pollUntil, prepareFile, supportedCountries, supportedDocumentTypes, toPage };