@smileid/usesmileid 12.0.0-beta01

package/src/data/model/__tests__/sdk_config_capture.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, it } from "vitest";
+import {
+  resolveDimensions,
+  resolveJpegQuality,
+  sdkConfigCaptureSchema,
+  type SdkConfigCapture,
+} from "../sdk_config_capture";
+
+describe("resolveDimensions — pair-fallback rule", () => {
+  it("returns the pair when both width and height are present and > 0", () => {
+    expect(resolveDimensions({ width: 640, height: 480 })).toEqual({
+      width: 640,
+      height: 480,
+    });
+  });
+
+  it("returns undefined when only width is present", () => {
+    expect(resolveDimensions({ width: 640 })).toBeUndefined();
+  });
+
+  it("returns undefined when only height is present", () => {
+    expect(resolveDimensions({ height: 480 })).toBeUndefined();
+  });
+
+  it("returns undefined when width is zero", () => {
+    expect(resolveDimensions({ width: 0, height: 480 })).toBeUndefined();
+  });
+
+  it("returns undefined when height is zero", () => {
+    expect(resolveDimensions({ width: 640, height: 0 })).toBeUndefined();
+  });
+
+  it("returns undefined when width is negative", () => {
+    expect(resolveDimensions({ width: -1, height: 480 })).toBeUndefined();
+  });
+
+  it("returns undefined when height is negative", () => {
+    expect(resolveDimensions({ width: 640, height: -1 })).toBeUndefined();
+  });
+
+  it("returns undefined when the capture block is undefined", () => {
+    expect(resolveDimensions(undefined)).toBeUndefined();
+  });
+
+  it("returns undefined for an empty capture block (no width / height)", () => {
+    expect(resolveDimensions({})).toBeUndefined();
+  });
+
+  it("returns the pair when quality is also present (extra fields ignored)", () => {
+    expect(resolveDimensions({ width: 320, height: 240, quality: 80 })).toEqual(
+      {
+        width: 320,
+        height: 240,
+      },
+    );
+  });
+});
+
+describe("resolveJpegQuality — 1..100 range rule", () => {
+  it("returns the quality when in range (1)", () => {
+    expect(resolveJpegQuality({ quality: 1 })).toBe(1);
+  });
+
+  it("returns the quality when in range (100)", () => {
+    expect(resolveJpegQuality({ quality: 100 })).toBe(100);
+  });
+
+  it("returns the quality at a midrange value (75)", () => {
+    expect(resolveJpegQuality({ quality: 75 })).toBe(75);
+  });
+
+  it("returns undefined when quality is 0 (out of range)", () => {
+    expect(resolveJpegQuality({ quality: 0 })).toBeUndefined();
+  });
+
+  it("returns undefined when quality is negative", () => {
+    expect(resolveJpegQuality({ quality: -1 })).toBeUndefined();
+  });
+
+  it("returns undefined when quality is 101 (out of range)", () => {
+    expect(resolveJpegQuality({ quality: 101 })).toBeUndefined();
+  });
+
+  it("returns undefined when quality is absent from the capture block", () => {
+    expect(resolveJpegQuality({ width: 640, height: 480 })).toBeUndefined();
+  });
+
+  it("returns undefined when the capture block is undefined", () => {
+    expect(resolveJpegQuality(undefined)).toBeUndefined();
+  });
+
+  it("does not clamp — 0 returns undefined, not 1", () => {
+    // The contract is never-clamp: out-of-range values are treated as
+    // absent so the caller uses its own default.
+    expect(resolveJpegQuality({ quality: 0 })).toBeUndefined();
+    expect(resolveJpegQuality({ quality: 101 })).toBeUndefined();
+  });
+});
+
+describe("sdkConfigCaptureSchema — Zod parsing", () => {
+  it("accepts an empty object (all fields optional)", () => {
+    const result = sdkConfigCaptureSchema.safeParse({});
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts a fully-populated block", () => {
+    const result = sdkConfigCaptureSchema.safeParse({
+      width: 640,
+      height: 480,
+      quality: 90,
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      const capture: SdkConfigCapture = result.data;
+      expect(capture.width).toBe(640);
+      expect(capture.height).toBe(480);
+      expect(capture.quality).toBe(90);
+    }
+  });
+
+  it("fails when width is a non-integer float", () => {
+    // The schema requires int values to reject partial-pixel nonsense.
+    const result = sdkConfigCaptureSchema.safeParse({ width: 640.5 });
+    expect(result.success).toBe(false);
+  });
+
+  it("strips unknown fields via Zod's default strip behaviour", () => {
+    const result = sdkConfigCaptureSchema.safeParse({
+      width: 640,
+      height: 480,
+      unknownField: "ignored",
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(
+        (result.data as Record<string, unknown>)["unknownField"],
+      ).toBeUndefined();
+    }
+  });
+});

package/src/data/model/image_dimensions.ts

@@ -0,0 +1,15 @@
+/**
+ * Resolved selfie or liveness image capture dimensions.
+ *
+ * Produced only by `resolveDimensions` in `sdk_config_capture` — never
+ * constructed directly. The pair rule (both width and height must be
+ * present and positive) is enforced at the point of creation, so any
+ * `ImageDimensions` value is guaranteed to carry two positive integers.
+ *
+ * Documents are always captured at sensor-native resolution; this type
+ * is intentionally absent from the document-capture path.
+ */
+export type ImageDimensions = {
+  readonly width: number;
+  readonly height: number;
+};

package/src/data/model/job_request.ts

@@ -0,0 +1,150 @@
+import type {
+  ConsentInformation,
+  EnhancedKYCParams,
+  BiometricKYCParams,
+  UserDetails,
+} from "../../core/models/params";
+import { JobType } from "../../core/models/job_type";
+import type { UseSmileIDMetadata } from "../../metadata/use_smile_id_metadata";
+
+/**
+ * Discriminated-union of submission requests. The `jobType` field
+ * narrows the union and tells the repository which API method to
+ * dispatch to.
+ *
+ * Every variant intersects [BaseJobRequest], which carries the two
+ * fields shared by all submissions: the partner-captured `consent`
+ * record and the per-submission `metadata` snapshot. Variants keep a
+ * narrowed `jobType` literal so the union still discriminates.
+ *
+ * `metadata` is built at the request-construction site (the flow
+ * navigation manager) and travels on the request itself — the API
+ * layer reads `request.metadata` and serializes it as the `metadata`
+ * multipart part rather than generating the snapshot at submit time.
+ */
+export interface BaseJobRequest {
+  readonly consent: ConsentInformation;
+  readonly metadata: UseSmileIDMetadata;
+}
+
+export type SmartSelfieEnrollmentRequest = BaseJobRequest & {
+  readonly jobType: typeof JobType.smartSelfieEnrollment;
+  readonly selfieImage: string;
+  readonly livenessImages: readonly string[];
+  readonly userDetails: UserDetails;
+  /**
+   * Screen-level enhanced-liveness intent marker. The wire path is
+   * always `/v3/registration` (and `/v3/authentication` on the auth
+   * variant); this flag governs only the capture-time head-turn
+   * pipeline — the previous "different URL when enhanced" behavior
+   * pointed at endpoints the lambda never exposed.
+   */
+  readonly enhanced: boolean;
+  /**
+   * Expected number of liveness images for this submission. Derived
+   * from the `sdk_config` JWT claim's `livenessImageCount` when
+   * present (`livenessImageCount` maps to `numSamples = count + 1`,
+   * so `expectedLivenessImageCount = count`); otherwise the
+   * `ScanPerformanceProfile` default minus one (`numSamples - 1`).
+   * For Enhanced Smart Selfie this is always
+   * `EnhancedSmartSelfieConfig.EXPECTED_LIVENESS_IMAGE_COUNT` (7).
+   *
+   * Used by `SmileIDAPI._validateLivenessCount` to surface a count
+   * mismatch before the request hits the network.
+   */
+  readonly expectedLivenessImageCount: number;
+};
+
+export type SmartSelfieAuthenticationRequest = BaseJobRequest & {
+  readonly jobType: typeof JobType.smartSelfieAuthentication;
+  readonly selfieImage: string;
+  readonly livenessImages: readonly string[];
+  readonly userDetails: UserDetails;
+  /**
+   * The `user_id` returned by a prior enrollment — the v3
+   * `/v3/authentication` endpoint requires it so the server can match
+   * the authentication attempt to the existing enrollment. Sent on
+   * the wire as a `user_id` multipart text form field.
+   */
+  readonly userId: string;
+  /** Screen-level enhanced-liveness intent marker. See
+   * `SmartSelfieEnrollmentRequest.enhanced`. */
+  readonly enhanced: boolean;
+  /** See `SmartSelfieEnrollmentRequest.expectedLivenessImageCount`. */
+  readonly expectedLivenessImageCount: number;
+};
+
+export type EnhancedKycRequest = BaseJobRequest & {
+  readonly jobType: typeof JobType.enhancedKyc;
+  readonly params: EnhancedKYCParams;
+  readonly userDetails: UserDetails;
+};
+
+/**
+ * BVN submission stub. The variant exists in the discriminated union
+ * so `JobType.bvn` can dispatch to a dedicated request rather than
+ * piggy-backing on `enhancedKyc`. The repository rejects it with the
+ * canonical `"BVN submission is not yet supported"` message until the
+ * dedicated endpoint lands.
+ */
+export type BvnRequest = BaseJobRequest & {
+  readonly jobType: typeof JobType.bvn;
+  readonly params: EnhancedKYCParams;
+  readonly userDetails: UserDetails;
+};
+
+export type BiometricKycRequest = BaseJobRequest & {
+  readonly jobType: typeof JobType.biometricKyc;
+  readonly selfieImage: string;
+  readonly livenessImages: readonly string[];
+  readonly params: BiometricKYCParams;
+  readonly userDetails: UserDetails;
+  /** See `SmartSelfieEnrollmentRequest.expectedLivenessImageCount`. */
+  readonly expectedLivenessImageCount: number;
+};
+
+export type DocumentVerificationRequest = BaseJobRequest & {
+  readonly jobType: typeof JobType.documentVerification;
+  readonly selfieImage: string;
+  readonly livenessImages: readonly string[];
+  /** Front of the captured ID. Sent as the `document` part. */
+  readonly frontDocument: string;
+  /** Back of the captured ID. Sent as the `document_back` part. */
+  readonly backDocument?: string;
+  readonly country: string;
+  /** Optional — the server classifies the document when omitted. */
+  readonly idType?: string;
+  readonly userDetails: UserDetails;
+  /** See `SmartSelfieEnrollmentRequest.expectedLivenessImageCount`. */
+  readonly expectedLivenessImageCount: number;
+};
+
+/**
+ * Enhanced variant of the document-verification job. Dispatches through
+ * `/v3/enhanced_document_verification` and lands on a distinct repository
+ * switch case. Differs from [DocumentVerificationRequest] in that
+ * `idType` is required (the server uses it for the ID-authority check).
+ */
+export type EnhancedDocumentVerificationRequest = BaseJobRequest & {
+  readonly jobType: typeof JobType.enhancedDocumentVerification;
+  readonly selfieImage: string;
+  readonly livenessImages: readonly string[];
+  /** Front of the captured ID. Sent as the `document` part. */
+  readonly frontDocument: string;
+  /** Back of the captured ID. Sent as the `document_back` part. */
+  readonly backDocument?: string;
+  readonly country: string;
+  readonly idType: string;
+  readonly userDetails: UserDetails;
+  /** See `SmartSelfieEnrollmentRequest.expectedLivenessImageCount`. */
+  readonly expectedLivenessImageCount: number;
+};
+
+export type JobRequest =
+  | SmartSelfieEnrollmentRequest
+  | SmartSelfieAuthenticationRequest
+  | EnhancedKycRequest
+  | BvnRequest
+  | BiometricKycRequest
+  | DocumentVerificationRequest
+  | EnhancedDocumentVerificationRequest;

package/src/data/model/job_submission_response.ts

@@ -0,0 +1,17 @@
+/**
+ * Job-submission response. Returned by every job-submission endpoint
+ * (`/v3/smart_selfie_*`, `/v3/biometric_kyc`,
+ * `/v3/document_verification`, …).
+ */
+export type JobSubmissionResponse = {
+  readonly jobId: string;
+  readonly userId: string;
+  readonly status: string;
+  readonly message: string;
+  /**
+   * ISO-8601 timestamp at which the server accepted the job. Always
+   * present in v3 responses but typed optional for forward and
+   * backward compatibility insurance.
+   */
+  readonly createdAt?: string;
+};

package/src/data/model/sdk_config.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+
+import { sdkConfigCaptureSchema } from "./sdk_config_capture";
+
+/**
+ * Capture-parameter settings delivered via the JWT auth token.
+ *
+ * The backend embeds this object under the `sdk_config` claim (JWT
+ * payload, base64url-decoded middle segment). All fields are optional;
+ * an absent or invalid field falls back to the SDK default — values are
+ * never clamped.
+ *
+ * Expected claim shape:
+ * ```jsonc
+ * {
+ *   "sdk_config": {
+ *     "selfie":   { "width": 640, "height": 480, "quality": 90 },
+ *     "liveness": { "width": 640, "height": 480, "quality": 80 },
+ *     "document": { "quality": 70 },
+ *     "livenessImageCount": 7
+ *   }
+ * }
+ * ```
+ *
+ * Field names are a deliberate cross-SDK shared contract that
+ * intentionally omits the `UseSmileID` prefix.
+ */
+export const sdkConfigSchema = z.object({
+  /** Selfie capture settings: pixel dimensions and JPEG quality. */
+  selfie: sdkConfigCaptureSchema.optional(),
+  /** Liveness capture settings: pixel dimensions and JPEG quality. */
+  liveness: sdkConfigCaptureSchema.optional(),
+  /**
+   * Document capture settings. Only `quality` is applied — document
+   * frames stay sensor-native with their longest side bounded at
+   * 1 600 px by the native resampler. `width` / `height` are accepted
+   * by the schema but deliberately ignored.
+   */
+  document: sdkConfigCaptureSchema.optional(),
+  /**
+   * Number of liveness images the native session should capture.
+   * Maps to the internal `numSamples` parameter as
+   * `numSamples = livenessImageCount + 1` (the `+1` accounts for the
+   * reference selfie still).
+   *
+   * A value of `0` or below is treated as absent; the caller falls back
+   * to the `ScanPerformanceProfile` default (`numSamples = 8`).
+   *
+   * This override is suppressed when Enhanced Smart Selfie liveness is
+   * active — the head-turn flow manages its own capture count.
+   */
+  livenessImageCount: z.number().int().optional(),
+});
+
+export type SdkConfig = z.infer<typeof sdkConfigSchema>;
+
+/**
+ * Convert `livenessImageCount` to the internal `numSamples` override,
+ * or `undefined` when the value is absent or invalid.
+ *
+ * Formula: `numSamples = livenessImageCount + 1`.
+ * The `+1` accounts for the reference selfie still that the native
+ * session captures in addition to the liveness frames.
+ * A count of `0` or below is treated as absent (returns `undefined`).
+ */
+export function numSamplesOverride(
+  config: SdkConfig | undefined,
+): number | undefined {
+  const count = config?.livenessImageCount;
+  if (count !== undefined && count > 0) {
+    return count + 1;
+  }
+  return undefined;
+}

package/src/data/model/sdk_config_capture.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+
+import type { ImageDimensions } from "./image_dimensions";
+
+/**
+ * Per-capture-type block inside an `sdk_config` JWT claim.
+ *
+ * Three instances appear under the `selfie`, `liveness`, and `document`
+ * keys of the top-level claim. Each field is optional — any absent or
+ * out-of-range value falls back to the SDK default at the point of use.
+ *
+ * Field names are a deliberate cross-SDK shared contract that
+ * intentionally omits the `UseSmileID` prefix.
+ */
+export const sdkConfigCaptureSchema = z.object({
+  /**
+   * Target capture width in pixels.
+   * Applied only for selfie and liveness — document frames stay
+   * sensor-native with their longest side bounded by the native
+   * resampler at 1 600 px.
+   */
+  width: z.number().int().optional(),
+  /**
+   * Target capture height in pixels.
+   * Resolved as a pair with `width` — both must be present and
+   * greater than zero, otherwise the pair falls back to the SDK
+   * default in full (never mix a server width with a default height).
+   */
+  height: z.number().int().optional(),
+  /**
+   * JPEG compression quality hint in the range `1..100`.
+   * Values outside that range are treated as absent — the caller uses
+   * the SDK default. Values are never clamped; the backend owns
+   * enforcement.
+   */
+  quality: z.number().int().optional(),
+});
+
+export type SdkConfigCapture = z.infer<typeof sdkConfigCaptureSchema>;
+
+/**
+ * Resolve a capture block to an `ImageDimensions` pair, or `undefined`
+ * when the pair rule is not satisfied.
+ *
+ * Rule (port of Flutter / iOS / Android cross-SDK contract):
+ *   - Both `width` and `height` must be present and `> 0`.
+ *   - If either is absent or invalid, return `undefined`; the caller
+ *     falls back to the SDK default pair in full. Mixing a server width
+ *     with a default height is explicitly forbidden to avoid
+ *     aspect-ratio mismatches.
+ */
+export function resolveDimensions(
+  capture: SdkConfigCapture | undefined,
+): ImageDimensions | undefined {
+  if (!capture) return undefined;
+  const { width, height } = capture;
+  if (width !== undefined && height !== undefined && width > 0 && height > 0) {
+    return { width, height };
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the JPEG quality from a capture block, or `undefined` when
+ * the value is outside the valid range.
+ *
+ * Range: integer `1..100` inclusive. Out-of-range values are not
+ * clamped — the caller uses the SDK default instead.
+ */
+export function resolveJpegQuality(
+  capture: SdkConfigCapture | undefined,
+): number | undefined {
+  const quality = capture?.quality;
+  if (quality !== undefined && quality >= 1 && quality <= 100) {
+    return quality;
+  }
+  return undefined;
+}

package/src/data/model/sdk_config_source.ts

@@ -0,0 +1,26 @@
+/**
+ * Provenance of the capture parameters used for a given submission.
+ *
+ * Emitted as the `sdk_config_source` metadata entry on every job
+ * submission. The backend gates its dimension-consistency check on this
+ * value — reporting the wrong source causes server-side validation
+ * failures, so these wire strings are parity-critical.
+ *
+ * Wire values are intentionally lowercase snake_case to match the
+ * backend's expected strings.
+ */
+export const SdkConfigSource = {
+  /**
+   * Capture parameters were overridden by a valid `sdk_config` claim
+   * decoded from the JWT auth token.
+   */
+  sdkConfig: "sdk_config",
+  /**
+   * No `sdk_config` claim was present (or it was structurally invalid);
+   * the SDK applied its built-in defaults throughout the flow.
+   */
+  defaultSource: "default",
+} as const;
+
+export type SdkConfigSourceValue =
+  (typeof SdkConfigSource)[keyof typeof SdkConfigSource];

package/src/data/repository/__tests__/use_smile_id_repository.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it, vi } from "vitest";
+
+/**
+ * Repository-level dispatch tests.
+ *
+ * Covers the BVN unsupported-submission path: the repository
+ * short-circuits a `BvnRequest` and returns a typed
+ * `InvalidFieldValueException` carrying the canonical
+ * "BVN submission is not yet supported" message, without ever
+ * reaching the API layer.
+ */
+
+vi.mock("axios", () => ({
+  __esModule: true,
+  default: {
+    create: vi.fn(),
+    isAxiosError: () => false,
+  },
+  isAxiosError: () => false,
+}));
+
+import { UseSmileIDRepositoryImpl } from "../use_smile_id_repository_impl";
+import { InvalidFieldValueException } from "../../../core/exception/job_validation_exceptions";
+import {
+  RetryStrategy,
+  type RetryConfig,
+} from "../../../core/models/network_config";
+import type { BvnRequest } from "../../model/job_request";
+import { JobType } from "../../../core/models/job_type";
+import type { ConsentInformation } from "../../../core/models/params";
+import { UseSmileIDMetadata } from "../../../metadata/use_smile_id_metadata";
+
+const NO_RETRY: RetryConfig = Object.freeze({
+  maxAttempts: 1,
+  strategy: RetryStrategy.none,
+  initialDelay: 0,
+  multiplier: 1,
+  maxDelay: 0,
+  jitter: 0,
+  fixedDelay: 0,
+});
+
+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 carried on every `JobRequest`. The
+// BVN path short-circuits before the API serializes it, but the field
+// is required on `BaseJobRequest` so the fixture must supply one.
+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",
+});
+
+describe("UseSmileIDRepositoryImpl — BVN submission", () => {
+  it("rejects BvnRequest with `BVN submission is not yet supported` without calling the API", async () => {
+    // Concrete scenario: partner configures `JobType.bvn` and the
+    // flow manager dispatches a `bvn` request to the repository.
+    // The repository must short-circuit before hitting the API.
+    const stubApi = {
+      enhancedKyc: vi.fn(),
+      biometricKyc: vi.fn(),
+      smartSelfieEnrollment: vi.fn(),
+      smartSelfieAuthentication: vi.fn(),
+      documentVerification: vi.fn(),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any;
+    const repository = new UseSmileIDRepositoryImpl(stubApi, NO_RETRY);
+    const request: BvnRequest = {
+      jobType: JobType.bvn,
+      params: {
+        idType: "BVN",
+        idNumber: "12345678901",
+        country: "NG",
+      },
+      userDetails: {
+        givenNames: "John",
+        lastName: "Doe",
+        email: "john@example.test",
+      },
+      consent: CONSENT,
+      metadata: METADATA,
+    };
+
+    const result = await repository.submit(request);
+
+    expect(result.status).toBe("failure");
+    if (result.status === "failure") {
+      expect(result.error).toBeInstanceOf(InvalidFieldValueException);
+      const err = result.error as InvalidFieldValueException;
+      expect(err.message).toMatch(/BVN submission is not yet supported/);
+      expect(err.errorDetails?.["fieldName"]).toBe("jobType");
+    }
+    expect(stubApi.enhancedKyc).not.toHaveBeenCalled();
+    expect(stubApi.biometricKyc).not.toHaveBeenCalled();
+  });
+});

package/src/data/repository/use_smile_id_repository.ts

@@ -0,0 +1,19 @@
+import type { JobRequest } from "../model/job_request";
+import type { JobSubmissionResponse } from "../model/job_submission_response";
+import type { UseSmileIDResult } from "../../core/models/result";
+
+/**
+ * Repository abstraction over `SmileIDAPI` + retry policy.
+ *
+ * The orchestrator depends on this interface, not the concrete
+ * `UseSmileIDRepositoryImpl`, so tests can substitute an in-memory
+ * repository without spinning up a real axios chain.
+ */
+export interface UseSmileIDRepository {
+  /**
+   * Submit a `JobRequest`, transparently retrying network-class
+   * failures per the configured retry policy. The `request.jobType`
+   * discriminator drives dispatch to the matching API method.
+   */
+  submit(request: JobRequest): Promise<UseSmileIDResult<JobSubmissionResponse>>;
+}