@sparkvault/sdk 1.0.0

package/dist/identity/modal.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Identity Modal Container
+ *
+ * Single responsibility: DOM modal container lifecycle.
+ * Creates, shows, hides, and destroys the modal overlay and container.
+ * Does NOT handle content rendering - that's the Renderer's job.
+ */
+import type { SdkConfigBranding } from './types';
+import type { Container } from './container';
+export interface ModalOptions {
+    branding: SdkConfigBranding;
+    /** Enable backdrop blur (default: true) */
+    backdropBlur?: boolean;
+}
+export interface ModalContainerElements {
+    overlay: HTMLDivElement;
+    modal: HTMLDivElement;
+    header: HTMLDivElement;
+    body: HTMLDivElement;
+    footer: HTMLDivElement;
+}
+export declare class ModalContainer implements Container {
+    private elements;
+    private onCloseCallback;
+    private keydownHandler;
+    private overlayClickHandler;
+    private closeBtnClickHandler;
+    private closeBtn;
+    private backdropBlur;
+    private effectiveTheme;
+    private headerElement;
+    /**
+     * Create and show the modal immediately with loading state.
+     * Uses default branding until real config is loaded.
+     * This provides instant visual feedback to the user.
+     */
+    createLoading(options: {
+        backdropBlur?: boolean;
+    }, onClose: () => void): ModalContainerElements;
+    /**
+     * Update the modal header and styles with real branding.
+     * Called after SDK config loads.
+     */
+    updateBranding(branding: SdkConfigBranding): void;
+    /**
+     * Update the backdrop blur setting.
+     * Called after SDK config loads with resolved value (client override > server config > default).
+     */
+    updateBackdropBlur(enabled: boolean): void;
+    /**
+     * Create and show the modal container.
+     * Returns the container elements for the renderer to populate.
+     */
+    create(options: ModalOptions, onClose: () => void): ModalContainerElements;
+    private createHeader;
+    private handleClose;
+    /**
+     * Get the modal body element for content rendering.
+     */
+    getBody(): HTMLDivElement | null;
+    /**
+     * Check if the modal is currently open.
+     */
+    isOpen(): boolean;
+    /**
+     * Destroy the modal and clean up all event listeners.
+     */
+    destroy(): void;
+}
+/**
+ * Escape HTML to prevent XSS.
+ * Used for any user-provided content rendered in the modal.
+ */
+export declare function escapeHtml(str: string): string;

package/dist/identity/renderer.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Identity View Renderer
+ *
+ * Orchestrates view state and rendering for identity verification flows.
+ * Uses extracted handlers for TOTP and Passkey operations.
+ */
+import type { VerifyOptions, VerifyResult } from './types';
+import { IdentityApi } from './api';
+import type { Container } from './container';
+interface RendererCallbacks {
+    onSuccess: (result: VerifyResult) => void;
+    onError: (error: Error) => void;
+    onCancel: () => void;
+}
+export declare class IdentityRenderer {
+    private readonly api;
+    private readonly container;
+    private readonly options;
+    private readonly callbacks;
+    private readonly verificationState;
+    private readonly passkeyHandler;
+    private readonly totpHandler;
+    private readonly sparkLinkHandler;
+    private currentView;
+    private focusTimeoutId;
+    private pollingInterval;
+    constructor(container: Container, api: IdentityApi, options: VerifyOptions, callbacks: RendererCallbacks);
+    private get recipient();
+    private get identityType();
+    private get sdkConfig();
+    /**
+     * Start the identity verification flow.
+     * If config was preloaded, opens modal and proceeds immediately.
+     * Otherwise shows loading state while fetching config.
+     */
+    start(): Promise<void>;
+    /**
+     * Close the modal and clean up.
+     */
+    close(): void;
+    private handleClose;
+    private get viewState();
+    private setState;
+    private render;
+    private destroyCurrentView;
+    private createViewForState;
+    private showIdentityInput;
+    private showMethodSelect;
+    private handleIdentitySubmit;
+    private getAllowedIdentityTypes;
+    private handleMethodSelect;
+    private handleTotpSubmit;
+    private handleTotpResend;
+    private handlePasskeyStart;
+    /**
+     * Handle fallback from passkey to email/SMS code.
+     * User clicked "Having trouble? Use email code instead".
+     */
+    private handlePasskeyFallback;
+    /**
+     * Handle skipping passkey registration when coming from passkey prompt.
+     * User clicked "Back" or cancelled registration after being prompted.
+     */
+    private handlePasskeyRegistrationSkip;
+    private handleSocialLogin;
+    private normalizeError;
+    /**
+     * Check if we should show the passkey registration prompt after PIN verification.
+     */
+    private shouldShowPasskeyPrompt;
+    /**
+     * Handle user clicking "Add Passkey" in the prompt.
+     * Directly triggers browser passkey creation without intermediate screen.
+     */
+    private handlePasskeyPromptAdd;
+    /**
+     * Handle user clicking "Not now" / "Skip" in the prompt.
+     */
+    private handlePasskeyPromptSkip;
+    /**
+     * Start polling for SparkLink verification status.
+     */
+    private startSparkLinkPolling;
+    /**
+     * Stop SparkLink polling.
+     */
+    private stopSparkLinkPolling;
+    /**
+     * Handle resending SparkLink.
+     */
+    private handleSparkLinkResend;
+    /**
+     * Handle fallback from SparkLink to TOTP verification code.
+     */
+    private handleSparkLinkFallback;
+}
+export {};

package/dist/identity/state.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Verification State Manager
+ *
+ * Single source of truth for all verification flow state.
+ * Centralizes scattered state from IdentityRenderer for:
+ * - Predictable state transitions
+ * - Easier debugging and testing
+ * - Clear data ownership
+ */
+import type { SdkConfig, VerifyResult, IdentityViewState, MethodMetadata } from './types';
+import type { IdentityType } from './views';
+/**
+ * Passkey-specific state
+ */
+interface PasskeyState {
+    /** Whether user has registered passkeys (null = unknown) */
+    hasPasskey: boolean | null;
+    /** Whether user fell back from passkey to another method */
+    isFallbackMode: boolean;
+    /** Pending result when prompting for passkey registration after TOTP */
+    pendingResult: VerifyResult | null;
+}
+/**
+ * TOTP-specific state
+ */
+interface TotpState {
+    /** Current kindling token for TOTP verification */
+    kindling: string;
+    /** Current TOTP method (email or sms) */
+    method: 'email' | 'sms' | null;
+}
+/**
+ * Centralized verification state
+ */
+export declare class VerificationState {
+    private _sdkConfig;
+    private _viewState;
+    private _recipient;
+    private _identityType;
+    private readonly _passkey;
+    private readonly _totp;
+    private readonly listeners;
+    /**
+     * Subscribe to state changes
+     * @param listener - Callback invoked on state change
+     * @returns Unsubscribe function
+     */
+    subscribe(listener: (state: IdentityViewState) => void): () => void;
+    /**
+     * Notify all listeners of state change
+     */
+    private notify;
+    get sdkConfig(): SdkConfig | null;
+    setConfig(config: SdkConfig): void;
+    get accountId(): string;
+    /**
+     * Get enriched methods filtered by identity type
+     */
+    getAvailableMethods(): MethodMetadata[];
+    /**
+     * Check if passkey method is enabled in config
+     */
+    isPasskeyEnabled(): boolean;
+    get viewState(): IdentityViewState;
+    setViewState(state: IdentityViewState): void;
+    get recipient(): string;
+    get identityType(): IdentityType;
+    setIdentity(recipient: string, type: IdentityType): void;
+    getAllowedIdentityTypes(): IdentityType[];
+    get passkey(): Readonly<PasskeyState>;
+    setPasskeyStatus(hasPasskey: boolean | null): void;
+    enablePasskeyFallback(): void;
+    setPendingResult(result: VerifyResult | null): void;
+    /**
+     * Check if we should show passkey registration prompt
+     * Based on: passkey enabled, user doesn't have one, not dismissed
+     */
+    shouldShowPasskeyPrompt(): boolean;
+    /**
+     * Check if passkey prompt was dismissed (30-day cookie)
+     */
+    private isPasskeyPromptDismissed;
+    /**
+     * Dismiss passkey prompt for 30 days
+     */
+    dismissPasskeyPrompt(): void;
+    get totp(): Readonly<TotpState>;
+    setKindling(kindling: string): void;
+    setTotpMethod(method: 'email' | 'sms'): void;
+    /**
+     * Reset state for new verification attempt
+     */
+    reset(): void;
+}
+export {};

package/dist/identity/styles.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Identity Modal Styles
+ *
+ * Enterprise-grade styling following Stripe/Adobe design principles:
+ * - Clean, minimal aesthetic with purposeful whitespace
+ * - 4px base spacing unit for consistency
+ * - Subtle depth through shadows and borders (not gradients)
+ * - Professional typography with clear hierarchy
+ * - Refined color palette with single accent
+ */
+import type { SdkConfigBranding } from './types';
+export interface StyleOptions {
+    branding: SdkConfigBranding;
+    backdropBlur?: boolean;
+}
+/**
+ * Inject modal styles into the document head.
+ */
+export declare function injectStyles(options: StyleOptions): void;
+export declare function updateThemeVariables(_branding: SdkConfigBranding | undefined | null): void;
+export declare function removeStyles(): void;
+export declare function resolveTheme(branding: SdkConfigBranding | undefined | null): 'light' | 'dark';

package/dist/identity/types.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Identity Module Types
+ */
+export type AuthMethod = 'passkey' | 'totp_email' | 'totp_sms' | 'totp_voice' | 'magic_link' | 'sparklink' | 'google' | 'apple' | 'microsoft' | 'github' | 'facebook' | 'linkedin' | 'social_google' | 'social_apple' | 'social_microsoft' | 'social_github' | 'social_facebook' | 'social_linkedin';
+export type Theme = 'light' | 'dark';
+export interface VerifyOptions {
+    /** Pre-fill email address (mutually exclusive with phone) */
+    email?: string;
+    /** Pre-fill phone number in E.164 format, e.g. "+14155551234" (mutually exclusive with email) */
+    phone?: string;
+    /** Override backdrop blur setting from app config */
+    backdropBlur?: boolean;
+    /** Called when user cancels */
+    onCancel?: () => void;
+    /** Called when verification completes (before promise resolves) */
+    onSuccess?: (result: VerifyResult) => void;
+    /** Called on error (before promise rejects) */
+    onError?: (error: Error) => void;
+}
+export interface RenderOptions extends VerifyOptions {
+    /** Target element to render inline UI into (required) */
+    target: HTMLElement;
+    /** Show header with branding and close button (default: true) */
+    showHeader?: boolean;
+    /** Show close button in header (default: true, requires showHeader) */
+    showCloseButton?: boolean;
+    /** Show footer with SparkVault branding (default: true) */
+    showFooter?: boolean;
+}
+export interface VerifyResult {
+    /** Signed JWT token */
+    token: string;
+    /** Verified identity (email or phone) */
+    identity: string;
+    /** Type of identity verified */
+    identityType: 'email' | 'phone';
+}
+export interface TokenClaims {
+    /** Issuer */
+    iss: string;
+    /** Subject (hashed identity) */
+    sub: string;
+    /** Audience (account ID for simple tokens, client ID for OIDC) */
+    aud: string;
+    /** Expiry (Unix seconds) */
+    exp: number;
+    /** Issued at (Unix seconds) */
+    iat: number;
+    /** Unique token ID for replay protection */
+    jti?: string;
+    /** Verified identity (email or phone) */
+    identity: string;
+    /** Identity type */
+    identity_type: 'email' | 'phone';
+    /** Verification timestamp (Unix seconds) */
+    verified_at: number;
+    /** Authentication method used */
+    method: string;
+}
+export interface EmbedMessage {
+    type: 'sparkvault:identity:result' | 'sparkvault:identity:cancel' | 'sparkvault:identity:error' | 'sparkvault:identity:ready';
+    payload?: VerifyResult | {
+        error: string;
+        code: string;
+    };
+}
+export interface SdkConfigBranding {
+    companyName: string;
+    logoLight: string | null;
+    logoDark: string | null;
+    /** Backdrop blur setting (default: true) */
+    backdrop_blur?: boolean;
+    /** Theme mode from server config */
+    themeMode?: 'light' | 'dark';
+}
+/** Method ID returned by config endpoint */
+export type MethodId = 'totp_email' | 'totp_sms' | 'totp_voice' | 'passkey' | 'sparklink' | 'social_google' | 'social_apple' | 'social_microsoft' | 'social_github' | 'social_facebook' | 'social_linkedin' | 'enterprise_okta' | 'enterprise_entra' | 'enterprise_onelogin' | 'enterprise_ping' | 'enterprise_jumpcloud' | 'hris_bamboohr' | 'hris_workday' | 'hris_adp' | 'hris_gusto' | 'hris_rippling';
+export interface SdkConfig {
+    accountId: string;
+    /** Branding configuration (optional in v1 - uses defaults if not provided) */
+    branding?: SdkConfigBranding;
+    /** Allowed identity types: 'email', 'phone', or both */
+    allowedIdentityTypes?: ('email' | 'phone')[];
+    /** Enabled method IDs */
+    methods: MethodId[];
+}
+/** Method metadata for SDK rendering (static lookup) */
+export interface MethodMetadata {
+    id: MethodId;
+    type: 'totp' | 'passkey' | 'magic_link' | 'social' | 'enterprise' | 'hris';
+    /** Which identity type this method requires */
+    identityType: 'email' | 'phone';
+    name: string;
+    description: string;
+    icon: string;
+    /** Provider name for social/enterprise/hris methods */
+    provider?: string;
+}
+export interface TotpSendResponse {
+    success: boolean;
+    kindling: string;
+    expires_at: number;
+    method: string;
+}
+export interface TotpVerifyResponse {
+    verified: boolean;
+    token?: string;
+    /** Identity (email or phone) - returned on success */
+    identity?: string;
+    /** Identity type - 'email' or 'phone' */
+    identity_type?: 'email' | 'phone';
+    /** Returned on failure - new kindling for next attempt */
+    kindling?: string;
+    /** Returned on failure - seconds until next attempt allowed */
+    retry_after?: number;
+    /** Returned on failure - when the backoff expires */
+    expires_at?: number;
+}
+export interface PasskeyChallengeResponse {
+    challenge: string;
+    rpId: string;
+    rpName: string;
+    userId?: string;
+    userName?: string;
+    allowCredentials?: Array<{
+        id: string;
+        type: 'public-key';
+    }>;
+    timeout: number;
+}
+export interface PasskeyVerifyResponse {
+    token: string;
+    identity: string;
+    identity_type: 'email' | 'phone';
+}
+export interface SparkLinkSendResponse {
+    sparkId: string;
+    expiresAt: number;
+}
+export interface SparkLinkStatusResponse {
+    verified: boolean;
+    token?: string;
+    identity?: string;
+    identityType?: string;
+}
+export type IdentityViewState = {
+    view: 'loading';
+} | {
+    view: 'identity-input';
+    error?: string;
+} | {
+    view: 'method-select';
+    email: string;
+    methods: MethodMetadata[];
+} | {
+    view: 'totp-verify';
+    email: string;
+    method: 'email' | 'sms';
+    kindling: string;
+    error?: string;
+    backoffExpires?: number;
+} | {
+    view: 'passkey';
+    email: string;
+    mode: 'register' | 'verify';
+    error?: string;
+} | {
+    view: 'passkey-prompt';
+    email: string;
+    pendingResult: VerifyResult;
+} | {
+    view: 'sparklink-waiting';
+    email: string;
+    sparkId: string;
+    expiresAt: number;
+} | {
+    view: 'oauth-pending';
+    provider: string;
+} | {
+    view: 'error';
+    message: string;
+    code: string;
+};

package/dist/identity/utils/cooldown-timer.d.ts

@@ -0,0 +1,73 @@
+/**
+ * CooldownTimer - Reusable countdown utility for resend buttons and rate limiting
+ *
+ * Manages interval-based countdowns with callbacks for tick and completion events.
+ * Properly cleans up intervals to prevent memory leaks.
+ */
+export interface CooldownTimerConfig {
+    /** Duration in seconds */
+    duration: number;
+    /** Called every second with remaining seconds */
+    onTick: (secondsRemaining: number) => void;
+    /** Called when countdown reaches zero */
+    onComplete: () => void;
+}
+export declare class CooldownTimer {
+    private intervalId;
+    private secondsRemaining;
+    private readonly onTick;
+    private readonly onComplete;
+    constructor(config: CooldownTimerConfig);
+    /**
+     * Start the countdown timer
+     * Immediately calls onTick with initial value, then updates every second
+     */
+    start(): void;
+    /**
+     * Stop and clean up the timer
+     */
+    stop(): void;
+    /**
+     * Check if timer is currently running
+     */
+    isRunning(): boolean;
+    /**
+     * Get current remaining seconds
+     */
+    getRemainingSeconds(): number;
+}
+/**
+ * ExpirationTimer - Countdown based on an absolute expiration timestamp
+ *
+ * Unlike CooldownTimer which counts down from a fixed duration,
+ * this calculates remaining time from a UTC timestamp, making it
+ * accurate even if the page was loaded after the timer started.
+ */
+export interface ExpirationTimerConfig {
+    /** UTC timestamp (seconds) when the countdown expires */
+    expiresAt: number;
+    /** Called every second with remaining seconds */
+    onTick: (secondsRemaining: number) => void;
+    /** Called when countdown reaches zero */
+    onExpired: () => void;
+}
+export declare class ExpirationTimer {
+    private intervalId;
+    private readonly expiresAt;
+    private readonly onTick;
+    private readonly onExpired;
+    constructor(config: ExpirationTimerConfig);
+    private calculateRemaining;
+    /**
+     * Start the countdown timer
+     */
+    start(): void;
+    /**
+     * Stop and clean up the timer
+     */
+    stop(): void;
+    /**
+     * Check if timer is currently running
+     */
+    isRunning(): boolean;
+}

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

@@ -0,0 +1,5 @@
+/**
+ * SDK Identity Utilities
+ */
+export { CooldownTimer, ExpirationTimer } from './cooldown-timer';
+export type { CooldownTimerConfig, ExpirationTimerConfig } from './cooldown-timer';

package/dist/identity/utils.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Identity Module Utilities
+ *
+ * Shared utility functions for encoding, validation, and cookie management.
+ * Consolidates duplicated logic from renderer, api, and index.
+ */
+export { CooldownTimer, ExpirationTimer } from './utils/cooldown-timer';
+export type { CooldownTimerConfig, ExpirationTimerConfig } from './utils/cooldown-timer';
+export { arrayBufferToBase64url, base64urlToArrayBuffer, base64urlToString, } from '../utils/base64url';
+/**
+ * Get cookie value by name
+ * @param name - Cookie name
+ * @returns Cookie value or null if not found
+ */
+export declare function getCookie(name: string): string | null;
+/**
+ * Set cookie with expiration
+ * @param name - Cookie name
+ * @param value - Cookie value
+ * @param days - Days until expiration
+ */
+export declare function setCookie(name: string, value: string, days: number): void;
+/**
+ * Generate cryptographically secure random state string
+ * Used for OAuth CSRF protection
+ */
+export declare function generateState(): string;

package/dist/identity/views/base.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Base View Types and Utilities
+ *
+ * Shared interfaces and helpers for all view components.
+ */
+import { escapeHtml } from '../modal';
+/**
+ * Base interface for all view components.
+ * Each view must implement render() to return its DOM element.
+ */
+export interface View {
+    render(): HTMLElement;
+    destroy?(): void;
+}
+/**
+ * Create an element with optional attributes and children.
+ * Type-safe DOM element creation utility.
+ */
+export declare function createElement<K extends keyof HTMLElementTagNameMap>(tag: K, attrs?: Partial<HTMLElementTagNameMap[K]> & {
+    className?: string;
+}, children?: (HTMLElement | string | null | undefined)[]): HTMLElementTagNameMap[K];
+/**
+ * Create a container div with optional class and children.
+ */
+export declare function div(className?: string, children?: (HTMLElement | string | null | undefined)[]): HTMLDivElement;
+/**
+ * Clear all children from an element safely.
+ * Preferred over innerHTML = '' for security and performance.
+ */
+export declare function clearChildren(element: HTMLElement): void;
+/**
+ * Create an error message element.
+ */
+export declare function errorMessage(message: string): HTMLDivElement;
+/**
+ * Validate email format.
+ * Returns sanitized email or null if invalid.
+ */
+export declare function validateEmail(email: string): string | null;
+/**
+ * Validate phone number format.
+ * Accepts various formats, returns E.164 format (+1XXXXXXXXXX) or null if invalid.
+ */
+export declare function validatePhone(phone: string): string | null;
+/**
+ * Format phone number for display as user types.
+ * Formats US numbers as (XXX) XXX-XXXX.
+ */
+export declare function formatPhoneDisplay(phone: string): string;
+/**
+ * Detect if input looks like a phone number (starts with digit or +).
+ */
+export declare function looksLikePhone(input: string): boolean;
+/**
+ * Validate TOTP code format.
+ * Returns sanitized code or null if invalid.
+ */
+export declare function validateTotpCode(code: string): string | null;
+/**
+ * Re-export escapeHtml for convenience.
+ */
+export { escapeHtml };

package/dist/identity/views/error.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Error View
+ *
+ * Professional enterprise-quality error display with clear visual hierarchy.
+ */
+import type { View } from './base';
+export interface ErrorViewProps {
+    message: string;
+    code: string;
+    onRetry: () => void;
+    onClose: () => void;
+}
+export declare class ErrorView implements View {
+    private readonly props;
+    private retryButton;
+    private closeButton;
+    private readonly boundHandleRetry;
+    private readonly boundHandleClose;
+    constructor(props: ErrorViewProps);
+    render(): HTMLElement;
+    /**
+     * Clean up event listeners to prevent memory leaks.
+     */
+    destroy(): void;
+}