Files SDK

A plugin is an opt-in, ordered pipeline passed to the createFiles constructor. Unlike hooks which only observe operations, plugins can transform inputs, veto calls (by throwing), or observe results. They can also contribute entirely new namespaced methods to the Files instance.

Use plugins for logic that requires changing behavior, such as:

• Envelope-encrypting bodies at rest.
• Gating uploads through a virus scanner.
• Metering bandwidth.
• Mirroring writes to a backup region.

import { createFiles, handlers } from "files-sdk";
import { s3 } from "files-sdk/s3";

const files = createFiles({
  adapter: s3({ bucket: "uploads" }),
  plugins: [
    {
      name: "uppercase",
      wrap: handlers({
        upload: (op, next) =>
          next({ ...op, body: (op.body as string).toUpperCase() }),
      }),
    },
  ],
});

await files.upload("a.txt", "hello"); // stored as "HELLO"

Files SDK provides a unified TypeScript API for object storage across 40+ providers, including AWS S3, Cloudflare R2, Vercel Blob, Google Cloud Storage, Azure, and various S3-compatible services (e.g., MinIO, DigitalOcean Spaces, Backblaze B2). It also supports consumer-style providers (Dropbox, Google Drive), upload services (Cloudinary), BaaS stacks (Firebase, Appwrite), and a local fs adapter for testing.

Key features include:

• Unified API: The same method signatures work across all adapters.
• Normalized Errors: Uses a single FilesError type with standardized codes (NotFound, Unauthorized, Conflict, ReadOnly, Provider), preserving the original error in the cause property.
• Lazy Loading: Adapters are subpath exports (e.g., files-sdk/s3), ensuring you only bundle the provider SDKs you actually use.
• Typed Escape Hatch: Use files.raw to access the underlying native client (like S3Client or VercelBlobClient) when provider-specific features are required.
• Agent-friendly CLI: A files binary with JSON output and an MCP server for AI agents.

The files-sdk provides a unified API for interacting with various object and blob storage providers (S3, R2, GCS, Azure, Vercel Blob, local filesystem, etc.).

Core Concepts

• The Files Instance: You configure a single Files class instance with an adapter at construction. This adapter remains fixed for the life of the instance.
• Subpath Imports: To keep bundles small, adapters are imported via subpaths (e.g., files-sdk/s3, files-sdk/r2, files-sdk/fs).
• Unified vs. Native API: The unified API represents the common subset of features supported by all adapters. For provider-specific features (like S3 versioning), use files.raw to access the underlying native client.
• Web-Standard I/O: All file bodies use web standards: Blob, File, ReadableStream<Uint8Array>, Uint8Array, ArrayBuffer, ArrayBufferView, or string.
• Error Handling: If an adapter cannot perform a requested unified operation (like a range download), it throws a FilesError rather than failing silently. You can check capability flags like supportsRange or supportsDelimiter at runtime.

Keep these technical constraints and behaviors in mind when working with archives:

• Streaming vs Buffering: zip() is a stream; it has flat memory usage because it only keeps one entry in flight at a time. unzip() is a buffer; it must download the entire archive into memory first to read the central directory at the end of the file.
• ZIP Limits: The plugin supports classic ZIP format only (no ZIP64). There is a limit of 65,535 entries and 4 GiB per entry/archive. Exceeding these limits will cause a failure.
• Security & Validation: Entry names are validated to prevent attacks like zip-slip. The plugin rejects duplicate names, .. segments, backslashes, and absolute paths. Extracted data is verified against recorded CRC-32 and size.
• Compression Method: Use method: "store" for files that are already compressed (e.g., JPEGs, videos) to save CPU cycles.
• Error Handling: For zip(), selection errors (like a missing key or unsafe name) surface on the stream. The stream will reject during the first read.

The Files instance provides a unified API across all supported providers (S3, GCS, Azure, Vercel Blob, local filesystem, etc.).

Supported Operations

• upload(key, body, options)
• download(key)
• head(key)
• exists(key): Returns false only when the provider reports NotFound. Auth or transport errors will still throw.
• delete(key)
• copy(sourceKey, destinationKey)
• move(sourceKey, destinationKey)
• list(options) / listAll(options)
• url(key, options)
• signedUploadUrl(key, options)
• file(key): Returns a key-scoped handle.

Key Characteristics

• Web-standard I/O: Bodies are handled as Blob, File, ReadableStream, Uint8Array, ArrayBuffer, or string. No provider-specific types leak into your code.
• Escape Hatch: Access the native client for any provider via files.raw to use provider-specific features.
• Tree-shakeable: Each adapter is a separate entry point, ensuring you only bundle what you use.