Files SDK icon

Files SDK

Files SDK is a unified TypeScript storage SDK for object and blob backends. It gives developers one consistent API across providers like S3, R2, GCS, and Azure Blob Storage, with a typed escape hatch for provider-specific clients.

Files SDK

Unified storage SDK for object and blob backends

Files SDK is a unified TypeScript storage SDK for object and blob backends. It presents one small API across providers such as AWS S3, Cloudflare R2, Google Cloud Storage, Azure Blob Storage, and other compatible services, so the same call sites can be reused when the backend changes.

The product centers on a `Files` class with standard operations like upload, download, head, list, delete, copy, move, url generation, and signed uploads. It also adds features for larger and more specialized workflows, including multipart uploads, live progress callbacks, byte-range reads, search by key, transfer and sync between instances, a CLI, and agent-oriented file tools. When provider-specific behavior is needed, the docs describe a typed `files.raw` escape hatch back to the native client.

Capabilities

Unified storage operations

The SDK exposes a compact `Files` surface with ten methods for common storage tasks, including bulk-friendly calls for `upload`, `delete`, and `exists`. It also adds `listAll`, `url`, `signedUploadUrl`, and a key-bound `file(key)` handle for narrower workflows.

Key-based search

`search()` finds objects by key using glob, regex, substring, or exact match. Results stream as an async iterable, and glob searches scope the bucket walk by prefix to avoid scanning unnecessary keys.

Multipart upload with progress

`upload()` supports multipart uploads for large or unbounded bodies, bounded concurrency, and configurable part size. The same operation can also report byte-level progress through `onProgress` for single or bulk uploads.

Byte-range downloads

Range requests map to HTTP 206 so callers can read only part of an object. The docs call out use for video seeking, resumable downloads, and header reads without fetching the entire file.

Agent and CLI workflows

The SDK includes ready-made file tools for Vercel AI SDK, OpenAI Agents, Claude, and MCP. It also ships a CLI that streams through stdin/stdout and defaults to JSON output.

Backend switching and escape hatch

The adapter layer covers many providers, and the core docs emphasize a typed escape hatch via `files.raw` when a backend-specific client is necessary. The API also supports `transfer` and `sync` for moving data between `Files` instances.

Use cases

  • Standardize storage calls across providers

    Use the same code path to upload, download, inspect metadata, list files, and delete objects across supported providers. This is the main fit for teams that want to switch storage backends without rewriting application logic.

  • Locate files by key pattern

    Use `search()` when you need to find files by naming patterns rather than by exact key. The documented glob, regex, substring, and exact-match options make it suitable for invoice buckets, log folders, or other structured key spaces.

  • Handle large uploads with progress

    Use multipart uploads and `onProgress` for large files, streamed bodies, or user-facing uploads that need progress feedback. The SDK documents bounded concurrency and configurable part size for these flows.

  • Read partial content efficiently

    Use byte-range downloads when you only need part of an object, such as a file header, a video segment, or a resumable chunk. The docs specifically map ranged reads to HTTP 206.

  • Automate file operations outside the app

    Use the CLI or agent tools when files need to be manipulated from scripts, CI jobs, or AI workflows. The source describes JSON output, stdin/stdout streaming, approval gates, and read-only modes for agent use.

Pros and Cons

Pros

  • One API covers common storage actions across many backends, reducing provider-specific rewrites.
  • The surface is intentionally small and consistent, with a shared error model and per-operation options like timeout, retries, and cancellation.
  • Search, multipart upload, live progress, and byte-range reads are built into the documented workflow.
  • The SDK includes both a CLI and agent-facing file tools, which broadens use beyond application code.
  • The adapter system keeps provider SDKs lazy-loaded as subpath exports, and `files.raw` remains typed when backend-specific access is needed.

Cons

  • Pricing is not established in the provided sources; the pricing page returns a 404, so the public site evidence here does not confirm a cost model.
  • Some adapter-specific capabilities still require the native client through `files.raw`, so the unified API does not cover every provider feature directly.

FAQ

Who is Files SDK for?

It is designed for applications that need a single TypeScript storage API across object and blob backends such as S3, R2, GCS, and Azure. The docs also describe an agent-friendly CLI and a typed escape hatch to native clients when provider-specific behavior is needed.

What does the core API look like?

The docs present a small unified surface: a `Files` instance with ten methods, plus `files.file(key)` for a key-bound handle. The API includes `upload`, `download`, `head`, `exists`, `delete`, `copy`, `move`, `list`, `url`, and `signedUploadUrl`, plus global `transfer` and `sync` helpers.

Can I still use provider-specific features?

Yes. The adapter docs say some backends support reads and writes directly through the shared API, while provider-specific capabilities such as versioning, lifecycle rules, multipart behavior, or ACLs are available through `files.raw`, which stays typed per adapter.

Is there a command-line interface?

The source shows a CLI that mirrors the SDK, with JSON output by default, stdin/stdout streaming, and a `--provider` flag to switch backends. It is positioned for scripts, CI, and one-off operations.

What does Files SDK cost?

The pricing page in the collected sources is a 404 and does not state any price or plan structure, so the public site evidence here does not confirm pricing details.

Quick Facts

Category
Developer Tool
Primary platform
TypeScript / JavaScript
Backends
S3, R2, GCS, Azure Blob Storage, plus many other adapters
Source domain
files-sdk.dev
Core model
One `Files` class with ten unified methods
Pricing
Not stated in the provided sources