@sparkvault/sdk-mobile 0.1.3

package/src/index.ts

@@ -0,0 +1,103 @@
+export {
+  SparkVaultMobile,
+  createSparkVaultMobileClient,
+} from './client.js';
+export type {
+  SparkVaultMobileConfig,
+  ResolvedMobileConfig,
+} from './config.js';
+export type {
+  AuthEvent,
+  AuthEventListener,
+} from './http.js';
+export {
+  MobileAuthClient,
+} from './auth.js';
+export {
+  MobileVaultsClient,
+} from './vaults.js';
+export {
+  MobileFoldersClient,
+} from './folders.js';
+export {
+  MobileIngotsClient,
+} from './ingots.js';
+export type {
+  DownloadToFileOptions,
+  DownloadToFileResult,
+  UploadOptions,
+  UploadFromUriOptions,
+  ReplaceFromUriOptions,
+} from './ingots.js';
+export {
+  MobileHealthClient,
+} from './health.js';
+export type {
+  HealthCheckOptions,
+  HealthCheckResult,
+} from './health.js';
+export {
+  MobileSparksClient,
+} from './sparks.js';
+export type {
+  CreateSparkOptions,
+  CreateSparkResponse,
+  ListSparksOptions,
+  ListSparksResponse,
+  Spark,
+  SparkResponse,
+} from './sparks.js';
+export {
+  MobileEntropyClient,
+} from './entropy.js';
+export type {
+  EntropyFormat,
+  EntropyResponse,
+  GenerateEntropyOptions,
+} from './entropy.js';
+export {
+  MobilePushTokensClient,
+} from './push-tokens.js';
+export type {
+  RegisterPushTokenResponse,
+} from './push-tokens.js';
+export {
+  MobileBillingClient,
+} from './billing.js';
+export type {
+  BillingBalance,
+} from './billing.js';
+export {
+  MobileTusUploader,
+  parseForgeUrl,
+} from './tus.js';
+export type {
+  TusUploadFromUriOptions,
+  ParsedForgeUrl,
+} from './tus.js';
+export {
+  base64EncodeUtf8,
+  base64UrlToBytes,
+  base64UrlToUtf8,
+  bytesToUtf8,
+  base64ToBytes,
+  bytesToBase64,
+  utf8ToBytes,
+} from './encoding.js';
+export {
+  SparkVaultAuthenticationError,
+  SparkVaultAuthorizationError,
+  SparkVaultMobileError,
+  SparkVaultNetworkError,
+  SparkVaultTimeoutError,
+  SparkVaultValidationError,
+  TusUploadError,
+} from './errors.js';
+export {
+  isSafeId,
+  sanitizeFilename,
+  validateFolderId,
+  validateIngotId,
+  validateVaultId,
+} from './validation.js';
+export type * from './types.js';

package/src/ingots.ts

@@ -0,0 +1,593 @@
+import type { ResolvedMobileConfig } from './config.js';
+import { SparkVaultMobileError, SparkVaultValidationError } from './errors.js';
+import type { MobileHttpClient } from './http.js';
+import { MobileTusUploader } from './tus.js';
+import type {
+  DebugLogger,
+  Ingot,
+  IngotAccessLog,
+  IngotAccessStats,
+  IngotInvite,
+  IngotSharingConfig,
+  ListIngotsResponse,
+  MobileFileDownloader,
+  UploadProgressCallback,
+  UploadResult,
+} from './types.js';
+import { validateIngotId, validateVaultId } from './validation.js';
+
+export interface UploadOptions {
+  vaultId: string;
+  vat: string;
+  name: string;
+  contentType: string;
+  onProgress?: UploadProgressCallback;
+  abortSignal?: AbortSignal;
+}
+
+export interface UploadFromUriOptions extends UploadOptions {
+  fileUri: string;
+  fileSize: number;
+  debug?: DebugLogger;
+}
+
+export interface ReplaceFromUriOptions extends UploadFromUriOptions {
+  ingotId: string;
+}
+
+export interface DownloadToFileOptions {
+  vaultId: string;
+  ingotId: string;
+  vat: string;
+  fileUri: string;
+  expectedSizeBytes?: number;
+  timeoutMs?: number;
+  retries?: number;
+  retryBaseDelayMs?: number;
+  deleteExisting?: boolean;
+  abortSignal?: AbortSignal;
+  onProgress?: UploadProgressCallback;
+}
+
+export interface DownloadToFileResult {
+  filePath: string;
+  sizeBytes: number;
+}
+
+interface IngotUploadInitResponse {
+  ingot_id: string;
+  forge_url: string;
+  name?: string;
+  size_bytes?: number;
+}
+
+export class MobileIngotsClient {
+  private static readonly INGOT_STATUS_POLL_MAX = 10;
+  private static readonly INGOT_STATUS_POLL_MS = 1000;
+  private static readonly DOWNLOAD_MAX_ATTEMPTS = 3;
+  private static readonly DOWNLOAD_RETRY_BASE_MS = 1000;
+
+  private readonly config: ResolvedMobileConfig;
+  private readonly http: MobileHttpClient;
+  private readonly tus: MobileTusUploader;
+
+  constructor(config: ResolvedMobileConfig, http: MobileHttpClient) {
+    this.config = config;
+    this.http = http;
+    this.tus = new MobileTusUploader(config);
+  }
+
+  async uploadFromUri(options: UploadFromUriOptions): Promise<UploadResult> {
+    validateVaultId(options.vaultId);
+    if (options.abortSignal?.aborted) {
+      throw new SparkVaultMobileError('Upload cancelled', { code: 'upload_cancelled' });
+    }
+
+    const init = await this.createIngotUpload({
+      vaultId: options.vaultId,
+      vat: options.vat,
+      name: options.name,
+      contentType: options.contentType,
+      sizeBytes: options.fileSize,
+    });
+
+    await this.tus.uploadFromUri({
+      fileUri: options.fileUri,
+      fileSize: options.fileSize,
+      filename: options.name,
+      contentType: options.contentType,
+      forgeUrl: init.forge_url,
+      onProgress: options.onProgress,
+      abortSignal: options.abortSignal,
+      debug: options.debug,
+    });
+
+    await this.verifyIngotActive(options.vaultId, init.ingot_id, options.vat);
+
+    return {
+      ingot_id: init.ingot_id,
+      name: init.name ?? options.name,
+      size_bytes: init.size_bytes ?? options.fileSize,
+      storage_location: 's3',
+    };
+  }
+
+  async replaceFromUri(options: ReplaceFromUriOptions): Promise<UploadResult> {
+    const { vaultId, ingotId, vat, name, contentType, fileUri, fileSize, onProgress, abortSignal, debug } = options;
+    validateVaultId(vaultId);
+    validateIngotId(ingotId);
+
+    if (abortSignal?.aborted) {
+      throw new SparkVaultMobileError('Upload cancelled', { code: 'upload_cancelled' });
+    }
+
+    const response = await this.http.put<IngotUploadInitResponse>(
+      `/vaults/${vaultId}/ingots/${ingotId}`,
+      { name, content_type: contentType, size_bytes: fileSize },
+      { vat }
+    );
+
+    if (!response.data.ingot_id || !response.data.forge_url) {
+      throw new SparkVaultMobileError('Server returned invalid response for ingot replacement');
+    }
+
+    await this.tus.uploadFromUri({
+      fileUri,
+      fileSize,
+      filename: name,
+      contentType,
+      forgeUrl: response.data.forge_url,
+      onProgress,
+      abortSignal,
+      debug,
+    });
+
+    await this.verifyIngotActive(vaultId, response.data.ingot_id, vat);
+
+    return {
+      ingot_id: response.data.ingot_id,
+      name,
+      size_bytes: fileSize,
+      storage_location: 's3',
+    };
+  }
+
+  async rename(vaultId: string, ingotId: string, vat: string, name: string): Promise<Ingot> {
+    validateVaultId(vaultId);
+    validateIngotId(ingotId);
+    const response = await this.http.patch<Ingot>(`/vaults/${vaultId}/ingots/${ingotId}`, { name }, { vat });
+    return response.data;
+  }
+
+  async list(
+    vaultId: string,
+    vat: string,
+    options?: { limit?: number; cursor?: string }
+  ): Promise<ListIngotsResponse> {
+    validateVaultId(vaultId);
+    const params = new URLSearchParams();
+    if (options?.limit) params.append('limit', options.limit.toString());
+    if (options?.cursor) params.append('cursor', options.cursor);
+
+    const query = params.toString();
+    const response = await this.http.get<ListIngotsResponse>(
+      query ? `/vaults/${vaultId}/ingots?${query}` : `/vaults/${vaultId}/ingots`,
+      { vat }
+    );
+    return response.data;
+  }
+
+  async listContents(
+    vaultId: string,
+    vat: string,
+    options?: {
+      folder_id?: string | null;
+      cursor?: string;
+      limit?: number;
+      sort_by?: string;
+      sort_order?: 'asc' | 'desc';
+      type?: string;
+    }
+  ): Promise<ListIngotsResponse> {
+    validateVaultId(vaultId);
+    const params = new URLSearchParams();
+    if (options?.folder_id) params.append('folder_id', options.folder_id);
+    if (options?.cursor) params.append('cursor', options.cursor);
+    if (options?.limit) params.append('limit', options.limit.toString());
+    if (options?.sort_by) params.append('sort_by', options.sort_by);
+    if (options?.sort_order) params.append('sort_order', options.sort_order);
+    if (options?.type && options.type !== 'all') params.append('type', options.type);
+
+    const query = params.toString();
+    const response = await this.http.get<ListIngotsResponse>(
+      query ? `/vaults/${vaultId}/contents?${query}` : `/vaults/${vaultId}/contents`,
+      { vat }
+    );
+    return response.data;
+  }
+
+  async search(
+    vaultId: string,
+    vat: string,
+    options?: {
+      q?: string;
+      file_type?: string;
+      min_size?: number;
+      max_size?: number;
+      limit?: number;
+      cursor?: string;
+      sort_order?: 'asc' | 'desc';
+    }
+  ): Promise<ListIngotsResponse> {
+    validateVaultId(vaultId);
+    const params = new URLSearchParams();
+    if (options?.q) params.append('q', options.q);
+    if (options?.file_type && options.file_type !== 'all') params.append('file_type', options.file_type);
+    if (options?.min_size !== undefined) params.append('min_size', options.min_size.toString());
+    if (options?.max_size !== undefined) params.append('max_size', options.max_size.toString());
+    if (options?.limit) params.append('limit', options.limit.toString());
+    if (options?.cursor) params.append('cursor', options.cursor);
+    if (options?.sort_order) params.append('sort_order', options.sort_order);
+
+    const query = params.toString();
+    const response = await this.http.get<ListIngotsResponse>(
+      query ? `/vaults/${vaultId}/ingots/search?${query}` : `/vaults/${vaultId}/ingots/search`,
+      { vat }
+    );
+    return response.data;
+  }
+
+  async get(vaultId: string, ingotId: string, vat: string): Promise<Ingot> {
+    validateVaultId(vaultId);
+    validateIngotId(ingotId);
+    const response = await this.http.get<Ingot>(`/vaults/${vaultId}/ingots/${ingotId}`, { vat });
+    return response.data;
+  }
+
+  async delete(vaultId: string, ingotId: string, vat: string): Promise<void> {
+    validateVaultId(vaultId);
+    validateIngotId(ingotId);
+    await this.http.delete(`/vaults/${vaultId}/ingots/${ingotId}`, { vat });
+  }
+
+  private async getDownloadUrl(
+    vaultId: string,
+    ingotId: string,
+    vat: string
+  ): Promise<string> {
+    validateVaultId(vaultId);
+    validateIngotId(ingotId);
+
+    const response = await this.http.post<{ download_url?: string }>(
+      `/vaults/${vaultId}/ingots/${ingotId}/download`,
+      undefined,
+      { vat }
+    );
+
+    const downloadUrl = response.data.download_url;
+    if (!downloadUrl) {
+      throw new SparkVaultMobileError('No download URL in response');
+    }
+
+    this.validateDownloadUrl(downloadUrl);
+    return downloadUrl;
+  }
+
+  async downloadToFile(options: DownloadToFileOptions): Promise<DownloadToFileResult> {
+    const {
+      vaultId,
+      ingotId,
+      vat,
+      fileUri,
+      expectedSizeBytes,
+      abortSignal,
+    } = options;
+    validateVaultId(vaultId);
+    validateIngotId(ingotId);
+    this.ensureNotAborted(abortSignal);
+
+    const fileDownloader = this.config.fileDownloader;
+    if (!fileDownloader) {
+      throw new SparkVaultValidationError('fileDownloader adapter is required for file downloads');
+    }
+
+    if (options.deleteExisting !== false) {
+      await this.deleteFileIfPresent(fileDownloader, fileUri);
+    }
+
+    const maxAttempts = options.retries ?? MobileIngotsClient.DOWNLOAD_MAX_ATTEMPTS;
+    const retryBaseDelayMs = options.retryBaseDelayMs ?? MobileIngotsClient.DOWNLOAD_RETRY_BASE_MS;
+    let lastError: Error | null = null;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      this.ensureNotAborted(abortSignal);
+      try {
+        // Fresh signed URL on every attempt — server URLs are short-lived,
+        // and retrying with a stale URL would just fail again.
+        const downloadUrl = await this.getDownloadUrl(vaultId, ingotId, vat);
+        const result = await fileDownloader.download(downloadUrl, fileUri, {
+          timeoutMs: options.timeoutMs ?? this.config.fileTransferTimeoutMs,
+          abortSignal,
+          onProgress: progress => options.onProgress?.(
+            progress.bytesWritten,
+            progress.bytesTotal ?? expectedSizeBytes ?? 0
+          ),
+        });
+
+        const status = result?.status;
+        if (result?.uri && (status === undefined || (status >= 200 && status < 300))) {
+          return await this.verifyDownloadedFile(
+            fileDownloader,
+            result.uri,
+            fileUri,
+            result.sizeBytes,
+            expectedSizeBytes
+          );
+        }
+
+        await this.deleteFileIfPresent(fileDownloader, fileUri);
+
+        const statusCode = result?.status;
+        const statusLabel = statusCode ?? 'unknown';
+        lastError = new SparkVaultMobileError(`Download failed with status ${statusLabel}`, {
+          code: statusLabel,
+          statusCode,
+        });
+      } catch (err) {
+        if (this.isAbortError(err) || abortSignal?.aborted) {
+          await this.deleteFileIfPresent(fileDownloader, fileUri);
+          throw new SparkVaultMobileError('Download cancelled', { code: 'download_cancelled' });
+        }
+        lastError = err instanceof Error ? err : new Error(String(err));
+      }
+
+      if (!this.isRetryableDownloadError(lastError) || attempt === maxAttempts) {
+        throw lastError;
+      }
+
+      await this.delay(retryBaseDelayMs * 2 ** (attempt - 1), abortSignal);
+    }
+
+    throw lastError ?? new SparkVaultMobileError('Download failed');
+  }
+
+  async getSharingConfig(vaultId: string, ingotId: string, vat: string): Promise<IngotSharingConfig> {
+    validateVaultId(vaultId);
+    validateIngotId(ingotId);
+    const response = await this.http.get<IngotSharingConfig>(
+      `/vaults/${vaultId}/ingots/${ingotId}/sharing`,
+      { vat }
+    );
+    return response.data;
+  }
+
+  async updateSharingConfig(
+    vaultId: string,
+    ingotId: string,
+    vat: string,
+    config: {
+      shared?: boolean;
+      visibility?: 'invite_only' | 'authenticated' | 'public';
+    }
+  ): Promise<IngotSharingConfig> {
+    validateVaultId(vaultId);
+    validateIngotId(ingotId);
+    const response = await this.http.put<IngotSharingConfig>(
+      `/vaults/${vaultId}/ingots/${ingotId}/sharing`,
+      config,
+      { vat }
+    );
+    return response.data;
+  }
+
+  async addInvite(
+    vaultId: string,
+    ingotId: string,
+    vat: string,
+    identity: string,
+    identityType: 'email' = 'email'
+  ): Promise<IngotInvite> {
+    validateVaultId(vaultId);
+    validateIngotId(ingotId);
+    const response = await this.http.post<IngotInvite>(
+      `/vaults/${vaultId}/ingots/${ingotId}/sharing/invite`,
+      { identity, identity_type: identityType },
+      { vat }
+    );
+    return response.data;
+  }
+
+  async revokeInvite(vaultId: string, ingotId: string, vat: string, inviteId: string): Promise<void> {
+    validateVaultId(vaultId);
+    validateIngotId(ingotId);
+    await this.http.delete(`/vaults/${vaultId}/ingots/${ingotId}/sharing/invite/${inviteId}`, { vat });
+  }
+
+  async getAccessLogs(
+    vaultId: string,
+    ingotId: string,
+    vat: string,
+    options?: { limit?: number; cursor?: string }
+  ): Promise<{ logs: IngotAccessLog[]; next_cursor?: string }> {
+    validateVaultId(vaultId);
+    validateIngotId(ingotId);
+    const params = new URLSearchParams();
+    if (options?.limit) params.append('limit', options.limit.toString());
+    if (options?.cursor) params.append('cursor', options.cursor);
+
+    const query = params.toString();
+    const response = await this.http.get<{ logs: IngotAccessLog[]; next_cursor?: string }>(
+      query
+        ? `/vaults/${vaultId}/ingots/${ingotId}/access-logs?${query}`
+        : `/vaults/${vaultId}/ingots/${ingotId}/access-logs`,
+      { vat }
+    );
+    return response.data;
+  }
+
+  async getAccessStats(vaultId: string, ingotId: string, vat: string): Promise<IngotAccessStats> {
+    validateVaultId(vaultId);
+    validateIngotId(ingotId);
+    const response = await this.http.get<IngotAccessStats>(
+      `/vaults/${vaultId}/ingots/${ingotId}/access-stats`,
+      { vat }
+    );
+    return response.data;
+  }
+
+  async purgeAccessLogs(vaultId: string, ingotId: string, vat: string): Promise<void> {
+    validateVaultId(vaultId);
+    validateIngotId(ingotId);
+    await this.http.delete(`/vaults/${vaultId}/ingots/${ingotId}/access-logs`, { vat });
+  }
+
+  private async createIngotUpload(options: {
+    vaultId: string;
+    vat: string;
+    name: string;
+    contentType: string;
+    sizeBytes: number;
+  }): Promise<IngotUploadInitResponse> {
+    const response = await this.http.post<IngotUploadInitResponse>(
+      `/vaults/${options.vaultId}/ingots`,
+      {
+        name: options.name,
+        content_type: options.contentType,
+        size_bytes: options.sizeBytes,
+      },
+      { vat: options.vat }
+    );
+
+    if (!response.data.ingot_id || !response.data.forge_url) {
+      throw new SparkVaultMobileError('Server returned invalid response for ingot creation');
+    }
+
+    return response.data;
+  }
+
+  private async verifyIngotActive(vaultId: string, ingotId: string, vat: string): Promise<Ingot> {
+    let ingot: Ingot | null = null;
+
+    for (let attempt = 1; attempt <= MobileIngotsClient.INGOT_STATUS_POLL_MAX; attempt++) {
+      ingot = await this.get(vaultId, ingotId, vat);
+
+      if (ingot.status === 'active') {
+        return ingot;
+      }
+
+      if (ingot.status === 'failed') {
+        throw new SparkVaultMobileError('Upload failed: server encryption error');
+      }
+
+      if (attempt < MobileIngotsClient.INGOT_STATUS_POLL_MAX) {
+        await new Promise(resolve => setTimeout(resolve, MobileIngotsClient.INGOT_STATUS_POLL_MS));
+      }
+    }
+
+    throw new SparkVaultMobileError(`Upload failed: ingot status is ${ingot?.status ?? 'unknown'}`);
+  }
+
+  private async verifyDownloadedFile(
+    fileDownloader: MobileFileDownloader,
+    preferredUri: string,
+    expectedUri: string,
+    knownSizeBytes?: number,
+    expectedSizeBytes?: number
+  ): Promise<DownloadToFileResult> {
+    const filePath = preferredUri || expectedUri;
+    const info = await fileDownloader.getInfo(filePath);
+    if (!info.exists) {
+      throw new SparkVaultMobileError('Download failed - file does not exist');
+    }
+
+    const sizeBytes = info.sizeBytes ?? knownSizeBytes ?? 0;
+    if (sizeBytes <= 0) {
+      await this.deleteFileIfPresent(fileDownloader, filePath);
+      throw new SparkVaultMobileError('Download failed - file is empty');
+    }
+
+    if (expectedSizeBytes !== undefined && expectedSizeBytes > 0 && sizeBytes !== expectedSizeBytes) {
+      await this.deleteFileIfPresent(fileDownloader, filePath);
+      // Deterministic server-content mismatch — retrying the same ingot will
+      // yield the same bytes, so this must surface as a non-retryable validation
+      // failure rather than a transient transport error.
+      throw new SparkVaultValidationError('Download failed - file size did not match expected ingot size', {
+        expectedSizeBytes,
+        actualSizeBytes: sizeBytes,
+      });
+    }
+
+    return { filePath, sizeBytes };
+  }
+
+  private async deleteFileIfPresent(fileDownloader: MobileFileDownloader, fileUri: string): Promise<void> {
+    await fileDownloader.delete(fileUri).catch(() => undefined);
+  }
+
+  private ensureNotAborted(signal?: AbortSignal): void {
+    if (signal?.aborted) {
+      throw new SparkVaultMobileError('Download cancelled', { code: 'download_cancelled' });
+    }
+  }
+
+  private isAbortError(err: unknown): boolean {
+    return err instanceof Error && (
+      err.name === 'AbortError' ||
+      err.message.toLowerCase().includes('abort') ||
+      err.message.toLowerCase().includes('cancelled')
+    );
+  }
+
+  private isRetryableDownloadError(err: Error): boolean {
+    // Validation errors (bad URL, bad size, bad host) won't be fixed by retrying.
+    if (err instanceof SparkVaultValidationError) return false;
+    const status = (err as Error & { statusCode?: number }).statusCode;
+    if (typeof status === 'number' && status >= 400 && status < 500 && status !== 408 && status !== 429) {
+      return false;
+    }
+    return true;
+  }
+
+  private delay(ms: number, signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        signal?.removeEventListener('abort', onAbort);
+        resolve();
+      }, ms);
+      const onAbort = () => {
+        clearTimeout(timeout);
+        reject(new SparkVaultMobileError('Download cancelled', { code: 'download_cancelled' }));
+      };
+      if (signal?.aborted) {
+        clearTimeout(timeout);
+        reject(new SparkVaultMobileError('Download cancelled', { code: 'download_cancelled' }));
+        return;
+      }
+      signal?.addEventListener('abort', onAbort, { once: true });
+    });
+  }
+
+  private validateDownloadUrl(downloadUrl: string): void {
+    let url: URL;
+    try {
+      url = new URL(downloadUrl);
+    } catch {
+      throw new SparkVaultValidationError('Invalid download URL from server');
+    }
+
+    if (url.protocol !== 'https:') {
+      throw new SparkVaultValidationError('Invalid download URL from server', {
+        reason: 'non_https_download_url',
+      });
+    }
+
+    const allowed = this.config.allowedDownloadHostPatterns.some(pattern => pattern.test(url.hostname));
+    if (!allowed) {
+      throw new SparkVaultValidationError('Invalid download URL from server', {
+        reason: 'download_host_not_allowed',
+        hostname: url.hostname,
+      });
+    }
+  }
+
+}