@sparkvault/sdk 1.1.5 → 1.8.2

package/dist/index.d.ts

@@ -13,6 +13,8 @@ interface SparkVaultConfig {
      * Set to false to defer config loading until verify() is called.
      */
     preloadConfig?: boolean;
+    /** Enable backdrop blur on dialogs (default: true) */
+    backdropBlur?: boolean;
 }
 interface ResolvedConfig {
     accountId: string;
@@ -20,36 +22,65 @@ interface ResolvedConfig {
     apiBaseUrl: string;
     identityBaseUrl: string;
     preloadConfig: boolean;
+    backdropBlur: boolean;
 }
 
 /**
  * Identity Module Types
  */
-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';
+type AuthMethod = 'passkey' | 'totp_email' | 'totp_sms' | 'totp_voice' | 'sparklink' | 'social_google' | 'social_apple' | 'social_microsoft' | 'social_github' | 'social_facebook' | 'social_linkedin';
 type Theme = 'light' | 'dark';
+/**
+ * Auth context for OIDC or simple redirect flows.
+ * Used by hosted login pages to complete authorization flows.
+ */
+interface AuthContext {
+    /** OIDC auth request ID for authorization code flow */
+    authRequestId?: string;
+    /** Simple redirect mode configuration */
+    simpleMode?: {
+        successUrl: string;
+        failureUrl: string;
+        state?: string;
+    };
+}
 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;
 }
-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 */
+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;
 }
 interface VerifyResult {
     /** Signed JWT token */
@@ -58,6 +89,8 @@ interface VerifyResult {
     identity: string;
     /** Type of identity verified */
     identityType: 'email' | 'phone';
+    /** Redirect URL (only present for OIDC/simple mode flows) */
+    redirect?: string;
 }
 interface TokenClaims {
     /** Issuer */
@@ -85,67 +118,85 @@ interface TokenClaims {
 /**
  * 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' });
  */
 
 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>;
 }
 
 /**
@@ -214,80 +265,6 @@ declare class HttpClient {
     private executeRequestRaw;
 }
 
-/**
- * Sparks Module Types
- */
-interface CreateSparkOptions {
-    /** Secret payload to encrypt */
-    payload: string | Uint8Array;
-    /** Time-to-live in seconds (default: 3600) */
-    ttl?: number;
-    /** Maximum number of reads before destruction (default: 1) */
-    maxReads?: number;
-    /** Optional password protection */
-    password?: string;
-    /** Optional name/label for the spark */
-    name?: string;
-}
-interface Spark {
-    /** Spark ID */
-    id: string;
-    /** Direct URL to read the spark */
-    url: string;
-    /** Expiry timestamp (Unix seconds) */
-    expiresAt: number;
-    /** Maximum reads remaining */
-    maxReads: number;
-    /** Name/label if provided */
-    name?: string;
-}
-interface SparkPayload {
-    /** Decrypted data */
-    data: string | Uint8Array;
-    /** When the spark was read (Unix seconds) */
-    readAt: number;
-    /** Whether the spark was destroyed after reading */
-    burned: boolean;
-    /** Reads remaining (0 if burned) */
-    readsRemaining: number;
-}
-
-/**
- * Sparks Module
- *
- * Create and read ephemeral encrypted secrets.
- * Sparks are destroyed after being read (burn-on-read).
- */
-
-declare class SparksModule {
-    private readonly http;
-    constructor(http: HttpClient);
-    /**
-     * Create an ephemeral encrypted secret.
-     *
-     * @example
-     * const spark = await sv.sparks.create({
-     *   payload: 'my secret data',
-     *   ttl: 3600,
-     *   maxReads: 1
-     * });
-     * console.log(spark.url);
-     */
-    create(options: CreateSparkOptions): Promise<Spark>;
-    /**
-     * Read and burn a spark.
-     * The spark is destroyed after the configured number of reads.
-     *
-     * @example
-     * const payload = await sv.sparks.read('spk_abc123');
-     * console.log(payload.data);
-     */
-    read(id: string, password?: string): Promise<SparkPayload>;
-    private validateCreateOptions;
-    private encodePayload;
-    private decodePayload;
-}
-
 /**
  * Vaults Module Types
  */
@@ -360,6 +337,153 @@ interface UploadIngotOptions {
     contentType?: string;
 }
 
+/**
+ * Vault Upload Module Types
+ *
+ * Types for the embedded vault upload widget.
+ */
+/**
+ * Branding configuration from vault upload info.
+ */
+interface UploadBranding {
+    /** Organization name */
+    organizationName: string;
+    /** Light theme logo URL */
+    logoLightUrl: string | null;
+    /** Dark theme logo URL */
+    logoDarkUrl: string | null;
+}
+/**
+ * Encryption information for the vault.
+ */
+interface EncryptionInfo {
+    /** Encryption algorithm (e.g., 'AES-256-GCM') */
+    algorithm: string;
+    /** Key derivation method (e.g., 'Triple Zero-Trust') */
+    keyDerivation: string;
+    /** Post-quantum protection status */
+    postQuantum: string;
+}
+/**
+ * Vault upload configuration from API.
+ */
+interface VaultUploadConfig {
+    /** Vault ID */
+    vaultId: string;
+    /** Vault name */
+    vaultName: string;
+    /** Maximum upload size in bytes */
+    maxSizeBytes: number;
+    /** Branding information */
+    branding: UploadBranding;
+    /** Encryption details */
+    encryption: EncryptionInfo;
+    /** Forge status */
+    forgeStatus: 'active' | 'inactive';
+}
+/**
+ * Options for upload().
+ * - Without `target`: Opens a dialog (modal)
+ * - With `target`: Renders inline into the specified element
+ */
+interface UploadOptions {
+    /** Vault ID to upload to */
+    vaultId: string;
+    /**
+     * Target element for inline rendering. Can be:
+     * - A CSS selector string (e.g., "#upload-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;
+    /** Callback when upload completes successfully (if omitted, uses server-configured redirect) */
+    onSuccess?: (result: UploadResult) => void;
+    /** Callback when an error occurs (if omitted, uses server-configured redirect) */
+    onError?: (error: Error) => void;
+    /** Callback when user cancels (if omitted, uses server-configured redirect) */
+    onCancel?: () => void;
+    /** Callback for upload progress */
+    onProgress?: (progress: UploadProgress) => void;
+}
+/** Options for attach() - binds upload to element clicks */
+interface UploadAttachOptions {
+    /** Vault ID to upload to */
+    vaultId: string;
+    /** Callback when upload completes successfully */
+    onSuccess?: (result: UploadResult) => void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+    /** Callback when user cancels */
+    onCancel?: () => void;
+    /** Callback for upload progress */
+    onProgress?: (progress: UploadProgress) => void;
+}
+/** @deprecated Use UploadOptions instead */
+type UploadPopOptions = UploadOptions;
+/** @deprecated Use UploadOptions instead */
+type UploadRenderOptions = UploadOptions;
+/**
+ * Upload progress information.
+ */
+interface UploadProgress {
+    /** Bytes uploaded */
+    bytesUploaded: number;
+    /** Total bytes */
+    bytesTotal: number;
+    /** Percentage (0-100) */
+    percentage: number;
+    /** Current phase */
+    phase: 'uploading' | 'ceremony' | 'complete';
+}
+/**
+ * Successful upload result.
+ */
+interface UploadResult {
+    /** Ingot ID */
+    ingotId: string;
+    /** Vault ID */
+    vaultId: string;
+    /** Original filename */
+    filename: string;
+    /** File size in bytes */
+    sizeBytes: number;
+    /** Upload timestamp (ISO 8601) */
+    uploadTime: string;
+}
+
+/**
+ * SparkVault SDK Error Types
+ */
+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>);
+}
+declare class AuthenticationError extends SparkVaultError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class AuthorizationError extends SparkVaultError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class ValidationError extends SparkVaultError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class NetworkError extends SparkVaultError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class TimeoutError extends SparkVaultError {
+    constructor(message?: string);
+}
+declare class UserCancelledError extends SparkVaultError {
+    constructor(message?: string);
+}
+declare class PopupBlockedError extends SparkVaultError {
+    constructor();
+}
+
 /**
  * Vaults Module
  *
@@ -367,9 +491,32 @@ interface UploadIngotOptions {
  * Uses Triple Zero-Trust encryption (SVMK + AMK + VMK).
  */
 
+/**
+ * Callable upload interface with methods.
+ * Allows both `sv.vaults.upload(options)` and `sv.vaults.upload.attach(selector, options)`.
+ */
+interface UploadCallable {
+    (options: UploadOptions): Promise<UploadResult>;
+    attach(selector: string, options: UploadAttachOptions): () => void;
+    close(): void;
+}
 declare class VaultsModule {
     private readonly http;
-    constructor(_config: ResolvedConfig, http: HttpClient);
+    private readonly uploadModule;
+    /**
+     * Upload to a vault with public upload enabled.
+     *
+     * @example Dialog mode
+     * const result = await sv.vaults.upload({ vaultId: 'vlt_abc123' });
+     *
+     * @example Attach to clicks
+     * sv.vaults.upload.attach('.upload-btn', { vaultId: 'vlt_abc123' });
+     *
+     * @example Inline mode
+     * sv.vaults.upload({ vaultId: 'vlt_abc123', target: '#upload-area' });
+     */
+    readonly upload: UploadCallable;
+    constructor(config: ResolvedConfig, http: HttpClient);
     /**
      * Create a new encrypted vault.
      * IMPORTANT: Store the VMK securely - it cannot be recovered!
@@ -441,80 +588,6 @@ declare class VaultsModule {
     private validateUploadOptions;
 }
 
-/**
- * RNG Module Types
- */
-type RNGFormat = 'hex' | 'base64' | 'base64url' | 'alphanumeric' | 'alphanumeric-mixed' | 'password' | 'numeric' | 'uuid' | 'bytes';
-interface GenerateOptions {
-    /** Number of bytes to generate (1-1024) */
-    bytes: number;
-    /** Output format (default: 'base64url') */
-    format?: RNGFormat;
-}
-interface RandomResult {
-    /** Generated random value */
-    value: string | number[];
-    /** Number of bytes generated */
-    bytes: number;
-    /** Format used */
-    format: RNGFormat;
-    /** Reference ID for billing/audit */
-    referenceId: string;
-}
-
-/**
- * RNG Module
- *
- * Generate cryptographically secure random numbers.
- * Uses hybrid entropy from AWS KMS HSM + local CSPRNG.
- */
-
-declare class RNGModule {
-    private readonly http;
-    constructor(http: HttpClient);
-    /**
-     * Generate cryptographically secure random bytes.
-     *
-     * @example
-     * const result = await sv.rng.generate({ bytes: 32, format: 'hex' });
-     * console.log(result.value);
-     */
-    generate(options: GenerateOptions): Promise<RandomResult>;
-    /**
-     * Generate a random UUID v4.
-     *
-     * @example
-     * const uuid = await sv.rng.uuid();
-     * console.log(uuid); // 'f47ac10b-58cc-4372-a567-0e02b2c3d479'
-     */
-    uuid(): Promise<string>;
-    /**
-     * Generate a random hex string.
-     *
-     * @example
-     * const hex = await sv.rng.hex(16);
-     * console.log(hex); // '1a2b3c4d5e6f7890...'
-     */
-    hex(bytes: number): Promise<string>;
-    /**
-     * Generate a random alphanumeric string.
-     *
-     * @example
-     * const code = await sv.rng.alphanumeric(8);
-     * console.log(code); // 'A1B2C3D4'
-     */
-    alphanumeric(bytes: number): Promise<string>;
-    /**
-     * Generate a random password with special characters.
-     *
-     * @example
-     * const password = await sv.rng.password(16);
-     * console.log(password); // 'aB3$xY7!mN9@pQ2#'
-     */
-    password(bytes: number): Promise<string>;
-    private validateOptions;
-}
-
 /**
  * SparkVault Debug Logger
  *
@@ -556,80 +629,42 @@ declare const logger: {
     groupEnd: () => void;
 };
 
-/**
- * SparkVault SDK Error Types
- */
-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>);
-}
-declare class AuthenticationError extends SparkVaultError {
-    constructor(message: string, details?: Record<string, unknown>);
-}
-declare class AuthorizationError extends SparkVaultError {
-    constructor(message: string, details?: Record<string, unknown>);
-}
-declare class ValidationError extends SparkVaultError {
-    constructor(message: string, details?: Record<string, unknown>);
-}
-declare class NetworkError extends SparkVaultError {
-    constructor(message: string, details?: Record<string, unknown>);
-}
-declare class TimeoutError extends SparkVaultError {
-    constructor(message?: string);
-}
-declare class UserCancelledError extends SparkVaultError {
-    constructor(message?: string);
-}
-declare class PopupBlockedError extends SparkVaultError {
-    constructor();
-}
-
 /**
  * SparkVault JavaScript SDK
  *
- * A unified SDK for Identity, Sparks, Vaults, and RNG.
+ * A unified SDK for Identity and Vaults.
  *
- * @example Auto-Init (Zero-Config)
+ * @example CDN Usage (Recommended)
  * ```html
  * <script
- *   async
  *   src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"
  *   data-account-id="acc_your_account"
- *   data-attach-selector=".js-sparkvault-auth"
- *   data-success-url="https://example.com/auth/verify-token"
- *   data-debug="true"
  * ></script>
  *
- * <button class="js-sparkvault-auth">Login with SparkVault</button>
- * ```
- *
- * @example Manual Init
- * ```html
- * <script src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"></script>
  * <script>
- *   const sv = SparkVault.init({
- *     accountId: 'acc_your_account'
+ *   // SDK auto-initializes. Use JavaScript API:
+ *   SparkVault.identity.attach('.login-btn', {
+ *     onSuccess: (result) => console.log('Verified:', result.identity)
  *   });
- *
- *   // Open identity verification modal
- *   const result = await sv.identity.pop();
- *   console.log(result.identity, result.identityType);
  * </script>
  * ```
+ *
+ * @example npm/Bundler Usage
+ * ```typescript
+ * import SparkVault from '@sparkvault/sdk';
+ *
+ * const sv = SparkVault.init({ accountId: 'acc_your_account' });
+ *
+ * const result = await sv.identity.verify();
+ * console.log(result.identity, result.identityType);
+ * ```
  */
 
 declare class SparkVault {
     /** Identity verification module */
     readonly identity: IdentityModule;
-    /** Ephemeral encrypted secrets module */
-    readonly sparks: SparksModule;
     /** Persistent encrypted storage module */
     readonly vaults: VaultsModule;
-    /** Cryptographic random number generation module */
-    readonly rng: RNGModule;
     private readonly config;
     private constructor();
     /**
@@ -650,9 +685,9 @@ declare class SparkVault {
 
 declare global {
     interface Window {
-        SparkVault: typeof SparkVault;
+        SparkVault: typeof SparkVault | SparkVault;
     }
 }
 
 export { AuthenticationError, AuthorizationError, NetworkError, PopupBlockedError, SparkVault, SparkVaultError, TimeoutError, UserCancelledError, ValidationError, SparkVault as default, logger, setDebugMode };
-export type { AuthMethod, CreateSparkOptions, CreateVaultOptions, GenerateOptions, Ingot, RNGFormat, RandomResult, Spark, SparkPayload, SparkVaultConfig, Theme, TokenClaims, UnsealedVault, UploadIngotOptions, Vault, VaultSummary, VerifyOptions, VerifyResult };
+export type { AuthMethod, CreateVaultOptions, AttachOptions as IdentityAttachOptions, Ingot, SparkVaultConfig, Theme, TokenClaims, UnsealedVault, UploadAttachOptions, UploadBranding, UploadIngotOptions, UploadOptions, UploadPopOptions, UploadProgress, UploadRenderOptions, UploadResult, Vault, VaultSummary, VaultUploadConfig, VerifyOptions, VerifyResult };