flingit 0.0.52 → 0.0.54

package/templates/default/dot-claude/skills/fling/references/API.md

@@ -457,6 +457,30 @@ if (file) {
 
 **Returns:** `StorageObjectBody | null` (null if not found)
 
+### Range Gets (Partial Reads)
+
+Read a byte range from an object (e.g., seeking into audio/video files):
+
+```typescript
+const chunk = await storage.get("audio/song.mp3", {
+  range: { offset: 1000, length: 500 },
+});
+
+if (chunk) {
+  chunk.size;   // full object size (not the range size)
+  chunk.range;  // { offset: 1000, length: 500 } — actual bytes returned
+  const bytes = await chunk.arrayBuffer(); // only the ranged bytes
+}
+```
+
+**Range rules:**
+- Both `offset` and `length` are **required** when specifying a range
+- `offset` and `length` must be non-negative integers
+- If `length` extends past the end of the object, it is clamped to the available bytes
+- If `offset` is beyond the object size, an error is thrown (except `offset == size` with `length == 0`, which returns an empty body)
+- `size` always reports the full object size; range size is in `result.range.length`
+- The `range` property is only present on the result when a range was requested
+
 ### Checking Existence (Head)
 
 Get metadata without downloading the content:
@@ -583,6 +607,97 @@ npx fling -- --prod storage info    # Production R2 stats
 - **5GB max object size** for direct uploads (streamed, not buffered)
 - **Streaming** - Large files are streamed, not buffered in memory
 
+### Presigned URLs (Direct Browser Upload/Download)
+
+For large files (up to 5GB), create presigned URLs that let browsers upload/download directly to/from R2, bypassing the worker's 100MB request limit.
+
+#### `storage.createUploadUrl(key, options?)`
+
+Create a presigned URL for uploading a file directly to storage.
+
+```typescript
+import { app, storage } from "flingit";
+
+// Worker endpoint that generates an upload URL
+app.post("/api/upload-url", async (c) => {
+  const { filename, contentType } = await c.req.json();
+  const key = `uploads/${Date.now()}-${filename}`;
+
+  const { url, expiresAt } = await storage.createUploadUrl(key, {
+    expiresIn: 600,        // URL valid for 10 minutes (default: 3600)
+    contentType,           // informational, NOT signed into URL
+  });
+
+  return c.json({ url, key, expiresAt: expiresAt.toISOString() });
+});
+```
+
+Frontend code to use the upload URL:
+
+```typescript
+// Get presigned URL from your API
+const { url, key } = await fetch("/api/upload-url", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ filename: file.name, contentType: file.type }),
+}).then(r => r.json());
+
+// Upload directly to R2 (bypasses worker)
+await fetch(url, {
+  method: "PUT",
+  body: file,
+  headers: { "Content-Type": file.type },
+});
+```
+
+**Options (`CreateUploadUrlOptions`):**
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `expiresIn` | `number` | `3600` | URL expiry in seconds (clamped to credential lifetime) |
+| `contentType` | `string` | — | Informational only; NOT signed into URL |
+
+#### `storage.createDownloadUrl(key, options?)`
+
+Create a presigned URL for downloading a file directly from storage.
+
+```typescript
+// Redirect pattern — browser downloads directly from R2
+app.get("/api/download/:key", async (c) => {
+  const key = c.req.param("key");
+  const { url } = await storage.createDownloadUrl(key, {
+    expiresIn: 300,
+    responseContentDisposition: `attachment; filename="${key.split("/").pop()}"`,
+  });
+  return c.redirect(url);
+});
+
+// JSON URL pattern — return URL for frontend to use
+app.get("/api/file-url/:key", async (c) => {
+  const key = c.req.param("key");
+  const { url, expiresAt } = await storage.createDownloadUrl(key);
+  return c.json({ url, expiresAt: expiresAt.toISOString() });
+});
+```
+
+**Options (`CreateDownloadUrlOptions`):**
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `expiresIn` | `number` | `3600` | URL expiry in seconds |
+| `responseContentDisposition` | `string` | — | Override Content-Disposition (e.g., force download) |
+
+**Return type (`PresignedUrl`):**
+| Field | Type | Description |
+|-------|------|-------------|
+| `url` | `string` | The presigned URL for browser use |
+| `expiresAt` | `Date` | When the URL expires |
+
+#### Important Notes
+
+- **Content-Type is NOT signed** into upload URLs — the browser sends it at upload time. This avoids charset mismatch issues.
+- **URLs expire** — default 1 hour, configurable via `expiresIn`. If the URL is near credential expiry, `expiresIn` is clamped to the remaining credential lifetime.
+- **Max file size:** 5GB per upload (R2 single PUT limit).
+- **CORS is configured automatically** on R2 buckets during deploy.
+
 ## WebAssembly (WASM)
 
 Fling supports importing WebAssembly modules in your backend code. This enables using libraries like `@resvg/resvg-wasm` for SVG rendering, image processing, and other compute-intensive tasks.