@replayio-app-building/netlify-recorder 0.4.0 → 0.6.0

package/README.md

@@ -28,7 +28,7 @@ The Netlify Recorder app (`https://netlify-recorder-bm4wmw.netlify.app`) provide
 
 | Variable | Description | How to set |
 |---|---|---|
-| `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 |
+| `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` |
 
@@ -59,12 +59,7 @@ import type { Handler } from "@netlify/functions";
 const RECORDER_URL = "https://netlify-recorder-bm4wmw.netlify.app";
 
 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,
-  });
+  const reqContext = startRequest(event);
 
   try {
     const result = await myBusinessLogic();
@@ -143,7 +138,7 @@ If you need full control, you can manage your own blob storage, database, and re
 
 ### 1. Set required environment variables
 
-Same as Option A — you must set `REPOSITORY_URL`, `COMMIT_SHA`, and `BRANCH_NAME` on your Netlify site. See the table in Option A, Step 1 above.
+Same as Option A — you must set `REPLAY_REPOSITORY_URL`, `COMMIT_SHA`, and `BRANCH_NAME` on your Netlify site. See the table in Option A, Step 1 above.
 
 ### 2. Wrap your Netlify function
 
@@ -154,12 +149,7 @@ import { startRequest, finishRequest } from "@replayio-app-building/netlify-reco
 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,
-  });
+  const reqContext = startRequest(event);
 
   try {
     const result = await myBusinessLogic();
@@ -300,15 +290,12 @@ Self-hosted recording requires these environment variables:
 
 ## API Reference
 
-### `startRequest(requestInfo): RequestContext`
+### `startRequest(event): RequestContext`
 
-Begins capturing a Netlify handler execution. Patches `globalThis.fetch` and `process.env` to record all outbound network calls and environment variable reads.
+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.
 
 **Parameters:**
-- `requestInfo.method` — HTTP method of the incoming request
-- `requestInfo.url` — Request URL/path
-- `requestInfo.headers` — Request headers
-- `requestInfo.body` — Optional request body
+- `event` — The Netlify handler event object (passed directly)
 
 **Returns:** A `RequestContext` object to pass to `finishRequest`.
 
@@ -316,7 +303,7 @@ Begins capturing a Netlify handler execution. Patches `globalThis.fetch` and `pr
 
 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`, `REPOSITORY_URL`. Throws if any are missing.
+**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`
@@ -325,7 +312,7 @@ Finalizes the request capture. Restores original `fetch` and `process.env`, seri
 - `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 `REPOSITORY_URL` env var
+- `options.repositoryUrl` — Override `REPLAY_REPOSITORY_URL` env var
 
 ### `remoteCallbacks(serviceUrl): FinishRequestCallbacks`
 
@@ -364,7 +351,7 @@ 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` |
-| `REPOSITORY_URL` | Git repository URL (no embedded credentials) | `git remote get-url origin` (strip tokens) |
+| `REPLAY_REPOSITORY_URL` | Git repository URL (no embedded credentials) | `git remote get-url origin` (strip tokens) |
 
 ### Required for self-hosted recording (Option B)
 

package/dist/index.d.ts

@@ -1,8 +1,32 @@
+/**
+ * Normalized request metadata stored in the blob.
+ * Populated internally by startRequest from the Netlify event.
+ */
 interface RequestInfo {
     method: string;
     url: string;
     headers: Record<string, string>;
     body?: string;
+    queryStringParameters?: Record<string, string | undefined> | null;
+    multiValueQueryStringParameters?: Record<string, string[] | undefined> | null;
+    rawUrl?: string;
+    rawQuery?: string;
+    isBase64Encoded?: boolean;
+}
+/**
+ * Input type for startRequest. Mirrors the Netlify HandlerEvent shape so
+ * handlers can simply pass the event object directly.
+ */
+interface NetlifyEvent {
+    httpMethod: string;
+    path: string;
+    headers: Record<string, string | undefined>;
+    body?: string | null;
+    queryStringParameters?: Record<string, string | undefined> | null;
+    multiValueQueryStringParameters?: Record<string, string[] | undefined> | null;
+    rawUrl?: string;
+    rawQuery?: string;
+    isBase64Encoded?: boolean;
 }
 interface RequestContext {
     requestInfo: RequestInfo;
@@ -92,6 +116,7 @@ interface EnsureRecordingOptions {
 
 /**
  * Called at the beginning of a Netlify handler execution.
+ * Accepts the raw Netlify event and extracts all request metadata internally.
  * 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.
@@ -101,7 +126,7 @@ interface EnsureRecordingOptions {
  * 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;
+declare function startRequest(event: NetlifyEvent): RequestContext;
 
 interface HandlerResponse {
     statusCode: number;
@@ -114,7 +139,7 @@ interface FinishRequestOptions {
     commitSha?: string;
     /** Override BRANCH_NAME env var. */
     branchName?: string;
-    /** Override REPOSITORY_URL env var. */
+    /** Override REPLAY_REPOSITORY_URL env var. */
     repositoryUrl?: string;
 }
 /**
@@ -227,4 +252,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 NetworkCall, type RequestContext, type RequestInfo, type SpawnRecordingContainerOptions, createRequestRecording, ensureRequestRecording, finishRequest, readInfraConfigFromEnv, redactBlobData, remoteCallbacks, spawnRecordingContainer, startRequest };
+export { type BlobData, type CapturedData, type ContainerInfraConfig, type EnsureRecordingOptions, type EnvRead, type FinishRequestCallbacks, type FinishRequestOptions, type NetlifyEvent, type NetworkCall, type RequestContext, type RequestInfo, type SpawnRecordingContainerOptions, createRequestRecording, ensureRequestRecording, finishRequest, readInfraConfigFromEnv, redactBlobData, remoteCallbacks, spawnRecordingContainer, startRequest };

package/dist/index.js

@@ -8,6 +8,7 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 // src/interceptors/network.ts
 function installNetworkInterceptor(mode, calls) {
   const originalFetch = globalThis.fetch;
+  let replayCallIndex = 0;
   if (mode === "capture") {
     const captureFetch = async (input, init) => {
       const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
@@ -39,14 +40,17 @@ function installNetworkInterceptor(mode, calls) {
     };
     globalThis.fetch = captureFetch;
   } else {
-    let callIndex = 0;
     const replayFetch = async () => {
-      const call = calls[callIndex++];
+      const idx = replayCallIndex++;
+      const call = calls[idx];
       if (!call) {
         throw new Error(
           `No more recorded network calls to replay (exhausted ${calls.length} calls)`
         );
       }
+      console.log(
+        `  [network-replay] Consumed call ${idx + 1}/${calls.length}: ${call.method} ${call.url} => ${call.responseStatus}`
+      );
       const body = call.responseBody ?? "";
       const status = call.responseStatus;
       return {
@@ -82,6 +86,12 @@ function installNetworkInterceptor(mode, calls) {
   return {
     restore() {
       globalThis.fetch = originalFetch;
+    },
+    consumedCount() {
+      return replayCallIndex;
+    },
+    totalCount() {
+      return calls.length;
     }
   };
 }
@@ -121,7 +131,24 @@ function installEnvironmentInterceptor(mode, reads) {
 }
 
 // src/startRequest.ts
-function startRequest(requestInfo) {
+function startRequest(event) {
+  const headers = {};
+  for (const [key, value] of Object.entries(event.headers)) {
+    if (value !== void 0) {
+      headers[key] = value;
+    }
+  }
+  const requestInfo = {
+    method: event.httpMethod,
+    url: event.path,
+    headers,
+    body: event.body ?? void 0,
+    queryStringParameters: event.queryStringParameters ?? null,
+    multiValueQueryStringParameters: event.multiValueQueryStringParameters ?? null,
+    rawUrl: event.rawUrl,
+    rawQuery: event.rawQuery,
+    isBase64Encoded: event.isBase64Encoded
+  };
   const capturedData = { networkCalls: [], envReads: [] };
   const isReplay = globalThis.__REPLAY_RECORDING_MODE__ === true;
   let cleanup;
@@ -180,6 +207,7 @@ var ENV_ALLOW_LIST = /* @__PURE__ */ new Set([
   "DEPLOY_ID",
   "DEPLOY_URL",
   "REPOSITORY_URL",
+  "REPLAY_REPOSITORY_URL",
   "APP_REPOSITORY_URL",
   "BRANCH",
   "HEAD",
@@ -277,11 +305,11 @@ async function finishRequest(requestContext, callbacks, response, options) {
   }
   const rawCommitSha = options?.commitSha ?? process.env.COMMIT_SHA;
   const rawBranchName = options?.branchName ?? process.env.BRANCH_NAME;
-  const rawRepositoryUrl = options?.repositoryUrl ?? process.env.REPOSITORY_URL;
+  const rawRepositoryUrl = options?.repositoryUrl ?? process.env.REPLAY_REPOSITORY_URL;
   const missing = [];
   if (!rawCommitSha) missing.push("COMMIT_SHA");
   if (!rawBranchName) missing.push("BRANCH_NAME");
-  if (!rawRepositoryUrl) missing.push("REPOSITORY_URL");
+  if (!rawRepositoryUrl) missing.push("REPLAY_REPOSITORY_URL");
   if (missing.length > 0) {
     throw new Error(
       `netlify-recorder: missing required configuration: ${missing.join(", ")}. Set these as environment variables on your Netlify site, or pass them via the options parameter. See the package README for setup instructions.`
@@ -653,9 +681,31 @@ async function createRequestRecording(blobUrlOrData, handlerPath, requestInfo) {
       httpMethod: requestInfo.method,
       path: requestInfo.url,
       headers: requestInfo.headers,
-      body: requestInfo.body ?? null
+      body: requestInfo.body ?? null,
+      queryStringParameters: requestInfo.queryStringParameters ?? null,
+      multiValueQueryStringParameters: requestInfo.multiValueQueryStringParameters ?? null,
+      rawUrl: requestInfo.rawUrl ?? requestInfo.url,
+      rawQuery: requestInfo.rawQuery ?? "",
+      isBase64Encoded: requestInfo.isBase64Encoded ?? false
     });
   } finally {
+    const consumed = networkHandle.consumedCount();
+    const total = networkHandle.totalCount();
+    if (consumed < total) {
+      console.error(
+        `ERROR: Not all recorded network calls were consumed during replay. Consumed ${consumed} of ${total} calls. ${total - consumed} call(s) were never replayed.`
+      );
+      for (let i = consumed; i < total; i++) {
+        const call = blobData.capturedData.networkCalls[i];
+        if (call) {
+          console.error(
+            `  Unconsumed call ${i + 1}/${total}: ${call.method} ${call.url} => ${call.responseStatus}`
+          );
+        }
+      }
+    } else {
+      console.log(`  [network-replay] All ${total} recorded network call(s) were consumed.`);
+    }
     globalThis.__REPLAY_RECORDING_MODE__ = false;
     networkHandle.restore();
     envHandle.restore();

package/package.json

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