stitchkit 0.101.0 → 0.101.2

package/llms/stitchkit.2.txt

@@ -352,8 +352,8 @@ non-flat field in a `GET` input, and a missing or invalid multipart file. → AD
 0148.
 
 Abort and timeout do not emit `network_error` and are not retried. The same
-options work for query, JSON, multipart and raw-response calls. Stitchkit does
-not expose upload progress: Fetch has no portable upload-progress primitive.
+options work for query, JSON, multipart and raw-response calls. A body call
+also takes `onUploadProgress` — see [Upload progress](#upload-progress).
 
 An injected transport failure is normalized to `UNKNOWN_ERROR` while its exact
 object remains available as `ApiError.cause`. This is how a bounded adapter can
@@ -368,6 +368,63 @@ For an endpoint without contract arguments, pass only the options object:
 await api.health.withOptions({ signal: controller.signal })
 ```
 
+### Upload progress
+
+A call with a body can report it leaving:
+
+> **In a browser or React Native, do not give the client its own `fetch` for
+> a call you want counted.** Without one the count comes from
+> `XMLHttpRequest` upload events; with one the body is streamed to it, which a
+> browser may buffer (and report at once) and React Native refuses.
+
+```ts
+await api.recordings.upload.withOptions(
+  { file, title: 'Take 3' },
+  {
+    signal,
+    onUploadProgress: ({ sentBytes, totalBytes, attempt }) => {
+      bar.value = sentBytes / totalBytes
+    },
+  },
+)
+```
+
+- `sentBytes` counts bytes of the encoded body handed to the network — not
+  bytes the server accepted. `totalBytes` is the encoded length, multipart
+  boundaries included. The first report is `0`, values only grow, and the last
+  one of an attempt equals `totalBytes`.
+- A transport retry (`HttpClientConfig.retry`) counts again from `0` under the
+  next `attempt`.
+- Without the option nothing changes: the request takes the path it always did.
+- A `GET`, `HEAD`, `DELETE` or streaming endpoint refuses the option with a
+  `TypeError` at the call — it has no body to count, or a live response the
+  browser route would buffer. A listener that throws does not fail the upload.
+
+Fetch has no upload event, so the count comes from one of three routes, chosen
+per call:
+
+| Where the client runs | Route | What counts |
+|---|---|---|
+| Bun, Node, SSR, an injected `fetch`, a unix socket | the body is encoded once and sent as a stream of 64 KiB pieces with an exact `content-length` | a piece counts when the transport pulls it |
+| a browser on its own fetch | `XMLHttpRequest`, with the same headers, credentials, errors, cancellation and timeout | `xhr.upload` progress events |
+| React Native / Expo on its own fetch | the platform's `XMLHttpRequest`, handed the body as the client built it — the `FormData` itself, so a `{ uri, name, type }` file streams from disk; the same errors, cancellation and timeout | `xhr.upload` progress events; a `FormData`'s `totalBytes` comes with the first one |
+
+The browser route exists because a streaming request body is not portable:
+Chromium sends one only over HTTP/2 and Safari not at all. Two consequences of
+XHR: `credentials: 'omit'` is refused (XHR cannot drop same-origin cookies),
+and the response is read whole before the call resolves. An injected `fetch`
+always takes the stream route — it owns the I/O, and a transport that buffers
+the stream before sending reports the whole body at once.
+
+React Native is recognised by `navigator.product === 'ReactNative'`. Its
+credentials follow its own fetch: `include` and `omit` set `withCredentials`,
+anything else keeps the platform default. An injected `fetch` there is refused
+with a `TypeError` at the call: React Native cannot stream a request body, so
+there is nothing to count.
+
+Off React Native a counted body is encoded in memory once. A file larger than one request
+belongs in [chunked uploads](#chunked-uploads), whose parts are sized for it.
+
 ### Injected delivery adapters
 
 `ClientFetch` is the narrow composition seam for application-owned delivery.
@@ -465,6 +522,124 @@ Every method now requires `tenantId`, and the callback sees it as a `string`.
 The batch form delegates to the same single-contract client runtime, including
 HTTP exposure filtering, multipart, raw responses and output validation.
 
+## Chunked uploads
+
+A file larger than one request goes as three calls of the application's own
+contract — open, parts, finish — driven by `uploadInChunks` on the client and
+held by `createChunkSpool` (`stitchkit/files`) on the server. The contract stays
+the application's: its fields, its limits, what happens to the finished file.
+
+```ts
+// shared: one part size for both halves
+export const CHUNK_BYTES = 4 * 1024 * 1024
+
+// contract
+init: {
+  method: 'POST', path: '/uploads', desc: 'Open an upload',
+  input: z.object({ uploadId: z.string(), totalBytes: z.number(), chunkCount: z.number(), name: z.string() }),
+  output: z.object({ finished: Accepted.optional() }),
+},
+chunk: {
+  method: 'PUT', path: '/uploads/:uploadId/chunks/:index', desc: 'Send one part',
+  params: z.object({ uploadId: z.string(), index: z.coerce.number() }),
+  multipart: { files: { bytes: {} } },
+  output: z.object({ state: z.enum(['stored', 'repeated']) }),
+},
+finalize: {
+  method: 'POST', path: '/uploads/:uploadId/finalize', desc: 'Assemble the file',
+  params: z.object({ uploadId: z.string() }),
+  output: Accepted,
+},
+```
+
+```ts
+// server
+import { createChunkSpool } from 'stitchkit/files'
+
+const spool = createChunkSpool({
+  directory: env.UPLOAD_SPOOL_DIR,
+  chunkBytes: CHUNK_BYTES,
+  maxFileBytes: 1024 * 1024 * 1024,
+  meta: z.object({ name: z.string() }),
+})
+
+implement(contract, {
+  init: async ({ input, ctx }) => {
+    const done = await findFinished(input.uploadId) // the app's own record
+    if (done) return { finished: done }
+    await spool.open({ owner: ctx.user.id, ...input, meta: { name: input.name } })
+    return {}
+  },
+  chunk: async ({ params, files, ctx }) => ({
+    state: await spool.put({ owner: ctx.user.id, ...params, bytes: files.bytes }),
+  }),
+  finalize: async ({ params, ctx }) => {
+    const key = { owner: ctx.user.id, uploadId: params.uploadId }
+    const file = await spool.assemble(key) // file.stream(), file.chunkPaths, file.meta
+    const accepted = await store(file)
+    await spool.discard(key)
+    return accepted
+  },
+})
+```
+
+```ts
+// client — Bun, Node, a browser or React Native
+import { uploadInChunks } from 'stitchkit'
+
+const accepted = await uploadInChunks({
+  file,
+  chunkBytes: CHUNK_BYTES,
+  signal,
+  onProgress: ({ sentBytes, totalBytes }) => draw(sentBytes / totalBytes),
+  init: async (start, options) => {
+    const opened = await api.uploads.init.withOptions({ ...start, name: file.name }, options)
+    return opened.finished ? { finished: opened.finished } : undefined
+  },
+  chunk: (part, options) => api.uploads.chunk.withOptions(part, options),
+  finalize: (upload, options) => api.uploads.finalize.withOptions(upload, options),
+})
+```
+
+The rules the two halves share:
+
+- **The client mints the upload id** (default `crypto.randomUUID()`, fresh per
+  call), so a repeated `init` is the same upload. The spool keys it by `owner`
+  too — the same id from another owner is another upload. To resume after the
+  app restarts instead of sending the file again, pass a stable `uploadId` —
+  the id of the app's own job or attempt.
+- **The file is anything with `size` and `slice(start, end)`** (`ChunkSource`).
+  A `Blob` is one; so is a platform file that is not a DOM `Blob`, such as an
+  Expo `File`, passed without a cast. A part's `bytes` is what `slice`
+  returns, so the part call hands it to the client as the multipart file.
+- **A part is idempotent.** The spool keeps a size+sha256 receipt per index:
+  the same bytes again answer `'repeated'`, other bytes `UPLOAD_CONFLICT`
+  (409). So the driver repeats `init` and a part on a failure that may pass — no
+  answer (network, timeout), `429`, `5xx` — up to `retries` times (default 3)
+  with a doubling pause from `retryDelayMs` (default 1 s). A refusal is final.
+- **`finalize` is never repeated.** After it the application owns the file and
+  the parts are gone; a lost answer is recovered by `init` returning
+  `{ finished }`, which the driver hands back without sending a byte.
+- **Cancellation is checked between parts**, so a cancelled upload never
+  reaches `finalize`.
+- **Every part but the last is exactly `chunkBytes`** and `chunkCount` must add
+  up; the spool refuses anything else with a 4xx `AppError`
+  (`ChunkSpoolErrorCode`), which a handler can let through as the client's
+  typed error. An application that maps error codes onto its own must map
+  these too — `isChunkSpoolErrorCode` / `CHUNK_SPOOL_ERROR_CODES` from
+  `stitchkit/files` — or a refusal reaches its client as an unknown 500.
+- **Progress counts file bytes**, inside a part too — the driver passes
+  `onUploadProgress` into the part call, so the [upload
+  progress](#upload-progress) route of the client applies. A repeated part
+  counts again from its start.
+- The first writer of a part wins across processes: its data file is named by
+  its hash and its receipt is published by an exclusive link. `sweep()` removes
+  uploads untouched for `staleAfterMs` (default 24 h); run it on a schedule.
+
+Part size is a latency decision: every part costs a round trip, so on a
+200 ms link a smaller part buys smoother progress at the price of a slower
+upload.
+
 ## Contract URL builders
 
 Browser-native consumers such as `<img src>`, downloads and navigation need a

package/llms/stitchkit.3.txt

@@ -41,7 +41,11 @@ The browser-and-server entrypoint. Re-exports everything from
 | `UrlBuilderConfig` | _type_ | explicit `{ baseUrl }` source for a URL builder |
 | `ClientConfig` | _type_ | config for `createClient`'s bare-fetch mode (2nd arg, no `HttpClient`) |
 | `ClientFetch` | _type_ | injectable Fetch-compatible transport used by framework and application-owned adapters |
-| `ClientRequestOptions` | _type_ | per-call `{ signal?: AbortSignal }` passed through an endpoint callable's `.withOptions(...)`; caller abort is distinct from timeout — [guide](../guide/client.md#per-call-cancellation) |
+| `ClientRequestOptions` | _type_ | per-call `{ signal?, onUploadProgress? }` passed through an endpoint callable's `.withOptions(...)`; caller abort is distinct from timeout — [guide](../guide/client.md#per-call-cancellation) |
+| `UploadProgress` | _type_ | `{ sentBytes, totalBytes, attempt }` heard by `onUploadProgress`: bytes of the encoded body handed to the network, first `0`, last `totalBytes`, counted again on each transport retry — [guide](../guide/client.md#upload-progress) |
+| `uploadInChunks` | function | send a file larger than one request as `init` → parts → `finalize` through three calls the app owns; client-minted id, repeats of a part on a failure that may pass, `finalize` never repeated, cancel checked between parts, progress in file bytes — [guide](../guide/client.md#chunked-uploads) |
+| `ChunkedUploadConfig` / `ChunkedUploadStart` / `ChunkedUploadPart` / `ChunkedUploadProgress` | _type_ | the driver's file, part size, retries and three calls; what `init` declares; one part; progress `{ sentBytes, totalBytes, index, chunkCount, attempt }` |
+| `ChunkSource` | _type_ | what the driver reads a file through — `size` and `slice(start, end)`; a `Blob` is one, so is a platform file that is not (an Expo `File`), and a part's `bytes` is what its `slice` returns |
 | `ContractClientConfig` | _type_ | per-tenant / resource-scoped client config — dynamic `pathPrefix` + `stripPrefixKeys` ([guide](../guide/client.md#contractclientconfig--per-tenant--resource-scoped-clients)) |
 | `contractEndpointMatchers` | function | compile exact pathname matchers for selected HTTP contract operations and expected-401 policy |
 | `PathPrefixArgs` | _type_ | required string-valued keys exposed to a typed dynamic `pathPrefix` callback |
@@ -54,7 +58,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `ConfiguredHttpClient` | _type_ | a framework-created `HttpClient` carrying its readonly `baseUrl` for URL builders |
 | `HttpClientConfig` | _type_ | config for `createHttpClient`; retry `limit` counts retries after the initial attempt (default 2 = at most 3 GET attempts), with `statusCodes: []` by default; `fetch` installs an explicit transport and is mutually exclusive with the legacy Bun-only `unix` option — [details](../guide/client.md#createhttpclient) |
 | `UnauthorizedMatcher` | _type_ | exact `(pathname) => boolean` policy accepted by `suppressUnauthorizedFor` |
-| `RequestOptions` | _type_ | per-call options — params, timeout, response type |
+| `RequestOptions` | _type_ | per-call options — params, timeout, response type, `onUploadProgress` |
 | `HeaderProvider` | _type_ | static or per-request headers |
 | `ApiEvent` | _type_ | a client event — `unauthorized` / `network_error` / `logout` |
 | `ApiEventListener` | _type_ | an `ApiEvent` handler |

package/llms-full.txt

@@ -2768,8 +2768,8 @@ non-flat field in a `GET` input, and a missing or invalid multipart file. → AD
 0148.
 
 Abort and timeout do not emit `network_error` and are not retried. The same
-options work for query, JSON, multipart and raw-response calls. Stitchkit does
-not expose upload progress: Fetch has no portable upload-progress primitive.
+options work for query, JSON, multipart and raw-response calls. A body call
+also takes `onUploadProgress` — see [Upload progress](#upload-progress).
 
 An injected transport failure is normalized to `UNKNOWN_ERROR` while its exact
 object remains available as `ApiError.cause`. This is how a bounded adapter can
@@ -2784,6 +2784,63 @@ For an endpoint without contract arguments, pass only the options object:
 await api.health.withOptions({ signal: controller.signal })
 ```
 
+### Upload progress
+
+A call with a body can report it leaving:
+
+> **In a browser or React Native, do not give the client its own `fetch` for
+> a call you want counted.** Without one the count comes from
+> `XMLHttpRequest` upload events; with one the body is streamed to it, which a
+> browser may buffer (and report at once) and React Native refuses.
+
+```ts
+await api.recordings.upload.withOptions(
+  { file, title: 'Take 3' },
+  {
+    signal,
+    onUploadProgress: ({ sentBytes, totalBytes, attempt }) => {
+      bar.value = sentBytes / totalBytes
+    },
+  },
+)
+```
+
+- `sentBytes` counts bytes of the encoded body handed to the network — not
+  bytes the server accepted. `totalBytes` is the encoded length, multipart
+  boundaries included. The first report is `0`, values only grow, and the last
+  one of an attempt equals `totalBytes`.
+- A transport retry (`HttpClientConfig.retry`) counts again from `0` under the
+  next `attempt`.
+- Without the option nothing changes: the request takes the path it always did.
+- A `GET`, `HEAD`, `DELETE` or streaming endpoint refuses the option with a
+  `TypeError` at the call — it has no body to count, or a live response the
+  browser route would buffer. A listener that throws does not fail the upload.
+
+Fetch has no upload event, so the count comes from one of three routes, chosen
+per call:
+
+| Where the client runs | Route | What counts |
+|---|---|---|
+| Bun, Node, SSR, an injected `fetch`, a unix socket | the body is encoded once and sent as a stream of 64 KiB pieces with an exact `content-length` | a piece counts when the transport pulls it |
+| a browser on its own fetch | `XMLHttpRequest`, with the same headers, credentials, errors, cancellation and timeout | `xhr.upload` progress events |
+| React Native / Expo on its own fetch | the platform's `XMLHttpRequest`, handed the body as the client built it — the `FormData` itself, so a `{ uri, name, type }` file streams from disk; the same errors, cancellation and timeout | `xhr.upload` progress events; a `FormData`'s `totalBytes` comes with the first one |
+
+The browser route exists because a streaming request body is not portable:
+Chromium sends one only over HTTP/2 and Safari not at all. Two consequences of
+XHR: `credentials: 'omit'` is refused (XHR cannot drop same-origin cookies),
+and the response is read whole before the call resolves. An injected `fetch`
+always takes the stream route — it owns the I/O, and a transport that buffers
+the stream before sending reports the whole body at once.
+
+React Native is recognised by `navigator.product === 'ReactNative'`. Its
+credentials follow its own fetch: `include` and `omit` set `withCredentials`,
+anything else keeps the platform default. An injected `fetch` there is refused
+with a `TypeError` at the call: React Native cannot stream a request body, so
+there is nothing to count.
+
+Off React Native a counted body is encoded in memory once. A file larger than one request
+belongs in [chunked uploads](#chunked-uploads), whose parts are sized for it.
+
 ### Injected delivery adapters
 
 `ClientFetch` is the narrow composition seam for application-owned delivery.
@@ -2881,6 +2938,124 @@ Every method now requires `tenantId`, and the callback sees it as a `string`.
 The batch form delegates to the same single-contract client runtime, including
 HTTP exposure filtering, multipart, raw responses and output validation.
 
+## Chunked uploads
+
+A file larger than one request goes as three calls of the application's own
+contract — open, parts, finish — driven by `uploadInChunks` on the client and
+held by `createChunkSpool` (`stitchkit/files`) on the server. The contract stays
+the application's: its fields, its limits, what happens to the finished file.
+
+```ts
+// shared: one part size for both halves
+export const CHUNK_BYTES = 4 * 1024 * 1024
+
+// contract
+init: {
+  method: 'POST', path: '/uploads', desc: 'Open an upload',
+  input: z.object({ uploadId: z.string(), totalBytes: z.number(), chunkCount: z.number(), name: z.string() }),
+  output: z.object({ finished: Accepted.optional() }),
+},
+chunk: {
+  method: 'PUT', path: '/uploads/:uploadId/chunks/:index', desc: 'Send one part',
+  params: z.object({ uploadId: z.string(), index: z.coerce.number() }),
+  multipart: { files: { bytes: {} } },
+  output: z.object({ state: z.enum(['stored', 'repeated']) }),
+},
+finalize: {
+  method: 'POST', path: '/uploads/:uploadId/finalize', desc: 'Assemble the file',
+  params: z.object({ uploadId: z.string() }),
+  output: Accepted,
+},
+```
+
+```ts
+// server
+import { createChunkSpool } from 'stitchkit/files'
+
+const spool = createChunkSpool({
+  directory: env.UPLOAD_SPOOL_DIR,
+  chunkBytes: CHUNK_BYTES,
+  maxFileBytes: 1024 * 1024 * 1024,
+  meta: z.object({ name: z.string() }),
+})
+
+implement(contract, {
+  init: async ({ input, ctx }) => {
+    const done = await findFinished(input.uploadId) // the app's own record
+    if (done) return { finished: done }
+    await spool.open({ owner: ctx.user.id, ...input, meta: { name: input.name } })
+    return {}
+  },
+  chunk: async ({ params, files, ctx }) => ({
+    state: await spool.put({ owner: ctx.user.id, ...params, bytes: files.bytes }),
+  }),
+  finalize: async ({ params, ctx }) => {
+    const key = { owner: ctx.user.id, uploadId: params.uploadId }
+    const file = await spool.assemble(key) // file.stream(), file.chunkPaths, file.meta
+    const accepted = await store(file)
+    await spool.discard(key)
+    return accepted
+  },
+})
+```
+
+```ts
+// client — Bun, Node, a browser or React Native
+import { uploadInChunks } from 'stitchkit'
+
+const accepted = await uploadInChunks({
+  file,
+  chunkBytes: CHUNK_BYTES,
+  signal,
+  onProgress: ({ sentBytes, totalBytes }) => draw(sentBytes / totalBytes),
+  init: async (start, options) => {
+    const opened = await api.uploads.init.withOptions({ ...start, name: file.name }, options)
+    return opened.finished ? { finished: opened.finished } : undefined
+  },
+  chunk: (part, options) => api.uploads.chunk.withOptions(part, options),
+  finalize: (upload, options) => api.uploads.finalize.withOptions(upload, options),
+})
+```
+
+The rules the two halves share:
+
+- **The client mints the upload id** (default `crypto.randomUUID()`, fresh per
+  call), so a repeated `init` is the same upload. The spool keys it by `owner`
+  too — the same id from another owner is another upload. To resume after the
+  app restarts instead of sending the file again, pass a stable `uploadId` —
+  the id of the app's own job or attempt.
+- **The file is anything with `size` and `slice(start, end)`** (`ChunkSource`).
+  A `Blob` is one; so is a platform file that is not a DOM `Blob`, such as an
+  Expo `File`, passed without a cast. A part's `bytes` is what `slice`
+  returns, so the part call hands it to the client as the multipart file.
+- **A part is idempotent.** The spool keeps a size+sha256 receipt per index:
+  the same bytes again answer `'repeated'`, other bytes `UPLOAD_CONFLICT`
+  (409). So the driver repeats `init` and a part on a failure that may pass — no
+  answer (network, timeout), `429`, `5xx` — up to `retries` times (default 3)
+  with a doubling pause from `retryDelayMs` (default 1 s). A refusal is final.
+- **`finalize` is never repeated.** After it the application owns the file and
+  the parts are gone; a lost answer is recovered by `init` returning
+  `{ finished }`, which the driver hands back without sending a byte.
+- **Cancellation is checked between parts**, so a cancelled upload never
+  reaches `finalize`.
+- **Every part but the last is exactly `chunkBytes`** and `chunkCount` must add
+  up; the spool refuses anything else with a 4xx `AppError`
+  (`ChunkSpoolErrorCode`), which a handler can let through as the client's
+  typed error. An application that maps error codes onto its own must map
+  these too — `isChunkSpoolErrorCode` / `CHUNK_SPOOL_ERROR_CODES` from
+  `stitchkit/files` — or a refusal reaches its client as an unknown 500.
+- **Progress counts file bytes**, inside a part too — the driver passes
+  `onUploadProgress` into the part call, so the [upload
+  progress](#upload-progress) route of the client applies. A repeated part
+  counts again from its start.
+- The first writer of a part wins across processes: its data file is named by
+  its hash and its receipt is published by an exclusive link. `sweep()` removes
+  uploads untouched for `staleAfterMs` (default 24 h); run it on a schedule.
+
+Part size is a latency decision: every part costs a round trip, so on a
+200 ms link a smaller part buys smoother progress at the price of a slower
+upload.
+
 ## Contract URL builders
 
 Browser-native consumers such as `<img src>`, downloads and navigation need a
@@ -18024,7 +18199,11 @@ The browser-and-server entrypoint. Re-exports everything from
 | `UrlBuilderConfig` | _type_ | explicit `{ baseUrl }` source for a URL builder |
 | `ClientConfig` | _type_ | config for `createClient`'s bare-fetch mode (2nd arg, no `HttpClient`) |
 | `ClientFetch` | _type_ | injectable Fetch-compatible transport used by framework and application-owned adapters |
-| `ClientRequestOptions` | _type_ | per-call `{ signal?: AbortSignal }` passed through an endpoint callable's `.withOptions(...)`; caller abort is distinct from timeout — [guide](../guide/client.md#per-call-cancellation) |
+| `ClientRequestOptions` | _type_ | per-call `{ signal?, onUploadProgress? }` passed through an endpoint callable's `.withOptions(...)`; caller abort is distinct from timeout — [guide](../guide/client.md#per-call-cancellation) |
+| `UploadProgress` | _type_ | `{ sentBytes, totalBytes, attempt }` heard by `onUploadProgress`: bytes of the encoded body handed to the network, first `0`, last `totalBytes`, counted again on each transport retry — [guide](../guide/client.md#upload-progress) |
+| `uploadInChunks` | function | send a file larger than one request as `init` → parts → `finalize` through three calls the app owns; client-minted id, repeats of a part on a failure that may pass, `finalize` never repeated, cancel checked between parts, progress in file bytes — [guide](../guide/client.md#chunked-uploads) |
+| `ChunkedUploadConfig` / `ChunkedUploadStart` / `ChunkedUploadPart` / `ChunkedUploadProgress` | _type_ | the driver's file, part size, retries and three calls; what `init` declares; one part; progress `{ sentBytes, totalBytes, index, chunkCount, attempt }` |
+| `ChunkSource` | _type_ | what the driver reads a file through — `size` and `slice(start, end)`; a `Blob` is one, so is a platform file that is not (an Expo `File`), and a part's `bytes` is what its `slice` returns |
 | `ContractClientConfig` | _type_ | per-tenant / resource-scoped client config — dynamic `pathPrefix` + `stripPrefixKeys` ([guide](../guide/client.md#contractclientconfig--per-tenant--resource-scoped-clients)) |
 | `contractEndpointMatchers` | function | compile exact pathname matchers for selected HTTP contract operations and expected-401 policy |
 | `PathPrefixArgs` | _type_ | required string-valued keys exposed to a typed dynamic `pathPrefix` callback |
@@ -18037,7 +18216,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `ConfiguredHttpClient` | _type_ | a framework-created `HttpClient` carrying its readonly `baseUrl` for URL builders |
 | `HttpClientConfig` | _type_ | config for `createHttpClient`; retry `limit` counts retries after the initial attempt (default 2 = at most 3 GET attempts), with `statusCodes: []` by default; `fetch` installs an explicit transport and is mutually exclusive with the legacy Bun-only `unix` option — [details](../guide/client.md#createhttpclient) |
 | `UnauthorizedMatcher` | _type_ | exact `(pathname) => boolean` policy accepted by `suppressUnauthorizedFor` |
-| `RequestOptions` | _type_ | per-call options — params, timeout, response type |
+| `RequestOptions` | _type_ | per-call options — params, timeout, response type, `onUploadProgress` |
 | `HeaderProvider` | _type_ | static or per-request headers |
 | `ApiEvent` | _type_ | a client event — `unauthorized` / `network_error` / `logout` |
 | `ApiEventListener` | _type_ | an `ApiEvent` handler |
@@ -19881,6 +20060,10 @@ 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 |
 
 ---
 

package/llms.txt

@@ -9,7 +9,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 Load the slice for each entrypoint your code imports — `import … from 'stitchkit/server'` → `llms/server.txt`; the root `stitchkit` import → `llms/stitchkit.txt`. A slice holds that entrypoint's API reference section and the guide pages whose home it is; every guide lives in exactly one slice, and a slice that needs another's guide names it under "Also read". Each file is at most 50.0 KB; a longer one continues in numbered parts, each naming the next at its top. Moving across versions: load `llms/upgrading.txt` and the range slices it lists between your version and the target. `llms-full.txt` inlines everything; it is far larger than a context window, so do not read it whole.
 
 ## Entrypoint slices
-- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 16.5 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 37.2 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 16.1 KB
+- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 16.5 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 45.2 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 17.1 KB
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.6 KB
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 9.0 KB
 - **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 9.4 KB
@@ -39,7 +39,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/application/schemas**: [llms/application-schemas.txt](llms/application-schemas.txt) 1.8 KB
 - **stitchkit/testing**: [llms/testing.txt](llms/testing.txt) 30.8 KB
 - **stitchkit/agent-runtime/sandbox**: [llms/agent-runtime-sandbox.txt](llms/agent-runtime-sandbox.txt) 8.1 KB
-- **stitchkit/files**: [llms/files.txt](llms/files.txt) 2.9 KB
+- **stitchkit/files**: [llms/files.txt](llms/files.txt) 4.1 KB
 - **stitchkit/telegram**: [llms/telegram.txt](llms/telegram.txt) 26.9 KB
 - **stitchkit/telegram/html**: [llms/telegram-html.txt](llms/telegram-html.txt) 2.7 KB
 - **stitchkit/telegram/screens**: [llms/telegram-screens.txt](llms/telegram-screens.txt) 21.2 KB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.101.0",
+  "version": "0.101.2",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",