---
changelog:
  category: Release
  version: files-sdk@3.2.0
date: '2026-11-14T19:13:40Z'
seo:
  description: >-
    Add a responseContentType option to url() that overrides the Content-Type of
    the response, so a PDF stored as application/octet-stream can be previewed
    inline…
title: files-sdk@3.2.0
type: changelog
---
## Minor Changes

- a0c6318: Add a `responseContentType` option to `url()` that overrides the `Content-Type` of the response, so a PDF stored as `application/octet-stream` can be previewed inline instead of downloaded. It is bound into the signed URL by S3 and every S3-compatible adapter (on either client engine), `files-sdk/bun-s3`, `files-sdk/gcs`, `files-sdk/firebase-storage`, `files-sdk/azure` with a signer, and `files-sdk/r2` over HTTP or in hybrid mode, and, like `responseContentDisposition`, it forces signing when a `publicBaseUrl` is configured. The new `capabilities.signedUrl.contentType` reports whether an instance can bind it; where it can't, `url()` throws `Unsupported` before the adapter is called, and a value that isn't exactly one media type, written in ASCII, throws `Invalid`. In `files-sdk/api`, `authorize` can return `responseContentType` to override the type of `download` and `url`: downloads redirect with it bound where the adapter supports it and are proxied with that `Content-Type` otherwise (the proxy's sandbox policy is decided on the type it sends), and the `url` operation fails with `Unsupported` on adapters that can't bind it. Browsers can't request a content type. The field is optional on `SignedUrlCapability`, so a plugin `capabilities` hook that builds its own `signedUrl` object keeps compiling; leaving it out reads as `false`.

## Patch Changes

- 511dceb: `files-sdk/ai-sdk` and `files-sdk/claude`: an override field set to `undefined` in `createFileTools({ overrides })` or `createClaudeFileTools({ overrides })` now leaves the tool's own value in place, as it already did in `files-sdk/openai`. It used to erase the field, so `overrides: { deleteFile: { needsApproval: undefined } }` removed the approval gate from a write tool, and an undefined `description` or `annotations` stripped the tool's description or its read-only and destructive hints.
- f58de4b: `files-sdk/box` resumable uploads now keep the buffered body until the final upload succeeds. A transient failure on that upload used to drop it, so the automatic retry failed with a misleading `Invalid` "resumable session not found" error and the upload could not be finished.
- 82b239d: `files-sdk/bun-s3`: a resumable upload (`control`) no longer fails after its final write has landed because the follow-up `stat()` was refused or failed. The stat only fills in the result's `etag` and `lastModified`, so a key allowed `PutObject` but not `HeadObject` now gets the upload result without them, as a plain `upload()` already did, instead of an error whose retry wrote the whole body again and left the buffered session in memory.
- 7dc03e6: `files-sdk/bunny-storage` now percent-encodes each key segment in the Storage API path. The Bunny SDK puts the path into the request URL unencoded, so a key containing `%` followed by two hex digits was written under its decoded name (`a%20b.txt` became `a b.txt`), a `\` became a `/`, and tabs and newlines were dropped.
- 5830ce2: `files-sdk/cache` no longer lets a read that was already in flight re-populate an entry after `invalidateCache()` or a provider storage event dropped it. A slow `head()`, `url()`, or `download()` that fetched before the out-of-band change used to cache its stale answer once it returned, serving it for the full `ttl` despite the invalidation; it now returns what it fetched without caching it, as a read that overlaps a write through the instance already did.
- 6e83742: `files events parse <path>` given a directory now exits 2 with `Invalid` like the other local file errors, instead of exit 5 with `Provider`, the code that tells a script the backend failed and the command is safe to retry.
- fcb7837: `files download --out-dir` now accepts a filesystem root (`/`, `C:\`) as the directory. The check that keeps a key from being written outside `--out-dir` compared against the root with a second separator appended, so every key was refused with `refusing to write key outside --out-dir`.
- 4bd42b8: `files upload --file` now checks its source before the upload starts: a directory fails with `Invalid` (exit 2) and points at `--dir`, and a file the process can't read fails as a local file error (exit 2). Both used to surface from inside the adapter's upload with whatever code that adapter gives a read error; on `fs` that was `Conflict` (exit 4) for a directory and `Unauthorized` (exit 3) for an unreadable file.
- d3c22f3: `files-sdk/content-type` now classifies an XML document that has no `<?xml` prolog by its root element when the declared type is XML-based. An XHTML- or SVG-namespaced root (`<x:html xmlns:x="http://www.w3.org/1999/xhtml">`, or an `<svg>` behind a `<!DOCTYPE>`) uploaded as `application/xml` used to count as unidentified bytes and keep that type, so it slipped past `onMismatch: "reject"` and a `validation()` allowlist; it is now relabeled (or rejected) as `application/xhtml+xml` / `image/svg+xml`, the same as one behind a prolog.
- 6f04f01: A plugin's `next()` now always returns a promise. When the core refused the operation synchronously (an invalid key, an unsupported `range`, a changed conditional predicate) or an inner plugin's `wrap` threw before returning, `next()` threw instead of rejecting, so a plugin written as `next(op).catch(...)` or `next(op).finally(...)` never ran its handler or cleanup.
- c677026: `files.search()` (and the `files-sdk/api` gateway's `search`) now finds keys when a glob has a wildcard after an escaped brace (`dir\{1\}/*.pdf`), a brace matched literally (`users/{id}/*.json`), or an unclosed bracket. The literal prefix pushed down to `list()` used to be the whole pattern, wildcards included, so the walk listed a prefix no key starts with and the search returned nothing.
- 30a21ad: `files-sdk/dedup` now releases a pointer's body before following it to the blob. A `download(key, { as: "stream" })` (which is how the `files-sdk/api` gateway proxies downloads) fetched the pointer as a live stream and never read or cancelled it, so on S3-style adapters every de-duplicated download left a provider connection open until the pool ran out.
- 0b25112: `files-sdk/dropbox` `list()` now caps `limit` at 2000, the largest page Dropbox accepts. A larger `limit` was sent as-is and failed the whole listing with a `400` from Dropbox.
- 9821e03: `files-sdk/dropbox` resumable uploads now continue from the offset Dropbox reports when a chunk is refused with `incorrect_offset` (a chunk that landed but whose reply was lost), and keep the resume token in step. Previously every retry and every later resume re-sent the chunk at the stale offset, so the upload could never finish.
- bc3e839: `files.events.webhook()` (`files-sdk/events`) now checks a `verify: { token }` or `verify: { google }` credential before reading the request body. It used to buffer the whole body first, so a sender with no valid credential could make the endpoint hold an arbitrarily large request in memory before getting its `401`.
- 75880de: `files.abortUpload()` and `control.abort()` on the filesystem adapter (`files-sdk/fs`) no longer remove a resumable upload's partial through a folder that is symlinked outside the adapter root. A key resolving through such a link was already refused by every write, but discarding its session deleted the matching `.fls-part` file outside the root; `abortUpload()` now rejects with `Invalid` and removes nothing.
- 0b75f6f: The filesystem adapter (`files-sdk/fs`) no longer mistakes a folder for a sidecar. A key such as `report.meta.json/page.txt` creates a folder at the path where the key `report` keeps its sidecar: `list()` then failed for the whole root, `head()` and `download()` of `report` threw `Conflict`, and `upload("report")` rejected with the new body already written. The folder now reads as "no sidecar", and an upload, copy, or resumable upload to such a key is refused with `Conflict` before the body is replaced.
- d1c111b: The filesystem adapter (`files-sdk/fs`) now treats a key more than one level under an existing file (`a.txt/b/c` when `a.txt` is an object) the way it already treated one directly under it: `delete()` is a no-op instead of throwing `NotFound`, and `upload()`, `copy()`, `move()`, and a resumable upload to such a key reject with `Conflict` instead of a `NotFound` that read as a missing source.
- 57c5f07: The filesystem and in-memory adapters (`files-sdk/fs`, `files-sdk/memory`) now honor an upload's `signal` and `timeout`. An aborted or timed-out upload rejected, but the adapter kept reading a stream body to its end and then stored the object anyway; the body is now cancelled and nothing is written.
- b1d71b1: `files-sdk/ftp` `move()` now throws `NotFound` when the source key is a directory instead of renaming the whole directory tree, and a missing source no longer leaves the destination's parent folder behind.
- 5949a67: The `files-sdk/api` gateway now refuses a client content type that isn't ASCII with `422` (`reason: "type"`) on `presign` and `signed-upload-url`. A type such as `image/png; name=日本` used to be stored, and every proxied download of that object then failed with a `500` because no response header can carry it.
- 238c679: The `files-sdk/api` gateway now refuses an empty key with `422` under an `authorize` `keyPrefix` too. It used to resolve to the prefix itself (`users/1/`), so the adapter was asked to head, delete, copy, or sign the caller's whole folder as if it were an object.
- bb9efda: The `files-sdk/api` gateway's `presign` now answers `422` for an `expiresIn` that isn't a positive whole number of seconds. `0` or a negative value used to return an upload token that had already expired, and on a signing adapter any such value silently switched the upload to the gateway's proxy.
- 5949a67: When `authorize` returns a `disposition` that can't be sent as a `Content-Disposition` header (a control character, or a raw non-Latin-1 filename), a proxied download through `files-sdk/api` now fails with a `422` that says how to encode the name (`filename*=UTF-8''…`). It used to open the object, fail while building the response, and answer a generic `500` with the storage stream left open.
- 5949a67: A proxied download through `files-sdk/api` no longer answers `500` for an object whose stored content type can't be sent as a header (one written outside the gateway with a character past U+00FF). The gateway serves it as `application/octet-stream` instead.
- 7d477f8: The `files-sdk/api` gateway's `search` no longer pushes a glob's literal head down to the adapter as a list prefix when it isn't a safe prefix (`../other/*`, `/etc/*`). Joined to an `authorize` `keyPrefix`, such a head asked the adapter to list a path outside the caller's scope; the search now walks the caller's own prefix and matches nothing.
- 4e24f5c: `files-sdk/gcs` and `files-sdk/firebase-storage` now throw `Unsupported` from `signedUploadUrl()` for a positive `minSize` without `maxSize`, as the S3 adapters do. The size floor is only enforced by the POST policy that `maxSize` selects, so the signed PUT URL returned before accepted uploads below the requested minimum.
- 9c5d462: `files-sdk/google-drive` `list()` now caps `limit` at 1000, the largest `pageSize` Drive accepts. A larger `limit` was sent as-is and failed the whole listing with a `400` from Drive.
- 56d87da: Stop a native bulk delete in the adapter once the constructor `signal` or `timeout` cuts its slice off. Each slice's `deleteMany` call now gets that slice's abort signal (the new `AdapterDeleteManyOptions.signal`, which a `signal` in the caller's bulk options never overrides). FTP and SFTP (`files-sdk/ftp`, `files-sdk/sftp`) stop before their next key, Azure (`files-sdk/azure`) cancels its batch request in flight and sends no further batch, and S3 and the S3-compatible adapters on the `aws-sdk` client cancel their `DeleteObjects` request in flight, instead of deleting the rest of the slice after the call has reported those keys in `errors`. A request the provider already received may still be carried out.
- 3c3d94f: The Node gateway bindings (`files-sdk/express`, `files-sdk/koa`, `files-sdk/fastify`, `files-sdk/nitro`, `files-sdk/nestjs` and the raw `node:http` handler) no longer let the request target choose the request's host. A path such as `//evil.example/api/files` or an absolute-form target resolved to that host, so on a catch-all mount a cross-site page on it passed the default same-origin check for mutations. The origin now always comes from the `Host` header.
- 1cd8bdc: `files-sdk/onedrive` and `files-sdk/sharepoint` resumable uploads now recover when Graph answers a retried chunk with `416` because it already holds those bytes: the driver reads the session's `nextExpectedRanges` and continues from there instead of failing the upload.
- 1cd8bdc: `files-sdk/onedrive` and `files-sdk/sharepoint` now classify a failed upload-session request by its status: an expired session (404/410) is `NotFound`, a refusal is `Unauthorized` or `Conflict`, and none of them are retried. They were all thrown as retryable `Provider` errors before.
- ce7bf24: `files-sdk/validation` and `files-sdk/content-type` now read an empty `contentType` (`""`, which is what `{ contentType: file.type }` passes for a file the browser can't type) as "not declared", the way the core does. Both plugins used to reject the upload with a "malformed content type" error; they now fall back to the `Blob`'s own type, then the key's extension, and check that.
- 7638bf4: `files-sdk/pocketbase` now sends every request with `requestKey: null`, opting out of the PocketBase SDK's auto-cancellation. Concurrent operations on one adapter (two uploads of new keys, two `list()` calls, two downloads or `url()` calls fetching a file token) no longer abort each other with a `Provider` error, and the operation's abort `signal` and `timeout` now reach the request instead of being replaced by the SDK's own controller.
- a82e58b: `files-sdk/r2`: errors from the Workers binding are now classified from the R2 code at the end of the error message (`"get: The requested range is not satisfiable (10039)"`), which is where workerd reports it, not only from a `code` property. A `range` past the end of an object is a permanent `Provider` error that `retries` no longer reissues, and a precondition, access, or missing-bucket failure maps to `Conflict`, `Unauthorized`, or `NotFound` instead of a retried `Provider` error.
- 4d27729: `files-sdk/s3` (and the `"aws-sdk"` engine of r2, minio, rustfs, and every S3-compatible wrapper): aborting an upload that goes through `@aws-sdk/lib-storage` (a `ReadableStream` body, `onProgress`, or `multipart`) now cancels the request in flight. The `signal` only stopped new requests from starting, so a single `PutObject` already on the wire still wrote the object after `upload()` had rejected as aborted, and in-flight parts uploaded to the end.
- a7c96e1: `files-sdk/sftp` `delete()` on a key that resolves to a directory is now a no-op, like a missing key and like the other filesystem-style adapters, instead of failing with a retryable `Provider` (or `Unauthorized`) error from the refused `unlink`.
- 64eb0cd: `files-sdk/sftp` `download()` and `copy()` now throw `NotFound` for a key that resolves to a directory, as `head()` and `exists()` already report it. Reading one used to fail with a retryable `Provider` error, and a streamed download returned a file that errored mid-read.
- 8b73561: `files-sdk/sftp` `move()` now throws `NotFound` when the source key is a directory instead of renaming the whole directory tree, and a missing source no longer leaves the destination's parent folder behind.
- 2850f3a: `files-sdk/supabase` now forwards the abort `signal` passed to `url()` and `signedUploadUrl()` to the signing request, so an aborted or timed-out call cancels it instead of leaving it running.
- c8f3f6a: `files-sdk/tiering` now cancels the source stream when a cross-tier `copy`, `move`, or `tier()` fails to upload to the destination tier. The streamed source download was left unread, so every failed transfer (a cold tier that is down, a timeout) kept a connection to the source tier open.
- c0edffb: `files-sdk/tiering`'s `tier(key, target)` now throws `Invalid` when `target` is anything other than `"hot"` or `"cold"`. An untyped value (say `"warm"`, from a request body) was treated as the cold tier, so calling it on an object already in the cold tier copied the object onto itself and then deleted it.
- d699138: `files-sdk/uploadthing` now uploads a `Blob` or `File` body with its own `type` when no `contentType` is passed. The type was dropped before, so the file was stored with a type guessed from the key's extension, or `application/octet-stream` for a key without one.
- e6caea1: `files-sdk/validation` now stops reading a streamed upload as soon as it passes `maxSize`, cancelling the source and rejecting with the size error. It used to buffer the entire stream before measuring it, so an oversized or never-ending body was held in memory in full (or forever) before the limit applied.
- c632e16: `files-sdk/vercel-blob` no longer fails a stream upload when the follow-up `head()` that reads the stored size fails. The blob is already written at that point, so `upload()` now resolves with `size: 0` instead of reporting a stored blob as not uploaded.
- 850198a: `files-sdk/webdav` now cancels the response when a server ignores the `Range` header on a streamed download, instead of throwing and leaving the full-object response (and its connection) open behind the error.
