@lunora/storage 1.0.0-alpha.7 → 1.0.0-alpha.70

package/README.md

@@ -34,7 +34,7 @@
 
 ---
 
-R2-backed file storage for Lunora. Wraps a Cloudflare `R2Bucket` binding with a typed API (`upload`/`store`, `download`, `delete`, `list`, `getMetadata`, multipart), worker-signed URLs for app-gated access, and native S3 presigned URLs for direct-to-R2 transfer.
+R2-backed file storage for Lunora. Wraps a Cloudflare `R2Bucket` binding with a typed API (`upload`/`store`, `download`, `head`, `delete`, `list`, `getMetadata`, multipart), worker-signed URLs for app-gated access, and native S3 presigned URLs for direct-to-R2 transfer.
 
 Part of the [Lunora](https://github.com/anolilab/lunora) framework — a type-safe, real-time backend on Cloudflare Workers + Durable Objects with a Vite-first DX.
 
@@ -75,13 +75,15 @@ export default defineApp<Env>()
 import { action, v } from "@/lunora/_generated/server";
 
 // Minting an upload URL is a write capability, so this is an `action`.
-// Queries and mutations get a read-only `ctx.storage`; the full surface
-// (generateUploadUrl/store/delete/multipart) is action-only.
+// Queries and mutations are TYPED with a read-only `ctx.storage`; the full
+// surface (generateUploadUrl/store/delete/getPresignedUrl) is action-only.
+// Multipart and `list` are on a `createStorage` instance, not on any ctx.
 export const uploadAvatar = action.input({ contentType: v.string() }).action(async ({ args, ctx }) => {
     const key = `avatars/${ctx.auth.userId ?? "anonymous"}/profile`;
 
-    // Short-lived signed PUT URL — the client uploads straight to R2 through
-    // your Worker route, with the Content-Type pinned into the signature.
+    // Short-lived signed PUT URL — the client uploads to your Worker route,
+    // which verifies the signature and writes to R2, with the Content-Type
+    // pinned into that signature.
     const url = await ctx.storage.generateUploadUrl(key, { contentType: args.contentType, expiresInSeconds: 60 });
 
     return { key, url };
@@ -95,6 +97,12 @@ import { createStorage } from "@lunora/storage";
 
 const storage = createStorage({
     bucket: env.FILES,
+    // Required. The name this bucket is registered under, bound into every signed
+    // URL's HMAC (and mirrored as `&bucket=`), so a URL minted for one bucket
+    // cannot be replayed against another sharing the signing secret. `"default"`
+    // for a single-bucket app; the registered name for anything reached through
+    // `createBucketStorage`.
+    bucketName: "default",
     publicBaseUrl: "https://cdn.acme.test",
     signingSecret: env.STORAGE_SECRET,
 });
@@ -104,12 +112,12 @@ await storage.upload("uploads/avatar.png", bytes, { contentType: "image/png", ma
 const url = await storage.getSignedUrl("uploads/avatar.png", { expiresInSeconds: 600 });
 ```
 
-> This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/addons/storage)**.
+> This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/packages/storage)**.
 
 ## Related
 
 - [`@lunora/server`](https://www.npmjs.com/package/@lunora/server) — call storage from queries, mutations, and actions.
-- [`@lunora/runtime`](https://www.npmjs.com/package/@lunora/runtime) — the Worker runtime that serves gated `GET /storage/:key` routes.
+- [`@lunora/runtime`](https://www.npmjs.com/package/@lunora/runtime) — the Worker runtime your signed-URL route sits in front of. It ships no public storage route of its own: the route that verifies a signed URL and moves the bytes is yours to add (see the `storage` registry item).
 - [`@lunora/d1`](https://www.npmjs.com/package/@lunora/d1) — store object metadata alongside your data.
 
 ## Supported Node.js Versions