@smileid/usesmileid-nodejs 12.0.0

package/dist/client/config.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Client configuration and resolution (spec §2.1).
+ */
+import type { Environment } from '../generated/models/index.js';
+/** The `fetch` implementation the SDK uses. Injectable for testing/proxies. */
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** Public client configuration (spec §2.1). */
+export interface SmileIDConfig {
+    /** Numeric partner id, no leading zeros. */
+    partnerId: string;
+    /** Partner API key. */
+    apiKey: string;
+    /** Environment. Sandbox by default. */
+    environment?: Environment;
+    /** Used when a call omits callbackUrl. */
+    defaultCallbackUrl?: string;
+    /** Explicit base URL override; wins over environment. */
+    baseUrl?: string;
+    /** Per-request total timeout in milliseconds. Default 30000. */
+    timeout?: number;
+    /** Retries for idempotent operations only. Default 2. */
+    maxRetries?: number;
+    /** Injectable fetch implementation. Defaults to the global fetch. */
+    fetch?: FetchLike;
+}
+/** Base URLs by environment (spec §2.1 — not in the OpenAPI spec, confirm before release). */
+export declare const BASE_URLS: Record<Environment, string>;
+/** Fully-resolved configuration with defaults applied. */
+export interface ResolvedConfig {
+    partnerId: string;
+    apiKey: string;
+    environment: Environment;
+    defaultCallbackUrl: string | null;
+    baseUrl: string;
+    timeout: number;
+    maxRetries: number;
+    fetch: FetchLike;
+}
+/** Validate and resolve raw config into {@link ResolvedConfig}. */
+export declare function resolveConfig(config: SmileIDConfig): ResolvedConfig;

package/dist/client/config.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Client configuration and resolution (spec §2.1).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASE_URLS = void 0;
+exports.resolveConfig = resolveConfig;
+const index_js_1 = require("../errors/index.js");
+const validation_js_1 = require("../helpers/validation.js");
+/** Base URLs by environment (spec §2.1 — not in the OpenAPI spec, confirm before release). */
+exports.BASE_URLS = {
+    sandbox: 'https://testapi.smileidentity.com',
+    production: 'https://api.smileidentity.com',
+};
+const PARTNER_ID_PATTERN = /^[1-9]\d*$/;
+/** Validate and resolve raw config into {@link ResolvedConfig}. */
+function resolveConfig(config) {
+    if (!config.partnerId || !PARTNER_ID_PATTERN.test(config.partnerId)) {
+        throw new TypeError('partnerId must be a numeric string with no leading zeros.');
+    }
+    if (!config.apiKey) {
+        throw new TypeError('apiKey is required.');
+    }
+    const environment = config.environment ?? 'sandbox';
+    // Runtime guard for plain-JavaScript callers; the TS union covers TS callers.
+    if (environment !== 'sandbox' && environment !== 'production') {
+        throw new index_js_1.ValidationError({
+            message: 'environment must be "sandbox" or "production".',
+        });
+    }
+    const rawBaseUrl = config.baseUrl ?? exports.BASE_URLS[environment];
+    // Fleet standard: absolute https, no query or fragment. No escape hatch.
+    (0, validation_js_1.assertHttpsUrl)(rawBaseUrl, 'baseUrl', { forbidQueryAndFragment: true });
+    const baseUrl = rawBaseUrl.replace(/\/+$/, '');
+    if (config.defaultCallbackUrl !== undefined) {
+        (0, validation_js_1.assertHttpsUrl)(config.defaultCallbackUrl, 'defaultCallbackUrl');
+    }
+    const fetchImpl = config.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new TypeError('No fetch implementation available. Node 18+ provides a global fetch, or pass one via config.fetch.');
+    }
+    return {
+        partnerId: config.partnerId,
+        apiKey: config.apiKey,
+        environment,
+        defaultCallbackUrl: config.defaultCallbackUrl ?? null,
+        baseUrl,
+        timeout: config.timeout ?? 30000,
+        maxRetries: config.maxRetries ?? 2,
+        fetch: fetchImpl,
+    };
+}

package/dist/client/transport.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The single internal transport (spec §2.2, §2.6, §2A).
+ *
+ * Every resource method funnels through here. It builds the URL, attaches auth
+ * and telemetry headers, serializes the body, sends, applies
+ * the retry policy, and parses the response into a typed result or error. It is
+ * the only layer that touches HTTP.
+ */
+import { TokenManager } from './auth.js';
+import type { ResolvedConfig } from './config.js';
+import type { SerializedMultipart } from '../helpers/multipart.js';
+/** A fully-described request for {@link Transport.execute}. */
+export interface RequestPlan {
+    method: 'GET' | 'POST';
+    /** Path with placeholders already substituted (e.g. /v3/status/job_123). */
+    path: string;
+    authenticated: boolean;
+    needsPartnerIdHeader: boolean;
+    /** True only for GETs and the token fetch (spec §2.6). */
+    idempotent: boolean;
+    query?: Record<string, string | undefined>;
+    /** Operation-specific headers (e.g. User-ID). */
+    headers?: Record<string, string | undefined>;
+    /** Multipart body, when the operation sends one. */
+    multipart?: SerializedMultipart;
+    /** When true, a final 404 returns the parsed body instead of raising (spec §6.8). */
+    allow404?: boolean;
+    /** Per-request options. */
+    timeout?: number;
+    signal?: AbortSignal;
+}
+/** The parsed outcome of a request. */
+export interface TransportResult {
+    statusCode: number;
+    /** Parsed JSON body, or null if the body was empty / not JSON. */
+    json: unknown;
+    rawBody: string;
+    requestId: string | null;
+}
+/** Should this attempt be retried, given the operation and outcome (spec §2A). */
+export declare function shouldRetry(idempotent: boolean, attempt: number, maxRetries: number, statusCode: number | null): boolean;
+/**
+ * Backoff delay in ms: honour Retry-After when present (capped at 60s),
+ * else exponential + jitter.
+ */
+export declare function computeBackoff(attempt: number, retryAfterSeconds: number | null): number;
+/**
+ * Parse a Retry-After header into seconds from now. Both RFC 7231 forms are
+ * honoured: delta-seconds ("2") and HTTP-date ("Wed, 01 Jul 2026 12:00:05 GMT").
+ */
+export declare function parseRetryAfter(value: string | null): number | null;
+export declare class Transport {
+    private readonly config;
+    private readonly sleep;
+    readonly tokenManager: TokenManager;
+    constructor(config: ResolvedConfig, sleep?: (ms: number) => Promise<void>);
+    /** The client-wide default callback URL, or null (spec §2.1). */
+    get defaultCallbackUrl(): string | null;
+    /** Telemetry headers, sent on every request (spec §2.4). */
+    telemetryHeaders(): Record<string, string>;
+    /** Execute a request plan, applying auth, retries, and error parsing. */
+    execute(plan: RequestPlan): Promise<TransportResult>;
+    private buildUrl;
+}

package/dist/client/transport.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * The single internal transport (spec §2.2, §2.6, §2A).
+ *
+ * Every resource method funnels through here. It builds the URL, attaches auth
+ * and telemetry headers, serializes the body, sends, applies
+ * the retry policy, and parses the response into a typed result or error. It is
+ * the only layer that touches HTTP.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transport = void 0;
+exports.shouldRetry = shouldRetry;
+exports.computeBackoff = computeBackoff;
+exports.parseRetryAfter = parseRetryAfter;
+const index_js_1 = require("../errors/index.js");
+const auth_js_1 = require("./auth.js");
+const version_js_1 = require("../version.js");
+/** HTTP statuses that are retryable for idempotent operations (spec §2.6). */
+const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+/** Base backoff in ms (SDK choice — not in the spec). */
+const BACKOFF_BASE_MS = 50;
+/** Cap on an honoured Retry-After delay (cross-SDK standard). */
+const RETRY_AFTER_CAP_SECONDS = 60;
+/** Should this attempt be retried, given the operation and outcome (spec §2A). */
+function shouldRetry(idempotent, attempt, maxRetries, statusCode) {
+    if (attempt >= maxRetries)
+        return false;
+    if (!idempotent)
+        return false;
+    // 409 is explicitly excluded (business-state conflict, not transient).
+    if (statusCode === null)
+        return true; // connection error
+    return RETRYABLE_STATUSES.has(statusCode);
+}
+/**
+ * Backoff delay in ms: honour Retry-After when present (capped at 60s),
+ * else exponential + jitter.
+ */
+function computeBackoff(attempt, retryAfterSeconds) {
+    if (retryAfterSeconds !== null && retryAfterSeconds >= 0) {
+        return Math.min(retryAfterSeconds, RETRY_AFTER_CAP_SECONDS) * 1000;
+    }
+    const exponential = BACKOFF_BASE_MS * 2 ** attempt;
+    const jitter = Math.floor(Math.random() * BACKOFF_BASE_MS);
+    return exponential + jitter;
+}
+/**
+ * Parse a Retry-After header into seconds from now. Both RFC 7231 forms are
+ * honoured: delta-seconds ("2") and HTTP-date ("Wed, 01 Jul 2026 12:00:05 GMT").
+ */
+function parseRetryAfter(value) {
+    if (!value)
+        return null;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds))
+        return seconds;
+    const date = Date.parse(value);
+    if (Number.isFinite(date))
+        return Math.max(0, Math.round((date - Date.now()) / 1000));
+    return null;
+}
+class Transport {
+    config;
+    sleep;
+    tokenManager;
+    constructor(config, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
+        this.config = config;
+        this.sleep = sleep;
+        this.tokenManager = new auth_js_1.TokenManager(config.partnerId, config.apiKey, (plan) => this.execute(plan));
+    }
+    /** The client-wide default callback URL, or null (spec §2.1). */
+    get defaultCallbackUrl() {
+        return this.config.defaultCallbackUrl;
+    }
+    /** Telemetry headers, sent on every request (spec §2.4). */
+    telemetryHeaders() {
+        return {
+            'SmileID-Source-SDK': 'node',
+            'SmileID-Source-SDK-Version': version_js_1.VERSION,
+            'User-Agent': `smileid-sdk-node/${version_js_1.VERSION} (node/${process.version.replace(/^v/, '')})`,
+        };
+    }
+    /** Execute a request plan, applying auth, retries, and error parsing. */
+    async execute(plan) {
+        const url = this.buildUrl(plan);
+        let attempt = 0;
+        let authRefreshed = false;
+        for (;;) {
+            if (plan.signal?.aborted) {
+                throw new index_js_1.ConnectionError({ message: 'Request aborted.' });
+            }
+            const headers = { ...this.telemetryHeaders() };
+            for (const [k, v] of Object.entries(plan.headers ?? {})) {
+                if (v !== undefined)
+                    headers[k] = v;
+            }
+            if (plan.needsPartnerIdHeader)
+                headers['SmileID-Partner-ID'] = this.config.partnerId;
+            if (plan.authenticated) {
+                headers['SmileID-Token'] = await this.tokenManager.ensureToken();
+            }
+            let body;
+            if (plan.multipart) {
+                headers['Content-Type'] = plan.multipart.contentType;
+                body = plan.multipart.body;
+            }
+            const controller = new AbortController();
+            const timeoutMs = plan.timeout ?? this.config.timeout;
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            const onAbort = () => controller.abort();
+            plan.signal?.addEventListener('abort', onAbort);
+            let resp;
+            try {
+                resp = await this.config.fetch(url, {
+                    method: plan.method,
+                    headers,
+                    body: body,
+                    signal: controller.signal,
+                });
+            }
+            catch (err) {
+                // A caller-initiated abort is not a transient fault: never retry it.
+                if (plan.signal?.aborted) {
+                    throw new index_js_1.ConnectionError({ message: 'Request aborted.' });
+                }
+                if (shouldRetry(plan.idempotent, attempt, this.config.maxRetries, null)) {
+                    await this.sleep(computeBackoff(attempt, null));
+                    attempt += 1;
+                    continue;
+                }
+                throw new index_js_1.ConnectionError({
+                    message: err instanceof Error ? err.message : 'Network request failed.',
+                });
+            }
+            finally {
+                clearTimeout(timer);
+                plan.signal?.removeEventListener('abort', onAbort);
+            }
+            const rawBody = await resp.text();
+            const requestId = resp.headers.get('x-request-id');
+            if (resp.status >= 200 && resp.status < 300) {
+                const json = safeJson(rawBody);
+                // Fleet standard: a success body must be a JSON object. The
+                // retrieve 404 → not_found path below is unaffected.
+                if (json === null || typeof json !== 'object' || Array.isArray(json)) {
+                    throw new index_js_1.UnexpectedResponseError({
+                        statusCode: resp.status,
+                        message: 'Expected a JSON object in the response body.',
+                        rawBody,
+                        requestId,
+                    });
+                }
+                return { statusCode: resp.status, json, rawBody, requestId };
+            }
+            // Refresh-on-401 once, then surface AuthenticationError (spec §2.3 item 5).
+            if (resp.status === 401 && plan.authenticated && !authRefreshed) {
+                this.tokenManager.invalidate();
+                authRefreshed = true;
+                continue;
+            }
+            if (plan.allow404 && resp.status === 404) {
+                return { statusCode: resp.status, json: safeJson(rawBody), rawBody, requestId };
+            }
+            if (shouldRetry(plan.idempotent, attempt, this.config.maxRetries, resp.status)) {
+                const retryAfter = parseRetryAfter(resp.headers.get('retry-after'));
+                await this.sleep(computeBackoff(attempt, retryAfter));
+                attempt += 1;
+                continue;
+            }
+            throw (0, index_js_1.parseError)({ statusCode: resp.status, rawBody, requestId });
+        }
+    }
+    buildUrl(plan) {
+        const url = new URL(this.config.baseUrl + plan.path);
+        for (const [k, v] of Object.entries(plan.query ?? {})) {
+            if (v !== undefined)
+                url.searchParams.set(k, v);
+        }
+        return url.toString();
+    }
+}
+exports.Transport = Transport;
+function safeJson(raw) {
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Error hierarchy (spec §7).
+ *
+ * One base class, {@link SmileIDError}, with typed subclasses keyed on HTTP
+ * status. Every error exposes the same accessor fields so callers can inspect
+ * a failure uniformly regardless of which wire error shape produced it.
+ */
+/** Fields shared by every SDK error. */
+export interface SmileIDErrorFields {
+    /** HTTP status code, or null for connection / SDK-local errors. */
+    statusCode: number | null;
+    /** HTTP status text from the response body when present (e.g. "Bad Request"). */
+    status: string | null;
+    /** Human-readable message. */
+    message: string;
+    /** Machine code, present only on the services `{error, code}` wire shape. */
+    code: string | null;
+    /** Request id from a response header when one exists, else null. */
+    requestId: string | null;
+    /** The unparsed response body, when there was one. */
+    rawBody: string | null;
+}
+/** Base class for every error raised by the SDK. */
+export declare class SmileIDError extends Error {
+    readonly statusCode: number | null;
+    readonly status: string | null;
+    readonly code: string | null;
+    readonly requestId: string | null;
+    readonly rawBody: string | null;
+    constructor(fields: Partial<SmileIDErrorFields> & {
+        message: string;
+    });
+}
+/** 400 / 415 — malformed or unsupported request. Also used for local validation. */
+export declare class InvalidRequestError extends SmileIDError {
+}
+/** 401 — authentication failed (raised after a failed token refresh). */
+export declare class AuthenticationError extends SmileIDError {
+}
+/** 402 — insufficient wallet balance. */
+export declare class PaymentRequiredError extends SmileIDError {
+}
+/** 403 — not authorized (includes the services `{error, code}` shape). */
+export declare class PermissionError extends SmileIDError {
+}
+/** 404 — resource not found. Not raised by `verifications.retrieve` (see §6.8). */
+export declare class NotFoundError extends SmileIDError {
+}
+/** 409 — business-state conflict (e.g. replay while still processing). Never auto-retried. */
+export declare class ConflictError extends SmileIDError {
+}
+/** 413 — request payload too large. */
+export declare class PayloadTooLargeError extends SmileIDError {
+}
+/** 429 — rate limited. */
+export declare class RateLimitError extends SmileIDError {
+}
+/** 5xx — server-side API error. */
+export declare class APIError extends SmileIDError {
+}
+/** Network failure or transport error with no HTTP response. */
+export declare class ConnectionError extends SmileIDError {
+}
+/** A 2xx success response whose body is not a JSON object (fleet standard). */
+export declare class UnexpectedResponseError extends SmileIDError {
+}
+/** SDK-local: raised by `verifications.waitUntilComplete` when the deadline passes. */
+export declare class TimeoutError extends SmileIDError {
+}
+/** SDK-local: client-side validation failure raised before a request is sent. */
+export declare class ValidationError extends InvalidRequestError {
+}
+/** Map an HTTP status code to the matching error class (spec §7 table). */
+export declare function errorClassForStatus(status: number): new (fields: Partial<SmileIDErrorFields> & {
+    message: string;
+}) => SmileIDError;
+/** A minimal view of a parsed HTTP response, enough for {@link parseError}. */
+export interface ErrorSource {
+    statusCode: number;
+    rawBody: string | null;
+    requestId: string | null;
+}
+/**
+ * Turn a failed HTTP response into a typed error (spec §2A `parse_error`).
+ *
+ * Handles both wire shapes: `{status, message}` (used almost everywhere, and
+ * `{message, status}` on id_status — same keys, any order) and `{error, code}`
+ * (the three unauthenticated services endpoints). The class is chosen by HTTP
+ * status, never by body contents.
+ */
+export declare function parseError(source: ErrorSource): SmileIDError;

package/dist/errors/index.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * Error hierarchy (spec §7).
+ *
+ * One base class, {@link SmileIDError}, with typed subclasses keyed on HTTP
+ * status. Every error exposes the same accessor fields so callers can inspect
+ * a failure uniformly regardless of which wire error shape produced it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = exports.TimeoutError = exports.UnexpectedResponseError = exports.ConnectionError = exports.APIError = exports.RateLimitError = exports.PayloadTooLargeError = exports.ConflictError = exports.NotFoundError = exports.PermissionError = exports.PaymentRequiredError = exports.AuthenticationError = exports.InvalidRequestError = exports.SmileIDError = void 0;
+exports.errorClassForStatus = errorClassForStatus;
+exports.parseError = parseError;
+/** Base class for every error raised by the SDK. */
+class SmileIDError extends Error {
+    statusCode;
+    status;
+    code;
+    requestId;
+    rawBody;
+    constructor(fields) {
+        super(fields.message);
+        this.name = new.target.name;
+        this.statusCode = fields.statusCode ?? null;
+        this.status = fields.status ?? null;
+        this.code = fields.code ?? null;
+        this.requestId = fields.requestId ?? null;
+        this.rawBody = fields.rawBody ?? null;
+        // Restore prototype chain when compiled down to older targets.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.SmileIDError = SmileIDError;
+/** 400 / 415 — malformed or unsupported request. Also used for local validation. */
+class InvalidRequestError extends SmileIDError {
+}
+exports.InvalidRequestError = InvalidRequestError;
+/** 401 — authentication failed (raised after a failed token refresh). */
+class AuthenticationError extends SmileIDError {
+}
+exports.AuthenticationError = AuthenticationError;
+/** 402 — insufficient wallet balance. */
+class PaymentRequiredError extends SmileIDError {
+}
+exports.PaymentRequiredError = PaymentRequiredError;
+/** 403 — not authorized (includes the services `{error, code}` shape). */
+class PermissionError extends SmileIDError {
+}
+exports.PermissionError = PermissionError;
+/** 404 — resource not found. Not raised by `verifications.retrieve` (see §6.8). */
+class NotFoundError extends SmileIDError {
+}
+exports.NotFoundError = NotFoundError;
+/** 409 — business-state conflict (e.g. replay while still processing). Never auto-retried. */
+class ConflictError extends SmileIDError {
+}
+exports.ConflictError = ConflictError;
+/** 413 — request payload too large. */
+class PayloadTooLargeError extends SmileIDError {
+}
+exports.PayloadTooLargeError = PayloadTooLargeError;
+/** 429 — rate limited. */
+class RateLimitError extends SmileIDError {
+}
+exports.RateLimitError = RateLimitError;
+/** 5xx — server-side API error. */
+class APIError extends SmileIDError {
+}
+exports.APIError = APIError;
+/** Network failure or transport error with no HTTP response. */
+class ConnectionError extends SmileIDError {
+}
+exports.ConnectionError = ConnectionError;
+/** A 2xx success response whose body is not a JSON object (fleet standard). */
+class UnexpectedResponseError extends SmileIDError {
+}
+exports.UnexpectedResponseError = UnexpectedResponseError;
+/** SDK-local: raised by `verifications.waitUntilComplete` when the deadline passes. */
+class TimeoutError extends SmileIDError {
+}
+exports.TimeoutError = TimeoutError;
+/** SDK-local: client-side validation failure raised before a request is sent. */
+class ValidationError extends InvalidRequestError {
+}
+exports.ValidationError = ValidationError;
+/** Map an HTTP status code to the matching error class (spec §7 table). */
+function errorClassForStatus(status) {
+    if (status === 400 || status === 415)
+        return InvalidRequestError;
+    if (status === 401)
+        return AuthenticationError;
+    if (status === 402)
+        return PaymentRequiredError;
+    if (status === 403)
+        return PermissionError;
+    if (status === 404)
+        return NotFoundError;
+    if (status === 409)
+        return ConflictError;
+    if (status === 413)
+        return PayloadTooLargeError;
+    if (status === 429)
+        return RateLimitError;
+    if (status >= 500)
+        return APIError;
+    // Any other 4xx we do not model explicitly is treated as an invalid request.
+    return InvalidRequestError;
+}
+/**
+ * Turn a failed HTTP response into a typed error (spec §2A `parse_error`).
+ *
+ * Handles both wire shapes: `{status, message}` (used almost everywhere, and
+ * `{message, status}` on id_status — same keys, any order) and `{error, code}`
+ * (the three unauthenticated services endpoints). The class is chosen by HTTP
+ * status, never by body contents.
+ */
+function parseError(source) {
+    let body = null;
+    if (source.rawBody) {
+        try {
+            const parsed = JSON.parse(source.rawBody);
+            if (parsed && typeof parsed === 'object') {
+                body = parsed;
+            }
+        }
+        catch {
+            body = null;
+        }
+    }
+    const message = (typeof body?.message === 'string' && body.message) ||
+        (typeof body?.error === 'string' && body.error) ||
+        `Request failed with status ${source.statusCode}`;
+    const code = typeof body?.code === 'string' ? body.code : null;
+    const status = typeof body?.status === 'string' ? body.status : null;
+    const ErrorClass = errorClassForStatus(source.statusCode);
+    return new ErrorClass({
+        statusCode: source.statusCode,
+        status,
+        message,
+        code,
+        requestId: source.requestId,
+        rawBody: source.rawBody,
+    });
+}