@sparkvault/sdk-mobile 5.2.2 → 5.3.0

package/src/ingots.ts

@@ -16,9 +16,13 @@ import type {
   IngotInvite,
   IngotSharingConfig,
   ListIngotsResponse,
+  IngotUploadSession,
   MobileFileDownloader,
+  UploadAbortBehavior,
   UploadProgressCallback,
   UploadResult,
+  UploadTransferPolicy,
+  UploadTransport,
 } from './types.js';
 import { validateIngotId, validateVaultId } from './validation.js';
 
@@ -51,6 +55,34 @@ export interface UploadOptions {
 export interface UploadFromUriOptions extends UploadOptions {
   fileUri: string;
   fileSize: number;
+  /**
+   * Invoked once the API has minted (or, via its same-name upsert, handed
+   * back) the ingot and before any Forge session exists. `created: false`
+   * means the bytes about to be sent will REPLACE an existing ingot's content
+   * once they finalize; a caller that must never overwrite throws here, and
+   * the throw propagates as-is with nothing sent and no session to clean up.
+   */
+  onIngotCreated?: (ingot: { ingotId: string; created: boolean }) => void;
+  /**
+   * Invoked once the Forge tus session exists and before the first byte is
+   * sent, so the caller can persist it and `resumeUpload` after a failed
+   * attempt or a relaunch instead of re-sending bytes Forge already holds.
+   */
+  onSessionCreated?: (session: IngotUploadSession) => void;
+  /** See `UploadTransport`; default `foreground`. */
+  transport?: UploadTransport;
+  /** Network policy for the OS transfer engine; see `UploadTransferPolicy`. Default: both allowed. */
+  transferPolicy?: UploadTransferPolicy;
+  /**
+   * What an abort does to the Forge session; see `UploadAbortBehavior`.
+   * Default `terminate` (a user cancel: Forge drops the chunks). `keep`
+   * (a pause) leaves the session on Forge so the caller can `resumeUpload`
+   * the one it was handed via `onSessionCreated` from the server offset;
+   * the caller then owns that session and is expected to resume or
+   * terminate it. The error is the same either way: the pre-flight
+   * `upload_cancelled` or the tus `cancelled`-phase `TusUploadError`.
+   */
+  abortBehavior?: UploadAbortBehavior;
   debug?: DebugLogger;
 }
 
@@ -58,6 +90,31 @@ export interface ReplaceFromUriOptions extends UploadFromUriOptions {
   ingotId: string;
 }
 
+export interface ResumeUploadOptions {
+  vaultId: string;
+  vat: string;
+  /** The ingot the session was created for (`UploadResult.ingot_id`). */
+  ingotId: string;
+  fileUri: string;
+  fileSize: number;
+  name: string;
+  contentType: string;
+  /** The persisted tus session handed to `onSessionCreated`. */
+  session: { uploadUrl: string; istk: string };
+  /** See `UploadTransport`; default `foreground`. */
+  transport?: UploadTransport;
+  /** Network policy for the OS transfer engine; see `UploadTransferPolicy`. Default: both allowed. */
+  transferPolicy?: UploadTransferPolicy;
+  onProgress?: UploadProgressCallback;
+  abortSignal?: AbortSignal;
+  /**
+   * See `UploadFromUriOptions.abortBehavior`. `keep` leaves `session` on
+   * Forge across the abort so the same session can be resumed again later.
+   */
+  abortBehavior?: UploadAbortBehavior;
+  debug?: DebugLogger;
+}
+
 export interface DownloadToFileOptions {
   vaultId: string;
   ingotId: string;
@@ -109,6 +166,11 @@ export interface CreateUploadResult {
   forgeUrl: string;
   name?: string;
   sizeBytes?: number;
+  /**
+   * Whether the server minted this ingot (true) or handed back an existing
+   * row via its same-name upsert (false). Absent when the server did not say.
+   */
+  created?: boolean;
 }
 
 export interface CreateDownloadLinkOptions {
@@ -127,6 +189,7 @@ interface IngotUploadInitResponse {
   forge_url: string;
   name?: string;
   size_bytes?: number;
+  created?: boolean;
 }
 
 interface IngotAuditLogEntry {
@@ -214,6 +277,12 @@ export class MobileIngotsClient {
       folderId: options.folderId,
       contentHmac: options.contentHmac,
     });
+    const created = init.created ?? true;
+
+    // The ingot row exists but no Forge session does: a caller that refuses
+    // to replace an existing ingot (created: false) aborts here, before a
+    // byte moves, and its error reaches it untouched.
+    options.onIngotCreated?.({ ingotId: init.ingotId, created });
 
     await this.tus.uploadFromUri({
       fileUri: options.fileUri,
@@ -221,21 +290,96 @@ export class MobileIngotsClient {
       filename: options.name,
       contentType: options.contentType,
       forgeUrl: init.forgeUrl,
+      onSessionCreated: session => options.onSessionCreated?.({ ...session, ingotId: init.ingotId, created }),
+      transport: options.transport,
+      transferPolicy: options.transferPolicy,
       onProgress: options.onProgress,
       abortSignal: options.abortSignal,
+      abortBehavior: options.abortBehavior,
       debug: options.debug,
     });
 
-    await this.verifyIngotActive(options.vaultId, init.ingotId, options.vat, options.debug);
+    const ingot = await this.verifyIngotActive(options.vaultId, init.ingotId, options.vat, options.debug);
 
     return {
       ingot_id: init.ingotId,
       name: init.name ?? options.name,
       size_bytes: init.sizeBytes ?? options.fileSize,
       storage_location: 's3',
+      // A server that does not report it minted the row (the upsert is the
+      // only other outcome, and it always says so).
+      created,
+      status: ingot.status,
+    };
+  }
+
+  /**
+   * Continue an interrupted upload from the tus session `uploadFromUri`
+   * handed to `onSessionCreated`. No ingot is created: the record already
+   * exists from the original call, and the session is bound to it — Forge is
+   * asked (HEAD) where the transfer stands and only the missing bytes are
+   * sent, then the ingot is verified active exactly as a fresh upload is.
+   *
+   * A `TusUploadError` with `sessionLost` means Forge no longer has the
+   * session (expired or terminated); the caller drops it and starts over
+   * with `uploadFromUri`.
+   */
+  async resumeUpload(options: ResumeUploadOptions): Promise<UploadResult> {
+    validateVaultId(options.vaultId);
+    validateIngotId(options.ingotId);
+    if (options.abortSignal?.aborted) {
+      throw new SparkVaultMobileError('Upload cancelled', { code: 'upload_cancelled' });
+    }
+
+    await this.tus.uploadFromUri({
+      fileUri: options.fileUri,
+      fileSize: options.fileSize,
+      filename: options.name,
+      contentType: options.contentType,
+      resume: options.session,
+      transport: options.transport,
+      transferPolicy: options.transferPolicy,
+      onProgress: options.onProgress,
+      abortSignal: options.abortSignal,
+      abortBehavior: options.abortBehavior,
+      debug: options.debug,
+    });
+
+    const ingot = await this.verifyIngotActive(options.vaultId, options.ingotId, options.vat, options.debug);
+
+    return {
+      ingot_id: options.ingotId,
+      name: options.name,
+      size_bytes: options.fileSize,
+      storage_location: 's3',
+      created: false,
+      status: ingot.status,
     };
   }
 
+  /**
+   * Where a persisted tus session stands on Forge, or `null` when Forge no
+   * longer has it. Lets a caller reconcile sessions on relaunch — a session
+   * at `offset === length` only needs its ingot verified, a lost one needs a
+   * fresh `uploadFromUri` — without spending an upload slot to find out.
+   */
+  probeUploadSession(
+    session: { uploadUrl: string; istk: string }
+  ): Promise<{ offset: number; length: number; chunkSize: number } | null> {
+    return this.tus.probeSession(session);
+  }
+
+  /**
+   * Release a tus session the caller kept on Forge (`abortBehavior: 'keep'`)
+   * and has since abandoned, so Forge drops the chunks it holds and settles
+   * the partial transfer's billing instead of waiting for expiry. Resolves
+   * once the session is gone, including when Forge no longer had it
+   * (404/410); any other failure rejects so the caller can retry later.
+   */
+  terminateUploadSession(session: { uploadUrl: string; istk: string }): Promise<void> {
+    return this.tus.terminateSession(session);
+  }
+
   /**
    * Initialize an ingot record and obtain the Forge resumable-upload endpoint
    * (with its upload-session token). The canonical first step of every upload;
@@ -273,6 +417,7 @@ export class MobileIngotsClient {
       forgeUrl: response.data.forge_url,
       name: response.data.name,
       sizeBytes: response.data.size_bytes,
+      created: typeof response.data.created === 'boolean' ? response.data.created : undefined,
     };
   }
 
@@ -306,18 +451,26 @@ export class MobileIngotsClient {
       filename: name,
       contentType,
       forgeUrl: response.data.forge_url,
+      // A replace never mints an ingot: the row is the caller's existing one.
+      onSessionCreated: session => options.onSessionCreated?.({ ...session, ingotId, created: false }),
+      transport: options.transport,
+      transferPolicy: options.transferPolicy,
       onProgress,
       abortSignal,
+      abortBehavior: options.abortBehavior,
       debug,
     });
 
-    await this.verifyIngotActive(vaultId, response.data.ingot_id, vat, debug);
+    const ingot = await this.verifyIngotActive(vaultId, response.data.ingot_id, vat, debug);
 
     return {
       ingot_id: response.data.ingot_id,
       name,
       size_bytes: fileSize,
       storage_location: 's3',
+      // A replace never mints an ingot: the row is the caller's existing one.
+      created: false,
+      status: ingot.status,
     };
   }