@replayio-app-building/netlify-recorder 0.1.0

package/README.md

@@ -0,0 +1,224 @@
+# @netlify-recorder/core
+
+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
+```
+
+## Quick Start
+
+### 1. Wrap your Netlify function with startRequest / finishRequest
+
+```typescript
+import { startRequest, finishRequest } from "@netlify-recorder/core";
+import type { Handler } from "@netlify/functions";
+
+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 {
+    // 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(
+      reqContext,
+      {
+        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,
+          });
+          const { url } = await res.json();
+          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')
+            RETURNING id
+          `;
+          return row.id;
+        },
+      },
+      {
+        statusCode: 200,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(result),
+      }
+    );
+  } catch (err) {
+    reqContext.cleanup(); // Always restore globals on error
+    throw err;
+  }
+};
+
+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(),
+  blob_url TEXT,
+  commit_sha TEXT,
+  handler_path TEXT,
+  recording_id TEXT,
+  status TEXT NOT NULL DEFAULT 'captured'
+    CHECK (status IN ('captured', 'processing', 'recorded', 'failed')),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+```
+
+**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 type { Handler } from "@netlify/functions";
+
+const handler: Handler = async (event) => {
+  const { requestId } = JSON.parse(event.body ?? "{}");
+
+  const recordingId = await ensureRequestRecording(requestId, {
+    repositoryUrl: process.env.APP_REPOSITORY_URL!,
+    replayApiKey: process.env.RECORD_REPLAY_API_KEY!,
+    lookupRequest: async (id) => {
+      const [row] = await sql`
+        SELECT blob_url, commit_sha, branch_name, handler_path
+        FROM requests WHERE id = ${id}
+      `;
+      return {
+        blobUrl: row.blob_url,
+        commitSha: row.commit_sha,
+        branchName: row.branch_name ?? "main",
+        handlerPath: row.handler_path,
+      };
+    },
+    updateStatus: async (id, status, recordingId) => {
+      await sql`
+        UPDATE requests
+        SET status = ${status},
+            recording_id = ${recordingId ?? null},
+            updated_at = NOW()
+        WHERE id = ${id}
+      `;
+    },
+  });
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify({ recordingId }),
+  };
+};
+
+export { handler };
+```
+
+### 4. Create a container script for createRequestRecording
+
+This script runs inside the container spawned by `ensureRequestRecording`, under `replay-node`:
+
+```typescript
+// scripts/create-request-recording.ts
+import { createRequestRecording } from "@netlify-recorder/core";
+
+const args = process.argv.slice(2);
+const blobUrl = args[args.indexOf("--blob-url") + 1]!;
+const handlerPath = args[args.indexOf("--handler-path") + 1]!;
+
+await createRequestRecording(blobUrl, handlerPath, {
+  method: "POST",
+  url: handlerPath,
+  headers: {},
+});
+```
+
+## API Reference
+
+### `startRequest(requestInfo): RequestContext`
+
+Begins capturing a Netlify handler execution. Patches `globalThis.fetch` and `process.env` to record all outbound network calls and environment variable reads.
+
+**Parameters:**
+- `requestInfo.method` — HTTP method of the incoming request
+- `requestInfo.url` — Request URL/path
+- `requestInfo.headers` — Request headers
+- `requestInfo.body` — Optional request body
+
+**Returns:** A `RequestContext` object to pass to `finishRequest`.
+
+### `finishRequest(requestContext, callbacks, response): 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.
+
+**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
+- `response` — The handler's response object (`{ statusCode, headers?, body? }`)
+
+### `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.
+
+**Parameters:**
+- `requestId` — The request to create a recording for
+- `options.repositoryUrl` — Git repository URL for the container to clone
+- `options.replayApiKey` — Replay API key for recording upload
+- `options.lookupRequest(id)` — Fetches `{ blobUrl, commitSha, branchName, handlerPath }` from the database
+- `options.updateStatus(id, status, recordingId?)` — Updates the request status in the database
+
+### `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.
+
+**Parameters:**
+- `blobUrl` — URL to the captured data blob
+- `handlerPath` — Path to the handler module to execute
+- `requestInfo` — The original request info to replay
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `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 |
+
+## 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.

package/dist/index.d.ts

@@ -0,0 +1,209 @@
+interface RequestInfo {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+}
+interface RequestContext {
+    requestInfo: RequestInfo;
+    capturedData: CapturedData;
+    startTime: number;
+    /** Restores original globals (fetch, process.env). Called automatically by finishRequest. */
+    cleanup: () => void;
+}
+interface CapturedData {
+    networkCalls: NetworkCall[];
+    envReads: EnvRead[];
+}
+interface NetworkCall {
+    url: string;
+    method: string;
+    requestHeaders: Record<string, string>;
+    requestBody?: string;
+    responseStatus: number;
+    responseHeaders: Record<string, string>;
+    responseBody?: string;
+    timestamp: number;
+}
+interface EnvRead {
+    key: string;
+    value: string | undefined;
+    timestamp: number;
+}
+interface BlobData {
+    requestInfo: RequestInfo;
+    capturedData: CapturedData;
+    /** Git commit SHA of the code that served this request. */
+    commitSha: string;
+    startTime: number;
+    endTime: number;
+}
+interface FinishRequestCallbacks {
+    /** Uploads serialized captured data and returns the blob URL. */
+    uploadBlob: (data: string) => Promise<string>;
+    /** Stores request metadata in the database and returns the request ID. */
+    storeRequestData: (data: {
+        blobUrl: string;
+        commitSha: string;
+        branchName: string;
+        handlerPath: string;
+    }) => Promise<string>;
+}
+/**
+ * Infrastructure credentials required to start a recording container.
+ *
+ * The container is started on Fly.io via the `@replayio/app-building` package.
+ * It requires Infisical credentials (for secrets management inside the
+ * container) and a Fly.io token + app name.
+ *
+ * These must be set as environment variables on the Netlify site:
+ *   INFISICAL_CLIENT_ID, INFISICAL_CLIENT_SECRET,
+ *   INFISICAL_PROJECT_ID, INFISICAL_ENVIRONMENT,
+ *   FLY_API_TOKEN, FLY_APP_NAME
+ */
+interface ContainerInfraConfig {
+    infisicalClientId: string;
+    infisicalClientSecret: string;
+    infisicalProjectId: string;
+    infisicalEnvironment: string;
+    flyToken: string;
+    flyApp: string;
+}
+interface EnsureRecordingOptions {
+    repositoryUrl: string;
+    replayApiKey: string;
+    /** Infrastructure credentials for starting the recording container. */
+    infraConfig?: ContainerInfraConfig;
+    /** Webhook URL the container can POST log entries to (optional). */
+    webhookUrl?: string;
+    /** Looks up request metadata by ID. */
+    lookupRequest: (requestId: string) => Promise<{
+        blobUrl: string;
+        commitSha: string;
+        branchName: string;
+        handlerPath: string;
+    }>;
+    /** Updates the request status (and optionally recording ID) in the database. */
+    updateStatus: (requestId: string, status: string, recordingId?: string) => Promise<void>;
+    /** Optional callback for the caller to emit structured log entries. */
+    onLog?: (level: "info" | "warn" | "error", message: string) => Promise<void>;
+}
+
+/**
+ * Called at the beginning of a Netlify handler execution.
+ * Installs interceptors on globalThis.fetch and process.env to capture
+ * outbound network calls and environment variable reads made by the handler.
+ * Returns a request context used by finishRequest.
+ *
+ * When running inside createRequestRecording (replay mode), the replay
+ * interceptors are already installed.  In that case we skip installing
+ * capture interceptors to avoid overwriting the replay layer (which would
+ * also crash on Node v16 where Headers/Response don't exist).
+ */
+declare function startRequest(requestInfo: RequestInfo): RequestContext;
+
+interface HandlerResponse {
+    statusCode: number;
+    headers?: Record<string, string>;
+    body?: string;
+}
+interface FinishRequestOptions {
+    handlerPath?: string;
+}
+/**
+ * Called at the end of the handler execution.
+ * Restores original globals, serializes all captured data,
+ * uploads it as a JSON blob via the provided callback,
+ * stores the request metadata, and sets the X-Replay-Request-Id header.
+ */
+declare function finishRequest(requestContext: RequestContext, callbacks: FinishRequestCallbacks, response: HandlerResponse, options?: FinishRequestOptions): Promise<HandlerResponse>;
+
+/**
+ * Redacts sensitive environment variable values from blob data.
+ *
+ * This function performs two passes:
+ *
+ *  Pass 1 — Redact env reads:
+ *    For each captured EnvRead whose value should be redacted,
+ *    replace the value with a "*"-repeated string of the same length.
+ *
+ *  Pass 2 — Scrub the rest of the blob:
+ *    Any redacted value that appears elsewhere in the blob data
+ *    (network call headers, bodies, request info headers/body) is
+ *    also replaced with the same mask. This prevents secrets from
+ *    leaking through, e.g., an Authorization header that embeds
+ *    an API key captured via process.env.
+ *
+ * The function returns a new BlobData object; the input is not mutated.
+ */
+declare function redactBlobData(blobData: BlobData): BlobData;
+
+/**
+ * Called by a background function to convert a request ID into a Replay recording ID.
+ *
+ * The function:
+ *  1. Looks up request metadata (blob URL, commit, handler path).
+ *  2. Delegates to `spawnRecordingContainer` which starts a detached Fly.io
+ *     container, runs the recording script under replay-node, and uploads
+ *     the resulting recording.
+ *  3. Updates the request status with the recording ID.
+ *
+ * **Required infrastructure:** Infisical credentials and a Fly.io token/app.
+ * See `ContainerInfraConfig` in types.ts for details. When these are not
+ * configured the function fails with an actionable error message listing
+ * the missing environment variables.
+ */
+declare function ensureRequestRecording(requestId: string, options: EnsureRecordingOptions): Promise<string>;
+/**
+ * Reads infrastructure config from environment variables.
+ * Returns undefined if any required variable is missing.
+ */
+declare function readInfraConfigFromEnv(): ContainerInfraConfig | undefined;
+
+/**
+ * Called from within a container (running under replay-node) to create a Replay recording.
+ * Installs replay-mode interceptors that return pre-recorded responses, then executes
+ * the original handler so that replay-node can record the execution.
+ *
+ * Accepts either a blob URL (fetched at runtime) or pre-parsed BlobData (avoids needing
+ * globalThis.fetch, which is missing in replay-node's Node v16 environment).
+ */
+declare function createRequestRecording(blobUrlOrData: string | BlobData, handlerPath: string, requestInfo: RequestInfo): Promise<void>;
+
+/**
+ * Options for spawning a recording container from a blob URL.
+ * This is the core building block — it knows nothing about request IDs or databases.
+ */
+interface SpawnRecordingContainerOptions {
+    /** URL (or data: URI) of the captured request blob JSON. */
+    blobUrl: string;
+    /** Handler file path relative to the app root (e.g. "netlify/functions/generate-haiku"). */
+    handlerPath: string;
+    /** Git commit SHA to check out inside the container. */
+    commitSha: string;
+    /** Git branch to clone. */
+    branchName: string;
+    /** Git repository URL for the app. */
+    repositoryUrl: string;
+    /** Replay API key for uploading recordings. */
+    replayApiKey: string;
+    /** Infrastructure credentials for Fly.io + Infisical. */
+    infraConfig: ContainerInfraConfig;
+    /** Optional webhook URL the container can POST log events to. */
+    logWebhookUrl?: string;
+    /** Optional callback for structured log entries. */
+    onLog?: (level: "info" | "warn" | "error", message: string) => Promise<void>;
+}
+/**
+ * Spawns a detached Fly.io container that:
+ *  1. Clones the app repo at the correct branch
+ *  2. Checks out the exact commit
+ *  3. Runs `scripts/create-request-recording.ts` under replay-node
+ *  4. Uploads the resulting recording
+ *  5. Outputs the recording ID
+ *
+ * Returns the recording ID on success, or throws on failure.
+ */
+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 };

package/dist/index.js

@@ -0,0 +1,614 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/interceptors/network.ts
+function installNetworkInterceptor(mode, calls) {
+  const originalFetch = globalThis.fetch;
+  if (mode === "capture") {
+    const captureFetch = async (input, init) => {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+      const method = init?.method ?? (input instanceof Request ? input.method : "GET");
+      const requestHeaders = {};
+      if (init?.headers) {
+        new Headers(init.headers).forEach((v, k) => {
+          requestHeaders[k] = v;
+        });
+      }
+      const requestBody = typeof init?.body === "string" ? init.body : void 0;
+      const response = await originalFetch(input, init);
+      const responseBody = await response.clone().text();
+      const responseHeaders = {};
+      response.headers.forEach((v, k) => {
+        responseHeaders[k] = v;
+      });
+      calls.push({
+        url,
+        method,
+        requestHeaders,
+        requestBody,
+        responseStatus: response.status,
+        responseHeaders,
+        responseBody,
+        timestamp: Date.now()
+      });
+      return response;
+    };
+    globalThis.fetch = captureFetch;
+  } else {
+    let callIndex = 0;
+    const replayFetch = async () => {
+      const call = calls[callIndex++];
+      if (!call) {
+        throw new Error(
+          `No more recorded network calls to replay (exhausted ${calls.length} calls)`
+        );
+      }
+      const body = call.responseBody ?? "";
+      const status = call.responseStatus;
+      return {
+        ok: status >= 200 && status < 300,
+        status,
+        statusText: "",
+        headers: {
+          get: (name) => (call.responseHeaders ?? {})[name.toLowerCase()] ?? null,
+          has: (name) => name.toLowerCase() in (call.responseHeaders ?? {}),
+          forEach: (cb) => {
+            for (const [k, v] of Object.entries(call.responseHeaders ?? {})) cb(v, k);
+          }
+        },
+        text: async () => body,
+        json: async () => JSON.parse(body),
+        clone: () => ({ text: async () => body, json: async () => JSON.parse(body) }),
+        body: null,
+        bodyUsed: false,
+        redirected: false,
+        type: "basic",
+        url: call.url,
+        arrayBuffer: async () => new ArrayBuffer(0),
+        blob: async () => {
+          throw new Error("blob() not supported in replay");
+        },
+        formData: async () => {
+          throw new Error("formData() not supported in replay");
+        }
+      };
+    };
+    globalThis.fetch = replayFetch;
+  }
+  return {
+    restore() {
+      globalThis.fetch = originalFetch;
+    }
+  };
+}
+
+// src/interceptors/environment.ts
+function installEnvironmentInterceptor(mode, reads) {
+  const originalEnv = process.env;
+  if (mode === "capture") {
+    process.env = new Proxy(originalEnv, {
+      get(target, prop) {
+        const value = target[prop];
+        if (typeof prop === "string" && prop !== "toJSON") {
+          reads.push({ key: prop, value, timestamp: Date.now() });
+        }
+        return value;
+      }
+    });
+  } else {
+    const readMap = /* @__PURE__ */ new Map();
+    for (const read of reads) {
+      readMap.set(read.key, read.value);
+    }
+    process.env = new Proxy(originalEnv, {
+      get(target, prop) {
+        if (typeof prop === "string" && readMap.has(prop)) {
+          return readMap.get(prop);
+        }
+        return target[prop];
+      }
+    });
+  }
+  return {
+    restore() {
+      process.env = originalEnv;
+    }
+  };
+}
+
+// src/startRequest.ts
+function startRequest(requestInfo) {
+  const capturedData = { networkCalls: [], envReads: [] };
+  const isReplay = globalThis.__REPLAY_RECORDING_MODE__ === true;
+  let cleanup;
+  if (isReplay) {
+    cleanup = () => {
+    };
+  } else {
+    const networkHandle = installNetworkInterceptor("capture", capturedData.networkCalls);
+    const envHandle = installEnvironmentInterceptor("capture", capturedData.envReads);
+    cleanup = () => {
+      networkHandle.restore();
+      envHandle.restore();
+    };
+  }
+  return {
+    requestInfo,
+    capturedData,
+    startTime: Date.now(),
+    cleanup
+  };
+}
+
+// src/redact.ts
+var ENV_ALLOW_LIST = /* @__PURE__ */ new Set([
+  // Node / runtime
+  "NODE_ENV",
+  "NODE_VERSION",
+  "NODE_PATH",
+  "NODE_OPTIONS",
+  "NPM_CONFIG_PREFIX",
+  // OS / shell
+  "HOME",
+  "PATH",
+  "USER",
+  "SHELL",
+  "LANG",
+  "LC_ALL",
+  "PWD",
+  "HOSTNAME",
+  "TZ",
+  "TERM",
+  "EDITOR",
+  "TMPDIR",
+  "LOGNAME",
+  // Deploy metadata (non-secret identifiers)
+  "COMMIT_SHA",
+  // Common non-secret Netlify build vars
+  "NETLIFY",
+  "NETLIFY_DEV",
+  "CONTEXT",
+  "DEPLOY_PRIME_URL",
+  "URL",
+  "SITE_NAME",
+  "BUILD_ID",
+  "DEPLOY_ID",
+  "DEPLOY_URL",
+  "REPOSITORY_URL",
+  "APP_REPOSITORY_URL",
+  "BRANCH",
+  "HEAD",
+  "COMMIT_REF",
+  "PULL_REQUEST",
+  "REVIEW_ID",
+  "LAMBDA_TASK_ROOT",
+  "AWS_REGION",
+  "AWS_EXECUTION_ENV",
+  "AWS_LAMBDA_FUNCTION_NAME",
+  "AWS_LAMBDA_FUNCTION_VERSION",
+  "AWS_LAMBDA_FUNCTION_MEMORY_SIZE"
+]);
+function shouldRedact(key, value) {
+  if (ENV_ALLOW_LIST.has(key)) return false;
+  if (value === void 0 || value.length <= 8) return false;
+  return true;
+}
+function replaceAll(text, searchValue, mask) {
+  return text.split(searchValue).join(mask);
+}
+function buildMask(value) {
+  return "*".repeat(value.length);
+}
+function redactBlobData(blobData) {
+  const redactions = /* @__PURE__ */ new Map();
+  const redactedEnvReads = blobData.capturedData.envReads.map(
+    (read) => {
+      if (shouldRedact(read.key, read.value) && read.value !== void 0) {
+        const mask = buildMask(read.value);
+        redactions.set(read.value, mask);
+        return { ...read, value: mask };
+      }
+      return { ...read };
+    }
+  );
+  if (redactions.size === 0) {
+    return {
+      ...blobData,
+      capturedData: {
+        ...blobData.capturedData,
+        envReads: redactedEnvReads
+      }
+    };
+  }
+  const sortedRedactions = [...redactions.entries()].sort(
+    (a, b) => b[0].length - a[0].length
+  );
+  function scrub(text) {
+    if (text === void 0) return void 0;
+    let result = text;
+    for (const [original, mask] of sortedRedactions) {
+      result = replaceAll(result, original, mask);
+    }
+    return result;
+  }
+  function scrubHeaders(headers) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers)) {
+      out[k] = scrub(v) ?? v;
+    }
+    return out;
+  }
+  const redactedRequestInfo = {
+    ...blobData.requestInfo,
+    url: scrub(blobData.requestInfo.url) ?? blobData.requestInfo.url,
+    headers: scrubHeaders(blobData.requestInfo.headers),
+    body: scrub(blobData.requestInfo.body)
+  };
+  const redactedNetworkCalls = blobData.capturedData.networkCalls.map(
+    (call) => ({
+      ...call,
+      url: scrub(call.url) ?? call.url,
+      requestHeaders: scrubHeaders(call.requestHeaders),
+      requestBody: scrub(call.requestBody),
+      responseHeaders: scrubHeaders(call.responseHeaders),
+      responseBody: scrub(call.responseBody)
+    })
+  );
+  return {
+    ...blobData,
+    requestInfo: redactedRequestInfo,
+    capturedData: {
+      networkCalls: redactedNetworkCalls,
+      envReads: redactedEnvReads
+    }
+  };
+}
+
+// src/finishRequest.ts
+async function finishRequest(requestContext, callbacks, response, options) {
+  requestContext.cleanup();
+  if (globalThis.__REPLAY_RECORDING_MODE__ === true) {
+    return response;
+  }
+  const commitSha = process.env.COMMIT_SHA ?? "HEAD";
+  const branchName = process.env.BRANCH_NAME ?? "main";
+  const rawBlobData = {
+    requestInfo: requestContext.requestInfo,
+    capturedData: requestContext.capturedData,
+    commitSha,
+    startTime: requestContext.startTime,
+    endTime: Date.now()
+  };
+  const blobData = redactBlobData(rawBlobData);
+  const blobContent = JSON.stringify(blobData);
+  const blobUrl = await callbacks.uploadBlob(blobContent);
+  const storedRequestId = await callbacks.storeRequestData({
+    blobUrl,
+    commitSha,
+    branchName,
+    handlerPath: options?.handlerPath ?? "unknown"
+  });
+  return {
+    ...response,
+    headers: {
+      ...response.headers,
+      "X-Replay-Request-Id": storedRequestId
+    }
+  };
+}
+
+// src/spawnRecordingContainer.ts
+async function spawnRecordingContainer(options) {
+  const {
+    blobUrl,
+    handlerPath,
+    commitSha,
+    branchName,
+    repositoryUrl,
+    replayApiKey,
+    infraConfig,
+    logWebhookUrl,
+    onLog
+  } = options;
+  const emit = async (level, message) => {
+    if (onLog) {
+      try {
+        await onLog(level, message);
+      } catch {
+      }
+    }
+  };
+  await emit("info", "Logging in to Infisical");
+  const {
+    infisicalLogin,
+    startContainer,
+    FileContainerRegistry,
+    httpGet,
+    httpOptsFor
+  } = await import("@replayio/app-building");
+  const infisicalToken = await infisicalLogin(
+    infraConfig.infisicalClientId,
+    infraConfig.infisicalClientSecret
+  );
+  const infisicalConfig = {
+    token: infisicalToken,
+    projectId: infraConfig.infisicalProjectId,
+    environment: infraConfig.infisicalEnvironment
+  };
+  const registry = new FileContainerRegistry("/tmp/netlify-recorder-containers.json");
+  const initialPrompt = [
+    `IMPORTANT: Follow these steps EXACTLY. Run each command as shown. Print ALL output.`,
+    `Do NOT explore the codebase, read AGENTS.md, or deviate from these steps.`,
+    `Do NOT attempt to debug, fix, shim, or work around ANY errors. If a command fails,`,
+    `print the full error output and move on to the next step. Errors during handler replay`,
+    `(like "No more recorded network calls" or DB errors) are EXPECTED and harmless.`,
+    ``,
+    `=== Step 1: Install dependencies ===`,
+    `cd /repo/apps/netlify-recorder && npm install 2>&1`,
+    ``,
+    `=== Step 2: Checkout the exact commit ===`,
+    `git fetch origin ${commitSha} 2>&1 || git fetch --all 2>&1`,
+    `git checkout ${commitSha} 2>&1`,
+    ``,
+    `=== Step 3: Verify recording script exists ===`,
+    `ls -la /repo/apps/netlify-recorder/scripts/create-request-recording.ts`,
+    `If the file does NOT exist, print "ERROR: create-request-recording.ts not found" and STOP.`,
+    ``,
+    `=== Step 4: Pre-compile for replay-node (Node v16) ===`,
+    `replay-node is Node v16 \u2014 it cannot run TypeScript or use modern APIs directly.`,
+    `You MUST compile everything with esbuild first. Run these commands exactly:`,
+    ``,
+    `# Install undici for web API polyfills (fetch, Headers, Response):`,
+    `cd /repo/apps/netlify-recorder && npm install undici@5 2>&1`,
+    ``,
+    `# Create the polyfill loader:`,
+    `cat > /tmp/web-polyfill.cjs << 'POLYFILL'`,
+    `try {`,
+    `  var u = require("undici");`,
+    `  if (!globalThis.fetch) globalThis.fetch = u.fetch;`,
+    `  if (!globalThis.Headers) globalThis.Headers = u.Headers;`,
+    `  if (!globalThis.Response) globalThis.Response = u.Response;`,
+    `  if (!globalThis.Request) globalThis.Request = u.Request;`,
+    `} catch(e) { console.error("polyfill warning:", e.message); }`,
+    `POLYFILL`,
+    ``,
+    `# Compile the recording script (bundles all local TS dependencies):`,
+    `npx esbuild scripts/create-request-recording.ts \\`,
+    `  --bundle --platform=node --target=node16 --format=cjs \\`,
+    `  --outfile=/tmp/create-recording.cjs 2>&1`,
+    ``,
+    `# Compile the handler (bundles everything including node_modules):`,
+    `npx esbuild ${handlerPath}.ts \\`,
+    `  --bundle --platform=node --target=node16 --format=cjs \\`,
+    `  --outfile=/tmp/handler.cjs 2>&1`,
+    ``,
+    `=== Step 5: Run under replay-node ===`,
+    `This MUST use replay-node so the execution is recorded. Run exactly:`,
+    ``,
+    `cd /repo/apps/netlify-recorder && npx @replayio/node \\`,
+    `  -r /tmp/web-polyfill.cjs /tmp/create-recording.cjs \\`,
+    `  --blob-url '${blobUrl}' \\`,
+    `  --handler-path '/tmp/handler.cjs' 2>&1`,
+    ``,
+    `The output will show captured data being replayed. Errors like "No more recorded`,
+    `network calls" or "DATABASE_URL" errors are EXPECTED \u2014 they come from post-handler`,
+    `DB operations that were not in the original blob. Do NOT try to fix these.`,
+    ``,
+    `=== Step 6: Upload the recording ===`,
+    `RECORD_REPLAY_API_KEY=${replayApiKey} npx replayio upload --all 2>&1`,
+    ``,
+    `Find the recording ID (UUID) in the upload output and print:`,
+    `  recording: <recording-id>`,
+    ``,
+    `Then output <DONE>.`
+  ].join("\n");
+  await emit("info", "Starting detached container on Fly.io");
+  const state = await startContainer(
+    {
+      infisical: infisicalConfig,
+      registry,
+      flyToken: infraConfig.flyToken,
+      flyApp: infraConfig.flyApp,
+      detached: true,
+      initialPrompt,
+      webhookUrl: logWebhookUrl
+    },
+    {
+      repoUrl: repositoryUrl,
+      cloneBranch: branchName
+    }
+  );
+  await emit("info", `Container started: ${state.containerName} at ${state.baseUrl}`);
+  const maxWaitMs = 10 * 60 * 1e3;
+  const pollIntervalMs = 1e4;
+  const deadline = Date.now() + maxWaitMs;
+  let containerDone = false;
+  while (Date.now() < deadline) {
+    try {
+      const status = await httpGet(`${state.baseUrl}/status`, httpOptsFor(state));
+      if (status?.state === "stopped" || status?.state === "stopping") {
+        containerDone = true;
+        break;
+      }
+    } catch {
+      containerDone = true;
+      break;
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+  }
+  if (!containerDone) {
+    await emit("warn", "Container did not finish within 10 minutes");
+  }
+  let recordingId = null;
+  try {
+    const logs = await httpGet(`${state.baseUrl}/logs?offset=0`, httpOptsFor(state));
+    if (typeof logs === "string") {
+      const match = logs.match(/recording[:\s]+([a-f0-9-]{36})/i);
+      if (match?.[1]) {
+        recordingId = match[1];
+      }
+    }
+  } catch {
+    await emit("warn", "Could not read container logs after exit");
+  }
+  if (!recordingId) {
+    await emit("error", "Container completed but no recording ID was found in output");
+    throw new Error("Recording creation failed: no recording ID returned from container");
+  }
+  await emit("info", `Container completed \u2014 recording ID: ${recordingId}`);
+  return recordingId;
+}
+
+// src/ensureRequestRecording.ts
+async function ensureRequestRecording(requestId, options) {
+  const { repositoryUrl, replayApiKey, infraConfig, webhookUrl, lookupRequest, updateStatus, onLog } = options;
+  const emit = async (level, message) => {
+    if (onLog) {
+      try {
+        await onLog(level, message);
+      } catch {
+      }
+    }
+  };
+  await updateStatus(requestId, "processing");
+  try {
+    if (!infraConfig) {
+      const missing = getMissingInfraVars();
+      throw new Error(
+        `Container infrastructure not configured. Missing environment variables: ${missing.join(", ")}. These must be set on the Netlify site for recording creation to work.`
+      );
+    }
+    const requestData = await lookupRequest(requestId);
+    await emit("info", `Request data retrieved \u2014 handler: ${requestData.handlerPath}, branch: ${requestData.branchName}, commit: ${requestData.commitSha}`);
+    const recordingId = await spawnRecordingContainer({
+      blobUrl: requestData.blobUrl,
+      handlerPath: requestData.handlerPath,
+      commitSha: requestData.commitSha,
+      branchName: requestData.branchName,
+      repositoryUrl,
+      replayApiKey,
+      infraConfig,
+      logWebhookUrl: webhookUrl,
+      onLog
+    });
+    await emit("info", `Recording created successfully: ${recordingId}`);
+    await updateStatus(requestId, "recorded", recordingId);
+    return recordingId;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    await emit("error", `Recording creation failed: ${message}`);
+    await updateStatus(requestId, "failed");
+    throw err;
+  }
+}
+function getMissingInfraVars() {
+  const required = [
+    "INFISICAL_CLIENT_ID",
+    "INFISICAL_CLIENT_SECRET",
+    "INFISICAL_PROJECT_ID",
+    "INFISICAL_ENVIRONMENT",
+    "FLY_API_TOKEN",
+    "FLY_APP_NAME"
+  ];
+  return required.filter((name) => !process.env[name]);
+}
+function readInfraConfigFromEnv() {
+  const clientId = process.env.INFISICAL_CLIENT_ID;
+  const clientSecret = process.env.INFISICAL_CLIENT_SECRET;
+  const projectId = process.env.INFISICAL_PROJECT_ID;
+  const environment = process.env.INFISICAL_ENVIRONMENT;
+  const flyToken = process.env.FLY_API_TOKEN;
+  const flyApp = process.env.FLY_APP_NAME;
+  if (!clientId || !clientSecret || !projectId || !environment || !flyToken || !flyApp) {
+    return void 0;
+  }
+  return {
+    infisicalClientId: clientId,
+    infisicalClientSecret: clientSecret,
+    infisicalProjectId: projectId,
+    infisicalEnvironment: environment,
+    flyToken,
+    flyApp
+  };
+}
+
+// src/createRequestRecording.ts
+async function createRequestRecording(blobUrlOrData, handlerPath, requestInfo) {
+  let blobData;
+  if (typeof blobUrlOrData === "string") {
+    const response = await fetch(blobUrlOrData);
+    if (!response.ok) {
+      throw new Error(
+        `Failed to download blob from ${blobUrlOrData}: ${response.status}`
+      );
+    }
+    blobData = await response.json();
+  } else {
+    blobData = blobUrlOrData;
+  }
+  for (const read of blobData.capturedData.envReads) {
+    if (read.value && read.value.length > 8 && /^\*+$/.test(read.value)) {
+      if (read.key === "DATABASE_URL" || read.key.endsWith("_DATABASE_URL")) {
+        read.value = "postgresql://replay:replay@localhost:5432/replay";
+      } else {
+        read.value = `placeholder_${read.key.toLowerCase()}`;
+      }
+    }
+  }
+  const networkHandle = installNetworkInterceptor(
+    "replay",
+    blobData.capturedData.networkCalls
+  );
+  const envHandle = installEnvironmentInterceptor(
+    "replay",
+    blobData.capturedData.envReads
+  );
+  globalThis.__REPLAY_RECORDING_MODE__ = true;
+  const g = globalThis;
+  if (typeof g.Blob === "undefined") {
+    try {
+      const { Blob } = __require("buffer");
+      g.Blob = Blob;
+    } catch {
+    }
+  }
+  if (typeof g.File === "undefined") {
+    const B = g.Blob ?? Object;
+    const FileShim = class File {
+      name;
+      lastModified;
+      constructor(parts, name, options) {
+        Object.assign(this, new B(parts, options));
+        this.name = name;
+        this.lastModified = Date.now();
+      }
+    };
+    g.File = FileShim;
+  }
+  try {
+    const handlerModule = await import(handlerPath);
+    await handlerModule.handler({
+      httpMethod: requestInfo.method,
+      path: requestInfo.url,
+      headers: requestInfo.headers,
+      body: requestInfo.body ?? null
+    });
+  } finally {
+    globalThis.__REPLAY_RECORDING_MODE__ = false;
+    networkHandle.restore();
+    envHandle.restore();
+  }
+}
+export {
+  createRequestRecording,
+  ensureRequestRecording,
+  finishRequest,
+  readInfraConfigFromEnv,
+  redactBlobData,
+  spawnRecordingContainer,
+  startRequest
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@replayio-app-building/netlify-recorder",
+  "version": "0.1.0",
+  "description": "Capture and replay Netlify function executions as Replay recordings",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "check": "tsc --noEmit",
+    "prepublishOnly": "tsup"
+  },
+  "peerDependencies": {
+    "@replayio/app-building": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@replayio/app-building": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@replayio/app-building": "^1.28.0",
+    "@types/node": "^25.6.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.3"
+  }
+}