@incodetech/core 2.0.0 → 2.0.1-rc.0

package/dist/session.d.ts

@@ -0,0 +1,217 @@
+import "./camera-DBSxa6ML.js";
+import "./types-CFV9G_7j.js";
+import { a as RegulationTypes } from "./types-BP1m8VRw.js";
+import { n as GetFinishStatusFn, r as getFinishStatus, t as FinishStatus } from "./flowCompletionService-DhkT4SRY.js";
+
+//#region src/internal/fingerprint/types.d.ts
+
+type DeviceFingerprintResult = {
+  success: boolean;
+  sessionStatus: string;
+  showMandatoryConsent?: boolean;
+  regulationType?: RegulationTypes;
+};
+//#endregion
+//#region src/internal/session/sessionService.d.ts
+type CreateSessionOptions = {
+  /** The configuration/flow ID from the Incode dashboard */
+  configurationId: string;
+  /** External ID to associate with this session */
+  externalId?: string;
+  /** External customer ID */
+  externalCustomerId?: string;
+  /** Language for the session (e.g., 'en-US', 'es-MX') */
+  language?: string;
+  /** Custom fields to attach to the session */
+  customFields?: Record<string, unknown>;
+  /** UUID for continuing an existing session */
+  uuid?: string;
+  /** QR anti-phishing token for continuing a phishing-resistant session from a mobile link */
+  urlUuid?: string;
+  /** Interview ID for continuing an existing interview */
+  interviewId?: string;
+  /** Hint forwarded to POST /omni/start as `loginHint` (e.g. from `auth_hint` URL param for identity search). */
+  loginHint?: string;
+};
+type Session = {
+  token: string;
+  interviewId: string;
+  uuid?: string;
+  regulationType?: string;
+  showMandatoryConsent?: boolean;
+};
+type ValidateQrUuidOptions = {
+  onboardingId: string | null;
+  urlUuid: string;
+};
+type QrValidationResult = {
+  urlUuid: string;
+};
+/**
+ * HTTP status codes the QR validation endpoint emits, keyed by their semantic
+ * name. Hosts switch on these to render distinct messaging — `invalidQRuuid`
+ * for an unknown/expired link, `onboardingUrlAlreadyUsed` for a one-time link
+ * that has already been consumed.
+ */
+declare const QR_VALIDATION_ERROR_CODES: {
+  readonly expiredUUID: 4026;
+  readonly invalidQRuuid: 4081;
+  readonly onboardingUrlAlreadyUsed: 4083;
+};
+type QrValidationErrorCode = (typeof QR_VALIDATION_ERROR_CODES)[keyof typeof QR_VALIDATION_ERROR_CODES];
+type RefreshQrUrlUuidOptions = {
+  /** QR anti-phishing token from the incoming URL. When empty/undefined, the call is a no-op. */
+  urlUuid?: string;
+  /** Onboarding session UUID, if known. Pass `null` or omit when the caller has no session yet. */
+  onboardingId?: string | null;
+  /** Invoked with the refreshed `urlUuid` once the server rotates it. */
+  onRefreshed?: (urlUuid: string) => void;
+};
+type BootstrapSessionOptions = CreateSessionOptions & {
+  /** Invoked with the rotated `urlUuid` after `validateQrUuid` succeeds. Hosts
+   *  typically use this to update the address bar via `history.replaceState`. */
+  onUrlUuidRefreshed?: (urlUuid: string) => void;
+};
+declare class QrValidationError extends Error {
+  readonly status: number;
+  readonly statusText: string;
+  constructor(status: number, statusText: string);
+}
+/**
+ * Creates a new onboarding session.
+ *
+ * @param apiKey - The API key from the Incode dashboard
+ * @param options - Session creation options
+ * @param signal - Optional AbortSignal for request cancellation
+ * @returns The created session with token
+ *
+ * @example
+ * ```ts
+ * const session = await createSession('your-api-key', {
+ *   configurationId: 'your-flow-id',
+ *   language: 'en-US',
+ * });
+ * console.log(session.token); // Use this token for subsequent API calls
+ * ```
+ */
+declare function createSession(apiKey: string, options: CreateSessionOptions, signal?: AbortSignal): Promise<Session>;
+/**
+ * Validates and rotates a QR anti-phishing URL UUID before creating a session.
+ *
+ * This call is unauthenticated; the `{ onboardingId, urlUuid }` pair itself
+ * acts as the credential. The server burns the incoming `urlUuid` and returns
+ * a freshly minted one that must be used in the subsequent `createSession`
+ * call.
+ *
+ * @param options - `{ onboardingId, urlUuid }` from the incoming URL
+ * @param signal - Optional AbortSignal for request cancellation
+ * @returns The refreshed `urlUuid` to use for the session
+ * @throws {QrValidationError} When the server rejects the validation request.
+ */
+declare function validateQrUuid(options: ValidateQrUuidOptions, signal?: AbortSignal): Promise<QrValidationResult>;
+/**
+ * One-shot QR phishing-resistance helper.
+ *
+ * When `urlUuid` is a non-empty string, burns the stale value via
+ * `validateQrUuid`, invokes `onRefreshed` with the fresh value, and returns
+ * it so callers can forward it into `createSession`. When `urlUuid` is
+ * absent, returns `undefined` without making any network call.
+ *
+ * Consolidates the rotation + callback logic shared by Flow self-loading and
+ * Workflow token-mode bootstraps.
+ *
+ * @throws {QrValidationError} When the server rejects the validation request.
+ */
+declare function refreshQrUrlUuid(options: RefreshQrUrlUuidOptions, signal?: AbortSignal): Promise<string | undefined>;
+/**
+ * Validates and rotates a QR anti-phishing `urlUuid` (when present), then
+ * creates a session bound to the refreshed value. When `urlUuid` is absent,
+ * behaves identically to {@link createSession}.
+ *
+ * Use this when the host owns session creation and wants the SDK to handle
+ * phishing-resistance rotation in a single call. For raw control, compose
+ * `refreshQrUrlUuid` and `createSession` directly.
+ *
+ * @throws {QrValidationError} When the server rejects the QR validation step.
+ *
+ * @example
+ * ```ts
+ * const session = await bootstrapSession(apiKey, {
+ *   configurationId,
+ *   urlUuid,
+ *   onUrlUuidRefreshed: (refreshed) => {
+ *     const url = new URL(window.location.href);
+ *     url.searchParams.set('url_uuid', refreshed);
+ *     window.history.replaceState({}, '', url);
+ *   },
+ * });
+ * ```
+ */
+declare function bootstrapSession(apiKey: string, options: BootstrapSessionOptions, signal?: AbortSignal): Promise<Session>;
+//#endregion
+//#region src/internal/featureConfig/types.d.ts
+type FeatureName = 'VIDEO_SELFIE_V2' | 'USE_CLIENT_GLARE' | 'USE_OPEN_VIDU' | 'DISABLE_IPIFY';
+type FeatureConfig = {
+  enabled: boolean;
+  feature: FeatureName;
+  config?: number | string;
+};
+type Features = {
+  features?: FeatureConfig[];
+  sessionIdentifier: string;
+};
+//#endregion
+//#region src/internal/session/sessionInitializer.d.ts
+type SessionInitOptions = {
+  /**
+   * Session token returned by `createSession`. Persisted on the HTTP client
+   * for the rest of the session.
+   *
+   * Optional only for internal re-triggers from inside flow/workflow loaders,
+   * where the token was already activated by an earlier `initializeSession`
+   * call. When omitted the function falls back to the currently registered
+   * token. Application code should always pass `token` explicitly.
+   */
+  token?: string;
+  /** Custom hosting app name for fingerprint */
+  hostingApp?: string;
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+};
+type SessionInitResult = {
+  features: Features;
+  disableIpify: boolean;
+  fingerprintSuccess: boolean;
+  fingerprintResult: DeviceFingerprintResult | undefined;
+};
+/**
+ * Activates a session by setting the auth token on the HTTP client and
+ * preloading session-scoped state.
+ *
+ * Performs:
+ * 1. Sets the token (and clears stale session-init cache if the token changed)
+ * 2. Fetches feature configuration from backend
+ * 3. Submits device fingerprint
+ * 4. Starts the analytics batcher so buffered events are flushed
+ *
+ * Results are cached per token. Calling again with the same token returns the
+ * cached result; calling with a different token re-initializes from scratch.
+ *
+ * @param options - Session activation options (`token` required)
+ * @returns Session initialization result with feature config
+ *
+ * @example
+ * ```ts
+ * await setup({ apiURL: 'https://api.incode.com' });
+ * const session = await createSession('api-key', options);
+ * const { features } = await initializeSession({ token: session.token });
+ *
+ * // Check feature flags
+ * if (isFeatureEnabled('DISABLE_IPIFY', features.features)) {
+ *   // Handle disabled ipify
+ * }
+ * ```
+ */
+declare function initializeSession(options?: SessionInitOptions): Promise<SessionInitResult>;
+//#endregion
+export { type BootstrapSessionOptions, type CreateSessionOptions, type FinishStatus, type GetFinishStatusFn, QR_VALIDATION_ERROR_CODES, QrValidationError, type QrValidationErrorCode, type QrValidationResult, type RefreshQrUrlUuidOptions, type Session, type SessionInitOptions, type SessionInitResult, type ValidateQrUuidOptions, bootstrapSession, createSession, getFinishStatus, initializeSession, refreshQrUrlUuid, validateQrUuid };

package/dist/session.esm.js

@@ -0,0 +1,9 @@
+import "./api-CESGtpbH.esm.js";
+import "./events-D6-e4vok.esm.js";
+import "./endpoints-CnN3SyDa.esm.js";
+import { c as QrValidationError, d as refreshQrUrlUuid, f as validateQrUuid, l as bootstrapSession, r as initializeSession, s as QR_VALIDATION_ERROR_CODES, u as createSession } from "./session-CGtQJJzB.esm.js";
+import "./IpifyProvider-D7jx52AL.esm.js";
+import "./browserSimulation-gxD8cSpM.esm.js";
+import { t as getFinishStatus } from "./flowCompletionService-P54yzGvA.esm.js";
+
+export { QR_VALIDATION_ERROR_CODES, QrValidationError, bootstrapSession, createSession, getFinishStatus, initializeSession, refreshQrUrlUuid, validateQrUuid };

package/dist/setup-C5AITV8m.d.ts

@@ -0,0 +1,254 @@
+import { n as WasmPipeline } from "./warmup-CEcppFiS.js";
+
+//#region src/setup.d.ts
+
+/**
+ * WASM warmup configuration. Path fields are optional; omitted values resolve to the Incode CDN defaults.
+ */
+type WasmConfig = {
+  /** Path to the WASM binary */
+  wasmPath?: string;
+  /** Path to the SIMD-optimized WASM binary (optional) */
+  wasmSimdPath?: string;
+  /** Path to the WASM glue code (paired with `wasmPath`) */
+  glueCodePath?: string;
+  /**
+   * Path to the SIMD-optimized WASM glue code (paired with `wasmSimdPath`).
+   * If omitted, defaults to a sibling `.js` derived from `wasmSimdPath`.
+   */
+  glueCodeSimdPath?: string;
+  /** Whether to use SIMD optimizations (default: true) */
+  useSimd?: boolean;
+  /** Which pipelines to preload models for */
+  pipelines?: WasmPipeline[];
+  /**
+   * Base path for ML model files. Models will be loaded from `${modelsBasePath}/${modelFileName}`.
+   * If not provided, models are expected in a 'models' subdirectory relative to the WASM binary.
+   */
+  modelsBasePath?: string;
+};
+/**
+ * Object form of the `encryption` option for {@link SetupOptions}. Reach for
+ * this when you need to pin the OAEP MGF1 hash; the boolean shorthand
+ * (`encryption: true`) is equivalent to `{}` and uses the SHA-1 default.
+ *
+ * Which value to pass is **dictated by the E2EE environment Incode has
+ * provisioned for your account** — confirm with your Incode account team
+ * before changing it.
+ */
+type EncryptionOptions = {
+  /**
+   * OAEP MGF1 hash for the in-binary RSA handshake.
+   * - `'sha1'` (default) — matches the legacy Java backend default. Most
+   *   E2EE environments are happy with this.
+   * - `'sha256'` — sends the
+   *   `X-RSA-Encryption-Scheme: RSA/NONE/OAEPWITHSHA-256ANDMGF1PADDING`
+   *   header on every encrypted request so the server matches. Only use this
+   *   if the environment has been configured to honor the explicit header.
+   *
+   * Locked at the first `setup()` call. To change it, call `reset()` and
+   * re-`setup()` from scratch.
+   */
+  mgf1?: 'sha1' | 'sha256';
+};
+/**
+ * Configuration options for the SDK setup.
+ */
+type SetupOptions = {
+  /** The base URL for the API. When omitted, no HTTP client is created — useful when all API actors are overridden via .provide(). */
+  apiURL?: string;
+  /**
+   * The session token for API requests.
+   *
+   * Optional convenience — when provided, `setup` delegates to
+   * `initializeSession({ token, hostingApp })` after the HTTP client is in
+   * place. Equivalent to calling `initializeSession` yourself after
+   * `setup({ apiURL })` returns, which is the preferred shape when you want to
+   * own the moment the session is activated (e.g. between `createSession` and
+   * mounting `<incode-flow>`).
+   */
+  token?: string;
+  /** Custom headers to include in all requests */
+  customHeaders?: Record<string, string>;
+  /** Request timeout in milliseconds */
+  timeout?: number;
+  /**
+   * WASM warmup config.
+   * - Omit (default): does not load WASM.
+   * - `false`: explicitly disable WASM loading.
+   * - Object: load WASM with CDN defaults plus any overrides you provide.
+   */
+  wasm?: WasmConfig | false;
+  /**
+   * Enable end-to-end encryption for SDK traffic. When enabled, the SDK
+   * negotiates an encrypted transport during initialization (RSA-OAEP key
+   * transport + AES-GCM payload encryption). Independent of `token` —
+   * encryption can be set up before a session token is known.
+   *
+   * **Not a self-serve flag.** E2EE has to be provisioned for your account
+   * by Incode, and you'll be given a dedicated `apiURL` (typically a
+   * `*-e2ee-api.incodesmile.com` host) plus the `mgf1` scheme that
+   * environment expects. Pointing this at a non-E2EE host will fail the
+   * handshake at `setup()`. Coordinate with your Incode account team before
+   * flipping this on.
+   *
+   * Accepts:
+   * - `true` → enabled with the default OAEP MGF1 hash (`'sha1'`).
+   * - `false` (or omitted) → disabled.
+   * - `{}` → same as `true`.
+   * - `{ mgf1: 'sha256' }` → enabled with the SHA-256 MGF1 hash.
+   *
+   * Encryption requires the binary (WASM) transport. If `wasm: false` is set,
+   * `setup` throws. If `wasm` is omitted, the binary transport is provisioned
+   * automatically with CDN defaults.
+   *
+   * **Locked at boot.** The first `setup()` call decides whether encryption
+   * is on, and if so which MGF1 scheme is used. Subsequent `setup()` calls
+   * that would change either of those values throw with a descriptive error.
+   * Call `reset()` if you need to change them.
+   *
+   * **Failure modes.** `setup()` rejects with a descriptive error if the
+   * encrypted-transport handshake (`GET /e2ee/key/v2` + `POST /e2ee/key`)
+   * cannot complete — most commonly because `apiURL` points at a host that
+   * isn't provisioned for E2EE, or because the requested `mgf1` doesn't
+   * match what the environment expects. There is no built-in retry; catch
+   * and re-call `setup()` after `reset()` if your environment is
+   * known-flaky.
+   *
+   * @throws If `wasm: false` is also set, or if the handshake fails, or if
+   *   the encryption value differs from what was locked in on the first
+   *   `setup()` call.
+   */
+  encryption?: boolean | EncryptionOptions;
+  /** Optional hosting app identifier for fingerprint tracking */
+  hostingApp?: string;
+};
+/**
+ * Initializes the SDK with the provided configuration.
+ * Must be called before using any SDK functionality.
+ *
+ * WASM loads only when `options.wasm` is provided as an object.
+ *
+ * `setup` is boot — it provisions the HTTP client, the optional E2EE
+ * handshake, WASM warmup, and the analytics batcher. The session token is a
+ * separate concern: hand it off via `initializeSession({ token })` from
+ * `@incodetech/core/session`, or pass it inline as `setup({ apiURL, token })`
+ * (a convenience that delegates to `initializeSession` for you).
+ *
+ * @param options - Configuration options for the SDK
+ *
+ * @example Boot first, activate the session later (preferred)
+ * ```ts
+ * import { setup } from '@incodetech/core';
+ * import { createSession, initializeSession } from '@incodetech/core/session';
+ *
+ * await setup({ apiURL: 'https://api.incode.com' });
+ * const session = await createSession(apiKey, { configurationId });
+ * await initializeSession({ token: session.token });
+ * ```
+ *
+ * @example One-shot convenience
+ * ```ts
+ * await setup({ apiURL: 'https://api.incode.com', token: 'session-token' });
+ * ```
+ *
+ * @example Explicitly disable WASM
+ * ```ts
+ * await setup({ apiURL: 'https://api.incode.com', wasm: false });
+ * ```
+ *
+ * @example Use CDN defaults for paths and preload only one pipeline
+ * ```ts
+ * await setup({
+ *   apiURL: 'https://api.incode.com',
+ *   wasm: { pipelines: ['selfie'] },
+ * });
+ * ```
+ *
+ * @example Self-hosted / custom version (full or partial path overrides)
+ * ```ts
+ * await setup({
+ *   apiURL: 'https://api.incode.com',
+ *   wasm: {
+ *     wasmPath: '/my-cdn/webLib.wasm',
+ *     glueCodePath: '/my-cdn/webLib.js',
+ *   },
+ * });
+ * ```
+ *
+ * @example Partial override: only models path, rest from CDN
+ * ```ts
+ * await setup({
+ *   apiURL: 'https://api.incode.com',
+ *   wasm: { modelsBasePath: 'https://my-cdn/models' },
+ * });
+ * ```
+ *
+ * @example Sessionless setup (all API actors overridden via .provide())
+ * ```ts
+ * await setup({
+ *   wasm: {
+ *     wasmPath: '/wasm/ml-wasm.wasm',
+ *     glueCodePath: '/wasm/ml-wasm.js',
+ *     pipelines: ['selfie'],
+ *   },
+ * });
+ * ```
+ *
+ * @example Enable end-to-end encryption at boot (defaults to MGF1 = SHA-1)
+ * ```ts
+ * await setup({ apiURL: 'https://api.incode.com', encryption: true });
+ * ```
+ *
+ * @example Enable encryption with the SHA-256 MGF1 padding
+ * ```ts
+ * await setup({
+ *   apiURL: 'https://api.incode.com',
+ *   encryption: { mgf1: 'sha256' },
+ * });
+ * ```
+ */
+declare function setup(options: SetupOptions): Promise<void>;
+/**
+ * Sets the WASM configuration without performing warmup.
+ * Useful when WASM warmup is handled separately (e.g., conditionally based on flow).
+ *
+ * @param config - WASM configuration to store
+ */
+declare function setWasmConfig(config: WasmConfig): void;
+/**
+ * Initializes WasmUtilProvider with the stored WASM configuration.
+ * Should be called after warmupWasm() completes when using conditional warmup.
+ * This ensures image encryption works properly.
+ *
+ * @param config - Optional WASM configuration. If not provided, uses the stored config from setWasmConfig().
+ * @throws Error if no config is provided and none is stored
+ */
+declare function initializeWasmUtil(config?: WasmConfig): Promise<void>;
+/**
+ * Replaces the active HTTP client with the WASM-backed one. Used internally
+ * by lazy-loading UI components (`<incode-flow>`, `<incode-workflow>`) when
+ * WASM finishes warming up.
+ *
+ * No-op when no apiURL was originally configured, or when the active client is
+ * already the WASM one.
+ *
+ * @internal NOT a public API. Application code should use
+ *   `setup({ wasm: {...} })` instead — that path is the supported way to opt
+ *   into the WASM HTTP client.
+ *
+ * @param config - Optional WASM configuration. Defaults to the config stored via `setWasmConfig`.
+ */
+declare function upgradeToWasmHttpClient(config?: WasmConfig): Promise<void>;
+/**
+ * Checks if the SDK has been configured.
+ *
+ * @returns true if setup() has been called, false otherwise
+ */
+declare function isConfigured(): boolean;
+/**
+ * Resets the SDK configuration. Useful for testing.
+ */
+declare function reset(): void;
+//#endregion
+export { reset as a, upgradeToWasmHttpClient as c, isConfigured as i, WasmConfig as n, setWasmConfig as o, initializeWasmUtil as r, setup as s, SetupOptions as t };