pi-cloudflare 0.1.0

package/skills/cloudflare/references/analytics-engine/gotchas.md

@@ -0,0 +1,85 @@
+# Analytics Engine Gotchas
+
+## Critical Issues
+
+### Sampling at High Volumes
+
+**Problem:** Queries return fewer points than written at >1M writes/min.
+
+**Solution:**
+```typescript
+// Pre-aggregate before writing
+let buffer = { count: 0, total: 0 };
+buffer.count++; buffer.total += value;
+
+// Write once per second instead of per request
+if (Date.now() % 1000 === 0) {
+  env.ANALYTICS.writeDataPoint({ doubles: [buffer.count, buffer.total] });
+}
+```
+
+**Detection:** `npx wrangler tail` → look for "sampling enabled"
+
+### writeDataPoint Returns void
+
+```typescript
+// ❌ Pointless await
+await env.ANALYTICS.writeDataPoint({...});
+
+// ✅ Fire-and-forget
+env.ANALYTICS.writeDataPoint({...});
+```
+
+Writes can fail silently. Check tail logs.
+
+### Index vs Blob
+
+| Cardinality | Use | Example |
+|-------------|-----|---------|
+| Millions | **Index** | user_id, api_key |
+| Hundreds | **Blob** | endpoint, status_code, country |
+
+```typescript
+// ✅ Correct
+{ blobs: [method, path, status], indexes: [userId] }
+```
+
+### Can't Query from Workers
+
+Query API requires HTTP auth. Use external service or cache in KV/D1.
+
+### No Custom Timestamps
+
+Auto-generated at write time. Store original in blob if needed.
+
+## Common Errors
+
+| Error | Fix |
+|-------|-----|
+| Binding not found | Check wrangler.jsonc, redeploy |
+| No data in query | Wait 30s; check dataset name; check time range |
+| Query timeout | Add time filter; use index for filtering |
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Blobs per point | 20 |
+| Doubles per point | 20 |
+| Indexes per point | 1 |
+| Blob/Index size | 16KB |
+| Write rate (no sampling) | ~1M/min |
+| Retention | 90 days |
+| Query timeout | 30s |
+
+## Best Practices
+
+✅ Pre-aggregate at high volumes  
+✅ Use index for high-cardinality (millions)  
+✅ Always include time filter in queries  
+✅ Design schema before coding  
+
+❌ Don't await writeDataPoint  
+❌ Don't use index for low-cardinality  
+❌ Don't query without time range  
+❌ Don't assume all writes succeed

package/skills/cloudflare/references/analytics-engine/patterns.md

@@ -0,0 +1,83 @@
+# Analytics Engine Patterns
+
+## Use Cases
+
+| Use Case | Key Metrics | Index On |
+|----------|-------------|----------|
+| API Metering | requests, bytes, compute_units | api_key |
+| Feature Usage | feature, action, duration | user_id |
+| Error Tracking | error_type, endpoint, count | customer_id |
+| Performance | latency_ms, cache_status | endpoint |
+| A/B Testing | variant, conversions | user_id |
+
+## API Metering (Billing)
+
+```typescript
+env.ANALYTICS.writeDataPoint({
+  blobs: [pathname, method, status, tier],
+  doubles: [1, computeUnits, bytes, latencyMs],
+  indexes: [apiKey]
+});
+
+// Query: Monthly usage by customer
+// SELECT index1 AS api_key, SUM(double2) AS compute_units
+// FROM usage WHERE timestamp >= DATE_TRUNC('month', NOW()) GROUP BY index1
+```
+
+## Error Tracking
+
+```typescript
+env.ANALYTICS.writeDataPoint({
+  blobs: [endpoint, method, errorName, errorMessage.slice(0, 1000)],
+  doubles: [1, timeToErrorMs],
+  indexes: [customerId]
+});
+```
+
+## Performance Monitoring
+
+```typescript
+env.ANALYTICS.writeDataPoint({
+  blobs: [pathname, method, cacheStatus, status],
+  doubles: [latencyMs, 1],
+  indexes: [userId]
+});
+
+// Query: P95 latency by endpoint
+// SELECT blob1, quantile(0.95)(double1) AS p95_ms FROM perf GROUP BY blob1
+```
+
+## Anti-Patterns
+
+| ❌ Wrong | ✅ Correct |
+|----------|-----------|
+| `await writeDataPoint()` | `writeDataPoint()` (fire-and-forget) |
+| `indexes: [method]` (low cardinality) | `blobs: [method]`, `indexes: [userId]` |
+| `blobs: [JSON.stringify(obj)]` | Store ID in blob, full object in D1/KV |
+| Write every request at 10M/min | Pre-aggregate per second |
+| Query from Worker | Query from external service/API |
+
+## Best Practices
+
+1. **Design schema upfront** - Document blob/double/index assignments
+2. **Always include count metric** - `doubles: [latency, 1]` for AVG calculations
+3. **Use enums for blobs** - Consistent values like `Status.SUCCESS`
+4. **Handle sampling** - Use ratios (avg_latency = SUM(latency)/SUM(count))
+5. **Test queries early** - Validate schema before heavy writes
+
+## Schema Template
+
+```typescript
+/**
+ * Dataset: my_metrics
+ * 
+ * Blobs:
+ *   blob1: endpoint, blob2: method, blob3: status
+ * 
+ * Doubles:
+ *   double1: latency_ms, double2: count (always 1)
+ * 
+ * Indexes:
+ *   index1: customer_id (high cardinality)
+ */
+```

package/skills/cloudflare/references/api/README.md

@@ -0,0 +1,66 @@
+# Cloudflare API Integration
+
+Guide for working with Cloudflare's REST API - authentication, SDK usage, common patterns, and troubleshooting.
+
+## Quick Decision Tree
+
+```
+How are you calling the Cloudflare API?
+├─ From Workers runtime → Use bindings, not REST API (see ../bindings/)
+├─ Server-side (Node/Python/Go) → Official SDK (see api.md)
+├─ CLI/scripts → Wrangler or curl (see configuration.md)
+├─ Infrastructure-as-code → See ../pulumi/ or ../terraform/
+└─ One-off requests → curl examples (see api.md)
+```
+
+## SDK Selection
+
+| Language | Package | Best For | Default Retries |
+|----------|---------|----------|-----------------|
+| TypeScript | `cloudflare` | Node.js, Bun, Next.js, Workers | 2 |
+| Python | `cloudflare` | FastAPI, Django, scripts | 2 |
+| Go | `cloudflare-go/v4` | CLI tools, microservices | 10 |
+
+All SDKs are Stainless-generated from OpenAPI spec (consistent APIs).
+
+## Authentication Methods
+
+| Method | Security | Use Case | Scope |
+|--------|----------|----------|-------|
+| **API Token** ✓ | Scoped, rotatable | Production | Per-zone or account |
+| API Key + Email | Full account access | Legacy only | Everything |
+| User Service Key | Limited | Origin CA certs only | Origin CA |
+
+**Always use API tokens** for new projects.
+
+## Rate Limits
+
+| Limit | Value |
+|-------|-------|
+| Per user/token | 1200 requests / 5 minutes |
+| Per IP | 200 requests / second |
+| GraphQL | 320 / 5 minutes (cost-based) |
+
+## Reading Order
+
+| Task | Files to Read |
+|------|---------------|
+| Initialize SDK client | api.md |
+| Configure auth/timeout/retry | configuration.md |
+| Find usage patterns | patterns.md |
+| Debug errors/rate limits | gotchas.md |
+| Product-specific APIs | ../workers/, ../r2/, ../kv/, etc. |
+
+## In This Reference
+
+- **[api.md](api.md)** - SDK client initialization, pagination, error handling, examples
+- **[configuration.md](configuration.md)** - Environment variables, SDK config, Wrangler setup
+- **[patterns.md](patterns.md)** - Real-world patterns, batch operations, workflows
+- **[gotchas.md](gotchas.md)** - Rate limits, SDK-specific issues, troubleshooting
+
+## See Also
+
+- [Cloudflare API Docs](https://developers.cloudflare.com/api/)
+- [Bindings Reference](../bindings/) - Workers runtime bindings (preferred over REST API)
+- [Wrangler Reference](../wrangler/) - CLI tool for Cloudflare development
+- [GraphQL Analytics API Reference](../graphql-api/) - Analytics data via GraphQL (separate endpoint from REST API)

package/skills/cloudflare/references/api/api.md

@@ -0,0 +1,204 @@
+# API Reference
+
+## Client Initialization
+
+### TypeScript
+
+```typescript
+import Cloudflare from 'cloudflare';
+
+const client = new Cloudflare({
+  apiToken: process.env.CLOUDFLARE_API_TOKEN,
+});
+```
+
+### Python
+
+```python
+from cloudflare import Cloudflare
+
+client = Cloudflare(api_token=os.environ.get("CLOUDFLARE_API_TOKEN"))
+
+# For async:
+from cloudflare import AsyncCloudflare
+client = AsyncCloudflare(api_token=os.environ["CLOUDFLARE_API_TOKEN"])
+```
+
+### Go
+
+```go
+import (
+    "github.com/cloudflare/cloudflare-go/v4"
+    "github.com/cloudflare/cloudflare-go/v4/option"
+)
+
+client := cloudflare.NewClient(
+    option.WithAPIToken(os.Getenv("CLOUDFLARE_API_TOKEN")),
+)
+```
+
+## Authentication
+
+### API Token (Recommended)
+
+**Create token**: Dashboard → My Profile → API Tokens → Create Token
+
+```bash
+export CLOUDFLARE_API_TOKEN='your-token-here'
+
+curl "https://api.cloudflare.com/client/v4/zones" \
+  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+```
+
+**Token scopes**: Always use minimal permissions (zone-specific, time-limited).
+
+### API Key (Legacy)
+
+```bash
+curl "https://api.cloudflare.com/client/v4/zones" \
+  --header "X-Auth-Email: user@example.com" \
+  --header "X-Auth-Key: $CLOUDFLARE_API_KEY"
+```
+
+**Not recommended:** Full account access, cannot scope permissions.
+
+## Auto-Pagination
+
+All SDKs support automatic pagination for list operations.
+
+```typescript
+// TypeScript: for await...of
+for await (const zone of client.zones.list()) {
+  console.log(zone.id);
+}
+```
+
+```python
+# Python: iterator protocol
+for zone in client.zones.list():
+    print(zone.id)
+```
+
+```go
+// Go: ListAutoPaging
+iter := client.Zones.ListAutoPaging(ctx, cloudflare.ZoneListParams{})
+for iter.Next() {
+    zone := iter.Current()
+    fmt.Println(zone.ID)
+}
+```
+
+## Error Handling
+
+```typescript
+try {
+  const zone = await client.zones.get({ zone_id: 'xxx' });
+} catch (err) {
+  if (err instanceof Cloudflare.NotFoundError) {
+    // 404
+  } else if (err instanceof Cloudflare.RateLimitError) {
+    // 429 - SDK auto-retries with backoff
+  } else if (err instanceof Cloudflare.APIError) {
+    console.log(err.status, err.message);
+  }
+}
+```
+
+**Common Error Types:**
+- `AuthenticationError` (401) - Invalid token
+- `PermissionDeniedError` (403) - Insufficient scope
+- `NotFoundError` (404) - Resource not found
+- `RateLimitError` (429) - Rate limit exceeded
+- `InternalServerError` (≥500) - Cloudflare error
+
+## Zone Management
+
+```typescript
+// List zones
+const zones = await client.zones.list({
+  account: { id: 'account-id' },
+  status: 'active',
+});
+
+// Create zone
+const zone = await client.zones.create({
+  account: { id: 'account-id' },
+  name: 'example.com',
+  type: 'full', // or 'partial'
+});
+
+// Update zone
+await client.zones.edit('zone-id', {
+  paused: false,
+});
+
+// Delete zone
+await client.zones.delete('zone-id');
+```
+
+```go
+// Go: requires cloudflare.F() wrapper
+zone, err := client.Zones.New(ctx, cloudflare.ZoneNewParams{
+    Account: cloudflare.F(cloudflare.ZoneNewParamsAccount{
+        ID: cloudflare.F("account-id"),
+    }),
+    Name: cloudflare.F("example.com"),
+    Type: cloudflare.F(cloudflare.ZoneNewParamsTypeFull),
+})
+```
+
+## DNS Management
+
+```typescript
+// Create DNS record
+await client.dns.records.create({
+  zone_id: 'zone-id',
+  type: 'A',
+  name: 'subdomain.example.com',
+  content: '192.0.2.1',
+  ttl: 1, // auto
+  proxied: true, // Orange cloud
+});
+
+// List DNS records (with auto-pagination)
+for await (const record of client.dns.records.list({
+  zone_id: 'zone-id',
+  type: 'A',
+})) {
+  console.log(record.name, record.content);
+}
+
+// Update DNS record
+await client.dns.records.update({
+  zone_id: 'zone-id',
+  dns_record_id: 'record-id',
+  type: 'A',
+  name: 'subdomain.example.com',
+  content: '203.0.113.1',
+  proxied: true,
+});
+
+// Delete DNS record
+await client.dns.records.delete({
+  zone_id: 'zone-id',
+  dns_record_id: 'record-id',
+});
+```
+
+```python
+# Python example
+client.dns.records.create(
+    zone_id="zone-id",
+    type="A",
+    name="subdomain.example.com",
+    content="192.0.2.1",
+    ttl=1,
+    proxied=True,
+)
+```
+
+## See Also
+
+- [configuration.md](./configuration.md) - SDK configuration, environment variables
+- [patterns.md](./patterns.md) - Real-world patterns and workflows
+- [gotchas.md](./gotchas.md) - Rate limits, troubleshooting

package/skills/cloudflare/references/api/configuration.md

@@ -0,0 +1,160 @@
+# Configuration
+
+## Environment Variables
+
+### Set Variables
+
+| Platform | Command |
+|----------|---------|
+| Linux/macOS | `export CLOUDFLARE_API_TOKEN='token'` |
+| PowerShell | `$env:CLOUDFLARE_API_TOKEN = 'token'` |
+| Windows CMD | `set CLOUDFLARE_API_TOKEN=token` |
+
+**Security:** Never commit tokens. Use `.env` files (gitignored) or secret managers.
+
+### .env File Pattern
+
+```bash
+# .env (add to .gitignore)
+CLOUDFLARE_API_TOKEN=your-token-here
+CLOUDFLARE_ACCOUNT_ID=your-account-id
+```
+
+```typescript
+// TypeScript
+import 'dotenv/config';
+
+const client = new Cloudflare({
+  apiToken: process.env.CLOUDFLARE_API_TOKEN,
+});
+```
+
+```python
+# Python
+from dotenv import load_dotenv
+load_dotenv()
+
+client = Cloudflare(api_token=os.environ["CLOUDFLARE_API_TOKEN"])
+```
+
+## SDK Configuration
+
+### TypeScript
+
+```typescript
+const client = new Cloudflare({
+  apiToken: process.env.CLOUDFLARE_API_TOKEN,
+  timeout: 120000,        // 2 min (default 60s), in milliseconds
+  maxRetries: 5,          // default 2
+  baseURL: 'https://...', // proxy (rare)
+});
+
+// Per-request overrides
+await client.zones.get(
+  { zone_id: 'zone-id' },
+  { timeout: 5000, maxRetries: 0 }
+);
+```
+
+### Python
+
+```python
+client = Cloudflare(
+    api_token=os.environ["CLOUDFLARE_API_TOKEN"],
+    timeout=120,         # seconds (default 60)
+    max_retries=5,       # default 2
+    base_url="https://...",  # proxy (rare)
+)
+
+# Per-request overrides
+client.with_options(timeout=5, max_retries=0).zones.get(zone_id="zone-id")
+```
+
+### Go
+
+```go
+client := cloudflare.NewClient(
+    option.WithAPIToken(os.Getenv("CLOUDFLARE_API_TOKEN")),
+    option.WithMaxRetries(5),  // default 10 (higher than TS/Python)
+    option.WithRequestTimeout(2 * time.Minute),  // default 60s
+    option.WithBaseURL("https://..."),  // proxy (rare)
+)
+
+// Per-request overrides
+client.Zones.Get(ctx, "zone-id", option.WithMaxRetries(0))
+```
+
+## Configuration Options
+
+| Option | TypeScript | Python | Go | Default |
+|--------|-----------|--------|-----|---------|
+| Timeout | `timeout` (ms) | `timeout` (s) | `WithRequestTimeout` | 60s |
+| Retries | `maxRetries` | `max_retries` | `WithMaxRetries` | 2 (Go: 10) |
+| Base URL | `baseURL` | `base_url` | `WithBaseURL` | api.cloudflare.com |
+
+**Note:** Go SDK has higher default retries (10) than TypeScript/Python (2).
+
+## Timeout Configuration
+
+**When to increase:**
+- Large zone transfers
+- Bulk DNS operations
+- Worker script uploads
+
+```typescript
+const client = new Cloudflare({
+  timeout: 300000, // 5 minutes
+});
+```
+
+## Retry Configuration
+
+**When to increase:** Rate-limit-heavy workflows, flaky network
+
+**When to decrease:** Fast-fail requirements, user-facing requests
+
+```typescript
+// Increase retries for batch operations
+const client = new Cloudflare({ maxRetries: 10 });
+
+// Disable retries for fast-fail
+const fastClient = new Cloudflare({ maxRetries: 0 });
+```
+
+## Wrangler CLI Integration
+
+```bash
+# Configure authentication
+wrangler login
+# Or
+export CLOUDFLARE_API_TOKEN='token'
+
+# Common commands that use API
+wrangler deploy              # Uploads worker via API
+wrangler kv:key put          # KV operations
+wrangler r2 bucket create    # R2 operations
+wrangler d1 execute          # D1 operations
+wrangler pages deploy        # Pages operations
+
+# Get API configuration
+wrangler whoami              # Shows authenticated user
+```
+
+### wrangler.toml
+
+```toml
+name = "my-worker"
+main = "src/index.ts"
+compatibility_date = "2024-01-01"
+account_id = "your-account-id"
+
+# Can also use env vars:
+# CLOUDFLARE_ACCOUNT_ID
+# CLOUDFLARE_API_TOKEN
+```
+
+## See Also
+
+- [api.md](./api.md) - Client initialization, authentication
+- [gotchas.md](./gotchas.md) - Rate limits, timeout errors
+- [Wrangler Reference](../wrangler/) - CLI tool details