@replayio-app-building/netlify-recorder 0.17.0 → 0.19.0

package/README.md

@@ -1,6 +1,6 @@
 # @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 via the Netlify Recorder service, and can later reproduce the exact execution as a Replay recording for debugging and analysis.
+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 in your app's own database, and can later reproduce the exact execution as a Replay recording for debugging and analysis.
 
 ## Installation
 
@@ -10,7 +10,19 @@ npm install @replayio-app-building/netlify-recorder
 
 ## Setup
 
-### 1. Set required environment variables
+### 1. Create the backend_requests table
+
+The package stores captured request data directly in your app's database. Call `backendRequestsEnsureTable` once during schema initialization to create the `backend_requests` table:
+
+```typescript
+import { backendRequestsEnsureTable } from "@replayio-app-building/netlify-recorder";
+
+await backendRequestsEnsureTable(sql);
+```
+
+This creates a table with columns for the serialized blob data, git metadata (commit SHA, branch, repository URL), handler path, recording status, and timestamps.
+
+### 2. Set required environment variables
 
 `finishRequest` needs to know which repository, branch, and commit your deployed code belongs to. Set these environment variables on your Netlify site:
 
@@ -19,9 +31,8 @@ npm install @replayio-app-building/netlify-recorder
 | `REPLAY_REPOSITORY_URL` | Your app's git repository URL (e.g. `https://github.com/org/repo.git`) | Set in your deploy script or Netlify site settings |
 | `COMMIT_SHA` | The git commit hash of the deployed code | Set in your deploy script via `git rev-parse HEAD` |
 | `BRANCH_NAME` | The git branch of the deployed code | Set in your deploy script via `git rev-parse --abbrev-ref HEAD` |
-| `NETLIFY_RECORDER_SECRET` | Secret string for access control — restricts who can view and act on your captured requests | Set in Netlify site environment variables or via `set-branch-secret` |
 
-The first three are **required** — `finishRequest` will throw an error if any are missing. `NETLIFY_RECORDER_SECRET` is strongly recommended to prevent other apps from accessing your captured request data. Your deploy script should resolve the git values and set them on the Netlify site before deploying. Example:
+All three are **required** — `finishRequest` will throw an error if any are missing. Your deploy script should resolve the git values and set them on the Netlify site before deploying. Example:
 
 ```typescript
 // In your deploy script:
@@ -33,19 +44,20 @@ const repositoryUrl = execSync("git remote get-url origin", { encoding: "utf-8"
 // Set these on your Netlify site via the Netlify API or CLI
 ```
 
-### 2. Wrap your Netlify function
+### 3. Wrap your Netlify function
 
-Use `createRecordingRequestHandler` with `remoteCallbacks()` to wrap your handler with automatic request capture. Set `secret` to restrict access to captured requests — only API calls providing the same secret can view or act on them.
+Use `createRecordingRequestHandler` with `databaseCallbacks(sql)` to wrap your handler with automatic request capture. The captured data is stored directly in the `backend_requests` table in your database.
 
 **v1 handler** (Netlify Functions v1 — `event` with `httpMethod`, `path`, etc.):
 
 ```typescript
 import {
   createRecordingRequestHandler,
-  remoteCallbacks,
+  databaseCallbacks,
 } from "@replayio-app-building/netlify-recorder";
+import { neon } from "@neondatabase/serverless";
 
-const RECORDER_URL = "https://netlify-recorder-bm4wmw.netlify.app";
+const sql = neon(process.env.DATABASE_URL!);
 
 const handler = createRecordingRequestHandler(
   async (event) => {
@@ -58,9 +70,8 @@ const handler = createRecordingRequestHandler(
     };
   },
   {
-    callbacks: remoteCallbacks(RECORDER_URL),
+    callbacks: databaseCallbacks(sql),
     handlerPath: "netlify/functions/my-handler",
-    secret: process.env.NETLIFY_RECORDER_SECRET,
   }
 );
 
@@ -72,10 +83,11 @@ export { handler };
 ```typescript
 import {
   createRecordingRequestHandler,
-  remoteCallbacks,
+  databaseCallbacks,
 } from "@replayio-app-building/netlify-recorder";
+import { neon } from "@neondatabase/serverless";
 
-const RECORDER_URL = "https://netlify-recorder-bm4wmw.netlify.app";
+const sql = neon(process.env.DATABASE_URL!);
 
 // The wrapper reads the body from a clone — you can still read req.json() etc.
 export default createRecordingRequestHandler(
@@ -90,140 +102,88 @@ export default createRecordingRequestHandler(
     };
   },
   {
-    callbacks: remoteCallbacks(RECORDER_URL),
+    callbacks: databaseCallbacks(sql),
     handlerPath: "netlify/functions/my-handler",
-    secret: process.env.NETLIFY_RECORDER_SECRET,
   }
 );
 ```
 
-`createRecordingRequestHandler` automatically captures all outbound network calls and environment variable reads during your handler's execution, then sends the captured data to the Netlify Recorder service. The response includes an `X-Replay-Request-Id` header with the request ID managed by the service.
+`createRecordingRequestHandler` automatically captures all outbound network calls and environment variable reads during your handler's execution, then stores the captured data in the `backend_requests` table. The response includes an `X-Replay-Request-Id` header with the ID of the stored request.
 
 > **Note:** Always use the response returned by the wrapper (or `finishRequest`), not your original response object. The wrapper adds the `X-Replay-Request-Id` header to the response it returns.
 
-### 3. Create recordings
+### 4. Create recordings via the Netlify Recorder service
 
-When you want to turn a captured request into a Replay recording, POST to the Netlify Recorder service's `create-recording` endpoint with the request ID. If the request was created with a secret, you must include it:
+Use `ensureRequestRecording` to turn a captured request into a Replay recording. It checks the `backend_requests` table first — if a recording already exists, it returns the recording ID immediately without calling the service. Otherwise it dispatches the work to the Netlify Recorder service and updates the row status to `"queued"`.
 
 ```typescript
-const response = await fetch(
-  `${RECORDER_URL}/api/create-recording`,
-  {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      requestId,
-      secret,
-      webhookUrl: "https://your-app.netlify.app/api/on-recording-complete", // optional
-    }),
-  }
-);
-```
+import { ensureRequestRecording } from "@replayio-app-building/netlify-recorder";
 
-The service looks up the stored blob data, dispatches the work to a recording container, and creates the recording.
+const RECORDER_URL = "https://netlify-recorder-bm4wmw.netlify.app";
 
-If `webhookUrl` is provided, the service will POST the result to that URL when the recording completes (or fails):
+const recordingId = await ensureRequestRecording(sql, requestId, {
+  recorderUrl: RECORDER_URL,
+});
 
-On success:
-```json
-{ "status": "recorded", "recordingId": "a1b2c3d4-..." }
-```
-
-On failure:
-```json
-{ "status": "failed", "error": "Error message" }
+if (recordingId) {
+  console.log(`Recording already exists: ${recordingId}`);
+} else {
+  console.log("Recording queued — check back later or use a webhook");
+}
 ```
 
-### 4. Check recording status
+The function is idempotent — calling it multiple times for the same request is safe:
+- **`status: "recorded"`** — returns the `recording_id` immediately
+- **`status: "queued"` or `"processing"`** — returns `null` without re-queuing
+- **`status: "captured"` or `"failed"`** — calls the service, updates status to `"queued"`, returns `null`
 
-You can poll the recording status at any time. If the request was created with a secret, you must include it:
+By default, the blob data URL points to `${recorderUrl}/api/get-backend-request-blob?requestId=${requestId}`. If your app serves blob data from a different endpoint, pass a custom `blobDataUrl`:
 
 ```typescript
-const res = await fetch(
-  `${RECORDER_URL}/api/get-request?requestId=${requestId}&secret=${secret}`
-);
-const { status, recordingId } = await res.json();
-// status: "captured" | "processing" | "recorded" | "failed"
-// recordingId: string | null
+const recordingId = await ensureRequestRecording(sql, requestId, {
+  recorderUrl: RECORDER_URL,
+  blobDataUrl: `https://your-app.netlify.app/api/get-blob?id=${requestId}`,
+  webhookUrl: "https://your-app.netlify.app/api/on-recording-complete", // optional
+});
 ```
 
-Requests created with a secret return 403 if the secret is missing or incorrect.
-
-### 5. Access control with secrets
-
-You can restrict access to captured requests by setting a `secret` string. When a secret is set, the request is only accessible via API calls that provide the same secret value. This lets each app isolate its requests from other apps sharing the same Netlify Recorder service.
-
-#### Setting a secret
+When `webhookUrl` is provided, the service POSTs the result when the recording completes:
 
-Pass `secret` in the options when wrapping your handler:
-
-```typescript
-export default createRecordingRequestHandler(
-  async (req) => {
-    const result = await myBusinessLogic();
-    return { statusCode: 200, body: JSON.stringify(result) };
-  },
-  {
-    callbacks: remoteCallbacks(RECORDER_URL),
-    handlerPath: "netlify/functions/my-handler",
-    secret: process.env.NETLIFY_RECORDER_SECRET,
-  }
-);
+On success:
+```json
+{ "status": "recorded", "recordingId": "a1b2c3d4-..." }
 ```
 
-#### Listing requests by secret
-
-Use the `requests` endpoint with a `secret` parameter to retrieve all requests associated with your secret, with optional filtering by status, handler path, and time range:
-
-```typescript
-const res = await fetch(
-  `${RECORDER_URL}/api/requests?secret=${secret}&status=recorded&handlerPath=netlify/functions/my-handler&after=2025-01-01T00:00:00Z&before=2025-12-31T23:59:59Z`
-);
-const { rows, total, page, limit } = await res.json();
+On failure:
+```json
+{ "status": "failed", "error": "Error message" }
 ```
 
-Query parameters:
-
-| Parameter | Description |
-|---|---|
-| `secret` | **(required)** The secret string used when creating the requests |
-| `id` | Search by request ID prefix |
-| `status` | Filter by status: `captured`, `queued`, `processing`, `recorded`, `failed`, `all` |
-| `handlerPath` | Filter by handler path (exact match) |
-| `after` | Only include requests created at or after this ISO timestamp |
-| `before` | Only include requests created at or before this ISO timestamp |
-| `page` | Page number (default 1) |
-| `limit` | Page size (default 20, max 100) |
+### 5. Manage stored requests
 
-Without a `secret` parameter, only requests created without a secret are returned.
-
-#### Checking request status with a secret
-
-When a request was created with a secret, you must include the secret when polling its status:
+Use the `backendRequests*` helpers to query and manage captured requests in your database:
 
 ```typescript
-const res = await fetch(
-  `${RECORDER_URL}/api/get-request?requestId=${requestId}&secret=${secret}`
-);
-```
-
-Requests created without a secret remain accessible without one (backward compatible).
-
-#### Managing your secret
-
-Store your secret as a `NETLIFY_RECORDER_SECRET` environment variable. To keep it secure:
-
-1. **Netlify site environment:** Add `NETLIFY_RECORDER_SECRET` in your Netlify site's environment variables (Site settings > Environment variables). This makes it available to all deployed functions.
+import {
+  backendRequestsGet,
+  backendRequestsList,
+  backendRequestsUpdateStatus,
+} from "@replayio-app-building/netlify-recorder";
 
-2. **Branch-level secret** (for CI/development): If you're using the Netlify Recorder agent infrastructure, store the secret as a branch secret so deploy scripts and background agents can access it:
+// Get a single request by ID
+const request = await backendRequestsGet(sql, requestId);
+// request.status: "captured" | "queued" | "processing" | "recorded" | "failed"
+// request.recording_id: string | null
 
-   ```bash
-   set-branch-secret NETLIFY_RECORDER_SECRET "your-secret-value"
-   ```
+// List requests with optional filters
+const requests = await backendRequestsList(sql, { status: "captured", limit: 20 });
 
-3. **Local development:** Add `NETLIFY_RECORDER_SECRET` to your `.env` file (make sure `.env` is in `.gitignore`).
+// Update status after recording completes
+await backendRequestsUpdateStatus(sql, requestId, "recorded", recordingId);
 
-Use a strong random string (e.g. `openssl rand -base64 32`) and rotate it if compromised. All requests created under the old secret remain accessible only with the old secret value — there is no migration mechanism, so plan rotations during low-traffic windows.
+// Update status on failure
+await backendRequestsUpdateStatus(sql, requestId, "failed", undefined, "Error message");
+```
 
 ---
 
@@ -261,7 +221,7 @@ No special SQL wrapper is needed. Any Neon SQL query inside a handler wrapped wi
 ```typescript
 import {
   createRecordingRequestHandler,
-  remoteCallbacks,
+  databaseCallbacks,
 } from "@replayio-app-building/netlify-recorder";
 
 export default createRecordingRequestHandler(
@@ -271,9 +231,8 @@ export default createRecordingRequestHandler(
     return { statusCode: 200, body: "OK" };
   },
   {
-    callbacks: remoteCallbacks(RECORDER_URL),
+    callbacks: databaseCallbacks(sql),
     handlerPath: "netlify/functions/create-order",
-    secret: process.env.NETLIFY_RECORDER_SECRET,
   }
 );
 ```
@@ -314,22 +273,21 @@ The network interceptor detects Neon SQL HTTP requests (which use `fetch` intern
 
 Wraps a Netlify handler function with automatic request recording. This is the recommended way to integrate — it handles `startRequest`/`finishRequest` and error cleanup internally.
 
-**Response timing:** When the Netlify Functions v2 `context` object is available (with `waitUntil`), the response is returned to the client **immediately** with a pre-generated `X-Replay-Request-Id` header. The blob upload and metadata storage continue in the background via `context.waitUntil()`, adding zero latency to the client response.
+**Response timing:** When the Netlify Functions v2 `context` object is available (with `waitUntil`), the response is returned to the client **immediately** with a pre-generated `X-Replay-Request-Id` header. The data storage continues in the background via `context.waitUntil()`, adding zero latency to the client response.
 
 When `context.waitUntil` is not available (v1 handlers or missing context), the wrapper falls back to awaiting `finishRequest` before returning.
 
 **Parameters:**
 - `handler` — Your async handler function `(event, context?) => Promise<{ statusCode, headers?, body? }>`
-- `options.callbacks` — `remoteCallbacks(serviceUrl)` for sending captured data to the Netlify Recorder service
+- `options.callbacks` — `databaseCallbacks(sql)` to store captured data in the `backend_requests` table
 - `options.handlerPath` — Path to the handler file (used for recording metadata)
 - `options.commitSha` — Override `COMMIT_SHA` env var
 - `options.branchName` — Override `BRANCH_NAME` env var
 - `options.repositoryUrl` — Override `REPLAY_REPOSITORY_URL` env var
-- `options.secret` — Optional secret string. When set, the stored request is only accessible via API calls that provide the same secret value.
 
 **Returns:** A wrapped handler function with the same signature.
 
-**Callbacks note:** When using the `waitUntil` flow, `storeRequestData` receives a `requestId` field in its data parameter. Callbacks should use this as the row ID so the stored record matches the ID already sent to the client.
+**Callbacks note:** When using the `waitUntil` flow, `storeRequest` receives a `requestId` field in its data parameter. Callbacks should use this as the row ID so the stored record matches the ID already sent to the client.
 
 ### `startRequest(event): RequestContext`
 
@@ -346,31 +304,158 @@ For v2 Request inputs, the body is read from a **clone** — the original reques
 
 ### `finishRequest(requestContext, callbacks, response, options?): Promise<HandlerResponse>`
 
-Lower-level API. 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.
+Lower-level API. Finalizes the request capture. Restores original `fetch` and `process.env`, serializes the captured data, stores it via the callback, and returns the response with `X-Replay-Request-Id` header set.
 
 **Important:** You must send the returned response to the client — it contains the `X-Replay-Request-Id` header.
 
-Logs a `console.warn` when the total duration exceeds 2 seconds or when individual callback steps (upload, store) exceed 1 second, to help diagnose slow operations.
+Logs a `console.warn` when the total duration exceeds 2 seconds to help diagnose slow operations.
 
 **Requires** the following environment variables (or equivalent options overrides): `COMMIT_SHA`, `BRANCH_NAME`, `REPLAY_REPOSITORY_URL`. Throws if any are missing.
 
 **Parameters:**
 - `requestContext` — The context returned by `startRequest`
-- `callbacks` — `remoteCallbacks(serviceUrl)` for sending captured data to the Netlify Recorder service
+- `callbacks` — `databaseCallbacks(sql)` or a custom `{ storeRequest }` callback
 - `response` — The handler's response object (`{ statusCode, headers?, body? }`)
 - `options.handlerPath` — Path to the handler file (used for recording metadata)
 - `options.commitSha` — Override `COMMIT_SHA` env var
 - `options.branchName` — Override `BRANCH_NAME` env var
 - `options.repositoryUrl` — Override `REPLAY_REPOSITORY_URL` env var
 - `options.requestId` — Pre-generated request ID (used by `createRecordingRequestHandler` in the `waitUntil` flow)
-- `options.secret` — Optional secret string. When set, the stored request is only accessible via API calls that provide the same secret value.
 
-### `remoteCallbacks(serviceUrl): FinishRequestCallbacks`
+### `databaseCallbacks(sql): FinishRequestCallbacks`
+
+Creates a `FinishRequestCallbacks` object that stores captured request data directly in the `backend_requests` table. This is the standard way to provide callbacks to `createRecordingRequestHandler` or `finishRequest`.
+
+**Parameters:**
+- `sql` — A Neon SQL tagged-template function
+
+**Returns:** An object with a `storeRequest` method that inserts rows into `backend_requests`.
+
+### `backendRequestsEnsureTable(sql): Promise<void>`
+
+Creates the `backend_requests` table and its indexes. Call once during schema initialization.
+
+The table schema:
+
+| Column | Type | Description |
+|---|---|---|
+| `id` | UUID (PK) | Auto-generated request ID |
+| `blob_data` | TEXT | Serialized JSON of captured request data |
+| `handler_path` | TEXT | Path to the handler file |
+| `commit_sha` | TEXT | Git commit SHA |
+| `branch_name` | TEXT | Git branch name (default: `'main'`) |
+| `repository_url` | TEXT | Git repository URL (nullable) |
+| `status` | TEXT | `'captured'`, `'queued'`, `'processing'`, `'recorded'`, or `'failed'` |
+| `recording_id` | TEXT | Replay recording ID (set when status is `'recorded'`) |
+| `error_message` | TEXT | Error details (set when status is `'failed'`) |
+| `created_at` | TIMESTAMPTZ | Row creation time |
+| `updated_at` | TIMESTAMPTZ | Last update time |
+
+**Parameters:**
+- `sql` — A Neon SQL tagged-template function
+
+### `backendRequestsInsert(sql, data): Promise<string>`
+
+Inserts a new row into `backend_requests` and returns the generated (or provided) ID.
+
+**Parameters:**
+- `sql` — A Neon SQL tagged-template function
+- `data.blobData` — Serialized blob JSON string
+- `data.handlerPath` — Handler file path
+- `data.commitSha` — Git commit SHA
+- `data.branchName` — Git branch name
+- `data.repositoryUrl` — Git repository URL (optional)
+- `data.id` — Pre-generated UUID (optional; auto-generated if omitted)
+
+### `backendRequestsGet(sql, id): Promise<BackendRequest | null>`
+
+Retrieves a single request by ID, or `null` if not found.
+
+**Parameters:**
+- `sql` — A Neon SQL tagged-template function
+- `id` — The request UUID
+
+### `backendRequestsGetBlobData(sql, id): Promise<string | null>`
+
+Retrieves only the `blob_data` column for a request, or `null` if not found. Use this to serve blob data to the recording container without fetching the full row.
+
+**Parameters:**
+- `sql` — A Neon SQL tagged-template function
+- `id` — The request UUID
+
+### `backendRequestsList(sql, filters?): Promise<BackendRequest[]>`
+
+Lists requests ordered by `created_at` DESC, with optional filters.
+
+**Parameters:**
+- `sql` — A Neon SQL tagged-template function
+- `filters.status` — Filter by status (e.g. `"captured"`, `"recorded"`)
+- `filters.limit` — Maximum rows to return (default: 50)
+
+### `backendRequestsUpdateStatus(sql, id, status, recordingId?, errorMessage?): Promise<void>`
 
-Creates callbacks for `finishRequest` that send captured data to the Netlify Recorder service. The service handles blob storage and request tracking.
+Updates the status of a request. Optionally sets `recording_id` (on success) or `error_message` (on failure).
 
 **Parameters:**
-- `serviceUrl` — Base URL of the Netlify Recorder service (e.g. `"https://netlify-recorder-bm4wmw.netlify.app"`)
+- `sql` — A Neon SQL tagged-template function
+- `id` — The request UUID
+- `status` — New status string
+- `recordingId` — Replay recording ID (optional, for `"recorded"` status)
+- `errorMessage` — Error details (optional, for `"failed"` status)
+
+### `ensureRequestRecording(sql, requestId, options): Promise<string | null>`
+
+Ensures a Replay recording exists (or is being created) for a backend request. Looks up the request in `backend_requests`, returns the `recording_id` if already recorded, or calls the Netlify Recorder service to queue a recording. Idempotent — safe to call multiple times for the same request.
+
+**Parameters:**
+- `sql` — A Neon SQL tagged-template function
+- `requestId` — The backend request UUID
+- `options.recorderUrl` — Base URL of the Netlify Recorder service
+- `options.blobDataUrl` — Override the URL where the recording container fetches the blob JSON (defaults to `${recorderUrl}/api/get-backend-request-blob?requestId=${requestId}`)
+- `options.webhookUrl` — URL to POST the result to when the recording completes or fails
+
+**Returns:** The recording ID (`string`) if the request is already recorded, or `null` if the recording was queued or is in progress.
+
+**Throws:** If the request ID is not found in `backend_requests`, or if the service call fails.
+
+### `createRequestRecording(blobUrlOrData, handlerPath, requestInfo): Promise<RecordingResult>`
+
+Called inside a recording container running under `replay-node`. Downloads the captured data blob (or accepts pre-parsed `BlobData`), installs replay-mode interceptors that return pre-recorded responses instead of making real calls, and executes the original handler so `replay-node` can record the execution.
+
+Returns a `RecordingResult` with mismatch detection:
+
+| Field | Type | Description |
+|---|---|---|
+| `responseMismatch` | boolean | Whether the replay response differs from the captured response |
+| `mismatchDetails` | string? | Description of the mismatch |
+| `replayResponse` | HandlerResponse? | The response produced during replay |
+| `capturedResponse` | HandlerResponse? | The original captured response |
+| `unconsumedNetworkCalls` | boolean | Whether some recorded network calls were not replayed |
+| `unconsumedNetworkDetails` | string? | Details about unconsumed calls |
+
+**Parameters:**
+- `blobUrlOrData` — URL to the captured data blob, or pre-parsed `BlobData` object
+- `handlerPath` — Path to the handler module to execute
+- `requestInfo` — The original request info to replay
+
+### `getCurrentRequestId(): string | null`
+
+Returns the request ID for the currently executing handler, or `null` if no handler is active. Useful for correlating logs or database operations with the current request.
+
+### `redactBlobData(data): BlobData`
+
+Redacts sensitive environment variable values from captured blob data before storage. Applied automatically by `finishRequest` — you only need to call this directly if using the lower-level APIs.
+
+Redaction rules:
+- Allow-listed keys (standard system/runtime variables like `NODE_ENV`, `PATH`, `COMMIT_SHA`) are never redacted
+- Values that are `undefined` or 8 characters or shorter are kept as-is
+- All other values are replaced with `*` repeated to the same length
+- Redacted values are also scrubbed from all other string fields in the blob (request headers, network call bodies, etc.) to prevent leakage through embedded values
+
+**Parameters:**
+- `data` — A `BlobData` object
+
+**Returns:** A new `BlobData` object with sensitive values masked.
 
 ### `databaseAuditEnsureLogTable(sql): Promise<void>`
 
@@ -403,10 +488,9 @@ These must be set on your Netlify site. Your deploy script should resolve them f
 | `COMMIT_SHA` | Git commit hash of the deployed code | `git rev-parse HEAD` |
 | `BRANCH_NAME` | Git branch of the deployed code | `git rev-parse --abbrev-ref HEAD` |
 | `REPLAY_REPOSITORY_URL` | Git repository URL (no embedded credentials) | `git remote get-url origin` (strip tokens) |
-| `NETLIFY_RECORDER_SECRET` | Secret for access control (strongly recommended) | `openssl rand -base64 32` — store in Netlify site env vars |
 
 ## How It Works
 
-1. **Capture phase** (`createRecordingRequestHandler` or `startRequest` / `finishRequest`): When a Netlify function handles a request, the recording layer patches `globalThis.fetch` and `process.env` with Proxies that record every outbound network call and environment variable read. When the handler completes, the originals are restored, the captured data is serialized to JSON, and sent to the Netlify Recorder service via `remoteCallbacks`.
+1. **Capture phase** (`createRecordingRequestHandler` or `startRequest` / `finishRequest`): When a Netlify function handles a request, the recording layer patches `globalThis.fetch` and `process.env` with Proxies that record every outbound network call and environment variable read. Sensitive environment variable values are automatically redacted. When the handler completes, the originals are restored, the captured data is serialized to JSON, and stored in the `backend_requests` table in your database via `databaseCallbacks`.
 
-2. **Recording phase**: The Netlify Recorder service dispatches the captured data to a recording container. Inside the container, the captured blob is downloaded, replay-mode interceptors return the pre-recorded responses instead of making real calls, and the original handler is re-executed under `replay-node`. Since replay-node records all execution, this produces a Replay recording of the exact same handler execution.
+2. **Recording phase**: To create a Replay recording, POST to the Netlify Recorder service's `create-recording` endpoint with a `blobDataUrl` pointing to the captured data. The service dispatches the work to a recording container, which fetches the blob data from the URL, installs replay-mode interceptors that return pre-recorded responses instead of making real calls, 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. The recording result includes mismatch detection — the service compares the replay response against the originally captured response to flag any divergence.