@sparkvault/sdk 1.24.1 → 1.24.3

package/dist/sparkvault.cjs.js

@@ -68,16 +68,32 @@ class PopupBlockedError extends SparkVaultError {
 /**
  * SparkVault SDK Configuration
  */
+const DEFAULT_ALLOWED_DOWNLOAD_HOST_PATTERNS = [
+    /\.sparkvault\.(com|io)$/i,
+    /\.amazonaws\.com$/i,
+    /\.cloudfront\.net$/i,
+];
 const API_URL = 'https://api.sparkvault.com';
 const IDENTITY_URL = 'https://api.sparkvault.com/v1/apps/identity';
+function normalizeApiBaseUrl(url) {
+    const trimmed = url.replace(/\/+$/, '');
+    return trimmed.endsWith('/v1') ? trimmed.slice(0, -3) : trimmed;
+}
+function normalizeBaseUrl(url) {
+    return url.replace(/\/+$/, '');
+}
 function resolveConfig(config) {
     return {
         accountId: config.accountId,
         timeout: config.timeout ?? 30000,
-        apiBaseUrl: API_URL,
-        identityBaseUrl: IDENTITY_URL,
+        apiBaseUrl: normalizeApiBaseUrl(config.apiBaseUrl ?? API_URL),
+        identityBaseUrl: normalizeBaseUrl(config.identityBaseUrl ?? IDENTITY_URL),
+        accessToken: config.accessToken,
+        getAccessToken: config.getAccessToken,
+        apiKey: config.apiKey,
         preloadConfig: config.preloadConfig !== false, // Default: true
         backdropBlur: config.backdropBlur !== false, // Default: true
+        allowedDownloadHostPatterns: config.allowedDownloadHostPatterns ?? DEFAULT_ALLOWED_DOWNLOAD_HOST_PATTERNS,
     };
 }
 function validateConfig(config) {
@@ -194,6 +210,31 @@ class HttpClient {
     constructor(config) {
         this.config = config;
     }
+    async getDefaultHeaders(headers, hasJsonBody) {
+        const requestHeaders = {
+            Accept: 'application/json',
+            ...headers,
+        };
+        if (hasJsonBody) {
+            requestHeaders['Content-Type'] = 'application/json';
+        }
+        if (!requestHeaders.Authorization) {
+            const token = await this.getAccessToken();
+            if (token) {
+                requestHeaders.Authorization = `Bearer ${token}`;
+            }
+        }
+        if (this.config.apiKey && !requestHeaders['X-API-Key']) {
+            requestHeaders['X-API-Key'] = this.config.apiKey;
+        }
+        return requestHeaders;
+    }
+    async getAccessToken() {
+        if (this.config.getAccessToken) {
+            return this.config.getAccessToken();
+        }
+        return this.config.accessToken ?? null;
+    }
     async request(path, options = {}) {
         const { retry } = options;
         // Per CLAUDE.md §7: Wrap with retry logic if enabled
@@ -213,11 +254,7 @@ class HttpClient {
     async executeRequest(path, options) {
         const { method = 'GET', headers = {}, body, timeout = this.config.timeout, } = options;
         const url = `${this.config.apiBaseUrl}${path}`;
-        const requestHeaders = {
-            'Content-Type': 'application/json',
-            Accept: 'application/json',
-            ...headers,
-        };
+        const requestHeaders = await this.getDefaultHeaders(headers, body !== undefined);
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), timeout);
         try {
@@ -228,12 +265,12 @@ class HttpClient {
                 signal: controller.signal,
             });
             clearTimeout(timeoutId);
-            const data = await this.parseResponse(response);
+            const parsed = await this.parseResponse(response);
             if (!response.ok) {
-                throw this.createErrorFromResponse(response.status, data);
+                throw this.createErrorFromResponse(response.status, parsed);
             }
             return {
-                data,
+                data: this.unwrapApiResponse(parsed),
                 status: response.status,
                 headers: response.headers,
             };
@@ -287,13 +324,23 @@ class HttpClient {
         // Safely extract error fields with runtime type checking
         const errorData = typeof data === 'object' && data !== null ? data : {};
         const record = errorData;
-        const message = (typeof record.message === 'string' ? record.message : null) ??
+        const nestedError = typeof record.error === 'object' && record.error !== null
+            ? record.error
+            : null;
+        const message = (typeof nestedError?.message === 'string' ? nestedError.message : null) ??
+            (typeof record.message === 'string' ? record.message : null) ??
             (typeof record.error === 'string' ? record.error : null) ??
             'Request failed';
-        const code = typeof record.code === 'string' ? record.code : 'api_error';
-        const details = typeof record.details === 'object' && record.details !== null
+        const code = (typeof nestedError?.code === 'string' ? nestedError.code : null) ??
+            (typeof record.code === 'string' ? record.code : null) ??
+            'api_error';
+        const nestedDetails = typeof nestedError?.details === 'object' && nestedError.details !== null
+            ? nestedError.details
+            : undefined;
+        const topLevelDetails = typeof record.details === 'object' && record.details !== null
             ? record.details
             : undefined;
+        const details = nestedDetails ?? topLevelDetails;
         switch (status) {
             case 400:
                 return new ValidationError(message, details);
@@ -305,6 +352,15 @@ class HttpClient {
                 return new SparkVaultError(message, code, status, details);
         }
     }
+    unwrapApiResponse(data) {
+        if (typeof data === 'object' && data !== null) {
+            const record = data;
+            if ('data' in record && ('meta' in record || 'error' in record)) {
+                return record.data;
+            }
+        }
+        return data;
+    }
     get(path, options) {
         return this.request(path, { ...options, method: 'GET' });
     }
@@ -342,10 +398,7 @@ class HttpClient {
     async executeRequestRaw(path, options) {
         const { method = 'GET', headers = {}, body, timeout = this.config.timeout, } = options;
         const url = `${this.config.apiBaseUrl}${path}`;
-        const requestHeaders = {
-            'Content-Type': 'application/json',
-            ...headers,
-        };
+        const requestHeaders = await this.getDefaultHeaders(headers, body !== undefined);
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), timeout);
         try {
@@ -379,6 +432,63 @@ class HttpClient {
     }
 }
 
+class HealthModule {
+    constructor(config) {
+        this.config = config;
+    }
+    async check(options = {}) {
+        const checkedAt = Math.floor(Date.now() / 1000);
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), options.timeout ?? this.config.timeout);
+        try {
+            const response = await fetch(`${this.config.apiBaseUrl}/health`, {
+                method: 'GET',
+                headers: { Accept: 'application/json' },
+                signal: controller.signal,
+            });
+            return {
+                online: response.ok,
+                status: response.ok ? await this.readStatus(response) : 'unhealthy',
+                httpStatus: response.status,
+                checkedAt,
+            };
+        }
+        catch (err) {
+            return {
+                online: false,
+                status: 'unreachable',
+                checkedAt,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    async isOnline(options = {}) {
+        const result = await this.check(options);
+        return result.online;
+    }
+    async readStatus(response) {
+        try {
+            const body = await response.json();
+            const data = typeof body === 'object' && body !== null && 'data' in body
+                ? body.data
+                : body;
+            if (typeof data === 'object' && data !== null) {
+                const status = data.status;
+                if (typeof status === 'string' && status) {
+                    return status;
+                }
+            }
+        }
+        catch {
+            return response.ok ? 'healthy' : 'unhealthy';
+        }
+        return response.ok ? 'healthy' : 'unhealthy';
+    }
+}
+
 /**
  * SparkVault API Base
  *
@@ -9553,6 +9663,7 @@ class VaultUploadModule {
  */
 class VaultsModule {
     constructor(config, http) {
+        this.config = config;
         this.http = http;
         this.uploadModule = new VaultUploadModule(config);
         // Create callable that also has attach/close methods
@@ -9600,13 +9711,15 @@ class VaultsModule {
         }
         const cleanId = vaultId.startsWith('vlt_') ? vaultId : `vlt_${vaultId}`;
         const response = await this.http.post(`/v1/vaults/${cleanId}/unseal`, { vmk });
+        if (!response.data.vat) {
+            throw new ValidationError('Unseal response did not include a vault access token');
+        }
         return {
             id: response.data.vault_id,
-            name: response.data.name,
-            vatToken: response.data.vat_token,
+            vatToken: response.data.vat,
+            issuedAt: response.data.issued_at,
             expiresAt: response.data.expires_at,
-            ingotCount: response.data.ingot_count,
-            storageBytes: response.data.storage_bytes,
+            ttlSeconds: response.data.ttl_seconds,
         };
     }
     /**
@@ -9651,22 +9764,26 @@ class VaultsModule {
      */
     async uploadIngot(vault, options) {
         this.validateUploadOptions(options);
-        const name = options.name ?? (options.file instanceof File ? options.file.name : 'unnamed');
-        const contentType = options.contentType ?? options.file.type ?? 'application/octet-stream';
+        const requestedName = options.name ?? getBlobName(options.file);
+        const requestedContentType = options.contentType ?? options.file.type ?? 'application/octet-stream';
         const createResponse = await this.http.post(`/v1/vaults/${vault.id}/ingots`, {
-            name,
-            content_type: contentType,
+            name: requestedName,
+            content_type: requestedContentType,
             size_bytes: options.file.size,
         }, {
-            headers: { Authorization: `Bearer ${vault.vatToken}` },
+            headers: { 'X-Vault-Access-Token': vault.vatToken },
         });
+        const created = createResponse.data;
+        if (!created.forge_url) {
+            throw new ValidationError('Upload endpoint did not return a Forge upload URL');
+        }
+        await uploadBlobWithTus(options.file, created.forge_url, created.name, created.content_type, options.onProgress);
         return {
-            id: createResponse.data.ingot_id,
-            name: createResponse.data.name,
-            contentType: createResponse.data.content_type,
-            size: createResponse.data.size_bytes,
-            createdAt: createResponse.data.created_at,
-            type: createResponse.data.ingot_type,
+            id: created.ingot_id,
+            name: created.name,
+            contentType: created.content_type,
+            size: created.size_bytes,
+            uploadExpiresAt: created.expires_at,
         };
     }
     /**
@@ -9678,10 +9795,27 @@ class VaultsModule {
      */
     async downloadIngot(vault, ingotId) {
         const cleanId = ingotId.startsWith('ing_') ? ingotId : `ing_${ingotId}`;
-        return this.http.requestRaw(`/v1/vaults/${vault.id}/ingots/${cleanId}/download`, {
-            method: 'POST',
-            headers: { Authorization: `Bearer ${vault.vatToken}` },
-        });
+        let lastError = null;
+        for (let attempt = 1; attempt <= DOWNLOAD_MAX_ATTEMPTS; attempt++) {
+            try {
+                const response = await this.http.post(`/v1/vaults/${vault.id}/ingots/${cleanId}/download`, undefined, {
+                    headers: { 'X-Vault-Access-Token': vault.vatToken },
+                });
+                if (!response.data.download_url) {
+                    throw new ValidationError('Download endpoint did not return a download URL');
+                }
+                this.validateDownloadUrl(response.data.download_url);
+                return await fetchBlobWithTimeout(response.data.download_url);
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                if (!isRetryableDownloadError(lastError) || attempt === DOWNLOAD_MAX_ATTEMPTS) {
+                    throw lastError;
+                }
+                await delayExponential(attempt);
+            }
+        }
+        throw lastError ?? new Error('Download failed');
     }
     /**
      * List all ingots in an unsealed vault.
@@ -9692,7 +9826,7 @@ class VaultsModule {
      */
     async listIngots(vault) {
         const response = await this.http.get(`/v1/vaults/${vault.id}/ingots`, {
-            headers: { Authorization: `Bearer ${vault.vatToken}` },
+            headers: { 'X-Vault-Access-Token': vault.vatToken },
         });
         return response.data.ingots.map((i) => ({
             id: i.ingot_id,
@@ -9700,7 +9834,6 @@ class VaultsModule {
             contentType: i.content_type,
             size: i.size_bytes,
             createdAt: i.created_at,
-            type: i.ingot_type,
         }));
     }
     /**
@@ -9712,7 +9845,7 @@ class VaultsModule {
     async deleteIngot(vault, ingotId) {
         const cleanId = ingotId.startsWith('ing_') ? ingotId : `ing_${ingotId}`;
         await this.http.delete(`/v1/vaults/${vault.id}/ingots/${cleanId}`, {
-            headers: { Authorization: `Bearer ${vault.vatToken}` },
+            headers: { 'X-Vault-Access-Token': vault.vatToken },
         });
     }
     validateCreateOptions(options) {
@@ -9731,6 +9864,133 @@ class VaultsModule {
             throw new ValidationError('File cannot be empty');
         }
     }
+    validateDownloadUrl(downloadUrl) {
+        let parsed;
+        try {
+            parsed = new URL(downloadUrl);
+        }
+        catch {
+            throw new ValidationError('Invalid download URL from server');
+        }
+        if (parsed.protocol !== 'https:') {
+            throw new ValidationError('Download URL must use HTTPS');
+        }
+        const allowedHosts = this.config.allowedDownloadHostPatterns;
+        if (!allowedHosts.some(pattern => pattern.test(parsed.hostname))) {
+            throw new ValidationError('Invalid download URL from server');
+        }
+    }
+}
+function getBlobName(file) {
+    if (typeof File !== 'undefined' && file instanceof File && file.name) {
+        return file.name;
+    }
+    return 'unnamed';
+}
+function base64Encode(value) {
+    return btoa(unescape(encodeURIComponent(value)));
+}
+async function uploadBlobWithTus(file, forgeUrl, filename, contentType, onProgress) {
+    if (typeof XMLHttpRequest === 'undefined') {
+        throw new ValidationError('XMLHttpRequest is required for browser ingot uploads');
+    }
+    const tusVersion = '1.0.0';
+    const defaultChunkSize = 50 * 1024 * 1024;
+    const url = new URL(forgeUrl);
+    const istk = url.searchParams.get('istk');
+    const endpoint = `${url.origin}${url.pathname}`;
+    if (!istk) {
+        throw new ValidationError('Forge upload URL is missing ISTK');
+    }
+    const createResponse = await fetch(endpoint, {
+        method: 'POST',
+        headers: {
+            'Tus-Resumable': tusVersion,
+            'Upload-Length': String(file.size),
+            'Upload-Metadata': `filename ${base64Encode(filename)},filetype ${base64Encode(contentType)}`,
+            'X-ISTK': istk,
+        },
+    });
+    if (!createResponse.ok) {
+        const errorText = await createResponse.text();
+        throw new Error(`Failed to create upload session: ${createResponse.status} ${errorText}`);
+    }
+    const location = createResponse.headers.get('Location');
+    const chunkSizeHeader = createResponse.headers.get('X-Chunk-Size');
+    const chunkSize = chunkSizeHeader ? parseInt(chunkSizeHeader, 10) : defaultChunkSize;
+    if (!location) {
+        throw new Error('Server did not return upload location');
+    }
+    const uploadUrl = location.startsWith('http') ? location : `${url.origin}${location}`;
+    let offset = 0;
+    while (offset < file.size) {
+        const chunkStart = offset;
+        const chunkEnd = Math.min(offset + chunkSize, file.size);
+        const chunk = file.slice(chunkStart, chunkEnd);
+        offset = await uploadChunkWithProgress(uploadUrl, chunk, chunkStart, file.size, tusVersion, istk, onProgress);
+    }
+}
+function uploadChunkWithProgress(uploadUrl, chunk, chunkStart, totalSize, tusVersion, istk, onProgress) {
+    return new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        xhr.upload.onprogress = (event) => {
+            if (event.lengthComputable) {
+                onProgress?.(chunkStart + event.loaded, totalSize);
+            }
+        };
+        xhr.onload = () => {
+            if (xhr.status >= 200 && xhr.status < 300) {
+                const newOffsetHeader = xhr.getResponseHeader('Upload-Offset');
+                const newOffset = newOffsetHeader ? parseInt(newOffsetHeader, 10) : chunkStart + chunk.size;
+                resolve(newOffset);
+            }
+            else {
+                reject(new Error(`Chunk upload failed with status ${xhr.status}`));
+            }
+        };
+        xhr.onerror = () => reject(new Error('Chunk upload failed'));
+        xhr.ontimeout = () => reject(new Error('Chunk upload timed out'));
+        xhr.onabort = () => reject(new Error('Upload cancelled'));
+        xhr.open('PATCH', uploadUrl);
+        xhr.setRequestHeader('Tus-Resumable', tusVersion);
+        xhr.setRequestHeader('Upload-Offset', String(chunkStart));
+        xhr.setRequestHeader('Content-Type', 'application/offset+octet-stream');
+        xhr.setRequestHeader('X-ISTK', istk);
+        xhr.send(chunk);
+    });
+}
+const DOWNLOAD_MAX_ATTEMPTS = 3;
+const DOWNLOAD_RETRY_BASE_MS = 500;
+function delayExponential(attempt) {
+    return new Promise(resolve => setTimeout(resolve, DOWNLOAD_RETRY_BASE_MS * 2 ** (attempt - 1)));
+}
+function isRetryableDownloadError(err) {
+    // Server contract / client-side validation errors aren't fixed by retrying.
+    if (err instanceof ValidationError)
+        return false;
+    // Network errors carry a status code only when the SDK HTTP client attached
+    // one; treat any explicitly-4xx response as a permanent failure.
+    const status = err.statusCode;
+    if (typeof status === 'number' && status >= 400 && status < 500 && status !== 408 && status !== 429) {
+        return false;
+    }
+    return true;
+}
+async function fetchBlobWithTimeout(url, timeout = 300000) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+        const response = await fetch(url, { signal: controller.signal });
+        if (!response.ok) {
+            const error = new Error(`Download failed with status ${response.status}`);
+            error.statusCode = response.status;
+            throw error;
+        }
+        return response.blob();
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
 }
 
 /**
@@ -9917,6 +10177,7 @@ class SparkVault {
         const http = new HttpClient(this.config);
         this.identity = new IdentityModule(this.config);
         this.vaults = new VaultsModule(this.config, http);
+        this.health = new HealthModule(this.config);
     }
     /**
      * Initialize the SparkVault SDK.