@smileid/usesmileid 12.0.0-beta01

package/src/core/models/job_type.ts

@@ -0,0 +1,53 @@
+/**
+ * Identifies the type of identity verification job to perform.
+ *
+ * The raw numeric value is the `job_type_id` carried in API requests
+ * and is part of the server wire-format contract — changing it is a
+ * breaking change.
+ */
+export const JobType = {
+  biometricKyc: 1,
+  smartSelfieAuthentication: 2,
+  smartSelfieEnrollment: 4,
+  enhancedKyc: 5,
+  documentVerification: 6,
+  bvn: 7,
+  enhancedDocumentVerification: 11,
+  /**
+   * Sentinel used when no job type has been configured, or when the
+   * server returns a value not recognised by this SDK version. Update
+   * the SDK to pick up new values.
+   */
+  unknown: -1,
+} as const;
+
+export type JobType = (typeof JobType)[keyof typeof JobType];
+
+export type JobTypeName = keyof typeof JobType;
+
+/**
+ * Look up a `JobType` by its raw integer value. Returns `unknown` when
+ * no case matches.
+ */
+export function jobTypeFromValue(value: number): JobType {
+  const match = (Object.values(JobType) as number[]).find((v) => v === value);
+  return (match ?? JobType.unknown) as JobType;
+}
+
+/** True when completing this job involves capturing a selfie. */
+export function requiresSelfie(jobType: JobType): boolean {
+  return (
+    jobType === JobType.biometricKyc ||
+    jobType === JobType.smartSelfieAuthentication ||
+    jobType === JobType.smartSelfieEnrollment
+  );
+}
+
+/** True when completing this job involves capturing an identity document. */
+export function requiresDocument(jobType: JobType): boolean {
+  return (
+    jobType === JobType.biometricKyc ||
+    jobType === JobType.documentVerification ||
+    jobType === JobType.enhancedDocumentVerification
+  );
+}

package/src/core/models/ml_config.ts

@@ -0,0 +1,47 @@
+import type { FaceConfig } from "@smileid/usesmileid_bridge";
+import type {
+  FaceAnalyzer,
+  DocumentAnalyzer,
+} from "@smileid/usesmileid_platform_interface";
+
+/**
+ * ML configuration — the registry maps a `CaptureType` to its analyzer
+ * plus the configured wire payload the orchestrator pushes through
+ * `FaceAnalyzer.configure()` at capture start.
+ *
+ * Per-capture-type registration is exposed via
+ * `ml.analyzers((a) => a.forCaptureType(CaptureType.selfie, ...))`. The
+ * concrete type is the `FaceAnalyzer` / `DocumentAnalyzer` exported by
+ * each federated provider package; the `*Config` companion is the
+ * pre-built wire payload computed from the DSL scope at builder
+ * `build()` time and stable for the lifetime of the flow.
+ *
+ * `CaptureType` is a TypeScript enum (not a string union) so bare
+ * string literals do not typecheck — partners must reference the
+ * namespaced enum value.
+ */
+
+export enum CaptureType {
+  /**
+   * Selfie capture — front-facing camera, face oval overlay, head-pose
+   * validation.
+   */
+  selfie = "selfie",
+  /** Document capture — rectangular frame, optional two-sided. */
+  document = "document",
+}
+
+export type AnalyzerRegistry = {
+  readonly selfie?: FaceAnalyzer;
+  /**
+   * Wire-shape `FaceConfig` built from the DSL scope (analyzer key,
+   * ScanPerformanceProfile, FaceDetectorConfig). Falls back to native
+   * platform defaults when omitted.
+   */
+  readonly selfieConfig?: FaceConfig;
+  readonly document?: DocumentAnalyzer;
+};
+
+export type MLConfig = {
+  readonly analyzers: AnalyzerRegistry;
+};

package/src/core/models/network_config.ts

@@ -0,0 +1,138 @@
+/**
+ * Network stack types — partner credentials, transport tuning, logging
+ * controls.
+ *
+ * Stub note: the network stack itself is not yet wired (see
+ * `docs/Architecture.md § Rollout`). The DSL builder accepts these
+ * values for forward-compatibility — the orchestrator will start
+ * honouring them when the network/job-submission milestone lands.
+ */
+
+import type { AxiosInstance } from "axios";
+
+import type { JobType } from "./job_type";
+
+/**
+ * HTTP log verbosity — progressively reveals more of each request as
+ * the level rises (less redaction).
+ *
+ * `LogLevel` is a TypeScript enum — partners must reference the
+ * namespaced value (`LogLevel.body`); bare string literals do not
+ * typecheck.
+ */
+export enum LogLevel {
+  /** Suppress all network logging. */
+  none = "none",
+  /** Method, URL, and status only. */
+  basic = "basic",
+  /** `basic` + request/response headers (pre-redaction applied). */
+  headers = "headers",
+  /** `headers` + request/response bodies. Verbose — partner-debug only. */
+  body = "body",
+}
+
+export type NetworkLoggingConfig = {
+  readonly enabled: boolean;
+  readonly level: LogLevel;
+  readonly redactHeaders: readonly string[];
+};
+
+/**
+ * Partner identity and per-job environment settings.
+ *
+ * The HTTP auth credential (`token`) and refresh callback (`onTokenExpired`)
+ * live on the parent {@link NetworkInnerConfig} instead — they are
+ * network-level concerns rather than partner identity.
+ */
+export type PartnerConfig = {
+  readonly partnerId: string;
+  /**
+   * Partner webhook endpoint. Sent as the `callback-url` HTTP header
+   * on every request and, when non-empty, as the `callback_url`
+   * multipart form part on Enhanced/Biometric KYC submissions.
+   */
+  readonly callbackUrl: string;
+  readonly useSandbox: boolean;
+  /**
+   * Optional partner-supplied key/value metadata. When set, attached
+   * as the `partner_params` JSON multipart form part on Enhanced /
+   * Biometric KYC submissions.
+   */
+  readonly partnerParams?: Record<string, string>;
+};
+
+/**
+ * Frozen snapshot of the network job + auth + partner + logging block.
+ *
+ * `token` is the HTTP credential stamped as the `smileid-token` header on
+ * every outbound request — separate from `partnerConfig` because
+ * authentication is a network-level credential, not partner identity.
+ *
+ * `onTokenExpired` is an optional async refresh callback invoked when the
+ * server returns a `401 Unauthorized` on an authed endpoint. The SDK
+ * collapses concurrent 401s into a single callback invocation via
+ * `TokenHolder`, updates the stored token on success, and retries the
+ * failed request once. If the callback throws (or the retry also returns
+ * 401) the original 401 is surfaced unchanged.
+ */
+export type NetworkInnerConfig = {
+  readonly jobType?: JobType;
+  readonly token?: string;
+  readonly onTokenExpired?: (previousToken: string) => Promise<string>;
+  readonly partnerConfig?: PartnerConfig;
+  readonly logging?: NetworkLoggingConfig;
+};
+
+/** Timeouts in seconds. */
+export type TimeoutConfig = {
+  readonly connect: number;
+  readonly read: number;
+  readonly write: number;
+  readonly call: number;
+};
+
+export type CacheConfig = {
+  readonly enabled: boolean;
+  readonly maxSize: number;
+};
+
+/**
+ * Retry strategy.
+ *   - `exponential`: `delay = min(initialDelay × multiplier^attempt, maxDelay)` plus `±jitter`
+ *   - `fixed`: constant `fixedDelay` between attempts
+ *   - `none`: no retry (`maxAttempts: 1`)
+ */
+export enum RetryStrategy {
+  exponential = "exponential",
+  fixed = "fixed",
+  none = "none",
+}
+
+/** Delays are in seconds. */
+export type RetryConfig = {
+  readonly maxAttempts: number;
+  readonly strategy: RetryStrategy;
+  readonly initialDelay: number;
+  readonly multiplier: number;
+  readonly maxDelay: number;
+  readonly jitter: number;
+  readonly fixedDelay: number;
+};
+
+/**
+ * A request interceptor that hooks into the SDK's axios client. The
+ * SDK's built-in interceptors (gzip, auth, request-MAC, integrity)
+ * implement this shape, and partners can supply their own.
+ */
+export interface Interceptor {
+  /** Wire the interceptor's request/response hooks onto the client. */
+  attach(client: AxiosInstance): void;
+}
+
+export type NetworkConfig = {
+  readonly config?: NetworkInnerConfig;
+  readonly timeouts?: TimeoutConfig;
+  readonly cache?: CacheConfig;
+  readonly retry?: RetryConfig;
+  readonly interceptors?: readonly Interceptor[];
+};

package/src/core/models/params.ts

@@ -0,0 +1,98 @@
+/**
+ * Job-specific parameters and consent records.
+ */
+
+/** ISO-8601 timestamp string. */
+export type Timestamp = string;
+
+/** Records that a user has granted consent to biometric data collection. */
+export type ConsentInformation = {
+  /** `true` when the user tapped Allow on the consent screen. */
+  readonly granted: boolean;
+  /** ISO-8601 timestamp at which consent was granted. */
+  readonly grantedAt: Timestamp;
+  /** BCP-47 language code for the displayed consent notice (e.g. `"en"`). */
+  readonly noticeLanguage: string;
+  /** URL of the partner's privacy policy shown at consent time. */
+  readonly noticePrivacyPolicyUrl: string;
+};
+
+/**
+ * Subject's personal details, sent as the `user_details` JSON part.
+ * Requires non-blank `givenNames` and `lastName`, plus at least one of
+ * `email` or `phoneNumber`.
+ */
+export type UserDetails = {
+  /** Subject's given / first names. Required, non-blank. */
+  readonly givenNames: string;
+  /** Subject's family / last name. Required, non-blank. */
+  readonly lastName: string;
+  /** Optional email address. */
+  readonly email?: string;
+  /** Optional phone number in international format (leading `+`). */
+  readonly phoneNumber?: string;
+};
+
+/**
+ * Identity fields for an Enhanced KYC job. `userDetails` is no longer
+ * carried on this type — set it on the top-level builder via
+ * `b.userDetails = ...` (shared across every job that needs the
+ * `user_details` multipart part: enhanced_kyc, biometric_kyc, and the
+ * v3 smartSelfie* endpoints).
+ */
+export type EnhancedKYCParams = {
+  /** Document type (e.g. `"NATIONAL_ID"`, `"PASSPORT"`). */
+  readonly idType: string;
+  /** Document number. */
+  readonly idNumber: string;
+  /** ISO 3166-1 alpha-2 country code (e.g. `"KE"`). */
+  readonly country: string;
+  /** Optional bank code, sent as `bank_code`. */
+  readonly bankCode?: string;
+  /** Optional mobile operator code, sent as `operator`. */
+  readonly mobileOperator?: string;
+};
+
+/**
+ * Identity fields for a Biometric KYC job. `userDetails` is no longer
+ * carried on this type — set it on the top-level builder via
+ * `b.userDetails = ...` (shared across every job that needs the
+ * `user_details` multipart part: enhanced_kyc, biometric_kyc, and the
+ * v3 smartSelfie* endpoints).
+ */
+export type BiometricKYCParams = {
+  /** Document type (e.g. `"NATIONAL_ID"`, `"PASSPORT"`). */
+  readonly idType: string;
+  /** Document number. */
+  readonly idNumber: string;
+  /** ISO 3166-1 alpha-2 country code (e.g. `"KE"`). */
+  readonly country: string;
+  /**
+   * When `true`, sends `use_enrolled_image` so the server uses the
+   * partner's previously enrolled image. Capture still runs.
+   */
+  readonly useEnrolledImage: boolean;
+};
+
+/**
+ * Identity fields for a Document Verification job. `userDetails` rides
+ * on the top-level builder via `b.userDetails = ...`, not on this type.
+ */
+export type DocumentVerificationParams = {
+  /** ISO 3166-1 alpha-2 country code (e.g. `"KE"`). */
+  readonly country: string;
+  /** Document type. Optional — the server classifies it when omitted. */
+  readonly idType?: string;
+};
+
+/**
+ * Identity fields for an Enhanced Document Verification job.
+ * `userDetails` rides on the top-level builder via `b.userDetails =
+ * ...`, not on this type.
+ */
+export type EnhancedDocumentVerificationParams = {
+  /** ISO 3166-1 alpha-2 country code (e.g. `"KE"`). */
+  readonly country: string;
+  /** Document type. Required — drives the ID-authority cross-check. */
+  readonly idType: string;
+};

package/src/core/models/result.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { cancelled, failure, success } from "./result";
+
+describe("UseSmileIDResult factories", () => {
+  it("success carries the value under a 'success' status", () => {
+    expect(success(42)).toEqual({ status: "success", value: 42 });
+  });
+
+  it("failure carries the error under a 'failure' status", () => {
+    const error = new Error("boom");
+    expect(failure(error)).toEqual({ status: "failure", error });
+  });
+
+  it("cancelled is a distinct status with no value/error payload", () => {
+    const result = cancelled();
+    expect(result).toEqual({ status: "cancelled" });
+    // Partners switch on `status`; cancelled must NOT masquerade as failure.
+    expect(result.status).not.toBe("failure");
+  });
+});

package/src/core/models/result.ts

@@ -0,0 +1,32 @@
+/**
+ * A result type for SDK operations that makes error handling explicit.
+ *
+ * Partners never need to unwrap a `UseSmileIDResult` directly — all
+ * errors are automatically surfaced through the `onResult` callback.
+ * The discriminated union lets partner code `switch (result.status)`
+ * and exhaust both branches without try/catch ceremony.
+ */
+export type UseSmileIDResult<T> =
+  | { readonly status: "success"; readonly value: T }
+  | { readonly status: "failure"; readonly error: unknown }
+  | { readonly status: "cancelled" };
+
+/** Construct a successful result carrying `value`. */
+export function success<T>(value: T): UseSmileIDResult<T> {
+  return { status: "success", value };
+}
+
+/** Construct a failed result carrying `error`. */
+export function failure<T>(error: unknown): UseSmileIDResult<T> {
+  return { status: "failure", error };
+}
+
+/**
+ * Construct a cancelled result — the user deliberately exited the flow
+ * (e.g. back-pressed out of the first screen) without completing or
+ * failing. Distinct from `failure` so partners can tell a user
+ * cancellation apart from an error.
+ */
+export function cancelled<T>(): UseSmileIDResult<T> {
+  return { status: "cancelled" };
+}