@sparkvault/sdk 1.23.9 → 1.24.0

package/dist/sparkvault.cjs.js

@@ -379,6 +379,153 @@ class HttpClient {
     }
 }
 
+/**
+ * SparkVault API Base
+ *
+ * Shared lifecycle and HTTP plumbing for every internal API client in the
+ * SDK. Concrete clients (IdentityApi, UploadApi, ...) extend this and
+ * provide:
+ *   - their own error factory via makeError()
+ *   - their own typed endpoint methods that call rawRequest()
+ *
+ * Session lifecycle invariant: every user-facing session (a modal open, a
+ * verify flow, an upload widget invocation) starts with the owning Module
+ * calling resetSession(). close() aborts the current AbortController; the
+ * next resetSession() swaps in a fresh one. The Module is responsible for
+ * this; clients of the SDK never see any of it.
+ */
+/** Default request timeout in milliseconds (30 seconds). */
+const DEFAULT_TIMEOUT_MS = 30000;
+class SparkVaultApi {
+    constructor(timeoutMs = DEFAULT_TIMEOUT_MS) {
+        /**
+         * Abort controller for the current session. Replaced by resetSession()
+         * at the start of every user-facing session — an aborted controller can
+         * never leak into the next session.
+         */
+        this.closeController = new AbortController();
+        this.timeoutMs = timeoutMs;
+    }
+    /** Abort all pending requests on this client. Called by the Module on close. */
+    abort() {
+        this.closeController.abort();
+    }
+    /** Whether the *current* session has been aborted. */
+    isAborted() {
+        return this.closeController.signal.aborted;
+    }
+    /** The current session's abort signal — for callers that need to wire it into XHR/etc. */
+    getAbortSignal() {
+        return this.closeController.signal;
+    }
+    /**
+     * Swap in a fresh AbortController. The Module calls this at the start of
+     * every user-facing session. Long-lived per-client state (e.g. config
+     * caches) is intentionally NOT cleared here.
+     */
+    resetSession() {
+        this.closeController = new AbortController();
+    }
+    /**
+     * Issue an HTTP request with timeout + session abort + standard error
+     * mapping. Subclasses build URLs and unwrap response envelopes on top.
+     *
+     * Returns the parsed JSON body (whatever shape it takes) plus the
+     * status code. Throws subclass-typed errors via makeError() for: aborted
+     * sessions, timeouts, network failures, and non-2xx responses.
+     */
+    async rawRequest(url, options) {
+        // Capture the current controller locally. If resetSession() swaps the
+        // field while this request is in flight (or in its catch block), the
+        // aborted-vs-timeout discrimination below stays accurate.
+        const localCloseController = this.closeController;
+        if (localCloseController.signal.aborted) {
+            throw this.makeError('Request cancelled', 'cancelled', 0);
+        }
+        const timeoutController = new AbortController();
+        const timeoutId = setTimeout(() => timeoutController.abort(), this.timeoutMs);
+        let combinedSignal;
+        let onCloseAbort = null;
+        if ('any' in AbortSignal) {
+            combinedSignal = AbortSignal.any([
+                timeoutController.signal,
+                localCloseController.signal,
+            ]);
+        }
+        else {
+            // Fallback for browsers without AbortSignal.any: link the close
+            // signal into the timeout controller manually. Listener is removed
+            // in the finally block so it doesn't leak across requests.
+            combinedSignal = timeoutController.signal;
+            onCloseAbort = () => timeoutController.abort();
+            localCloseController.signal.addEventListener('abort', onCloseAbort);
+        }
+        try {
+            // Only send Content-Type when there's actually a body — otherwise GETs
+            // with no payload would carry a misleading content-type header.
+            const headers = { 'Accept': 'application/json' };
+            if (options.body !== undefined)
+                headers['Content-Type'] = 'application/json';
+            if (options.headers)
+                Object.assign(headers, options.headers);
+            const response = await fetch(url, {
+                method: options.method,
+                headers,
+                body: options.body,
+                signal: combinedSignal,
+            });
+            const json = await response.json().catch(() => null);
+            if (!response.ok) {
+                const { message, code } = extractApiError(json);
+                throw this.makeError(message, code, response.status);
+            }
+            return { data: json, status: response.status };
+        }
+        catch (error) {
+            // Re-throw SparkVault errors as-is — they already carry the right code/status.
+            if (error instanceof SparkVaultError)
+                throw error;
+            // Distinguish session-close (cancelled) from timeout. Use the LOCAL
+            // controller captured at request start, not `this.closeController`.
+            if (error != null && typeof error === 'object' && 'name' in error && error.name === 'AbortError') {
+                if (localCloseController.signal.aborted) {
+                    throw this.makeError('Request cancelled', 'cancelled', 0);
+                }
+                throw this.makeError(`Request timed out after ${this.timeoutMs}ms`, 'timeout', 0);
+            }
+            // Browser-level network failure: TypeError("Failed to fetch")
+            // (Chrome/Firefox) or TypeError("Load failed") (WebKit).
+            if (error instanceof TypeError) {
+                throw this.makeError('Unable to connect. Please check your connection and try again.', 'network_error', 0);
+            }
+            throw this.makeError(error instanceof Error ? error.message : 'An unexpected error occurred', 'unknown_error', 0);
+        }
+        finally {
+            clearTimeout(timeoutId);
+            if (onCloseAbort) {
+                localCloseController.signal.removeEventListener('abort', onCloseAbort);
+            }
+        }
+    }
+}
+/**
+ * Extract { message, code } from an API error body. The API wraps errors as
+ * `{ error: { code, message, details }, meta: {...} }`, but legacy/edge
+ * paths may flatten or use `{ error: 'string' }` instead.
+ */
+function extractApiError(json) {
+    const root = (typeof json === 'object' && json !== null) ? json : {};
+    const errorObj = typeof root.error === 'object' && root.error !== null
+        ? root.error
+        : root;
+    const message = (typeof errorObj.message === 'string' ? errorObj.message : null) ??
+        (typeof errorObj.error === 'string' ? errorObj.error : null) ??
+        (typeof root.message === 'string' ? root.message : null) ??
+        'Request failed';
+    const code = typeof errorObj.code === 'string' ? errorObj.code : 'api_error';
+    return { message, code };
+}
+
 /**
  * CooldownTimer - Reusable countdown utility for resend buttons and rate limiting
  *
@@ -637,122 +784,30 @@ function generateState() {
  * Handles all HTTP communication with the Identity App endpoints.
  * Single responsibility: API calls only.
  */
-/** Default request timeout in milliseconds (30 seconds) */
-const DEFAULT_TIMEOUT_MS$1 = 30000;
-class IdentityApi {
-    constructor(config, timeoutMs = DEFAULT_TIMEOUT_MS$1) {
+class IdentityApi extends SparkVaultApi {
+    constructor(config, timeoutMs) {
+        super(timeoutMs);
         /** Cached config promise - allows preloading and deduplication */
         this.configCache = null;
-        /**
-         * Abort controller for cancelling all pending requests on close.
-         * Replaced by resetSession() at the start of every user-facing session.
-         */
-        this.closeController = new AbortController();
         this.config = config;
-        this.timeoutMs = timeoutMs;
-    }
-    /**
-     * Abort all pending requests.
-     * Call this when the renderer is closed to prevent orphaned requests.
-     */
-    abort() {
-        this.closeController.abort();
-    }
-    /**
-     * Check if the API has been aborted.
-     */
-    isAborted() {
-        return this.closeController.signal.aborted;
-    }
-    /**
-     * Reset the session lifecycle by swapping in a fresh AbortController.
-     * The Module calls this at the start of every user-facing session so a
-     * previously-closed session can never leak its aborted state into the
-     * next one. The config cache is intentionally preserved across sessions
-     * so preloadConfig() keeps making modal opens instant.
-     */
-    resetSession() {
-        this.closeController = new AbortController();
     }
     get baseUrl() {
         return `${this.config.identityBaseUrl}/${this.config.accountId}`;
     }
+    makeError(message, code, statusCode) {
+        return new IdentityApiError(message, code, statusCode);
+    }
     async request(method, endpoint, body) {
-        // Don't start new requests if already aborted (renderer closed)
-        if (this.closeController.signal.aborted) {
-            throw new IdentityApiError('Request cancelled', 'cancelled', 0);
-        }
-        const url = `${this.baseUrl}${endpoint}`;
-        const headers = {
-            'Accept': 'application/json',
-        };
-        if (body) {
-            headers['Content-Type'] = 'application/json';
-        }
-        // Create abort controller for request timeout
-        const timeoutController = new AbortController();
-        const timeoutId = setTimeout(() => timeoutController.abort(), this.timeoutMs);
-        // Combine timeout and close signals - abort on either
-        // Use AbortSignal.any if available, otherwise fall back to manual linking
-        let combinedSignal;
-        if ('any' in AbortSignal) {
-            combinedSignal = AbortSignal.any([
-                timeoutController.signal,
-                this.closeController.signal,
-            ]);
-        }
-        else {
-            // Fallback for older browsers: link close signal to timeout controller
-            combinedSignal = timeoutController.signal;
-            const onClose = () => timeoutController.abort();
-            this.closeController.signal.addEventListener('abort', onClose);
-        }
-        try {
-            const response = await fetch(url, {
-                method,
-                headers,
-                body: body ? JSON.stringify(body) : undefined,
-                signal: combinedSignal,
-            });
-            const json = await response.json();
-            if (!response.ok) {
-                // API error responses have format: { error: { code, message, details }, meta: {...} }
-                const errorData = json.error || {};
-                const message = errorData.message || json.message || 'Request failed';
-                const code = errorData.code || json.code || 'api_error';
-                throw new IdentityApiError(message, code, response.status);
-            }
-            // API responses are wrapped in { data: ..., meta: ... }
-            // Unwrap the data field
-            return (json.data ?? json);
-        }
-        catch (error) {
-            // Convert AbortError to a more descriptive error.
-            // Check error.name directly (DOMException may not extend Error in all environments).
-            if (error != null && typeof error === 'object' && 'name' in error && error.name === 'AbortError') {
-                // Check which signal triggered the abort
-                if (this.closeController.signal.aborted) {
-                    throw new IdentityApiError('Request cancelled', 'cancelled', 0);
-                }
-                throw new IdentityApiError('Request timed out', 'timeout', 0);
-            }
-            // Convert TypeError to a user-friendly network error.
-            // WebKit (Safari/iOS) throws TypeError("Load failed"),
-            // Chrome/Firefox throw TypeError("Failed to fetch")
-            // when fetch() fails at the browser level (network error, CORS, DNS, etc.).
-            if (error instanceof TypeError) {
-                throw new IdentityApiError('Unable to connect. Please check your connection and try again.', 'network_error', 0);
-            }
-            // Re-throw IdentityApiError as-is (already has user-friendly message)
-            if (error instanceof IdentityApiError) {
-                throw error;
-            }
-            // Convert any other unexpected errors to a structured error
-            throw new IdentityApiError(error instanceof Error ? error.message : 'An unexpected error occurred', 'unknown_error', 0);
-        }
-        finally {
-            clearTimeout(timeoutId);
-        }
+        const { data } = await this.rawRequest(`${this.baseUrl}${endpoint}`, {
+            method,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        // API responses are wrapped in `{ data: ..., meta: ... }`. Unwrap the
+        // data field if present; otherwise return the raw payload.
+        const unwrapped = (typeof data === 'object' && data !== null && 'data' in data)
+            ? data.data
+            : data;
+        return unwrapped;
     }
     /**
      * Fetch SDK configuration (branding, enabled methods).
@@ -943,12 +998,10 @@ class IdentityApi {
         });
     }
 }
-class IdentityApiError extends Error {
+class IdentityApiError extends SparkVaultError {
     constructor(message, code, statusCode) {
-        super(message);
+        super(message, code, statusCode);
         this.name = 'IdentityApiError';
-        this.code = code;
-        this.statusCode = statusCode;
         Object.setPrototypeOf(this, IdentityApiError.prototype);
     }
 }
@@ -6523,23 +6576,18 @@ class IdentityModule {
  *
  * API client for vault upload operations.
  */
-/** Default request timeout in milliseconds (30 seconds) */
-const DEFAULT_TIMEOUT_MS = 30000;
 /**
- * Error class for upload API errors.
+ * Error class for upload API errors. Inherits `code` and `statusCode` from
+ * SparkVaultError — no duplicate `httpStatus` field.
  */
 class UploadApiError extends SparkVaultError {
-    constructor(message, code, httpStatus) {
-        super(message, code, httpStatus);
-        this.httpStatus = httpStatus;
+    constructor(message, code, statusCode) {
+        super(message, code, statusCode);
         this.name = 'UploadApiError';
         Object.setPrototypeOf(this, UploadApiError.prototype);
     }
 }
-/**
- * Runtime validation for VaultUploadInfoResponse.
- * Validates required fields exist and have correct types.
- */
+/** Runtime validation for VaultUploadInfoResponse. */
 function isVaultUploadInfoResponse(data) {
     if (typeof data !== 'object' || data === null)
         return false;
@@ -6555,52 +6603,30 @@ function isVaultUploadInfoResponse(data) {
         typeof d.encryption.algorithm === 'string' &&
         (d.forge_status === 'active' || d.forge_status === 'inactive'));
 }
-/**
- * Runtime validation for InitiateUploadResponse.
- */
+/** Runtime validation for InitiateUploadResponse. */
 function isInitiateUploadResponse(data) {
     if (typeof data !== 'object' || data === null)
         return false;
     const d = data;
     return typeof d.forge_url === 'string' && typeof d.ingot_id === 'string';
 }
-class UploadApi {
+class UploadApi extends SparkVaultApi {
     constructor(config) {
-        /**
-         * Abort controller for cancelling all pending requests on close.
-         * Replaced by resetSession() at the start of every user-facing session.
-         */
-        this.closeController = new AbortController();
+        super(config.timeout);
         this.config = config;
-        this.timeoutMs = config.timeout ?? DEFAULT_TIMEOUT_MS;
-    }
-    /**
-     * Abort all pending requests.
-     * Call this when the renderer is closed to prevent orphaned requests.
-     */
-    abort() {
-        this.closeController.abort();
-    }
-    /**
-     * Check if the API has been aborted.
-     */
-    isAborted() {
-        return this.closeController.signal.aborted;
     }
-    /**
-     * Get the abort signal for external use (e.g., XHR uploads).
-     */
-    getAbortSignal() {
-        return this.closeController.signal;
+    makeError(message, code, statusCode) {
+        return new UploadApiError(message, code, statusCode);
     }
     /**
-     * Reset the session lifecycle by swapping in a fresh AbortController.
-     * The Module calls this at the start of every user-facing session so a
-     * previously-closed session can never leak its aborted state into the
-     * next one. (Long-lived caches on `this` are intentionally preserved.)
+     * Issue a request and unwrap the standard `{ data, meta }` envelope.
      */
-    resetSession() {
-        this.closeController = new AbortController();
+    async request(url, options) {
+        const { data: raw, status } = await this.rawRequest(url, options);
+        const data = (typeof raw === 'object' && raw !== null && 'data' in raw)
+            ? raw.data
+            : raw;
+        return { data, status };
     }
     /**
      * Get vault upload info (public endpoint).
@@ -6650,85 +6676,6 @@ class UploadApi {
             ingotId: response.data.ingot_id,
         };
     }
-    /**
-     * Internal request method with timeout handling and error context.
-     */
-    async request(url, options) {
-        // Don't start new requests if already aborted (renderer closed)
-        if (this.closeController.signal.aborted) {
-            throw new UploadApiError('Request cancelled', 'cancelled', 0);
-        }
-        const timeoutController = new AbortController();
-        const timeoutId = setTimeout(() => timeoutController.abort(), this.timeoutMs);
-        // Combine timeout and close signals - abort on either
-        let combinedSignal;
-        if ('any' in AbortSignal) {
-            combinedSignal = AbortSignal.any([
-                timeoutController.signal,
-                this.closeController.signal,
-            ]);
-        }
-        else {
-            // Fallback for older browsers: link close signal to timeout controller
-            combinedSignal = timeoutController.signal;
-            const onClose = () => timeoutController.abort();
-            this.closeController.signal.addEventListener('abort', onClose);
-        }
-        try {
-            const response = await fetch(url, {
-                method: options.method,
-                headers: {
-                    'Content-Type': 'application/json',
-                    'Accept': 'application/json',
-                },
-                body: options.body,
-                signal: combinedSignal,
-            });
-            const json = await response.json();
-            if (!response.ok) {
-                // Safely extract error fields with runtime type checking
-                const errorData = typeof json === 'object' && json !== null ? json : {};
-                const errorObj = typeof errorData.error === 'object' && errorData.error !== null
-                    ? errorData.error
-                    : errorData;
-                const message = (typeof errorObj.message === 'string' ? errorObj.message : null) ??
-                    (typeof errorObj.error === 'string' ? errorObj.error : null) ??
-                    'Request failed';
-                const code = typeof errorObj.code === 'string' ? errorObj.code : 'api_error';
-                throw new UploadApiError(message, code, response.status);
-            }
-            // API responses are wrapped in { data: ..., meta: ... }
-            const data = typeof json === 'object' && json !== null && 'data' in json
-                ? json.data
-                : json;
-            return { data, status: response.status };
-        }
-        catch (error) {
-            // Re-throw SparkVault errors as-is
-            if (error instanceof SparkVaultError) {
-                throw error;
-            }
-            // Convert AbortError to appropriate error
-            if (error instanceof DOMException && error.name === 'AbortError') {
-                // Check which signal triggered the abort
-                if (this.closeController.signal.aborted) {
-                    throw new UploadApiError('Request cancelled', 'cancelled', 0);
-                }
-                throw new TimeoutError(`Request timed out after ${this.timeoutMs}ms`);
-            }
-            // Network errors with context
-            if (error instanceof TypeError) {
-                throw new NetworkError(`Network request failed: ${error.message}`, { url, method: options.method });
-            }
-            // Unknown errors - preserve message
-            throw new NetworkError(error instanceof Error
-                ? `Request failed: ${error.message}`
-                : 'Request failed: Unknown error');
-        }
-        finally {
-            clearTimeout(timeoutId);
-        }
-    }
 }
 
 /**
@@ -9321,25 +9268,25 @@ class UploadRenderer {
                     title: 'Upload Widget Not Enabled',
                     message: 'This vault has not enabled the embedded upload widget. Enable it on the vault\'s settings page in the SparkVault dashboard to start accepting uploads here.',
                     code: 'UPLOAD_SOURCE_DISABLED',
-                    httpStatus: error.httpStatus,
+                    statusCode: error.statusCode,
                 });
             }
-            else if (error.httpStatus === 404) {
+            else if (error.statusCode === 404) {
                 this.setState({
                     view: 'error',
                     title: 'Upload Page Not Found',
                     message: 'The requested upload endpoint could not be located. This may occur if the upload link has expired or was entered incorrectly.',
                     code: 'NOT_FOUND',
-                    httpStatus: 404,
+                    statusCode: 404,
                 });
             }
-            else if (error.httpStatus === 402) {
+            else if (error.statusCode === 402) {
                 this.setState({
                     view: 'error',
                     title: 'Service Unavailable',
                     message: 'This upload endpoint has been temporarily disabled due to an account billing issue. Please contact the organization\'s administrator.',
                     code: 'PAYMENT_REQUIRED',
-                    httpStatus: 402,
+                    statusCode: 402,
                 });
             }
             else {
@@ -9348,7 +9295,7 @@ class UploadRenderer {
                     title: 'Upload Failed',
                     message: error.message,
                     code: error.code,
-                    httpStatus: error.httpStatus,
+                    statusCode: error.statusCode,
                 });
             }
             this.callbacks.onError(error);