codexkit 1.0.0

package/.codex/skills/cloudflare/references/stream/configuration.md

@@ -0,0 +1,127 @@
+# Stream Configuration
+
+Setup, environment variables, and wrangler configuration.
+
+## Environment Variables
+
+```bash
+# Required
+CF_ACCOUNT_ID=your-account-id
+CF_API_TOKEN=your-api-token
+
+# For signed URLs (high volume)
+STREAM_KEY_ID=your-key-id
+STREAM_JWK=base64-encoded-jwk
+
+# For webhooks
+WEBHOOK_SECRET=your-webhook-secret
+
+# Customer subdomain (from dashboard)
+STREAM_CUSTOMER_CODE=your-customer-code
+```
+
+## Wrangler Configuration
+
+```jsonc
+{
+  "name": "stream-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01", // Use current date for new projects
+  "vars": {
+    "CF_ACCOUNT_ID": "your-account-id"
+  }
+  // Store secrets: wrangler secret put CF_API_TOKEN
+  // wrangler secret put STREAM_KEY_ID
+  // wrangler secret put STREAM_JWK
+  // wrangler secret put WEBHOOK_SECRET
+}
+```
+
+## Signing Keys (High Volume)
+
+Create once for self-signing tokens (thousands of daily users).
+
+**Create key**
+```bash
+curl -X POST \
+  "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/keys" \
+  -H "Authorization: Bearer <API_TOKEN>"
+
+# Save `id` and `jwk` (base64) from response
+```
+
+**Store in secrets**
+```bash
+wrangler secret put STREAM_KEY_ID
+wrangler secret put STREAM_JWK
+```
+
+## Webhooks
+
+**Setup webhook URL**
+```bash
+curl -X PUT \
+  "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/webhook" \
+  -H "Authorization: Bearer <API_TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{"notificationUrl": "https://your-worker.workers.dev/webhook"}'
+
+# Save the returned `secret` for signature verification
+```
+
+**Store secret**
+```bash
+wrangler secret put WEBHOOK_SECRET
+```
+
+## Direct Upload / Live / Watermark Config
+
+```typescript
+// Direct upload
+const uploadConfig = {
+  maxDurationSeconds: 3600,
+  expiry: new Date(Date.now() + 3600000).toISOString(),
+  requireSignedURLs: true,
+  allowedOrigins: ['https://yourdomain.com'],
+  meta: { creator: 'user-123' }
+};
+
+// Live input
+const liveConfig = {
+  recording: { mode: 'automatic', timeoutSeconds: 30 },
+  deleteRecordingAfterDays: 30
+};
+
+// Watermark
+const watermark = {
+  name: 'Logo', opacity: 0.7, padding: 20,
+  position: 'lowerRight', scale: 0.15
+};
+```
+
+## Access Rules & Player Config
+
+```typescript
+// Access rules: allow US/CA, block CN/RU, or IP allowlist
+const geoRestrict = [
+  { type: 'ip.geoip.country', action: 'allow', country: ['US', 'CA'] },
+  { type: 'any', action: 'block' }
+];
+
+// Player params for iframe
+const playerParams = new URLSearchParams({
+  autoplay: 'true', muted: 'true', preload: 'auto', defaultTextTrack: 'en'
+});
+```
+
+## In This Reference
+
+- [README.md](./README.md) - Overview and quick start
+- [api.md](./api.md) - Upload, playback, live streaming APIs
+- [patterns.md](./patterns.md) - Full-stack flows, best practices
+- [gotchas.md](./gotchas.md) - Error codes, troubleshooting
+
+## See Also
+
+- [wrangler](../wrangler/) - Wrangler CLI and configuration
+- [workers](../workers/) - Deploy Stream APIs in Workers

package/.codex/skills/cloudflare/references/stream/gotchas.md

@@ -0,0 +1,131 @@
+# Stream Gotchas
+
+Common issues, troubleshooting, and limits.
+
+## Common Errors
+
+### ERR_NON_VIDEO
+**Cause**: Uploaded file is not a valid video format
+
+**Solution**: Ensure file is in supported format (MP4, MKV, MOV, AVI, FLV, MPEG-2 TS/PS, MXF, LXF, GXF, 3GP, WebM, MPG, QuickTime)
+
+### ERR_DURATION_EXCEED_CONSTRAINT
+**Cause**: Video duration exceeds `maxDurationSeconds` constraint
+
+**Solution**: Increase `maxDurationSeconds` in direct upload config or trim video before upload
+
+### ERR_FETCH_ORIGIN_ERROR
+**Cause**: Failed to download video from URL (upload from URL)
+
+**Solution**: Ensure URL is publicly accessible, uses HTTPS, and video file is available
+
+### ERR_MALFORMED_VIDEO
+**Cause**: Video file is corrupted or improperly encoded
+
+**Solution**: Re-encode video using FFmpeg or check source file integrity
+
+### ERR_DURATION_TOO_SHORT
+**Cause**: Video must be at least 0.1 seconds long
+
+**Solution**: Ensure video has valid duration (not a single frame)
+
+## Troubleshooting
+
+### Video stuck in "inprogress" state
+- **Cause**: Processing large/complex video
+- **Solution**: Wait up to 5 minutes for processing; use webhooks instead of polling
+
+### Signed URL returns 403
+- **Cause**: Token expired or invalid signature
+- **Solution**: Check expiration timestamp, verify JWK is correct, ensure clock sync
+
+### Live stream not connecting
+- **Cause**: Invalid RTMPS URL or stream key
+- **Solution**: Use exact URL/key from API, ensure firewall allows outbound 443
+
+### Webhook signature verification fails
+- **Cause**: Incorrect secret or timestamp window
+- **Solution**: Use exact secret from webhook setup, allow 5-minute timestamp drift
+
+### Video uploads but isn't visible
+- **Cause**: `requireSignedURLs` enabled without providing token
+- **Solution**: Generate signed token or set `requireSignedURLs: false` for public videos
+
+### Player shows infinite loading
+- **Cause**: CORS issue with allowedOrigins
+- **Solution**: Add your domain to `allowedOrigins` array
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Max file size | 30 GB |
+| Max frame rate | 60 fps (recommended) |
+| Max duration per direct upload | Configurable via `maxDurationSeconds` |
+| Token generation (API endpoint) | 1,000/day recommended (use signing keys for higher) |
+| Live input outputs (simulcast) | 5 per live input |
+| Webhook retry attempts | 5 (exponential backoff) |
+| Webhook timeout | 30 seconds |
+| Caption file size | 5 MB |
+| Watermark image size | 2 MB |
+| Metadata keys per video | Unlimited |
+| Search results per page | Max 1,000 |
+
+## Performance Issues
+
+### Upload is slow
+- **Cause**: Large file size or network constraints
+- **Solution**: Use TUS resumable upload, compress video before upload, check bandwidth
+
+### Playback buffering
+- **Cause**: Network congestion or low bandwidth
+- **Solution**: Use ABR (adaptive bitrate) with HLS/DASH, reduce max bitrate
+
+### High processing time
+- **Cause**: Complex video codec, high resolution
+- **Solution**: Pre-encode with H.264 (most efficient), reduce resolution
+
+## Type Safety
+
+```typescript
+// Error response type
+interface StreamError {
+  success: false;
+  errors: Array<{
+    code: number;
+    message: string;
+  }>;
+}
+
+// Handle errors
+async function uploadWithErrorHandling(url: string, file: File) {
+  const formData = new FormData();
+  formData.append('file', file);
+  const response = await fetch(url, { method: 'POST', body: formData });
+  const result = await response.json();
+  
+  if (!result.success) {
+    throw new Error(result.errors[0]?.message || 'Upload failed');
+  }
+  return result;
+}
+```
+
+## Security Gotchas
+
+1. **Never expose API token in frontend** - Use direct creator uploads
+2. **Always verify webhook signatures** - Prevent spoofed notifications
+3. **Set appropriate token expiration** - Short-lived for security
+4. **Use requireSignedURLs for private content** - Prevent unauthorized access
+5. **Whitelist allowedOrigins** - Prevent hotlinking/embedding on unauthorized sites
+
+## In This Reference
+
+- [README.md](./README.md) - Overview and quick start
+- [configuration.md](./configuration.md) - Setup and config
+- [api.md](./api.md) - Upload, playback, live streaming APIs
+- [patterns.md](./patterns.md) - Full-stack flows, best practices
+
+## See Also
+
+- [workers](../workers/) - Deploy Stream APIs securely

package/.codex/skills/cloudflare/references/stream/patterns.md

@@ -0,0 +1,152 @@
+# Stream Patterns
+
+Common workflows, full-stack flows, and best practices.
+
+## Full-Stack Upload Flow
+
+**Backend API (Next.js route)**
+```typescript
+// app/api/upload-url/route.ts
+export async function POST(req: Request) {
+  const { userId, videoName } = await req.json();
+  
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/accounts/${process.env.CF_ACCOUNT_ID}/stream/direct_upload`,
+    {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${process.env.CF_API_TOKEN}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        maxDurationSeconds: 3600,
+        requireSignedURLs: true,
+        meta: { creator: userId, name: videoName }
+      })
+    }
+  );
+  const data = await response.json();
+  return Response.json({ uploadURL: data.result.uploadURL, uid: data.result.uid });
+}
+```
+
+**Frontend component**
+```tsx
+'use client';
+import { useState } from 'react';
+
+export function VideoUploader() {
+  const [uploading, setUploading] = useState(false);
+  const [progress, setProgress] = useState(0);
+  
+  async function handleUpload(file: File) {
+    setUploading(true);
+    const { uploadURL, uid } = await fetch('/api/upload-url', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ videoName: file.name })
+    }).then(r => r.json());
+    
+    const formData = new FormData();
+    formData.append('file', file);
+    
+    const xhr = new XMLHttpRequest();
+    xhr.upload.addEventListener('progress', (e) => {
+      if (e.lengthComputable) setProgress((e.loaded / e.total) * 100);
+    });
+    xhr.addEventListener('load', () => {
+      setUploading(false);
+      window.location.href = `/videos/${uid}`;
+    });
+    xhr.open('POST', uploadURL);
+    xhr.send(formData);
+  }
+  
+  return (
+    <div>
+      <input type="file" accept="video/*"
+        onChange={(e) => e.target.files?.[0] && handleUpload(e.target.files[0])}
+        disabled={uploading} />
+      {uploading && <progress value={progress} max={100} />}
+    </div>
+  );
+}
+```
+
+## Video State Management
+
+```typescript
+interface VideoState {
+  uid: string;
+  readyToStream: boolean;
+  status: { state: 'queued' | 'inprogress' | 'ready' | 'error'; pctComplete?: string };
+}
+
+async function waitForVideoReady(
+  accountId: string, videoId: string, apiToken: string,
+  maxAttempts = 60, intervalMs = 5000
+): Promise<VideoState> {
+  for (let i = 0; i < maxAttempts; i++) {
+    const response = await fetch(
+      `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/${videoId}`,
+      { headers: { 'Authorization': `Bearer ${apiToken}` } }
+    );
+    const { result } = await response.json();
+    if (result.readyToStream || result.status.state === 'error') return result;
+    await new Promise(resolve => setTimeout(resolve, intervalMs));
+  }
+  throw new Error('Video processing timeout');
+}
+```
+
+## Webhook Handler (Workers)
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const signature = request.headers.get('Webhook-Signature');
+    if (!signature) return new Response('No signature', { status: 401 });
+    
+    const body = await request.text();
+    // Verify HMAC-SHA256: parse time/sig1, check 5min window, compare signature
+    const isValid = await verifySignature(signature, body, env.WEBHOOK_SECRET);
+    if (!isValid) return new Response('Invalid', { status: 401 });
+    
+    const payload = JSON.parse(body);
+    if (payload.readyToStream) console.log(`Video ${payload.uid} ready`);
+    return new Response('OK');
+  }
+};
+// Full verifySignature impl in gotchas.md
+```
+
+## Live Streaming Setup
+
+**OBS**: Server `rtmps://live.cloudflare.com:443/live/`, Stream Key from API
+
+**FFmpeg**: `ffmpeg -re -i input.mp4 -c:v libx264 -preset veryfast -b:v 3000k -c:a aac -f flv rtmps://live.cloudflare.com:443/live/<KEY>`
+
+## Best Practices
+
+1. **Use Direct Creator Uploads** - Avoid proxying video through servers
+2. **Enable requireSignedURLs** - Control access to private content
+3. **Use signing keys for high volume** - Self-sign tokens instead of API calls
+4. **Set allowedOrigins** - Prevent hotlinking
+5. **Use webhooks over polling** - Efficient status updates
+6. **Cache video metadata** - Reduce API calls
+7. **Set maxDurationSeconds** - Prevent abuse on direct uploads
+8. **Use creator metadata** - Enable per-user filtering/analytics
+9. **Enable recordings for live** - Automatic VOD after stream ends
+10. **Monitor with GraphQL analytics** - Track views, watch time, geo
+
+## In This Reference
+
+- [README.md](./README.md) - Overview and quick start
+- [configuration.md](./configuration.md) - Setup and config
+- [api.md](./api.md) - Upload, playback, live streaming APIs
+- [gotchas.md](./gotchas.md) - Error codes, troubleshooting
+
+## See Also
+
+- [workers](../workers/) - Deploy Stream APIs in Workers
+- [pages](../pages/) - Integrate Stream with Pages