@sparkvault/sdk-mobile 6.0.2 → 7.0.1

package/dist/tus.d.ts

@@ -13,27 +13,37 @@ export interface ParsedForgeUrl {
  *
  * A resume that cannot use the session throws a `TusUploadError` whose
  * `sessionLost` is true exactly when the session is worthless for this file
- * and the caller should drop it and start fresh: Forge no longer has it
+ * and the caller should drop it and start fresh: the expiry the caller holds
+ * for it has passed (refused before any request), Forge no longer has it
  * (404/410), or its `Upload-Length` is not this file's size (it belongs to a
- * different file). A transient HEAD failure (5xx, timeout) is NOT
- * `sessionLost`; the session is intact and the same resume can be retried.
+ * different file). A HEAD that keeps failing transiently (5xx, timeouts) past
+ * the upload's retry budget is NOT `sessionLost`; the session is intact and
+ * the same resume can be retried.
  */
 export interface TusResumeSession {
     uploadUrl: string;
     /** The session's ISTK. Falls back to the one in `forgeUrl` when omitted. */
     istk?: string;
+    /**
+     * The session's expiry as the caller holds it (`expiresAt` from
+     * `onSessionCreated`, kept current through `onSessionExpiry`). Null or
+     * omitted is unknown, and Forge's HEAD decides.
+     */
+    expiresAt?: number | null;
 }
 /** Where a tus session stands server-side, as reported by HEAD. */
 export interface TusSessionProbe {
     offset: number;
     length: number;
     chunkSize: number;
+    /** When the session lapses (epoch ms, Forge's `Upload-Expires`), or null when the HEAD named none. */
+    expiresAt: number | null;
 }
 export interface TusUploadFromUriOptions {
     fileUri: string;
     fileSize: number;
+    /** Names the file in error context and debug logs; Forge never receives it. */
     filename: string;
-    contentType: string;
     /**
      * Forge tus endpoint plus ISTK (`forge_url` from the ingot create).
      * Required to create a session; on resume it only supplies the ISTK when
@@ -48,6 +58,17 @@ export interface TusUploadFromUriOptions {
      * relaunch. Not invoked on resume. A throw here fails the upload.
      */
     onSessionCreated?: (session: TusSessionInfo) => void;
+    /**
+     * Invoked whenever the session's expiry, as its latest answer named it,
+     * changes: Forge slides it forward with every committed chunk and names it
+     * on its answers (`Upload-Expires`). It is null (unknown) after an answer
+     * that named none, and from the hand-off of a request the OS carries on
+     * without JS (the transfer engine's range, the single-chunk background
+     * PATCH): either may have moved it unread. A caller that persists the
+     * session keeps its `expiresAt` current with this, so a session it judges
+     * expired (`isSessionExpired`) really is. A throw here fails the upload.
+     */
+    onSessionExpiry?: (expiresAt: number | null) => void;
     /**
      * `background` rides the best suspension-proof engine the app provides:
      * the OS transfer engine (`backgroundTransfer`) for the whole remaining
@@ -75,7 +96,18 @@ export interface TusUploadFromUriOptions {
     abortBehavior?: UploadAbortBehavior;
     debug?: DebugLogger;
 }
-export declare function parseForgeUrl(forgeUrl: string): ParsedForgeUrl;
+/**
+ * Read a Core-issued Forge upload URL with the platform's transfer URL rule
+ * (app-sdk/forge-url.js): https, no credentials or fragment, the encrypt
+ * endpoint on an allowed host, and one base64url ISTK.
+ *
+ * @param allowedHostPatterns - Hosts trusted with the upload; the platform's
+ *   own hosts by default (a configured SDK passes `allowedDownloadHostPatterns`).
+ * @throws SparkVaultValidationError when the URL is refused.
+ */
+export declare function parseForgeUrl(forgeUrl: string, allowedHostPatterns?: readonly RegExp[]): ParsedForgeUrl;
+/** The forge-url rule's host check over a configured list of host patterns. */
+export declare function allowsHost(allowedHostPatterns: readonly RegExp[]): (hostname: string) => boolean;
 /** File context carried on every `TusUploadError` a request throws. */
 interface TusErrorContext {
     filename?: string;
@@ -84,16 +116,42 @@ interface TusErrorContext {
 /**
  * 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.
+ * fresh upload instead of retrying it. It is the transfer policy's GONE
+ * verdict, so every request that can meet a dead session (HEAD, a PATCH, the
+ * OS engine's PATCHes, DELETE) and the app's own session bookkeeping agree on
+ * what "gone" is.
  */
 export declare function isSessionGone(status: number): boolean;
+/**
+ * How far past the expiry Forge named a session still counts as live: the
+ * allowance for a device clock running ahead of Forge's. `Upload-Expires` is
+ * read off Forge's clock and compared with the device's; a phone on automatic
+ * time is within seconds of Forge, one set by hand is typically minutes fast.
+ * The two mistakes cost very differently: a live session judged expired is
+ * dropped and its file sent again from byte 0, an expired one judged live
+ * costs a single HEAD (Forge answers 410, `sessionLost`). So the margin errs
+ * long, and stays small against the 72 h idle window a session lives from its
+ * last commit (`@sparkvault/app-sdk/upload-expiry`): a session the clock says
+ * lapsed hours ago is still dropped without a request.
+ */
+export declare const SESSION_EXPIRY_CLOCK_MARGIN_MS: number;
+/**
+ * True when the expiry Forge named for a session (`TusSessionInfo.expiresAt`,
+ * kept current through `onSessionExpiry`) is past by more than the clock
+ * margin: Forge refuses every request to a session past its expiry, so a
+ * caller drops it without asking. Within the margin the session is live for
+ * all the device clock can tell, and Forge's HEAD decides. An unknown expiry
+ * (null) never has passed: only Forge's HEAD can say.
+ */
+export declare function isSessionExpired(expiresAt: number | null | undefined, now?: number): boolean;
 /**
  * Translate what the OS transfer adapter reports into the SDK's one error
  * 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
- * status `isSessionGone` recognises marks the session lost exactly as HEAD
- * would, and any other status keeps its number for the caller's own policy
+ * through untouched: the refusal Core decided is `upload_refused` in Core's
+ * words as on the XHR path, a 402 becomes the gate error the XHR path
+ * throws, a 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
@@ -106,16 +164,137 @@ export declare function mapBackgroundTransferError(err: unknown, context?: TusEr
 export declare class MobileTusUploader {
     private readonly config;
     constructor(config: ResolvedMobileConfig);
+    /**
+     * Upload a file over tus: create the session (or resume a kept one), send
+     * the bytes Forge does not hold, and resolve once Forge has confirmed the
+     * ingot published.
+     *
+     * Every answer is read through the platform's transfer policy
+     * (`@sparkvault/app-sdk/transfer-retry`), and one budget per call bounds
+     * every retry, the create's included: a request that got no answer, 408,
+     * 425, 429, a 5xx or a lease-held 409 waits its backoff (never shorter than
+     * `Retry-After`), then asks Forge where the session stands (HEAD) and sends
+     * from there; a 409 carrying `Upload-Offset` continues from that offset at
+     * once; a receipt Forge defers (503 with `Retry-After`) is asked again,
+     * each time after a longer backoff, without spending a failure until the
+     * idle limit ends the upload as `upload_received_publishing`
+     * (`retryLater`); a gone session is `sessionLost` (`coreCode` naming the
+     * code Core ended it with, when the answer named one); a final refusal of
+     * Core's (`UPLOAD_POOL_FULL`, `UPLOAD_SUPERSEDED`) is `upload_refused` in
+     * Core's words (`coreCode`); any other 4xx ends the upload with the
+     * server's answer. No chunk is ever sent at an offset the server did not just name. While the device is offline (`isOnline`), a request that got
+     * no answer spends nothing: the upload waits for the network. The OS
+     * transfer engine's range is the exception: the engine chains its own
+     * requests, and its failure ends the call for the caller's own retry.
+     */
     uploadFromUri(options: TusUploadFromUriOptions): Promise<void>;
+    /**
+     * Open the upload's session. A create the transfer policy calls RETRY (no
+     * answer, 408, 425, 429, a 5xx) is sent again under the upload's budget,
+     * its backoff never shorter than `Retry-After`: Forge refuses such a create
+     * before it claims the token, or hands the claim back on a transient
+     * key-service failure (503), so the same ISTK opens the session on a later
+     * attempt. Every other answer is final and never a lost session, a 401
+     * included: the token was already used, by an earlier create whose answer
+     * was lost, and no Location survives to continue that session from. No
+     * session URL exists yet to spread the retries by, and the ISTK never feeds
+     * one, so they spread by a key of the endpoint (`transferJitterKey`).
+     */
+    private createSession;
+    /**
+     * Where a kept session stands, asked of Forge (HEAD) under the upload's
+     * budget, so resume never re-sends bytes the server holds: it is the only
+     * way to learn what a background transfer delivered after the process was
+     * killed, and what a failed attempt left behind. A HEAD that gets no
+     * answer or a transient one is asked again after its backoff; a gone
+     * session is `sessionLost`, so the caller drops it and creates a fresh one
+     * rather than retrying a dead URL. A session is bound to one file: a length that
+     * is not this file's means the persisted session belongs to another file
+     * (or this file changed), and PATCHing into it would corrupt the ingot.
+     * That makes it as worthless as a gone one: `sessionLost` too.
+     */
+    private readResumePoint;
+    /**
+     * Ask Forge once where the session stands (tus HEAD): the probe on a 2xx,
+     * or the failure its answer amounts to. Forge re-drives a received
+     * upload's publication on its HEAD and answers the full offset whatever the
+     * re-drive came to, so an offset at the total proves receipt only: the
+     * receipt PATCH (`confirmReceipt`) is what says published.
+     */
+    private headSession;
+    /**
+     * Send the chunk that starts at `offset`. Answers where the upload stands
+     * next: past the chunk on its 2xx, which for the last chunk is also the
+     * publication receipt (Forge answers it only once the ingot is published),
+     * or wherever the server says after a failure.
+     */
+    private sendChunkAt;
+    /** PATCH the chunk at `offset` on the transport the upload rides, resolving with Forge's answer. */
+    private sendChunk;
+    /**
+     * Where the upload stands after a failed chunk PATCH, in the server's
+     * words: a 409's own `Upload-Offset` at once, otherwise the session's HEAD
+     * after the backoff, the HEAD itself retried the same way out of the same
+     * budget. A PATCH whose answer was lost may have landed, and one sent at a
+     * stale offset is refused, so no chunk is ever sent again at an offset the
+     * server did not just name.
+     */
+    private positionAfterFailure;
+    /**
+     * Continue from the offset a 409 named, at once and without a HEAD: the
+     * server just said where the session stands. Past what this upload sent,
+     * the server holds more than it knew, which is progress; anywhere else the
+     * answer contradicts the request, so it spends the budget like any failure
+     * and repeating it ends the upload.
+     */
+    private resyncedPosition;
+    /**
+     * Every byte is on the server but publication is unconfirmed: the final
+     * chunk's answer was lost or deferred, or a HEAD's offset proved receipt
+     * only. A zero-length PATCH at the final offset re-drives publication if it
+     * did not finish (a transient Core or billing failure after the last chunk)
+     * and answers 204 once the ingot is published, which is the receipt every
+     * upload resolves on. While another request finalizes it answers 409 with
+     * `Retry-After`, asked again as a failure; while the publication is
+     * deferred, 503 with `Retry-After`, asked again, each time after a longer
+     * backoff, without spending a failure until the idle limit ends the upload
+     * as `upload_received_publishing` (`retryLater`); a 503 naming no
+     * `Retry-After` is no deferral of Forge's, asked again as a failure. A 409
+     * naming an earlier offset means bytes are missing, and the upload
+     * continues from there. Forge answers it only after its own call to Core,
+     * so it waits `HEAD_AND_RECEIPT_TIMEOUT_MS`, as a HEAD does.
+     */
+    private confirmReceipt;
+    /**
+     * Wait out the backoff of a failed request, spending a retry of the
+     * upload's budget, or of a deferred receipt, spending none for as long as
+     * the idle limit allows; never shorter than the answer's `Retry-After`.
+     * Throws the failure no retry follows (a gone session, the server's
+     * verdict), and the last one, or the deferral, once the budget is spent. A
+     * request that got no answer while the device is offline spends nothing:
+     * the upload waits for the network (or the caller's abort), the idle clock
+     * starts over when it is back, and the next request asks again at once.
+     */
+    private waitToRetry;
     /**
      * Where a persisted session stands, or `null` when Forge no longer has it
-     * (404/410 — expired or terminated). Any other failure throws with
-     * `sessionLost` false (a 5xx or timeout says nothing about the session).
-     * The probe reports the session's own length; whether that length is the
-     * caller's file is for the caller (or `uploadFromUri`'s resume, which
-     * throws `sessionLost` on a mismatch) to judge. Lets a caller reconcile
-     * sessions on relaunch (a completed one just needs its ingot verified; a
-     * lost one needs a fresh create) before spending an upload slot on it.
+     * (404/410 — expired or terminated), from one HEAD and no retry. Any other
+     * failure throws with `sessionLost` false (a 5xx or a timeout says nothing
+     * against the session), carrying the answer's `retryAfterMs`; a final
+     * refusal Core decided on the HEAD's re-drive (`UPLOAD_POOL_FULL` or
+     * `UPLOAD_SUPERSEDED` in `X-Upload-Refusal`) throws as `upload_refused`,
+     * which no fresh create remedies, and any other code Core ended the session
+     * with reads as gone (null). An offset at
+     * the session's length proves every byte received, not published: a
+     * resume of it sends the receipt. The probe reports the session's own length;
+     * whether that length is the caller's file is for the caller (or
+     * `uploadFromUri`'s resume, which throws `sessionLost` on a mismatch) to
+     * judge. Lets a caller reconcile sessions on relaunch (a completed one just
+     * needs its ingot verified; a lost one needs a fresh create) before
+     * spending an upload slot on it.
+     *
+     * @throws SparkVaultValidationError, before any request, when `uploadUrl`
+     *   is not an upload session on an allowed transfer host.
      */
     probeSession(session: {
         uploadUrl: string;
@@ -141,6 +320,9 @@ export declare class MobileTusUploader {
      * 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.
+     *
+     * @throws SparkVaultValidationError, before any request, when `uploadUrl`
+     *   is not an upload session on an allowed transfer host.
      */
     terminateSession(session: {
         uploadUrl: string;