@replayio-app-building/netlify-recorder 0.8.0 → 0.10.0

package/README.md

@@ -46,44 +46,69 @@ 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.
+
+**v1 handler** (Netlify Functions v1 — `event` with `httpMethod`, `path`, etc.):
 
 ```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.
+**v2 handler** (Netlify Functions v2 — Web API `Request`):
+
+```typescript
+import {
+  createRecordingRequestHandler,
+  remoteCallbacks,
+} from "@replayio-app-building/netlify-recorder";
+
+const RECORDER_URL = "https://netlify-recorder-bm4wmw.netlify.app";
+
+// The wrapper reads the body from a clone — you can still read req.json() etc.
+export default createRecordingRequestHandler(
+  async (req) => {
+    const body = await (req as Request).json();
+    const result = await myBusinessLogic(body);
+
+    return {
+      statusCode: 200,
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(result),
+    };
+  },
+  {
+    callbacks: remoteCallbacks(RECORDER_URL),
+    handlerPath: "netlify/functions/my-handler",
+  }
+);
+```
+
+`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.
+
+> **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.
 
 ### 2. Create recordings
 
@@ -142,50 +167,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,18 +308,40 @@ 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.
+
+Accepts either a **v1** `NetlifyEvent` (has `httpMethod`) or a **v2** Web API `Request` (has `method` + `url`). The version is detected automatically.
+
+For v2 Request inputs, the body is read from a **clone** — the original request body remains consumable by your handler.
 
 **Parameters:**
-- `event` — The Netlify handler event object (passed directly)
+- `event` — A v1 `NetlifyEvent` or v2 `Request` object (passed directly — no need to clone)
 
 **Returns:** A `RequestContext` object to pass to `finishRequest`.
 
 ### `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.
+
+**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.
 
 **Requires** the following environment variables (or equivalent options overrides): `COMMIT_SHA`, `BRANCH_NAME`, `REPLAY_REPOSITORY_URL`. Throws if any are missing.
 
@@ -362,6 +402,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

@@ -28,6 +28,27 @@ interface NetlifyEvent {
     rawQuery?: string;
     isBase64Encoded?: boolean;
 }
+/**
+ * Minimal interface for a Netlify Functions v2 Web API Request.
+ *
+ * This is a subset of the standard `Request` interface — only the properties
+ * that `startRequest` actually reads are required. Any spec-compliant
+ * `Request` object (including `new Request(...)`) satisfies this interface.
+ *
+ * `startRequest` reads the body from a **clone**, so the original request
+ * remains consumable by your handler. You do **not** need to clone the
+ * request before passing it in.
+ */
+interface NetlifyV2Request {
+    readonly method: string;
+    readonly url: string;
+    readonly headers: Headers | {
+        forEach(cb: (value: string, key: string) => void): void;
+    };
+    readonly body: ReadableStream<Uint8Array> | null;
+    clone(): NetlifyV2Request;
+    text(): Promise<string>;
+}
 interface RequestContext {
     requestInfo: RequestInfo;
     capturedData: CapturedData;
@@ -57,7 +78,7 @@ interface EnvRead {
     value: string | undefined;
     timestamp: number;
 }
-interface HandlerResponse {
+interface HandlerResponse$1 {
     statusCode: number;
     body?: string;
 }
@@ -69,7 +90,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. */
@@ -125,18 +146,46 @@ interface EnsureRecordingOptions {
 
 /**
  * Called at the beginning of a Netlify handler execution.
- * Accepts either a Netlify Functions v1 event (HandlerEvent with httpMethod,
- * path, etc.) or a v2 Web API Request.  Extracts all request metadata
- * internally, installs interceptors on globalThis.fetch and process.env to
- * capture outbound network calls and environment variable reads, and returns
- * a request context used by finishRequest.
  *
- * When running inside createRequestRecording (replay mode), the replay
+ * Accepts either a **Netlify Functions v1** event (`NetlifyEvent` — has
+ * `httpMethod`, `path`, etc.) or a **v2 Web API `Request`** object
+ * (`NetlifyV2Request`).  The version is detected automatically: v1 events
+ * have an `httpMethod` property while v2 Request objects have `method` +
+ * `url`.
+ *
+ * **v2 body handling:** For v2 Request inputs the body is read from a
+ * **clone** of the request, so the original `Request` body remains
+ * consumable by your handler. You do **not** need to call `req.clone()`
+ * before passing it in. The body text is resolved asynchronously and
+ * captured when `finishRequest` is called.
+ *
+ * Installs interceptors on `globalThis.fetch` and `process.env` to capture
+ * outbound network calls and environment variable reads, and returns a
+ * request context that must be passed to `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).
+ * capture interceptors to avoid overwriting the replay layer.
+ *
+ * @example
+ * ```typescript
+ * // v1 handler
+ * export async function handler(event: NetlifyEvent) {
+ *   const ctx = startRequest(event);
+ *   // ... your logic ...
+ *   return finishRequest(ctx, callbacks, response);
+ * }
+ *
+ * // v2 handler — no need to clone the request
+ * export default async function handler(req: Request) {
+ *   const ctx = startRequest(req);
+ *   const body = await req.json(); // still works — body was NOT consumed
+ *   // ... your logic ...
+ *   return finishRequest(ctx, callbacks, response);
+ * }
+ * ```
  */
-declare function startRequest(event: NetlifyEvent | /* v2 Request */ Record<string, unknown>): RequestContext;
+declare function startRequest(event: NetlifyEvent | NetlifyV2Request): RequestContext;
 
 interface FullHandlerResponse {
     statusCode: number;
@@ -157,9 +206,85 @@ interface FinishRequestOptions {
  * 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.
+ *
+ * **Important:** The returned response includes the `X-Replay-Request-Id`
+ * header. You must send the returned response to the client — not the
+ * original response object you passed in.
+ *
+ * Logs a warning to `console.warn` when the total finishRequest time or
+ * individual callback steps exceed their thresholds, to help diagnose
+ * slow blob uploads or database writes.
  */
 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.
+ *
+ * **Important:** You must use the response returned by the wrapped handler
+ * (not your original response object), because it includes the
+ * `X-Replay-Request-Id` header set by `finishRequest`.
+ *
+ * For v2 handlers the request body is read from a clone internally — your
+ * handler still receives the original request with an unconsumed body.
+ *
+ * @example v1 handler (NetlifyEvent)
+ * ```typescript
+ * import { createRecordingRequestHandler, remoteCallbacks } from "@replayio-app-building/netlify-recorder";
+ *
+ * const handler = createRecordingRequestHandler(
+ *   async (event) => {
+ *     const result = await myBusinessLogic(event.body);
+ *     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 };
+ * ```
+ *
+ * @example v2 handler (Web API Request)
+ * ```typescript
+ * import { createRecordingRequestHandler, remoteCallbacks } from "@replayio-app-building/netlify-recorder";
+ *
+ * export default createRecordingRequestHandler(
+ *   async (req) => {
+ *     // Body is still available — startRequest reads from a clone
+ *     const body = await (req as Request).json();
+ *     const result = await myBusinessLogic(body);
+ *     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",
+ *   }
+ * );
+ * ```
+ */
+declare function createRecordingRequestHandler(handler: (event: NetlifyEvent | NetlifyV2Request, context?: unknown) => Promise<HandlerResponse>, options: CreateRecordingRequestHandlerOptions): (event: NetlifyEvent | NetlifyV2Request, 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 +347,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 +401,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 NetlifyV2Request, type NetworkCall, type RecordingResult, type RequestContext, type RequestInfo, type SpawnRecordingContainerOptions, createRecordingRequestHandler, createRequestRecording, ensureRequestRecording, finishRequest, readInfraConfigFromEnv, redactBlobData, remoteCallbacks, spawnRecordingContainer, startRequest };

package/dist/index.js

@@ -367,7 +367,10 @@ function redactBlobData(blobData) {
 }
 
 // src/finishRequest.ts
+var SLOW_THRESHOLD_MS = 2e3;
+var SLOW_STEP_THRESHOLD_MS = 1e3;
 async function finishRequest(requestContext, callbacks, response, options) {
+  const finishStart = Date.now();
   requestContext.cleanup();
   if (globalThis.__REPLAY_RECORDING_MODE__ === true) {
     return response;
@@ -387,6 +390,7 @@ async function finishRequest(requestContext, callbacks, response, options) {
   const commitSha = rawCommitSha;
   const branchName = rawBranchName;
   const repositoryUrl = rawRepositoryUrl;
+  const handlerPath = options?.handlerPath ?? "unknown";
   if (requestContext._v2BodyPromise && !requestContext.requestInfo.body) {
     try {
       const bodyText = await requestContext._v2BodyPromise;
@@ -409,14 +413,34 @@ async function finishRequest(requestContext, callbacks, response, options) {
   };
   const blobData = redactBlobData(rawBlobData);
   const blobContent = JSON.stringify(blobData);
+  const uploadStart = Date.now();
   const blobUrl = await callbacks.uploadBlob(blobContent);
+  const uploadDuration = Date.now() - uploadStart;
+  if (uploadDuration > SLOW_STEP_THRESHOLD_MS) {
+    console.warn(
+      `netlify-recorder: uploadBlob took ${uploadDuration}ms (handler: ${handlerPath})`
+    );
+  }
+  const storeStart = Date.now();
   const storedRequestId = await callbacks.storeRequestData({
     blobUrl,
     commitSha,
     branchName,
     repositoryUrl,
-    handlerPath: options?.handlerPath ?? "unknown"
+    handlerPath
   });
+  const storeDuration = Date.now() - storeStart;
+  if (storeDuration > SLOW_STEP_THRESHOLD_MS) {
+    console.warn(
+      `netlify-recorder: storeRequestData took ${storeDuration}ms (handler: ${handlerPath})`
+    );
+  }
+  const totalDuration = Date.now() - finishStart;
+  if (totalDuration > SLOW_THRESHOLD_MS) {
+    console.warn(
+      `netlify-recorder: finishRequest took ${totalDuration}ms total (upload: ${uploadDuration}ms, store: ${storeDuration}ms, handler: ${handlerPath})`
+    );
+  }
   return {
     ...response,
     headers: {
@@ -426,6 +450,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 +1032,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.8.0",
+  "version": "0.10.0",
   "description": "Capture and replay Netlify function executions as Replay recordings",
   "type": "module",
   "exports": {