@smileid/usesmileid 12.0.0-beta01

package/src/data/api/__tests__/smile_id_api.test.ts

@@ -0,0 +1,1197 @@
+import { describe, expect, it, vi } from "vitest";
+
+/**
+ * `SmileIDAPI` tests for the v3 `biometric_kyc` and `enhanced_kyc`
+ * multipart wire format.
+ *
+ * The class only ever calls `client.post(url, body, config)` on the
+ * injected `AxiosInstance`. We construct a fake instance whose `post`
+ * is a `vi.fn()` and inspect each multipart part by reading back the
+ * `FormData` it was handed — this mirrors what axios would serialize
+ * onto the wire without depending on the real axios module (the
+ * pnpm workspace does not install transitive dependencies for the
+ * library workspace).
+ */
+
+vi.mock("axios", () => ({
+  __esModule: true,
+  default: {
+    create: vi.fn(),
+    isAxiosError: () => false,
+  },
+  isAxiosError: () => false,
+}));
+
+import { SmileIDAPI } from "../smile_id_api";
+import { REQUEST_MAC_OPT_IN_KEY } from "../interceptors/smile_request_mac_interceptor";
+import { ATTESTATION_OPT_IN_KEY } from "../interceptors/smile_integrity_interceptor";
+import { NetworkResponseParseException } from "../../../core/exception/use_smile_id_network_exception";
+import type {
+  BiometricKycRequest,
+  DocumentVerificationRequest,
+  EnhancedDocumentVerificationRequest,
+  EnhancedKycRequest,
+  SmartSelfieAuthenticationRequest,
+  SmartSelfieEnrollmentRequest,
+} from "../../model/job_request";
+import { JobType } from "../../../core/models/job_type";
+import type {
+  ConsentInformation,
+  UserDetails,
+} from "../../../core/models/params";
+import { UseSmileIDMetadata } from "../../../metadata/use_smile_id_metadata";
+
+type RecordedCall = {
+  url: string;
+  body: FormData;
+  config?: { headers?: Record<string, string> } & Record<string, unknown>;
+};
+
+function makeApi(
+  partnerOverrides: {
+    callbackUrl?: string;
+    partnerParams?: Record<string, string>;
+  } = {},
+): {
+  api: SmileIDAPI;
+  calls: RecordedCall[];
+  setNextResponse: (data: unknown) => void;
+} {
+  const calls: RecordedCall[] = [];
+  let nextResponse: unknown = {
+    job_id: "job-1",
+    user_id: "user-1",
+    status: "accepted",
+    message: "ok",
+  };
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const fakeClient: any = {
+    post: vi.fn(
+      async (
+        url: string,
+        body: FormData,
+        config?: { headers?: Record<string, string> } & Record<string, unknown>,
+      ) => {
+        const call: RecordedCall = { url, body };
+        if (config !== undefined) {
+          call.config = config;
+        }
+        calls.push(call);
+        return { data: nextResponse };
+      },
+    ),
+  };
+  const api = new SmileIDAPI(fakeClient, {
+    partnerId: "p",
+    callbackUrl: partnerOverrides.callbackUrl ?? "",
+    useSandbox: true,
+    ...(partnerOverrides.partnerParams !== undefined
+      ? { partnerParams: partnerOverrides.partnerParams }
+      : {}),
+  });
+  return {
+    api,
+    calls,
+    setNextResponse: (d) => {
+      nextResponse = d;
+    },
+  };
+}
+
+const consent: ConsentInformation = Object.freeze({
+  granted: true,
+  grantedAt: "2026-04-30T00:00:00.000Z",
+  noticeLanguage: "EN",
+  noticePrivacyPolicyUrl: "https://example.test/p",
+});
+
+// Per-submission metadata snapshot. The request-construction site
+// builds this and it travels on every `JobRequest`; the API
+// serializes `request.metadata` as the `metadata` multipart part.
+const metadata = new UseSmileIDMetadata({
+  sdkVersion: "12.0.0",
+  sdk: "react-native-expo",
+  deviceOs: "",
+  deviceModel: "",
+  appName: "",
+  sessionId: "test-session-id",
+  clientIp: "",
+  networkConnection: "",
+  carrierInfo: "",
+  proxy: false,
+  timezone: "",
+  locale: "",
+  screenResolution: "",
+  memoryInfoMb: 0,
+  deviceOrientation: "",
+  systemArchitecture: "",
+  numberOfCameras: 0,
+  hostApplication: "",
+  proximitySensor: false,
+  securityPolicyVersion: "12.0.0",
+});
+
+/**
+ * Read every multipart part out of a `FormData` instance. The native
+ * spec exposes `entries()`; the RN runtime FormData polyfill in
+ * tests does too. Returns an array of `[name, value]` tuples
+ * preserving insertion order so tests can assert ordering when
+ * needed.
+ */
+function dumpFormData(form: FormData): Array<[string, unknown]> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const entries: Array<[string, unknown]> = [];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  for (const [k, v] of (form as any).entries()) {
+    entries.push([k, v]);
+  }
+  return entries;
+}
+
+function partsByName(form: FormData): Record<string, unknown[]> {
+  const out: Record<string, unknown[]> = {};
+  for (const [name, value] of dumpFormData(form)) {
+    (out[name] ??= []).push(value);
+  }
+  return out;
+}
+
+/**
+ * Read a JSON-content multipart part as a string. The SDK appends
+ * JSON parts as plain text form fields carrying the JSON-serialized
+ * value as the part body (no per-part `Content-Type` header — the
+ * live server's multipart parser rejects parts tagged
+ * `application/json` as "missing or invalid"). Node's native
+ * `FormData` stores text form-field values as plain strings; this
+ * helper coerces defensively in case a future runtime wraps them.
+ */
+/**
+ * A value carrying an async `text()` reader. The runtime `Blob` (Node /
+ * vitest) exposes `text(): Promise<string>`, but the ambient `Blob` type
+ * pulled in via `react-native` types does not declare it, so the helper
+ * narrows structurally on the method it actually calls.
+ */
+type TextReadable = { text(): Promise<string> };
+
+function hasTextReader(value: unknown): value is TextReadable {
+  return (
+    typeof Blob !== "undefined" &&
+    value instanceof Blob &&
+    typeof (value as { text?: unknown }).text === "function"
+  );
+}
+
+async function readJsonPart(part: unknown): Promise<string> {
+  if (hasTextReader(part)) {
+    return await part.text();
+  }
+  return String(part);
+}
+
+/**
+ * Assert that a JSON multipart part is NOT tagged with a per-part
+ * `Content-Type: application/json` header. Concrete scenario: the
+ * live server's multipart parser expects `user_details`, `consent`,
+ * `metadata`, and `partner_params` as plain text form fields and
+ * rejects parts tagged `application/json` as "missing or invalid".
+ * This assertion pins the wire shape so a regression that wraps the
+ * value in a `Blob({ type: "application/json" })` would fail here.
+ */
+function expectNoJsonContentType(part: unknown): void {
+  // A plain-string form-field value has no `.type` to inspect. If the
+  // runtime did wrap the value in a `Blob`, its `type` MUST NOT be
+  // `application/json` (or any other MIME type that would tag the
+  // multipart part on the wire).
+  if (typeof Blob !== "undefined" && part instanceof Blob) {
+    expect((part as Blob).type).not.toBe("application/json");
+  } else {
+    expect(typeof part).toBe("string");
+  }
+}
+
+describe("SmileIDAPI.biometricKyc", () => {
+  function makeRequest(
+    overrides: Partial<BiometricKycRequest["params"]> & {
+      userDetails?: UserDetails;
+    } = {},
+  ): BiometricKycRequest {
+    const { userDetails: userDetailsOverride, ...paramOverrides } = overrides;
+    return {
+      jobType: JobType.biometricKyc,
+      selfieImage: "file:///selfie.jpg",
+      livenessImages: [
+        "file:///l1.jpg",
+        "file:///l2.jpg",
+        "file:///l3.jpg",
+        "file:///l4.jpg",
+        "file:///l5.jpg",
+        "file:///l6.jpg",
+        "file:///l7.jpg",
+      ],
+      consent,
+      metadata,
+      expectedLivenessImageCount: 7,
+      userDetails: userDetailsOverride ?? {
+        givenNames: "John",
+        lastName: "Doe",
+        email: "john@example.test",
+        phoneNumber: "+254700000000",
+      },
+      params: {
+        idType: "NATIONAL_ID",
+        idNumber: "32232403",
+        country: "KE",
+        // `useEnrolledImage` is non-nullable on the public type;
+        // tests default to `false` and individual cases opt into
+        // `true` via `overrides`.
+        useEnrolledImage: false,
+        ...paramOverrides,
+      },
+    };
+  }
+
+  it("sends a `user_details` JSON multipart part with snake_case keys", async () => {
+    const { api, calls } = makeApi();
+    await api.biometricKyc(makeRequest());
+    expect(calls).toHaveLength(1);
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["user_details"]).toBeDefined();
+    const userDetailsRaw = await readJsonPart(parts["user_details"]![0]);
+    const parsed = JSON.parse(userDetailsRaw);
+    expect(parsed).toEqual({
+      given_names: "John",
+      last_name: "Doe",
+      email: "john@example.test",
+      phone_number: "+254700000000",
+    });
+  });
+
+  it("sends the `user_details` part as a plain text form field (no application/json tag)", async () => {
+    // Concrete scenario: the live server's multipart parser rejects
+    // parts tagged `Content-Type: application/json` with "missing or
+    // invalid" — it expects `user_details`, `consent`, `metadata`,
+    // and `partner_params` as plain text form fields (Postman
+    // `"type": "text"`) carrying a JSON-serialized string value.
+    // This test pins the wire shape so a future refactor that wraps
+    // the value in a `Blob({ type: "application/json" })` would
+    // surface as a regression here.
+    const { api, calls } = makeApi();
+    await api.biometricKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expectNoJsonContentType(parts["user_details"]![0]);
+  });
+
+  it("sends the `consent` part as a plain text form field (no application/json tag)", async () => {
+    const { api, calls } = makeApi();
+    await api.biometricKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expectNoJsonContentType(parts["consent"]![0]);
+  });
+
+  it("serializes the `metadata` part from `request.metadata` (built at the request-construction site)", async () => {
+    // Concrete scenario: the metadata snapshot is built by the flow
+    // navigation manager and travels on the request. The API no longer
+    // holds a metadata provider — it serializes `request.metadata`
+    // directly. This pins that the `session_id` entry (and the array
+    // wire shape) come from the request's own snapshot.
+    const { api, calls } = makeApi();
+    await api.biometricKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["metadata"]).toBeDefined();
+    expectNoJsonContentType(parts["metadata"]![0]);
+    const parsed = JSON.parse(await readJsonPart(parts["metadata"]![0]));
+    expect(parsed).toEqual(metadata.toEntries());
+    const sessionEntry = (
+      parsed as Array<{ name: string; value: string }>
+    ).find((entry) => entry.name === "session_id");
+    expect(sessionEntry?.value).toBe("test-session-id");
+  });
+
+  it("sends the `partner_params` part as a plain text form field (no application/json tag)", async () => {
+    const { api, calls } = makeApi({ partnerParams: { jobRef: "ref-1" } });
+    await api.biometricKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expectNoJsonContentType(parts["partner_params"]![0]);
+  });
+
+  it("does NOT send the legacy flat PII parts (server strips them anyway)", async () => {
+    const { api, calls } = makeApi();
+    await api.biometricKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["given_names"]).toBeUndefined();
+    expect(parts["last_name"]).toBeUndefined();
+    expect(parts["email"]).toBeUndefined();
+    expect(parts["phone_number"]).toBeUndefined();
+  });
+
+  it("omits `email` and `phone_number` from user_details when empty", async () => {
+    const { api, calls } = makeApi();
+    await api.biometricKyc(
+      makeRequest({
+        userDetails: {
+          givenNames: "John",
+          lastName: "Doe",
+          phoneNumber: "+254700000000",
+        },
+      }),
+    );
+    const parts = partsByName(calls[0]!.body);
+    const parsed = JSON.parse(await readJsonPart(parts["user_details"]![0]));
+    expect(parsed).toEqual({
+      given_names: "John",
+      last_name: "Doe",
+      phone_number: "+254700000000",
+    });
+    expect(parsed.email).toBeUndefined();
+  });
+
+  it("trims whitespace and omits whitespace only optional user_details fields", async () => {
+    const { api, calls } = makeApi();
+    await api.biometricKyc(
+      makeRequest({
+        userDetails: {
+          givenNames: "John",
+          lastName: "Doe",
+          email: "  john@example.test  ",
+          phoneNumber: "   ",
+        },
+      }),
+    );
+    const parts = partsByName(calls[0]!.body);
+    const parsed = JSON.parse(await readJsonPart(parts["user_details"]![0]));
+    expect(parsed.email).toBe("john@example.test");
+    expect(parsed.phone_number).toBeUndefined();
+  });
+
+  it("appends `use_enrolled_image=true` and still sends selfie + liveness when set", async () => {
+    const { api, calls } = makeApi();
+    await api.biometricKyc(makeRequest({ useEnrolledImage: true }));
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["use_enrolled_image"]).toEqual(["true"]);
+    expect(parts["selfie_image"]).toHaveLength(1);
+    expect(parts["liveness_images"]).toHaveLength(7);
+  });
+
+  it("omits `use_enrolled_image` part by default and sends selfie + liveness", async () => {
+    const { api, calls } = makeApi();
+    await api.biometricKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["use_enrolled_image"]).toBeUndefined();
+    expect(parts["selfie_image"]).toHaveLength(1);
+    expect(parts["liveness_images"]).toHaveLength(7);
+  });
+
+  it("never serializes user_id as a multipart part", async () => {
+    const { api, calls } = makeApi();
+    await api.biometricKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["user_id"]).toBeUndefined();
+  });
+
+  it("emits `callback_url` part from PartnerConfig.callbackUrl when set", async () => {
+    // Concrete scenario: partner configures `p.callbackUrl =
+    // 'https://partner.test/cb'` at the SDK level. `PartnerConfig` is
+    // the sole source for `callback_url` on Biometric KYC submissions
+    // — symmetric with Enhanced KYC and the canonical SDKs.
+    const { api, calls } = makeApi({
+      callbackUrl: "https://partner.test/cb",
+    });
+    await api.biometricKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["callback_url"]).toEqual(["https://partner.test/cb"]);
+  });
+
+  it("omits `callback_url` part when PartnerConfig.callbackUrl is empty", async () => {
+    const { api, calls } = makeApi();
+    await api.biometricKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["callback_url"]).toBeUndefined();
+  });
+
+  it("emits `partner_params` JSON part from PartnerConfig.partnerParams when set", async () => {
+    const { api, calls } = makeApi({
+      partnerParams: { jobRef: "ref-1", sessionId: "s-1" },
+    });
+    await api.biometricKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["partner_params"]).toBeDefined();
+    expectNoJsonContentType(parts["partner_params"]![0]);
+    const parsed = JSON.parse(await readJsonPart(parts["partner_params"]![0]));
+    expect(parsed).toEqual({ jobRef: "ref-1", sessionId: "s-1" });
+  });
+
+  it("omits `partner_params` part when PartnerConfig.partnerParams is unset", async () => {
+    const { api, calls } = makeApi();
+    await api.biometricKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["partner_params"]).toBeUndefined();
+  });
+
+  it("posts to `/v3/biometric_kyc`", async () => {
+    const { api, calls } = makeApi();
+    await api.biometricKyc(makeRequest());
+    expect(calls[0]!.url).toBe("/v3/biometric_kyc");
+  });
+});
+
+describe("SmileIDAPI.enhancedKyc", () => {
+  function makeRequest(
+    overrides: Partial<EnhancedKycRequest["params"]> & {
+      userDetails?: UserDetails;
+    } = {},
+  ): EnhancedKycRequest {
+    const { userDetails: userDetailsOverride, ...paramOverrides } = overrides;
+    return {
+      jobType: JobType.enhancedKyc,
+      consent,
+      metadata,
+      userDetails: userDetailsOverride ?? {
+        givenNames: "John",
+        lastName: "Doe",
+        email: "john@example.test",
+        phoneNumber: "+254700000000",
+      },
+      params: {
+        idType: "NATIONAL_ID",
+        idNumber: "32232403",
+        country: "KE",
+        ...paramOverrides,
+      },
+    };
+  }
+
+  it("sends user_details and the three id fields, no flat PII", async () => {
+    const { api, calls } = makeApi();
+    await api.enhancedKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["id_type"]).toEqual(["NATIONAL_ID"]);
+    expect(parts["id_number"]).toEqual(["32232403"]);
+    expect(parts["country"]).toEqual(["KE"]);
+    expect(parts["user_details"]).toBeDefined();
+    expect(parts["given_names"]).toBeUndefined();
+    expect(parts["last_name"]).toBeUndefined();
+  });
+
+  it("sends `bank_code` part when set", async () => {
+    const { api, calls } = makeApi();
+    await api.enhancedKyc(makeRequest({ bankCode: "044" }));
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["bank_code"]).toEqual(["044"]);
+  });
+
+  it("sends `operator` part when mobileOperator is set (TS name maps to wire key)", async () => {
+    const { api, calls } = makeApi();
+    await api.enhancedKyc(makeRequest({ mobileOperator: "MTN" }));
+    const parts = partsByName(calls[0]!.body);
+    // TS public field is `mobileOperator`; wire key stays `operator`.
+    expect(parts["operator"]).toEqual(["MTN"]);
+    expect(parts["mobile_operator"]).toBeUndefined();
+    expect(parts["mobileOperator"]).toBeUndefined();
+  });
+
+  it("omits `bank_code` and `operator` parts when unset", async () => {
+    const { api, calls } = makeApi();
+    await api.enhancedKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["bank_code"]).toBeUndefined();
+    expect(parts["operator"]).toBeUndefined();
+  });
+
+  it("sends the `user_details` part as a plain text form field (no application/json tag)", async () => {
+    const { api, calls } = makeApi();
+    await api.enhancedKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expectNoJsonContentType(parts["user_details"]![0]);
+  });
+
+  it("posts to `/v3/enhanced_kyc`", async () => {
+    const { api, calls } = makeApi();
+    await api.enhancedKyc(makeRequest());
+    expect(calls[0]!.url).toBe("/v3/enhanced_kyc");
+  });
+
+  it("emits `callback_url` part from PartnerConfig.callbackUrl when set", async () => {
+    // Concrete scenario: partner configures `p.callbackUrl =
+    // 'https://partner.test/cb'` at the SDK level (not per-job). The
+    // server expects the callback URL as the `callback_url` multipart
+    // part, in addition to the `callback-url` HTTP header that the
+    // auth interceptor adds on every request.
+    const { api, calls } = makeApi({
+      callbackUrl: "https://partner.test/cb",
+    });
+    await api.enhancedKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["callback_url"]).toEqual(["https://partner.test/cb"]);
+  });
+
+  it("omits `callback_url` part when PartnerConfig.callbackUrl is empty", async () => {
+    const { api, calls } = makeApi();
+    await api.enhancedKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["callback_url"]).toBeUndefined();
+  });
+
+  it("emits `partner_params` JSON part from PartnerConfig.partnerParams when set", async () => {
+    const { api, calls } = makeApi({
+      partnerParams: { jobRef: "ref-1", sessionId: "s-1" },
+    });
+    await api.enhancedKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["partner_params"]).toBeDefined();
+    expectNoJsonContentType(parts["partner_params"]![0]);
+    const parsed = JSON.parse(await readJsonPart(parts["partner_params"]![0]));
+    expect(parsed).toEqual({ jobRef: "ref-1", sessionId: "s-1" });
+  });
+
+  it("omits `partner_params` part when PartnerConfig.partnerParams is unset", async () => {
+    const { api, calls } = makeApi();
+    await api.enhancedKyc(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["partner_params"]).toBeUndefined();
+  });
+});
+
+describe("SmileIDAPI.documentVerification / enhancedDocumentVerification", () => {
+  const livenessImages: readonly string[] = [
+    "file:///l1.jpg",
+    "file:///l2.jpg",
+    "file:///l3.jpg",
+    "file:///l4.jpg",
+    "file:///l5.jpg",
+    "file:///l6.jpg",
+    "file:///l7.jpg",
+  ];
+
+  const baseUserDetails: UserDetails = {
+    givenNames: "John",
+    lastName: "Doe",
+    email: "john@example.test",
+    phoneNumber: "+254700000000",
+  };
+
+  function documentRequest(
+    overrides: Partial<DocumentVerificationRequest> = {},
+  ): DocumentVerificationRequest {
+    return {
+      jobType: JobType.documentVerification,
+      selfieImage: "file:///selfie.jpg",
+      livenessImages,
+      frontDocument: "file:///front.jpg",
+      country: "KE",
+      userDetails: baseUserDetails,
+      consent,
+      metadata,
+      expectedLivenessImageCount: 7,
+      ...overrides,
+    };
+  }
+
+  function enhancedRequest(
+    overrides: Partial<EnhancedDocumentVerificationRequest> = {},
+  ): EnhancedDocumentVerificationRequest {
+    return {
+      jobType: JobType.enhancedDocumentVerification,
+      selfieImage: "file:///selfie.jpg",
+      livenessImages,
+      frontDocument: "file:///front.jpg",
+      country: "KE",
+      idType: "NATIONAL_ID",
+      userDetails: baseUserDetails,
+      consent,
+      metadata,
+      expectedLivenessImageCount: 7,
+      ...overrides,
+    };
+  }
+
+  it("names the front document part `document` — NOT `front_document`", async () => {
+    const { api, calls } = makeApi();
+    await api.documentVerification(documentRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["document"]).toHaveLength(1);
+    expect(parts["front_document"]).toBeUndefined();
+  });
+
+  it("names the back document part `document_back` — NOT `back_document` — when present", async () => {
+    const { api, calls } = makeApi();
+    await api.documentVerification(
+      documentRequest({ backDocument: "file:///back.jpg" }),
+    );
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["document_back"]).toHaveLength(1);
+    expect(parts["back_document"]).toBeUndefined();
+  });
+
+  it("omits the `document_back` part when no back image was captured", async () => {
+    const { api, calls } = makeApi();
+    await api.documentVerification(documentRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["document_back"]).toBeUndefined();
+  });
+
+  it("sends selfie + liveness + country + user_details parts", async () => {
+    const { api, calls } = makeApi();
+    await api.documentVerification(documentRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["selfie_image"]).toHaveLength(1);
+    expect(parts["liveness_images"]).toHaveLength(7);
+    expect(parts["country"]).toEqual(["KE"]);
+    expect(parts["user_details"]).toBeDefined();
+    expectNoJsonContentType(parts["user_details"]![0]);
+    const parsed = JSON.parse(await readJsonPart(parts["user_details"]![0]));
+    expect(parsed).toEqual({
+      given_names: "John",
+      last_name: "Doe",
+      email: "john@example.test",
+      phone_number: "+254700000000",
+    });
+  });
+
+  it("omits `id_type` on document_verification when the request leaves it unset", async () => {
+    const { api, calls } = makeApi();
+    await api.documentVerification(documentRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["id_type"]).toBeUndefined();
+  });
+
+  it("sends `id_type` on document_verification when supplied", async () => {
+    const { api, calls } = makeApi();
+    await api.documentVerification(documentRequest({ idType: "PASSPORT" }));
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["id_type"]).toEqual(["PASSPORT"]);
+  });
+
+  it("always sends `id_type` (required) on enhanced_document_verification", async () => {
+    const { api, calls } = makeApi();
+    await api.enhancedDocumentVerification(enhancedRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["id_type"]).toEqual(["NATIONAL_ID"]);
+    expect(parts["country"]).toEqual(["KE"]);
+    expect(parts["document"]).toHaveLength(1);
+  });
+
+  it("forwards PartnerConfig.callbackUrl and partnerParams as multipart parts", async () => {
+    const { api, calls } = makeApi({
+      callbackUrl: "https://partner.test/cb",
+      partnerParams: { jobRef: "ref-1" },
+    });
+    await api.documentVerification(documentRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["callback_url"]).toEqual(["https://partner.test/cb"]);
+    expect(parts["partner_params"]).toBeDefined();
+    expectNoJsonContentType(parts["partner_params"]![0]);
+  });
+
+  it("posts to the canonical document endpoints", async () => {
+    const { api, calls } = makeApi();
+    await api.documentVerification(documentRequest());
+    await api.enhancedDocumentVerification(enhancedRequest());
+    expect(calls[0]!.url).toBe("/v3/document_verification");
+    expect(calls[1]!.url).toBe("/v3/enhanced_document_verification");
+  });
+});
+
+describe("SmileIDAPI response mapping (job_id, user_id, created_at)", () => {
+  it("parses snake_case wire keys into camelCase fields including createdAt", async () => {
+    const { api, calls, setNextResponse } = makeApi();
+    setNextResponse({
+      job_id: "job-XYZ",
+      user_id: "user-XYZ",
+      status: "accepted",
+      message: "Request accepted and queued for processing.",
+      created_at: "2026-05-05T15:00:00.000Z",
+    });
+    const response = await api.enhancedKyc({
+      jobType: JobType.enhancedKyc,
+      consent,
+      metadata,
+      userDetails: {
+        givenNames: "John",
+        lastName: "Doe",
+        email: "john@example.test",
+      },
+      params: {
+        idType: "NATIONAL_ID",
+        idNumber: "1",
+        country: "KE",
+      },
+    });
+    expect(calls).toHaveLength(1);
+    expect(response.jobId).toBe("job-XYZ");
+    expect(response.userId).toBe("user-XYZ");
+    expect(response.status).toBe("accepted");
+    expect(response.createdAt).toBe("2026-05-05T15:00:00.000Z");
+  });
+
+  it("leaves createdAt undefined when the server omits it", async () => {
+    const { api, setNextResponse } = makeApi();
+    setNextResponse({
+      job_id: "job-1",
+      user_id: "user-1",
+      status: "accepted",
+      message: "ok",
+    });
+    const response = await api.enhancedKyc({
+      jobType: JobType.enhancedKyc,
+      consent,
+      metadata,
+      userDetails: {
+        givenNames: "John",
+        lastName: "Doe",
+        email: "john@example.test",
+      },
+      params: {
+        idType: "NATIONAL_ID",
+        idNumber: "1",
+        country: "KE",
+      },
+    });
+    expect(response.createdAt).toBeUndefined();
+  });
+
+  it("throws when the server returns a null body", async () => {
+    const { api, setNextResponse } = makeApi();
+    setNextResponse(null);
+    await expect(
+      api.enhancedKyc({
+        jobType: JobType.enhancedKyc,
+        consent,
+        metadata,
+        userDetails: {
+          givenNames: "John",
+          lastName: "Doe",
+          email: "john@example.test",
+        },
+        params: {
+          idType: "NATIONAL_ID",
+          idNumber: "1",
+          country: "KE",
+        },
+      }),
+    ).rejects.toThrow(/empty or non.object/i);
+  });
+
+  it("throws when the server returns an array body", async () => {
+    const { api, setNextResponse } = makeApi();
+    setNextResponse([]);
+    await expect(
+      api.enhancedKyc({
+        jobType: JobType.enhancedKyc,
+        consent,
+        metadata,
+        userDetails: {
+          givenNames: "John",
+          lastName: "Doe",
+          email: "john@example.test",
+        },
+        params: {
+          idType: "NATIONAL_ID",
+          idNumber: "1",
+          country: "KE",
+        },
+      }),
+    ).rejects.toThrow(/empty or non.object/i);
+  });
+});
+
+describe("SmileIDAPI.smartSelfieEnrollment", () => {
+  function makeRequest(
+    userDetailsOverride?: UserDetails,
+  ): SmartSelfieEnrollmentRequest {
+    return {
+      jobType: JobType.smartSelfieEnrollment,
+      selfieImage: "file:///selfie.jpg",
+      // 7-frame canonical liveness count — matches the
+      // `REQUIRED_LIVENESS_FRAME_COUNT` enforced by `SmileIDAPI`.
+      livenessImages: [
+        "file:///l1.jpg",
+        "file:///l2.jpg",
+        "file:///l3.jpg",
+        "file:///l4.jpg",
+        "file:///l5.jpg",
+        "file:///l6.jpg",
+        "file:///l7.jpg",
+      ],
+      consent,
+      metadata,
+      expectedLivenessImageCount: 7,
+      userDetails: userDetailsOverride ?? {
+        givenNames: "John",
+        lastName: "Doe",
+        email: "john@example.test",
+        phoneNumber: "+254700000000",
+      },
+      enhanced: false,
+    };
+  }
+
+  it("posts to the canonical `/v3/registration` path", async () => {
+    // Concrete scenario: the previous behavior selected a different
+    // URL when `enhanced: true`. The lambda only routes on
+    // `/v3/registration` for smart-selfie enrollment, so both paths
+    // collapse onto the canonical URL.
+    const { api, calls } = makeApi();
+    await api.smartSelfieEnrollment(makeRequest());
+    expect(calls[0]!.url).toBe("/v3/registration");
+  });
+
+  it("posts to `/v3/registration` even when the request is marked enhanced", async () => {
+    const { api, calls } = makeApi();
+    await api.smartSelfieEnrollment({ ...makeRequest(), enhanced: true });
+    expect(calls[0]!.url).toBe("/v3/registration");
+  });
+
+  it("sends a `user_details` JSON multipart part with snake_case keys", async () => {
+    const { api, calls } = makeApi();
+    await api.smartSelfieEnrollment(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["user_details"]).toBeDefined();
+    const parsed = JSON.parse(await readJsonPart(parts["user_details"]![0]));
+    expect(parsed).toEqual({
+      given_names: "John",
+      last_name: "Doe",
+      email: "john@example.test",
+      phone_number: "+254700000000",
+    });
+  });
+
+  it("sends the `user_details` part as a plain text form field (no application/json tag)", async () => {
+    // Concrete scenario: the live server's multipart parser rejects
+    // parts tagged `Content-Type: application/json` with "missing or
+    // invalid". `user_details` rides as a plain text form field
+    // carrying a JSON-serialized string value (Postman `"type":
+    // "text"` shape).
+    const { api, calls } = makeApi();
+    await api.smartSelfieEnrollment(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expectNoJsonContentType(parts["user_details"]![0]);
+  });
+
+  it("omits `email` from user_details when blank", async () => {
+    const { api, calls } = makeApi();
+    await api.smartSelfieEnrollment(
+      makeRequest({
+        givenNames: "John",
+        lastName: "Doe",
+        phoneNumber: "+254700000000",
+      }),
+    );
+    const parts = partsByName(calls[0]!.body);
+    const parsed = JSON.parse(await readJsonPart(parts["user_details"]![0]));
+    expect(parsed.email).toBeUndefined();
+  });
+
+  it("sends selfie + liveness file parts", async () => {
+    const { api, calls } = makeApi();
+    await api.smartSelfieEnrollment(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["selfie_image"]).toHaveLength(1);
+    expect(parts["liveness_images"]).toHaveLength(7);
+  });
+
+  it("forwards PartnerConfig.callbackUrl and partnerParams as multipart parts", async () => {
+    const { api, calls } = makeApi({
+      callbackUrl: "https://partner.test/cb",
+      partnerParams: { jobRef: "ref-1" },
+    });
+    await api.smartSelfieEnrollment(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["callback_url"]).toEqual(["https://partner.test/cb"]);
+    expect(parts["partner_params"]).toBeDefined();
+    expectNoJsonContentType(parts["partner_params"]![0]);
+  });
+});
+
+describe("SmileIDAPI.smartSelfieAuthentication", () => {
+  function makeRequest(
+    userDetailsOverride?: UserDetails,
+  ): SmartSelfieAuthenticationRequest {
+    return {
+      jobType: JobType.smartSelfieAuthentication,
+      selfieImage: "file:///selfie.jpg",
+      // 7-frame canonical liveness count — matches the
+      // `REQUIRED_LIVENESS_FRAME_COUNT` enforced by `SmileIDAPI`.
+      livenessImages: [
+        "file:///l1.jpg",
+        "file:///l2.jpg",
+        "file:///l3.jpg",
+        "file:///l4.jpg",
+        "file:///l5.jpg",
+        "file:///l6.jpg",
+        "file:///l7.jpg",
+      ],
+      consent,
+      metadata,
+      expectedLivenessImageCount: 7,
+      userDetails: userDetailsOverride ?? {
+        givenNames: "Jane",
+        lastName: "Doe",
+        email: "jane@example.test",
+        phoneNumber: "+254700000000",
+      },
+      userId: "prior-enrollment-user-id",
+      enhanced: false,
+    };
+  }
+
+  it("posts to the canonical `/v3/authentication` path", async () => {
+    const { api, calls } = makeApi();
+    await api.smartSelfieAuthentication(makeRequest());
+    expect(calls[0]!.url).toBe("/v3/authentication");
+  });
+
+  it("posts to `/v3/authentication` even when the request is marked enhanced", async () => {
+    const { api, calls } = makeApi();
+    await api.smartSelfieAuthentication({ ...makeRequest(), enhanced: true });
+    expect(calls[0]!.url).toBe("/v3/authentication");
+  });
+
+  it("sends a `user_details` JSON multipart part with snake_case keys", async () => {
+    const { api, calls } = makeApi();
+    await api.smartSelfieAuthentication(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["user_details"]).toBeDefined();
+    const parsed = JSON.parse(await readJsonPart(parts["user_details"]![0]));
+    expect(parsed).toEqual({
+      given_names: "Jane",
+      last_name: "Doe",
+      email: "jane@example.test",
+      phone_number: "+254700000000",
+    });
+  });
+
+  it("sends the `user_details` part as a plain text form field (no application/json tag)", async () => {
+    const { api, calls } = makeApi();
+    await api.smartSelfieAuthentication(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expectNoJsonContentType(parts["user_details"]![0]);
+  });
+
+  it("sends selfie + liveness file parts", async () => {
+    const { api, calls } = makeApi();
+    await api.smartSelfieAuthentication(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["selfie_image"]).toHaveLength(1);
+    expect(parts["liveness_images"]).toHaveLength(7);
+  });
+
+  it("sends a `user_id` plain text multipart part carrying the request's userId", async () => {
+    const { api, calls } = makeApi();
+    await api.smartSelfieAuthentication(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["user_id"]).toEqual(["prior-enrollment-user-id"]);
+  });
+
+  it("sends the `user_id` part as a plain text form field (no application/json tag)", async () => {
+    const { api, calls } = makeApi();
+    await api.smartSelfieAuthentication(makeRequest());
+    const parts = partsByName(calls[0]!.body);
+    expectNoJsonContentType(parts["user_id"]![0]);
+  });
+});
+
+describe("SmileIDAPI response-body parse failures", () => {
+  /**
+   * Lock down the parse-error path: when the server returns a 2xx
+   * response with a malformed body (e.g. wire-format change, broken
+   * proxy that strips JSON, …), the SDK must throw
+   * `NetworkResponseParseException` so partner code branching on
+   * `e instanceof NetworkResponseParseException` sees the right
+   * type. The repository's `_mapError` recognises this typed
+   * exception via the idempotent pass-through in `mapAxiosError`
+   * and surfaces it through `failure(...)` without re-wrapping.
+   */
+
+  function makeSelfieRequest(): SmartSelfieEnrollmentRequest {
+    return {
+      jobType: JobType.smartSelfieEnrollment,
+      selfieImage: "file:///selfie.jpg",
+      livenessImages: [
+        "file:///l1.jpg",
+        "file:///l2.jpg",
+        "file:///l3.jpg",
+        "file:///l4.jpg",
+        "file:///l5.jpg",
+        "file:///l6.jpg",
+        "file:///l7.jpg",
+      ],
+      consent,
+      metadata,
+      expectedLivenessImageCount: 7,
+      userDetails: {
+        givenNames: "John",
+        lastName: "Doe",
+        email: "john@example.test",
+        phoneNumber: "+254700000000",
+      },
+      enhanced: false,
+    };
+  }
+
+  it("throws NetworkResponseParseException when the body is null", async () => {
+    const { api, setNextResponse } = makeApi();
+    setNextResponse(null);
+    await expect(
+      api.smartSelfieEnrollment(makeSelfieRequest()),
+    ).rejects.toBeInstanceOf(NetworkResponseParseException);
+  });
+
+  it("throws NetworkResponseParseException when the body is an array", async () => {
+    // A server / proxy returning a JSON array instead of a job-result
+    // object would otherwise slip through as `NetworkUnknownException`
+    // and bury the wire-format mismatch. The typed exception keeps
+    // partner triage tight.
+    const { api, setNextResponse } = makeApi();
+    setNextResponse([]);
+    await expect(
+      api.smartSelfieEnrollment(makeSelfieRequest()),
+    ).rejects.toBeInstanceOf(NetworkResponseParseException);
+  });
+
+  it("throws NetworkResponseParseException when the body is a string", async () => {
+    const { api, setNextResponse } = makeApi();
+    setNextResponse("not-an-object");
+    await expect(
+      api.smartSelfieEnrollment(makeSelfieRequest()),
+    ).rejects.toBeInstanceOf(NetworkResponseParseException);
+  });
+
+  it("the thrown exception carries the canonical error code", async () => {
+    const { api, setNextResponse } = makeApi();
+    setNextResponse(null);
+    try {
+      await api.smartSelfieEnrollment(makeSelfieRequest());
+      throw new Error("expected smartSelfieEnrollment to throw");
+    } catch (error) {
+      expect(error).toBeInstanceOf(NetworkResponseParseException);
+      expect((error as NetworkResponseParseException).errorCode).toBe(
+        "NETWORK_PARSE_ERROR",
+      );
+    }
+  });
+});
+
+describe("SmileIDAPI signed job opt-in (request MAC + attestation)", () => {
+  // An endpoint missing the opt-in flags ships an unsigned job the
+  // server rejects — while the interceptors' own tests stay green.
+  const livenessImages: readonly string[] = [
+    "file:///l1.jpg",
+    "file:///l2.jpg",
+    "file:///l3.jpg",
+    "file:///l4.jpg",
+    "file:///l5.jpg",
+    "file:///l6.jpg",
+    "file:///l7.jpg",
+  ];
+  const userDetails: UserDetails = {
+    givenNames: "John",
+    lastName: "Doe",
+  };
+  const kycParams = {
+    idType: "NATIONAL_ID",
+    idNumber: "32232403",
+    country: "KE",
+  };
+
+  const submissions: ReadonlyArray<{
+    readonly endpoint: string;
+    readonly submit: (api: SmileIDAPI) => Promise<unknown>;
+  }> = [
+    {
+      endpoint: "/v3/registration",
+      submit: (api) =>
+        api.smartSelfieEnrollment({
+          jobType: JobType.smartSelfieEnrollment,
+          selfieImage: "file:///selfie.jpg",
+          livenessImages,
+          userDetails,
+          enhanced: false,
+          consent,
+          metadata,
+          expectedLivenessImageCount: 7,
+        }),
+    },
+    {
+      endpoint: "/v3/authentication",
+      submit: (api) =>
+        api.smartSelfieAuthentication({
+          jobType: JobType.smartSelfieAuthentication,
+          selfieImage: "file:///selfie.jpg",
+          livenessImages,
+          userDetails,
+          userId: "user-1",
+          enhanced: false,
+          consent,
+          metadata,
+          expectedLivenessImageCount: 7,
+        }),
+    },
+    {
+      endpoint: "/v3/enhanced_kyc",
+      submit: (api) =>
+        api.enhancedKyc({
+          jobType: JobType.enhancedKyc,
+          params: kycParams,
+          userDetails,
+          consent,
+          metadata,
+        }),
+    },
+    {
+      endpoint: "/v3/biometric_kyc",
+      submit: (api) =>
+        api.biometricKyc({
+          jobType: JobType.biometricKyc,
+          selfieImage: "file:///selfie.jpg",
+          livenessImages,
+          params: { ...kycParams, useEnrolledImage: false },
+          userDetails,
+          consent,
+          metadata,
+          expectedLivenessImageCount: 7,
+        }),
+    },
+    {
+      endpoint: "/v3/document_verification",
+      submit: (api) =>
+        api.documentVerification({
+          jobType: JobType.documentVerification,
+          selfieImage: "file:///selfie.jpg",
+          livenessImages,
+          frontDocument: "file:///front.jpg",
+          country: "KE",
+          userDetails,
+          consent,
+          metadata,
+          expectedLivenessImageCount: 7,
+        }),
+    },
+    {
+      endpoint: "/v3/enhanced_document_verification",
+      submit: (api) =>
+        api.enhancedDocumentVerification({
+          jobType: JobType.enhancedDocumentVerification,
+          selfieImage: "file:///selfie.jpg",
+          livenessImages,
+          frontDocument: "file:///front.jpg",
+          country: "KE",
+          idType: "NATIONAL_ID",
+          userDetails,
+          consent,
+          metadata,
+          expectedLivenessImageCount: 7,
+        }),
+    },
+  ];
+
+  for (const { endpoint, submit } of submissions) {
+    it(`opts the ${endpoint} submission into MAC signing and attestation`, async () => {
+      const { api, calls } = makeApi();
+      await submit(api);
+      expect(calls).toHaveLength(1);
+      expect(calls[0]!.url).toBe(endpoint);
+      expect(calls[0]!.config?.[REQUEST_MAC_OPT_IN_KEY]).toBe(true);
+      expect(calls[0]!.config?.[ATTESTATION_OPT_IN_KEY]).toBe(true);
+    });
+  }
+});