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

package/README.md

@@ -46,7 +46,9 @@ const repositoryUrl = execSync("git remote get-url origin", { encoding: "utf-8"
 
 ### 2. Wrap your Netlify function
 
-Use `createRecordingRequestHandler` with `remoteCallbacks()` to wrap your handler with automatic request capture:
+Use `createRecordingRequestHandler` with `remoteCallbacks()` to wrap your handler with automatic request capture.
+
+**v1 handler** (Netlify Functions v1 — `event` with `httpMethod`, `path`, etc.):
 
 ```typescript
 import {
@@ -75,8 +77,39 @@ const handler = createRecordingRequestHandler(
 export { handler };
 ```
 
+**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
 
 When you want to turn a captured request into a Replay recording, POST to the service's `create-recording` endpoint with the request ID:
@@ -293,8 +326,12 @@ Wraps a Netlify handler function with automatic request recording. This is the r
 
 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`.
 
@@ -302,6 +339,10 @@ Lower-level API. Begins capturing a Netlify handler execution. Patches `globalTh
 
 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.
 
 **Parameters:**

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;
@@ -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,6 +206,14 @@ 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>;
 
@@ -175,13 +232,20 @@ interface CreateRecordingRequestHandlerOptions extends FinishRequestOptions {
  * after, capturing all outbound network calls and environment variable reads.
  * On error, interceptors are cleaned up and the error is re-thrown.
  *
- * @example
+ * **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();
+ *     const result = await myBusinessLogic(event.body);
  *     return {
  *       statusCode: 200,
  *       headers: { "Content-Type": "application/json" },
@@ -196,8 +260,30 @@ interface CreateRecordingRequestHandlerOptions extends FinishRequestOptions {
  *
  * 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 | Record<string, unknown>, context?: unknown) => Promise<HandlerResponse>, options: CreateRecordingRequestHandlerOptions): (event: NetlifyEvent | Record<string, unknown>, context?: unknown) => Promise<HandlerResponse>;
+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
@@ -315,4 +401,4 @@ interface SpawnRecordingContainerOptions {
  */
 declare function spawnRecordingContainer(options: SpawnRecordingContainerOptions): Promise<string>;
 
-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 };
+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: {

package/package.json

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