stitchkit 0.101.0 → 0.101.2

package/dist/entrypoints/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/entrypoints/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,wBAAwB,EACxB,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,yBAAyB,EAC9B,+BAA+B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,KAAK,wBAAwB,GAC9B,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,yBAAyB,EACzB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,YAAY,GAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,GAC9B,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,WAAW,EACX,QAAQ,GACT,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,mBAAmB,EACnB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAKvD,OAAO,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGzF,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,wBAAwB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/entrypoints/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,cAAc,GACf,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,wBAAwB,EACxB,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,yBAAyB,EAC9B,+BAA+B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,KAAK,wBAAwB,GAC9B,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,yBAAyB,EACzB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,YAAY,GAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,GAC9B,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,WAAW,EACX,QAAQ,GACT,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,mBAAmB,EACnB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAKvD,OAAO,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGzF,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,wBAAwB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/entrypoints/index.js

@@ -8,7 +8,7 @@ import {
 import {
   ApiError2,
   createHttpClient2
-} from "../index-qjeggp8w.js";
+} from "../index-1h6gtdrj.js";
 import"../index-m38ej7e5.js";
 import {
   DEFAULT_CONTRACT_STREAM_FRAME_BYTES2,
@@ -24,7 +24,7 @@ import {
   createUrlBuilder2,
   createUrlBuilders2,
   createScopedUrlBuilders2
-} from "../index-aaj97r4y.js";
+} from "../index-d82d3xg4.js";
 import"../index-w0eqdhyd.js";
 import {
   LiveStatePhaseSchema2,
@@ -95,6 +95,98 @@ import {
   zodIssues2,
   formatZodError2
 } from "../index-1eeqpadm.js";
+
+// src/browser/chunked-upload.ts
+function isRetryableUploadFailure(error) {
+  if (ApiError2.is(error)) {
+    if (error.status === 0)
+      return error.code === "UNKNOWN_ERROR" || error.code === "REQUEST_TIMEOUT";
+    return error.status === 429 || error.status >= 500;
+  }
+  return error instanceof TypeError;
+}
+async function uploadInChunks(config) {
+  const { file, chunkBytes, signal } = config;
+  if (!Number.isSafeInteger(chunkBytes) || chunkBytes <= 0) {
+    throw new TypeError("uploadInChunks: chunkBytes must be a positive integer");
+  }
+  if (!Number.isSafeInteger(file.size) || file.size < 0) {
+    throw new TypeError("uploadInChunks: the file size must be a whole number of bytes");
+  }
+  if (file.size === 0)
+    throw new TypeError("uploadInChunks: the file is empty");
+  const totalBytes = file.size;
+  const chunkCount = Math.ceil(totalBytes / chunkBytes);
+  const uploadId = config.uploadId ?? crypto.randomUUID();
+  const retries = config.retries ?? 3;
+  const retryDelayMs = config.retryDelayMs ?? 1000;
+  const report = (sentBytes, index, attempt) => {
+    if (!config.onProgress)
+      return;
+    try {
+      config.onProgress({ sentBytes, totalBytes, index, chunkCount, attempt });
+    } catch {}
+  };
+  throwIfAborted(signal);
+  const opened = await repeating(() => config.init({ uploadId, totalBytes, chunkBytes, chunkCount }, { signal }), { retries, retryDelayMs, signal });
+  if (opened) {
+    report(totalBytes, chunkCount, 1);
+    return opened.finished;
+  }
+  report(0, 0, 1);
+  for (let index = 0;index < chunkCount; index += 1) {
+    throwIfAborted(signal);
+    const start = index * chunkBytes;
+    const end = Math.min(totalBytes, start + chunkBytes);
+    const partBytes = end - start;
+    const bytes = file.slice(start, end);
+    await repeating((attempt) => config.chunk({ uploadId, index, bytes }, {
+      ...signal && { signal },
+      onUploadProgress: (progress) => report(start + fileShare(progress, partBytes), index, attempt)
+    }), { retries, retryDelayMs, signal });
+    report(end, index + 1, 1);
+  }
+  throwIfAborted(signal);
+  return config.finalize({ uploadId }, { signal });
+}
+function fileShare(progress, partBytes) {
+  if (progress.totalBytes === 0)
+    return 0;
+  return Math.floor(partBytes * progress.sentBytes / progress.totalBytes);
+}
+async function repeating(call, {
+  retries,
+  retryDelayMs,
+  signal
+}) {
+  for (let attempt = 1;; attempt += 1) {
+    try {
+      return await call(attempt);
+    } catch (error) {
+      if (signal?.aborted || attempt > retries || !isRetryableUploadFailure(error))
+        throw error;
+      await pause(retryDelayMs * 2 ** (attempt - 1), signal);
+    }
+  }
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted) {
+    throw new ApiError2("REQUEST_ABORTED", 0, undefined, "Request was aborted");
+  }
+}
+function pause(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      clearTimeout(timer);
+      reject(new ApiError2("REQUEST_ABORTED", 0, undefined, "Request was aborted"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", abort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", abort, { once: true });
+  });
+}
 // src/browser/socket-io-trace.ts
 var realtimeRequestTraces = new WeakMap;
 function observeRealtimeRequestPhase(trace, phase) {
@@ -954,6 +1046,7 @@ export {
   rateLimited2 as rateLimited,
   resumableIterator,
   unauthorized2 as unauthorized,
+  uploadInChunks,
   withToolView2 as withToolView,
   zodIssues2 as zodIssues
 };

package/dist/entrypoints/react.js

@@ -2,7 +2,7 @@ import"../index-hby4qhax.js";
 import {
   ApiError2,
   isAbortLikeError
-} from "../index-qjeggp8w.js";
+} from "../index-1h6gtdrj.js";
 import {
   isRecord
 } from "../index-9jfdm5tg.js";

package/dist/entrypoints/remote.js

@@ -1,12 +1,12 @@
 import"../index-hby4qhax.js";
 import {
   ApiError2
-} from "../index-qjeggp8w.js";
+} from "../index-1h6gtdrj.js";
 import"../index-m38ej7e5.js";
 import"../index-r5c4fedv.js";
 import {
   createClient2
-} from "../index-aaj97r4y.js";
+} from "../index-d82d3xg4.js";
 import {
   AppError2
 } from "../index-n53mswt3.js";

package/dist/entrypoints/testing.js

@@ -1,5 +1,5 @@
 import"../index-hby4qhax.js";
-import"../index-qjeggp8w.js";
+import"../index-1h6gtdrj.js";
 import {
   joinRoutePath
 } from "../index-m38ej7e5.js";
@@ -7,7 +7,7 @@ import"../index-r5c4fedv.js";
 import {
   createClient2,
   createClients2
-} from "../index-aaj97r4y.js";
+} from "../index-d82d3xg4.js";
 import"../index-n53mswt3.js";
 import"../index-q0th8q0z.js";
 import {

package/dist/entrypoints/tracking.js

@@ -1,7 +1,7 @@
 import"../index-hby4qhax.js";
 import {
   ApiError2
-} from "../index-qjeggp8w.js";
+} from "../index-1h6gtdrj.js";
 import"../index-m38ej7e5.js";
 import {
   defineContract2

package/dist/files/chunk-spool.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The server half of a chunked upload (`uploadInChunks` is the client half):
+ * parts land on disk under the upload's owner, each with a receipt, and come
+ * back in order once every part is in.
+ *
+ * - An upload is keyed by `owner` (whoever the application says sends it —
+ *   a user, a user and a device) and the client-minted `uploadId`; the same id
+ *   from another owner is another upload.
+ * - `open` is idempotent: the same declaration again is `'reopened'`, a
+ *   different one is `UPLOAD_CONFLICT`.
+ * - A part's receipt is its size and sha256. The same bytes again are
+ *   `'repeated'`; other bytes at the same index are `UPLOAD_CONFLICT`. The
+ *   first writer wins across processes: a part's data file is named by its hash
+ *   and its receipt is published by an exclusive link, so a loser can neither
+ *   replace the receipt nor the bytes it names.
+ * - Every part but the last is exactly `chunkBytes` long.
+ * - `sweep` removes an upload nothing has touched for `staleAfterMs`.
+ *
+ * Refusals are `AppError`s with a 4xx status, so a handler that does not catch
+ * them answers the client with a typed envelope the driver does not repeat.
+ */
+import type { ZodType } from 'zod';
+export type ChunkSpoolErrorCode = 'UPLOAD_INVALID' | 'UPLOAD_TOO_LARGE' | 'UPLOAD_NOT_FOUND' | 'UPLOAD_CONFLICT' | 'UPLOAD_CHUNK_OUT_OF_RANGE' | 'UPLOAD_CHUNK_SIZE' | 'UPLOAD_INCOMPLETE';
+/**
+ * Whether an error code is one the spool refuses with. An application that
+ * maps error codes onto its own must map these too — an unmapped one would
+ * reach its client as an unknown 500 instead of the spool's 4xx.
+ */
+export declare function isChunkSpoolErrorCode(code: string): code is ChunkSpoolErrorCode;
+/** Every code the spool refuses with. */
+export declare const CHUNK_SPOOL_ERROR_CODES: readonly ChunkSpoolErrorCode[];
+export interface ChunkSpoolConfig<TMeta> {
+    /** Where uploads in progress live; one directory per upload. */
+    readonly directory: string;
+    /** Bytes per part, the same number the client driver uses. */
+    readonly chunkBytes: number;
+    readonly maxFileBytes: number;
+    /** What `open` stores beside the upload — file name, type, the app's fields. */
+    readonly meta: ZodType<TMeta>;
+    /** Default 24 hours. */
+    readonly staleAfterMs?: number;
+}
+export interface ChunkSpoolKey {
+    readonly owner: string;
+    readonly uploadId: string;
+}
+export interface ChunkSpoolOpen<TMeta> extends ChunkSpoolKey {
+    readonly totalBytes: number;
+    readonly chunkCount: number;
+    readonly meta: TMeta;
+}
+export interface ChunkSpoolPart extends ChunkSpoolKey {
+    readonly index: number;
+    readonly bytes: Blob;
+}
+export interface ChunkSpoolAssembly<TMeta> {
+    readonly meta: TMeta;
+    readonly totalBytes: number;
+    /** The parts on disk, in order; valid until `discard`. */
+    readonly chunkPaths: string[];
+    /** The whole file, part after part. */
+    stream(): ReadableStream<Uint8Array>;
+}
+export interface ChunkSpool<TMeta> {
+    open(upload: ChunkSpoolOpen<TMeta>): Promise<'opened' | 'reopened'>;
+    put(part: ChunkSpoolPart): Promise<'stored' | 'repeated'>;
+    /** Every part, checked against its receipt; `UPLOAD_INCOMPLETE` names the first missing. */
+    assemble(key: ChunkSpoolKey): Promise<ChunkSpoolAssembly<TMeta>>;
+    discard(key: ChunkSpoolKey): Promise<void>;
+    /** Remove uploads untouched for `staleAfterMs`; resolves with how many. */
+    sweep(): Promise<number>;
+}
+export declare function createChunkSpool<TMeta>(config: ChunkSpoolConfig<TMeta>): ChunkSpool<TMeta>;
+//# sourceMappingURL=chunk-spool.d.ts.map

package/dist/files/chunk-spool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk-spool.d.ts","sourceRoot":"","sources":["../../src/files/chunk-spool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAgBH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAInC,MAAM,MAAM,mBAAmB,GAC3B,gBAAgB,GAChB,kBAAkB,GAClB,kBAAkB,GAClB,iBAAiB,GACjB,2BAA2B,GAC3B,mBAAmB,GACnB,mBAAmB,CAAC;AAYxB;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,mBAAmB,CAE/E;AAED,yCAAyC;AACzC,eAAO,MAAM,uBAAuB,EAAE,SAAS,mBAAmB,EAEjE,CAAC;AAUF,MAAM,WAAW,gBAAgB,CAAC,KAAK;IACrC,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9B,wBAAwB;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc,CAAC,KAAK,CAAE,SAAQ,aAAa;IAC1D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB,CAAC,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAC9B,uCAAuC;IACvC,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,UAAU,CAAC,KAAK;IAC/B,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,QAAQ,GAAG,UAAU,CAAC,CAAC;IACpE,GAAG,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,GAAG,UAAU,CAAC,CAAC;IAC1D,4FAA4F;IAC5F,QAAQ,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC;IACjE,OAAO,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,2EAA2E;IAC3E,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1B;AAkED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CA4J1F"}

package/dist/{index-qjeggp8w.js → index-1h6gtdrj.js}

@@ -144,6 +144,207 @@ function responseTraceId(response) {
   return response?.headers.get(REQUEST_ID_HEADER) ?? undefined;
 }
 
+// src/browser/upload-progress.ts
+var PIECE_BYTES = 64 * 1024;
+function isReactNative() {
+  return Reflect.get(globalThis.navigator ?? {}, "product") === "ReactNative";
+}
+function uploadProgressRoute(injectedTransport) {
+  if (isReactNative()) {
+    if (injectedTransport) {
+      throw new TypeError("onUploadProgress in React Native counts through its XMLHttpRequest and cannot count an injected fetch — drop the custom fetch for this client");
+    }
+    return "native-xhr";
+  }
+  return !injectedTransport && typeof globalThis.XMLHttpRequest === "function" ? "xhr" : "stream";
+}
+function reporter(listener, attempt) {
+  let reported = -1;
+  const emit = (sentBytes, totalBytes) => {
+    reported = sentBytes;
+    try {
+      listener({ sentBytes, totalBytes, attempt });
+    } catch {}
+  };
+  return (sentBytes, totalBytes) => {
+    if (sentBytes <= reported)
+      return;
+    if (reported < 0 && sentBytes > 0)
+      emit(0, totalBytes);
+    emit(sentBytes, totalBytes);
+  };
+}
+function withUploadProgress(transport, listener, delivery) {
+  let attempts = 0;
+  return async (input, init) => {
+    attempts += 1;
+    const report = reporter(listener, attempts);
+    const signal = init?.signal ?? (input instanceof Request ? input.signal : undefined);
+    const credentials = init?.credentials ?? (input instanceof Request ? input.credentials : undefined);
+    if (delivery.route === "native-xhr") {
+      return sendNative(input, init, delivery.nativeBody ?? xhrBodyOf(init?.body), {
+        signal,
+        credentials,
+        report
+      });
+    }
+    const request = new Request(input, init);
+    const headers = new Headers(request.headers);
+    const bytes = new Uint8Array(await request.arrayBuffer());
+    const total = bytes.byteLength;
+    report(0, total);
+    if (delivery.route === "xhr") {
+      if (credentials === "omit") {
+        throw new TypeError("onUploadProgress sends through XMLHttpRequest, which cannot omit same-origin cookies — use credentials 'same-origin' or 'include'");
+      }
+      return sendThroughXhr({
+        method: request.method,
+        url: request.url,
+        headers,
+        body: total > 0 ? bytes : null,
+        totalBytes: total,
+        withCredentials: credentials === "include",
+        signal,
+        report
+      });
+    }
+    headers.set("content-length", String(total));
+    const counted = total > 0 ? { body: countedBody(bytes, (sent) => report(sent, total)), duplex: "half" } : {};
+    const outgoing = {
+      ...init,
+      method: request.method,
+      headers,
+      body: undefined,
+      ...counted,
+      ...signal && { signal },
+      ...credentials && { credentials }
+    };
+    return transport(request.url, outgoing);
+  };
+}
+function countedBody(bytes, report) {
+  let offset = 0;
+  return new ReadableStream({
+    pull(controller) {
+      if (offset >= bytes.byteLength) {
+        controller.close();
+        return;
+      }
+      const end = Math.min(offset + PIECE_BYTES, bytes.byteLength);
+      controller.enqueue(bytes.slice(offset, end));
+      offset = end;
+      report(offset);
+    }
+  }, { highWaterMark: 0 });
+}
+function sendNative(input, init, body, { signal, credentials, report }) {
+  const request = input instanceof Request ? input : undefined;
+  const headers = new Headers(request?.headers);
+  new Headers(init?.headers).forEach((value, name) => {
+    headers.set(name, value);
+  });
+  if (body instanceof FormData)
+    headers.delete("content-type");
+  const totalBytes = knownLength(body);
+  if (totalBytes !== undefined)
+    report(0, totalBytes);
+  return sendThroughXhr({
+    method: init?.method ?? request?.method ?? "GET",
+    url: request?.url ?? String(input),
+    headers,
+    body,
+    totalBytes,
+    ...credentials === "include" && { withCredentials: true },
+    ...credentials === "omit" && { withCredentials: false },
+    signal,
+    report
+  });
+}
+function xhrBodyOf(body) {
+  if (body instanceof ReadableStream) {
+    throw new TypeError("onUploadProgress in React Native cannot send a streamed body");
+  }
+  return body ?? null;
+}
+function knownLength(body) {
+  if (body === null)
+    return 0;
+  if (typeof body === "string")
+    return new TextEncoder().encode(body).byteLength;
+  if (body instanceof Blob)
+    return body.size;
+  if (body instanceof ArrayBuffer || ArrayBuffer.isView(body))
+    return body.byteLength;
+  return;
+}
+var BROWSER_OWNED_HEADERS = new Set(["content-length", "host", "connection"]);
+function sendThroughXhr(send) {
+  const { signal, report } = send;
+  let total = send.totalBytes;
+  const progress = (loaded, eventTotal) => {
+    if (total === undefined && eventTotal > 0)
+      total = eventTotal;
+    if (total !== undefined)
+      report(Math.min(loaded, total), total);
+  };
+  const finished = () => {
+    if (total !== undefined)
+      report(total, total);
+  };
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortReason(signal));
+      return;
+    }
+    const xhr = new XMLHttpRequest;
+    xhr.open(send.method, send.url, true);
+    send.headers.forEach((value, name) => {
+      if (!BROWSER_OWNED_HEADERS.has(name))
+        xhr.setRequestHeader(name, value);
+    });
+    if (send.withCredentials !== undefined)
+      xhr.withCredentials = send.withCredentials;
+    xhr.responseType = "arraybuffer";
+    const abort = () => xhr.abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    const settle = () => signal?.removeEventListener("abort", abort);
+    xhr.upload.onprogress = (event) => progress(event.loaded, event.total);
+    xhr.upload.onload = finished;
+    xhr.onload = () => {
+      settle();
+      if (xhr.status < 200 || xhr.status > 599) {
+        reject(new TypeError("Network request failed"));
+        return;
+      }
+      finished();
+      resolve(responseOf(xhr));
+    };
+    xhr.onerror = () => {
+      settle();
+      reject(new TypeError("Network request failed"));
+    };
+    xhr.onabort = () => {
+      settle();
+      reject(signal ? abortReason(signal) : new DOMException("Aborted", "AbortError"));
+    };
+    xhr.send(send.body);
+  });
+}
+function abortReason(signal) {
+  return signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+var NULL_BODY_STATUSES = new Set([101, 103, 204, 205, 304]);
+function responseOf(xhr) {
+  const headers = new Headers;
+  for (const line of xhr.getAllResponseHeaders().trim().split(/[\r\n]+/)) {
+    const colon = line.indexOf(":");
+    if (colon > 0)
+      headers.append(line.slice(0, colon).trim(), line.slice(colon + 1).trim());
+  }
+  const body = xhr.response;
+  return new Response(NULL_BODY_STATUSES.has(xhr.status) || !(body instanceof ArrayBuffer) ? null : body, { status: xhr.status, statusText: xhr.statusText, headers });
+}
+
 // src/browser/http.ts
 var API_ERROR_BRAND = Symbol.for("stitchkit.ApiError");
 function messageForCode(code, message) {
@@ -225,6 +426,18 @@ function requestFailure(error, emit) {
   const msg = error instanceof Error ? error.message : undefined;
   return new ApiError2("UNKNOWN_ERROR", status, msg ? { message: msg } : undefined, msg, undefined, responseTraceId(response), { cause: error });
 }
+function jsonBodyOf(data) {
+  return data === undefined ? null : JSON.stringify(data);
+}
+function errorBodyOf(data) {
+  if (typeof data !== "string")
+    return data ?? null;
+  try {
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
 function createHttpClient2(config) {
   assertTransportChoice(config);
   let ssrCookies = null;
@@ -280,23 +493,29 @@ function createHttpClient2(config) {
               emit({ type: "unauthorized" });
             }
           }
-          if (!response.ok) {
-            const body = await response.clone().json().catch(() => null);
-            if (body) {
-              const parsed = parseError(body);
-              if (parsed) {
-                throw new ApiError2(parsed.code, response.status, parsed.details, parsed.message, parsed.hint, responseTraceId(response));
-              }
-            }
-          }
+        }
+      ],
+      beforeError: [
+        ({ error }) => {
+          if (!isHTTPError(error))
+            return error;
+          const body = errorBodyOf(error.data);
+          const parsed = body === null ? null : parseError(body);
+          if (!parsed)
+            return error;
+          return new ApiError2(parsed.code, error.response.status, parsed.details, parsed.message, parsed.hint, responseTraceId(error.response));
         }
       ]
     }
   });
   async function request(method, url, data, options = {}) {
     const cancellation = createRequestCancellation(options.signal, options.timeout ?? config.timeout ?? 30000);
+    const transport = config.fetch ?? globalThis.fetch.bind(globalThis);
     const kyOptions = {
-      fetch: createRetryAwareFetch(config.fetch ?? globalThis.fetch.bind(globalThis), config.unix),
+      fetch: createRetryAwareFetch(options.onUploadProgress ? withUploadProgress(transport, options.onUploadProgress, {
+        route: uploadProgressRoute(config.fetch !== undefined || config.unix !== undefined),
+        nativeBody: data instanceof FormData ? data : jsonBodyOf(data)
+      }) : transport, config.unix),
       timeout: false,
       signal: cancellation.signal
     };
@@ -339,4 +558,4 @@ function createHttpClient2(config) {
   };
 }
 
-export { RequestCancellationError, createRequestCancellation, responseTraceId, ApiError2, refuseLocally, isAbortLikeError, parseApiErrorBody, createHttpClient2 };
+export { RequestCancellationError, createRequestCancellation, responseTraceId, uploadProgressRoute, withUploadProgress, ApiError2, refuseLocally, isAbortLikeError, parseApiErrorBody, createHttpClient2 };

package/dist/{index-aaj97r4y.js → index-d82d3xg4.js}

@@ -2,10 +2,12 @@ import {
   RequestCancellationError,
   createRequestCancellation,
   responseTraceId,
+  uploadProgressRoute,
+  withUploadProgress,
   ApiError2,
   refuseLocally,
   parseApiErrorBody
-} from "./index-qjeggp8w.js";
+} from "./index-1h6gtdrj.js";
 import {
   parseTrailingWildcard
 } from "./index-m38ej7e5.js";
@@ -538,10 +540,14 @@ function createFetchExecutor(endpoint, prefix, config, contractConfig) {
     const hasBody = endpoint.method !== "GET" && endpoint.method !== "HEAD" && endpoint.method !== "DELETE" && !endpoint.multipart && endpoint.input && Object.keys(plan.remainingArgs).length > 0;
     if (hasBody)
       headers["Content-Type"] = "application/json";
+    const progressRoute = options?.onUploadProgress ? uploadProgressRoute(config.fetch !== undefined) : undefined;
     try {
       return await cancellation.run(async (signal) => {
         const body = endpoint.multipart ? buildMultipartForm(endpoint.multipart, plan.remainingArgs) : hasBody ? JSON.stringify(plan.remainingArgs) : undefined;
-        const res = await executeFetch(url, {
+        const deliver = options?.onUploadProgress && progressRoute ? withUploadProgress(executeFetch, options.onUploadProgress, {
+          route: progressRoute
+        }) : executeFetch;
+        const res = await deliver(url, {
           method: endpoint.method,
           headers,
           credentials: config.credentials,
@@ -660,7 +666,7 @@ function createEndpointMethod(endpoint, execute, contractConfig) {
     return Object.assign(method, {
       withOptions: (...args) => {
         refuseExtraWithOptionsArguments(endpoint, args.length, 2);
-        return settle(execute, readClientRequestArgs(args[0]), readClientRequestOptions(args[1]));
+        return settle(execute, readClientRequestArgs(args[0]), readClientRequestOptions(endpoint, args[1]));
       }
     });
   }
@@ -668,7 +674,7 @@ function createEndpointMethod(endpoint, execute, contractConfig) {
   return Object.assign(method, {
     withOptions: (...args) => {
       refuseExtraWithOptionsArguments(endpoint, args.length, 1);
-      return settle(execute, {}, readClientRequestOptions(args[0]));
+      return settle(execute, {}, readClientRequestOptions(endpoint, args[0]));
     }
   });
 }
@@ -694,16 +700,30 @@ function readClientRequestArgs(requestArgs) {
   }
   return requestArgs ?? {};
 }
-function readClientRequestOptions(value) {
+function readClientRequestOptions(endpoint, value) {
   if (!isRecord(value))
     throw new TypeError("Client request options must be an object");
-  const signal = value.signal;
-  if (signal === undefined)
-    return {};
-  if (!isAbortSignal(signal)) {
+  const { signal, onUploadProgress } = value;
+  if (signal !== undefined && !isAbortSignal(signal)) {
     throw new TypeError("Client request signal must be an AbortSignal");
   }
-  return { signal };
+  if (onUploadProgress === undefined)
+    return signal === undefined ? {} : { signal };
+  if (typeof onUploadProgress !== "function") {
+    throw new TypeError("Client request onUploadProgress must be a function");
+  }
+  if (!endpointSendsBody(endpoint)) {
+    throw new TypeError(`${endpoint.method} ${endpoint.path}: onUploadProgress needs a request body — ` + "a GET, HEAD or DELETE sends none, and a streaming endpoint keeps its response live, " + "which the XMLHttpRequest route would buffer.");
+  }
+  return {
+    ...signal !== undefined && { signal },
+    onUploadProgress: (progress) => {
+      onUploadProgress(progress);
+    }
+  };
+}
+function endpointSendsBody(endpoint) {
+  return endpoint.method !== "GET" && endpoint.method !== "HEAD" && endpoint.method !== "DELETE" && !(("stream" in endpoint) && endpoint.stream);
 }
 function isAbortSignal(value) {
   return typeof value === "object" && value !== null && "aborted" in value && typeof value.aborted === "boolean" && "addEventListener" in value && typeof value.addEventListener === "function" && "removeEventListener" in value && typeof value.removeEventListener === "function";

package/llms/files.txt

@@ -29,5 +29,9 @@ available from `stitchkit/contract`.
 | `writeFileAtomic` / `writeFileAtomicSync` / `WriteFileAtomicOptions` | function / _type_ | replace a file atomically: a random staging name created exclusively (never through a planted link), the mode set on the descriptor before the file is visible (default `0o600`, not masked by the umask), `fsync`, rename; a failure leaves the target and no staging file. The asynchronous form keeps the event loop running |
 | `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time and nullable kernel process identity); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; an ownerless lock only after `ownerlessGraceMs` |
 | `ExclusiveLockError` | class | `LOCK_TIMEOUT` naming the resource and its holder, or `LOCK_ABORTED` with the signal's reason |
+| `createChunkSpool` | function | the server half of a chunked upload: parts on disk under `owner` + client-minted `uploadId`, each with a size+sha256 receipt; idempotent `open` and `put`, the first writer of a part wins across processes, `assemble` in order once every part is in, `sweep` of untouched uploads — [guide](../guide/client.md#chunked-uploads) |
+| `ChunkSpool` / `ChunkSpoolConfig` / `ChunkSpoolKey` / `ChunkSpoolOpen` / `ChunkSpoolPart` / `ChunkSpoolAssembly` | _type_ | the spool, its directory, part size, file limit, meta schema and age; an upload's key; its declaration; one part; the assembled parts with a concatenating `stream()` |
+| `ChunkSpoolErrorCode` | _type_ | the `AppError` codes a spool refuses with, each with its 4xx status: `UPLOAD_INVALID`, `UPLOAD_TOO_LARGE`, `UPLOAD_NOT_FOUND`, `UPLOAD_CONFLICT`, `UPLOAD_CHUNK_OUT_OF_RANGE`, `UPLOAD_CHUNK_SIZE`, `UPLOAD_INCOMPLETE` |
+| `CHUNK_SPOOL_ERROR_CODES` / `isChunkSpoolErrorCode` | const / function | every `ChunkSpoolErrorCode` as a frozen list, and the guard for one — map them onto the app's own error codes, or a spool refusal reaches its client as an unknown 500 |
 
 ---