@smileid/usesmileid 12.0.0-beta01

package/src/data/dsl/builder/__tests__/interceptor_config_builder.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it, vi } from "vitest";
+import axios, { AxiosHeaders, type InternalAxiosRequestConfig } from "axios";
+import {
+  InterceptorConfigBuilder,
+  LoggingInterceptorBuilder,
+} from "../interceptor_config_builder";
+import { LogLevel } from "../../../../core/models/network_config";
+
+/**
+ * The builder's public surface is the DSL — the network factory
+ * consumes whatever shape `add(...)` collected. These tests pin down
+ *
+ *   - `build()` returns the exact list a partner `add(...)`-ed
+ *   - `gzip()` produces an interceptor that stamps `Content-Encoding`
+ *   - `logging(...)` accepts a configure block and threads it through
+ *     to the underlying logging interceptor (we verify by attaching to
+ *     a real axios instance and inspecting the registered handler)
+ */
+describe("InterceptorConfigBuilder", () => {
+  describe("add / build", () => {
+    it("returns the interceptors `add()`-ed by the partner, in order", () => {
+      const builder = new InterceptorConfigBuilder();
+      const first = { attach: () => {} };
+      const second = { attach: () => {} };
+      const third = { attach: () => {} };
+
+      builder.add(first);
+      builder.add(second);
+      builder.add(third);
+
+      const result = builder.build();
+      expect(result).toEqual([first, second, third]);
+    });
+
+    it("freezes the returned list so partners can't mutate the internal state", () => {
+      const builder = new InterceptorConfigBuilder();
+      builder.add({ attach: () => {} });
+      const result = builder.build();
+      expect(Object.isFrozen(result)).toBe(true);
+    });
+
+    it("returns an empty frozen list when no interceptors were added", () => {
+      const builder = new InterceptorConfigBuilder();
+      const result = builder.build();
+      expect(result).toEqual([]);
+      expect(Object.isFrozen(result)).toBe(true);
+    });
+  });
+
+  describe("gzip()", () => {
+    it("returns an attach-shaped interceptor", () => {
+      const builder = new InterceptorConfigBuilder();
+      const interceptor = builder.gzip();
+      expect(interceptor).toHaveProperty("attach");
+      expect(typeof (interceptor as { attach: unknown }).attach).toBe(
+        "function",
+      );
+    });
+
+    it("stamps Accept-Encoding: gzip on the request", async () => {
+      // Hint-only — match the iOS interceptor's behavior. The prior
+      // `Content-Encoding: gzip` stamp was incorrect because the body
+      // was never compressed; servers strict-parsing the header would
+      // reject the request.
+      const builder = new InterceptorConfigBuilder();
+      const client = axios.create();
+      const interceptor = builder.gzip() as {
+        attach: (client: typeof axios) => void;
+      };
+      interceptor.attach(client as unknown as typeof axios);
+
+      const handlers = (
+        client.interceptors.request as unknown as {
+          handlers: Array<{
+            fulfilled: (
+              config: InternalAxiosRequestConfig,
+            ) =>
+              | InternalAxiosRequestConfig
+              | Promise<InternalAxiosRequestConfig>;
+          }>;
+        }
+      ).handlers;
+      const headers = new AxiosHeaders();
+      const fakeConfig = { headers } as InternalAxiosRequestConfig;
+      const out = await handlers[handlers.length - 1]!.fulfilled(fakeConfig);
+      expect(out.headers.get("Accept-Encoding")).toBe("gzip");
+      // And explicitly does NOT lie about the request body being
+      // gzipped — the prior buggy header is gone.
+      expect(out.headers.get("Content-Encoding")).toBeUndefined();
+    });
+  });
+
+  describe("logging()", () => {
+    it("returns an attach-shaped interceptor with no configure block", () => {
+      const builder = new InterceptorConfigBuilder();
+      const interceptor = builder.logging();
+      expect(interceptor).toHaveProperty("attach");
+      expect(typeof (interceptor as { attach: unknown }).attach).toBe(
+        "function",
+      );
+    });
+
+    it("threads the configure block's level + redactHeaders through", () => {
+      const builder = new InterceptorConfigBuilder();
+      const seen: LoggingInterceptorBuilder[] = [];
+      const interceptor = builder.logging((l) => {
+        seen.push(l);
+        l.level = LogLevel.body;
+        l.redactHeaders = ["x-secret"];
+      });
+
+      expect(seen).toHaveLength(1);
+      expect(seen[0]!.level).toBe(LogLevel.body);
+      expect(seen[0]!.redactHeaders).toEqual(["x-secret"]);
+
+      // Attaching against a real axios client should not throw — the
+      // underlying logging interceptor is exercised by its own test
+      // suite; here we only assert this builder wires it.
+      const client = axios.create();
+      const handler = interceptor as { attach: (client: unknown) => void };
+      expect(() => handler.attach(client)).not.toThrow();
+    });
+
+    it("defaults to LogLevel.basic and an empty redact list", () => {
+      const builder = new InterceptorConfigBuilder();
+      const interceptor = builder.logging();
+      // Attach is callable and respects defaults — exercise by
+      // attaching, then make sure the request pipeline still works.
+      const client = axios.create();
+      const handler = interceptor as { attach: (client: unknown) => void };
+      handler.attach(client);
+
+      const directBuilder = new LoggingInterceptorBuilder();
+      expect(directBuilder.enabled).toBe(true);
+      expect(directBuilder.level).toBe(LogLevel.basic);
+      expect(directBuilder.redactHeaders).toEqual([]);
+    });
+
+    it("does not log when level is none (logging interceptor is a no-op)", async () => {
+      const builder = new InterceptorConfigBuilder();
+      const interceptor = builder.logging((l) => {
+        l.level = LogLevel.none;
+      });
+      const client = axios.create();
+      const handler = interceptor as { attach: (client: unknown) => void };
+      handler.attach(client);
+
+      const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+      const handlers = (
+        client.interceptors.request as unknown as {
+          handlers: Array<{
+            fulfilled: (
+              config: InternalAxiosRequestConfig,
+            ) =>
+              | InternalAxiosRequestConfig
+              | Promise<InternalAxiosRequestConfig>;
+          }>;
+        }
+      ).handlers;
+      const headers = new AxiosHeaders();
+      const fakeConfig = {
+        headers,
+        method: "POST",
+        url: "/test",
+      } as InternalAxiosRequestConfig;
+      await handlers[handlers.length - 1]!.fulfilled(fakeConfig);
+
+      expect(logSpy).not.toHaveBeenCalled();
+      logSpy.mockRestore();
+    });
+  });
+});

package/src/data/dsl/builder/cache_config_builder.ts

@@ -0,0 +1,26 @@
+import type { CacheConfig } from "../../../core/models/network_config";
+
+/**
+ * DSL builder for HTTP response cache settings.
+ *
+ * `maxSize` is in bytes; the default of 50 MB covers typical
+ * verification flows without aggressive trimming.
+ */
+export class CacheConfigBuilder {
+  enabled = true;
+  /** Bytes — default 50 MB. */
+  maxSize = 50 * 1024 * 1024;
+
+  /**
+   * Multiplier helper: `c.megabytes(50)` evaluates to `50 * 1024 * 1024`
+   * bytes. TypeScript has no number extensions, so this lives as a
+   * builder method.
+   */
+  megabytes(count: number): number {
+    return count * 1024 * 1024;
+  }
+
+  build(): CacheConfig {
+    return Object.freeze({ enabled: this.enabled, maxSize: this.maxSize });
+  }
+}

package/src/data/dsl/builder/config_builder.ts

@@ -0,0 +1,125 @@
+import type { JobType } from "../../../core/models/job_type";
+import {
+  LogLevel,
+  type NetworkInnerConfig,
+  type NetworkLoggingConfig,
+  type PartnerConfig,
+} from "../../../core/models/network_config";
+
+/**
+ * DSL builder for partner identity and per-job environment.
+ *
+ * Set `partnerId` and choose `useSandbox` for the dev API or production.
+ * `callbackUrl` is the partner's webhook endpoint.
+ *
+ * The HTTP auth credential (`token`) and refresh callback
+ * (`onTokenExpired`) live on the parent {@link ConfigBuilder} instead —
+ * authentication is a network-level credential, not part of partner
+ * identity.
+ */
+export class PartnerConfigBuilder {
+  partnerId = "";
+  callbackUrl = "";
+  useSandbox = false;
+  /**
+   * Optional partner-supplied key/value metadata. Forwarded onto the
+   * `partner_params` JSON multipart form part on Enhanced / Biometric
+   * KYC submissions when set.
+   */
+  partnerParams?: Record<string, string>;
+
+  build(): PartnerConfig {
+    return Object.freeze({
+      partnerId: this.partnerId,
+      callbackUrl: this.callbackUrl,
+      useSandbox: this.useSandbox,
+      ...(this.partnerParams !== undefined
+        ? { partnerParams: Object.freeze({ ...this.partnerParams }) }
+        : {}),
+    });
+  }
+}
+
+/**
+ * DSL builder for HTTP request/response logging.
+ *
+ * `level` controls verbosity (none / basic / headers / body); the
+ * built-in auth interceptor already redacts sensitive headers
+ * (`SmileID-Token`, `smileid-partner-id`). Partners can extend the
+ * redaction list with their own proxy-injected headers.
+ */
+export class LoggingConfigBuilder {
+  enabled = true;
+  level: LogLevel = LogLevel.basic;
+  redactHeaders: readonly string[] = [];
+
+  build(): NetworkLoggingConfig {
+    return Object.freeze({
+      enabled: this.enabled,
+      level: this.level,
+      redactHeaders: Object.freeze([...this.redactHeaders]),
+    });
+  }
+}
+
+/**
+ * DSL builder for the main network job + auth + partner block.
+ *
+ * Holds `jobType`, the HTTP auth credentials (`token` + `onTokenExpired`),
+ * plus nested `partnerConfig` and `logging` sub-builders. The auth
+ * credential sits at this level — separate from `partnerConfig` which
+ * carries partner identity — because authentication is a network-level
+ * credential, not part of partner identity.
+ *
+ * Sub-builders are constructed lazily on first access so the partner can
+ * omit blocks they don't need.
+ */
+export class ConfigBuilder {
+  jobType?: JobType;
+
+  /**
+   * Short-lived v3 auth token issued by `/v3/token`. The partner
+   * application is responsible for exchanging its API key for a token
+   * before invoking the SDK and supplying the result here. Stamped as
+   * the `smileid-token` HTTP header on every authenticated request.
+   */
+  token = "";
+
+  /**
+   * Optional async refresh callback invoked when the server responds
+   * with `401 Unauthorized`. The callback receives the token the SDK
+   * was using and returns a fresh token; the SDK then retries the
+   * original request once with the new value. Concurrent 401s collapse
+   * to a single callback invocation via the SDK's shared `TokenHolder`.
+   * If the callback throws or the retry also returns 401, the original
+   * 401 response is surfaced unchanged.
+   */
+  onTokenExpired?: (previousToken: string) => Promise<string>;
+
+  private _partnerConfig?: PartnerConfigBuilder;
+  private _logging?: LoggingConfigBuilder;
+
+  partnerConfig(block: (p: PartnerConfigBuilder) => void): void {
+    if (!this._partnerConfig) this._partnerConfig = new PartnerConfigBuilder();
+    block(this._partnerConfig);
+  }
+
+  logging(block: (l: LoggingConfigBuilder) => void): void {
+    if (!this._logging) this._logging = new LoggingConfigBuilder();
+    block(this._logging);
+  }
+
+  build(): NetworkInnerConfig {
+    return Object.freeze({
+      ...(this.jobType !== undefined ? { jobType: this.jobType } : {}),
+      ...(this.token !== "" ? { token: this.token } : {}),
+      ...(this.onTokenExpired !== undefined
+        ? { onTokenExpired: this.onTokenExpired }
+        : {}),
+      ...(this._partnerConfig
+        ? { partnerConfig: this._partnerConfig.build() }
+        : {}),
+      ...(this._logging ? { logging: this._logging.build() } : {}),
+    });
+  }
+}

package/src/data/dsl/builder/interceptor_config_builder.ts

@@ -0,0 +1,81 @@
+import type { AxiosInstance } from "axios";
+import { attachLoggingInterceptor } from "../../api/interceptors/logging_interceptor";
+import { createGzipInterceptor } from "../../api/interceptors/gzip_interceptor";
+import {
+  LogLevel,
+  type Interceptor,
+  type NetworkLoggingConfig,
+} from "../../../core/models/network_config";
+
+/**
+ * DSL builder for registering custom HTTP interceptors.
+ *
+ * Partners compose the interceptor list via `add(...)`. Two
+ * convenience factories — `gzip()` and `logging(...)` — produce
+ * ready-to-add `Interceptor` instances.
+ *
+ * Usage:
+ * ```ts
+ * b.network((n) => {
+ *   n.interceptors((i) => {
+ *     i.add(i.gzip());
+ *     i.add(i.logging((l) => { l.level = LogLevel.body; }));
+ *     i.add(myCustomInterceptor);
+ *   });
+ * });
+ * ```
+ */
+export class InterceptorConfigBuilder {
+  private _interceptors: Interceptor[] = [];
+
+  add(interceptor: Interceptor): void {
+    this._interceptors.push(interceptor);
+  }
+
+  /**
+   * Returns an interceptor that stamps `Accept-Encoding: gzip` on
+   * every outbound request. Hint-only — the SDK does not pull in a
+   * JS gzip dependency to compress request bodies. See
+   * [createGzipInterceptor] for the rationale.
+   */
+  gzip(): Interceptor {
+    return createGzipInterceptor();
+  }
+
+  /**
+   * Returns a logging interceptor configured by `configure`. The
+   * partner block mutates a `LoggingInterceptorBuilder` carrying
+   * `level` and `redactHeaders`.
+   */
+  logging(
+    configure?: (builder: LoggingInterceptorBuilder) => void,
+  ): Interceptor {
+    const builder = new LoggingInterceptorBuilder();
+    if (configure) {
+      configure(builder);
+    }
+    const loggingConfig: NetworkLoggingConfig = Object.freeze({
+      enabled: builder.enabled,
+      level: builder.level,
+      redactHeaders: Object.freeze([...builder.redactHeaders]),
+    });
+    return {
+      attach(client: AxiosInstance): void {
+        attachLoggingInterceptor(client, loggingConfig);
+      },
+    };
+  }
+
+  build(): readonly Interceptor[] {
+    return Object.freeze([...this._interceptors]);
+  }
+}
+
+/**
+ * Configuration carrier for `InterceptorConfigBuilder.logging(...)`.
+ */
+export class LoggingInterceptorBuilder {
+  enabled = true;
+  level: LogLevel = LogLevel.basic;
+  redactHeaders: readonly string[] = [];
+}

package/src/data/dsl/builder/retry_config_builder.ts

@@ -0,0 +1,36 @@
+import {
+  RetryStrategy,
+  type RetryConfig,
+} from "../../../core/models/network_config";
+
+export { RetryStrategy };
+
+/**
+ * DSL builder for request retry behaviour.
+ *
+ * Defaults to exponential backoff with 3 attempts, 1 s initial delay,
+ * 32 s ceiling, ±20% jitter. `fixedDelay` is honoured only when
+ * `strategy = RetryStrategy.fixed`.
+ */
+export class RetryConfigBuilder {
+  maxAttempts = 3;
+  strategy: RetryStrategy = RetryStrategy.exponential;
+  initialDelay = 1;
+  multiplier = 2;
+  maxDelay = 32;
+  /** ±20% randomized jitter on the computed delay, in [0, 1]. */
+  jitter = 0.2;
+  fixedDelay = 1;
+
+  build(): RetryConfig {
+    return Object.freeze({
+      maxAttempts: this.maxAttempts,
+      strategy: this.strategy,
+      initialDelay: this.initialDelay,
+      multiplier: this.multiplier,
+      maxDelay: this.maxDelay,
+      jitter: this.jitter,
+      fixedDelay: this.fixedDelay,
+    });
+  }
+}

package/src/data/dsl/builder/timeout_config_builder.ts

@@ -0,0 +1,24 @@
+import type { TimeoutConfig } from "../../../core/models/network_config";
+
+/**
+ * DSL builder for per-phase HTTP timeouts in **seconds**.
+ *
+ * `connect` is the connection-establishment phase; `read` and `write`
+ * cap the individual socket-read / socket-write operations; `call` is
+ * the end-to-end ceiling for the whole request including retries.
+ */
+export class TimeoutConfigBuilder {
+  connect = 60;
+  read = 60;
+  write = 60;
+  call = 120;
+
+  build(): TimeoutConfig {
+    return Object.freeze({
+      connect: this.connect,
+      read: this.read,
+      write: this.write,
+      call: this.call,
+    });
+  }
+}

package/src/data/dsl/use_smile_id_network_builder.ts

@@ -0,0 +1,69 @@
+import type { NetworkConfig } from "../../core/models/network_config";
+import { CacheConfigBuilder } from "./builder/cache_config_builder";
+import { ConfigBuilder } from "./builder/config_builder";
+import { InterceptorConfigBuilder } from "./builder/interceptor_config_builder";
+import { RetryConfigBuilder } from "./builder/retry_config_builder";
+import { TimeoutConfigBuilder } from "./builder/timeout_config_builder";
+
+/**
+ * DSL builder for the complete network stack configuration.
+ *
+ * Three levels of closure nesting:
+ *
+ *   network → config → partnerConfig
+ *                  └→ logging
+ *           → timeouts
+ *           → cache
+ *           → retry
+ *           → interceptors
+ *
+ * Mutable-receiver pattern: each closure mutates a builder, which
+ * snapshots its state via `build()` once the partner's callback
+ * returns. Builders are constructed lazily on first access so the
+ * partner can omit blocks they don't need.
+ */
+export class UseSmileIDNetworkBuilder {
+  private _config?: ConfigBuilder;
+  private _timeouts?: TimeoutConfigBuilder;
+  private _cache?: CacheConfigBuilder;
+  private _retry?: RetryConfigBuilder;
+  private _interceptors?: InterceptorConfigBuilder;
+
+  config(block: (c: ConfigBuilder) => void): void {
+    if (!this._config) this._config = new ConfigBuilder();
+    block(this._config);
+  }
+
+  timeouts(block: (t: TimeoutConfigBuilder) => void): void {
+    if (!this._timeouts) this._timeouts = new TimeoutConfigBuilder();
+    block(this._timeouts);
+  }
+
+  cache(block: (c: CacheConfigBuilder) => void): void {
+    if (!this._cache) this._cache = new CacheConfigBuilder();
+    block(this._cache);
+  }
+
+  retry(block: (r: RetryConfigBuilder) => void): void {
+    if (!this._retry) this._retry = new RetryConfigBuilder();
+    block(this._retry);
+  }
+
+  interceptors(block: (i: InterceptorConfigBuilder) => void): void {
+    if (!this._interceptors)
+      this._interceptors = new InterceptorConfigBuilder();
+    block(this._interceptors);
+  }
+
+  build(): NetworkConfig {
+    return Object.freeze({
+      ...(this._config ? { config: this._config.build() } : {}),
+      ...(this._timeouts ? { timeouts: this._timeouts.build() } : {}),
+      ...(this._cache ? { cache: this._cache.build() } : {}),
+      ...(this._retry ? { retry: this._retry.build() } : {}),
+      ...(this._interceptors
+        ? { interceptors: this._interceptors.build() }
+        : {}),
+    });
+  }
+}