@replayio-app-building/netlify-recorder 0.7.0 → 0.9.0

package/README.md

@@ -46,44 +46,36 @@ const repositoryUrl = execSync("git remote get-url origin", { encoding: "utf-8"
 
 ### 2. Wrap your Netlify function
 
-Use `startRequest` / `finishRequest` with `remoteCallbacks()` to capture request data and send it to the service:
+Use `createRecordingRequestHandler` with `remoteCallbacks()` to wrap your handler with automatic request capture:
 
 ```typescript
 import {
-  startRequest,
-  finishRequest,
+  createRecordingRequestHandler,
   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(event);
-
-  try {
+const handler = createRecordingRequestHandler(
+  async (event) => {
     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;
+    return {
+      statusCode: 200,
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(result),
+    };
+  },
+  {
+    callbacks: remoteCallbacks(RECORDER_URL),
+    handlerPath: "netlify/functions/my-handler",
   }
-};
+);
 
 export { handler };
 ```
 
-The `remoteCallbacks(url)` helper sends the captured blob data — including the repository URL, branch, and commit — to the Netlify Recorder service's `/api/store-request` endpoint, 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.
+`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.
 
 ### 2. Create recordings
 
@@ -142,50 +134,43 @@ Same as Option A — you must set `REPLAY_REPOSITORY_URL`, `COMMIT_SHA`, and `BR
 
 ### 2. Wrap your Netlify function
 
-Use `startRequest` / `finishRequest` with custom callbacks that write to your own storage and database:
+Use `createRecordingRequestHandler` 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) => {
-  const reqContext = startRequest(event);
+import { createRecordingRequestHandler } from "@replayio-app-building/netlify-recorder";
 
-  try {
+const handler = createRecordingRequestHandler(
+  async (event) => {
     const result = await myBusinessLogic();
 
-    return await finishRequest(
-      reqContext,
-      {
-        uploadBlob: async (data) => {
-          // Upload the JSON string to your blob storage (S3, R2, etc.)
-          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, repositoryUrl, handlerPath }) => {
-          const [row] = await sql`
-            INSERT INTO requests (blob_url, commit_sha, branch_name, repository_url, handler_path, status)
-            VALUES (${blobUrl}, ${commitSha}, ${branchName}, ${repositoryUrl}, ${handlerPath}, 'captured')
-            RETURNING id
-          `;
-          return row.id;
-        },
+    return {
+      statusCode: 200,
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(result),
+    };
+  },
+  {
+    callbacks: {
+      uploadBlob: async (data) => {
+        // Upload the JSON string to your blob storage (S3, R2, etc.)
+        const res = await fetch("https://storage.example.com/upload", {
+          method: "PUT",
+          body: data,
+        });
+        const { url } = await res.json();
+        return url;
+      },
+      storeRequestData: async ({ blobUrl, commitSha, branchName, repositoryUrl, handlerPath }) => {
+        const [row] = await sql`
+          INSERT INTO requests (blob_url, commit_sha, branch_name, repository_url, handler_path, status)
+          VALUES (${blobUrl}, ${commitSha}, ${branchName}, ${repositoryUrl}, ${handlerPath}, 'captured')
+          RETURNING id
+        `;
+        return row.id;
       },
-      {
-        statusCode: 200,
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(result),
-      }
-    );
-  } catch (err) {
-    reqContext.cleanup();
-    throw err;
+    },
   }
-};
+);
 
 export { handler };
 ```
@@ -290,9 +275,23 @@ Self-hosted recording requires these environment variables:
 
 ## API Reference
 
+### `createRecordingRequestHandler(handler, options): Handler`
+
+Wraps a Netlify handler function with automatic request recording. This is the recommended way to integrate — it handles `startRequest`/`finishRequest` and error cleanup internally.
+
+**Parameters:**
+- `handler` — Your async handler function `(event, context?) => Promise<{ statusCode, headers?, body? }>`
+- `options.callbacks` — Either `remoteCallbacks(serviceUrl)` or custom `{ uploadBlob, storeRequestData }` callbacks
+- `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
+
+**Returns:** A wrapped handler function with the same signature.
+
 ### `startRequest(event): RequestContext`
 
-Begins capturing a Netlify handler execution. Accepts the raw Netlify event object and extracts all request metadata internally (method, path, headers, body, query string parameters, etc.). Patches `globalThis.fetch` and `process.env` to record all outbound network calls and environment variable reads.
+Lower-level API. Begins capturing a Netlify handler execution. Patches `globalThis.fetch` and `process.env` to record all outbound network calls and environment variable reads. Use this with `finishRequest` when you need more control than `createRecordingRequestHandler` provides.
 
 **Parameters:**
 - `event` — The Netlify handler event object (passed directly)
@@ -301,7 +300,7 @@ Begins capturing a Netlify handler execution. Accepts the raw Netlify event obje
 
 ### `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 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, uploads it via the callbacks, and returns the response with `X-Replay-Request-Id` header set.
 
 **Requires** the following environment variables (or equivalent options overrides): `COMMIT_SHA`, `BRANCH_NAME`, `REPLAY_REPOSITORY_URL`. Throws if any are missing.
 
@@ -362,6 +361,6 @@ These must be set on your Netlify site. Your deploy script should resolve them f
 
 ## 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, and sends it to either the remote service (via `remoteCallbacks`) or your own storage (via custom callbacks).
+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 either the remote service (via `remoteCallbacks`) or your own storage (via custom callbacks).
 
 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

@@ -57,7 +57,7 @@ interface EnvRead {
     value: string | undefined;
     timestamp: number;
 }
-interface HandlerResponse {
+interface HandlerResponse$1 {
     statusCode: number;
     body?: string;
 }
@@ -69,7 +69,7 @@ interface BlobData {
     startTime: number;
     endTime: number;
     /** The response returned to the client, used to detect replay mismatches. */
-    handlerResponse?: HandlerResponse;
+    handlerResponse?: HandlerResponse$1;
 }
 interface FinishRequestCallbacks {
     /** Uploads serialized captured data and returns the blob URL. */
@@ -160,6 +160,45 @@ interface FinishRequestOptions {
  */
 declare function finishRequest(requestContext: RequestContext, callbacks: FinishRequestCallbacks, response: FullHandlerResponse, options?: FinishRequestOptions): Promise<FullHandlerResponse>;
 
+interface HandlerResponse {
+    statusCode: number;
+    headers?: Record<string, string>;
+    body?: string;
+}
+interface CreateRecordingRequestHandlerOptions extends FinishRequestOptions {
+    callbacks: FinishRequestCallbacks;
+}
+/**
+ * Wraps a Netlify handler function with request recording.
+ *
+ * Automatically calls `startRequest` before the handler and `finishRequest`
+ * after, capturing all outbound network calls and environment variable reads.
+ * On error, interceptors are cleaned up and the error is re-thrown.
+ *
+ * @example
+ * ```typescript
+ * import { createRecordingRequestHandler, remoteCallbacks } from "@replayio-app-building/netlify-recorder";
+ *
+ * const handler = createRecordingRequestHandler(
+ *   async (event) => {
+ *     const result = await myBusinessLogic();
+ *     return {
+ *       statusCode: 200,
+ *       headers: { "Content-Type": "application/json" },
+ *       body: JSON.stringify(result),
+ *     };
+ *   },
+ *   {
+ *     callbacks: remoteCallbacks("https://netlify-recorder-bm4wmw.netlify.app"),
+ *     handlerPath: "netlify/functions/my-handler",
+ *   }
+ * );
+ *
+ * export { handler };
+ * ```
+ */
+declare function createRecordingRequestHandler(handler: (event: NetlifyEvent | Record<string, unknown>, context?: unknown) => Promise<HandlerResponse>, options: CreateRecordingRequestHandlerOptions): (event: NetlifyEvent | Record<string, unknown>, context?: unknown) => Promise<HandlerResponse>;
+
 /**
  * Creates `FinishRequestCallbacks` that send captured data to a remote
  * Netlify Recorder service. This removes the need for the consuming app
@@ -222,9 +261,9 @@ interface RecordingResult {
     /** Details about the mismatch, if any. */
     mismatchDetails?: string;
     /** The response produced during replay. */
-    replayResponse?: HandlerResponse;
+    replayResponse?: HandlerResponse$1;
     /** The original response captured in the blob. */
-    capturedResponse?: HandlerResponse;
+    capturedResponse?: HandlerResponse$1;
     /** Whether some recorded network calls were not consumed during replay. */
     unconsumedNetworkCalls: boolean;
     /** Details about unconsumed network calls, if any. */
@@ -276,4 +315,4 @@ interface SpawnRecordingContainerOptions {
  */
 declare function spawnRecordingContainer(options: SpawnRecordingContainerOptions): Promise<string>;
 
-export { type BlobData, type CapturedData, type ContainerInfraConfig, type EnsureRecordingOptions, type EnvRead, type FinishRequestCallbacks, type FinishRequestOptions, type HandlerResponse, type NetlifyEvent, type NetworkCall, type RecordingResult, type RequestContext, type RequestInfo, type SpawnRecordingContainerOptions, createRequestRecording, ensureRequestRecording, finishRequest, readInfraConfigFromEnv, redactBlobData, remoteCallbacks, spawnRecordingContainer, startRequest };
+export { type BlobData, type CapturedData, type ContainerInfraConfig, type CreateRecordingRequestHandlerOptions, type EnsureRecordingOptions, type EnvRead, type FinishRequestCallbacks, type FinishRequestOptions, type HandlerResponse$1 as HandlerResponse, type NetlifyEvent, type NetworkCall, type RecordingResult, type RequestContext, type RequestInfo, type SpawnRecordingContainerOptions, createRecordingRequestHandler, createRequestRecording, ensureRequestRecording, finishRequest, readInfraConfigFromEnv, redactBlobData, remoteCallbacks, spawnRecordingContainer, startRequest };

package/dist/index.js

@@ -426,6 +426,20 @@ async function finishRequest(requestContext, callbacks, response, options) {
   };
 }
 
+// src/createRecordingRequestHandler.ts
+function createRecordingRequestHandler(handler, options) {
+  return async (event, context) => {
+    const reqContext = startRequest(event);
+    try {
+      const response = await handler(event, context);
+      return await finishRequest(reqContext, options.callbacks, response, options);
+    } catch (err) {
+      reqContext.cleanup();
+      throw err;
+    }
+  };
+}
+
 // src/remoteCallbacks.ts
 function remoteCallbacks(serviceUrl) {
   const base = serviceUrl.replace(/\/+$/, "");
@@ -994,6 +1008,7 @@ async function createRequestRecording(blobUrlOrData, handlerPath, requestInfo) {
   return result;
 }
 export {
+  createRecordingRequestHandler,
   createRequestRecording,
   ensureRequestRecording,
   finishRequest,

package/package.json

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