Introduction

s3.delivery is a file-storage SDK for TypeScript apps. Files go straight from the browser to your own bucket through short-lived presigned URLs — they never pass through your server or ours. Your code only signs and authorizes; the bytes take the direct path.

You get fast uploads, cheap bandwidth (no proxy egress to pay for), and no vendor lock-in (the files live in your own S3-compatible bucket). One API key wires up the whole thing.

import { S3Delivery } from "s3delivery";

const s3 = new S3Delivery(); // reads S3DELIVERY_TOKEN
const file = await s3.upload(blob, { name: "report.pdf" });

console.log(file.url); // a stable link, ready to share

That is the whole upload: reserve a record → send bytes straight to your bucket → confirm — in one call.

The browser → bucket model

A typical upload SDK proxies your file through the vendor's storage: the browser sends bytes to the vendor, the vendor stores them, and you fetch them back through the vendor again. You pay for that bandwidth and inherit that latency.

s3.delivery splits the work in two:

• Control plane — a small Worker API checks your API key, enforces quota and per-route constraints, writes a metadata row, and mints a presigned URL. Every request is a quick signing + database operation.
• Data plane — the browser (or your server) PUTs the bytes directly to your bucket using that presigned URL. The API never sees a byte.

Downloads work the same way in reverse: the API checks permissions and signs a short-lived GET URL, and the browser reads straight from the bucket.

What you get

• One API key. No file-router DSL and no per-bucket config. Mount one route and call one function.
• Bytes skip the API. Browser → bucket directly, so uploads are fast and you do not pay for proxy bandwidth.
• Locally signed downloads. Download URLs are signed without an extra API round-trip.
• Reliable completion. A synchronous confirm step verifies the object really landed in the bucket — no webhooks and no dev tunnels.
• Your bucket, no lock-in. Files live in your own S3-compatible bucket.
• Parallel + multipart, built in. Batches upload several files at once; large files split into parts that upload concurrently — automatically.
• AI-agent native. s3delivery/ai turns the client into ready-made tools for the Vercel AI SDK, with read-only and approval gates.
• Public MCP for coding agents. The public MCP is intentionally tiny: it helps agents write integration code, but it cannot access your account or files.

Add uploads in ~5 lines

Server-side, end to end:

import { S3Delivery } from "s3delivery";

const s3 = new S3Delivery();
const file = await s3.upload(blob, { name: "report.pdf" });
file.url;

From the browser, with the React hook:

import { useUploadFiles } from "s3delivery/react";

const { upload, uploadedFiles, progress, isPending } = useUploadFiles();

<input type="file" multiple onChange={(e) => upload(e.target.files!)} />;

Head to the Quickstart to set up the route handler that keeps your key on the server.

Install

npm i s3delivery

The package ships three entry points:

react and ai are optional peer dependencies — the core SDK only depends on zod.