flingit 0.0.9 → 0.0.11

package/templates/default/CLAUDE.md

@@ -50,7 +50,7 @@ Just edit and save - changes appear immediately.
 All primitives are imported from `"flingit"` in the backend:
 
 ```typescript
-import { app, db, migrate, secrets, cron } from "flingit";
+import { app, db, migrate, secrets, cron, storage } from "flingit";
 ```
 
 ### HTTP Routes (Hono)
@@ -129,6 +129,49 @@ npm exec fling cron history <name> # View invocation history
 npm exec fling cron trigger <name> # Manually trigger a job
 ```
 
+### Storage (R2)
+
+Store and retrieve files. Uses local filesystem in development, Cloudflare R2 in production.
+
+```typescript
+import { storage } from "flingit";
+
+// Store objects
+await storage.put("images/logo.png", imageBuffer, { contentType: "image/png" });
+await storage.put("data/config.json", JSON.stringify(config));
+
+// Retrieve objects
+const file = await storage.get("images/logo.png");
+if (file) {
+  const buffer = await file.arrayBuffer();
+  const text = await file.text();
+  const json = await file.json<ConfigType>();
+  // Or stream: file.body (ReadableStream)
+}
+
+// Check existence without downloading
+const meta = await storage.head("images/logo.png");
+
+// Delete objects
+await storage.delete("old-file.txt");
+await storage.delete(["file1.txt", "file2.txt"]); // Batch delete
+
+// List objects
+const result = await storage.list({ prefix: "images/", limit: 100 });
+for (const obj of result.objects) {
+  console.log(`${obj.key}: ${obj.size} bytes`);
+}
+```
+
+Manage storage with CLI:
+```bash
+npm exec fling storage list              # List local storage objects
+npm exec fling storage put key file.txt  # Upload file to storage
+npm exec fling storage get key output    # Download object to file
+npm exec fling storage delete key --yes  # Delete object
+npm exec fling storage info              # Show storage stats
+```
+
 ## React Frontend
 
 The frontend is a standard React + Vite setup. Call the backend API:
@@ -155,22 +198,27 @@ npm exec fling db sql "SELECT * FROM users"  # Query local SQLite
 npm exec fling secret set K=V   # Set local secret
 npm exec fling secret list      # List local secrets
 npm exec fling logs             # View local logs
+npm exec fling storage list     # List storage objects
+npm exec fling storage put K F  # Upload file F as key K
+npm exec fling storage get K O  # Download key K to file O
 npm exec fling push             # Build and deploy to production
 ```
 
 ### Local vs Production (`--prod`)
 
-Most CLI commands operate on the **local** environment by default. Add `--prod` for production (logs and db only):
+Most CLI commands operate on the **local** environment by default. Add `--prod` for production:
 
 ```bash
 # Local (default)
 npm exec fling secret list              # Local secrets
 npm exec fling logs                     # Local logs
 npm exec fling db sql "SELECT 1"        # Local SQLite
+npm exec fling storage list             # Local storage
 
 # Production (requires login)
 npm exec fling -- --prod logs              # Deployed logs
 npm exec fling -- --prod db sql "SELECT 1" # Deployed D1
+npm exec fling -- --prod storage list      # R2 storage
 ```
 
 **Note:** Production logs have a delay of ~10 seconds or more before they appear.
@@ -198,8 +246,8 @@ npm exec fling -- --prod db sql "SELECT 1" # Deployed D1
 Be aware of these constraints when building:
 
 ### Feature Scope
-- **Supported:** Frontend (React), backend (Hono API), database (SQLite/D1), cron jobs
-- **Not yet supported:** File/blob storage, websockets
+- **Supported:** Frontend (React), backend (Hono API), database (SQLite/D1), cron jobs, file storage (R2), Discord integration
+- **Not yet supported:** Websockets
 - If the user needs unsupported features, encourage them to send feedback via `npm exec fling feedback`
 
 ### Backend Memory (128MB limit)
@@ -216,11 +264,16 @@ Be aware of these constraints when building:
 
 ### Backend Assets (Images, Fonts, etc.)
 
-If the backend needs to return or process an asset (image, icon, font), keep it small and embed it directly in the code as base64:
+If the backend needs to return or process an asset (image, icon, font), keep it small and store the base64 data in a separate file to keep your main code clean:
+
+```typescript
+// src/worker/assets/favicon.ts - separate file for the asset
+export const FAVICON_BASE64 = "iVBORw0KGgo..."; // base64-encoded PNG
+```
 
 ```typescript
-// Small assets should be base64 encoded directly in the code
-const FAVICON_BASE64 = "iVBORw0KGgo..."; // base64-encoded PNG
+// src/worker/index.ts - import and use the asset
+import { FAVICON_BASE64 } from "./assets/favicon";
 
 app.get("/favicon.ico", (c) => {
   const buffer = Uint8Array.from(atob(FAVICON_BASE64), c => c.charCodeAt(0));
@@ -230,10 +283,10 @@ app.get("/favicon.ico", (c) => {
 });
 ```
 
-This is necessary because:
-- Workers have limited memory (~128MB)
-- There's no built-in asset serving for backend code
-- Base64 keeps assets bundled with the code
+This approach:
+- Keeps the main code readable (no long base64 strings inline)
+- Makes assets easy to find and update
+- Base64 keeps assets bundled with the code (required for Workers)
 
 **For large assets:** Serve them from the frontend (`public/` folder) instead.
 
@@ -260,3 +313,4 @@ Slugs must be:
 - Globally unique across all Fling projects
 
 See `.claude/skills/fling/` for detailed API documentation.
+See `.claude/skills/discord/` for Discord chatops integration (slash commands, messages, interactions).

package/templates/default/skills/discord/SKILL.md

@@ -0,0 +1,328 @@
+# Discord Skill
+
+Build Discord chatops bots with Fling. Add slash commands, send messages, handle interactions, and react to events — all from your Fling project.
+
+## Setup
+
+Discord requires a one-time setup before use:
+
+```bash
+npm exec fling plugin install discord    # Connect Discord account (opens browser)
+npm exec fling plugin discord add-server # Claim a server for your project
+npm exec fling push                      # Deploy code + register slash commands
+```
+
+Run these commands yourself — you have bash access.
+
+## Quick Reference
+
+```typescript
+import { app } from "flingit";
+import { discord } from "flingit/plugin/discord";
+
+// 1. Define slash commands (synced to Discord on `fling push`)
+export const commands = discord.defineCommands([
+  { name: "ping", description: "Check bot latency" },
+  {
+    name: "deploy",
+    description: "Deploy a branch",
+    options: [
+      { name: "branch", type: "string", description: "Branch name", required: true }
+    ]
+  }
+]);
+
+// 2. Handle slash commands on POST /discord
+app.post("/discord", async (c) => {
+  const interaction = await discord.verifyInteraction(c);
+
+  if (interaction.data?.name === "ping") {
+    await discord.replyToInteraction(interaction, {
+      content: "Pong!",
+      ephemeral: true  // Only visible to the user who ran the command
+    });
+  }
+
+  if (interaction.data?.name === "deploy") {
+    const branch = interaction.data.options?.[0]?.value as string;
+    await discord.replyToInteraction(interaction, {
+      content: `Deploying ${branch}...`
+    });
+
+    // Do work after the initial reply...
+    const result = await runDeploy(branch);
+
+    // Send a followup message (no 3-second limit)
+    await discord.sendFollowup(interaction, {
+      content: `Deployed ${branch}: ${result}`
+    });
+  }
+
+  return c.json({ ok: true });
+});
+
+// 3. Send messages proactively (e.g., from webhooks or cron)
+app.post("/api/notify", async (c) => {
+  const { channelId, text } = await c.req.json();
+
+  await discord.sendMessage({
+    channelId,
+    content: text
+  });
+
+  return c.json({ sent: true });
+});
+```
+
+## API Reference
+
+All methods are imported from `"flingit/plugin/discord"`:
+
+```typescript
+import { discord } from "flingit/plugin/discord";
+```
+
+### discord.defineCommands(commands)
+
+Register slash commands. **Must be exported** as a top-level `export const commands` for `fling push` to detect them.
+
+```typescript
+export const commands = discord.defineCommands([
+  { name: "status", description: "Show system status" },
+  {
+    name: "lookup",
+    description: "Look up a user",
+    options: [
+      { name: "email", type: "string", description: "User email", required: true },
+      { name: "verbose", type: "boolean", description: "Show full details" }
+    ]
+  }
+]);
+```
+
+**Command names:** 1-32 chars, lowercase letters, numbers, and hyphens only.
+
+**Option types:** `"string"`, `"integer"`, `"boolean"`, `"user"`, `"channel"`, `"role"`
+
+Options can have predefined choices:
+
+```typescript
+{
+  name: "env",
+  type: "string",
+  description: "Target environment",
+  required: true,
+  choices: [
+    { name: "Production", value: "prod" },
+    { name: "Staging", value: "staging" }
+  ]
+}
+```
+
+### discord.verifyInteraction(c)
+
+Parse an incoming Discord interaction from a Hono request context. Call this in your `POST /discord` handler.
+
+```typescript
+app.post("/discord", async (c) => {
+  const interaction = await discord.verifyInteraction(c);
+
+  // interaction.data.name = command name
+  // interaction.data.options = command arguments
+  // interaction.member.user = who ran the command (in servers)
+  // interaction.guild_id = which server
+  // interaction.channel_id = which channel
+});
+```
+
+The platform verifies Discord's cryptographic signature before forwarding to your code — you don't need to handle that.
+
+### discord.replyToInteraction(interaction, options)
+
+Reply to a slash command. **Must be called within 3 seconds** of receiving the interaction.
+
+```typescript
+await discord.replyToInteraction(interaction, {
+  content: "Hello!",              // Text content (max 2000 chars)
+  ephemeral: true,                // Only visible to command user (optional)
+  embeds: [{                      // Rich embeds (optional, max 10)
+    title: "Status",
+    description: "All systems operational",
+    color: 0x00ff00
+  }]
+});
+```
+
+### discord.sendFollowup(interaction, options)
+
+Send additional messages after the initial reply. No 3-second time limit.
+
+```typescript
+await discord.replyToInteraction(interaction, { content: "Working on it..." });
+
+// ... do async work ...
+
+const msg = await discord.sendFollowup(interaction, {
+  content: "Done! Here are the results.",
+  embeds: [{ title: "Results", description: resultText }]
+});
+// Returns: { id, channelId, content }
+```
+
+### discord.sendMessage(options)
+
+Send a message to any channel in a claimed server. Use this for notifications, alerts, or proactive messages.
+
+```typescript
+const msg = await discord.sendMessage({
+  channelId: "123456789012345678",
+  content: "Deployment complete!",
+  embeds: [{
+    title: "Deploy Report",
+    description: "v2.1.0 is now live",
+    color: 0x00ff00,
+    fields: [
+      { name: "Duration", value: "42s", inline: true },
+      { name: "Status", value: "Success", inline: true }
+    ],
+    timestamp: new Date().toISOString()
+  }]
+});
+// Returns: { id, channelId, content }
+```
+
+The channel must be in a server claimed by your project.
+
+### discord.editMessage(channelId, messageId, options)
+
+Edit a previously sent message.
+
+```typescript
+const msg = await discord.sendMessage({
+  channelId: channel,
+  content: "Deploying..."
+});
+
+// Later, update it
+await discord.editMessage(channel, msg.id, {
+  content: "Deploy complete!",
+  embeds: [{ title: "Done", color: 0x00ff00 }]
+});
+```
+
+### discord.addReaction(channelId, messageId, emoji)
+
+Add an emoji reaction to a message.
+
+```typescript
+await discord.addReaction(channelId, messageId, "✅");
+await discord.addReaction(channelId, messageId, "🚀");
+```
+
+## Embeds
+
+Rich embeds support these fields:
+
+```typescript
+const embed: DiscordEmbed = {
+  title: "Title text",
+  description: "Body text (supports markdown)",
+  color: 0xff5733,              // Hex color as number
+  url: "https://example.com",   // Makes title a link
+  timestamp: new Date().toISOString(),
+  footer: { text: "Footer text", icon_url: "https://..." },
+  author: { name: "Author", url: "https://...", icon_url: "https://..." },
+  fields: [                     // Up to 25 fields
+    { name: "Field 1", value: "Value 1", inline: true },
+    { name: "Field 2", value: "Value 2", inline: true }
+  ]
+};
+```
+
+Content max: 2000 characters. Embeds max: 10 per message.
+
+## Reading Command Options
+
+Access option values from `interaction.data.options`:
+
+```typescript
+app.post("/discord", async (c) => {
+  const interaction = await discord.verifyInteraction(c);
+
+  if (interaction.data?.name === "deploy") {
+    const options = interaction.data.options ?? [];
+    const branch = options.find(o => o.name === "branch")?.value as string;
+    const force = options.find(o => o.name === "force")?.value as boolean ?? false;
+
+    await discord.replyToInteraction(interaction, {
+      content: `Deploying ${branch}${force ? " (force)" : ""}...`
+    });
+  }
+
+  return c.json({ ok: true });
+});
+```
+
+## Interaction Context
+
+Access who ran the command and where:
+
+```typescript
+app.post("/discord", async (c) => {
+  const interaction = await discord.verifyInteraction(c);
+
+  // Who ran it
+  const user = interaction.member?.user;  // In servers
+  // user.id, user.username
+
+  // Where
+  const guildId = interaction.guild_id;     // Server ID
+  const channelId = interaction.channel_id; // Channel ID
+
+  // Permissions
+  const roles = interaction.member?.roles;        // Role IDs
+  const perms = interaction.member?.permissions;  // Permission bitfield
+});
+```
+
+## CLI Commands
+
+```bash
+# Setup
+npm exec fling plugin install discord      # Connect Discord (OAuth)
+npm exec fling plugin discord add-server   # Claim a server
+npm exec fling plugin discord remove-server # Release a server
+
+# Status
+npm exec fling plugin permissions discord  # Show connection status + servers
+
+# Deployment (registers slash commands automatically)
+npm exec fling push
+
+# Teardown
+npm exec fling plugin remove discord       # Disconnect, release all servers
+```
+
+## How It Works
+
+1. **`fling plugin install discord`** opens a browser for Discord OAuth. You authorize Fling to see your servers and add the bot.
+2. **`fling plugin discord add-server`** claims a Discord server for your project. Each server can only be claimed by one project.
+3. **`export const commands = discord.defineCommands([...])`** in your code defines slash commands. `fling push` extracts them and registers them with Discord in all claimed servers.
+4. When a user runs a slash command, Discord sends it to the platform, which routes it to your worker's `POST /discord` endpoint.
+5. Your code calls `discord.verifyInteraction(c)` to parse it and `discord.replyToInteraction()` to respond.
+
+## Important Constraints
+
+1. **Discord features only work in deployed workers** — They throw errors locally. Use `fling push` to deploy, then test in Discord.
+
+2. **Reply within 3 seconds** — `replyToInteraction()` must be called within 3 seconds. For slow operations, reply immediately with "Working..." then use `sendFollowup()` for the result.
+
+3. **Commands must be exported** — `fling push` looks for `export const commands = discord.defineCommands(...)`. If the export is missing, commands won't be registered.
+
+4. **Handle interactions at POST /discord** — The platform routes all interactions to this exact path on your worker.
+
+5. **Channels must be in claimed servers** — `sendMessage()`, `editMessage()`, and `addReaction()` only work in channels belonging to servers claimed by your project.
+
+6. **One project per server** — A Discord server can only be claimed by one Fling project at a time.
+
+7. **Plugin must be installed first** — Run `fling plugin install discord` before using any Discord features. Check with `fling plugin permissions discord`.

package/templates/default/skills/fling/API.md

@@ -333,6 +333,214 @@ Secret names must be uppercase with underscores:
 - `apiKey` ✗
 - `github-token` ✗
 
+## Storage (R2)
+
+Object storage for files and binary data. Uses local filesystem in development, Cloudflare R2 in production.
+
+### Basic Usage
+
+```typescript
+import { storage } from "flingit";
+
+// Store a file
+await storage.put("images/logo.png", imageBuffer, { contentType: "image/png" });
+
+// Retrieve a file
+const file = await storage.get("images/logo.png");
+if (file) {
+  const buffer = await file.arrayBuffer();
+  console.log(`Downloaded ${file.size} bytes`);
+}
+```
+
+### Storing Objects
+
+```typescript
+// String content (auto-detects content type from key extension)
+await storage.put("data/config.json", JSON.stringify({ setting: true }));
+
+// Binary data
+const imageBuffer = await fetch("https://example.com/image.png").then(r => r.arrayBuffer());
+await storage.put("images/photo.png", imageBuffer, { contentType: "image/png" });
+
+// From request body (streaming)
+app.post("/api/upload", async (c) => {
+  const body = await c.req.arrayBuffer();
+  const result = await storage.put("uploads/file.bin", body);
+  return c.json({ key: result.key, size: result.size });
+});
+
+// With custom metadata
+await storage.put("documents/report.pdf", pdfBuffer, {
+  contentType: "application/pdf",
+  customMetadata: { uploadedBy: "user123", version: "2" }
+});
+```
+
+**Returns:** `StorageObject` with metadata:
+```typescript
+{
+  key: string;        // Object key
+  size: number;       // Size in bytes
+  etag: string;       // Content hash
+  uploaded: Date;     // Upload timestamp
+  contentType?: string;
+  customMetadata?: Record<string, string>;
+}
+```
+
+### Retrieving Objects
+
+```typescript
+const file = await storage.get("images/logo.png");
+
+if (file) {
+  // Read as different formats
+  const buffer = await file.arrayBuffer();  // Raw bytes
+  const text = await file.text();           // UTF-8 string
+  const json = await file.json<MyType>();   // Parsed JSON
+
+  // Or stream the body
+  const stream = file.body;  // ReadableStream<Uint8Array>
+
+  // Access metadata
+  console.log(file.key);           // "images/logo.png"
+  console.log(file.size);          // 12800
+  console.log(file.etag);          // '"abc123"'
+  console.log(file.uploaded);      // Date object
+  console.log(file.contentType);   // "image/png"
+  console.log(file.customMetadata);// { uploadedBy: "user123" }
+}
+```
+
+**Returns:** `StorageObjectBody | null` (null if not found)
+
+### Checking Existence (Head)
+
+Get metadata without downloading the content:
+
+```typescript
+const meta = await storage.head("images/logo.png");
+
+if (meta) {
+  console.log(`File exists: ${meta.size} bytes`);
+  console.log(`Uploaded: ${meta.uploaded}`);
+  console.log(`Content-Type: ${meta.contentType}`);
+} else {
+  console.log("File not found");
+}
+```
+
+**Returns:** `StorageObject | null` (same as put result, null if not found)
+
+### Deleting Objects
+
+```typescript
+// Delete single object
+await storage.delete("old-file.txt");
+
+// Delete multiple objects (batch)
+await storage.delete(["file1.txt", "file2.txt", "file3.txt"]);
+```
+
+**Returns:** `void` (no error if object doesn't exist)
+
+### Listing Objects
+
+```typescript
+// List all objects
+const result = await storage.list();
+for (const obj of result.objects) {
+  console.log(`${obj.key}: ${obj.size} bytes`);
+}
+
+// Filter by prefix
+const images = await storage.list({ prefix: "images/" });
+
+// Pagination
+const page1 = await storage.list({ limit: 100 });
+if (page1.truncated) {
+  const page2 = await storage.list({ limit: 100, cursor: page1.cursor });
+}
+```
+
+**Options:**
+```typescript
+{
+  prefix?: string;   // Filter to keys starting with this
+  cursor?: string;   // Pagination cursor from previous response
+  limit?: number;    // Max results (default 1000, max 1000)
+}
+```
+
+**Returns:**
+```typescript
+{
+  objects: StorageObject[];  // Array of object metadata
+  truncated: boolean;        // true if more results available
+  cursor?: string;           // Use in next request for pagination
+}
+```
+
+### Serving Files via HTTP
+
+```typescript
+app.get("/files/:key", async (c) => {
+  const key = c.req.param("key");
+  const file = await storage.get(key);
+
+  if (!file) {
+    return c.text("Not found", 404);
+  }
+
+  return new Response(file.body, {
+    headers: {
+      "Content-Type": file.contentType ?? "application/octet-stream",
+      "Content-Length": String(file.size),
+      "ETag": file.etag,
+    }
+  });
+});
+```
+
+### Key Naming Rules
+
+- **Max length:** 1024 characters
+- **Cannot start with:** `/`
+- **Cannot contain:** `..`
+- Use path-like structure for organization: `images/2024/photo.png`
+
+### CLI Commands
+
+```bash
+# List objects
+npm exec fling storage list              # Local storage
+npm exec fling -- --prod storage list    # Production R2
+npm exec fling storage list images/      # Filter by prefix
+
+# Upload file
+npm exec fling storage put images/logo.png ./logo.png
+npm exec fling storage put data.json - < data.json  # From stdin
+
+# Download file
+npm exec fling storage get images/logo.png ./output.png
+npm exec fling storage get data.json     # Output to stdout
+
+# Delete object
+npm exec fling storage delete old-file.txt --yes
+
+# Storage info
+npm exec fling storage info              # Local stats
+npm exec fling -- --prod storage info    # Production R2 stats
+```
+
+### Important Notes
+
+- **Storage is provisioned automatically** on first `fling push` - no setup required
+- **Keys are flat** - `images/logo.png` is just a string, not a directory structure
+- **100MB max object size** for direct uploads
+- **Streaming** - Large files are streamed, not buffered in memory
+
 ## 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.