@sparkvault/sdk 1.0.0

package/dist/auto-init.d.ts

@@ -0,0 +1,51 @@
+/**
+ * SparkVault Auto-Initialization
+ *
+ * Enables zero-config initialization via script tag data attributes.
+ *
+ * @example
+ * ```html
+ * <script
+ *   async
+ *   src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"
+ *   data-account-id="acc_your_account_id"
+ *   data-attach-selector=".js-sparkvault-auth"
+ *   data-success-url="https://example.com/auth/verify-token"
+ *   data-error-function="handleSparkVaultError"
+ *   data-debug="true"
+ * ></script>
+ * ```
+ *
+ * Supported attributes:
+ * - data-account-id: Account ID (required for auto-init)
+ * - data-attach-selector: CSS selector for elements to attach click handlers
+ * - data-success-url: URL to POST { token, identity } on successful verification
+ * - data-success-function: Global function name to call on success (receives { token, identity, identityType })
+ * - data-error-url: URL to redirect to on error (appends ?error=message)
+ * - data-error-function: Global function name to call on error (receives Error object)
+ * - data-debug: Set to "true" to enable verbose console logging
+ */
+import type { SparkVault } from './index';
+/** Auto-init configuration parsed from script tag attributes */
+export interface AutoInitConfig {
+    accountId: string | null;
+    attachSelector: string | null;
+    successUrl: string | null;
+    successFunction: string | null;
+    errorUrl: string | null;
+    errorFunction: string | null;
+    debug: boolean;
+    preloadConfig: boolean;
+    timeout: number;
+}
+/**
+ * Initialize the SDK from script tag attributes
+ *
+ * Called automatically when the script loads.
+ * Requires SparkVault class to be passed in to avoid circular dependency.
+ */
+export declare function autoInit(SparkVaultClass: typeof SparkVault): void;
+/**
+ * Clean up auto-init resources
+ */
+export declare function cleanup(): void;

package/dist/config.d.ts

@@ -0,0 +1,25 @@
+/**
+ * SparkVault SDK Configuration
+ */
+export interface SparkVaultConfig {
+    /** Account ID for Identity operations */
+    accountId: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /**
+     * Preload Identity configuration on SDK init (default: true).
+     * When enabled, the /config call is made immediately when the SDK initializes,
+     * so verify() opens instantly without waiting for the config fetch.
+     * Set to false to defer config loading until verify() is called.
+     */
+    preloadConfig?: boolean;
+}
+export interface ResolvedConfig {
+    accountId: string;
+    timeout: number;
+    apiBaseUrl: string;
+    identityBaseUrl: string;
+    preloadConfig: boolean;
+}
+export declare function resolveConfig(config: SparkVaultConfig): ResolvedConfig;
+export declare function validateConfig(config: SparkVaultConfig): void;

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * SparkVault SDK Error Types
+ */
+export declare class SparkVaultError extends Error {
+    readonly code: string;
+    readonly statusCode?: number;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: string, statusCode?: number, details?: Record<string, unknown>);
+}
+export declare class AuthenticationError extends SparkVaultError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class AuthorizationError extends SparkVaultError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class ValidationError extends SparkVaultError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class NetworkError extends SparkVaultError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class TimeoutError extends SparkVaultError {
+    constructor(message?: string);
+}
+export declare class UserCancelledError extends SparkVaultError {
+    constructor(message?: string);
+}
+export declare class PopupBlockedError extends SparkVaultError {
+    constructor();
+}

package/dist/http.d.ts

@@ -0,0 +1,48 @@
+/**
+ * SparkVault SDK HTTP Client
+ */
+import type { ResolvedConfig } from './config';
+import { type RetryOptions } from './utils/retry';
+export interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    headers?: Record<string, string>;
+    body?: unknown;
+    timeout?: number;
+    /** Enable automatic retry with exponential backoff (per CLAUDE.md §7) */
+    retry?: boolean | RetryOptions;
+}
+export interface ApiResponse<T = unknown> {
+    data: T;
+    status: number;
+    headers: Headers;
+}
+export declare class HttpClient {
+    private readonly config;
+    constructor(config: ResolvedConfig);
+    request<T = unknown>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Execute the actual HTTP request (internal implementation)
+     */
+    private executeRequest;
+    /**
+     * Check if an error is safe to retry
+     * Per CLAUDE.md §7: Only retry on transient/network errors, not client errors
+     */
+    private isRetryableError;
+    private parseResponse;
+    private createErrorFromResponse;
+    get<T = unknown>(path: string, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<ApiResponse<T>>;
+    post<T = unknown>(path: string, body?: unknown, options?: Omit<RequestOptions, 'method'>): Promise<ApiResponse<T>>;
+    put<T = unknown>(path: string, body?: unknown, options?: Omit<RequestOptions, 'method'>): Promise<ApiResponse<T>>;
+    patch<T = unknown>(path: string, body?: unknown, options?: Omit<RequestOptions, 'method'>): Promise<ApiResponse<T>>;
+    delete<T = unknown>(path: string, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<ApiResponse<T>>;
+    /**
+     * Request raw binary data (e.g., file downloads).
+     * Returns a Blob instead of parsed JSON.
+     */
+    requestRaw(path: string, options?: RequestOptions): Promise<Blob>;
+    /**
+     * Execute the actual raw HTTP request (internal implementation)
+     */
+    private executeRequestRaw;
+}

package/dist/identity/api.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Identity API Client
+ *
+ * Handles all HTTP communication with the Identity App endpoints.
+ * Single responsibility: API calls only.
+ */
+import type { ResolvedConfig } from '../config';
+import type { SdkConfig, TotpSendResponse, TotpVerifyResponse, PasskeyChallengeResponse, PasskeyVerifyResponse, SparkLinkSendResponse, SparkLinkStatusResponse } from './types';
+export declare class IdentityApi {
+    private readonly config;
+    private readonly timeoutMs;
+    /** Cached config promise - allows preloading and deduplication */
+    private configCache;
+    constructor(config: ResolvedConfig, timeoutMs?: number);
+    private get baseUrl();
+    private request;
+    /**
+     * Fetch SDK configuration (branding, enabled methods).
+     * Uses caching to avoid redundant requests - safe to call multiple times.
+     */
+    getConfig(): Promise<SdkConfig>;
+    /**
+     * Preload the SDK configuration in the background.
+     * Called on SDK init when preloadConfig is enabled.
+     * The result is cached and used when verify() is called.
+     */
+    preloadConfig(): void;
+    /**
+     * Check if config has been preloaded and is ready.
+     */
+    isConfigPreloaded(): boolean;
+    /**
+     * Check if an email has registered passkeys and validate email domain
+     *
+     * Returns:
+     * - email_valid: whether the email domain has valid MX records
+     * - hasPasskey: whether any passkeys are registered (only meaningful if email_valid)
+     */
+    checkPasskey(email: string): Promise<{
+        email_valid: boolean;
+        hasPasskey: boolean;
+    }>;
+    /**
+     * Send TOTP code to email or phone
+     */
+    sendTotp(params: {
+        recipient: string;
+        method: 'email' | 'sms' | 'voice';
+    }): Promise<TotpSendResponse>;
+    /**
+     * Verify TOTP code
+     */
+    verifyTotp(params: {
+        kindling: string;
+        pin: string;
+        recipient: string;
+    }): Promise<TotpVerifyResponse>;
+    /**
+     * Start passkey registration
+     */
+    startPasskeyRegister(email: string): Promise<PasskeyChallengeResponse>;
+    /**
+     * Complete passkey registration
+     */
+    completePasskeyRegister(params: {
+        email: string;
+        credential: PublicKeyCredential;
+    }): Promise<PasskeyVerifyResponse>;
+    /**
+     * Start passkey verification
+     */
+    startPasskeyVerify(email: string): Promise<PasskeyChallengeResponse>;
+    /**
+     * Complete passkey verification
+     */
+    completePasskeyVerify(params: {
+        email: string;
+        credential: PublicKeyCredential;
+    }): Promise<PasskeyVerifyResponse>;
+    /**
+     * Get OAuth redirect URL for social provider
+     */
+    getSocialAuthUrl(provider: string, redirectUri: string, state: string): string;
+    /**
+     * Get SAML redirect URL for enterprise provider
+     */
+    getEnterpriseAuthUrl(provider: string, redirectUri: string, state: string): string;
+    /**
+     * Send SparkLink email for identity verification
+     */
+    sendSparkLink(email: string): Promise<SparkLinkSendResponse>;
+    /**
+     * Check SparkLink verification status (polling endpoint)
+     */
+    checkSparkLinkStatus(sparkId: string): Promise<SparkLinkStatusResponse>;
+}
+export declare class IdentityApiError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    constructor(message: string, code: string, statusCode: number);
+}

package/dist/identity/container.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Container Interface
+ *
+ * Abstract interface for identity UI containers.
+ * Allows switching between modal (popup) and inline rendering modes
+ * while reusing all view logic, state management, and handlers.
+ */
+import type { SdkConfigBranding } from './types';
+/**
+ * Container options for initialization.
+ */
+export interface ContainerOptions {
+    branding?: SdkConfigBranding;
+    /** Enable backdrop blur (modal only) */
+    backdropBlur?: boolean;
+}
+/**
+ * Container interface that both ModalContainer and InlineContainer implement.
+ * The renderer interacts with containers through this interface.
+ */
+export interface Container {
+    /**
+     * Create the container with loading state.
+     * Called immediately when verification starts.
+     */
+    createLoading(options: {
+        backdropBlur?: boolean;
+    }, onClose: () => void): void;
+    /**
+     * Update branding after SDK config loads.
+     */
+    updateBranding(branding: SdkConfigBranding): void;
+    /**
+     * Update backdrop blur setting (may be no-op for inline container).
+     */
+    updateBackdropBlur(enabled: boolean): void;
+    /**
+     * Get the body element where views are rendered.
+     */
+    getBody(): HTMLDivElement | null;
+    /**
+     * Check if the container is currently active.
+     */
+    isOpen(): boolean;
+    /**
+     * Destroy the container and clean up event listeners.
+     */
+    destroy(): void;
+}

package/dist/identity/handlers/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Identity Handlers
+ *
+ * Extracted handlers for specific authentication flows.
+ * Each handler has a single responsibility.
+ */
+export { PasskeyHandler, type PasskeyResult, type PasskeyCheckResult } from './passkey-handler';
+export { TotpHandler, type TotpSendResult, type TotpVerifyResult } from './totp-handler';
+export { SparkLinkHandler, type SparkLinkSendResult, type SparkLinkStatusResult } from './sparklink-handler';

package/dist/identity/handlers/passkey-handler.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Passkey Handler
+ *
+ * Single responsibility: WebAuthn passkey registration and verification.
+ * Extracts passkey logic from IdentityRenderer for better separation of concerns.
+ */
+import type { IdentityApi } from '../api';
+import type { VerifyResult } from '../types';
+import type { VerificationState } from '../state';
+/**
+ * Result of passkey operation
+ */
+export interface PasskeyResult {
+    success: boolean;
+    result?: VerifyResult;
+    error?: string;
+    errorType?: 'cancelled' | 'not_found' | 'not_allowed' | 'unknown';
+}
+/**
+ * Result of passkey check operation
+ */
+export interface PasskeyCheckResult {
+    /** Whether the email domain is valid (has MX records) */
+    emailValid: boolean;
+    /** Whether the user has registered passkeys (only meaningful if emailValid is true) */
+    hasPasskey: boolean;
+}
+/**
+ * Handles WebAuthn passkey registration and verification
+ */
+export declare class PasskeyHandler {
+    private readonly api;
+    private readonly state;
+    constructor(api: IdentityApi, state: VerificationState);
+    /**
+     * Check if user has registered passkeys and validate email domain
+     * @returns Check result with emailValid and hasPasskey, or null on error
+     */
+    checkPasskey(): Promise<PasskeyCheckResult | null>;
+    /**
+     * Register a new passkey for the user
+     */
+    register(): Promise<PasskeyResult>;
+    /**
+     * Verify user with existing passkey
+     */
+    verify(): Promise<PasskeyResult>;
+    /**
+     * Handle WebAuthn errors and categorize them
+     */
+    private handleError;
+}

package/dist/identity/handlers/sparklink-handler.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SparkLink Handler
+ *
+ * Single responsibility: SparkLink (magic link) sending and status polling.
+ * Extracts SparkLink logic from IdentityRenderer for better separation of concerns.
+ */
+import type { IdentityApi } from '../api';
+import type { VerificationState } from '../state';
+/**
+ * Result of SparkLink send operation
+ */
+export interface SparkLinkSendResult {
+    success: boolean;
+    sparkId?: string;
+    expiresAt?: number;
+    error?: string;
+}
+/**
+ * Result of SparkLink status check
+ */
+export interface SparkLinkStatusResult {
+    verified: boolean;
+    token?: string;
+    identity?: string;
+    identityType?: string;
+}
+/**
+ * Handles SparkLink (magic link) sending and verification polling
+ */
+export declare class SparkLinkHandler {
+    private readonly api;
+    private readonly state;
+    constructor(api: IdentityApi, state: VerificationState);
+    /**
+     * Send SparkLink to the user's email
+     */
+    send(): Promise<SparkLinkSendResult>;
+    /**
+     * Check SparkLink verification status
+     * Called periodically by the renderer to poll for completion
+     */
+    checkStatus(sparkId: string): Promise<SparkLinkStatusResult>;
+}

package/dist/identity/handlers/totp-handler.d.ts

@@ -0,0 +1,52 @@
+/**
+ * TOTP Handler
+ *
+ * Single responsibility: TOTP code sending and verification.
+ * Extracts TOTP logic from IdentityRenderer for better separation of concerns.
+ */
+import type { IdentityApi } from '../api';
+import type { VerifyResult } from '../types';
+import type { VerificationState } from '../state';
+/**
+ * Result of TOTP send operation
+ */
+export interface TotpSendResult {
+    success: boolean;
+    kindling?: string;
+    expiresAt?: number;
+    error?: string;
+}
+/**
+ * Result of TOTP verify operation
+ */
+export interface TotpVerifyResult {
+    success: boolean;
+    result?: VerifyResult;
+    /** New kindling if verification failed (for retry) */
+    newKindling?: string;
+    /** Seconds until retry allowed (rate limiting) */
+    retryAfter?: number;
+    /** When backoff expires (Unix timestamp) */
+    backoffExpires?: number;
+    error?: string;
+}
+/**
+ * Handles TOTP code sending and verification
+ */
+export declare class TotpHandler {
+    private readonly api;
+    private readonly state;
+    constructor(api: IdentityApi, state: VerificationState);
+    /**
+     * Send TOTP code via email or SMS
+     */
+    send(method: 'email' | 'sms'): Promise<TotpSendResult>;
+    /**
+     * Resend TOTP code
+     */
+    resend(): Promise<TotpSendResult>;
+    /**
+     * Verify TOTP code
+     */
+    verify(code: string): Promise<TotpVerifyResult>;
+}

package/dist/identity/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Identity Module
+ *
+ * Provides identity verification through a DOM-based modal interface.
+ * Supports passkey, TOTP, magic link, and social authentication.
+ */
+import type { ResolvedConfig } from '../config';
+import type { VerifyOptions, VerifyResult, TokenClaims, RenderOptions } from './types';
+export declare class IdentityModule {
+    private readonly config;
+    private readonly api;
+    private renderer;
+    constructor(config: ResolvedConfig);
+    /**
+     * Open the identity verification modal (popup).
+     * Returns when user successfully verifies their identity.
+     *
+     * @example
+     * const result = await sv.identity.pop({
+     *   email: 'user@example.com'
+     * });
+     * console.log(result.token, result.identity, result.identityType);
+     */
+    pop(options?: VerifyOptions): Promise<VerifyResult>;
+    /**
+     * Render identity verification inline within a target element.
+     * Unlike verify() which opens a modal popup, this embeds the UI
+     * directly into the specified element.
+     *
+     * @example
+     * // Render in a div
+     * const result = await sv.identity.render({
+     *   target: document.getElementById('auth-container'),
+     *   email: 'user@example.com'
+     * });
+     *
+     * @example
+     * // Render in a custom dialog without header/footer
+     * const result = await sv.identity.render({
+     *   target: dialogContentElement,
+     *   showHeader: false,
+     *   showFooter: false
+     * });
+     */
+    render(options: RenderOptions): Promise<VerifyResult>;
+    /**
+     * Verify and decode an identity token.
+     * Validates the token structure, expiry, and issuer.
+     *
+     * Note: For production use, verify the Ed25519 signature server-side
+     * using the JWKS endpoint.
+     *
+     * @example
+     * const claims = await sv.identity.verifyToken(token);
+     * console.log(claims.identity, claims.identity_type, claims.method);
+     */
+    verifyToken(token: string): Promise<TokenClaims>;
+    /**
+     * Close the identity modal if open.
+     */
+    close(): void;
+    /**
+     * @deprecated Use `pop()` instead. Will be removed in v2.0.
+     */
+    verify(options?: VerifyOptions): Promise<VerifyResult>;
+}
+export type { VerifyOptions, RenderOptions, VerifyResult, TokenClaims, AuthMethod, Theme, SdkConfig, SdkConfigBranding, MethodId, MethodMetadata, } from './types';
+export { METHOD_REGISTRY, getMethodMetadata, enrichMethods } from './methods';
+export { IdentityApi, IdentityApiError } from './api';

package/dist/identity/inline-container.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Inline Container
+ *
+ * Renders identity verification UI inline within a target element.
+ * Unlike ModalContainer which creates an overlay popup, this embeds
+ * directly into the customer's page/dialog where render() was called.
+ *
+ * Implements the Container interface for use with IdentityRenderer.
+ */
+import type { Container } from './container';
+import type { SdkConfigBranding } from './types';
+export interface InlineContainerOptions {
+    /** Show header with branding and optional close button */
+    showHeader?: boolean;
+    /** Show close button in header (requires showHeader) */
+    showCloseButton?: boolean;
+    /** Show footer with SparkVault branding */
+    showFooter?: boolean;
+}
+export declare class InlineContainer implements Container {
+    private readonly targetElement;
+    private readonly containerOptions;
+    private container;
+    private header;
+    private body;
+    private footer;
+    private closeBtn;
+    private onCloseCallback;
+    private closeBtnClickHandler;
+    private effectiveTheme;
+    constructor(targetElement: HTMLElement, options?: InlineContainerOptions);
+    /**
+     * Create the inline container with loading state.
+     */
+    createLoading(_options: {
+        backdropBlur?: boolean;
+    }, onClose: () => void): void;
+    /**
+     * Update branding after SDK config loads.
+     */
+    updateBranding(branding: SdkConfigBranding): void;
+    /**
+     * Update backdrop blur setting (no-op for inline container).
+     */
+    updateBackdropBlur(_enabled: boolean): void;
+    /**
+     * Get the body element for content rendering.
+     */
+    getBody(): HTMLDivElement | null;
+    /**
+     * Check if the container is currently active.
+     */
+    isOpen(): boolean;
+    /**
+     * Destroy the container and clean up.
+     */
+    destroy(): void;
+    private createHeader;
+    private handleClose;
+}

package/dist/identity/methods.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Method Registry
+ *
+ * Static metadata for all authentication methods.
+ * API returns method IDs; SDK enriches with this metadata for rendering.
+ */
+import type { MethodId, MethodMetadata } from './types';
+/**
+ * Static method metadata registry
+ */
+export declare const METHOD_REGISTRY: Record<MethodId, MethodMetadata>;
+/**
+ * Get method metadata by ID
+ * @param id - Method ID from config
+ * @returns Method metadata or undefined if not found
+ */
+export declare function getMethodMetadata(id: MethodId): MethodMetadata | undefined;
+/**
+ * Enrich method IDs with full metadata
+ * @param ids - Array of method IDs from config
+ * @returns Array of method metadata objects
+ */
+export declare function enrichMethods(ids: MethodId[]): MethodMetadata[];