update skills

.agents/skills/cloudflare-deploy/references/bindings/api.md

@@ -0,0 +1,203 @@
+# Bindings API Reference
+
+## TypeScript Types
+
+Cloudflare generates binding types via `npx wrangler types`. This creates `.wrangler/types/runtime.d.ts` with your Env interface.
+
+### Generated Env Interface
+
+After running `wrangler types`, TypeScript knows your bindings:
+
+```typescript
+interface Env {
+  // From wrangler.jsonc bindings
+  MY_KV: KVNamespace;
+  MY_BUCKET: R2Bucket;
+  DB: D1Database;
+  MY_SERVICE: Fetcher;
+  AI: Ai;
+  
+  // From vars
+  API_URL: string;
+  
+  // From secrets (set via wrangler secret put)
+  API_KEY: string;
+}
+```
+
+### Binding Types
+
+| Config | TypeScript Type | Package |
+|--------|-----------------|---------|
+| `kv_namespaces` | `KVNamespace` | `@cloudflare/workers-types` |
+| `r2_buckets` | `R2Bucket` | `@cloudflare/workers-types` |
+| `d1_databases` | `D1Database` | `@cloudflare/workers-types` |
+| `durable_objects.bindings` | `DurableObjectNamespace` | `@cloudflare/workers-types` |
+| `vectorize` | `VectorizeIndex` | `@cloudflare/workers-types` |
+| `queues.producers` | `Queue` | `@cloudflare/workers-types` |
+| `services` | `Fetcher` | `@cloudflare/workers-types` |
+| `ai` | `Ai` | `@cloudflare/workers-types` |
+| `browser` | `Fetcher` | `@cloudflare/workers-types` |
+| `analytics_engine_datasets` | `AnalyticsEngineDataset` | `@cloudflare/workers-types` |
+| `hyperdrive` | `Hyperdrive` | `@cloudflare/workers-types` |
+| `rate_limiting` | `RateLimit` | `@cloudflare/workers-types` |
+| `workflows` | `Workflow` | `@cloudflare/workers-types` |
+| `mtls_certificates` / `vars` / `text_blobs` / `data_blobs` | `string` | Built-in |
+| `wasm_modules` | `WebAssembly.Module` | Built-in |
+
+## Accessing Bindings
+
+### Method 1: fetch() Handler (Recommended)
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const value = await env.MY_KV.get('key');
+    return new Response(value);
+  }
+}
+```
+
+**Why:** Type-safe, aligns with Workers API, supports ctx for waitUntil/passThroughOnException.
+
+### Method 2: Hono Framework
+
+```typescript
+import { Hono } from 'hono';
+
+const app = new Hono<{ Bindings: Env }>();
+
+app.get('/', async (c) => {
+  const value = await c.env.MY_KV.get('key');
+  return c.json({ value });
+});
+
+export default app;
+```
+
+**Why:** c.env auto-typed, ergonomic for routing-heavy apps.
+
+### Method 3: Module Workers (Legacy)
+
+```typescript
+export async function handleRequest(request: Request, env: Env): Promise<Response> {
+  const value = await env.MY_KV.get('key');
+  return new Response(value);
+}
+
+addEventListener('fetch', (event) => {
+  // env not directly available - requires workarounds
+});
+```
+
+**Avoid:** Use fetch() handler instead (Method 1).
+
+## Type Generation Workflow
+
+### Initial Setup
+
+```bash
+# Install wrangler
+npm install -D wrangler
+
+# Generate types from wrangler.jsonc
+npx wrangler types
+```
+
+### After Changing Bindings
+
+```bash
+# Added/modified binding in wrangler.jsonc
+npx wrangler types
+
+# TypeScript now sees updated Env interface
+```
+
+**Note:** `wrangler types` outputs to `.wrangler/types/runtime.d.ts`. TypeScript picks this up automatically if `@cloudflare/workers-types` is in `tsconfig.json` `"types"` array.
+
+## Key Binding Methods
+
+**KV:**
+```typescript
+await env.MY_KV.get(key, { type: 'json' });  // text|json|arrayBuffer|stream
+await env.MY_KV.put(key, value, { expirationTtl: 3600 });
+await env.MY_KV.delete(key);
+await env.MY_KV.list({ prefix: 'user:' });
+```
+
+**R2:**
+```typescript
+await env.BUCKET.get(key);
+await env.BUCKET.put(key, value);
+await env.BUCKET.delete(key);
+await env.BUCKET.list({ prefix: 'images/' });
+```
+
+**D1:**
+```typescript
+await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();
+await env.DB.batch([stmt1, stmt2]);
+```
+
+**Service:**
+```typescript
+await env.MY_SERVICE.fetch(new Request('https://fake/path'));
+```
+
+**Workers AI:**
+```typescript
+await env.AI.run('@cf/meta/llama-3.1-8b-instruct', { prompt: 'Hello' });
+```
+
+**Queues:**
+```typescript
+await env.MY_QUEUE.send({ userId: 123, action: 'process' });
+```
+
+**Durable Objects:**
+```typescript
+const id = env.MY_DO.idFromName('user-123');
+const stub = env.MY_DO.get(id);
+await stub.fetch(new Request('https://fake/increment'));
+```
+
+## Runtime vs Build-Time Types
+
+| Type Source | When Generated | Use Case |
+|-------------|----------------|----------|
+| `@cloudflare/workers-types` | npm install | Base Workers APIs (Request, Response, etc.) |
+| `wrangler types` | After config change | Your specific bindings (Env interface) |
+
+**Install both:**
+```bash
+npm install -D @cloudflare/workers-types
+npx wrangler types
+```
+
+## Type Safety Best Practices
+
+1. **Never use `any` for env:**
+```typescript
+// ❌ BAD
+async fetch(request: Request, env: any) { }
+
+// ✅ GOOD
+async fetch(request: Request, env: Env) { }
+```
+
+2. **Run wrangler types after config changes:**
+```bash
+# After editing wrangler.jsonc
+npx wrangler types
+```
+
+3. **Check generated types match config:**
+```bash
+# View generated Env interface
+cat .wrangler/types/runtime.d.ts
+```
+
+## See Also
+
+- [Workers Types Package](https://www.npmjs.com/package/@cloudflare/workers-types)
+- [Wrangler Types Command](https://developers.cloudflare.com/workers/wrangler/commands/#types)