@basis-theory/web-elements 3.0.0-beta.4 → 3.0.0-beta.5

package/dist/index.d.ts

@@ -0,0 +1,1119 @@
+/**
+ * Base event detail - all element events include this metadata
+ */
+export declare interface BaseEventDetail {
+    /** Element type that fired this event */
+    elementType: ElementType;
+    /** Unique element ID (for distinguishing multiple elements) */
+    elementId: string;
+    /** Event timestamp (Unix milliseconds) */
+    timestamp: number;
+}
+
+/**
+ * Creates a BasisTheory SDK instance
+ * Factory function (no class, pure functional approach)
+ *
+ * @param apiKey - Your Basis Theory public API key (starts with 'pk_')
+ * @param options - SDK configuration options
+ * @param queuedCommands - Optional: Commands queued by loader before SDK loaded
+ * @returns SDK instance with methods to create and tokenize elements
+ *
+ * @example
+ * ```typescript
+ * import BasisTheory from '@basis-theory/web-elements';
+ *
+ * const bt = BasisTheory('pk_test_YOUR_API_KEY');
+ *
+ * const cardNumber = bt.createElement('cardNumber', {
+ *   placeholder: '4111 1111 1111 1111'
+ * });
+ *
+ * await cardNumber.mount('#card-number');
+ * ```
+ */
+declare const BasisTheory: (apiKey: string, options?: SDKOptions, queuedCommands?: QueuedCommand[]) => BasisTheorySDK;
+export default BasisTheory;
+
+export declare interface BasisTheorySDK {
+    /**
+     * Create a new element instance
+     * Returns Element instance immediately (synchronous)
+     */
+    createElement(type: 'card', options?: ElementOptions): CardElement;
+    createElement(type: 'copyButton', options: CopyButtonOptions): CopyButtonElement;
+    createElement(type: 'cardDisplay', options: CardDisplayOptions): CardDisplayElement;
+    createElement(type: Exclude<ElementType, 'card' | 'copyButton' | 'cardDisplay'>, options?: ElementOptions): Element_2;
+    createElement(type: ElementType, options?: ElementOptions | CopyButtonOptions): Element_2 | CardElement | CopyButtonElement;
+    createElement(type: ElementType, options?: ElementOptions | CardDisplayOptions): Element_2 | CardElement | CardDisplayElement;
+    /**
+     * Tokenize data (creates a token)
+     */
+    tokenize(data: ElementInputObject): Promise<TokenizeResult>;
+    /**
+     * Token CRUD operations
+     * Supports Element references - automatically resolves to secure values
+     *
+     * @example
+     * ```typescript
+     * // Create token with Elements (element references resolved automatically)
+     * const token = await bt.tokens.create({
+     *   type: 'card',
+     *   data: {
+     *     number: cardNumberElement,
+     *     expiration_month: expiryElement,
+     *     cvc: cvvElement
+     *   }
+     * });
+     *
+     * // Retrieve token
+     * const retrieved = await bt.tokens.retrieve(token.id);
+     *
+     * // Update token metadata
+     * await bt.tokens.update(token.id, {
+     *   metadata: { source: 'updated' }
+     * });
+     *
+     * // Encrypt token with client-side JWE
+     * const encrypted = await bt.tokens.encrypt(
+     *   { type: 'card', data: { number: cardNumberElement } },
+     *   publicKeyPEM,
+     *   'key-id-123'
+     * );
+     * ```
+     */
+    tokens: {
+        create(data: TokenCreateRequest): Promise<TokenizeResult>;
+        retrieve(id: string, options?: {
+            apiKey?: string;
+        }): Promise<TokenizeResult>;
+        update(id: string, data: TokenUpdateRequest): Promise<TokenizeResult>;
+        encrypt(tokenData: EncryptToken | Record<string, EncryptToken>, publicKeyPEM: string, keyId: string): Promise<EncryptedToken | Record<string, EncryptedToken>>;
+    };
+    /**
+     * Token Intent operations (short-lived sensitive data validation)
+     * Supports Element references - automatically resolves to secure values
+     *
+     * @example
+     * ```typescript
+     * // Create token intent with Elements
+     * const intent = await bt.tokenIntents.create({
+     *   type: 'card',
+     *   data: {
+     *     number: cardNumberElement,
+     *     expiration_month: 12,
+     *     expiration_year: 2025,
+     *     cvc: cvvElement
+     *   }
+     * });
+     *
+     * // Retrieve token intent
+     * const retrieved = await bt.tokenIntents.get(intent.id);
+     * ```
+     */
+    tokenIntents: {
+        create(data: TokenIntentRequest, options?: {
+            apiKey?: string;
+        }): Promise<TokenIntent>;
+        get(id: string, options?: {
+            apiKey?: string;
+        }): Promise<TokenIntent>;
+    };
+    /**
+     * Session management for temporary elevated access
+     *
+     * Creates a session that provides temporary elevated access to tokenized data.
+     * Sessions MUST be authorized by a Private Application on your backend.
+     *
+     * @example
+     * ```typescript
+     * // Create a session (frontend)
+     * const session = await bt.sessions.create();
+     * console.log('Session nonce:', session.nonce);
+     *
+     * // Session must be authorized on backend before use
+     * // Once authorized, use the session API key with tokens.retrieve()
+     * const token = await bt.tokens.retrieve(tokenId, {
+     *   apiKey: sessionApiKey // From authorized session
+     * });
+     * ```
+     */
+    sessions: {
+        create(): Promise<Session>;
+    };
+    /**
+     * Proxy HTTP requests through Basis Theory (Element references in `body` are resolved in the coordinator).
+     */
+    proxy: {
+        get(options: ProxyRequestOptions & {
+            includeResponseHeaders: true;
+        }): Promise<ProxyResponse>;
+        get(options?: ProxyRequestOptions): Promise<unknown>;
+        post(options: ProxyRequestOptions & {
+            includeResponseHeaders: true;
+        }): Promise<ProxyResponse>;
+        post(options?: ProxyRequestOptions): Promise<unknown>;
+        put(options: ProxyRequestOptions & {
+            includeResponseHeaders: true;
+        }): Promise<ProxyResponse>;
+        put(options?: ProxyRequestOptions): Promise<unknown>;
+        patch(options: ProxyRequestOptions & {
+            includeResponseHeaders: true;
+        }): Promise<ProxyResponse>;
+        patch(options?: ProxyRequestOptions): Promise<unknown>;
+        delete(options: ProxyRequestOptions & {
+            includeResponseHeaders: true;
+        }): Promise<ProxyResponse>;
+        delete(options?: ProxyRequestOptions): Promise<unknown>;
+    };
+    /**
+     * Update the theme mode for all mounted elements
+     *
+     * @param mode - Theme mode to apply ('light', 'dark', or 'auto')
+     * @returns Promise that resolves when all elements have been updated
+     *
+     * @example
+     * ```typescript
+     * await bt.updateThemeMode('dark');
+     * ```
+     */
+    updateThemeMode(mode: ThemeMode): Promise<void>;
+    /**
+     * Destroys this instance and removes its elements from the page. Once
+     * destroyed, its other methods throw; create a new instance with
+     * BasisTheory() to recover. Safe to call more than once.
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Blur event - fired when element loses focus
+ */
+export declare interface BlurEventDetail extends BaseEventDetail {
+}
+
+/**
+ * ISO 8601 timestamp when the SDK was built
+ * @example
+ * ```typescript
+ * import { buildDate } from '@basis-theory/web-elements';
+ * console.log(`Built on ${buildDate}`);
+ * ```
+ */
+export declare const buildDate: string;
+
+/**
+ * Change event detail for cardDisplay
+ */
+export declare interface CardDisplayChangeEventDetail {
+    loaded: boolean;
+    brand?: string;
+    last4?: string;
+}
+
+/**
+ * Card display element interface (read-only, no input methods)
+ */
+export declare interface CardDisplayElement extends Element_2 {
+    /**
+     * Element type
+     */
+    readonly type: 'cardDisplay';
+    /**
+     * Update element configuration
+     * Changing tokenId triggers a reload
+     */
+    update(options: Partial<CardDisplayOptions>): Promise<void>;
+    /**
+     * Listen for element events
+     */
+    on(eventType: CardDisplayEventType, listener: EventListener_2): () => void;
+}
+
+/**
+ * Card display event types
+ */
+export declare type CardDisplayEventType = 'ready' | 'change' | 'error';
+
+/**
+ * Display mode for card display fields
+ */
+declare type CardDisplayMode = 'masked' | 'hidden' | 'visible';
+
+/**
+ * Options for cardDisplay element
+ */
+export declare interface CardDisplayOptions extends ElementOptions {
+    /**
+     * Token ID to load and display
+     */
+    tokenId: string;
+    /**
+     * Card number display configuration
+     * @default { display: 'masked' }
+     */
+    number?: FieldDisplayConfig;
+    /**
+     * CVC display configuration
+     * @default { display: 'masked' }
+     */
+    cvc?: FieldDisplayConfig;
+    /**
+     * Expiration date display configuration
+     * @default { display: 'masked' }
+     */
+    expiration?: FieldDisplayConfig;
+}
+
+/**
+ * Card element with sub-field refs
+ */
+export declare interface CardElement extends Element_2 {
+    number: SubElementRef;
+    expiryDate: SubElementRef;
+    cvc: SubElementRef;
+}
+
+/**
+ * Card element specific change event detail (unified card element)
+ * Extends base with unified card state for all 3 sub-fields
+ */
+export declare interface CardElementChangeEventDetail extends ChangeEventDetail {
+    /** Detected card brand (Visa, Mastercard, etc.) */
+    cardBrand?: string;
+    /** Last 4 digits (PCI-safe, for display) */
+    last4?: string | null;
+    /** BIN (Bank Identification Number) - first 6-8 digits */
+    bin?: string | null;
+    /** Co-badge (when BIN enrichment returns multiple networks) */
+    networks?: string[];
+    selectedNetwork?: string;
+    /** Validation errors from all sub-fields (cardNumber, expirationDate, cvc) */
+    errors?: Array<{
+        field: string;
+        code: string;
+        message: string;
+    }> | null;
+}
+
+/**
+ * Card element options
+ */
+export declare interface CardElementOptions {
+    /** CSS styling */
+    style?: Record<string, any>;
+    /** Placeholder text for each sub-field */
+    placeholder?: {
+        cardNumber?: string;
+        expiryDate?: string;
+        cvc?: string;
+    };
+    /** Accessibility label */
+    ariaLabel?: string;
+    /** Disabled state (applies to all 3 sub-fields) */
+    disabled?: boolean;
+    /** Read-only state (applies to all 3 sub-fields) */
+    readOnly?: boolean;
+    /** Layout mode */
+    layout?: 'row' | 'column' | 'auto';
+    /** Stack threshold in pixels (only applies when layout: 'auto') */
+    stackAt?: number;
+    /** Icon position */
+    iconPosition?: 'left' | 'right' | 'none';
+    /** Restrict accepted card brands */
+    cardBrands?: string[];
+    /**
+     * BIN enrichment for the card number field. Setting `coBadge` turns enrichment on and
+     * overrides this — an explicit `binLookup: false` is ignored when `coBadge` is set.
+     */
+    binLookup?: boolean | {
+        enabled?: boolean;
+        debounceMs?: number;
+    };
+    /** Co-badge options; forces BIN enrichment on when set, overriding `binLookup`. */
+    coBadge?: {
+        preferredNetworks?: string[];
+        mode?: 'auto' | 'manual';
+    };
+}
+
+/**
+ * Card number specific change event detail
+ * Extends base with card brand detection metadata
+ */
+export declare interface CardNumberChangeEventDetail extends ChangeEventDetail {
+    /** Detected card brand (Visa, Mastercard, etc.) */
+    cardBrand?: string;
+    /** Last 4 digits (PCI-safe, for display) */
+    last4?: string | null;
+    /** BIN (Bank Identification Number) - first 6-8 digits */
+    bin?: string | null;
+    /** CVV lengths for detected brand (for coordinating with CVV element) */
+    cvvLengths?: number[] | null;
+    /** All brands that could potentially match */
+    potentialBrands?: string[];
+    /** Match confidence (0-1, higher = more confident) */
+    matchStrength?: number;
+    /** Co-badge networks from BIN enrichment (multi-network cards only) */
+    networks?: string[];
+    /** Selected payment network (kebab-case, multi-network cards only) */
+    selectedNetwork?: string;
+}
+
+/**
+ * Base change event detail - common to all element types
+ */
+export declare interface ChangeEventDetail extends BaseEventDetail {
+    /** Whether the current value is valid */
+    isValid: boolean;
+    /** Whether the input is empty */
+    isEmpty: boolean;
+    /** Validation error (null if valid) */
+    error: ValidationError | null;
+}
+
+/**
+ * CopyButton element with setValueRef method
+ */
+export declare interface CopyButtonElement extends Element_2 {
+    /**
+     * Link this copy button to another element's value
+     * When clicked, copies the linked element's current value
+     *
+     * @param element - The element to link to (e.g., cardNumber, text)
+     *
+     * @example
+     * ```typescript
+     * const cardNumber = bt.createElement('cardNumber');
+     * const copyBtn = bt.createElement('copyButton', { allowClipboard: true });
+     *
+     * copyBtn.setValueRef(cardNumber);
+     *
+     * // Now clicking copyBtn will copy the card number value
+     * ```
+     */
+    setValueRef(element: Element_2): Promise<void>;
+}
+
+/**
+ * Options specific to the CopyButton element
+ *
+ * SECURITY NOTE: This element is opt-in only via allowClipboard: true.
+ * Clipboard access for raw card data may not be PCI compliant and must
+ * never be enabled inadvertently.
+ */
+export declare interface CopyButtonOptions {
+    /**
+     * REQUIRED: Explicitly opt-in to clipboard access
+     * Must be set to true - throws ConfigurationError if missing
+     *
+     * @security This flag exists because clipboard access for raw card data
+     * may not be PCI compliant and must never be enabled inadvertently.
+     */
+    allowClipboard: true;
+    /**
+     * Static string value to copy when clicked
+     * Overridden by setValueRef() if called
+     */
+    value?: string;
+    /**
+     * Label text displayed on the button
+     * @default 'Copy'
+     */
+    text?: string;
+    /**
+     * Disable the button
+     * @default false
+     */
+    disabled?: boolean;
+}
+
+/**
+ * Copy event - fired when copy button is clicked
+ * Only available on copyButton element type
+ */
+export declare interface CopyEventDetail extends BaseEventDetail {
+    /** Whether the copy operation succeeded */
+    success: boolean;
+    /** Error message if copy failed (no sensitive data) */
+    error?: string;
+}
+
+declare interface Element_2 {
+    /**
+     * Unique identifier for the element
+     */
+    readonly id: string;
+    /**
+     * Element type ('cardNumber', 'cvv', 'expiry')
+     */
+    readonly type: ElementType;
+    /**
+     * Whether the element is currently mounted to the DOM
+     */
+    readonly mounted: boolean;
+    /**
+     * Whether the element is currently loaded
+     */
+    readonly loaded: boolean;
+    /**
+     * Mount the element to a DOM container
+     * @param selector - CSS selector or HTMLElement
+     */
+    mount(selector: string | HTMLElement): Promise<void>;
+    /**
+     * Unmount the element from the DOM
+     */
+    unmount(): void;
+    /**
+     * Update element configuration (placeholder, style, theme mode, etc.)
+     */
+    update(options: Partial<ElementOptions> & {
+        themeMode?: 'light' | 'dark' | 'auto';
+    }): Promise<void>;
+    /**
+     * Focus the input
+     */
+    focus(): void;
+    /**
+     * Blur the input
+     */
+    blur(): void;
+    /**
+     * Clear the input value
+     */
+    clear(): void;
+    /**
+     * Listen for element events
+     * @returns Unsubscribe function
+     */
+    on(eventType: EventType, listener: EventListener_2): () => void;
+    /**
+     * Override selected payment network for co-badge cards (card number element only)
+     */
+    setNetwork?(network: string): Promise<void>;
+}
+export { Element_2 as Element }
+
+/** Array that may contain Element references at any depth */
+export declare type ElementInputArray = Array<ElementLeaf | ElementInputObject | ElementInputArray>;
+
+/** Freeform object that may contain Element references at any depth */
+export declare interface ElementInputObject {
+    [key: string]: ElementLeaf | ElementInputObject | ElementInputArray;
+}
+
+/** Primitive or an Element reference — resolved to a value during tokenization */
+export declare type ElementLeaf = string | number | boolean | null | undefined | Element_2;
+
+export declare interface ElementOptions {
+    /**
+     * Placeholder text displayed when input is empty.
+     * For card elements, an object with per-field placeholders.
+     */
+    placeholder?: string | {
+        cardNumber?: string;
+        expiryDate?: string;
+        cvc?: string;
+    };
+    /**
+     * ARIA label for accessibility
+     * @default Based on element type (e.g., 'Card Number')
+     */
+    ariaLabel?: string;
+    /**
+     * Disable the input
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Make the input read-only
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * RegExp pattern for validation
+     * Only applicable to text elements
+     * @example /^[a-zA-Z\s]{2,50}$/ for names
+     * @example /^\d{3}-\d{2}-\d{4}$/ for SSN
+     */
+    validation?: RegExp;
+    /**
+     * Whether the field is required
+     * Only applicable to text elements
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Maximum input length
+     * Only applicable to text elements
+     * @example 50 for name fields
+     */
+    maxLength?: number;
+    /**
+     * Enable password mode (type="password")
+     * Only applicable to text elements
+     * @default false
+     */
+    password?: boolean;
+    /**
+     * Mobile keyboard hint
+     * Only applicable to text elements
+     * @example 'numeric', 'tel', 'email'
+     */
+    inputMode?: string;
+    /**
+     * Input masking pattern (lazy-loaded ~5KB module)
+     * Only applicable to text elements
+     *
+     * @example
+     * // SSN: XXX-XX-XXXX
+     * mask: [/\d/, /\d/, /\d/, '-', /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/]
+     *
+     * // Phone: (XXX) XXX-XXXX
+     * mask: ['(', /\d/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/]
+     */
+    mask?: (RegExp | string)[];
+    /**
+     * Transform pattern before tokenization
+     * Only applicable to text elements
+     *
+     * @example
+     * // Remove dashes from SSN before tokenization
+     * transform: [/-/g, '']
+     */
+    transform?: Transform;
+    /**
+     * Renders a show/hide toggle button inside the CVV field.
+     * Clicking toggles between `type="password"` and `type="text"`.
+     * CVV element only. Set at creation time only — runtime updates via
+     * `element.update()` are not supported.
+     * @default false
+     */
+    showToggle?: boolean;
+    /* Excluded from this release type: cardBrand */
+    /* Excluded from this release type: cvvLengths */
+    /**
+     * Layout mode for unified card element
+     * Only applicable to card elements
+     * @default 'auto'
+     */
+    layout?: 'row' | 'column' | 'auto';
+    /**
+     * Stack threshold in pixels (only applies when layout: 'auto')
+     * Only applicable to card elements
+     * @default 400
+     */
+    stackAt?: number;
+    /**
+     * Icon position for card brand icon
+     * Only applicable to card elements
+     * @default 'right'
+     */
+    iconPosition?: 'left' | 'right' | 'none';
+    /**
+     * Restrict accepted card brands
+     * Only applicable to card elements
+     */
+    cardBrands?: string[];
+    /**
+     * Enable BIN enrichment (6-digit) for the card number field (standalone or unified card).
+     * When true, co-badge networks are detected and `selectedNetwork` is available when applicable.
+     * Setting `coBadge` turns BIN enrichment on and overrides this — an explicit
+     * `binLookup: false` (or `{ enabled: false }`) is ignored when `coBadge` is set.
+     */
+    binLookup?: boolean | {
+        enabled?: boolean;
+        debounceMs?: number;
+    };
+    /**
+     * Co-badge: network priority and optional in-iframe network selector (manual mode).
+     * Forces BIN enrichment on when set, overriding `binLookup`; you only need to pass
+     * `binLookup` when you want to tune `debounceMs`.
+     */
+    coBadge?: {
+        preferredNetworks?: string[];
+        mode?: 'auto' | 'manual';
+    };
+}
+
+/**
+ * Event type definitions for Basis Theory Elements v3
+ * All events follow a consistent contract with base metadata
+ */
+/**
+ * Element types
+ */
+export declare type ElementType = 'cardNumber' | 'cvv' | 'expiry' | 'text' | 'card' | 'copyButton' | 'cardDisplay';
+
+/**
+ * Encrypted token result
+ */
+export declare interface EncryptedToken {
+    encrypted: string;
+    type: string;
+}
+
+/**
+ * Token data for encryption
+ */
+export declare interface EncryptToken {
+    type: string;
+    data: ElementInputObject;
+}
+
+/**
+ * Error codes
+ */
+export declare type ErrorCode = 'MOUNT_ERROR' | 'POSTMESSAGE_TIMEOUT' | 'IFRAME_LOAD_ERROR' | 'INITIALIZATION_ERROR' | 'API_ERROR' | 'NETWORK_ERROR' | 'VALIDATION_ERROR' | 'INVALID_CONFIGURATION' | 'UNKNOWN_ERROR' | 'SESSION_CREATION_FAILED' | 'SESSION_AUTHORIZATION_FAILED' | 'TOKEN_NOT_FOUND' | 'TOKEN_RETRIEVAL_FAILED' | 'SESSION_NOT_FOUND' | 'INVALID_TOKEN_TYPE' | 'INVALID_TOKEN_DATA' | 'LOADING_TIMEOUT';
+
+/**
+ * Error event detail - fired when errors occur during element operations
+ */
+export declare interface ErrorEventDetail extends BaseEventDetail {
+    /** Machine-readable error code */
+    code: ErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** HTTP status code (for API errors) */
+    status?: number;
+    /** Field-level validation errors from API */
+    validationErrors?: Record<string, string[]>;
+    /** Additional error context */
+    metadata?: {
+        /** Error source (e.g., 'tokenize', 'mount') */
+        source?: string;
+        /** Number of retry attempts */
+        retryCount?: number;
+        /** Full API response body (for debugging) */
+        body?: unknown;
+        /** Original error object */
+        originalError?: Error;
+    };
+}
+
+declare type EventListener_2 = (event: CustomEvent) => void;
+export { EventListener_2 as EventListener }
+
+export declare type EventType = 'change' | 'ready' | 'networkChanged' | 'focus' | 'blur' | 'error' | 'copy';
+
+/**
+ * Per-field display configuration
+ */
+declare interface FieldDisplayConfig {
+    display?: CardDisplayMode;
+}
+
+/**
+ * Focus event - fired when element receives focus
+ */
+export declare interface FocusEventDetail extends BaseEventDetail {
+}
+
+/**
+ * Fired when the selected payment network changes (co-badge)
+ */
+export declare interface NetworkChangedEventDetail extends BaseEventDetail {
+    network: string;
+    previousNetwork?: string;
+    availableNetworks: string[];
+    selectionMode: 'auto' | 'manual' | 'user';
+}
+
+/**
+ * Options for {@link BasisTheorySDK.proxy} — HTTP verb is chosen by the method name.
+ */
+export declare interface ProxyRequestOptions {
+    /** Destination URL (ephemeral proxy). Mutually exclusive with `proxyKey`. */
+    url?: string;
+    /** Pre-configured proxy key. Mutually exclusive with `url`. */
+    proxyKey?: string;
+    /** Headers forwarded to the destination request */
+    headers?: Record<string, string>;
+    /** Request body; may contain Element references */
+    body?: ElementInputObject | unknown;
+    /** When true, the API may return response metadata alongside data */
+    includeResponseHeaders?: boolean;
+}
+
+/**
+ * Proxy result when `includeResponseHeaders` is true (matches common API envelope).
+ */
+export declare interface ProxyResponse {
+    data: unknown;
+    headers: Record<string, string>;
+}
+
+/**
+ * Queued command from loader
+ * Commands are queued before SDK loads, then replayed
+ */
+declare interface QueuedCommand {
+    method: 'createElement' | 'tokenize' | 'updateThemeMode';
+    args: any[];
+    resolve: (result: any) => void;
+    reject: (error: Error) => void;
+}
+
+/**
+ * Ready event - fired when element iframe loads and is ready for interaction
+ */
+export declare interface ReadyEventDetail extends BaseEventDetail {
+}
+
+export declare interface SDKOptions {
+    /**
+     * Base URL where element iframes are hosted
+     * FRD-2026-003: Now defaults to production CDN (build-time injected, environment-specific)
+     * @default 'https://js.basistheory.com/{version}/elements' (production)
+     * @example 'http://localhost:4243' (for local development)
+     */
+    elementsBaseUrl?: string;
+    /**
+     * Whitelabel origin (https) for npm consumers. Derives `elementsBaseUrl` from
+     * this origin; ignored when `elementsBaseUrl` is set explicitly.
+     * @example 'https://pay.customer.com'
+     */
+    whitelabelDomain?: string;
+    /**
+     * @deprecated Use `elementsBaseUrl` instead
+     * Origin of the iframe host (where element.html is served)
+     */
+    iframeOrigin?: string;
+    /**
+     * API base URL for tokenization and API operations
+     * Auto-detects based on page origin by default:
+     * - localhost/flock-dev.com → https://js.flock-dev.com/api (dev)
+     * - btsandbox.com → https://js.btsandbox.com/api (uat)
+     * - basistheory.com → https://js.basistheory.com/api (prod)
+     * - other origins → https://js.basistheory.com/api (prod default)
+     *
+     * Override for:
+     * - Testing against custom API environments
+     * - Corporate proxies routing API calls
+     * - Regional API endpoints
+     *
+     * @default Auto-detected based on window.location.origin
+     * @example 'https://api-proxy.company.com/basistheory'
+     */
+    apiBaseUrl?: string;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Enable performance monitoring (bundle size, load times, compression metrics)
+     * When enabled, automatically measures and logs performance after elements load
+     * @default false
+     */
+    measurePerformance?: boolean;
+    /**
+     * PostMessage timeout (milliseconds)
+     * Increase this for slow network connections (3G, etc.)
+     * @default 30000
+     */
+    timeoutMs?: number;
+    /**
+     * PostMessage retry configuration
+     */
+    retryConfig?: {
+        maxRetries: number;
+        delayMs: number;
+        backoffFactor: number;
+    };
+    /**
+     * Theme mode: 'light', 'dark', or 'auto' (follows prefers-color-scheme)
+     * @default 'auto'
+     */
+    themeMode?: ThemeMode;
+    /**
+     * Theme configuration (design tokens)
+     * CSS variables will be injected into element iframes
+     *
+     * Supports light/dark themes via themeMode or separate theme/darkTheme objects
+     *
+     * @example
+     * ```typescript
+     * theme: {
+     *   colors: {
+     *     primary: '#007bff',
+     *     error: '#EA4B97',
+     *     text: '#1a1a1a',
+     *   },
+     *   typography: {
+     *     fontFamily: 'Inter, sans-serif',
+     *     fontSize: { base: '16px' },
+     *     fontWeight: { normal: '400' },
+     *   },
+     *   spacing: { sm: '8px', md: '12px', lg: '16px' },
+     *   borders: {
+     *     radius: { base: '4px' },
+     *     width: { base: '2px' },
+     *   },
+     * }
+     * ```
+     */
+    theme?: ThemeTokens;
+    /**
+     * Optional dark theme configuration
+     * Used when themeMode is 'dark' or 'auto' in dark mode
+     *
+     * If not provided, will use theme with adjusted colors for dark mode
+     */
+    darkTheme?: ThemeTokens;
+    /**
+     * URL of your backend endpoint that authorizes sessions.
+     * Required for cardDisplay element.
+     *
+     * The SDK will POST { nonce } to this URL after creating a session.
+     * Your backend must call POST /sessions/{nonce}/authorize with your private key.
+     *
+     * @example '/api/authorize-session'
+     * @example 'https://api.mycompany.com/bt/authorize'
+     */
+    sessionAuthorizationUrl?: string;
+}
+
+/**
+ * Session response (snake_case to match BasisTheory API)
+ */
+export declare interface Session {
+    /** Unique session nonce */
+    nonce: string;
+    /** Session expiration timestamp (ISO 8601 format) */
+    expires_at?: string;
+}
+
+/**
+ * Sub-element reference for tokenization (used in CardElement)
+ */
+export declare interface SubElementRef {
+    id: string;
+    type: string;
+    mounted: boolean;
+    mount: () => never;
+    unmount: () => void;
+    update: () => Promise<void>;
+    focus: () => void;
+    blur: () => void;
+    clear: () => void;
+    on: () => () => void;
+}
+
+/**
+ * Theme System Types
+ * Implements Hybrid approach: CSS variables for theming + property overrides
+ *
+ * Uses semantic nesting for better DX:
+ * - Magnitude scales: fontSize.sm/base/lg
+ * - State variants: border.default/hover/focus
+ * - Semantic groups: text.primary/secondary/placeholder
+ *
+ * Supports light/dark themes via prefers-color-scheme or explicit theme prop
+ */
+declare type ThemeMode = 'light' | 'dark' | 'auto';
+
+declare interface ThemeTokens {
+    colors: {
+        primary: string;
+        error: string;
+        success: string;
+        text: {
+            primary: string;
+            secondary?: string;
+            placeholder?: string;
+            disabled?: string;
+        };
+        background: {
+            default: string;
+            hover?: string;
+            focus?: string;
+            disabled?: string;
+        };
+        border: {
+            default: string;
+            hover?: string;
+            focus?: string;
+            error?: string;
+        };
+    };
+    typography: {
+        fontFamily: string;
+        fontSize: {
+            sm?: string;
+            base: string;
+            lg?: string;
+        };
+        fontWeight: {
+            normal: string;
+            medium?: string;
+            semibold?: string;
+        };
+        lineHeight?: {
+            tight?: string;
+            normal?: string;
+            relaxed?: string;
+        };
+    };
+    spacing: {
+        xs?: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl?: string;
+    };
+    borders: {
+        radius: {
+            none?: string;
+            sm?: string;
+            base: string;
+            md?: string;
+            lg?: string;
+            full?: string;
+        };
+        width: {
+            thin?: string;
+            base: string;
+            thick?: string;
+        };
+    };
+    shadows?: {
+        none?: string;
+        sm?: string;
+        base?: string;
+        md?: string;
+        lg?: string;
+        focus?: string;
+    };
+    transitions?: {
+        fast?: string;
+        base?: string;
+        slow?: string;
+    };
+}
+
+export declare interface TokenCreateRequest {
+    type: string;
+    data: ElementInputObject;
+    metadata?: Record<string, string>;
+    containers?: string[];
+    mask?: Record<string, unknown>;
+    aliases?: string[];
+    search_indexes?: string[];
+    fingerprint_expression?: string;
+    expires_at?: string;
+}
+
+/**
+ * Token Intent Response
+ */
+export declare interface TokenIntent {
+    /** Token Intent ID */
+    id: string;
+    /** Tenant ID */
+    tenant_id: string;
+    /** Token type */
+    type: string;
+    /** Intent status (e.g. 'created') */
+    status?: string;
+    /** Card details (when type is 'card') */
+    card?: {
+        bin?: string;
+        last4?: string;
+        expiration_month?: number;
+        expiration_year?: number;
+        brand?: string;
+        funding?: string;
+        issuer_country?: {
+            alpha2?: string;
+            name?: string;
+            numeric?: string;
+        };
+        authentication?: string;
+    };
+    /** Bank details (when type is 'bank') */
+    bank?: {
+        routing_number?: string;
+        account_number_last4?: string;
+    };
+    /** Fingerprint */
+    fingerprint?: string;
+    /** Created by application ID */
+    created_by?: string;
+    /** Creation timestamp */
+    created_at: string;
+    /** Expiration timestamp */
+    expires_at: string;
+}
+
+export declare interface TokenIntentRequest {
+    type: string;
+    data: ElementInputObject;
+}
+
+export declare type TokenizeInput = {
+    cardNumber: Element_2;
+} | {
+    number: Element_2;
+    cvv: Element_2;
+    expiry: Element_2;
+};
+
+export declare interface TokenizeResult {
+    id: string;
+    type: 'card' | 'token';
+    mask?: string;
+    brand?: string;
+    expiry?: {
+        month: number;
+        year: number;
+    };
+    metadata?: Record<string, unknown>;
+}
+
+/** Token `type` is immutable after creation */
+export declare type TokenUpdateRequest = Omit<Partial<TokenCreateRequest>, 'type'>;
+
+/**
+ * Transform pattern for modifying input before tokenization
+ * [pattern, replacement] - uses String.prototype.replace(pattern, replacement)
+ *
+ * @example
+ * // Remove dashes from SSN: "123-45-6789" → "123456789"
+ * const ssnTransform: Transform = [/-/g, ''];
+ *
+ * @example
+ * // Remove all non-digits from phone: "(555) 123-4567" → "5551234567"
+ * const phoneTransform: Transform = [/\D/g, ''];
+ */
+declare type Transform = [RegExp, string];
+
+/**
+ * Validation error structure
+ */
+export declare interface ValidationError {
+    /** Machine-readable error code */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+}
+
+/**
+ * SDK version from package.json
+ * @example
+ * ```typescript
+ * import { version } from '@basis-theory/web-elements';
+ * console.log(`Using SDK version ${version}`);
+ * ```
+ */
+export declare const version: string;
+
+export { }
+
+
+declare global {
+    interface Window {
+        BasisTheory?: typeof BasisTheory;
+    }
+}