@kyciris/core 0.1.1 → 1.0.0

package/dist/index.js

@@ -1,518 +1,1990 @@
 'use strict';
 
-var axios = require('axios');
-
-function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
-
-var axios__default = /*#__PURE__*/_interopDefault(axios);
-
-// src/index.ts
-var KYCSdkError = class extends Error {
-  /**
-   * Creates a new KYC SDK error
-   * @param message Human-readable error message
-   * @param code Error code for handling
-   * @param statusCode Optional HTTP status code
-   */
-  constructor(message, code, statusCode) {
+// src/errors.ts
+var GATEWAY_ERROR_CODES = [
+  // OCR processing
+  "INVALID_OCR_DATA",
+  "OCR_EXTRACTION_ERROR",
+  // Document validation
+  "DOCUMENT_EXPIRED",
+  "INVALID_DOCUMENT_QUALITY",
+  // Face matching
+  "FACE_MISMATCH",
+  "LOW_FACE_MATCH_SCORE",
+  "NO_FACE",
+  // Manual review
+  "MANUAL_REJECTION",
+  // Worker terminal failures
+  "BAD_PAYLOAD",
+  "UNSUPPORTED_DOCUMENT",
+  "BAD_IMAGE",
+  // Account status
+  "ACCOUNT_SUSPENDED",
+  // Generic HTTP labels
+  "VALIDATION_ERROR",
+  "UNAUTHORIZED",
+  "FORBIDDEN",
+  "NOT_FOUND",
+  "RESOURCE_ALREADY_EXISTS",
+  "RATE_LIMIT_EXCEEDED",
+  "INTERNAL_SERVER_ERROR"
+];
+var SDK_ERROR_CODES = [
+  /** The client was constructed with an unusable configuration. */
+  "CONFIG_ERROR",
+  /** A project API key was about to be sent from a browser or React Native app. */
+  "CREDENTIAL_MISUSE",
+  /** The endpoint needs a credential the client was not given. */
+  "MISSING_CREDENTIAL",
+  /** The request never reached the gateway (DNS, TLS, offline, CORS). */
+  "NETWORK_ERROR",
+  /** The request exceeded `timeoutMs`. */
+  "TIMEOUT",
+  /** An AbortSignal supplied by the caller fired. */
+  "ABORTED",
+  /** A 2xx response whose body was not the documented envelope. */
+  "INVALID_RESPONSE",
+  /** A file argument could not be turned into an upload on this platform. */
+  "INVALID_FILE",
+  /** Polling ran past its own timeout without reaching a final state. */
+  "POLL_TIMEOUT",
+  /** No verification session was found in storage to resume from. */
+  "SESSION_NOT_FOUND"
+];
+var KycirisError = class _KycirisError extends Error {
+  constructor(message, init) {
     super(message);
-    this.name = "KYCSdkError";
-    this.code = code;
-    this.statusCode = statusCode;
+    this.name = "KycirisError";
+    if (init.cause !== void 0) {
+      this.cause = init.cause;
+    }
+    this.code = init.code;
+    this.status = init.status;
+    this.requestId = init.requestId;
+    this.details = init.details;
+    this.retryable = init.retryable ?? false;
+    Object.setPrototypeOf(this, _KycirisError.prototype);
+  }
+  /** True when this is a KycirisError, across bundle/realm boundaries. */
+  static isKycirisError(value) {
+    return value instanceof _KycirisError || typeof value === "object" && value !== null && value.name === "KycirisError" && typeof value.code === "string";
   }
 };
-var _KYCCore = class _KYCCore {
-  /**
-   * Creates a new KYC Core instance
-   * @param credentials API credentials (apiKey, baseUrl, and optional storage)
-   */
-  constructor(credentials) {
-    this.eventCallbacks = [];
-    this.credentials = credentials;
-    this.storage = credentials.storage;
-    this.client = axios__default.default.create({
-      baseURL: credentials.baseUrl,
-      headers: {
-        "Content-Type": "application/json",
-        Accept: "application/json"
-      }
+function isKycirisError(value) {
+  return KycirisError.isKycirisError(value);
+}
+function isRetryableStatus(status) {
+  return status === 408 || status === 429 || status >= 500 && status <= 599;
+}
+
+// src/files.ts
+var MAX_IMAGE_FILE_SIZE = 8 * 1024 * 1024;
+var NORMALIZED = /* @__PURE__ */ Symbol.for("kyciris.normalizedFile");
+function mark(file) {
+  Object.defineProperty(file, NORMALIZED, { value: true, enumerable: false });
+  return file;
+}
+function isNormalizedFile(value) {
+  return typeof value === "object" && value !== null && value[NORMALIZED] === true;
+}
+function isReactNative() {
+  return typeof navigator !== "undefined" && navigator.product === "ReactNative";
+}
+var JPEG_MAGIC = [255, 216, 255];
+var PNG_MAGIC = [137, 80, 78, 71, 13, 10, 26, 10];
+function startsWith(bytes, magic) {
+  if (bytes.length < magic.length) return false;
+  return magic.every((byte, index) => bytes[index] === byte);
+}
+function detectImageMimeType(bytes) {
+  if (bytes.length < 8) return null;
+  if (startsWith(bytes, JPEG_MAGIC)) return "image/jpeg";
+  if (startsWith(bytes, PNG_MAGIC)) return "image/png";
+  return null;
+}
+var BASE64_ALPHABET = /^[A-Za-z0-9+/]+={0,2}$/;
+function decodeBase64(input) {
+  const normalized = input.replace(/\s/g, "");
+  const maybeBuffer = globalThis.Buffer;
+  if (maybeBuffer) {
+    const buffer = maybeBuffer.from(normalized, "base64");
+    return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+  }
+  if (typeof atob === "function") {
+    const binary = atob(normalized);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+  }
+  throw new KycirisError(
+    "This runtime has neither Buffer nor atob, so base64 image data cannot be decoded. Pass a Blob or raw bytes instead.",
+    { code: "INVALID_FILE" }
+  );
+}
+function toBytes(data) {
+  return data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}
+function isPlatformUri(value) {
+  return /^(file|content|ph|assets-library):/i.test(value);
+}
+var DATA_URI_RE = /^data:([^;,]*)(;[^,]*)?,(.*)$/s;
+function parseDataUri(value) {
+  const match = DATA_URI_RE.exec(value);
+  if (!match) {
+    throw new KycirisError("Malformed data: URI.", { code: "INVALID_FILE" });
+  }
+  const [, declaredType, parameters, payload] = match;
+  const isBase64 = (parameters ?? "").toLowerCase().includes("base64");
+  let bytes;
+  if (isBase64) {
+    bytes = decodeBase64(payload);
+  } else {
+    try {
+      bytes = new TextEncoder().encode(decodeURIComponent(payload));
+    } catch (cause) {
+      throw new KycirisError(
+        "Malformed percent-encoding in a data: URI. Image data should be base64-encoded (data:image/jpeg;base64,...) \u2014 percent-encoding is UTF-8 and cannot carry arbitrary bytes.",
+        { code: "INVALID_FILE", cause }
+      );
+    }
+  }
+  return { mimeType: declaredType || "application/octet-stream", bytes };
+}
+function assertBlobSize(blob, filename) {
+  if (blob.size === 0) {
+    throw new KycirisError(`${filename} is empty.`, { code: "INVALID_FILE" });
+  }
+  if (blob.size > MAX_IMAGE_FILE_SIZE) {
+    throw new KycirisError(
+      `${filename} is ${(blob.size / 1024 / 1024).toFixed(1)}MB; the gateway accepts at most ${MAX_IMAGE_FILE_SIZE / 1024 / 1024}MB. Re-encode at a lower quality before uploading.`,
+      { code: "INVALID_FILE" }
+    );
+  }
+}
+function assertUsableImage(bytes, filename) {
+  if (bytes.length === 0) {
+    throw new KycirisError(`${filename} is empty.`, { code: "INVALID_FILE" });
+  }
+  if (bytes.length > MAX_IMAGE_FILE_SIZE) {
+    throw new KycirisError(
+      `${filename} is ${(bytes.length / 1024 / 1024).toFixed(1)}MB; the gateway accepts at most ${MAX_IMAGE_FILE_SIZE / 1024 / 1024}MB. Re-encode at a lower quality before uploading.`,
+      { code: "INVALID_FILE" }
+    );
+  }
+  const mimeType = detectImageMimeType(bytes);
+  if (!mimeType) {
+    throw new KycirisError(
+      `${filename} is not a JPEG or PNG image. The gateway decides the type from the file's own bytes, not its name or Content-Type.`,
+      { code: "INVALID_FILE" }
+    );
+  }
+  return mimeType;
+}
+function bytesToValue(bytes, mimeType, filename) {
+  if (isReactNative()) {
+    const base64 = encodeBase64(bytes);
+    return mark({
+      value: { uri: `data:${mimeType};base64,${base64}`, name: filename, type: mimeType },
+      filename,
+      mimeType
     });
-    this.client.interceptors.request.use((config) => {
-      config.headers["x-api-key"] = this.credentials.apiKey;
-      return config;
+  }
+  if (typeof Blob === "undefined") {
+    throw new KycirisError(
+      "This runtime has no Blob, so image bytes cannot be turned into an upload. Node 18+ is required.",
+      { code: "INVALID_FILE" }
+    );
+  }
+  const copy = new Uint8Array(bytes.byteLength);
+  copy.set(bytes);
+  return mark({ value: new Blob([copy], { type: mimeType }), filename, mimeType });
+}
+function encodeBase64(bytes) {
+  const maybeBuffer = globalThis.Buffer;
+  if (maybeBuffer) {
+    return maybeBuffer.from(bytes).toString("base64");
+  }
+  if (typeof btoa === "function") {
+    let binary = "";
+    const CHUNK = 32768;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+      binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    return btoa(binary);
+  }
+  throw new KycirisError(
+    "This runtime has neither Buffer nor btoa, so image bytes cannot be base64-encoded.",
+    { code: "INVALID_FILE" }
+  );
+}
+function normalizeFile(input, defaultName) {
+  if (input == null) {
+    throw new KycirisError(`No image was given for ${defaultName}.`, {
+      code: "INVALID_FILE"
     });
   }
-  /**
-   * Persists the active verification session via the injected storage adapter.
-   * No-op when no storage was provided.
-   */
-  async saveSession(session) {
-    if (!this.storage) return;
-    try {
-      await this.storage.setItem(_KYCCore.SESSION_KEY, JSON.stringify(session));
-    } catch {
+  if (isNormalizedFile(input)) return input;
+  if (typeof Blob !== "undefined" && input instanceof Blob) {
+    assertBlobSize(input, defaultName);
+    const filename = input.name || defaultName;
+    return mark({ value: input, filename, mimeType: input.type || "image/jpeg" });
+  }
+  if (typeof input === "string") {
+    if (input.startsWith("data:")) {
+      const { bytes: bytes2 } = parseDataUri(input);
+      const mimeType2 = assertUsableImage(bytes2, defaultName);
+      return bytesToValue(bytes2, mimeType2, defaultName);
     }
+    if (isPlatformUri(input)) {
+      if (!isReactNative()) {
+        throw new KycirisError(
+          `${defaultName} was given as "${input.slice(0, 12)}\u2026", a URI only React Native can read. Read the file yourself and pass a Blob or its bytes.`,
+          { code: "INVALID_FILE" }
+        );
+      }
+      return mark({
+        value: { uri: input, name: defaultName, type: "image/jpeg" },
+        filename: defaultName,
+        mimeType: "image/jpeg"
+      });
+    }
+    const trimmed = input.replace(/\s/g, "");
+    if (!trimmed || !BASE64_ALPHABET.test(trimmed)) {
+      throw new KycirisError(
+        `${defaultName} was given as a string that is neither a data: URI, a file URI, nor base64.`,
+        { code: "INVALID_FILE" }
+      );
+    }
+    const bytes = decodeBase64(trimmed);
+    const mimeType = assertUsableImage(bytes, defaultName);
+    return bytesToValue(bytes, mimeType, defaultName);
   }
-  /**
-   * Reads the persisted verification session, or null if none exists or no
-   * storage adapter was provided.
-   */
-  async getSession() {
-    if (!this.storage) return null;
+  if ("uri" in input && typeof input.uri === "string") {
+    if (input.uri.startsWith("data:")) {
+      const { bytes } = parseDataUri(input.uri);
+      const mimeType2 = assertUsableImage(bytes, input.name ?? defaultName);
+      return bytesToValue(bytes, mimeType2, input.name ?? defaultName);
+    }
+    if (!isReactNative()) {
+      throw new KycirisError(
+        `${defaultName} was given as a { uri } object, which only React Native can read. Read the file yourself and pass a Blob or its bytes.`,
+        { code: "INVALID_FILE" }
+      );
+    }
+    const filename = input.name ?? defaultName;
+    const mimeType = input.type ?? "image/jpeg";
+    return mark({ value: { uri: input.uri, name: filename, type: mimeType }, filename, mimeType });
+  }
+  if ("data" in input && input.data) {
+    const bytes = toBytes(input.data);
+    const filename = input.name ?? defaultName;
+    const mimeType = assertUsableImage(bytes, filename);
+    return bytesToValue(bytes, mimeType, filename);
+  }
+  throw new KycirisError(
+    `${defaultName} is not a Blob, a { uri } object, a { data } object, or a base64/data: string.`,
+    { code: "INVALID_FILE" }
+  );
+}
+async function readBlobHead(blob) {
+  const head = blob.slice(0, 8);
+  if (typeof head.arrayBuffer === "function") {
     try {
-      const raw = await this.storage.getItem(_KYCCore.SESSION_KEY);
-      return raw ? JSON.parse(raw) : null;
+      return new Uint8Array(await head.arrayBuffer());
     } catch {
       return null;
     }
   }
-  /**
-   * Clears the persisted verification session. Call this once a verification is
-   * fully complete so the next flow starts fresh.
-   */
-  async clearSession() {
-    if (!this.storage) return;
+  if (typeof FileReader === "undefined") return null;
+  return new Promise((resolve) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result instanceof ArrayBuffer ? new Uint8Array(reader.result) : null);
+    reader.onerror = () => resolve(null);
+    reader.onabort = () => resolve(null);
     try {
-      await this.storage.removeItem(_KYCCore.SESSION_KEY);
+      reader.readAsArrayBuffer(head);
     } catch {
+      resolve(null);
+    }
+  });
+}
+async function prepareFile(input, defaultName) {
+  if (isNormalizedFile(input)) return input;
+  if (typeof Blob !== "undefined" && input instanceof Blob) {
+    assertBlobSize(input, defaultName);
+    const filename = input.name || defaultName;
+    const head = await readBlobHead(input);
+    if (!head) {
+      return mark({ value: input, filename, mimeType: input.type || "image/jpeg" });
+    }
+    const mimeType = detectImageMimeType(head);
+    if (!mimeType) {
+      throw new KycirisError(
+        `${filename} is not a JPEG or PNG image. The gateway decides the type from the file's own bytes, not its name or Content-Type.`,
+        { code: "INVALID_FILE" }
+      );
     }
+    return mark({ value: input, filename, mimeType });
   }
-  /**
-   * Registers a callback for KYC status events
-   * @param callback Function to call when status changes
-   * @returns Unsubscribe function to remove the callback
-   */
-  onEvent(callback) {
-    this.eventCallbacks.push(callback);
-    return () => {
-      this.eventCallbacks = this.eventCallbacks.filter((cb) => cb !== callback);
+  return normalizeFile(input, defaultName);
+}
+
+// src/http/envelope.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function readMeta(body) {
+  if (!isRecord(body) || !isRecord(body.meta)) return void 0;
+  const { requestId, timestamp, version } = body.meta;
+  if (typeof requestId !== "string") return void 0;
+  return {
+    requestId,
+    timestamp: typeof timestamp === "string" ? timestamp : "",
+    version: typeof version === "string" ? version : ""
+  };
+}
+function readRequestId(body) {
+  return readMeta(body)?.requestId;
+}
+function unwrapEnvelope(body, requestPath) {
+  const meta = readMeta(body);
+  if (!isRecord(body) || !("data" in body) || !meta) {
+    throw new KycirisError(
+      `The response to ${requestPath} was not a KYCiris API envelope. Check that baseUrl points at the gateway and that nothing is rewriting responses in between.`,
+      { code: "INVALID_RESPONSE" }
+    );
+  }
+  const result = { data: body.data, meta };
+  if (isRecord(body.pagination)) {
+    const { page, limit, total } = body.pagination;
+    if (typeof page === "number" && typeof limit === "number" && typeof total === "number") {
+      result.pagination = { page, limit, total };
+    }
+  }
+  return result;
+}
+function toPage(result) {
+  const items = Array.isArray(result.data) ? result.data : [];
+  return {
+    items,
+    pagination: result.pagination ?? {
+      page: 1,
+      limit: items.length,
+      total: items.length
+    }
+  };
+}
+function readErrorEnvelope(body) {
+  if (!isRecord(body)) {
+    return typeof body === "string" && body.trim() ? { message: body.trim() } : {};
+  }
+  const error = isRecord(body.error) ? body.error : void 0;
+  if (error) {
+    return {
+      code: typeof error.code === "string" ? error.code : void 0,
+      message: typeof error.message === "string" ? error.message : void 0,
+      details: error.details
     };
   }
-  /**
-   * Emits a status event to all registered callbacks
-   * @param event The event to emit
-   */
-  emitEvent(event) {
-    this.eventCallbacks.forEach((callback) => callback(event));
+  const message = body.message;
+  return {
+    message: Array.isArray(message) ? message.join(", ") : typeof message === "string" ? message : void 0
+  };
+}
+
+// src/http/client.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_MAX_RETRIES = 2;
+var BASE_BACKOFF_MS = 300;
+var MAX_BACKOFF_MS = 5e3;
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1", "[::1]", "0.0.0.0"]);
+function isUntrustedClient() {
+  if (typeof navigator !== "undefined" && navigator.product === "ReactNative") {
+    return true;
   }
-  /**
-   * 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
-   */
-  async createVerificationToken(externalId, expiry = "3") {
-    try {
-      const response = await this.client.post("/verification/token", {
-        externalId,
-        expiry
-      });
-      return response.data;
-    } catch (error) {
-      const message = error.response?.data?.message || error.message || "Failed to create verification token";
-      throw new KYCSdkError(message, "TOKEN_CREATE_FAILED", error.response?.status);
+  if (typeof window !== "undefined" && typeof window.document !== "undefined") {
+    return true;
+  }
+  const scope = globalThis;
+  if (typeof scope.importScripts === "function") return true;
+  return /WorkerGlobalScope$/.test(scope.constructor?.name ?? "");
+}
+function assertUsableBaseUrl(baseUrl, allowInsecure) {
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw new KycirisError(
+      `baseUrl "${baseUrl}" is not a valid URL. Expected something like https://api.kyciris.com.`,
+      { code: "CONFIG_ERROR" }
+    );
+  }
+  if (url.protocol === "https:") return url;
+  if (url.protocol !== "http:") {
+    throw new KycirisError(`baseUrl must be http:// or https://, not ${url.protocol}`, {
+      code: "CONFIG_ERROR"
+    });
+  }
+  if (LOOPBACK_HOSTS.has(url.hostname) || allowInsecure) return url;
+  throw new KycirisError(
+    `baseUrl "${baseUrl}" is plaintext http to a remote host. API keys, verification tokens and identity-document data would travel unencrypted. Use https, or set allowInsecureBaseUrl if this is a trusted private network.`,
+    { code: "CONFIG_ERROR" }
+  );
+}
+function parseRetryAfter(header) {
+  if (!header) return void 0;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+  const date = Date.parse(header);
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  return void 0;
+}
+function backoffDelay(attempt) {
+  const ceiling = Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** attempt);
+  return Math.random() * ceiling;
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new KycirisError("The request was aborted.", { code: "ABORTED" }));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(new KycirisError("The request was aborted.", { code: "ABORTED" }));
     }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+var HttpClient = class {
+  constructor(config) {
+    this.baseUrl = assertUsableBaseUrl(
+      config.baseUrl,
+      config.allowInsecureBaseUrl ?? false
+    );
+    if (!config.apiKey && !config.verificationToken) {
+      throw new KycirisError(
+        "Provide either apiKey (server-side) or verificationToken (client-side) when creating the client.",
+        { code: "CONFIG_ERROR" }
+      );
+    }
+    if (config.apiKey && isUntrustedClient() && !config.allowApiKeyInUntrustedClient) {
+      throw new KycirisError(
+        "A project API key must not be used from a browser or React Native app: it is readable by anyone who has the bundle and grants access to every identity in the project. Mint a verification token on your server (POST /verification/token) and pass it as verificationToken instead.",
+        { code: "CREDENTIAL_MISUSE" }
+      );
+    }
+    this.apiKey = config.apiKey;
+    this.tokenSource = config.verificationToken;
+    this.apiVersion = (config.apiVersion ?? "v1").replace(/^\/+|\/+$/g, "");
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.maxRetries = Math.max(0, config.maxRetries ?? DEFAULT_MAX_RETRIES);
+    this.extraHeaders = { ...config.headers };
+    const fetchImpl = config.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+      throw new KycirisError(
+        "No global fetch was found. Use Node 18+, or pass a fetch implementation as `fetch`.",
+        { code: "CONFIG_ERROR" }
+      );
+    }
+    this.fetchImpl = fetchImpl;
   }
-  /**
-   * Starts a new verification session
-   * @param params Parameters including documentType, country, identityId, and externalId
-   * @returns Verification session with verificationId and status
-   */
-  async startVerification(params) {
-    try {
-      const response = await this.client.post("/verification/start", params);
-      const session = response.data;
-      if (session.identityId && session.verificationId) {
-        await this.saveSession({
-          identityId: session.identityId,
-          verificationId: session.verificationId,
-          externalId: params.externalId,
-          documentType: params.documentType
-        });
+  /** True when the client holds a project API key. */
+  hasApiKey() {
+    return Boolean(this.apiKey);
+  }
+  /** True when the client holds (or can fetch) a verification token. */
+  hasVerificationToken() {
+    return Boolean(this.tokenSource);
+  }
+  buildUrl(path, query) {
+    const basePath = this.baseUrl.pathname.replace(/\/+$/, "");
+    const url = new URL(this.baseUrl.toString());
+    url.pathname = `${basePath}/${this.apiVersion}${path.startsWith("/") ? path : `/${path}`}`;
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value === void 0 || value === null) continue;
+        if (Array.isArray(value)) {
+          for (const entry of value) {
+            if (entry !== void 0 && entry !== null) {
+              url.searchParams.append(key, String(entry));
+            }
+          }
+        } else {
+          url.searchParams.append(key, String(value));
+        }
       }
-      this.emitEvent({
-        type: "statusChanged",
-        status: "PENDING"
-      });
-      return response.data;
-    } catch (error) {
-      const message = error.response?.data?.message || error.message || "Failed to start verification";
-      throw new KYCSdkError(message, "VERIFICATION_START_FAILED", error.response?.status);
     }
+    return url.toString();
   }
-  /**
-   * Uploads a selfie image for face verification
-   * @param params Parameters including verificationId, imageData, and optional mimeType
-   * @returns Upload result with status
-   */
-  async uploadSelfie(params) {
-    try {
-      const formData = new FormData();
-      formData.append("verificationId", params.verificationId);
-      const mimeType = params.mimeType || "image/jpeg";
-      const imageData = params.imageData;
-      if (imageData.startsWith("file://")) {
-        formData.append("file", {
-          uri: imageData,
-          type: mimeType,
-          name: "selfie.jpg"
-        });
-      } else if (imageData.startsWith("data:")) {
-        formData.append("file", {
-          uri: imageData,
-          type: mimeType,
-          name: "selfie.jpg"
-        });
+  async authHeaders(mode) {
+    if (mode === "none") return {};
+    if (mode === "api-key") {
+      if (!this.apiKey) {
+        throw new KycirisError(
+          "This endpoint requires the project API key, which is a server-side credential. A verification token is scoped to one end user and is refused here.",
+          { code: "MISSING_CREDENTIAL", status: 401 }
+        );
+      }
+      return { "X-API-Key": this.apiKey };
+    }
+    const token = await this.resolveToken();
+    if (mode === "token") {
+      if (!token) {
+        throw new KycirisError(
+          "This endpoint requires a verification token. Mint one with client.verifications.createToken(externalId) using the project API key.",
+          { code: "MISSING_CREDENTIAL", status: 401 }
+        );
+      }
+      return { "x-verification-token": token };
+    }
+    if (token) return { "x-verification-token": token };
+    if (this.apiKey) return { "X-API-Key": this.apiKey };
+    throw new KycirisError("No credential is configured for this request.", {
+      code: "MISSING_CREDENTIAL",
+      status: 401
+    });
+  }
+  async resolveToken() {
+    if (!this.tokenSource) return void 0;
+    if (typeof this.tokenSource === "string") return this.tokenSource;
+    const token = await this.tokenSource();
+    if (typeof token !== "string" || !token) {
+      throw new KycirisError(
+        "The verificationToken provider returned no token.",
+        { code: "MISSING_CREDENTIAL", status: 401 }
+      );
+    }
+    return token;
+  }
+  async buildForm(form, fileFields) {
+    if (typeof FormData === "undefined") {
+      throw new KycirisError(
+        "This runtime has no FormData, so files cannot be uploaded. Node 18+ is required.",
+        { code: "CONFIG_ERROR" }
+      );
+    }
+    const formData = new FormData();
+    for (const [field, value] of Object.entries(form)) {
+      if (value === void 0) continue;
+      if (fileFields.includes(field)) {
+        const file = await prepareFile(value, `${field}.jpg`);
+        formData.append(field, file.value, file.filename);
       } else {
-        formData.append("file", {
-          uri: `data:${mimeType};base64,${imageData}`,
-          type: mimeType,
-          name: "selfie.jpg"
+        formData.append(field, String(value));
+      }
+    }
+    return formData;
+  }
+  /** Runs a request, retrying where the method and failure allow it. */
+  async request(options) {
+    const method = options.method ?? "GET";
+    const url = this.buildUrl(options.path, options.query);
+    const idempotent = options.retry ?? method === "GET";
+    const formData = options.form ? await this.buildForm(options.form, options.fileFields ?? []) : void 0;
+    let attempt = 0;
+    for (; ; ) {
+      try {
+        return await this.attempt(options, method, url, formData);
+      } catch (error) {
+        const failure = error;
+        const canRetry = attempt < this.maxRetries && KycirisError.isKycirisError(failure) && failure.retryable && // A rate-limited request never ran, so repeating it is safe whatever
+        // the method. Everything else is only repeated when the caller says
+        // the call can be made twice.
+        (idempotent || failure.status === 429);
+        if (!canRetry) throw error;
+        const delay2 = failure.status === 429 && failure.details ? failure.details.retryAfterMs ?? backoffDelay(attempt) : backoffDelay(attempt);
+        await sleep(delay2, options.signal);
+        attempt += 1;
+      }
+    }
+  }
+  async attempt(options, method, url, formData) {
+    if (options.signal?.aborted) {
+      throw new KycirisError("The request was aborted.", { code: "ABORTED" });
+    }
+    const controller = new AbortController();
+    const timeoutMs = options.timeoutMs ?? this.timeoutMs;
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const onCallerAbort = () => controller.abort();
+    options.signal?.addEventListener("abort", onCallerAbort, { once: true });
+    try {
+      const headers = {
+        Accept: "application/json",
+        ...this.extraHeaders,
+        ...await this.authHeaders(options.auth ?? "any")
+      };
+      let body;
+      if (formData) {
+        body = formData;
+      } else if (options.body !== void 0) {
+        headers["Content-Type"] = "application/json";
+        body = JSON.stringify(options.body);
+      }
+      let response;
+      try {
+        response = await this.fetchImpl(url, {
+          method,
+          headers,
+          body,
+          signal: controller.signal
         });
+      } catch (cause) {
+        if (options.signal?.aborted) {
+          throw new KycirisError("The request was aborted.", {
+            code: "ABORTED",
+            cause
+          });
+        }
+        if (controller.signal.aborted) {
+          throw new KycirisError(
+            `The request to ${options.path} timed out after ${timeoutMs}ms.`,
+            { code: "TIMEOUT", retryable: true, cause }
+          );
+        }
+        throw new KycirisError(
+          `The request to ${options.path} could not reach the gateway. Check connectivity, the baseUrl, and (in a browser) that this origin is in the gateway's ALLOWED_ORIGINS.`,
+          { code: "NETWORK_ERROR", retryable: true, cause }
+        );
       }
-      const response = await this.client.post("/verification/upload/selfie", formData, {
-        headers: { "Content-Type": "multipart/form-data" }
-      });
-      this.emitEvent({
-        type: "statusChanged",
-        status: "PROCESSING"
-      });
-      return response.data;
-    } catch (error) {
-      console.log("Upload selfie error:", error.response?.data || error.message);
-      const message = error.response?.data?.message || error.message || "Failed to upload selfie";
-      throw new KYCSdkError(message, "SELFIE_UPLOAD_FAILED", error.response?.status);
+      const payload = await readBody(response);
+      if (!response.ok) {
+        throw toApiError(response, payload, options.path);
+      }
+      if (response.status === 204 || payload === void 0) {
+        return {
+          data: void 0,
+          meta: {
+            requestId: response.headers.get("x-request-id") ?? "",
+            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+            version: ""
+          }
+        };
+      }
+      return unwrapEnvelope(payload, options.path);
+    } finally {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onCallerAbort);
     }
   }
   /**
-   * Uploads a document image (front or back)
-   * @param params Parameters including verificationId, type, imageData, and optional mimeType
-   * @returns Upload result with status
+   * Streams a response body instead of parsing it — the media download
+   * endpoint returns an image, not an envelope.
    */
-  async uploadDocument(params) {
+  async requestRaw(options) {
+    if (options.signal?.aborted) {
+      throw new KycirisError("The request was aborted.", { code: "ABORTED" });
+    }
+    const url = this.buildUrl(options.path, options.query);
+    const controller = new AbortController();
+    const timeoutMs = options.timeoutMs ?? this.timeoutMs;
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const onCallerAbort = () => controller.abort();
+    options.signal?.addEventListener("abort", onCallerAbort, { once: true });
     try {
-      const formData = new FormData();
-      formData.append("verificationId", params.verificationId);
-      formData.append("type", params.type);
-      const mimeType = params.mimeType || "image/jpeg";
-      const imageData = params.imageData;
-      if (imageData.startsWith("file://")) {
-        formData.append("file", {
-          uri: imageData,
-          type: mimeType,
-          name: `${params.type}.jpg`
-        });
-      } else if (imageData.startsWith("data:")) {
-        formData.append("file", {
-          uri: imageData,
-          type: mimeType,
-          name: `${params.type}.jpg`
-        });
-      } else {
-        formData.append("file", {
-          uri: `data:${mimeType};base64,${imageData}`,
-          type: mimeType,
-          name: `${params.type}.jpg`
+      const headers = {
+        ...this.extraHeaders,
+        ...await this.authHeaders(options.auth ?? "any")
+      };
+      let response;
+      try {
+        response = await this.fetchImpl(url, {
+          method: options.method ?? "GET",
+          headers,
+          signal: controller.signal
         });
+      } catch (cause) {
+        if (options.signal?.aborted) {
+          throw new KycirisError("The request was aborted.", { code: "ABORTED", cause });
+        }
+        if (controller.signal.aborted) {
+          throw new KycirisError(
+            `The request to ${options.path} timed out after ${timeoutMs}ms.`,
+            { code: "TIMEOUT", retryable: true, cause }
+          );
+        }
+        throw new KycirisError(
+          `The request to ${options.path} could not reach the gateway.`,
+          { code: "NETWORK_ERROR", retryable: true, cause }
+        );
       }
-      const response = await this.client.post("/verification/upload/document", formData, {
-        headers: { "Content-Type": "multipart/form-data" }
-      });
-      this.emitEvent({
-        type: "statusChanged",
-        status: "PROCESSING"
-      });
-      return response.data;
-    } catch (error) {
-      console.log("Upload document error:", error.response?.data || error.message);
-      const message = error.response?.data?.message || error.message || "Failed to upload document";
-      throw new KYCSdkError(message, "DOCUMENT_UPLOAD_FAILED", error.response?.status);
+      if (!response.ok) {
+        throw toApiError(response, await readBody(response), options.path);
+      }
+      return response;
+    } finally {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onCallerAbort);
     }
   }
-  /**
-   * 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
-   */
-  async getStatus(verificationId) {
+};
+async function readBody(response) {
+  const contentType = response.headers.get("content-type") ?? "";
+  try {
+    if (contentType.includes("application/json")) {
+      return await response.json();
+    }
+    const text = await response.text();
+    if (!text) return void 0;
     try {
-      const response = await this.client.get(`/verification/status/${verificationId}`);
-      this.emitEvent({
-        type: "statusChanged",
-        status: response.data.status
-      });
-      return response.data;
-    } catch (error) {
-      const message = error.response?.data?.message || error.message || "Failed to get verification status";
-      throw new KYCSdkError(message, "STATUS_CHECK_FAILED", error.response?.status);
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  } catch {
+    return void 0;
+  }
+}
+function toApiError(response, payload, path) {
+  const { code, message, details } = readErrorEnvelope(payload);
+  const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
+  const fallback = response.status === 401 ? "The credential was rejected. Check the API key, or mint a fresh verification token \u2014 they expire." : response.status === 403 ? "The gateway refused this request." : `The gateway returned ${response.status} for ${path}.`;
+  return new KycirisError(message || fallback, {
+    code: code ?? statusFallbackCode(response.status),
+    status: response.status,
+    requestId: readRequestId(payload) ?? response.headers.get("x-request-id") ?? void 0,
+    details: retryAfterMs !== void 0 ? { ...typeof details === "object" && details ? details : { details }, retryAfterMs } : details,
+    retryable: isRetryableStatus(response.status)
+  });
+}
+function statusFallbackCode(status) {
+  switch (status) {
+    case 400:
+    case 422:
+      return "VALIDATION_ERROR";
+    case 401:
+      return "UNAUTHORIZED";
+    case 403:
+      return "FORBIDDEN";
+    case 404:
+      return "NOT_FOUND";
+    case 409:
+      return "RESOURCE_ALREADY_EXISTS";
+    case 429:
+      return "RATE_LIMIT_EXCEEDED";
+    default:
+      return "INTERNAL_SERVER_ERROR";
+  }
+}
+
+// src/resources/analytics.ts
+var AnalyticsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  async get(options = {}) {
+    const result = await this.http.request({
+      path: "/analytics",
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+};
+
+// src/poll.ts
+var DEFAULT_INTERVAL_MS = 3e3;
+var DEFAULT_TIMEOUT_MS2 = 12e4;
+function abortError() {
+  return new KycirisError("Polling was aborted.", { code: "ABORTED" });
+}
+async function pollUntil(fetchOnce, isDone, options = {}, description = "the operation") {
+  const intervalMs = Math.max(0, options.intervalMs ?? DEFAULT_INTERVAL_MS);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    if (options.signal?.aborted) throw abortError();
+    const value = await fetchOnce(options.signal);
+    options.onUpdate?.(value);
+    if (isDone(value)) return value;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      throw new KycirisError(
+        `Timed out after ${timeoutMs}ms waiting for ${description} to finish. It may still complete \u2014 read the status again later, or subscribe to the webhook instead of polling.`,
+        { code: "POLL_TIMEOUT", details: { lastValue: value } }
+      );
+    }
+    await delay(Math.min(intervalMs, remaining), options.signal);
+  }
+}
+function delay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortError());
+      return;
     }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(abortError());
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/resources/identities.ts
+var IdentitiesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Registers an identity independently of any verification. */
+  async create(fields, options = {}) {
+    const result = await this.http.request({
+      method: "POST",
+      path: "/identities",
+      body: fields,
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+  /** A page of identity summaries. Read one identity for the full record. */
+  async list(params = {}, options = {}) {
+    const result = await this.http.request({
+      path: "/identities",
+      query: { ...params },
+      auth: "api-key",
+      signal: options.signal
+    });
+    return toPage(result);
+  }
+  /** The full record, including its verification history. */
+  async get(id, options = {}) {
+    const result = await this.http.request({
+      path: `/identities/${encodeURIComponent(id)}`,
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+  /** This identity's verifications, without embeddings or storage paths. */
+  async verifications(id, options = {}) {
+    const result = await this.http.request({
+      path: `/identities/${encodeURIComponent(id)}/verifications`,
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data ?? [];
+  }
+  async update(id, fields, options = {}) {
+    const result = await this.http.request({
+      method: "PUT",
+      path: `/identities/${encodeURIComponent(id)}`,
+      body: fields,
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+  /** Deletes the identity, its verifications, and the stored images. */
+  async delete(id, options = {}) {
+    await this.http.request({
+      method: "DELETE",
+      path: `/identities/${encodeURIComponent(id)}`,
+      auth: "api-key",
+      signal: options.signal
+    });
   }
   /**
-   * 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
+   * 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.
    */
-  async getIdentity(identityId) {
-    try {
-      const response = await this.client.get(`/identities/${identityId}`);
-      return response.data;
-    } catch (error) {
-      const message = error.response?.data?.message || error.message || "Failed to get identity";
-      throw new KYCSdkError(message, "IDENTITY_FETCH_FAILED", error.response?.status);
-    }
+  async findDuplicates(params = {}, options = {}) {
+    const result = await this.http.request({
+      path: "/identities/duplicates",
+      query: { field: params.field, id: params.id },
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+  /**
+   * 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.
+   */
+  async merge(id, duplicateIds, options = {}) {
+    const result = await this.http.request({
+      method: "POST",
+      path: "/identities/merge",
+      body: { id, duplicateIds },
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+  /**
+   * 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`.
+   */
+  async faceMatch(id, file, options = {}) {
+    const result = await this.http.request({
+      method: "POST",
+      path: `/identities/${encodeURIComponent(id)}/face-match`,
+      form: { file },
+      fileFields: ["file"],
+      auth: "api-key",
+      signal: options.signal,
+      timeoutMs: options.timeoutMs
+    });
+    return result.data;
+  }
+  /** The result of a face-match check started with `faceMatch`. */
+  async faceCheckStatus(id, faceCheckId, options = {}) {
+    const result = await this.http.request({
+      path: `/identities/${encodeURIComponent(id)}/face-match/status/${encodeURIComponent(faceCheckId)}`,
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+  /** Polls a face-match check until it is APPROVED or REJECTED. */
+  async waitForFaceCheck(id, faceCheckId, options = {}) {
+    return pollUntil(
+      (signal) => this.faceCheckStatus(id, faceCheckId, { signal }),
+      (check) => check.status === "APPROVED" || check.status === "REJECTED",
+      options,
+      `face check ${faceCheckId}`
+    );
+  }
+};
+
+// src/resources/levels.ts
+var LevelsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  async create(params, options = {}) {
+    const result = await this.http.request({
+      method: "POST",
+      path: "/verification-levels",
+      body: params,
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+  async list(options = {}) {
+    const result = await this.http.request({
+      path: "/verification-levels",
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data ?? [];
+  }
+  async get(id, options = {}) {
+    const result = await this.http.request({
+      path: `/verification-levels/${encodeURIComponent(id)}`,
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+  async update(id, params, options = {}) {
+    const result = await this.http.request({
+      method: "PUT",
+      path: `/verification-levels/${encodeURIComponent(id)}`,
+      body: params,
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+  async delete(id, options = {}) {
+    await this.http.request({
+      method: "DELETE",
+      path: `/verification-levels/${encodeURIComponent(id)}`,
+      auth: "api-key",
+      signal: options.signal
+    });
+  }
+};
+
+// src/resources/media.ts
+var MediaResourceApi = class {
+  constructor(http) {
+    this.http = http;
   }
   /**
-   * Returns the required steps for a given document type, in collection order.
-   * ID cards require both sides; driving licenses are single-sided.
+   * 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.
+   */
+  async createDownloadToken(verificationId, resource, options = {}) {
+    const result = await this.http.request({
+      method: "POST",
+      path: `/media/token/${encodeURIComponent(verificationId)}`,
+      body: { resource },
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+  /**
+   * 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.
    */
-  getRequiredSteps(documentType) {
-    if (documentType === "DRIVING_LICENSE") {
-      return ["document_front", "selfie"];
+  downloadUrl(token) {
+    return this.http.buildUrl("/media/download", { token });
+  }
+  /**
+   * 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.
+   */
+  async download(verificationId, resource, options = {}) {
+    const { token } = await this.createDownloadToken(verificationId, resource, options);
+    return this.http.requestRaw({
+      path: "/media/download",
+      query: { token },
+      // The single-use token *is* the credential here; sending the API key as
+      // well would put it on a URL-addressed request for no benefit.
+      auth: "none",
+      signal: options.signal
+    });
+  }
+  /** Fetches a file and buffers it. Convenient; holds the image in memory. */
+  async downloadBytes(verificationId, resource, options = {}) {
+    const response = await this.download(verificationId, resource, options);
+    return new Uint8Array(await response.arrayBuffer());
+  }
+};
+
+// src/types.ts
+var DOCUMENT_CATALOG = [
+  { country: "AO", documentType: "ID_CARD" },
+  { country: "AO", documentType: "DRIVING_LICENSE" },
+  { country: "MZ", documentType: "ID_CARD" }
+];
+function isSupportedDocumentPair(country, documentType) {
+  return DOCUMENT_CATALOG.some(
+    (entry) => entry.country === country && entry.documentType === documentType
+  );
+}
+function supportedCountries() {
+  return Array.from(new Set(DOCUMENT_CATALOG.map((entry) => entry.country)));
+}
+function supportedDocumentTypes(country) {
+  return DOCUMENT_CATALOG.filter((entry) => entry.country === country).map(
+    (entry) => entry.documentType
+  );
+}
+var VERIFICATION_STATUSES = [
+  "PENDING",
+  "PROCESSING",
+  "REVIEW",
+  "APPROVED",
+  "REJECTED"
+];
+var VERIFICATION_OUTCOMES = [
+  /** Passed. */
+  "APPROVED",
+  /** A genuine business decision. Retrying cannot change it. */
+  "REJECTED",
+  /** The pipeline broke. Not the user's fault; retry once fixed. */
+  "FAILED_TECHNICAL",
+  /** Could be either — a human should look at the images. */
+  "NEEDS_REVIEW"
+];
+var TERMINAL_VERIFICATION_STATUSES = ["APPROVED", "REJECTED"];
+function isTerminalStatus(status) {
+  return TERMINAL_VERIFICATION_STATUSES.includes(status);
+}
+var PIPELINE_EVENT_KINDS = [
+  /** The verification was created — the start of every timeline. */
+  "CREATED",
+  /** The status moved; `fromStatus`/`toStatus` say where. */
+  "STATUS_CHANGED",
+  /**
+   * The pipeline was re-run from the uploaded files, clearing what had been
+   * extracted. Not a STATUS_CHANGED: a re-run of an already-PROCESSING
+   * verification would otherwise read "PROCESSING -> PROCESSING", which says
+   * nothing while hiding the destructive part.
+   */
+  "REPROCESSED",
+  /** A queue message for it exhausted every retry and was stored. */
+  "JOB_PARKED",
+  /** A parked message was handed back to its handler. */
+  "JOB_RESENT",
+  /** A parked message was abandoned. Reversible — a resend may follow. */
+  "JOB_DISCARDED"
+];
+var DUPLICATE_FIELDS = [
+  "fullName",
+  "idNumber",
+  "mrz",
+  "gender",
+  "country",
+  "birthDate"
+];
+var WEBHOOK_EVENT_TYPES = [
+  "VERIFICATION_STARTED",
+  "VERIFICATION_COMPLETED",
+  "VERIFICATION_APPROVED",
+  "VERIFICATION_REJECTED",
+  "VERIFICATION_REVIEW_REQUIRED",
+  "OCR_COMPLETED",
+  "OCR_FAILED"
+];
+var ALL_WEBHOOK_EVENTS = "*";
+
+// src/resources/ocr.ts
+var OcrResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Queues a document for extraction.
+   *
+   * Returns as soon as the job is accepted; the fields arrive later, via
+   * `getStatus` or `waitForResult`.
+   */
+  async run(file, params, options = {}) {
+    if (!isSupportedDocumentPair(params.country, params.documentType)) {
+      const forCountry = supportedDocumentTypes(params.country);
+      throw new KycirisError(
+        forCountry.length ? `${params.country} supports ${forCountry.join(", ")}, not ${params.documentType}.` : `No documents are supported for country "${params.country}".`,
+        { code: "VALIDATION_ERROR" }
+      );
     }
-    return ["document_front", "document_back", "selfie"];
+    const result = await this.http.request({
+      method: "POST",
+      path: "/ocr",
+      // The gateway names this field `document`, not `file`.
+      form: {
+        document: file,
+        documentType: params.documentType,
+        country: params.country,
+        externalId: params.externalId
+      },
+      fileFields: ["document"],
+      signal: options.signal,
+      timeoutMs: options.timeoutMs
+    });
+    return result.data;
+  }
+  /** Status of a queued job, with the extracted fields once COMPLETED. */
+  async getStatus(ocrId, options = {}) {
+    const result = await this.http.request({
+      path: `/ocr/${encodeURIComponent(ocrId)}/status`,
+      signal: options.signal
+    });
+    return result.data;
   }
+  /** Polls until the job is COMPLETED or FAILED. */
+  async waitForResult(ocrId, options = {}) {
+    return pollUntil(
+      (signal) => this.getStatus(ocrId, { signal }),
+      (process) => process.status === "COMPLETED" || process.status === "FAILED",
+      options,
+      `OCR job ${ocrId}`
+    );
+  }
+};
+
+// src/resources/verifications.ts
+var DOCUMENT_STEPS = ["document_front", "document_back"];
+var STEP_MEDIA = {
+  document_front: "document-front",
+  document_back: "document-back",
+  selfie: "selfie"
+};
+var VerificationsResource = class {
+  constructor(http, session) {
+    this.http = http;
+    this.session = session;
+  }
+  // -------------------------------------------------------------------------
+  // Credentials
+  // -------------------------------------------------------------------------
   /**
-   * 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.
+   * 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.
    *
-   * 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.
+   * @param externalId Your own reference for the end user
+   */
+  async createToken(externalId, options = {}) {
+    const result = await this.http.request({
+      method: "POST",
+      path: "/verification/token",
+      body: { externalId },
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+  // -------------------------------------------------------------------------
+  // The end-user flow
+  // -------------------------------------------------------------------------
+  /**
+   * Starts a verification and, when a storage adapter is configured, records
+   * it so an interrupted flow can be resumed.
    *
-   * @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
+   * 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.
    */
-  async getVerificationProgress(identityId, verificationId) {
-    const session = identityId && verificationId ? null : await this.getSession();
-    const resolvedIdentityId = identityId ?? session?.identityId;
-    const resolvedVerificationId = verificationId ?? session?.verificationId;
-    if (!resolvedIdentityId) {
-      throw new KYCSdkError(
-        "No identityId provided and no persisted session found",
-        "SESSION_NOT_FOUND",
-        404
+  async start(params, options = {}) {
+    if (typeof params.levelName !== "string" || !params.levelName.trim()) {
+      throw new KycirisError(
+        "levelName is required: a verification runs under a verification level, which says which documents are accepted and whether a selfie is needed. Create one from your backend with client.levels.create().",
+        { code: "VALIDATION_ERROR", details: { levelName: params.levelName ?? null } }
       );
     }
-    const identity = await this.getIdentity(resolvedIdentityId);
-    const verifications = identity.verifications ?? [];
-    if (verifications.length === 0) {
-      throw new KYCSdkError("No verifications found for identity", "VERIFICATION_NOT_FOUND", 404);
-    }
-    const verification = resolvedVerificationId ? verifications.find((v) => v.id === resolvedVerificationId) : [...verifications].sort(
-      (a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime()
-    )[0];
-    if (!verification) {
-      throw new KYCSdkError(
-        `Verification ${resolvedVerificationId} not found for identity`,
-        "VERIFICATION_NOT_FOUND",
-        404
+    if (!isSupportedDocumentPair(params.country, params.documentType)) {
+      const forCountry = supportedDocumentTypes(params.country);
+      throw new KycirisError(
+        forCountry.length ? `${params.country} supports ${forCountry.join(", ")}, not ${params.documentType}.` : `No documents are supported for country "${params.country}".`,
+        { code: "VALIDATION_ERROR", details: { country: params.country, documentType: params.documentType } }
       );
     }
-    const selfieUploaded = !!verification.selfiePath;
-    const documentFrontUploaded = !!verification.documentFrontPath;
-    const documentBackUploaded = !!verification.documentBackPath;
+    const result = await this.http.request({
+      method: "POST",
+      path: "/verification/start",
+      body: params,
+      signal: options.signal
+    });
+    const started = result.data;
+    if (started?.verificationId) {
+      await this.session.save({
+        verificationId: started.verificationId,
+        identityId: started.identityId,
+        externalId: params.externalId,
+        documentType: params.documentType,
+        country: params.country,
+        levelName: params.levelName,
+        startedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
+    return started;
+  }
+  /** Uploads the end user's selfie. Triggers face matching once OCR has run. */
+  async uploadSelfie(verificationId, file, options = {}) {
+    const result = await this.http.request({
+      method: "POST",
+      path: "/verification/upload/selfie",
+      form: { verificationId, file },
+      fileFields: ["file"],
+      signal: options.signal,
+      timeoutMs: options.timeoutMs
+    });
+    return result.data;
+  }
+  /**
+   * 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.
+   */
+  async uploadDocument(verificationId, side, file, options = {}) {
+    const result = await this.http.request({
+      method: "POST",
+      path: "/verification/upload/document",
+      form: { verificationId, type: side, file },
+      fileFields: ["file"],
+      signal: options.signal,
+      timeoutMs: options.timeoutMs
+    });
+    return result.data;
+  }
+  /** Current status, face-match score and extracted document data. */
+  async getStatus(verificationId, options = {}) {
+    const result = await this.http.request({
+      path: `/verification/status/${encodeURIComponent(verificationId)}`,
+      signal: options.signal
+    });
+    return result.data;
+  }
+  /**
+   * 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.
+   */
+  async listMedia(verificationId, options = {}) {
+    const result = await this.http.request({
+      path: `/verification/${encodeURIComponent(verificationId)}/media`,
+      signal: options.signal
+    });
+    return result.data?.available ?? [];
+  }
+  /**
+   * 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.
+   */
+  async reanalyze(verificationId, options = {}) {
+    const result = await this.http.request({
+      method: "POST",
+      path: `/verification/reanalyze/${encodeURIComponent(verificationId)}`,
+      signal: options.signal
+    });
+    return result.data;
+  }
+  // -------------------------------------------------------------------------
+  // Resumable flow helpers
+  // -------------------------------------------------------------------------
+  /** The stored session, or null when there is none. */
+  async getSession() {
+    return this.session.read();
+  }
+  /**
+   * Forgets the stored session. Call it once a verification is finished, so
+   * the next one starts clean.
+   */
+  async clearSession() {
+    return this.session.clear();
+  }
+  /**
+   * 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.
+   */
+  async getProgress(verificationId, options = {}) {
+    const id = await this.resolveVerificationId(verificationId);
+    const [status, available] = await Promise.all([
+      this.getStatus(id, { signal: options.signal }),
+      this.listMedia(id, { signal: options.signal })
+    ]);
+    const present = new Set(available);
+    const required = [
+      ...DOCUMENT_STEPS,
+      ...options.selfieRequired === false ? [] : ["selfie"]
+    ];
     const uploaded = {
-      selfie: selfieUploaded,
-      document_front: documentFrontUploaded,
-      document_back: documentBackUploaded
+      document_front: present.has("document-front"),
+      document_back: present.has("document-back"),
+      selfie: present.has("selfie")
     };
-    const missingSteps = this.getRequiredSteps(verification.documentType).filter(
-      (step) => !uploaded[step]
-    );
+    const missingSteps = required.filter((step) => !present.has(STEP_MEDIA[step]));
     return {
-      verificationId: verification.id,
-      documentType: verification.documentType,
-      status: verification.status,
-      selfieUploaded,
-      documentFrontUploaded,
-      documentBackUploaded,
+      verificationId: id,
+      status: status.status,
+      outcome: status.outcome,
+      uploaded,
       missingSteps,
       isComplete: missingSteps.length === 0
     };
   }
   /**
-   * Returns whether every required step of a verification has already been
-   * uploaded (both document sides where applicable, plus the selfie).
+   * Uploads one step, skipping it when the file is already there.
    *
-   * 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.
+   * 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.
+   */
+  async uploadStep(params) {
+    const verificationId = await this.resolveVerificationId(params.verificationId);
+    const prepared = await prepareFile(params.file, `${params.step}.jpg`);
+    const progress = await this.getProgress(verificationId, {
+      selfieRequired: params.selfieRequired,
+      signal: params.signal
+    });
+    if (progress.uploaded[params.step]) {
+      return {
+        message: `${params.step} was already uploaded`,
+        status: progress.status,
+        skipped: true
+      };
+    }
+    const uploadOptions = {
+      signal: params.signal,
+      timeoutMs: params.timeoutMs
+    };
+    const result = params.step === "selfie" ? await this.uploadSelfie(verificationId, prepared, uploadOptions) : await this.uploadDocument(
+      verificationId,
+      params.step === "document_front" ? "front" : "back",
+      prepared,
+      uploadOptions
+    );
+    return { ...result, skipped: false };
+  }
+  /**
+   * Polls the status until the verification is decided.
+   *
+   * 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`.
+   */
+  async waitForResult(verificationId, options = {}) {
+    const id = await this.resolveVerificationId(verificationId);
+    const stopOnReview = options.stopOnReview ?? true;
+    return pollUntil(
+      (signal) => this.getStatus(id, { signal }),
+      (status) => isTerminalStatus(status.status) || stopOnReview && status.status === "REVIEW",
+      options,
+      `verification ${id}`
+    );
+  }
+  async resolveVerificationId(explicit) {
+    if (explicit) return explicit;
+    const stored = await this.session.read();
+    if (stored?.verificationId) return stored.verificationId;
+    throw new KycirisError(
+      this.session.enabled ? "No verificationId was given and there is no stored session to resume. Start a verification first." : "No verificationId was given. Pass one, or configure `storage` so the SDK can remember the verification it started.",
+      { code: "SESSION_NOT_FOUND" }
+    );
+  }
+  // -------------------------------------------------------------------------
+  // Review and operations (project API key)
+  // -------------------------------------------------------------------------
+  /**
+   * A page of the project's verifications, newest first.
+   *
+   * 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.
+   */
+  async list(params = {}, options = {}) {
+    const result = await this.http.request({
+      path: "/verification",
+      query: { ...params },
+      auth: "api-key",
+      signal: options.signal
+    });
+    return toPage(result);
+  }
+  /** Counts per status and outcome, plus what needs an operator's attention. */
+  async summary(options = {}) {
+    const result = await this.http.request({
+      path: "/verification/summary",
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+  /**
+   * 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.
+   */
+  async events(verificationId, options = {}) {
+    const result = await this.http.request({
+      path: `/verification/events/${encodeURIComponent(verificationId)}`,
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data ?? [];
+  }
+  /** Moves a PENDING verification to REVIEW so a person can look at it. */
+  async sendToReview(verificationId, options = {}) {
+    const result = await this.http.request({
+      method: "PATCH",
+      path: `/verification/review/${encodeURIComponent(verificationId)}`,
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+  /**
+   * 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.
    */
-  async hasAllDocuments(identityId, verificationId) {
+  async decide(verificationId, decision, options = {}) {
+    const result = await this.http.request({
+      method: "PATCH",
+      path: `/verification/decision/${encodeURIComponent(verificationId)}`,
+      body: decision,
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+};
+
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  async create(params, options = {}) {
+    const result = await this.http.request({
+      method: "POST",
+      path: "/webhooks",
+      body: params,
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+  async list(options = {}) {
+    const result = await this.http.request({
+      path: "/webhooks",
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data ?? [];
+  }
+  async get(id, options = {}) {
+    const result = await this.http.request({
+      path: `/webhooks/${encodeURIComponent(id)}`,
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+  async update(id, params, options = {}) {
+    const result = await this.http.request({
+      method: "PUT",
+      path: `/webhooks/${encodeURIComponent(id)}`,
+      body: params,
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+  async delete(id, options = {}) {
+    await this.http.request({
+      method: "DELETE",
+      path: `/webhooks/${encodeURIComponent(id)}`,
+      auth: "api-key",
+      signal: options.signal
+    });
+  }
+  /**
+   * 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.
+   */
+  async logs(params = {}, options = {}) {
+    const result = await this.http.request({
+      path: "/webhook-log",
+      query: { ...params },
+      auth: "api-key",
+      signal: options.signal
+    });
+    return toPage(result);
+  }
+  /** One delivery attempt. */
+  async log(id, options = {}) {
+    const result = await this.http.request({
+      path: `/webhook-log/${encodeURIComponent(id)}`,
+      auth: "api-key",
+      signal: options.signal
+    });
+    return result.data;
+  }
+  /**
+   * Sends a recorded delivery again, to the endpoint it originally went to.
+   *
+   * 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.
+   */
+  async resendLog(id, options = {}) {
+    const result = await this.http.request({
+      method: "POST",
+      path: `/webhook-log/${encodeURIComponent(id)}/resend`,
+      auth: "api-key",
+      retry: false,
+      signal: options.signal
+    });
+    return result.data;
+  }
+};
+
+// src/storage.ts
+var SESSION_STORAGE_KEY = "kyciris:session:v1";
+function isStoredSession(value) {
+  return typeof value === "object" && value !== null && typeof value.verificationId === "string";
+}
+var SessionStore = class {
+  constructor(storage) {
+    this.storage = storage;
+  }
+  /** True when a storage adapter was configured. */
+  get enabled() {
+    return Boolean(this.storage);
+  }
+  async save(session) {
+    if (!this.storage) return;
     try {
-      const progress = await this.getVerificationProgress(identityId, verificationId);
-      return progress.isComplete;
-    } catch (error) {
-      if (error instanceof KYCSdkError && (error.code === "VERIFICATION_NOT_FOUND" || error.code === "SESSION_NOT_FOUND")) {
-        return false;
-      }
-      throw error;
+      await this.storage.setItem(SESSION_STORAGE_KEY, JSON.stringify(session));
+    } catch {
     }
   }
+  async read() {
+    if (!this.storage) return null;
+    try {
+      const raw = await this.storage.getItem(SESSION_STORAGE_KEY);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw);
+      return isStoredSession(parsed) ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+  async clear() {
+    if (!this.storage) return;
+    try {
+      await this.storage.removeItem(SESSION_STORAGE_KEY);
+    } catch {
+    }
+  }
+};
+function createMemoryStorage() {
+  const map = /* @__PURE__ */ new Map();
+  return {
+    getItem: (key) => map.get(key) ?? null,
+    setItem: (key, value) => {
+      map.set(key, value);
+    },
+    removeItem: (key) => {
+      map.delete(key);
+    }
+  };
+}
+
+// src/client.ts
+var KycirisClient = class {
+  constructor(config) {
+    this.http = new HttpClient(config);
+    const session = new SessionStore(config.storage);
+    this.verifications = new VerificationsResource(this.http, session);
+    this.identities = new IdentitiesResource(this.http);
+    this.levels = new LevelsResource(this.http);
+    this.media = new MediaResourceApi(this.http);
+    this.ocr = new OcrResource(this.http);
+    this.webhooks = new WebhooksResource(this.http);
+    this.analytics = new AnalyticsResource(this.http);
+  }
   /**
-   * 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.
+   * Whether this client holds the project API key, and so can reach the
+   * server-side endpoints.
    *
-   * @param params The step, image data, and optional verification/identity overrides
-   * @returns The upload result; `skipped` is true when the step was already uploaded
+   * Worth checking in code that runs in both places, rather than letting a
+   * MISSING_CREDENTIAL error be the way you find out.
    */
-  async uploadStep(params) {
-    const session = params.verificationId && params.identityId ? null : await this.getSession();
-    const verificationId = params.verificationId ?? session?.verificationId;
-    const identityId = params.identityId ?? session?.identityId;
+  get isServerSide() {
+    return this.http.hasApiKey();
+  }
+};
+function createKycirisClient(config) {
+  return new KycirisClient(config);
+}
+
+// src/flow.ts
+var EMPTY_UPLOADED = {
+  document_front: false,
+  document_back: false,
+  selfie: false
+};
+var VerificationFlow = class {
+  constructor(client, options) {
+    this.client = client;
+    this.options = options;
+    this.state = {
+      phase: "idle",
+      verificationId: null,
+      currentStep: null,
+      missingSteps: [],
+      uploaded: { ...EMPTY_UPLOADED },
+      status: null,
+      outcome: null,
+      rejectionReason: null,
+      error: null,
+      busy: false
+    };
+    this.listeners = /* @__PURE__ */ new Set();
+    this.aborter = null;
+    if (options.onStateChange) this.listeners.add(options.onStateChange);
+  }
+  getState() {
+    return this.state;
+  }
+  /** Observes state changes. Returns an unsubscribe function. */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /**
+   * 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.
+   */
+  async start(options = {}) {
+    return this.guard("starting", async (signal) => {
+      if (options.fresh) {
+        await this.client.verifications.clearSession();
+      } else {
+        const existing = await this.client.verifications.getSession();
+        if (existing?.verificationId) {
+          return this.loadProgress(existing.verificationId, signal);
+        }
+      }
+      const session = await this.client.verifications.start(
+        {
+          country: this.options.country,
+          documentType: this.options.documentType,
+          levelName: this.options.levelName,
+          externalId: this.options.externalId
+        },
+        { signal }
+      );
+      return this.loadProgress(session.verificationId, signal);
+    });
+  }
+  /**
+   * 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.
+   */
+  async refresh() {
+    const verificationId = this.state.verificationId;
+    if (!verificationId) return this.start();
+    return this.guard(
+      this.state.phase,
+      (signal) => this.loadProgress(verificationId, signal)
+    );
+  }
+  /**
+   * 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.
+   */
+  async submit(file) {
+    const { verificationId, currentStep } = this.state;
     if (!verificationId) {
-      throw new KYCSdkError(
-        "No verificationId provided and no persisted session found",
-        "SESSION_NOT_FOUND",
-        404
+      return this.fail(
+        new KycirisError("The flow has not been started yet.", {
+          code: "SESSION_NOT_FOUND"
+        })
       );
     }
-    if (identityId) {
-      const progress = await this.getVerificationProgress(identityId, verificationId);
-      if (!progress.missingSteps.includes(params.step)) {
-        return {
-          message: `Step ${params.step} already uploaded`,
-          status: progress.status,
-          skipped: true
-        };
-      }
+    if (!currentStep) {
+      return this.fail(
+        new KycirisError("There is no step waiting for an image.", {
+          code: "VALIDATION_ERROR"
+        })
+      );
     }
-    if (params.step === "selfie") {
-      return this.uploadSelfie({
+    return this.guard("uploading", async (signal) => {
+      await this.client.verifications.uploadStep({
+        step: currentStep,
+        file,
         verificationId,
-        imageData: params.imageData,
-        mimeType: params.mimeType
+        selfieRequired: this.options.selfieRequired,
+        signal
       });
-    }
-    return this.uploadDocument({
-      verificationId,
-      type: params.step === "document_front" ? "front" : "back",
-      imageData: params.imageData,
-      mimeType: params.mimeType
+      return this.loadProgress(verificationId, signal);
     });
   }
-  async faceMatchVerification(params) {
-    try {
-      const formData = new FormData();
-      const mimeType = params.mimeType || "image/jpeg";
-      const imageData = params.file;
-      if (imageData.startsWith("file://")) {
-        formData.append("file", {
-          uri: imageData,
-          type: mimeType,
-          name: `selfie.jpg`
-        });
-      } else if (imageData.startsWith("data:")) {
-        formData.append("file", {
-          uri: imageData,
-          type: mimeType,
-          name: `selfie.jpg`
-        });
-      } else {
-        formData.append("file", {
-          uri: `data:${mimeType};base64,${imageData}`,
-          type: mimeType,
-          name: `selfie.jpg`
-        });
-      }
-      const response = await this.client.post(
-        `identities/${params.identityId}/face-match`,
-        formData,
-        {
-          headers: { "Content-Type": "multipart/form-data" }
-        }
+  /**
+   * 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.
+   */
+  async waitForDecision() {
+    const verificationId = this.state.verificationId;
+    if (!verificationId) {
+      return this.fail(
+        new KycirisError("The flow has not been started yet.", {
+          code: "SESSION_NOT_FOUND"
+        })
       );
-      return response.data;
-    } catch (error) {
-      console.log("Upload face match error:", error.response?.data || error.message);
-      const message = error.response?.data?.message || error.message || "Failed to upload face match";
-      throw new KYCSdkError(message, "FACEMATCH_UPLOAD_FAILED", error.response?.status);
-    }
-  }
-  async faceMatchStatus({
-    identityId,
-    faceCheckId,
-    interval = 3e3,
-    timeout = 12e4
-  }) {
-    const startTime = Date.now();
-    return new Promise((resolve, reject) => {
-      const poll = async () => {
-        try {
-          const status = (await this.client.get(`identities/${identityId}/face-match/status/${faceCheckId}`)).data;
-          if (status.status === "APPROVED" || status.status === "REJECTED") {
-            resolve(status);
-            return;
-          }
-          if (Date.now() - startTime > timeout) {
-            reject(new KYCSdkError("Polling timeout", "POLLING_TIMEOUT"));
-            return;
-          }
-          setTimeout(poll, interval);
-        } catch (error) {
-          reject(error);
-        }
+    }
+    return this.guard("processing", async (signal) => {
+      const status = await this.client.verifications.waitForResult(verificationId, {
+        signal,
+        timeoutMs: this.options.decisionTimeoutMs
+      });
+      return {
+        phase: "finished",
+        status: status.status,
+        outcome: status.outcome,
+        rejectionReason: status.rejectionReason
       };
-      poll();
     });
   }
   /**
-   * 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
+   * 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.
    */
-  async pollStatus(verificationId, interval = 3e3, timeout = 12e4) {
-    const startTime = Date.now();
-    return new Promise((resolve, reject) => {
-      const poll = async () => {
-        try {
-          const status = await this.getStatus(verificationId);
-          if (status.status === "APPROVED" || status.status === "REJECTED") {
-            resolve(status);
-            return;
-          }
-          if (Date.now() - startTime > timeout) {
-            reject(new KYCSdkError("Polling timeout", "POLLING_TIMEOUT"));
-            return;
-          }
-          setTimeout(poll, interval);
-        } catch (error) {
-          reject(error);
-        }
-      };
-      poll();
+  cancel() {
+    this.aborter?.abort();
+    this.aborter = null;
+    if (this.state.busy) this.patch({ busy: false });
+  }
+  /** Cancels, forgets the stored session, and returns to `idle`. */
+  async reset() {
+    this.cancel();
+    await this.client.verifications.clearSession();
+    this.patch({
+      phase: "idle",
+      verificationId: null,
+      currentStep: null,
+      missingSteps: [],
+      uploaded: { ...EMPTY_UPLOADED },
+      status: null,
+      outcome: null,
+      rejectionReason: null,
+      error: null,
+      busy: false
+    });
+    return this.state;
+  }
+  // -------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async loadProgress(verificationId, signal) {
+    const progress = await this.client.verifications.getProgress(verificationId, {
+      selfieRequired: this.options.selfieRequired,
+      signal
     });
+    return {
+      verificationId,
+      currentStep: progress.missingSteps[0] ?? null,
+      missingSteps: progress.missingSteps,
+      uploaded: progress.uploaded,
+      status: progress.status,
+      outcome: progress.outcome,
+      phase: progress.isComplete ? "processing" : "collecting"
+    };
   }
   /**
-   * Static factory method to create a KYC client instance
-   * @param credentials API credentials (apiKey and baseUrl)
-   * @returns Configured KYCCore instance
+   * 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.
    */
-  static createClient(credentials) {
-    return new _KYCCore(credentials);
+  async guard(phase, run) {
+    this.aborter?.abort();
+    const aborter = new AbortController();
+    this.aborter = aborter;
+    this.patch({ phase, busy: true, error: null });
+    try {
+      const patch = await run(aborter.signal);
+      this.patch({ ...patch, busy: false });
+      const shouldWait = this.state.phase === "processing" && (this.options.waitForDecision ?? true) && // Not a nested call: waitForDecision itself lands here with phase
+      // 'processing' already set, and would otherwise recurse forever.
+      phase !== "processing";
+      if (shouldWait) return this.waitForDecision();
+      return this.state;
+    } catch (error) {
+      if (isKycirisError(error) && error.code === "ABORTED") {
+        this.patch({ busy: false });
+        return this.state;
+      }
+      return this.fail(error);
+    } finally {
+      if (this.aborter === aborter) this.aborter = null;
+    }
+  }
+  fail(error) {
+    const failure = isKycirisError(error) ? error : new KycirisError(
+      error instanceof Error ? error.message : "The verification failed.",
+      { code: "INTERNAL_SERVER_ERROR", cause: error }
+    );
+    this.patch({ phase: "failed", busy: false, error: failure });
+    return this.state;
+  }
+  patch(patch) {
+    this.state = { ...this.state, ...patch };
+    for (const listener of this.listeners) listener(this.state);
   }
 };
-/** Storage key under which the active verification session is persisted */
-_KYCCore.SESSION_KEY = "kyc:session";
-var KYCCore = _KYCCore;
-function createKYCClient(credentials) {
-  return KYCCore.createClient(credentials);
-}
 
-exports.KYCCore = KYCCore;
-exports.KYCSdkError = KYCSdkError;
-exports.createKYCClient = createKYCClient;
+exports.ALL_WEBHOOK_EVENTS = ALL_WEBHOOK_EVENTS;
+exports.AnalyticsResource = AnalyticsResource;
+exports.DOCUMENT_CATALOG = DOCUMENT_CATALOG;
+exports.DUPLICATE_FIELDS = DUPLICATE_FIELDS;
+exports.GATEWAY_ERROR_CODES = GATEWAY_ERROR_CODES;
+exports.HttpClient = HttpClient;
+exports.IdentitiesResource = IdentitiesResource;
+exports.KycirisClient = KycirisClient;
+exports.KycirisError = KycirisError;
+exports.LevelsResource = LevelsResource;
+exports.MAX_IMAGE_FILE_SIZE = MAX_IMAGE_FILE_SIZE;
+exports.MediaResourceApi = MediaResourceApi;
+exports.OcrResource = OcrResource;
+exports.PIPELINE_EVENT_KINDS = PIPELINE_EVENT_KINDS;
+exports.SDK_ERROR_CODES = SDK_ERROR_CODES;
+exports.SESSION_STORAGE_KEY = SESSION_STORAGE_KEY;
+exports.SessionStore = SessionStore;
+exports.TERMINAL_VERIFICATION_STATUSES = TERMINAL_VERIFICATION_STATUSES;
+exports.VERIFICATION_OUTCOMES = VERIFICATION_OUTCOMES;
+exports.VERIFICATION_STATUSES = VERIFICATION_STATUSES;
+exports.VerificationFlow = VerificationFlow;
+exports.VerificationsResource = VerificationsResource;
+exports.WEBHOOK_EVENT_TYPES = WEBHOOK_EVENT_TYPES;
+exports.WebhooksResource = WebhooksResource;
+exports.createKycirisClient = createKycirisClient;
+exports.createMemoryStorage = createMemoryStorage;
+exports.decodeBase64 = decodeBase64;
+exports.detectImageMimeType = detectImageMimeType;
+exports.encodeBase64 = encodeBase64;
+exports.isKycirisError = isKycirisError;
+exports.isNormalizedFile = isNormalizedFile;
+exports.isReactNative = isReactNative;
+exports.isRetryableStatus = isRetryableStatus;
+exports.isSupportedDocumentPair = isSupportedDocumentPair;
+exports.isTerminalStatus = isTerminalStatus;
+exports.isUntrustedClient = isUntrustedClient;
+exports.normalizeFile = normalizeFile;
+exports.pollUntil = pollUntil;
+exports.prepareFile = prepareFile;
+exports.supportedCountries = supportedCountries;
+exports.supportedDocumentTypes = supportedDocumentTypes;
+exports.toPage = toPage;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map