@incodetech/core 2.0.0-alpha.8 → 2.0.0-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-BS-d_vuE.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 };