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

package/README.md

@@ -1,19 +1,136 @@
-# @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
+## Integration Options
 
-### 1. Wrap your Netlify function with startRequest / finishRequest
+There are two ways to use this package:
+
+- **Option A: Use the Netlify Recorder service (recommended)** — The service handles blob storage, request tracking, and recording creation. Your app just wraps its handlers and calls `remoteCallbacks()`. No database or container infrastructure needed.
+
+- **Option B: Self-hosted** — You manage your own blob storage, database tables, and recording containers. Full control, but requires more setup.
+
+---
+
+## Option A: Using the Netlify Recorder Service
+
+The Netlify Recorder app (`https://netlify-recorder-bm4wmw.netlify.app`) provides a hosted service that stores captured request data, manages a pool of recording containers, and creates Replay recordings on demand. Your app needs zero database or infrastructure setup.
+
+### 1. Wrap your Netlify function
+
+Use `startRequest` / `finishRequest` with `remoteCallbacks()` to capture request data and send it to the service:
 
 ```typescript
-import { startRequest, finishRequest } from "@netlify-recorder/core";
+import {
+  startRequest,
+  finishRequest,
+  remoteCallbacks,
+} from "@replayio-app-building/netlify-recorder";
+import type { Handler } from "@netlify/functions";
+
+const RECORDER_URL = "https://netlify-recorder-bm4wmw.netlify.app";
+
+const handler: Handler = async (event) => {
+  const reqContext = startRequest({
+    method: event.httpMethod,
+    url: event.path,
+    headers: event.headers as Record<string, string>,
+    body: event.body ?? undefined,
+  });
+
+  try {
+    const result = await myBusinessLogic();
+
+    return await finishRequest(
+      reqContext,
+      remoteCallbacks(RECORDER_URL),
+      {
+        statusCode: 200,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(result),
+      },
+      { handlerPath: "netlify/functions/my-handler" }
+    );
+  } catch (err) {
+    reqContext.cleanup();
+    throw err;
+  }
+};
+
+export { handler };
+```
+
+That's it for capturing. The `remoteCallbacks(url)` helper sends the captured blob data to the Netlify Recorder service, which uploads it to blob storage and stores the request metadata. The response includes an `X-Replay-Request-Id` header with the request ID managed by the service.
+
+### 2. Create recordings
+
+When you want to turn a captured request into a Replay recording, POST to the service's `create-recording` endpoint with the request ID:
+
+```typescript
+const response = await fetch(
+  `${RECORDER_URL}/.netlify/functions/create-recording`,
+  {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ requestId }),
+  }
+);
+```
+
+The service looks up the stored blob data, dispatches the work to a pool container, and creates the recording. You can check the recording status via the service's Requests page, or provide a webhook to be notified on completion.
+
+### 3. (Optional) Get notified when recordings complete
+
+If you want to be notified when a recording finishes, call the blob endpoint directly with a `webhookUrl`:
+
+```typescript
+await fetch(
+  `${RECORDER_URL}/.netlify/functions/create-recording-from-blob-background`,
+  {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      blobUrl: "https://...",         // blob URL from the service
+      handlerPath: "netlify/functions/my-handler",
+      commitSha: "a1b2c3d4...",
+      branchName: "main",
+      repositoryUrl: "https://github.com/your-org/your-repo",
+      webhookUrl: "https://your-app.netlify.app/.netlify/functions/on-recording-complete",
+    }),
+  }
+);
+```
+
+**Webhook payload (POSTed to `webhookUrl`):**
+
+On success:
+```json
+{ "status": "recorded", "recordingId": "a1b2c3d4-..." }
+```
+
+On failure:
+```json
+{ "status": "failed", "error": "Error message" }
+```
+
+---
+
+## Option B: Self-Hosted
+
+If you need full control, you can manage your own blob storage, database, and recording containers. This requires more setup but gives you complete ownership of the data pipeline.
+
+### 1. Wrap your Netlify function
+
+Use `startRequest` / `finishRequest` with custom callbacks that write to your own storage and database:
+
+```typescript
+import { startRequest, finishRequest } from "@replayio-app-building/netlify-recorder";
 import type { Handler } from "@netlify/functions";
 
 const handler: Handler = async (event) => {
@@ -25,8 +142,6 @@ const handler: Handler = async (event) => {
   });
 
   try {
-    // Your handler logic — all fetch() calls and process.env reads
-    // are automatically captured while the context is active.
     const result = await myBusinessLogic();
 
     return await finishRequest(
@@ -34,7 +149,6 @@ const handler: Handler = async (event) => {
       {
         uploadBlob: async (data) => {
           // Upload the JSON string to your blob storage (S3, R2, etc.)
-          // and return the public URL.
           const res = await originalFetch("https://storage.example.com/upload", {
             method: "PUT",
             body: data,
@@ -43,7 +157,6 @@ const handler: Handler = async (event) => {
           return url;
         },
         storeRequestData: async ({ blobUrl, commitSha, branchName, handlerPath }) => {
-          // Insert a row into your requests table and return the request ID.
           const [row] = await sql`
             INSERT INTO requests (blob_url, commit_sha, branch_name, handler_path, status)
             VALUES (${blobUrl}, ${commitSha}, ${branchName}, ${handlerPath}, 'captured')
@@ -59,7 +172,7 @@ const handler: Handler = async (event) => {
       }
     );
   } catch (err) {
-    reqContext.cleanup(); // Always restore globals on error
+    reqContext.cleanup();
     throw err;
   }
 };
@@ -67,12 +180,8 @@ const handler: Handler = async (event) => {
 export { handler };
 ```
 
-The response returned by `finishRequest` includes the `X-Replay-Request-Id` header, which the frontend can read to display the request ID.
-
 ### 2. Create a requests database table
 
-The consuming app must provide a PostgreSQL table to track captured requests:
-
 ```sql
 CREATE TABLE IF NOT EXISTS requests (
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -87,24 +196,10 @@ CREATE TABLE IF NOT EXISTS requests (
 );
 ```
 
-**Columns:**
-
-| Column | Type | Description |
-|---|---|---|
-| `id` | UUID | Unique request ID |
-| `blob_url` | TEXT | URL to the stored captured data blob |
-| `commit_sha` | TEXT | Git commit hash when the request was captured |
-| `branch_name` | TEXT | Git branch name for container cloning |
-| `handler_path` | TEXT | Path to the handler file that was executed |
-| `recording_id` | TEXT | Replay recording ID (null until recording is created) |
-| `status` | TEXT | One of: `captured`, `processing`, `recorded`, `failed` |
-| `created_at` | TIMESTAMPTZ | When the request was captured |
-| `updated_at` | TIMESTAMPTZ | Last status update |
-
 ### 3. Create a background function to produce recordings
 
 ```typescript
-import { ensureRequestRecording } from "@netlify-recorder/core";
+import { ensureRequestRecording } from "@replayio-app-building/netlify-recorder";
 import type { Handler } from "@netlify/functions";
 
 const handler: Handler = async (event) => {
@@ -145,13 +240,13 @@ const handler: Handler = async (event) => {
 export { handler };
 ```
 
-### 4. Create a container script for createRequestRecording
+### 4. 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 +259,23 @@ await createRequestRecording(blobUrl, handlerPath, {
 });
 ```
 
+### Required infrastructure
+
+Self-hosted recording requires these environment variables:
+
+| 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`
@@ -178,19 +290,26 @@ Begins capturing a Netlify handler execution. Patches `globalThis.fetch` and `pr
 
 **Returns:** A `RequestContext` object to pass to `finishRequest`.
 
-### `finishRequest(requestContext, callbacks, response): Promise<HandlerResponse>`
+### `finishRequest(requestContext, callbacks, response, options?): Promise<HandlerResponse>`
 
-Finalizes the request capture. Restores original `fetch` and `process.env`, serializes the captured data, uploads it via the `uploadBlob` callback, stores metadata via `storeRequestData`, and returns the response with `X-Replay-Request-Id` header set.
+Finalizes the request capture. Restores original `fetch` and `process.env`, serializes the captured data, uploads it via the callbacks, and returns the response with `X-Replay-Request-Id` header set.
 
 **Parameters:**
 - `requestContext` — The context returned by `startRequest`
-- `callbacks.uploadBlob(data)` — Receives serialized JSON, must return a URL
-- `callbacks.storeRequestData({ blobUrl, commitSha, branchName, handlerPath })` — Stores metadata, returns request ID
+- `callbacks` — Either `remoteCallbacks(serviceUrl)` or custom `{ uploadBlob, storeRequestData }` callbacks
 - `response` — The handler's response object (`{ statusCode, headers?, body? }`)
+- `options.handlerPath` — Path to the handler file (used for recording metadata)
+
+### `remoteCallbacks(serviceUrl): FinishRequestCallbacks`
+
+Creates callbacks for `finishRequest` that send captured data to the Netlify Recorder service. The service handles blob storage and request tracking — no local database needed.
+
+**Parameters:**
+- `serviceUrl` — Base URL of the Netlify Recorder service (e.g. `"https://netlify-recorder-bm4wmw.netlify.app"`)
 
 ### `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 self-hosted setups (Option B).
 
 **Parameters:**
 - `requestId` — The request to create a recording for
@@ -201,7 +320,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 self-hosted setups (Option B).
 
 **Parameters:**
 - `blobUrl` — URL to the captured data blob
@@ -214,11 +333,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.
+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, and sends it to either the remote service (via `remoteCallbacks`) or your own storage (via custom callbacks).
 
-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/dist/index.d.ts

@@ -118,6 +118,20 @@ interface FinishRequestOptions {
  */
 declare function finishRequest(requestContext: RequestContext, callbacks: FinishRequestCallbacks, response: HandlerResponse, options?: FinishRequestOptions): Promise<HandlerResponse>;
 
+/**
+ * Creates `FinishRequestCallbacks` that send captured data to a remote
+ * Netlify Recorder service. This removes the need for the consuming app
+ * to set up its own blob storage or database tables.
+ *
+ * The callbacks upload blob data and store request metadata via the
+ * service's `store-request` endpoint, which handles UploadThing storage
+ * and database insertion.
+ *
+ * @param serviceUrl - Base URL of the Netlify Recorder service
+ *   (e.g. "https://netlify-recorder-bm4wmw.netlify.app")
+ */
+declare function remoteCallbacks(serviceUrl: string): FinishRequestCallbacks;
+
 /**
  * Redacts sensitive environment variable values from blob data.
  *
@@ -206,4 +220,4 @@ interface SpawnRecordingContainerOptions {
  */
 declare function spawnRecordingContainer(options: SpawnRecordingContainerOptions): Promise<string>;
 
-export { type BlobData, type CapturedData, type ContainerInfraConfig, type EnsureRecordingOptions, type EnvRead, type FinishRequestCallbacks, type NetworkCall, type RequestContext, type RequestInfo, type SpawnRecordingContainerOptions, createRequestRecording, ensureRequestRecording, finishRequest, readInfraConfigFromEnv, redactBlobData, spawnRecordingContainer, startRequest };
+export { type BlobData, type CapturedData, type ContainerInfraConfig, type EnsureRecordingOptions, type EnvRead, type FinishRequestCallbacks, type NetworkCall, type RequestContext, type RequestInfo, type SpawnRecordingContainerOptions, createRequestRecording, ensureRequestRecording, finishRequest, readInfraConfigFromEnv, redactBlobData, remoteCallbacks, spawnRecordingContainer, startRequest };

package/dist/index.js

@@ -301,6 +301,48 @@ async function finishRequest(requestContext, callbacks, response, options) {
   };
 }
 
+// src/remoteCallbacks.ts
+function remoteCallbacks(serviceUrl) {
+  const base = serviceUrl.replace(/\/+$/, "");
+  let pendingBlobData;
+  return {
+    uploadBlob: async (data) => {
+      pendingBlobData = data;
+      return "__pending__";
+    },
+    storeRequestData: async (metadata) => {
+      const blobData = pendingBlobData;
+      pendingBlobData = void 0;
+      if (!blobData) {
+        throw new Error(
+          "remoteCallbacks: uploadBlob must be called before storeRequestData"
+        );
+      }
+      const res = await fetch(
+        `${base}/.netlify/functions/store-request`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            blobData,
+            handlerPath: metadata.handlerPath,
+            commitSha: metadata.commitSha,
+            branchName: metadata.branchName
+          })
+        }
+      );
+      if (!res.ok) {
+        const errBody = await res.text().catch(() => "(unreadable)");
+        throw new Error(
+          `Netlify Recorder store-request failed: ${res.status} ${errBody}`
+        );
+      }
+      const result = await res.json();
+      return result.requestId;
+    }
+  };
+}
+
 // src/spawnRecordingContainer.ts
 async function spawnRecordingContainer(options) {
   const {
@@ -609,6 +651,7 @@ export {
   finishRequest,
   readInfraConfigFromEnv,
   redactBlobData,
+  remoteCallbacks,
   spawnRecordingContainer,
   startRequest
 };

package/package.json

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