@sparkvault/sdk-mobile 5.2.2 → 5.2.3

package/src/types.ts

@@ -583,6 +583,21 @@ export interface UploadResult {
   name: string;
   size_bytes: number;
   storage_location: 's3';
+  /**
+   * Whether this upload minted the ingot (true) or was handed an existing row
+   * by the server's same-name upsert / a resumed session (false). A caller
+   * that discards its ingot on a failure path needs this to tell "mine to
+   * discard" from "someone else's live row".
+   */
+  created?: boolean;
+  /**
+   * The ingot status the upload last observed: `active` when the server
+   * confirmed activation. Anything else means the transfer completed but the
+   * activation poll budget ran out first - the ingot usually activates
+   * moments later, but a caller recording "backed up" must not take that on
+   * faith (resume the session later; Forge re-confirms finalization).
+   */
+  status?: string;
 }
 
 export interface IngotSharingConfig {
@@ -691,6 +706,119 @@ export interface MobileFileReader {
   readAsBase64(fileUri: string, options: { position: number; length: number }): Promise<string>;
 }
 
+/**
+ * A tus upload session as Forge created it: the session URL, the per-upload
+ * token every request on it must carry, and the chunk geometry Forge fixed
+ * for it. Persist it to resume the upload after a failed attempt or a
+ * relaunch (`ingots.resumeUpload`) instead of re-sending bytes Forge holds.
+ */
+export interface TusSessionInfo {
+  uploadUrl: string;
+  istk: string;
+  chunkSize: number;
+}
+
+/**
+ * The Forge tus session an ingot upload created, bound to the ingot the API
+ * minted (or handed back) for it. Everything `ingots.resumeUpload` needs.
+ */
+export interface IngotUploadSession extends TusSessionInfo {
+  ingotId: string;
+  /** Whether the upload minted the ingot (see `UploadResult.created`). */
+  created: boolean;
+}
+
+/**
+ * Which transport a tus upload rides. `foreground` (the default) streams
+ * chunks over XHR with progress events, abort, and the stall watchdog.
+ * `background` asks for the transfer to survive the app being suspended, and
+ * resolves to the best engine the app provides, in order: the OS transfer
+ * engine (`backgroundTransfer`: any file size, any offset, progress and
+ * abort, chunks chained natively), else the single-chunk background adapter
+ * (`backgroundUploader`: only a file that fits one chunk, no progress, no
+ * abort), else plain XHR. The upload semantics are the same on every engine;
+ * only the guarantees against suspension differ.
+ */
+export type UploadTransport = 'foreground' | 'background';
+
+/**
+ * The remaining range of a tus session handed to the OS transfer engine:
+ * everything from `offset` to `fileSize`, PATCHed in `chunkSize` pieces with
+ * the four tus headers. The network flags ride on every request the engine
+ * sends, because the OS (not JS) is what waits for an acceptable network
+ * while the app is suspended.
+ */
+export interface BackgroundTransferJob {
+  uploadUrl: string;
+  istk: string;
+  /** file:// URI of the whole source file; it must stay in place until the job completes. */
+  fileUri: string;
+  fileSize: number;
+  /** Forge X-Chunk-Size: every non-final PATCH body is exactly this many bytes. */
+  chunkSize: number;
+  /** Server offset to start from (0 after create; the HEAD offset on resume). */
+  offset: number;
+  allowsCellularAccess: boolean;
+  allowsConstrainedNetworkAccess: boolean;
+}
+
+/**
+ * Why an OS transfer ended without reaching the final offset. `http` carries
+ * Forge's status and body (the SDK maps gates and lost sessions from them);
+ * `cancelled` is the caller's own abort; `interrupted` is the OS ending the
+ * task without being asked (a relaunch, a system cancel); `stalled` is a 2xx
+ * whose offset did not advance; `file` is a source the engine could not read.
+ */
+export type BackgroundTransferFailureKind = 'network' | 'http' | 'file' | 'cancelled' | 'stalled' | 'interrupted';
+
+/** App adapter over an OS-driven background transfer engine (iOS background URLSession with native chunk chaining). */
+export interface MobileBackgroundTransfer {
+  /** Resolves when the OS reports the final offset; rejects with BackgroundTransferError. Start-or-attach: the same uploadUrl attaches to a job already running. */
+  transfer(
+    job: BackgroundTransferJob,
+    options: { abortSignal?: AbortSignal; onProgress?: (offset: number) => void }
+  ): Promise<{ offset: number }>;
+  /** Cancel and forget the OS job for this session (no-op when none). */
+  cancel(uploadUrl: string): Promise<void>;
+}
+
+/** Network policy an upload carries into the OS transfer; ignored by the XHR paths (JS gates those). Defaults: both true. */
+export interface UploadTransferPolicy {
+  allowsCellularAccess?: boolean;
+  allowsConstrainedNetworkAccess?: boolean;
+}
+
+/**
+ * What happens to the Forge tus session when an upload's `abortSignal` fires
+ * mid-transfer. `terminate` (the default) sends a tus DELETE so Forge drops
+ * the chunks it already holds: right for a user cancel, where the bytes will
+ * never be wanted again. `keep` leaves the session untouched on Forge, so a
+ * PAUSE (WiFi lost, low battery, app going to background) can stop the
+ * transfer now and `ingots.resumeUpload` it later from the server offset
+ * instead of re-sending the file. The caller owns a kept session: it is
+ * expected to persist it (`onSessionCreated`) and resume or terminate it,
+ * otherwise it only goes away when Forge's abandoned-session TTL reaps it.
+ * The cancellation error is identical either way.
+ */
+export type UploadAbortBehavior = 'terminate' | 'keep';
+
+/**
+ * App-provided adapter that PATCHes a whole local file as the request body
+ * on a background URLSession (expo-file-system legacy `uploadAsync` with
+ * `sessionType: BACKGROUND`), so a single-chunk upload finishes even when iOS
+ * suspends the app mid-transfer. The fallback behind `backgroundTransfer`:
+ * the tus uploader reaches for it only when no OS transfer engine is
+ * configured and the file fits one chunk; everything else keeps the
+ * streaming XHR path.
+ */
+export interface MobileBackgroundUploader {
+  uploadFile(
+    url: string,
+    fileUri: string,
+    options: { method: 'PATCH'; headers: Record<string, string> }
+  ): Promise<{ status: number; headers: Record<string, string>; body: string }>;
+}
+
 export interface MobileDownloadProgress {
   bytesWritten: number;
   bytesTotal?: number;