@sparkvault/sdk-mobile 5.3.0 → 6.0.0

package/src/tus.ts

@@ -149,17 +149,6 @@ function getErrorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
-function inferTusPhase(error: Error): TusUploadError['phase'] {
-  const message = error.message;
-  if (message.includes('cancelled') || message.includes('aborted')) return 'cancelled';
-  if (message.includes('timeout') || message.includes('timed out')) return 'timeout';
-  if (message.includes('stall')) return 'stalled';
-  if (message.includes('network')) return 'network';
-  if (message.includes('create') || message.includes('POST')) return 'create';
-  if (message.includes('upload') || message.includes('PATCH') || message.includes('Chunk')) return 'upload';
-  return 'unknown';
-}
-
 function ensureNotAborted(signal?: AbortSignal): void {
   if (signal?.aborted) {
     throw new TusUploadError('Upload cancelled', { phase: 'cancelled' });
@@ -194,6 +183,87 @@ function parseIntegerHeader(raw: string | null, minimum: number): number | null
   return Number.isSafeInteger(value) && value >= minimum ? value : null;
 }
 
+/** File context carried on every `TusUploadError` a request throws. */
+interface TusErrorContext {
+  filename?: string;
+  fileSize?: number;
+}
+
+/**
+ * Forge's answers that mean the tus session no longer exists: it expired,
+ * or a DELETE terminated it. One list, so every request that can meet a
+ * dead session (HEAD, the finalization PATCH, the OS engine's PATCHes,
+ * DELETE) and the app's own session bookkeeping agree on what "gone" is.
+ */
+const SESSION_GONE_STATUSES: ReadonlySet<number> = new Set([404, 410]);
+
+/**
+ * True when a Forge status says the tus session is gone (expired or
+ * terminated): the persisted session is worthless, and a caller starts a
+ * fresh upload instead of retrying it.
+ */
+export function isSessionGone(status: number): boolean {
+  return SESSION_GONE_STATUSES.has(status);
+}
+
+function sessionLostError(
+  status: number,
+  context: TusErrorContext,
+  phase: TusUploadError['phase'],
+  cause: Error | null = null
+): TusUploadError {
+  return new TusUploadError(`TUS session no longer exists on the server (${status})`, {
+    cause,
+    httpStatus: status,
+    ...context,
+    phase,
+    sessionLost: true,
+  });
+}
+
+interface TusRequestInit {
+  method: 'POST' | 'HEAD' | 'PATCH' | 'DELETE';
+  headers: Record<string, string>;
+  signal?: AbortSignal;
+  timeoutMs: number;
+}
+
+/**
+ * The one seam every tus request sent through `config.fetch` (the create
+ * POST, HEAD, the finalization PATCH, DELETE) passes its rejection through,
+ * so a request that never got an HTTP answer is classified once and the
+ * same way everywhere. The caller's own abort is `cancelled` and the request
+ * timeout is `timeout`: both arrive as an `AbortError` and the signal tells
+ * them apart, and an XHR adapter's `TimeoutError` is a timeout too (the
+ * same contract http.ts honours). An SDK error passes through untouched.
+ * Everything else is `network` (an offline device, a DNS failure, a reset
+ * connection), so `isNetworkError` holds and the caller retries instead of
+ * charging the failure to the file. Chunk PATCHes ride XHR directly and
+ * classify their own events (see uploadChunk).
+ */
+async function tusRequest(
+  config: ResolvedMobileConfig,
+  url: string,
+  init: TusRequestInit,
+  label: string,
+  context: TusErrorContext = {}
+): Promise<Response> {
+  try {
+    return await config.fetch(url, init);
+  } catch (err) {
+    if (err instanceof SparkVaultMobileError) throw err;
+    const cause = err instanceof Error ? err : null;
+    const name = getErrorName(err);
+    if (name === 'AbortError' && init.signal?.aborted) {
+      throw new TusUploadError('Upload cancelled', { cause, ...context, phase: 'cancelled' });
+    }
+    if (name === 'AbortError' || name === 'TimeoutError') {
+      throw new TusUploadError(`${label} timed out`, { cause, ...context, phase: 'timeout' });
+    }
+    throw new TusUploadError(`${label} failed: ${getErrorMessage(err)}`, { cause, ...context, phase: 'network' });
+  }
+}
+
 /**
  * Case-insensitive header lookup for adapter results. Native HTTP stacks
  * hand headers back in whatever case they please (iOS lower-cases them),
@@ -242,27 +312,23 @@ async function createTusUpload(
   ensureNotAborted(signal);
 
   const metadata = `filename ${base64EncodeUtf8(filename)},filetype ${base64EncodeUtf8(contentType || 'application/octet-stream')}`;
-  const response = await config.fetch(parsed.tusEndpoint, {
-    method: 'POST',
-    headers: {
-      'Tus-Resumable': TUS_VERSION,
-      'Upload-Length': String(fileSize),
-      'Upload-Metadata': metadata,
-      'X-ISTK': parsed.istk,
+  const response = await tusRequest(
+    config,
+    parsed.tusEndpoint,
+    {
+      method: 'POST',
+      headers: {
+        'Tus-Resumable': TUS_VERSION,
+        'Upload-Length': String(fileSize),
+        'Upload-Metadata': metadata,
+        'X-ISTK': parsed.istk,
+      },
+      signal,
+      timeoutMs: config.tusPostTimeoutMs,
     },
-    signal,
-    timeoutMs: config.tusPostTimeoutMs,
-  }).catch(err => {
-    if (getErrorName(err) === 'AbortError') {
-      throw new TusUploadError('TUS POST request timed out', {
-        cause: err instanceof Error ? err : null,
-        filename,
-        fileSize,
-        phase: 'timeout',
-      });
-    }
-    throw err;
-  });
+    'TUS POST request',
+    { filename, fileSize }
+  );
 
   if (!response.ok) {
     const errorText = await response.text().catch(() => '');
@@ -315,10 +381,11 @@ async function createTusUpload(
  * Ask Forge where a session stands (tus HEAD). This is the only way to learn
  * what a background URLSession delivered after the process was killed, and
  * what a failed attempt left behind — so resume never re-sends bytes the
- * server holds. A 404/410 means the session expired or was terminated: the
- * error carries `sessionLost` so the caller drops its persisted session and
- * creates a fresh one rather than retrying a dead URL. Any other failure
- * (a 5xx, an auth rejection, a timeout) leaves `sessionLost` false: the
+ * server holds. A status `isSessionGone` recognises means the session
+ * expired or was terminated: the error carries `sessionLost` so the caller
+ * drops its persisted session and creates a fresh one rather than retrying
+ * a dead URL. Any other failure (a 5xx, an auth rejection, a timeout)
+ * leaves `sessionLost` false: the
  * session may well be intact, and treating it as dead would re-upload a
  * whole file over a blip.
  */
@@ -327,38 +394,28 @@ async function headTusSession(
   uploadUrl: string,
   istk: string,
   signal?: AbortSignal,
-  context: { filename?: string; fileSize?: number } = {}
+  context: TusErrorContext = {}
 ): Promise<TusSessionProbe> {
   ensureNotAborted(signal);
 
-  const response = await config.fetch(uploadUrl, {
-    method: 'HEAD',
-    headers: {
-      'Tus-Resumable': TUS_VERSION,
-      'X-ISTK': istk,
+  const response = await tusRequest(
+    config,
+    uploadUrl,
+    {
+      method: 'HEAD',
+      headers: {
+        'Tus-Resumable': TUS_VERSION,
+        'X-ISTK': istk,
+      },
+      signal,
+      timeoutMs: config.tusPostTimeoutMs,
     },
-    signal,
-    timeoutMs: config.tusPostTimeoutMs,
-  }).catch(err => {
-    if (getErrorName(err) === 'AbortError') {
-      // The same AbortError ends a user cancel and the request timeout; the
-      // caller's signal tells them apart.
-      throw new TusUploadError(signal?.aborted ? 'Upload cancelled' : 'TUS HEAD request timed out', {
-        cause: err instanceof Error ? err : null,
-        ...context,
-        phase: signal?.aborted ? 'cancelled' : 'timeout',
-      });
-    }
-    throw err;
-  });
+    'TUS HEAD request',
+    context
+  );
 
-  if (response.status === 404 || response.status === 410) {
-    throw new TusUploadError(`TUS session no longer exists on the server (${response.status})`, {
-      httpStatus: response.status,
-      ...context,
-      phase: 'create',
-      sessionLost: true,
-    });
+  if (isSessionGone(response.status)) {
+    throw sessionLostError(response.status, context, 'create');
   }
 
   if (!response.ok) {
@@ -397,7 +454,8 @@ async function headTusSession(
  * to the status poll and could report a never-activated ingot as done.
  *
  * 409 means another finalizer holds the lease right now: retry later, the
- * session is intact. 404/410 mean the session is gone (`sessionLost`).
+ * session is intact. A status `isSessionGone` recognises means the session
+ * is gone (`sessionLost`).
  */
 async function confirmTusFinalization(
   config: ResolvedMobileConfig,
@@ -405,38 +463,30 @@ async function confirmTusFinalization(
   istk: string,
   fileSize: number,
   signal?: AbortSignal,
-  context: { filename?: string; fileSize?: number } = {}
+  context: TusErrorContext = {}
 ): Promise<void> {
   ensureNotAborted(signal);
 
-  const response = await config.fetch(uploadUrl, {
-    method: 'PATCH',
-    headers: {
-      'Tus-Resumable': TUS_VERSION,
-      'Upload-Offset': String(fileSize),
-      'Content-Type': 'application/offset+octet-stream',
-      'X-ISTK': istk,
+  const response = await tusRequest(
+    config,
+    uploadUrl,
+    {
+      method: 'PATCH',
+      headers: {
+        'Tus-Resumable': TUS_VERSION,
+        'Upload-Offset': String(fileSize),
+        'Content-Type': 'application/offset+octet-stream',
+        'X-ISTK': istk,
+      },
+      signal,
+      timeoutMs: config.tusChunkTimeoutMs,
     },
-    signal,
-    timeoutMs: config.tusChunkTimeoutMs,
-  }).catch(err => {
-    if (getErrorName(err) === 'AbortError') {
-      throw new TusUploadError(signal?.aborted ? 'Upload cancelled' : 'TUS finalization request timed out', {
-        cause: err instanceof Error ? err : null,
-        ...context,
-        phase: signal?.aborted ? 'cancelled' : 'timeout',
-      });
-    }
-    throw err;
-  });
+    'TUS finalization request',
+    context
+  );
 
-  if (response.status === 404 || response.status === 410) {
-    throw new TusUploadError(`TUS session no longer exists on the server (${response.status})`, {
-      httpStatus: response.status,
-      ...context,
-      phase: 'create',
-      sessionLost: true,
-    });
+  if (isSessionGone(response.status)) {
+    throw sessionLostError(response.status, context, 'create');
   }
   if (response.status === 409) {
     throw new TusUploadError('TUS finalization is already in progress on the server; retry shortly', {
@@ -620,12 +670,12 @@ async function uploadWholeFileInBackground(
 
   const body = typeof result.body === 'string' ? result.body : '';
   if (result.status >= 200 && result.status < 300) {
-    const offsetHeader = getHeaderIgnoreCase(result.headers, 'Upload-Offset');
-    // Forge always answers a PATCH with Upload-Offset. A 2xx without it is not
-    // Forge (a captive portal's 200 page is the classic case), so report no
-    // advance: the stall guard fails the attempt and the next one asks Forge
-    // (HEAD) instead of marking bytes uploaded that may never have arrived.
-    return offsetHeader ? parseInt(offsetHeader, 10) : offset;
+    // Forge always answers a PATCH with a readable Upload-Offset. A 2xx
+    // without one is not Forge (a captive portal's 200 page is the classic
+    // case), so report no advance: the stall guard fails the attempt and the
+    // next one asks Forge (HEAD) instead of marking bytes uploaded that may
+    // never have arrived. Same strict parse as the XHR path (uploadChunk).
+    return parseIntegerHeader(getHeaderIgnoreCase(result.headers, 'Upload-Offset'), 0) ?? offset;
   }
 
   const gateError = gateErrorFromBody(result.status, parseErrorBody(body));
@@ -643,9 +693,10 @@ async function uploadWholeFileInBackground(
  * taxonomy, so a caller sees the same `TusUploadError` phases and typed gate
  * errors whichever engine carried the bytes. Forge's status and body ride
  * through untouched: a 402 becomes the gate error the XHR path throws, a
- * 404/410 marks the session lost exactly as HEAD would, and any other status
- * keeps its number for the caller's own policy (a 409 during finalize is a
- * retry-later, not a lost session). The remaining kinds are transport
+ * status `isSessionGone` recognises marks the session lost exactly as HEAD
+ * would, and any other status keeps its number for the caller's own policy
+ * (a 409 during finalize is a retry-later, not a lost session). The
+ * remaining kinds are transport
  * outcomes: the caller's own abort is `cancelled`; an OS-ended task
  * (`interrupted`) is a network failure, because the right response is the
  * same as for a dropped connection: resume from the server offset. Anything
@@ -654,7 +705,7 @@ async function uploadWholeFileInBackground(
  */
 export function mapBackgroundTransferError(
   err: unknown,
-  context: { filename?: string; fileSize?: number } = {}
+  context: TusErrorContext = {}
 ): SparkVaultMobileError {
   if (!(err instanceof BackgroundTransferError)) {
     return new TusUploadError(`Background transfer failed: ${getErrorMessage(err)}`, {
@@ -671,13 +722,11 @@ export function mapBackgroundTransferError(
       if (status !== undefined) {
         const gateError = gateErrorFromBody(status, parseErrorBody(body));
         if (gateError) return gateError;
+        if (isSessionGone(status)) return sessionLostError(status, context, 'upload', err);
       }
-      const sessionLost = status === 404 || status === 410;
       return new TusUploadError(
-        sessionLost
-          ? `TUS session no longer exists on the server (${status})`
-          : `Background chunk upload failed: ${status ?? 'unknown status'} - ${body.substring(0, 200)}`,
-        { cause: err, httpStatus: status ?? null, ...context, phase: 'upload', sessionLost }
+        `Background chunk upload failed: ${status ?? 'unknown status'} - ${body.substring(0, 200)}`,
+        { cause: err, httpStatus: status ?? null, ...context, phase: 'upload' }
       );
     }
     case 'cancelled':
@@ -919,10 +968,13 @@ export class MobileTusUploader {
       // the caller intact so the subscribe / add-on UX fires; never bury them
       // in a generic TusUploadError.
       if (err instanceof SparkVaultMobileError) throw err;
+      // Only a fileReader read or an onSessionCreated hook can throw anything
+      // else here: every request classifies its own failure (tusRequest,
+      // uploadChunk, the adapters). Those are the caller's errors, wrapped
+      // with the file context and nothing inferred about them.
       throw TusUploadError.fromError(error, {
         filename: options.filename,
         fileSize: options.fileSize,
-        phase: inferTusPhase(error),
       });
     }
   }
@@ -963,9 +1015,10 @@ export class MobileTusUploader {
    * and will not resume after all: the tus DELETE lets Forge drop the chunk
    * objects it holds (nothing else cleans them up before expiry) and settle
    * the partial transfer's billing. Resolves once the session is gone,
-   * which includes Forge answering 404/410 (already expired or terminated);
-   * any other failure rejects with a `TusUploadError` (a timeout, or the
-   * status Forge sent) so the caller can retry later. Not bound to any
+   * which includes Forge answering a status `isSessionGone` recognises
+   * (already expired or terminated); any other failure rejects with a
+   * `TusUploadError` (a timeout, a connectivity failure, or the status
+   * Forge sent) so the caller can retry later. Not bound to any
    * abort signal: a terminate is the last thing a caller does with a
    * session, never something to cancel.
    */
@@ -978,17 +1031,9 @@ export class MobileTusUploader {
       await this.cancelBackgroundTransfer(backgroundTransfer, session.uploadUrl);
     }
 
-    const response = await this.requestTerminate(session.uploadUrl, session.istk).catch(err => {
-      if (getErrorName(err) === 'AbortError') {
-        throw new TusUploadError('TUS DELETE request timed out', {
-          cause: err instanceof Error ? err : null,
-          phase: 'timeout',
-        });
-      }
-      throw err;
-    });
+    const response = await this.requestTerminate(session.uploadUrl, session.istk);
 
-    if (response.ok || response.status === 404 || response.status === 410) return;
+    if (response.ok || isSessionGone(response.status)) return;
 
     const errorText = await response.text().catch(() => '');
     throw new TusUploadError(`TUS terminate failed: ${response.status} - ${errorText.substring(0, 200)}`, {
@@ -1045,14 +1090,19 @@ export class MobileTusUploader {
    * callers for why neither may carry one).
    */
   private requestTerminate(uploadUrl: string, istk: string): Promise<Response> {
-    return this.config.fetch(uploadUrl, {
-      method: 'DELETE',
-      headers: {
-        'Tus-Resumable': TUS_VERSION,
-        'X-ISTK': istk,
+    return tusRequest(
+      this.config,
+      uploadUrl,
+      {
+        method: 'DELETE',
+        headers: {
+          'Tus-Resumable': TUS_VERSION,
+          'X-ISTK': istk,
+        },
+        timeoutMs: this.config.tusPostTimeoutMs,
       },
-      timeoutMs: this.config.tusPostTimeoutMs,
-    });
+      'TUS DELETE request'
+    );
   }
 
   private async readChunk(

package/src/types.ts

@@ -603,7 +603,7 @@ export interface UploadResult {
    * moments later, but a caller recording "backed up" must not take that on
    * faith (resume the session later; Forge re-confirms finalization).
    */
-  status?: string;
+  status?: Ingot['status'];
 }
 
 export interface IngotSharingConfig {
@@ -769,11 +769,13 @@ export interface BackgroundTransferJob {
 }
 
 /**
- * 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.
+ * Why an OS transfer ended without reaching the final offset: the engine's
+ * own failure kinds plus `cancelled`, which only the app adapter produces
+ * for the caller's own abort (the engine never reports a cancel it was asked
+ * for). `http` carries Forge's status and body (the SDK maps gates and lost
+ * sessions from them); `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';
 
@@ -842,6 +844,15 @@ export interface MobileFileInfo {
   sizeBytes?: number;
 }
 
+/**
+ * App-provided file download adapter. The rejection contract is typed, not
+ * textual: a download the caller's `abortSignal` cut short rejects with an
+ * Error whose `name` is `'AbortError'` (the SDK reports it as cancelled and
+ * never retries it); a download that ran past `timeoutMs` rejects with a
+ * `SparkVaultTimeoutError` (retried like any connectivity failure). Any
+ * other rejection is a transport failure the SDK retries with a fresh
+ * signed URL.
+ */
 export interface MobileFileDownloader {
   download(
     url: string,