@hostr/upload 0.1.0

package/dist/react-native/background-plan.d.ts

@@ -0,0 +1,57 @@
+/** Pure planner for the iOS background transport. Mirrors `UploadEngine`'s
+ *  `reconcile()` philosophy exactly (see `../core/engine.ts`): an md5-vs-etag
+ *  match is what promotes a part to "done" — never bookkeeping (a staged
+ *  record, a completion callback) taken on its own. This function does no
+ *  I/O; it only decides, given four facts —
+ *    - `session`: the persisted record, whose `done` map is trusted
+ *      (verified when written, by the engine or by a background completion
+ *      callback that already checked md5-vs-etag itself);
+ *    - `remote`: what R2 actually holds right now (`GET /v1/uploads/:id`);
+ *    - `staged`: part slices currently sitting on disk, each carrying the
+ *      md5 computed at staging time and the process epoch that staged it;
+ *    - `currentEpoch`: this process's own epoch, so a staged record left by
+ *      a process that no longer exists can be told apart from one this
+ *      process itself just wrote —
+ *  what the executor (`background.ts`) should do next: which parts to slice
+ *  and hand to the OS, which staged files are safe to delete, and which
+ *  landed parts can be adopted as done without re-uploading.
+ *
+ *  Deliberate asymmetry with `UploadEngine.reconcile`: that function actively
+ *  invalidates `session.done` entries R2 no longer backs (see its comment).
+ *  This planner never does — `session.done` is trusted outright, full stop,
+ *  everywhere below. A background completion callback and the engine's own
+ *  writes are the only ways to set it, and both already checked md5-vs-etag
+ *  before doing so, so re-checking here on every reconcile would just be
+ *  spending a file read + hash for no new information. The cost of that
+ *  trust: if a `done` entry were ever wrong (storage corruption, manual
+ *  tampering), this planner would not catch it — the composite-etag check in
+ *  `background.ts`'s completion path would, but only at the very end, not on
+ *  the reconcile that produced the bad entry. */
+import type { SessionRecord } from '../core/session.js';
+import type { RemotePart } from '../api/client.js';
+export type StagedPart = {
+    partNumber: number;
+    fileUri: string;
+    md5: string;
+    /** The staging process's epoch (see `currentEpoch` below) at the moment
+     *  this part was staged. A force-kill cancels the OS's in-flight
+     *  transfers, so a staged record surviving from a *different* (and
+     *  therefore dead) epoch means no transfer for it is actually running
+     *  anymore, however untouched the record looks. */
+    launchEpoch: string;
+};
+export type BackgroundWork = {
+    /** Parts to slice to disk and hand to the OS as a new background upload task. */
+    toStage: number[];
+    /** Staged file URIs whose parts have landed (or are already done) — safe to delete. */
+    toCleanup: string[];
+    /** partNumber -> md5, for remote parts whose etag matches a staged md5. */
+    adopt: Record<number, string>;
+};
+export declare function planBackgroundWork(i: {
+    session: SessionRecord;
+    remote: RemotePart[];
+    staged: StagedPart[];
+    /** This process's own epoch — see `StagedPart.launchEpoch`. */
+    currentEpoch: string;
+}): BackgroundWork;

package/dist/react-native/background.d.ts

@@ -0,0 +1,126 @@
+/** Thin executor over expo-file-system's iOS background upload tasks.
+ *  Deliberately not unit-tested — everything that decides is
+ *  `planBackgroundWork` (pure, tested in `test/background-plan.test.ts`);
+ *  this file only does I/O and delegates every decision to it. Exercised
+ *  on-device via `apps/expo-playground` (see the checklist at the top of
+ *  its `App.tsx`).
+ *
+ *  The OS carries the parts once a background upload task is launched — it
+ *  keeps running (subject to the OS's own scheduling) even if the app is
+ *  backgrounded or the JS runtime is suspended. But a transfer can still die
+ *  two different ways, and this file recovers from both:
+ *    - a force-kill cancels the OS's transfers outright (documented iOS
+ *      behavior for `URLSessionUploadTask` background sessions with no
+ *      persisted `URLSession` delegate reattachment on our side) — the
+ *      process that launched them is simply gone, so `LAUNCH_EPOCH` (below)
+ *      is what `planBackgroundWork` uses to recognize their staged records
+ *      as dead and re-stage them;
+ *    - a transfer can also die *in-process* — a presign expiring while iOS
+ *      suspends rather than kills the app (a background URLSession task can
+ *      sit deferred for well over the entry token's window), or the OS
+ *      abandoning it during a long airplane-mode stretch — surfacing as a
+ *      non-2xx `uploadAsync()` result or a rejected one. Its staged record's
+ *      `launchEpoch` is still *this* process's live epoch, so the planner
+ *      alone can't tell it apart from one genuinely still in flight; the
+ *      completion handler below (`stagePart`) is what closes that gap, by
+ *      dropping the staged record itself the moment it sees the failure —
+ *      after that, the planner sees nothing staged for the part at all, the
+ *      same as a part that was never staged in the first place.
+ *  Either way, nothing here is treated as a fatal error: `reconcile()`
+ *  re-derives truth from `ListParts` (`GET /v1/uploads/:id`) every time, so
+ *  a lost or 403'd transfer really is simply re-staged with a fresh presign
+ *  on the next call. Completion callbacks attached to a task while the app
+ *  is alive are an optimization (mark done sooner, skip a network round
+ *  trip, clear a dead record sooner, and — when the part they verify is the
+ *  last one outstanding — trigger the completing reconcile automatically) —
+ *  never the only path to correctness.
+ *
+ *  `LAUNCH_EPOCH` is this process's boot id, generated once when this
+ *  module is first loaded. It's what lets `planBackgroundWork` tell a
+ *  staged-but-unlanded part apart from a *live* one: a staged record from a
+ *  process that has since force-killed and relaunched — a new epoch — no
+ *  longer describes a real OS transfer, however untouched the file and its
+ *  record look, and gets re-staged; a record from *this* epoch is left
+ *  alone because its OS task is presumably still in flight (or, if it isn't
+ *  anymore, its own completion handler is the one responsible for saying
+ *  so — see above). */
+import type { StateStore } from '../core/types.js';
+type BgFile = {
+    uri: string;
+    size: number;
+    modificationTime?: number;
+};
+/** Optional per-upload event sink, threaded from `startBackgroundUpload`
+ *  down to each part's OS task. Everything here is advisory-grade, exactly
+ *  like the completion handlers that fire it: events only flow while the JS
+ *  runtime is alive, and nothing that matters for correctness depends on
+ *  them — they exist so a foreground UI (`createUpload`'s `NativeUpload`
+ *  wrapper) can show progress and settle its `done` promise without
+ *  polling. */
+export type BackgroundObserver = {
+    /** OS task progress for one part (bytes sent so far of that part). */
+    onPartProgress?: (partNumber: number, bytesSent: number) => void;
+    /** A part's etag verified and recorded in `session.done`. */
+    onPartLanded?: (partNumber: number) => void;
+    /** A part's task failed or its landed bytes didn't verify; its staged
+     *  record was dropped and the part needs a re-stage (next reconcile). */
+    onPartFailed?: (partNumber: number) => void;
+    /** CompleteMultipartUpload succeeded and the composite etag verified. */
+    onComplete?: (info: {
+        assetId: string;
+        etag: string;
+        bytes: number;
+    }) => void;
+};
+/** Cancels every live OS task for one asset. Returns how many were told to
+ *  cancel — already-settled tasks are unaffected (their `cancel()` is a
+ *  documented no-op). */
+export declare function cancelBackgroundTasks(assetId: string): number;
+export declare function startBackgroundUpload(opts: {
+    endpoint: string;
+    uploadToken: string;
+    assetId: string;
+    file: BgFile;
+    store: StateStore;
+    onTokenExpired?: (assetId: string) => Promise<string>;
+    /** Called with the result of reconciles this module runs on its own — the
+     *  automatic pass triggered when the last outstanding part lands, which is
+     *  what finishes the multipart upload without a manual `reconcile()`. A
+     *  caller-driven `reconcile()` reports through its return value instead. */
+    onAutoReconcile?: (result: 'complete' | 'in-progress') => void;
+    observer?: BackgroundObserver;
+}): Promise<BackgroundHandle>;
+export type BackgroundHandle = {
+    /** One reconcile pass: adopt landed parts, re-stage what died, complete
+     *  when nothing remains. Safe to call any time; serialized per asset. */
+    reconcile(): Promise<'complete' | 'in-progress'>;
+    /** Cancels the live OS tasks (returns how many). Their staged records
+     *  self-clean as the cancellations settle; nothing else is touched, so a
+     *  later `reconcile()` resumes by re-staging what hadn't landed. */
+    pause(): number;
+    /** Cancels live tasks, aborts the multipart upload server-side (best
+     *  effort), and deletes all local state — staged files and records, the
+     *  session, the launch-recovery pointers. Not resumable. */
+    abort(): Promise<void>;
+    readonly assetId: string;
+    readonly partSize: number;
+    readonly expectedParts: number;
+    readonly declaredSize: number;
+    /** Part numbers verified so far, per the in-memory session record. */
+    donePartNumbers(): number[];
+};
+/** Call once on app launch (a `useEffect` with an empty dependency array is
+ *  the natural fit). Finds every fileId with background work outstanding —
+ *  from a previous `startBackgroundUpload` call, however long ago, possibly
+ *  a prior app install's session if storage survived — and reconciles each:
+ *  a force-kill mid-upload lands here with the OS having cancelled its
+ *  transfers, and `ListParts` (not any surviving OS session, and not
+ *  `launchEpoch` matches from the dead process) tells this function what
+ *  actually made it to R2 and what needs re-staging. No `onTokenExpired`
+ *  hook is available at this call site (the app hasn't picked a file or
+ *  shown UI yet); an expired upload token here is a benign no-op — the next
+ *  `startBackgroundUpload` for the same asset carries its own refresh. */
+export declare function reconcileOnLaunch(store: StateStore, opts: {
+    endpoint: string;
+}): Promise<void>;
+export {};

package/dist/react-native/fs.d.ts

@@ -0,0 +1,28 @@
+/** Lazily loads the modern `expo-file-system` File/Directory API — the
+ *  surface this package's RN adapter and background transport are built on:
+ *  `FileHandle` byte-window reads, `File.write(Uint8Array)` staging writes,
+ *  the native `md5` property, and `File.createUploadTask` background
+ *  transfers.
+ *
+ *  Minimum peer: expo-file-system 57 (Expo SDK 57), and deliberately no
+ *  fallback to the `expo-file-system/legacy` subpath this package used to
+ *  ride. The modern API only gained upload support (`UploadTask`,
+ *  `sessionType`) in v57 — on 54–56 the legacy subpath was the only option —
+ *  but keeping both paths alive would mean every change to `background.ts`
+ *  doubles the on-device test matrix (real iPhone, multi-GB files, force-kill
+ *  runs), for SDK versions no consumer of this package uses: the playground
+ *  is on 57 and Tinglebay isn't integrated yet. Older SDKs can pin an older
+ *  version of this package.
+ *
+ *  The import stays lazy (inside a function, not top-level) so this package
+ *  loads fine in Node tests where expo-file-system isn't installed — only
+ *  actually reading/staging/uploading in an RN runtime pulls it in. */
+export declare function loadFileSystem(): Promise<{
+    FileHandle: typeof import("expo-file-system").FileHandle;
+    UploadType: typeof import("expo-file-system").UploadType;
+    UploadTask: typeof import("expo-file-system").UploadTask;
+    Directory: typeof import("expo-file-system").Directory;
+    File: typeof import("expo-file-system").File;
+    Paths: typeof import("expo-file-system").Paths;
+    default: typeof import("expo-file-system");
+}>;

package/dist/react-native/index.d.ts

@@ -0,0 +1,69 @@
+/** React Native adapter. This is a subpath entry (`@hostr/upload/react-native`),
+ *  never re-exported from the package root — it pulls in a lazy
+ *  `expo-file-system` dependency (declared locally in `./expo-fs.d.ts`, not
+ *  installed as a real package here) that neither Node nor browser builds
+ *  should see.
+ *
+ *  There is ONE upload path on RN: staged parts + OS-carried native upload
+ *  tasks (`background.ts`), wrapped in the engine-shaped `Upload` surface by
+ *  `NativeUpload`. The browser-derived engine path (XHR transport, bytes
+ *  read into JS, pure-JS hashing) used to live here as "foreground mode" —
+ *  it was removed because every byte crossed the Hermes bridge two to three
+ *  times and got hashed in interpreted JS, capping throughput far below the
+ *  network, and because a native background-session task does everything it
+ *  did (progress callbacks, cancellation) while also surviving the app
+ *  being suspended. "Background" is not a mode anymore; it is a property
+ *  every RN upload has. */
+import type { StateStore } from '../core/types.js';
+import { NativeUpload } from './native-upload.js';
+export { NetworkError, ApiError } from '../api/client.js';
+export { IntegrityError } from '../core/engine.js';
+export type { CompleteInfo } from '../core/engine.js';
+export type { Progress } from '../core/events.js';
+/** Headless surface (no events, no `done` promise): launch, reconcile, and
+ *  recover uploads directly. `createUpload` below is this plus liveness;
+ *  `reconcileOnLaunch` is the mandatory app-launch recovery hook either
+ *  way. `planBackgroundWork`, the pure decision core, lives at
+ *  `./background-plan.ts` and is imported directly by its tests. */
+export { startBackgroundUpload, reconcileOnLaunch, cancelBackgroundTasks, type BackgroundHandle, type BackgroundObserver, } from './background.js';
+export { NativeUpload } from './native-upload.js';
+/** The engine-compatible public surface (`core/upload.ts`'s `Upload` is the
+ *  same pick over the engine class). `pause`/`abort` are synchronous here —
+ *  cancellation of OS tasks doesn't need awaiting — where the engine's are
+ *  async; callers that ignore the return value (all known ones) see no
+ *  difference. */
+export type Upload = Pick<NativeUpload, 'done' | 'state' | 'on' | 'start' | 'pause' | 'resume' | 'abort'>;
+/** Wraps an AsyncStorage-like backend (`@react-native-async-storage/async-storage`,
+ *  or any object with the same three methods) into a `StateStore`. RN has no
+ *  default persisted store the way the browser adapter defaults to
+ *  `localStorage` — the host app always supplies one. */
+export declare function asyncStorageStore(as: {
+    getItem(k: string): Promise<string | null>;
+    setItem(k: string, v: string): Promise<void>;
+    removeItem(k: string): Promise<void>;
+}): StateStore;
+export type CreateUploadOptions = {
+    endpoint: string;
+    uploadToken: string;
+    assetId: string;
+    /** `uri`/`size` (and optional `modificationTime`) as returned by
+     *  `expo-image-picker` / `expo-document-picker`. Identity for resume is
+     *  `uri:size:modificationTime`. */
+    file: {
+        uri: string;
+        size: number;
+        modificationTime?: number;
+    };
+    /** REQUIRED — RN has no default persisted store the way the browser
+     *  adapter defaults to `localStorage`. Wrap AsyncStorage (or an
+     *  equivalent) with `asyncStorageStore`. */
+    store: StateStore;
+    onTokenExpired?: (assetId: string) => Promise<string>;
+};
+/** One upload, engine-shaped: `start()`, listen to `progress`/`statechange`/
+ *  `error`, await `done`. Bytes move via OS background-session tasks, so the
+ *  transfer continues if the app is backgrounded mid-upload; a force-kill is
+ *  recovered by `reconcileOnLaunch` on the next launch, not by this object.
+ *  `async` only for signature stability — construction itself is cheap and
+ *  the real work starts at `start()`. */
+export declare function createUpload(opts: CreateUploadOptions): Promise<Upload>;

package/dist/react-native/native-upload.d.ts

@@ -0,0 +1,76 @@
+/** `Upload`-shaped wrapper over the staged-parts + OS-task transport
+ *  (`background.ts`). This is what makes RN's `createUpload` a single path:
+ *  the same `done`/`state`/`on`/`start`/`pause`/`resume`/`abort` surface the
+ *  browser/Node engine exposes, but with every byte moved natively — no
+ *  bytes through the JS interpreter, transfers that survive the app being
+ *  backgrounded, and completion driven by the all-parts-landed
+ *  auto-reconcile.
+ *
+ *  Division of labor: `background.ts` owns correctness (staging, ListParts
+ *  reconciliation, completion); this class owns *liveness* — UI events, the
+ *  `done` promise, and re-driving reconciles while the JS runtime is awake
+ *  so a failed part doesn't sit dead until the next app launch. Everything
+ *  here degrades to the background story when JS goes away: events stop,
+ *  the retry timer dies, and `reconcileOnLaunch`/`reconcile()` pick up the
+ *  truth later. That asymmetry is deliberate; nothing in this file may
+ *  become a correctness dependency.
+ *
+ *  Semantics that differ from the engine, on purpose:
+ *  - `pause()` cancels the live OS tasks. Their unlanded staged bytes are
+ *    discarded (records self-clean) and `resume()` re-stages what's still
+ *    missing — cheap now that staging is native. Landed parts are never
+ *    re-sent.
+ *  - No `checksum` option and no whole-file sha256: the composite etag
+ *    (verified part-by-part and again at complete) is the integrity check,
+ *    which is also all Mux ever provided. `CompleteInfo.sha256` is
+ *    therefore always undefined here.
+ *  - Part upload failures never exhaust a retry budget; they re-stage on a
+ *    timer while running (and on every explicit `resume()`/`reconcile()`),
+ *    because the OS may hold a transfer in limbo for arbitrarily long and a
+ *    "budget" would misfire on healthy-but-slow links. */
+import type { SessionStatus } from '../core/session.js';
+import type { CompleteInfo } from '../core/engine.js';
+import { type Progress } from '../core/events.js';
+type Events = {
+    progress: Progress;
+    statechange: SessionStatus;
+    error: Error;
+};
+export declare class NativeUpload {
+    readonly done: Promise<CompleteInfo>;
+    private resolveDone;
+    private rejectDone;
+    private emitter;
+    private handle;
+    private status;
+    private doneParts;
+    private inflight;
+    private confirmedBytes;
+    private confirmedAtStart;
+    private startedAtMs;
+    private lastProgressEmit;
+    private retryTimer;
+    private opts;
+    constructor(opts: NativeUpload['opts']);
+    get state(): SessionStatus;
+    on<K extends keyof Events>(ev: K, cb: (v: Events[K]) => void): () => void;
+    /** Kicks the upload off. Synchronous by signature (matching the engine);
+     *  the launch itself is async and reports failures via the 'error' event
+     *  and the `done` promise. Calling it twice is a no-op. */
+    start(): void;
+    pause(): void;
+    resume(): void;
+    abort(): void;
+    private launch;
+    /** A reconcile whose failure must not kill the upload: log-free retry via
+     *  the timer, because reconcile failures here are transient by
+     *  construction (offline, a token mid-refresh) and the store still holds
+     *  everything needed to finish later. */
+    private reconcileQuietly;
+    private scheduleRetry;
+    private clearRetry;
+    private partSizeOf;
+    private setStatus;
+    private emitProgress;
+}
+export {};