@sparkvault/sdk 1.1.6 → 1.8.2

package/README.md

@@ -198,7 +198,7 @@ const result = await sparkvault.identity.pop();
 
 ## Identity Verification
 
-The Identity module provides passwordless authentication through a beautiful, customizable modal. Users can verify via passkeys, email codes, SMS codes, magic links, or social providers.
+The Identity module provides passwordless authentication through a beautiful, customizable modal. Users can verify via passkeys, email codes, SMS codes, SparkLink, or social providers.
 
 ### Basic Usage
 
@@ -275,13 +275,13 @@ Authentication methods are configured in your Identity App settings. The SDK aut
 | `totp_email` | 6-digit code sent via email | Email |
 | `totp_sms` | 6-digit code sent via SMS | Phone |
 | `totp_voice` | 6-digit code sent via voice call | Phone |
-| `magic_link` / `sparklink` | One-click magic link via email | Email |
-| `google` | Sign in with Google | Email |
-| `apple` | Sign in with Apple | Email |
-| `microsoft` | Sign in with Microsoft | Email |
-| `github` | Sign in with GitHub | Email |
-| `facebook` | Sign in with Facebook | Email |
-| `linkedin` | Sign in with LinkedIn | Email |
+| `sparklink` | One-click sign-in link via email | Email |
+| `social_google` | Sign in with Google | Email |
+| `social_apple` | Sign in with Apple | Email |
+| `social_microsoft` | Sign in with Microsoft | Email |
+| `social_github` | Sign in with GitHub | Email |
+| `social_facebook` | Sign in with Facebook | Email |
+| `social_linkedin` | Sign in with LinkedIn | Email |
 
 ## Backend Token Verification
 

package/dist/auto-init.d.ts

@@ -1,51 +1,32 @@
 /**
  * SparkVault Auto-Initialization
  *
- * Enables zero-config initialization via script tag data attributes.
+ * Auto-initializes the SDK from 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>
+ *
+ * <script>
+ *   // SDK is ready - just use it
+ *   SparkVault.identity.attach('.login-btn', {
+ *     onSuccess: (result) => console.log('Verified:', result.identity)
+ *   });
+ * </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
+ * 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
+ * Returns the initialized instance if data-account-id is present, null otherwise.
  */
-export declare function cleanup(): void;
+export declare function autoInit(SparkVaultClass: typeof SparkVault): SparkVault | null;

package/dist/config.d.ts

@@ -13,6 +13,8 @@ export interface SparkVaultConfig {
      * Set to false to defer config loading until verify() is called.
      */
     preloadConfig?: boolean;
+    /** Enable backdrop blur on dialogs (default: true) */
+    backdropBlur?: boolean;
 }
 export interface ResolvedConfig {
     accountId: string;
@@ -20,6 +22,7 @@ export interface ResolvedConfig {
     apiBaseUrl: string;
     identityBaseUrl: string;
     preloadConfig: boolean;
+    backdropBlur: boolean;
 }
 export declare function resolveConfig(config: SparkVaultConfig): ResolvedConfig;
 export declare function validateConfig(config: SparkVaultConfig): void;

package/dist/identity/api.d.ts

@@ -5,7 +5,7 @@
  * Single responsibility: API calls only.
  */
 import type { ResolvedConfig } from '../config';
-import type { SdkConfig, TotpSendResponse, TotpVerifyResponse, PasskeyChallengeResponse, PasskeyVerifyResponse, SparkLinkSendResponse, SparkLinkStatusResponse } from './types';
+import type { SdkConfig, TotpSendResponse, TotpVerifyResponse, PasskeyChallengeResponse, PasskeyVerifyResponse, SparkLinkSendResponse, SparkLinkStatusResponse, AuthContext } from './types';
 export declare class IdentityApi {
     private readonly config;
     private readonly timeoutMs;
@@ -40,12 +40,18 @@ export declare class IdentityApi {
         email_valid: boolean;
         hasPasskey: boolean;
     }>;
+    /**
+     * Build auth context params for API requests (OIDC/simple mode).
+     * Converts AuthContext to snake_case params expected by backend.
+     */
+    private buildAuthContextParams;
     /**
      * Send TOTP code to email or phone
      */
     sendTotp(params: {
         recipient: string;
         method: 'email' | 'sms' | 'voice';
+        authContext?: AuthContext;
     }): Promise<TotpSendResponse>;
     /**
      * Verify TOTP code
@@ -54,6 +60,7 @@ export declare class IdentityApi {
         kindling: string;
         pin: string;
         recipient: string;
+        authContext?: AuthContext;
     }): Promise<TotpVerifyResponse>;
     /**
      * Start passkey registration
@@ -69,31 +76,28 @@ export declare class IdentityApi {
     /**
      * Start passkey verification
      */
-    startPasskeyVerify(email: string): Promise<PasskeyChallengeResponse>;
+    startPasskeyVerify(email: string, authContext?: AuthContext): Promise<PasskeyChallengeResponse>;
     /**
      * Complete passkey verification
      */
     completePasskeyVerify(params: {
         session: Record<string, unknown>;
         credential: PublicKeyCredential;
+        authContext?: AuthContext;
     }): 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.
      * Includes openerOrigin for postMessage-based completion notification.
      */
-    sendSparkLink(email: string): Promise<SparkLinkSendResponse>;
+    sendSparkLink(email: string, authContext?: AuthContext): Promise<SparkLinkSendResponse>;
     /**
      * Check SparkLink verification status (polling endpoint)
      */
-    checkSparkLinkStatus(sparkId: string): Promise<SparkLinkStatusResponse>;
+    checkSparkLinkStatus(sparkId: string, _authContext?: AuthContext): Promise<SparkLinkStatusResponse>;
 }
 export declare class IdentityApiError extends Error {
     readonly code: string;

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

@@ -1,8 +1,15 @@
 /**
  * Passkey Handler
  *
- * Single responsibility: WebAuthn passkey registration and verification.
- * Extracts passkey logic from IdentityRenderer for better separation of concerns.
+ * Handles WebAuthn passkey registration and verification via popup.
+ * Uses a popup window on sparkvault.com domain to ensure WebAuthn works
+ * correctly when the SDK is embedded on third-party client domains.
+ *
+ * Flow:
+ * 1. SDK opens popup to sparkvault.com/passkey/popup
+ * 2. Popup executes WebAuthn (origin = sparkvault.com matches RP ID)
+ * 3. Popup sends result via postMessage
+ * 4. SDK receives result and returns to caller
  */
 import type { IdentityApi } from '../api';
 import type { VerifyResult } from '../types';
@@ -14,7 +21,7 @@ export interface PasskeyResult {
     success: boolean;
     result?: VerifyResult;
     error?: string;
-    errorType?: 'cancelled' | 'not_found' | 'not_allowed' | 'unknown';
+    errorType?: 'cancelled' | 'not_found' | 'not_allowed' | 'popup_blocked' | 'unknown';
 }
 /**
  * Result of passkey check operation
@@ -26,11 +33,13 @@ export interface PasskeyCheckResult {
     hasPasskey: boolean;
 }
 /**
- * Handles WebAuthn passkey registration and verification
+ * Handles WebAuthn passkey registration and verification via popup
  */
 export declare class PasskeyHandler {
     private readonly api;
     private readonly state;
+    private readonly baseUrl;
+    private readonly accountId;
     constructor(api: IdentityApi, state: VerificationState);
     /**
      * Check if user has registered passkeys and validate email domain
@@ -38,15 +47,23 @@ export declare class PasskeyHandler {
      */
     checkPasskey(): Promise<PasskeyCheckResult | null>;
     /**
-     * Register a new passkey for the user
+     * Register a new passkey for the user via popup
      */
     register(): Promise<PasskeyResult>;
     /**
-     * Verify user with existing passkey
+     * Verify user with existing passkey via popup
      */
     verify(): Promise<PasskeyResult>;
     /**
-     * Handle WebAuthn errors and categorize them
+     * Open passkey popup and wait for result
+     */
+    private openPasskeyPopup;
+    /**
+     * Validate that a message origin is from sparkvault.com domain
+     */
+    private isValidMessageOrigin;
+    /**
+     * Handle popup error response
      */
-    private handleError;
+    private handlePopupError;
 }

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

@@ -1,7 +1,7 @@
 /**
  * SparkLink Handler
  *
- * Single responsibility: SparkLink (magic link) sending and status polling.
+ * Single responsibility: SparkLink sending and status polling.
  * Extracts SparkLink logic from IdentityRenderer for better separation of concerns.
  */
 import type { IdentityApi } from '../api';
@@ -23,9 +23,11 @@ export interface SparkLinkStatusResult {
     token?: string;
     identity?: string;
     identityType?: string;
+    /** Redirect URL for OIDC/simple mode flows */
+    redirect?: string;
 }
 /**
- * Handles SparkLink (magic link) sending and verification polling
+ * Handles SparkLink sending and verification polling
  */
 export declare class SparkLinkHandler {
     private readonly api;

package/dist/identity/index.d.ts

@@ -1,69 +1,87 @@
 /**
  * Identity Module
  *
- * Provides identity verification through a DOM-based modal interface.
- * Supports passkey, TOTP, magic link, and social authentication.
+ * Provides identity verification through dialog or inline UI.
+ * Supports passkey, TOTP, SparkLink, and social authentication.
+ *
+ * @example Dialog mode (immediate)
+ * const result = await sv.identity.verify();
+ *
+ * @example Dialog mode (attached to clicks)
+ * sv.identity.attach('.login-btn');
+ *
+ * @example Inline mode
+ * const result = await sv.identity.verify({ target: '#auth-container' });
  */
 import type { ResolvedConfig } from '../config';
-import type { VerifyOptions, VerifyResult, TokenClaims, RenderOptions } from './types';
+import type { VerifyOptions, VerifyResult, TokenClaims, AttachOptions } from './types';
 export declare class IdentityModule {
     private readonly config;
     private readonly api;
     private renderer;
+    private attachedElements;
     constructor(config: ResolvedConfig);
     /**
-     * Open the identity verification modal (popup).
-     * Returns when user successfully verifies their identity.
+     * Verify user identity.
      *
-     * @example
-     * const result = await sv.identity.pop({
+     * - Without `target`: Opens a dialog (modal)
+     * - With `target`: Renders inline into the specified element
+     *
+     * @example Dialog mode
+     * const result = await sv.identity.verify();
+     * console.log(result.token, result.identity);
+     *
+     * @example Inline mode
+     * const result = await sv.identity.verify({
+     *   target: '#auth-container',
      *   email: 'user@example.com'
      * });
-     * console.log(result.token, result.identity, result.identityType);
      */
-    pop(options?: VerifyOptions): Promise<VerifyResult>;
+    verify(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.
+     * Attach identity verification to element clicks.
+     * When any matching element is clicked, opens the verification dialog.
      *
-     * @example
-     * // Render in a div
-     * const result = await sv.identity.render({
-     *   target: document.getElementById('auth-container'),
-     *   email: 'user@example.com'
-     * });
+     * @param selector - CSS selector for elements to attach to
+     * @param options - Verification options and callbacks
+     * @returns Cleanup function to remove event listeners
      *
      * @example
-     * // Render in a custom dialog without header/footer
-     * const result = await sv.identity.render({
-     *   target: dialogContentElement,
-     *   showHeader: false,
-     *   showFooter: false
+     * const cleanup = sv.identity.attach('.login-btn', {
+     *   onSuccess: (result) => console.log('Verified:', result.identity)
      * });
+     *
+     * // Later, remove listeners
+     * cleanup();
      */
-    render(options: RenderOptions): Promise<VerifyResult>;
+    attach(selector: string, options?: AttachOptions): () => void;
     /**
      * 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 the identity dialog/inline UI if open.
      */
     close(): void;
     /**
-     * @deprecated Use `pop()` instead. Will be removed in v2.0.
+     * Resolve target to an HTMLElement.
      */
-    verify(options?: VerifyOptions): Promise<VerifyResult>;
+    private createInlineContainer;
+    /**
+     * @deprecated Use `verify()` instead. Will be removed in v2.0.
+     */
+    pop(options?: VerifyOptions): Promise<VerifyResult>;
+    /**
+     * @deprecated Use `verify({ target })` instead. Will be removed in v2.0.
+     */
+    render(options: VerifyOptions & {
+        target: HTMLElement;
+    }): Promise<VerifyResult>;
 }
-export type { VerifyOptions, RenderOptions, VerifyResult, TokenClaims, AuthMethod, Theme, SdkConfig, SdkConfigBranding, MethodId, MethodMetadata, } from './types';
+export type { VerifyOptions, AttachOptions, VerifyResult, TokenClaims, AuthMethod, AuthContext, Theme, SdkConfig, SdkConfigBranding, MethodId, MethodMetadata, } from './types';
 export { METHOD_REGISTRY, getMethodMetadata, enrichMethods } from './methods';
 export { IdentityApi, IdentityApiError } from './api';

package/dist/identity/renderer.d.ts

@@ -65,6 +65,14 @@ export declare class IdentityRenderer {
     private handlePasskeyRegistrationSkip;
     private handleSocialLogin;
     private normalizeError;
+    /**
+     * Check if error is a session/token expiration that should redirect to identity input.
+     */
+    private isSessionExpiredError;
+    /**
+     * Handle errors - redirect to identity input for session errors, show error view otherwise.
+     */
+    private handleErrorWithRecovery;
     /**
      * Check if we should show the passkey registration prompt after PIN verification.
      */

package/dist/identity/state.d.ts

@@ -7,7 +7,7 @@
  * - Easier debugging and testing
  * - Clear data ownership
  */
-import type { SdkConfig, VerifyResult, IdentityViewState, MethodMetadata } from './types';
+import type { SdkConfig, VerifyResult, IdentityViewState, MethodMetadata, AuthContext } from './types';
 import type { IdentityType } from './views';
 /**
  * Passkey-specific state
@@ -37,6 +37,7 @@ export declare class VerificationState {
     private _viewState;
     private _recipient;
     private _identityType;
+    private _authContext;
     private readonly _passkey;
     private readonly _totp;
     private readonly listeners;
@@ -67,6 +68,8 @@ export declare class VerificationState {
     get identityType(): IdentityType;
     setIdentity(recipient: string, type: IdentityType): void;
     getAllowedIdentityTypes(): IdentityType[];
+    get authContext(): AuthContext | undefined;
+    setAuthContext(context: AuthContext | undefined): void;
     get passkey(): Readonly<PasskeyState>;
     setPasskeyStatus(hasPasskey: boolean | null): void;
     enablePasskeyFallback(): void;

package/dist/identity/types.d.ts

@@ -1,31 +1,59 @@
 /**
  * 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 AuthMethod = 'passkey' | 'totp_email' | 'totp_sms' | 'totp_voice' | 'sparklink' | 'social_google' | 'social_apple' | 'social_microsoft' | 'social_github' | 'social_facebook' | 'social_linkedin';
 export type Theme = 'light' | 'dark';
+/**
+ * Auth context for OIDC or simple redirect flows.
+ * Used by hosted login pages to complete authorization flows.
+ */
+export interface AuthContext {
+    /** OIDC auth request ID for authorization code flow */
+    authRequestId?: string;
+    /** Simple redirect mode configuration */
+    simpleMode?: {
+        successUrl: string;
+        failureUrl: string;
+        state?: string;
+    };
+}
 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 */
+    /**
+     * Target element for inline rendering. Can be:
+     * - A CSS selector string (e.g., "#auth-container")
+     * - An HTMLElement reference
+     * - Omitted for dialog mode (default)
+     */
+    target?: string | HTMLElement;
+    /** Override backdrop blur for this dialog (uses global config if omitted) */
     backdropBlur?: boolean;
-    /** Called when user cancels */
+    /** Auth context for OIDC/simple mode flows (used by hosted login) */
+    authContext?: AuthContext;
+    /** Called when user cancels (if omitted, uses server-configured redirect) */
     onCancel?: () => void;
-    /** Called when verification completes (before promise resolves) */
+    /** Called when verification completes (if omitted, uses server-configured redirect) */
     onSuccess?: (result: VerifyResult) => void;
-    /** Called on error (before promise rejects) */
+    /** Called on error (if omitted, uses server-configured redirect) */
     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;
+/** Options for attach() - binds verification to element clicks */
+export interface AttachOptions {
+    /** Pre-fill email address */
+    email?: string;
+    /** Pre-fill phone number in E.164 format */
+    phone?: string;
+    /** Auth context for OIDC/simple mode flows */
+    authContext?: AuthContext;
+    /** Called when user cancels */
+    onCancel?: () => void;
+    /** Called when verification completes */
+    onSuccess?: (result: VerifyResult) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
 }
 export interface VerifyResult {
     /** Signed JWT token */
@@ -34,6 +62,8 @@ export interface VerifyResult {
     identity: string;
     /** Type of identity verified */
     identityType: 'email' | 'phone';
+    /** Redirect URL (only present for OIDC/simple mode flows) */
+    redirect?: string;
 }
 export interface TokenClaims {
     /** Issuer */
@@ -74,7 +104,7 @@ export interface SdkConfigBranding {
     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 type MethodId = 'totp_email' | 'totp_sms' | 'totp_voice' | 'passkey' | 'sparklink' | 'social_google' | 'social_apple' | 'social_microsoft' | 'social_github' | 'social_facebook' | 'social_linkedin';
 export interface SdkConfig {
     accountId: string;
     /** Branding configuration (optional in v1 - uses defaults if not provided) */
@@ -87,13 +117,13 @@ export interface SdkConfig {
 /** Method metadata for SDK rendering (static lookup) */
 export interface MethodMetadata {
     id: MethodId;
-    type: 'totp' | 'passkey' | 'magic_link' | 'social' | 'enterprise' | 'hris';
+    type: 'totp' | 'passkey' | 'sparklink' | 'social';
     /** Which identity type this method requires */
     identityType: 'email' | 'phone';
     name: string;
     description: string;
     icon: string;
-    /** Provider name for social/enterprise/hris methods */
+    /** Provider name for social methods */
     provider?: string;
 }
 export interface TotpSendResponse {
@@ -109,6 +139,8 @@ export interface TotpVerifyResponse {
     identity?: string;
     /** Identity type - 'email' or 'phone' */
     identity_type?: 'email' | 'phone';
+    /** Redirect URL for OIDC/simple mode flows */
+    redirect?: string;
     /** Returned on failure - new kindling for next attempt */
     kindling?: string;
     /** Returned on failure - seconds until next attempt allowed */
@@ -134,6 +166,8 @@ export interface PasskeyVerifyResponse {
     token: string;
     identity: string;
     identity_type: 'email' | 'phone';
+    /** Redirect URL for OIDC/simple mode flows */
+    redirect?: string;
 }
 export interface SparkLinkSendResponse {
     sparkId: string;
@@ -144,6 +178,8 @@ export interface SparkLinkStatusResponse {
     token?: string;
     identity?: string;
     identityType?: string;
+    /** Redirect URL for OIDC/simple mode flows */
+    redirect?: string;
 }
 export type IdentityViewState = {
     view: 'loading';
@@ -170,6 +206,7 @@ export type IdentityViewState = {
     view: 'passkey-prompt';
     email: string;
     pendingResult: VerifyResult;
+    error?: string;
 } | {
     view: 'sparklink-waiting';
     email: string;

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

@@ -21,7 +21,7 @@ export declare function createCloseIcon(): SVGSVGElement;
  */
 export declare function createAuthShieldIcon(): SVGSVGElement;
 /**
- * Passkey icon
+ * Passkey icon - simple key design
  */
 export declare function createPasskeyIcon(): SVGSVGElement;
 /**

package/dist/identity/views/passkey-prompt.d.ts

@@ -9,6 +9,8 @@ export interface PasskeyPromptViewProps {
     email: string;
     onAddPasskey: () => void;
     onSkip: () => void;
+    /** Error message to display when registration fails */
+    error?: string;
 }
 export declare class PasskeyPromptView implements View {
     private readonly props;