@smileid/usesmileid 12.0.0-beta01

package/src/data/api/interceptors/token_refresh_interceptor.ts

@@ -0,0 +1,122 @@
+import type {
+  AxiosError,
+  AxiosInstance,
+  AxiosResponse,
+  InternalAxiosRequestConfig,
+} from "axios";
+
+import type { TokenHolder } from "../auth/token_holder";
+
+/**
+ * Refreshes the partner-supplied `smileid-token` when the server responds
+ * with a `401 Unauthorized` and retries the request once with the fresh
+ * token.
+ *
+ * Policy:
+ * - **401 only.** A 403 means the token is valid but unauthorized for the
+ *   resource — a refresh will not change that, so 403s pass through unchanged.
+ * - **At most one refresh per request.** A marker is stamped on the request
+ *   config so a second 401 surfaces unchanged instead of looping.
+ * - **Single-flight via {@link TokenHolder}.** Concurrent 401s share one
+ *   refresh invocation.
+ *
+ * Sits outermost of the SDK-owned response interceptors so its retry — which
+ * re-issues via the same axios instance — re-runs the downstream interceptors
+ * (mac, integrity, auth) with the now-refreshed token (auth reads from the
+ * same `TokenHolder` this interceptor wrote into).
+ */
+export type TokenRefreshInterceptorOptions = {
+  readonly tokenHolder: TokenHolder;
+  /**
+   * Partner-supplied refresh callback. `undefined` disables refresh — every
+   * 401 surfaces unchanged. The callback receives the token the SDK was
+   * using and returns a fresh one; any thrown exception is treated as a
+   * refresh failure and the original 401 is surfaced unchanged.
+   *
+   * Field is `T | undefined` (not just `T?`) so that under
+   * `exactOptionalPropertyTypes`, callers can pass `onTokenExpired: maybeUndefined`
+   * directly without a narrowing dance.
+   */
+  readonly onTokenExpired:
+    | ((previousToken: string) => Promise<string>)
+    | undefined;
+};
+
+/** Marker on `RequestOptions.config` so a second 401 stops here instead of looping. */
+const RETRIED_FLAG = "__smileid_token_refresh_retried" as const;
+
+type RetryableConfig = InternalAxiosRequestConfig & {
+  [RETRIED_FLAG]?: boolean;
+};
+
+export class TokenRefreshInterceptor {
+  private readonly _tokenHolder: TokenHolder;
+  private readonly _onTokenExpired:
+    | ((previousToken: string) => Promise<string>)
+    | undefined;
+
+  constructor(options: TokenRefreshInterceptorOptions) {
+    this._tokenHolder = options.tokenHolder;
+    this._onTokenExpired = options.onTokenExpired;
+  }
+
+  /** Attach a response interceptor that intercepts 401s and retries once. */
+  attach(client: AxiosInstance): { response: number } {
+    const responseId = client.interceptors.response.use(
+      (response) => response,
+      (error: unknown) => this._onError(client, error),
+    );
+    return { response: responseId };
+  }
+
+  private async _onError(
+    client: AxiosInstance,
+    error: unknown,
+  ): Promise<AxiosResponse> {
+    const refresh = this._onTokenExpired;
+    if (!refresh) throw error;
+
+    if (!isAxiosErrorLike(error)) throw error;
+    const response = error.response;
+    if (!response || response.status !== 401) throw error;
+
+    const config = error.config as RetryableConfig | undefined;
+    if (!config) throw error;
+    if (config[RETRIED_FLAG] === true) throw error;
+
+    const previousToken = this._tokenHolder.current;
+    const newToken = await this._tokenHolder.refreshSingleFlight(
+      previousToken,
+      async (previous) => {
+        try {
+          return await refresh(previous);
+        } catch {
+          // Partner-supplied callback: opaque error surface. Any failure →
+          // null, caller surfaces the original 401 unchanged.
+          return null;
+        }
+      },
+    );
+
+    if (newToken === null || newToken === previousToken) {
+      throw error;
+    }
+
+    config[RETRIED_FLAG] = true;
+    return client.request(config);
+  }
+}
+
+/**
+ * Narrow `unknown` to the shape `TokenRefreshInterceptor` needs to read
+ * (`response.status`, `config`). Avoids relying on `axios.isAxiosError`
+ * which requires the package's named export at runtime.
+ */
+function isAxiosErrorLike(error: unknown): error is AxiosError {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "isAxiosError" in error &&
+    (error as { isAxiosError?: boolean }).isAxiosError === true
+  );
+}

package/src/data/api/smile_id_api.ts

@@ -0,0 +1,488 @@
+import axios, { type AxiosInstance } from "axios";
+import type {
+  NetworkConfig,
+  PartnerConfig,
+} from "../../core/models/network_config";
+import { SmileIDUrls } from "../smile_id_urls";
+import type { ConsentInformation, UserDetails } from "../../core/models/params";
+import type {
+  BiometricKycRequest,
+  DocumentVerificationRequest,
+  EnhancedDocumentVerificationRequest,
+  EnhancedKycRequest,
+  SmartSelfieAuthenticationRequest,
+  SmartSelfieEnrollmentRequest,
+} from "../model/job_request";
+import { SmileAuthInterceptor } from "./interceptors/smile_auth_interceptor";
+import { attachLoggingInterceptor } from "./interceptors/logging_interceptor";
+import { REQUEST_MAC_OPT_IN_KEY } from "./interceptors/smile_request_mac_interceptor";
+import { ATTESTATION_OPT_IN_KEY } from "./interceptors/smile_integrity_interceptor";
+import type { JobSubmissionResponse } from "../model/job_submission_response";
+import type { UseSmileIDMetadata } from "../../metadata/use_smile_id_metadata";
+import { NetworkResponseParseException } from "../../core/exception";
+import { LivenessFrameCountException } from "../../core/exception";
+
+/**
+ * Typed Smile ID API wrapper around axios.
+ *
+ * Construction goes through `NetworkingFactory.make(config)` — the
+ * factory sets up the axios instance and attaches the auth + logging
+ * interceptors in the right order. The auth interceptor stamps the
+ * partner-supplied `PartnerConfig.token` onto every outbound request;
+ * the partner application is responsible for refreshing that token
+ * via its own backend.
+ *
+ * Sandbox switch: `partnerConfig.useSandbox` selects between dev and
+ * prod base URLs. Currently both point to dev — the conditional is
+ * infrastructure for future divergence.
+ */
+
+// Both URLs point to dev during the v12 rollout. The `useSandbox`
+// conditional in `buildAxiosClient` stays as the seam for future
+// divergence; partners flipping the flag won't see a wire change yet,
+// but their code is forward-compatible. A previous mistake of pointing
+// only one of these at prod was the cause of a partner-credential 401
+// (prod traffic against creds registered on dev).
+const PROD_BASE_URL = SmileIDUrls.production;
+const SANDBOX_BASE_URL = SmileIDUrls.sandbox;
+
+/**
+ * Opts a request into `smileid-request-mac` signing and
+ * `smileid-device-nonce` attestation — the server rejects job
+ * submissions that arrive without both headers.
+ */
+const SIGNED_JOB_SUBMISSION_FLAGS = {
+  [REQUEST_MAC_OPT_IN_KEY]: true,
+  [ATTESTATION_OPT_IN_KEY]: true,
+} as const;
+
+export class SmileIDAPI {
+  private readonly _client: AxiosInstance;
+  private readonly _partnerConfig: PartnerConfig;
+
+  constructor(client: AxiosInstance, partnerConfig: PartnerConfig) {
+    this._client = client;
+    this._partnerConfig = partnerConfig;
+  }
+
+  /**
+   * v3 smart-selfie enrollment.
+   *
+   * Endpoint: `/v3/registration` (canonical). The previous
+   * `/v3/smart_selfie_enrollment(_enhanced)` paths are deprecated —
+   * the lambda only routes on the canonical path. The `enhanced` flag
+   * on the request stays as the screen-level intent marker (the
+   * capture pipeline reads it to toggle enhanced liveness); it no
+   * longer selects a different URL.
+   *
+   * Wire format: multipart/form-data with the usual selfie + liveness
+   * file parts, plus a `user_details` plain text form field carrying a
+   * JSON-string value (matches the enhanced_kyc / biometric_kyc shape).
+   * The part is NOT tagged with a `Content-Type: application/json`
+   * header — the live server's multipart parser rejects parts tagged
+   * `application/json` as "missing or invalid" when it expects a text
+   * form field.
+   */
+  async smartSelfieEnrollment(
+    request: SmartSelfieEnrollmentRequest,
+  ): Promise<JobSubmissionResponse> {
+    const formData = this._buildSelfieFormData(request);
+    appendJsonPart(
+      formData,
+      "user_details",
+      userDetailsToWire(request.userDetails),
+    );
+    this._appendPartnerConfigParts(formData);
+    this._appendConsentAndMetadata(formData, request.consent, request.metadata);
+    return this._postMultipart("/v3/registration", formData);
+  }
+
+  /**
+   * v3 smart-selfie authentication. Same notes as
+   * `smartSelfieEnrollment` — canonical path is `/v3/authentication`,
+   * the `enhanced` flag is intent-only, and `user_details` rides as a
+   * JSON multipart part.
+   */
+  async smartSelfieAuthentication(
+    request: SmartSelfieAuthenticationRequest,
+  ): Promise<JobSubmissionResponse> {
+    const formData = this._buildSelfieFormData(request);
+    appendStringPart(formData, "user_id", request.userId);
+    appendJsonPart(
+      formData,
+      "user_details",
+      userDetailsToWire(request.userDetails),
+    );
+    this._appendPartnerConfigParts(formData);
+    this._appendConsentAndMetadata(formData, request.consent, request.metadata);
+    return this._postMultipart("/v3/authentication", formData);
+  }
+
+  async enhancedKyc(
+    request: EnhancedKycRequest,
+  ): Promise<JobSubmissionResponse> {
+    // Multipart/form-data wire format — server rejects JSON bodies
+    // with `415 — Unsupported Media Type. Required Content-Type is
+    // multipart/form-data`.
+    const formData = new FormData();
+    this._appendIdFields(formData, request.params);
+    appendJsonPart(
+      formData,
+      "user_details",
+      userDetailsToWire(request.userDetails),
+    );
+    if (request.params.bankCode) {
+      appendStringPart(formData, "bank_code", request.params.bankCode);
+    }
+    // TS property `mobileOperator` maps to wire key `operator`.
+    if (request.params.mobileOperator) {
+      appendStringPart(formData, "operator", request.params.mobileOperator);
+    }
+    this._appendPartnerConfigParts(formData);
+    this._appendConsentAndMetadata(formData, request.consent, request.metadata);
+    return this._postMultipart("/v3/enhanced_kyc", formData);
+  }
+
+  async biometricKyc(
+    request: BiometricKycRequest,
+  ): Promise<JobSubmissionResponse> {
+    const useEnrolled = request.params.useEnrolledImage;
+    const formData = this._buildSelfieFormData(request);
+    this._appendIdFields(formData, request.params);
+    appendJsonPart(
+      formData,
+      "user_details",
+      userDetailsToWire(request.userDetails),
+    );
+    if (useEnrolled) {
+      appendStringPart(formData, "use_enrolled_image", "true");
+    }
+    // `callback_url` and `partner_params` are sourced exclusively from
+    // `PartnerConfig` — symmetric with Enhanced KYC and the canonical
+    // SDKs. The `callback-url` HTTP header (attached by
+    // `SmileAuthInterceptor`) rides on every request independently.
+    this._appendPartnerConfigParts(formData);
+    this._appendConsentAndMetadata(formData, request.consent, request.metadata);
+    return this._postMultipart("/v3/biometric_kyc", formData);
+  }
+
+  async documentVerification(
+    request: DocumentVerificationRequest,
+  ): Promise<JobSubmissionResponse> {
+    return this._postDocumentVerification(request, "/v3/document_verification");
+  }
+
+  async enhancedDocumentVerification(
+    request: EnhancedDocumentVerificationRequest,
+  ): Promise<JobSubmissionResponse> {
+    return this._postDocumentVerification(
+      request,
+      "/v3/enhanced_document_verification",
+    );
+  }
+
+  private async _postDocumentVerification(
+    request: DocumentVerificationRequest | EnhancedDocumentVerificationRequest,
+    url: string,
+  ): Promise<JobSubmissionResponse> {
+    const formData = this._buildSelfieFormData(request);
+    appendFilePart(formData, "document", request.frontDocument);
+    if (request.backDocument) {
+      appendFilePart(formData, "document_back", request.backDocument);
+    }
+    appendStringPart(formData, "country", request.country);
+    if (request.idType) {
+      appendStringPart(formData, "id_type", request.idType);
+    }
+    appendJsonPart(
+      formData,
+      "user_details",
+      userDetailsToWire(request.userDetails),
+    );
+    this._appendPartnerConfigParts(formData);
+    this._appendConsentAndMetadata(formData, request.consent, request.metadata);
+    return this._postMultipart(url, formData);
+  }
+
+  // --- internals ---------------------------------------------------------
+
+  /**
+   * Build the selfie + liveness portion of a multipart form. No
+   * `user_id` / `job_id` / `partner_id` form fields (partner-id rides
+   * the auth header `smileid-partner-id`). Consent + metadata are
+   * appended separately by `_appendConsentAndMetadata` so callers
+   * (biometric_kyc, document_verification) can inject extra fields
+   * between selfie and consent in the multipart order.
+   *
+   * `expectedLivenessCount` is the expected number of liveness frames
+   * for this submission — derived from the decoded `sdk_config` claim
+   * when present, otherwise the `ScanPerformanceProfile` default (7).
+   */
+  private _buildSelfieFormData(request: {
+    readonly selfieImage: string;
+    readonly livenessImages: readonly string[];
+    readonly expectedLivenessImageCount: number;
+  }): FormData {
+    SmileIDAPI._validateLivenessCount(
+      request.livenessImages,
+      request.expectedLivenessImageCount,
+    );
+    const formData = new FormData();
+    appendFilePart(formData, "selfie_image", request.selfieImage);
+    for (const liveness of request.livenessImages) {
+      appendFilePart(formData, "liveness_images", liveness);
+    }
+    return formData;
+  }
+
+  /**
+   * Validates that the number of captured liveness images matches the
+   * expected count. A drift in either direction is surfaced here before
+   * the request hits the network so the mismatch is debuggable rather
+   * than swallowed by a generic 400.
+   *
+   * The expected count is derived from the `sdk_config` JWT claim's
+   * `livenessImageCount` when present (default 7 without a claim).
+   */
+  private static _validateLivenessCount(
+    livenessImages: readonly string[],
+    expectedCount: number,
+  ): void {
+    if (livenessImages.length !== expectedCount) {
+      throw new LivenessFrameCountException({
+        expected: expectedCount,
+        actual: livenessImages.length,
+      });
+    }
+  }
+
+  /**
+   * Append the three top-level non-PII KYC string fields (`id_type`,
+   * `id_number`, `country`). PII fields move into the `user_details`
+   * JSON part; partner-supplied per-job overrides (`callback_url`,
+   * `partner_params`, `use_enrolled_image`) are appended by the
+   * endpoint-specific path.
+   */
+  private _appendIdFields(
+    formData: FormData,
+    params: {
+      readonly idType: string;
+      readonly idNumber: string;
+      readonly country: string;
+    },
+  ): void {
+    appendStringPart(formData, "id_type", params.idType);
+    appendStringPart(formData, "id_number", params.idNumber);
+    appendStringPart(formData, "country", params.country);
+  }
+
+  /**
+   * Append the partner-config-level `callback_url` + `partner_params`
+   * multipart parts on Enhanced KYC submissions. Biometric KYC has its
+   * own per-job override path that already prefers `request.params.*`
+   * over the partner config and is handled inline; this helper covers
+   * the no-per-job-override case for Enhanced KYC.
+   *
+   * `callback_url` rides as a string part; `partner_params` as a JSON
+   * part. The `callback-url` HTTP header (attached by
+   * `SmileAuthInterceptor`) is independent and is preserved on every
+   * request regardless of this helper.
+   */
+  private _appendPartnerConfigParts(formData: FormData): void {
+    const callbackUrl = this._partnerConfig.callbackUrl;
+    if (callbackUrl) {
+      appendStringPart(formData, "callback_url", callbackUrl);
+    }
+    const partnerParams = this._partnerConfig.partnerParams;
+    if (partnerParams) {
+      appendJsonPart(formData, "partner_params", partnerParams);
+    }
+  }
+
+  /**
+   * Append `consent` + `metadata` as plain text form fields carrying
+   * JSON-string values. The server's multipart parser reads these as
+   * text form fields and JSON-parses the body by field name; tagging
+   * the part with `Content-Type: application/json` causes the parser
+   * to reject the part as "missing or invalid".
+   *
+   * The `metadata` snapshot is built by the request-construction site
+   * (the flow navigation manager) and travels on the request — this
+   * method serializes the snapshot it is handed rather than generating
+   * one, so a single per-flow metadata factory backs every submission.
+   */
+  private _appendConsentAndMetadata(
+    formData: FormData,
+    consent: ConsentInformation,
+    metadata: UseSmileIDMetadata,
+  ): void {
+    // Transform the JS camelCase shape into the canonical snake_case
+    // wire JSON before serialization. The server validates the wire
+    // shape exactly — `consent.granted` (snake_case via `granted`
+    // already) and `consent.granted_at` are required.
+    appendJsonPart(formData, "consent", {
+      granted: consent.granted,
+      granted_at: consent.grantedAt,
+      notice_language: consent.noticeLanguage,
+      notice_privacy_policy_url: consent.noticePrivacyPolicyUrl,
+    });
+    appendJsonPart(formData, "metadata", metadata.toEntries());
+  }
+
+  private async _postMultipart(
+    url: string,
+    body: FormData,
+  ): Promise<JobSubmissionResponse> {
+    const response = await this._client.post(url, body, {
+      headers: {
+        "Content-Type": "multipart/form-data",
+      },
+      ...SIGNED_JOB_SUBMISSION_FLAGS,
+    });
+    return mapJobSubmissionResponse(response.data);
+  }
+}
+
+/**
+ * Map the snake_case wire JSON to camelCase `JobSubmissionResponse`.
+ *
+ * Throws [NetworkResponseParseException] when the body is missing or
+ * shaped wrong — the typed exception flows through `mapAxiosError`'s
+ * idempotent pass-through so partner code catching on
+ * `e instanceof NetworkResponseParseException` sees it cleanly,
+ * distinct from `NetworkUnknownException` (which would otherwise
+ * swallow shape mismatches and bury them behind a generic message).
+ */
+function mapJobSubmissionResponse(data: unknown): JobSubmissionResponse {
+  if (data == null || typeof data !== "object" || Array.isArray(data)) {
+    throw new NetworkResponseParseException({
+      message:
+        "SmileIDAPI: server returned an empty or non-object response body.",
+    });
+  }
+  const raw = data as Record<string, unknown>;
+  // Required string fields must be present and string-typed — a missing
+  // or non-string value is a malformed response, surfaced as a parse
+  // failure rather than silently coerced to "".
+  const requireString = (value: unknown, field: string): string => {
+    if (typeof value !== "string") {
+      throw new NetworkResponseParseException({
+        message: `SmileIDAPI: response is missing the required string field '${field}'.`,
+      });
+    }
+    return value;
+  };
+  const result: JobSubmissionResponse = {
+    jobId: requireString(raw["job_id"] ?? raw["jobId"], "job_id"),
+    userId: requireString(raw["user_id"] ?? raw["userId"], "user_id"),
+    status: requireString(raw["status"], "status"),
+    message: requireString(raw["message"], "message"),
+  };
+  const createdAtRaw = raw["created_at"] ?? raw["createdAt"];
+  if (typeof createdAtRaw === "string" && createdAtRaw.length > 0) {
+    return { ...result, createdAt: createdAtRaw };
+  }
+  return result;
+}
+
+/**
+ * Convert `UserDetails` to the snake_case wire shape. Optional fields
+ * are trimmed; blank values are omitted.
+ */
+function userDetailsToWire(details: UserDetails): Record<string, string> {
+  const wire: Record<string, string> = {
+    given_names: details.givenNames,
+    last_name: details.lastName,
+  };
+  const trimmedEmail = details.email?.trim();
+  if (trimmedEmail) {
+    wire["email"] = trimmedEmail;
+  }
+  const trimmedPhone = details.phoneNumber?.trim();
+  if (trimmedPhone) {
+    wire["phone_number"] = trimmedPhone;
+  }
+  return wire;
+}
+
+/**
+ * RN-style `FormData.append` for a string part. Used as the underlying
+ * primitive for `appendJsonPart` (which serializes a JSON value into a
+ * string part).
+ */
+function appendStringPart(
+  formData: FormData,
+  name: string,
+  value: string,
+): void {
+  // Cast to any — RN's FormData type signature predates the
+  // {uri, name, type} object form below, but the runtime accepts both
+  // strings and the file-descriptor object. `any` here is the
+  // standard RN workaround.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (formData as any).append(name, value);
+}
+
+/**
+ * Append a JSON value as a plain text multipart form field. The field
+ * carries the JSON-serialized value as its body; the part is NOT
+ * tagged with a `Content-Type: application/json` header. The live
+ * server's multipart parser expects these fields (`user_details`,
+ * `consent`, `metadata`, `partner_params`) as text form fields and
+ * rejects parts tagged `application/json` as "missing or invalid".
+ * This matches the Postman canonical `"type": "text"` wire shape.
+ */
+function appendJsonPart(
+  formData: FormData,
+  name: string,
+  value: unknown,
+): void {
+  const json = JSON.stringify(value);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (formData as any).append(name, json);
+}
+
+/**
+ * Append a JPEG file by URI. RN's `FormData` accepts a file-descriptor
+ * object `{ uri, name, type }`; axios serializes it as a binary part.
+ * The native side handles the file read.
+ */
+function appendFilePart(formData: FormData, name: string, uri: string): void {
+  const fileName = uri.split("/").pop() ?? `${name}.jpg`;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (formData as any).append(name, {
+    uri,
+    name: fileName,
+    type: "image/jpeg",
+  });
+}
+
+/**
+ * Construct the axios instance used by `SmileIDAPI`. Lives here so
+ * the factory and the auth-interceptor can share a single call site
+ * for `baseURL` + timeout setup.
+ */
+export function buildAxiosClient(config: NetworkConfig): AxiosInstance {
+  const partnerConfig = config.config?.partnerConfig;
+  const useSandbox = partnerConfig?.useSandbox ?? true;
+  const baseURL = useSandbox ? SANDBOX_BASE_URL : PROD_BASE_URL;
+
+  // Public API expresses timeouts in seconds; axios takes ms. Default
+  // is 120 s — matches the per-phase ceiling on the other platforms'
+  // network stacks.
+  const callSeconds = config.timeouts?.call ?? 120;
+  return axios.create({
+    baseURL,
+    timeout: callSeconds * 1000,
+    // axios honors connect/read individually only on Node; on RN we
+    // get a single ceiling, so the configured `call` is the overall
+    // mark at which a hung request fails.
+  });
+}
+
+export {
+  SmileAuthInterceptor,
+  attachLoggingInterceptor,
+  PROD_BASE_URL,
+  SANDBOX_BASE_URL,
+};