@editframe/create 0.43.0 → 0.45.0

package/dist/skills/editframe-webhooks/references/events.md

@@ -0,0 +1,382 @@
+---
+title: Webhook Events
+description: Complete reference for all Editframe webhook event types, payload schemas, and the conditions that trigger each event.
+type: reference
+nav:
+  parent: "Events & Payloads"
+  priority: 2
+---
+
+# Webhook Events
+
+Complete reference of all webhook event types and their payload structures.
+
+## Event Structure
+
+All webhook events follow this structure:
+
+```typescript
+interface WebhookEvent<T> {
+  topic: string;        // Event type (e.g., "render.completed")
+  data: T;              // Event-specific payload
+}
+```
+
+The webhook is delivered as an HTTP POST request with:
+- **Headers**: `Content-Type: application/json`, `X-Webhook-Signature: <hmac>`
+- **Body**: JSON-encoded webhook event
+
+## Render Events
+
+### render.created
+
+Triggered when a render job is created.
+
+```typescript
+interface RenderCreatedPayload {
+  id: string;              // Render UUID
+  status: "created";       // Always "created" for this event
+  created_at: string;      // ISO 8601 timestamp
+  completed_at: null;      // Not completed yet
+  failed_at: null;         // Not failed yet
+  width: number;           // Video width in pixels
+  height: number;          // Video height in pixels
+  fps: number;             // Frames per second
+  byte_size: null;         // Not available until completed
+  duration_ms: null;       // Not available until completed
+  md5: null;               // Not available until completed
+  metadata: object | null; // Custom metadata from request
+  download_url: null;      // Not available until completed
+}
+```
+
+**Example:**
+```json
+{
+  "topic": "render.created",
+  "data": {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "status": "created",
+    "created_at": "2024-10-30T10:00:00Z",
+    "completed_at": null,
+    "failed_at": null,
+    "width": 1920,
+    "height": 1080,
+    "fps": 30,
+    "byte_size": null,
+    "duration_ms": null,
+    "md5": null,
+    "metadata": { "project_id": "abc123" },
+    "download_url": null
+  }
+}
+```
+
+### render.pending
+
+Triggered when a render is queued for processing.
+
+Payload structure is identical to `render.created`, with `status: "pending"`.
+
+### render.rendering
+
+Triggered when a render begins active processing.
+
+Payload structure is identical to `render.created`, with `status: "rendering"`.
+
+### render.completed
+
+Triggered when a render successfully finishes.
+
+```typescript
+interface RenderCompletedPayload {
+  id: string;              // Render UUID
+  status: "complete";      // Always "complete" for this event
+  created_at: string;      // ISO 8601 timestamp
+  completed_at: string;    // ISO 8601 timestamp of completion
+  failed_at: null;         // Not failed
+  width: number;           // Video width in pixels
+  height: number;          // Video height in pixels
+  fps: number;             // Frames per second
+  byte_size: number;       // File size in bytes
+  duration_ms: number;     // Video duration in milliseconds
+  md5: string;             // MD5 hash of video file
+  metadata: object | null; // Custom metadata from request
+  download_url: string;    // Signed URL to download video
+}
+```
+
+**Example:**
+```json
+{
+  "topic": "render.completed",
+  "data": {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "status": "complete",
+    "created_at": "2024-10-30T10:00:00Z",
+    "completed_at": "2024-10-30T10:01:23Z",
+    "failed_at": null,
+    "width": 1920,
+    "height": 1080,
+    "fps": 30,
+    "byte_size": 15728640,
+    "duration_ms": 5000,
+    "md5": "098f6bcd4621d373cade4e832627b4f6",
+    "metadata": { "project_id": "abc123" },
+    "download_url": "https://editframe.com/api/v1/renders/550e8400-e29b-41d4-a716-446655440000/mp4"
+  }
+}
+```
+
+**Usage:**
+```typescript
+if (event.topic === "render.completed") {
+  const { id, download_url, duration_ms, byte_size } = event.data;
+
+  console.log(`Render ${id} completed:`);
+  console.log(`- Duration: ${duration_ms / 1000}s`);
+  console.log(`- Size: ${(byte_size / 1024 / 1024).toFixed(2)} MB`);
+
+  // Download the video
+  const response = await fetch(download_url);
+  const videoBuffer = await response.arrayBuffer();
+
+  // Save or upload to your storage
+  await saveVideo(id, videoBuffer);
+}
+```
+
+### render.failed
+
+Triggered when a render encounters an error.
+
+```typescript
+interface RenderFailedPayload {
+  id: string;              // Render UUID
+  status: "failed";        // Always "failed" for this event
+  created_at: string;      // ISO 8601 timestamp
+  completed_at: null;      // Not completed
+  failed_at: string;       // ISO 8601 timestamp of failure
+  width: number;           // Video width in pixels
+  height: number;          // Video height in pixels
+  fps: number;             // Frames per second
+  byte_size: null;         // Not available
+  duration_ms: null;       // Not available
+  md5: null;               // Not available
+  metadata: object | null; // Custom metadata from request
+  download_url: null;      // Not available
+}
+```
+
+**Example:**
+```json
+{
+  "topic": "render.failed",
+  "data": {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "status": "failed",
+    "created_at": "2024-10-30T10:00:00Z",
+    "completed_at": null,
+    "failed_at": "2024-10-30T10:00:45Z",
+    "width": 1920,
+    "height": 1080,
+    "fps": 30,
+    "byte_size": null,
+    "duration_ms": null,
+    "md5": null,
+    "metadata": { "project_id": "abc123" },
+    "download_url": null
+  }
+}
+```
+
+## File Events
+
+### file.created
+
+Triggered when a file record is created (before upload).
+
+```typescript
+interface FileCreatedPayload {
+  id: string;              // File UUID
+  type: "video" | "image" | "caption"; // File type
+  status: "created";       // Always "created" for this event
+  filename: string;        // Original filename
+  byte_size: null;         // Not uploaded yet
+  md5: null;               // Not uploaded yet
+  mime_type: null;         // Not available yet
+  width: null;             // Not available yet (images only)
+  height: null;            // Not available yet (images only)
+}
+```
+
+**Example:**
+```json
+{
+  "topic": "file.created",
+  "data": {
+    "id": "660e8400-e29b-41d4-a716-446655440001",
+    "type": "video",
+    "status": "created",
+    "filename": "my-video.mp4",
+    "byte_size": null,
+    "md5": null,
+    "mime_type": null,
+    "width": null,
+    "height": null
+  }
+}
+```
+
+### file.uploading
+
+Triggered when file upload is in progress.
+
+Payload structure similar to `file.created`, with `status: "uploading"`.
+
+### file.processing
+
+Triggered when a video file is being processed to ISOBMFF format.
+
+Only sent for `type: "video"` files.
+
+```typescript
+interface FileProcessingPayload {
+  id: string;              // File UUID
+  type: "video";           // Always "video" for processing
+  status: "processing";    // Always "processing" for this event
+  filename: string;        // Original filename
+  byte_size: number;       // Uploaded file size
+  md5: string;             // MD5 hash of uploaded file
+  mime_type: string;       // MIME type (e.g., "video/mp4")
+  width: number | null;    // Video width in pixels
+  height: number | null;   // Video height in pixels
+}
+```
+
+### file.ready
+
+Triggered when a file is ready for use in compositions.
+
+```typescript
+interface FileReadyPayload {
+  id: string;              // File UUID
+  type: "video" | "image" | "caption"; // File type
+  status: "ready";         // Always "ready" for this event
+  filename: string;        // Original filename
+  byte_size: number;       // File size in bytes
+  md5: string;             // MD5 hash of file
+  mime_type: string;       // MIME type
+  width: number | null;    // Width in pixels (images/video only)
+  height: number | null;   // Height in pixels (images/video only)
+}
+```
+
+**Example:**
+```json
+{
+  "topic": "file.ready",
+  "data": {
+    "id": "660e8400-e29b-41d4-a716-446655440001",
+    "type": "video",
+    "status": "ready",
+    "filename": "my-video.mp4",
+    "byte_size": 52428800,
+    "md5": "5d41402abc4b2a76b9719d911017c592",
+    "mime_type": "video/mp4",
+    "width": 1920,
+    "height": 1080
+  }
+}
+```
+
+**Usage:**
+```typescript
+if (event.topic === "file.ready") {
+  const { id, type, filename } = event.data;
+
+  console.log(`File ${filename} (${type}) is ready`);
+  console.log(`Use in composition: <ef-${type} file-id="${id}"></${type}>`);
+
+  // Update database record
+  await db.updateFile(id, { status: "ready", processedAt: new Date() });
+}
+```
+
+### file.failed
+
+Triggered when file upload or processing fails.
+
+Payload structure similar to other file events, with `status: "failed"`.
+
+## Legacy Events
+
+### unprocessed_file.created
+
+**Deprecated**: Use `file.created` instead.
+
+Triggered when an unprocessed file is created.
+
+```typescript
+interface UnprocessedFileCreatedPayload {
+  id: string;              // File UUID
+  byte_size: number;       // File size in bytes
+  next_byte: number;       // Upload progress
+  md5: string | null;      // MD5 hash if completed
+  filename: string;        // Original filename
+  completed_at: string | null; // Completion timestamp
+}
+```
+
+## Webhook Test Event
+
+### webhook.test
+
+Sent when you trigger a test webhook from the dashboard.
+
+```json
+{
+  "topic": "webhook.test",
+  "data": {
+    "id": "your-api-key-id",
+    "org_id": "your-org-id"
+  }
+}
+```
+
+Use this to verify your webhook endpoint is correctly configured.
+
+## Event Ordering
+
+Events are sent in chronological order, but network issues or retries may cause events to arrive out of order. Use timestamps (`created_at`, `completed_at`, etc.) to determine actual event sequence.
+
+Example render lifecycle:
+1. `render.created` (status: "created")
+2. `render.pending` (status: "pending")
+3. `render.rendering` (status: "rendering")
+4. `render.completed` (status: "complete") OR `render.failed` (status: "failed")
+
+## Subscribing to Events
+
+Configure which events you receive when creating or updating an API key:
+
+```typescript
+const apiKey = await createApiKey({
+  name: "Production",
+  webhookUrl: "https://api.yourapp.com/webhooks",
+  webhookEvents: [
+    "render.completed",
+    "render.failed",
+    "file.ready",
+    "file.failed"
+  ]
+});
+```
+
+**Recommendation**: Subscribe only to events you need to reduce unnecessary webhook traffic.
+
+## Next Steps
+
+- [security.md](references/security.md) — Verify webhook signatures
+- [testing.md](references/testing.md) — Test webhook payloads locally
+- [troubleshooting.md](references/troubleshooting.md) — Debug webhook issues

package/dist/skills/editframe-webhooks/references/getting-started.md

@@ -0,0 +1,232 @@
+---
+title: Getting Started with Webhooks
+description: Configure a webhook endpoint URL to receive Editframe event notifications for render completion and file processing.
+type: tutorial
+nav:
+  parent: "Quick Start"
+  priority: 1
+---
+
+# Getting Started with Webhooks
+
+Configure webhooks to receive real-time notifications when renders complete or files finish processing.
+
+## Prerequisites
+
+- An Editframe account with API access
+- A publicly accessible HTTPS endpoint to receive webhooks
+- Ability to verify HMAC signatures in your application
+
+## Step 1: Create a Webhook Endpoint
+
+Create an endpoint in your application that accepts POST requests:
+
+```typescript
+import express from "express";
+import crypto from "node:crypto";
+
+const app = express();
+app.use(express.json());
+
+app.post("/webhooks/editframe", async (req, res) => {
+  const signature = req.headers["x-webhook-signature"];
+  const payload = req.body;
+
+  // TODO: Verify signature (see Step 3)
+
+  console.log("Webhook received:", payload.topic);
+
+  // Respond quickly - process events asynchronously
+  res.status(200).send("OK");
+
+  // Process event in background
+  processWebhookEvent(payload).catch(console.error);
+});
+
+app.listen(3000);
+```
+
+Your endpoint must:
+- Accept POST requests with JSON body
+- Respond with 200 OK within 30 seconds
+- Verify the `X-Webhook-Signature` header
+- Handle events idempotently (events may be delivered multiple times)
+
+## Step 2: Register Your Webhook
+
+Register your webhook URL when creating an API key. You can do this via the Editframe dashboard or programmatically:
+
+### Via Dashboard
+
+1. Go to [editframe.com/resource/api_keys](https://editframe.com/resource/api_keys)
+2. Click "Create API Key"
+3. Fill in the form:
+   - **Name**: "My Application"
+   - **Webhook URL**: `https://your-app.com/webhooks/editframe`
+   - **Webhook Events**: Select events to receive:
+     - `render.completed`
+     - `render.failed`
+     - `file.ready`
+4. Click "Create"
+5. Copy and securely store:
+   - **API Key** (for making API requests)
+   - **Webhook Secret** (for verifying signatures)
+
+### Via API (Programmatic)
+
+```typescript
+import { db } from "@/sql-client.server";
+import { createApiKey } from "@/createApiKey.server";
+import { generateApiToken } from "@/util/scryptPromise.server";
+import crypto from "node:crypto";
+
+// Generate tokens
+const apiToken = crypto.randomBytes(32).toString("hex");
+const webhookSecret = crypto.randomBytes(32).toString("hex");
+
+// Create API key with webhook configuration
+const apiKey = await createApiKey({
+  token: apiToken,
+  webhookSecret: webhookSecret,
+  name: "My Application",
+  orgId: "your-org-id",
+  userId: "your-user-id",
+  webhookUrl: "https://your-app.com/webhooks/editframe",
+  webhookEvents: ["render.completed", "render.failed", "file.ready"],
+  expired_at: null, // or set expiration date
+});
+
+console.log("API Key ID:", apiKey.id);
+console.log("API Token:", apiToken); // Store securely
+console.log("Webhook Secret:", webhookSecret); // Store securely
+```
+
+## Step 3: Verify Webhook Signatures
+
+Every webhook request includes an `X-Webhook-Signature` header containing an HMAC-SHA256 signature. Verify this signature to ensure the request is from Editframe:
+
+```typescript
+import crypto from "node:crypto";
+
+function verifyWebhookSignature(
+  payload: string,
+  signature: string,
+  secret: string
+): boolean {
+  const expectedSignature = crypto
+    .createHmac("sha256", secret)
+    .update(payload)
+    .digest("hex");
+
+  return crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(expectedSignature)
+  );
+}
+
+// In your webhook handler
+app.post("/webhooks/editframe", async (req, res) => {
+  const signature = req.headers["x-webhook-signature"] as string;
+  const payload = JSON.stringify(req.body);
+  const secret = process.env.EDITFRAME_WEBHOOK_SECRET!;
+
+  if (!verifyWebhookSignature(payload, signature, secret)) {
+    console.error("Invalid webhook signature");
+    return res.status(401).send("Invalid signature");
+  }
+
+  // Signature is valid - process event
+  const { topic, data } = req.body;
+  console.log(`Verified webhook: ${topic}`);
+
+  res.status(200).send("OK");
+});
+```
+
+**Critical**: Hash the raw request body as received, not the parsed JSON object. Different JSON serialization can produce different hashes.
+
+## Step 4: Handle Webhook Events
+
+Process events based on their topic:
+
+```typescript
+async function processWebhookEvent(event: WebhookEvent) {
+  const { topic, data } = event;
+
+  switch (topic) {
+    case "render.completed":
+      console.log(`Render ${data.id} completed`);
+      console.log(`Download URL: ${data.download_url}`);
+      console.log(`Duration: ${data.duration_ms}ms`);
+      console.log(`Size: ${data.byte_size} bytes`);
+
+      // Download the render
+      const response = await fetch(data.download_url);
+      const videoBuffer = await response.arrayBuffer();
+      // ... save or process video
+      break;
+
+    case "render.failed":
+      console.error(`Render ${data.id} failed`);
+      // ... notify user or retry
+      break;
+
+    case "file.ready":
+      console.log(`File ${data.id} is ready`);
+      // ... use file in composition
+      break;
+
+    default:
+      console.log(`Unhandled webhook topic: ${topic}`);
+  }
+}
+```
+
+## Step 5: Test Your Webhook
+
+Use the Editframe dashboard to send a test webhook:
+
+1. Go to your API key detail page
+2. Click "Test Webhook"
+3. Select a topic (e.g., "render.completed")
+4. Click "Send Test"
+
+Your endpoint should receive a test webhook with sample data. Check your server logs to verify the webhook was received and the signature was validated.
+
+## Local Development
+
+For local testing, use a tunneling service like ngrok:
+
+```bash
+# Start your local server
+npm run dev
+
+# In another terminal, start ngrok
+ngrok http 3000
+
+# Use the ngrok URL as your webhook URL
+# Example: https://abc123.ngrok.io/webhooks/editframe
+```
+
+Update your API key's webhook URL to the ngrok URL, then trigger events to test locally.
+
+See [testing.md](references/testing.md) for more testing strategies.
+
+## Production Considerations
+
+When deploying to production:
+
+1. **Use HTTPS**: Webhook URLs must use HTTPS (not HTTP)
+2. **Store secrets securely**: Never commit webhook secrets to version control
+3. **Respond quickly**: Return 200 OK within 30 seconds
+4. **Process asynchronously**: Handle events in background jobs/queues
+5. **Implement idempotency**: Use event IDs to prevent duplicate processing
+6. **Log delivery failures**: Monitor webhook delivery in the dashboard
+7. **Handle retries**: Events may be delivered multiple times
+
+## Next Steps
+
+- [events.md](references/events.md) — Learn about all event types and payload structures
+- [security.md](references/security.md) — Deep dive into signature verification
+- [testing.md](references/testing.md) — Advanced testing strategies
+- [troubleshooting.md](references/troubleshooting.md) — Debug common issues