@sparkvault/sdk-mobile 5.2.1 → 5.2.3

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,
     };
   }
 

package/src/notify.test-d.ts

@@ -0,0 +1,42 @@
+/**
+ * Notify wire-contract assertions — COMPILE-TIME ONLY.
+ *
+ * `NotificationRow` has no runtime, so a unit test can never catch it drifting
+ * from the server: the transpiler strips it and every assertion passes. This file
+ * is the gate instead — `tsc --noEmit` (`pnpm typecheck`, which CI runs on every
+ * push and again on every SDK publish) fails the moment the published row stops
+ * matching what `apps/api` actually emits.
+ *
+ * It is deliberately NOT a `*.test.ts`: that suffix is excluded from `tsconfig`,
+ * which would put these assertions exactly where the compiler cannot see them.
+ *
+ * The row shape is shared verbatim with `@sparkvault/sdk-js`, whose own contract
+ * file asserts the same three members — both must move together, and the mirrored
+ * server source is `apps/api/src/notify/inbox.js` (`projectRow`).
+ */
+
+import type { NotificationRow } from './notify.js';
+
+/** Fails to compile unless `T` resolves to exactly `true`. */
+type Assert<T extends true> = T;
+
+/**
+ * Invariant type equality — `A` and `B` must be the SAME type, not merely mutually
+ * assignable. Assignability would accept an optional member where the wire always
+ * carries one, which is the precise drift these assertions exist to catch.
+ */
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+  ? true
+  : false;
+
+export type NotifyWireContract = [
+  // `recalled` is `Boolean(row.recalled_at)`, so it is always on the wire: typing
+  // it optional would let the app skip the "no longer available" branch and fall
+  // through to a reveal that opens nothing.
+  Assert<Equals<NotificationRow['recalled'], boolean>>,
+  // `locked` is `!recalled && Boolean(row.sparklink_code)` — always present.
+  Assert<Equals<NotificationRow['locked'], boolean>>,
+  // The pointer is withheld on a recalled row and absent on a cleartext one, so
+  // it is optional in both directions and must be guarded before use.
+  Assert<Equals<NotificationRow['sparklink_code'], string | undefined>>,
+];

package/src/notify.ts

@@ -31,13 +31,26 @@ export interface NotificationRow {
   read_at: number | null;
   archived_at: number | null;
   /**
-   * The grant to open. Present only for a SEALED (secure) send — a cleartext send
-   * delivers its content inline in the channel and mints no grant, so its row has
-   * no pointer. Guard before building a URL from it.
+   * The grant to open. Present only while a live reveal stands behind it — a
+   * SEALED (secure) send that has not been recalled. A cleartext send delivers its
+   * content inline in the channel and mints no grant; a recalled row's grant is
+   * revoked and the pointer is withheld rather than echoed. Guard before building
+   * a URL from it.
    */
   sparklink_code?: string;
-  /** True only when there is a secure part to reveal (i.e. `sparklink_code` is set). */
+  /**
+   * True only when there is a secure part left to reveal — exactly when
+   * `sparklink_code` is present. `false` does NOT mean "cleartext row": a recalled
+   * row is unlocked too, with nothing behind it. Branch on `recalled` before
+   * treating an unlocked row as plain text.
+   */
   locked: boolean;
+  /**
+   * The sender took this notification back. The grant is revoked and
+   * `sparklink_code` is withheld, so render "no longer available" rather than a
+   * tap-to-reveal that opens nothing.
+   */
+  recalled: boolean;
   thread_id?: string;
 }