Skip to content
Files SDK
Esc
↑↓navigate↵open⌘Jpreview
On this page

files-sdk@3.2.0

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.

Last updated on

Was this page helpful?