DX-2982 Upstash blob docs

agent-resources/cli.mdx

@@ -91,6 +91,7 @@ upstash team    # Teams and members
 upstash vector  # Vector indexes
 upstash search  # Search indexes
 upstash qstash  # QStash instances
+upstash blob    # Blob buckets
 ```
 
 Use `--help` on any command or subcommand for details:
@@ -231,3 +232,20 @@ upstash qstash update-budget --qstash-id $QSTASH_ID --budget $BUDGET_DOLLARS   #
 upstash qstash enable-prodpack --qstash-id $QSTASH_ID
 upstash qstash disable-prodpack --qstash-id $QSTASH_ID
 ```
+
+# Blob
+
+```bash
+upstash blob list
+upstash blob get --bucket-id $BUCKET_ID
+upstash blob get --bucket-id $BUCKET_ID --hide-credentials          # omit token and token_next
+upstash blob create --name $NAME --visibility $VISIBILITY           # private (default), public
+upstash blob create --name $NAME --cors $ORIGIN $ORIGIN             # space-separated origins
+upstash blob delete --bucket-id $BUCKET_ID --dry-run
+upstash blob delete --bucket-id $BUCKET_ID
+upstash blob credentials --bucket-id $BUCKET_ID                     # temporary S3 credentials
+upstash blob credentials                                            # from UPSTASH_BLOB_TOKEN
+```
+
+`blob credentials` exchanges a bucket token for temporary, bucket-scoped S3 credentials for use
+with the AWS CLI, rclone, or any S3 SDK. `expiresAt` is the credential's expiry.

blob/bucket/caching.mdx

@@ -0,0 +1,183 @@
+---
+title: "Caching"
+---
+
+This page covers the `cache` option: what `Cache-Control` an object is served with, where to set it, and which value to pick.
+
+```ts
+await bucket.put("avatars/7.png", file, { contentType: "image/png", cache: "immutable" })
+```
+
+`Cache-Control` is written once, at upload, and stored with the object. The CDN and the browser honor it on every read. There is no per-request override; changing it means writing the object again.
+
+---
+
+## Which value to pick
+
+| Object | Path | `cache` | How readers see a change |
+| --- | --- | --- | --- |
+| Unique path per upload (`uniquePath`) | new each time | `'immutable'` | the path is new, nothing to invalidate |
+| Stable path that changes rarely | stable | `'immutable'` plus `versionedUrl` | the URL changes with the etag |
+| Fixed URL you do not control, or a client that drops query strings | stable | `'revalidate'` | a 304 check on every read |
+| Private or sensitive | any | `'no-store'`, or a short duration | the link expires; see [below](#no-store-and-signed-reads) |
+
+---
+
+## The `cache` option
+
+| Value | Stored header |
+| ----- | ------------- |
+| `'immutable'` | `public, max-age=31536000, immutable` |
+| `'revalidate'` | `public, max-age=0, must-revalidate` |
+| `'no-store'` | `no-store` |
+| a duration (`'15m'`, `3600`) | `public, max-age=<seconds>` |
+| unset | `public, max-age=3600` |
+| anything containing `=` or `,` | stored exactly as written |
+
+```ts
+cache: "1h"      // public, max-age=3600
+cache: 3600      // public, max-age=3600
+cache: "15 min"  // public, max-age=900
+cache: "7d"      // public, max-age=604800
+```
+
+A duration is converted to whole seconds, so `'1500ms'` stores `max-age=1`. The grammar is on [Types](/blob/reference/types#duration).
+
+### The raw header
+
+```ts
+cache: "public, max-age=60, s-maxage=31536000"
+cache: "max-age=0, stale-while-revalidate=86400"
+```
+
+Anything containing `=` or `,` is treated as a raw header and stored as written. Use this for `s-maxage`, `stale-while-revalidate`, `no-transform` and anything else the three keywords do not cover.
+
+---
+
+## `revalidate` versus a short max-age
+
+| | `cache: 'revalidate'` | `cache: '60s'` |
+| --- | --- | --- |
+| Unchanged object | 304, no body | full object, once a minute |
+| Object just overwritten | next read sees it | up to 60 s of the old bytes |
+
+`'revalidate'` stores `public, max-age=0, must-revalidate`. The cached copy is checked with `If-None-Match` on every read, so an unchanged object costs a 304 with no body. A short max-age serves stale bytes until it expires, then re-downloads the whole object.
+
+`'revalidate'` costs a round trip per read, but is never stale and never downloads the bytes twice.
+
+---
+
+## Where you can set it
+
+Four places. The most specific one wins.
+
+### On the bucket
+
+```ts lib/blob.ts
+import { Bucket } from "@upstash/blob"
+
+export const bucket = Bucket.fromEnv({ cache: "immutable" })
+```
+
+The default for every object this bucket stores.
+
+### On a put
+
+```ts
+await bucket.put("avatars/7.png", file, {
+  contentType: "image/png",
+  cache: "revalidate",
+})
+```
+
+`updateJson` takes it too, for the object it rewrites. So do `copy` and `move`, for the destination. Without it the source's value carries over.
+
+### On a signed upload URL
+
+```ts
+const upload = await bucket.signedUploadUrl("u/7/report.pdf", {
+  contentType: "application/pdf",
+  cache: "immutable",
+})
+
+await fetch(upload.url, { method: "PUT", headers: upload.headers, body })
+```
+
+Signed into the URL and handed back in `headers`, so the uploader has to send it verbatim.
+
+### On a direct browser upload
+
+```ts lib/uploads.ts
+import { uniquePath, uploadHandler } from "@upstash/blob"
+
+export const uploads = uploadHandler({
+  onBeforeUpload: ({ file }) => ({
+    path: uniquePath`uploads/${file.name}`,
+    cache: "immutable",
+  }),
+})
+```
+
+Decided per upload on your server and signed into the presigned PUT. See [Upload handler](/blob/uploads/upload-handler#onbeforeupload).
+
+---
+
+## Private buckets
+
+| `cache` | Public bucket | Private bucket |
+| ------- | ------------- | -------------- |
+| unset | `public, max-age=3600` | `private, max-age=3600` |
+| `'1m'` | `public, max-age=60` | `private, max-age=60` |
+| `'immutable'` | `public, max-age=31536000, immutable` | `private, max-age=31536000, immutable` |
+| `'revalidate'` | `public, max-age=0, must-revalidate` | `private, max-age=0, must-revalidate` |
+| `'no-store'` | `no-store` | `no-store` |
+
+On a private bucket, `private` replaces `public`, so no shared cache keeps a copy of an object only a signed request may read. This follows the bucket's visibility in the console; nothing in the code declares it.
+
+A raw header string is passed through as written, visibility included: `cache: 'public, max-age=60'` on a private bucket stores `public, max-age=60`.
+
+---
+
+## Immutable plus a versioned URL
+
+```ts app/api/avatar/route.ts
+const blob = await bucket.put(`avatars/${user.id}.png`, file, {
+  contentType: "image/png",
+  cache: "immutable",
+})
+
+await db.users.update(user.id, { avatar: blob.versionedUrl })
+```
+
+```tsx
+<img src={user.avatar} />
+```
+
+`versionedUrl` is `url` with the etag on the query, so it changes whenever the content does. A stable path stored `immutable` and served through `versionedUrl` is cached for a year, and every overwrite produces a URL no cache has seen. The path never moves, so nothing has to be deleted.
+
+`url` and `versionedUrl` are both `undefined` on a private bucket.
+
+---
+
+## `no-store` and signed reads
+
+```ts
+await bucket.put("private/report.pdf", body, {
+  contentType: "application/pdf",
+  cache: "no-store",
+})
+
+const { url, expiresAt } = await bucket.signedReadUrl("private/report.pdf")
+```
+
+These are two separate mechanisms. The link expires at `expiresAt`, but the stored `Cache-Control` outlives it: with a long max-age the reader's browser keeps the bytes after the link stops working. If a reader must not keep the bytes, store the object with `no-store`.
+
+`no-store` drops the visibility scope entirely and stores `no-store` on public and private buckets alike.
+
+See [signedReadUrl](/blob/bucket/reading#signedreadurl) for link lifetimes.
+
+---
+
+## What the upload route itself caches
+
+An upload route's `GET` serves its constraints document with a 60 second `Cache-Control` of its own, unrelated to the objects the route stores. See [Constraints](/blob/uploads/constraints#in-the-browser).

blob/bucket/connecting.mdx

@@ -0,0 +1,112 @@
+---
+title: "Connecting"
+---
+
+This page covers creating the `Bucket` client, the options it takes, and running it on platforms without `process.env`.
+
+```ts lib/blob.ts
+import { Bucket } from "@upstash/blob"
+
+export const bucket = Bucket.fromEnv() // reads UPSTASH_BLOB_TOKEN
+```
+
+Create a bucket in the [Upstash Console](https://console.upstash.com) and put its token in your environment:
+
+```bash .env
+UPSTASH_BLOB_TOKEN=...
+```
+
+The token is a bearer secret. Anything holding it can read and write the whole bucket. Keep it server side, never in `NEXT_PUBLIC_`, `VITE_`, or any other variable your bundler inlines into client code.
+
+---
+
+## Options
+
+```ts lib/blob.ts
+import { Bucket } from "@upstash/blob"
+
+export const bucket = new Bucket({
+  token: process.env.UPSTASH_BLOB_TOKEN!,
+  cache: "immutable",
+  enableTelemetry: false,
+})
+```
+
+`Bucket.fromEnv()` is the same constructor with `token` read from `UPSTASH_BLOB_TOKEN`. It takes the same options minus the token, and a variable name when the token lives somewhere else:
+
+```ts
+Bucket.fromEnv({ cache: "immutable" })
+Bucket.fromEnv("REPORTS_BUCKET_TOKEN", { cache: "immutable" })
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `token` | `string` | required | The bucket token. |
+| `cache` | `CacheOption` | `'1h'` | The default `Cache-Control` for every object this client stores. A per-call `cache` overrides it. See [Caching](/blob/bucket/caching). |
+| `enableTelemetry` | `boolean` | `true` | See [Telemetry](#telemetry). |
+
+Whether the bucket is public or private is a console setting, not an option: the SDK learns it from the backend on the first request. See [Private buckets](/blob/bucket/reading#private-buckets).
+
+Constructing a `Bucket` per request is fine. Credentials are cached per token, so two clients built from the same token share one.
+
+---
+
+## Cloudflare Workers
+
+There is no `process.env` on Workers, so `Bucket.fromEnv()` throws. Pass the token from the request's `env`:
+
+```ts src/index.ts
+import { Bucket } from "@upstash/blob"
+
+export default {
+  async fetch(request: Request, env: { UPSTASH_BLOB_TOKEN: string }) {
+    const bucket = new Bucket({ token: env.UPSTASH_BLOB_TOKEN })
+    await bucket.put("hits.txt", "1")
+    return new Response("ok")
+  },
+}
+```
+
+An [upload handler](/blob/uploads/upload-handler#the-bucket) on Workers needs the same thing: build the bucket from `env` and pass it as `bucket:`.
+
+---
+
+## Telemetry
+
+The SDK sends its version, runtime and platform as headers on credential requests to Upstash. Turn it off with `UPSTASH_DISABLE_TELEMETRY` in the environment (any value), or `enableTelemetry: false` on the `Bucket`.
+
+---
+
+## Using an S3 client
+
+```ts
+import { GetObjectCommand, S3Client } from "@aws-sdk/client-s3"
+import { bucket } from "@/lib/blob"
+
+const { endpoint, region, bucket: name, credentials } = bucket.s3()
+const s3 = new S3Client({ endpoint, region, credentials })
+
+await s3.send(
+  new GetObjectCommand({ Bucket: name, Key: "reports/q3.pdf", Range: "bytes=0-1023" }),
+)
+```
+
+Buckets are backed by Cloudflare R2 and are S3-compatible. `bucket.s3()` returns a config for `@aws-sdk/client-s3`, for anything the SDK does not wrap: byte ranges, conditional GETs, delimiters and common prefixes, object tagging.
+
+`endpoint` and `credentials` are async providers rather than values. Pass them through as they come, so the aws-sdk can pick up a fresh credential when the old one expires.
+
+An error message that mentions R2 is talking about the storage layer.
+
+---
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Writing" href="/blob/bucket/writing">
+    `put`, metadata, conditional writes and multipart from the server.
+  </Card>
+
+  <Card title="Reading" href="/blob/bucket/reading">
+    `get`, `info`, `exists`, `list` and signed read URLs.
+  </Card>
+</CardGroup>