@replayio-app-building/netlify-recorder 0.1.0 → 0.1.1

package/README.md

@@ -1,19 +1,21 @@
-# @netlify-recorder/core
+# @replayio-app-building/netlify-recorder
 
 Capture and replay Netlify function executions as [Replay](https://replay.io) recordings. This package intercepts outbound network calls and environment variable reads during handler execution, stores the captured data as a blob, and can later reproduce the exact execution as a Replay recording for debugging and analysis.
 
 ## Installation
 
 ```bash
-npm install @netlify-recorder/core
+npm install @replayio-app-building/netlify-recorder
 ```
 
-## Quick Start
+## Capturing Requests
 
-### 1. Wrap your Netlify function with startRequest / finishRequest
+Every integration starts by wrapping your Netlify functions with `startRequest` / `finishRequest` to capture execution data. This is the same regardless of how you create recordings afterwards.
+
+### 1. Wrap your Netlify function
 
 ```typescript
-import { startRequest, finishRequest } from "@netlify-recorder/core";
+import { startRequest, finishRequest } from "@replayio-app-building/netlify-recorder";
 import type { Handler } from "@netlify/functions";
 
 const handler: Handler = async (event) => {
@@ -101,10 +103,105 @@ CREATE TABLE IF NOT EXISTS requests (
 | `created_at` | TIMESTAMPTZ | When the request was captured |
 | `updated_at` | TIMESTAMPTZ | Last status update |
 
-### 3. Create a background function to produce recordings
+## Creating Recordings
+
+Once you are capturing requests, you need a way to turn captured data into Replay recordings. There are two options:
+
+### Option A: Use the Netlify Recorder service (recommended)
+
+The Netlify Recorder app (`https://netlify-recorder-bm4wmw.netlify.app`) hosts a recording service with a pool of warm containers. Your app sends the captured blob URL and the service handles all container orchestration, recording creation, and upload. No container infrastructure is needed in your app.
+
+#### How it works
+
+1. Your Netlify function captures request data via `startRequest`/`finishRequest` (see above).
+2. When a recording is needed, your app POSTs to the Netlify Recorder's background function.
+3. The service dispatches the work to a pool container (or queues it if none are idle).
+4. When the recording is ready, the service POSTs the result to your webhook URL.
+
+#### Call the recording endpoint
 
 ```typescript
-import { ensureRequestRecording } from "@netlify-recorder/core";
+// In a Netlify background function or server-side code:
+const response = await fetch(
+  "https://netlify-recorder-bm4wmw.netlify.app/.netlify/functions/create-recording-from-blob-background",
+  {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      blobUrl: "https://your-storage.com/blob/abc123.json",
+      handlerPath: "netlify/functions/your-handler",
+      commitSha: "a1b2c3d4...",
+      branchName: "main",
+      repositoryUrl: "https://github.com/your-org/your-repo",
+      webhookUrl: "https://your-app.netlify.app/.netlify/functions/recording-complete",
+      requestId: "optional-uuid-for-log-correlation",
+    }),
+  }
+);
+// Returns 202 immediately (background function).
+```
+
+**Request body:**
+
+| Field | Required | Description |
+|---|---|---|
+| `blobUrl` | Yes | URL (or `data:` URI) of the captured request blob JSON |
+| `handlerPath` | Yes | Handler file path relative to the app root (e.g. `netlify/functions/generate-haiku`) |
+| `commitSha` | Yes | Git commit SHA to check out inside the recording container |
+| `branchName` | Yes | Git branch name for cloning |
+| `repositoryUrl` | No | Git repository URL. Required when the handler lives in a different repo than netlify-recorder |
+| `webhookUrl` | No | URL the service will POST the result to on completion |
+| `requestId` | No | Your internal request ID, used for log correlation |
+
+**Webhook payload (POSTed to `webhookUrl`):**
+
+On success:
+```json
+{ "status": "recorded", "recordingId": "a1b2c3d4-..." }
+```
+
+On failure:
+```json
+{ "status": "failed", "error": "Error message" }
+```
+
+#### Receive the result
+
+Create a webhook endpoint in your app to receive the recording result:
+
+```typescript
+import type { Handler } from "@netlify/functions";
+
+const handler: Handler = async (event) => {
+  const { status, recordingId, error } = JSON.parse(event.body ?? "{}");
+
+  if (status === "recorded") {
+    // Update your database with the recording ID
+    await sql`
+      UPDATE requests SET status = 'recorded', recording_id = ${recordingId}, updated_at = NOW()
+      WHERE id = ${requestId}
+    `;
+  } else {
+    await sql`
+      UPDATE requests SET status = 'failed', updated_at = NOW()
+      WHERE id = ${requestId}
+    `;
+  }
+
+  return { statusCode: 200, body: "OK" };
+};
+
+export { handler };
+```
+
+### Option B: Self-hosted recording with your own containers
+
+If you need full control over the recording infrastructure, you can run your own containers using `ensureRequestRecording`. This requires Fly.io and Infisical credentials configured in your environment.
+
+#### Create a background function to produce recordings
+
+```typescript
+import { ensureRequestRecording } from "@replayio-app-building/netlify-recorder";
 import type { Handler } from "@netlify/functions";
 
 const handler: Handler = async (event) => {
@@ -145,13 +242,13 @@ const handler: Handler = async (event) => {
 export { handler };
 ```
 
-### 4. Create a container script for createRequestRecording
+#### Create a container script
 
-This script runs inside the container spawned by `ensureRequestRecording`, under `replay-node`:
+This script runs inside the recording container under `replay-node`:
 
 ```typescript
 // scripts/create-request-recording.ts
-import { createRequestRecording } from "@netlify-recorder/core";
+import { createRequestRecording } from "@replayio-app-building/netlify-recorder";
 
 const args = process.argv.slice(2);
 const blobUrl = args[args.indexOf("--blob-url") + 1]!;
@@ -164,6 +261,21 @@ await createRequestRecording(blobUrl, handlerPath, {
 });
 ```
 
+#### Required infrastructure
+
+Self-hosted recording requires the following environment variables for container orchestration:
+
+| Variable | Description |
+|---|---|
+| `INFISICAL_CLIENT_ID` | Infisical service account client ID |
+| `INFISICAL_CLIENT_SECRET` | Infisical service account client secret |
+| `INFISICAL_PROJECT_ID` | Infisical project ID |
+| `INFISICAL_ENVIRONMENT` | Infisical environment (e.g. `production`) |
+| `FLY_API_TOKEN` | Fly.io API token for container management |
+| `FLY_APP_NAME` | Fly.io app name for container deployment |
+| `APP_REPOSITORY_URL` | Git repository URL for container cloning |
+| `RECORD_REPLAY_API_KEY` | Replay API key for recording upload |
+
 ## API Reference
 
 ### `startRequest(requestInfo): RequestContext`
@@ -190,7 +302,7 @@ Finalizes the request capture. Restores original `fetch` and `process.env`, seri
 
 ### `ensureRequestRecording(requestId, options): Promise<string>`
 
-Spawns a container via `@replayio/app-building` to create a Replay recording from captured request data. Returns the recording ID.
+Spawns a container via `@replayio/app-building` to create a Replay recording from captured request data. Returns the recording ID. Only needed for Option B (self-hosted).
 
 **Parameters:**
 - `requestId` — The request to create a recording for
@@ -201,7 +313,7 @@ Spawns a container via `@replayio/app-building` to create a Replay recording fro
 
 ### `createRequestRecording(blobUrl, handlerPath, requestInfo): Promise<void>`
 
-Called inside a container running under `replay-node`. Downloads the captured data blob, installs replay-mode interceptors (which return pre-recorded responses instead of making real calls), and executes the original handler so replay-node can record the execution.
+Called inside a container running under `replay-node`. Downloads the captured data blob, installs replay-mode interceptors (which return pre-recorded responses instead of making real calls), and executes the original handler so replay-node can record the execution. Only needed for Option B (self-hosted).
 
 **Parameters:**
 - `blobUrl` — URL to the captured data blob
@@ -214,11 +326,11 @@ Called inside a container running under `replay-node`. Downloads the captured da
 |---|---|---|
 | `COMMIT_SHA` | No | Git commit hash (defaults to `"HEAD"`) |
 | `BRANCH_NAME` | No | Git branch name for container cloning (defaults to `"main"`) |
-| `RECORD_REPLAY_API_KEY` | For recording | Replay API key for uploading recordings |
-| `APP_REPOSITORY_URL` | For recording | Git repository URL for container cloning |
+| `RECORD_REPLAY_API_KEY` | For self-hosted recording | Replay API key for uploading recordings |
+| `APP_REPOSITORY_URL` | For self-hosted recording | Git repository URL for container cloning |
 
 ## How It Works
 
 1. **Capture phase** (`startRequest` / `finishRequest`): When a Netlify function handles a request, `startRequest` patches `globalThis.fetch` and `process.env` with Proxies that record every outbound network call and environment variable read. When the handler completes, `finishRequest` restores the originals, serializes the captured data to JSON, uploads it as a blob, and records the request in the database.
 
-2. **Recording phase** (`ensureRequestRecording` / `createRequestRecording`): A background function calls `ensureRequestRecording`, which spawns a container with `@replayio/app-building`. Inside the container, `createRequestRecording` downloads the blob, installs replay-mode interceptors that return the pre-recorded responses, and re-executes the handler under `replay-node`. Since replay-node records all execution, this produces a Replay recording of the exact same handler execution.
+2. **Recording phase**: The captured blob is sent to a recording container (either via the Netlify Recorder service or self-hosted). Inside the container, `createRequestRecording` downloads the blob, installs replay-mode interceptors that return the pre-recorded responses, and re-executes the handler under `replay-node`. Since replay-node records all execution, this produces a Replay recording of the exact same handler execution.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@replayio-app-building/netlify-recorder",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Capture and replay Netlify function executions as Replay recordings",
   "type": "module",
   "exports": {