@sparkvault/sdk-mobile 7.0.0 → 7.0.1

package/src/config.ts

@@ -31,6 +31,11 @@ export interface SparkVaultMobileConfig {
   userAgent?: string;
   timeoutMs?: number;
   fileTransferTimeoutMs?: number;
+  /**
+   * Timeout of a tus create POST and DELETE. A HEAD and the receipt (the
+   * PATCH at the final offset) wait HEAD_AND_RECEIPT_TIMEOUT_MS instead:
+   * Forge answers either only after its own call to Core.
+   */
   tusPostTimeoutMs?: number;
   /** Stall watchdog per tus chunk PATCH: aborts after this long with NO upload progress (not an absolute deadline). */
   tusChunkTimeoutMs?: number;
@@ -53,6 +58,21 @@ export interface SparkVaultMobileConfig {
    * upload, and every upload when this is unset, streams over XHR.
    */
   backgroundUploader?: MobileBackgroundUploader;
+  /**
+   * Whether the device has a network path right now (an app wires it to its
+   * OS network signal). Read when an upload request got no answer: while it
+   * answers false the upload waits for `onOnline` instead of spending its
+   * retries, then asks Forge where the session stands. Only a definite
+   * "offline" should answer false; a path that may come up is online. Given
+   * together with `onOnline`, or not at all.
+   */
+  isOnline?: () => boolean;
+  /**
+   * Subscribe to the network coming back; returns the unsubscribe. The pair
+   * of `isOnline`. A wait it ends is otherwise ended only by the upload's
+   * `abortSignal`.
+   */
+  onOnline?: (listener: () => void) => () => void;
   logger?: Partial<SparkVaultLogger>;
   /**
    * Host allowlist for the backend-issued Forge transfer URLs the SDK sends an
@@ -62,6 +82,12 @@ export interface SparkVaultMobileConfig {
   allowedDownloadHostPatterns?: RegExp[];
 }
 
+/** The device's network signal, as the upload's offline wait reads it (`isOnline` with `onOnline`). */
+export interface MobileConnectivity {
+  isOnline(): boolean;
+  onOnline(listener: () => void): () => void;
+}
+
 export interface ResolvedMobileConfig {
   tokenStorage: TokenStorageAdapter;
   apiBaseUrl: string;
@@ -78,10 +104,23 @@ export interface ResolvedMobileConfig {
   fileDownloader?: MobileFileDownloader;
   backgroundTransfer?: MobileBackgroundTransfer;
   backgroundUploader?: MobileBackgroundUploader;
+  connectivity?: MobileConnectivity;
   logger: SparkVaultLogger;
   allowedDownloadHostPatterns: RegExp[];
 }
 
+/** The `isOnline` / `onOnline` pair as one signal, or none: one without the other cannot wait for the network. */
+function resolveConnectivity(config: SparkVaultMobileConfig): MobileConnectivity | undefined {
+  const { isOnline, onOnline } = config;
+  if (isOnline === undefined && onOnline === undefined) return undefined;
+  if (typeof isOnline !== 'function' || typeof onOnline !== 'function') {
+    throw new SparkVaultValidationError('isOnline and onOnline are given together, as functions', {
+      field: typeof isOnline === 'function' ? 'onOnline' : 'isOnline',
+    });
+  }
+  return { isOnline, onOnline };
+}
+
 function normalizeBaseUrl(url: string, field: string): string {
   if (!url || typeof url !== 'string') {
     throw new SparkVaultValidationError(`${field} must be a non-empty string`, { field });
@@ -157,6 +196,7 @@ export function resolveMobileConfig(config: SparkVaultMobileConfig): ResolvedMob
     fileDownloader: config.fileDownloader,
     backgroundTransfer: config.backgroundTransfer,
     backgroundUploader: config.backgroundUploader,
+    connectivity: resolveConnectivity(config),
     logger: { ...noopLogger, ...config.logger },
     allowedDownloadHostPatterns: config.allowedDownloadHostPatterns ?? [...SPARKVAULT_OWNED_HOST_PATTERNS],
   };

package/src/errors.ts

@@ -181,28 +181,62 @@ export class TusUploadError extends SparkVaultMobileError {
   readonly cause: Error | null;
   readonly filename: string | null;
   readonly fileSize: number | null;
-  readonly phase: 'create' | 'upload' | 'network' | 'timeout' | 'cancelled' | 'stalled' | 'unknown';
+  /**
+   * Where the upload stopped: `finalize` is after the transfer, when every
+   * byte was on Forge but the ingot was not confirmed published.
+   */
+  readonly phase: 'create' | 'upload' | 'finalize' | 'network' | 'timeout' | 'cancelled' | 'stalled' | 'unknown';
   /**
    * True when Forge no longer has the session (it answered a status
-   * `isSessionGone` recognises: expired or terminated), or the session
-   * cannot carry this file. The persisted session is worthless, so the
-   * caller starts a fresh upload instead of retrying it.
+   * `isSessionGone` recognises, or the expiry it named has passed), or the
+   * session cannot carry this file. The persisted session is worthless, so
+   * the caller starts a fresh upload instead of retrying it.
    */
   readonly sessionLost: boolean;
+  /**
+   * The `Retry-After` of the answer that ended the upload, in ms: the
+   * earliest a next attempt can expect another answer. Null when that answer
+   * named none, or no answer arrived.
+   */
+  readonly retryAfterMs: number | null;
+  /**
+   * True when every byte is on Forge and the session is intact but the ingot
+   * was not confirmed published: the vault did not read it `active` within
+   * the activation poll budget, or Forge was still saving the file at the
+   * upload's idle limit (code `upload_received_publishing`; it finishes
+   * without this device). The caller retries later by resuming the session
+   * it persisted, which asks Forge for the receipt again and sends no bytes.
+   */
+  readonly retryLater: boolean;
+  /**
+   * The code Core ended this upload with, as Forge named it. With code
+   * `upload_refused` a final refusal (`UPLOAD_POOL_FULL`: the account's
+   * storage pool cannot take it; `UPLOAD_SUPERSEDED`: a later upload replaced
+   * it), whose message is Core's own sentence and which no new upload of the
+   * same file remedies; with `sessionLost` any other code (`NOT_FOUND`: the
+   * file the upload was for is gone; `UPLOAD_PROTOCOL_RETIRED`; a 412's),
+   * which a fresh upload starts over from. Null when the answer named none.
+   */
+  readonly coreCode: string | null;
 
   constructor(
     message: string,
     options: {
       cause?: Error | null;
       httpStatus?: number | null;
+      /** The error's code when it names an outcome of its own; otherwise the HTTP status, or `tus_upload_error`. */
+      code?: string;
       filename?: string | null;
       fileSize?: number | null;
       phase?: TusUploadError['phase'];
       sessionLost?: boolean;
+      retryAfterMs?: number | null;
+      retryLater?: boolean;
+      coreCode?: string | null;
     } = {}
   ) {
     super(message, {
-      code: options.httpStatus ?? 'tus_upload_error',
+      code: options.code ?? options.httpStatus ?? 'tus_upload_error',
       statusCode: options.httpStatus ?? undefined,
     });
     this.name = 'TusUploadError';
@@ -211,6 +245,9 @@ export class TusUploadError extends SparkVaultMobileError {
     this.fileSize = options.fileSize ?? null;
     this.phase = options.phase ?? 'unknown';
     this.sessionLost = options.sessionLost ?? false;
+    this.retryAfterMs = options.retryAfterMs ?? null;
+    this.retryLater = options.retryLater ?? false;
+    this.coreCode = options.coreCode ?? null;
     Object.setPrototypeOf(this, TusUploadError.prototype);
   }
 

package/src/index.ts

@@ -3,6 +3,7 @@ export {
   createSparkVaultMobileClient,
 } from './client.js';
 export type {
+  MobileConnectivity,
   SparkVaultMobileConfig,
   ResolvedMobileConfig,
 } from './config.js';
@@ -92,6 +93,7 @@ export {
   MobileUsersClient,
 } from './users.js';
 export {
+  isSessionExpired,
   isSessionGone,
   MobileTusUploader,
   parseForgeUrl,

package/src/ingots.ts

@@ -7,9 +7,10 @@ import {
   isRetryableDownloadError,
   SparkVaultMobileError,
   SparkVaultValidationError,
+  TusUploadError,
 } from './errors.js';
 import type { MobileHttpClient } from './http.js';
-import { allowsHost, MobileTusUploader } from './tus.js';
+import { allowsHost, MobileTusUploader, type TusSessionProbe } from './tus.js';
 import type {
   DebugLogger,
   HashCheckResponse,
@@ -97,6 +98,12 @@ export interface UploadFromUriOptions extends UploadOptions {
    * attempt or a relaunch instead of re-sending bytes Forge already holds.
    */
   onSessionCreated?: (session: IngotUploadSession) => void;
+  /**
+   * Invoked whenever the session's expiry changes (see
+   * `TusUploadFromUriOptions.onSessionExpiry`): a caller that persists the
+   * session keeps its `expiresAt` current with it.
+   */
+  onSessionExpiry?: (expiresAt: number | null) => void;
   /** See `UploadTransport`; default `foreground`. */
   transport?: UploadTransport;
   /** Network policy for the OS transfer engine; see `UploadTransferPolicy`. Default: both allowed. */
@@ -127,8 +134,14 @@ export interface ResumeUploadOptions {
   fileUri: string;
   fileSize: number;
   name: string;
-  /** The persisted tus session handed to `onSessionCreated`. */
-  session: { uploadUrl: string; istk: string };
+  /**
+   * The persisted tus session handed to `onSessionCreated`, with the expiry
+   * the caller keeps for it (`onSessionExpiry`): a session past it is
+   * refused as `sessionLost` before any request.
+   */
+  session: { uploadUrl: string; istk: string; expiresAt?: number | null };
+  /** See `UploadFromUriOptions.onSessionExpiry`. */
+  onSessionExpiry?: (expiresAt: number | null) => void;
   /** See `UploadTransport`; default `foreground`. */
   transport?: UploadTransport;
   /** Network policy for the OS transfer engine; see `UploadTransferPolicy`. Default: both allowed. */
@@ -343,6 +356,7 @@ export class MobileIngotsClient {
       filename: name,
       forgeUrl: init.forgeUrl,
       onSessionCreated: session => options.onSessionCreated?.({ ...session, ingotId: init.ingotId, created }),
+      onSessionExpiry: options.onSessionExpiry,
       transport: options.transport,
       transferPolicy: options.transferPolicy,
       onProgress: options.onProgress,
@@ -351,7 +365,11 @@ export class MobileIngotsClient {
       debug: options.debug,
     });
 
-    const ingot = await this.verifyIngotActive(options.vaultId, init.ingotId, options.vat, options.debug);
+    const ingot = await this.verifyIngotActive(
+      { vaultId: options.vaultId, ingotId: init.ingotId, vat: options.vat },
+      { filename: name, fileSize: options.fileSize },
+      options.debug
+    );
 
     return {
       ingot_id: init.ingotId,
@@ -373,10 +391,10 @@ export class MobileIngotsClient {
    * 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`. A session `uploadUrl` that is not an upload session
-   * on an allowed transfer host is refused (SparkVaultValidationError) before
-   * the ISTK or a byte is sent anywhere.
+   * session (its expiry passed, or it was terminated); the caller drops it
+   * and starts over with `uploadFromUri`. A session `uploadUrl` that is not
+   * an upload session on an allowed transfer host is refused
+   * (SparkVaultValidationError) before the ISTK or a byte is sent anywhere.
    */
   async resumeUpload(options: ResumeUploadOptions): Promise<UploadResult> {
     validateVaultId(options.vaultId);
@@ -390,6 +408,7 @@ export class MobileIngotsClient {
       fileSize: options.fileSize,
       filename: options.name,
       resume: options.session,
+      onSessionExpiry: options.onSessionExpiry,
       transport: options.transport,
       transferPolicy: options.transferPolicy,
       onProgress: options.onProgress,
@@ -398,7 +417,11 @@ export class MobileIngotsClient {
       debug: options.debug,
     });
 
-    const ingot = await this.verifyIngotActive(options.vaultId, options.ingotId, options.vat, options.debug);
+    const ingot = await this.verifyIngotActive(
+      { vaultId: options.vaultId, ingotId: options.ingotId, vat: options.vat },
+      { filename: options.name, fileSize: options.fileSize },
+      options.debug
+    );
 
     return {
       ingot_id: options.ingotId,
@@ -418,9 +441,7 @@ export class MobileIngotsClient {
    * An `uploadUrl` that is not an upload session on an allowed transfer host
    * is refused (SparkVaultValidationError) before the ISTK is sent anywhere.
    */
-  probeUploadSession(
-    session: { uploadUrl: string; istk: string }
-  ): Promise<{ offset: number; length: number; chunkSize: number } | null> {
+  probeUploadSession(session: { uploadUrl: string; istk: string }): Promise<TusSessionProbe | null> {
     return this.tus.probeSession(session);
   }
 
@@ -512,6 +533,7 @@ export class MobileIngotsClient {
       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 }),
+      onSessionExpiry: options.onSessionExpiry,
       transport: options.transport,
       transferPolicy: options.transferPolicy,
       onProgress,
@@ -520,7 +542,11 @@ export class MobileIngotsClient {
       debug,
     });
 
-    const ingot = await this.verifyIngotActive(vaultId, response.data.ingot_id, vat, debug);
+    const ingot = await this.verifyIngotActive(
+      { vaultId, ingotId: response.data.ingot_id, vat },
+      { filename: name, fileSize },
+      debug
+    );
 
     return {
       ingot_id: response.data.ingot_id,
@@ -866,22 +892,24 @@ export class MobileIngotsClient {
   }
 
   /**
-   * Wait for a just-uploaded ingot to finish server-side finalization.
+   * Read a just-uploaded ingot until the server reports it `active`.
    *
-   * The bytes are already fully uploaded and the ingot record exists before
-   * this runs, so this NEVER re-creates or re-uploads anything - it only polls
-   * status. A still-`uploading` ingot after the poll budget
-   * is returned as success, not thrown: the transport completed and the ingot
-   * exists, so treating it as a failure would make the caller re-run the whole
-   * upload and mint a DUPLICATE ingot (re-streaming the entire file and
-   * double-billing storage). Finalization completes asynchronously server-side.
+   * The upload resolved on Forge's receipt (a 2xx to the PATCH at the final
+   * offset, which Forge answers only once the ingot is published), so a read
+   * that is not `active` yet is a read lagging that publication, which the
+   * poll waits out. It never re-creates or re-uploads anything. A row still
+   * not `active` past the poll budget is never reported as a success: it
+   * throws a `TusUploadError` whose `retryLater` is set (every byte is
+   * received, publication is unconfirmed), so the caller resumes the session
+   * it persisted later, which asks Forge for the receipt again and sends no
+   * bytes, rather than recording a backup the vault may not hold.
    */
   private async verifyIngotActive(
-    vaultId: string,
-    ingotId: string,
-    vat: string,
+    ingotRef: { vaultId: string; ingotId: string; vat: string },
+    upload: { filename: string; fileSize: number },
     debug?: DebugLogger
   ): Promise<Ingot> {
+    const { vaultId, ingotId, vat } = ingotRef;
     const deadline = Date.now() + MobileIngotsClient.INGOT_STATUS_POLL_BUDGET_MS;
     let delay = MobileIngotsClient.INGOT_STATUS_POLL_INITIAL_MS;
     let ingot = await this.get(vaultId, ingotId, vat);
@@ -891,9 +919,12 @@ export class MobileIngotsClient {
       if (remaining <= 0) {
         debug?.log(
           `Ingot ${ingotId} still '${ingot.status}' after ${MobileIngotsClient.INGOT_STATUS_POLL_BUDGET_MS}ms; ` +
-            'upload transport is complete, finalizing asynchronously'
+            'the upload is received and will be confirmed on a later attempt'
+        );
+        throw new TusUploadError(
+          `Upload received; the vault has not confirmed ingot ${ingotId} published yet (status ${ingot.status ?? 'unknown'})`,
+          { ...upload, phase: 'finalize', retryLater: true }
         );
-        return ingot;
       }
 
       await new Promise(resolve => setTimeout(resolve, Math.min(delay, remaining)));