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

package/README.md

@@ -22,7 +22,29 @@ There are two ways to use this package:
 
 The Netlify Recorder app (`https://netlify-recorder-bm4wmw.netlify.app`) provides a hosted service that stores captured request data, manages a pool of recording containers, and creates Replay recordings on demand. Your app needs zero database or infrastructure setup.
 
-### 1. Wrap your Netlify function
+### 1. Set required environment variables
+
+`finishRequest` needs to know which repository, branch, and commit your deployed code belongs to. Set these three environment variables on your Netlify site:
+
+| 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 |
+| `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` |
+
+**These are required.** `finishRequest` will throw an error if any are missing. Your deploy script should resolve them from git and set them on the Netlify site before deploying. Example:
+
+```typescript
+// In your deploy script:
+const commitSha = execSync("git rev-parse HEAD", { encoding: "utf-8" }).trim();
+const branchName = execSync("git rev-parse --abbrev-ref HEAD", { encoding: "utf-8" }).trim();
+const repositoryUrl = execSync("git remote get-url origin", { encoding: "utf-8" }).trim()
+  .replace(/\/\/[^@]+@/, "//"); // strip embedded credentials
+
+// Set these on your Netlify site via the Netlify API or CLI
+```
+
+### 2. Wrap your Netlify function
 
 Use `startRequest` / `finishRequest` with `remoteCallbacks()` to capture request data and send it to the service:
 
@@ -66,7 +88,7 @@ const handler: Handler = async (event) => {
 export { handler };
 ```
 
-That's it for capturing. The `remoteCallbacks(url)` helper sends the captured blob data 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.
+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.
 
 ### 2. Create recordings
 
@@ -119,7 +141,11 @@ const { status, recordingId } = await res.json();
 
 If you need full control, you can manage your own blob storage, database, and recording containers. This requires more setup but gives you complete ownership of the data pipeline.
 
-### 1. Wrap your Netlify function
+### 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.
+
+### 2. Wrap your Netlify function
 
 Use `startRequest` / `finishRequest` with custom callbacks that write to your own storage and database:
 
@@ -150,10 +176,10 @@ const handler: Handler = async (event) => {
           const { url } = await res.json();
           return url;
         },
-        storeRequestData: async ({ blobUrl, commitSha, branchName, handlerPath }) => {
+        storeRequestData: async ({ blobUrl, commitSha, branchName, repositoryUrl, handlerPath }) => {
           const [row] = await sql`
-            INSERT INTO requests (blob_url, commit_sha, branch_name, handler_path, status)
-            VALUES (${blobUrl}, ${commitSha}, ${branchName}, ${handlerPath}, 'captured')
+            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;
@@ -174,13 +200,15 @@ const handler: Handler = async (event) => {
 export { handler };
 ```
 
-### 2. Create a requests database table
+### 3. Create a requests database table
 
 ```sql
 CREATE TABLE IF NOT EXISTS requests (
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
   blob_url TEXT,
   commit_sha TEXT,
+  branch_name TEXT,
+  repository_url TEXT,
   handler_path TEXT,
   recording_id TEXT,
   status TEXT NOT NULL DEFAULT 'captured'
@@ -190,7 +218,7 @@ CREATE TABLE IF NOT EXISTS requests (
 );
 ```
 
-### 3. Create a background function to produce recordings
+### 4. Create a background function to produce recordings
 
 ```typescript
 import { ensureRequestRecording } from "@replayio-app-building/netlify-recorder";
@@ -234,7 +262,7 @@ const handler: Handler = async (event) => {
 export { handler };
 ```
 
-### 4. Create a container script
+### 5. Create a container script
 
 This script runs inside the recording container under `replay-node`:
 
@@ -288,11 +316,16 @@ 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.
+
 **Parameters:**
 - `requestContext` — The context returned by `startRequest`
 - `callbacks` — Either `remoteCallbacks(serviceUrl)` or custom `{ uploadBlob, storeRequestData }` callbacks
 - `response` — The handler's response object (`{ statusCode, headers?, body? }`)
 - `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
 
 ### `remoteCallbacks(serviceUrl): FinishRequestCallbacks`
 
@@ -323,12 +356,22 @@ Called inside a container running under `replay-node`. Downloads the captured da
 
 ## Environment Variables
 
-| Variable | Required | Description |
+### Required for all setups (read by `finishRequest`)
+
+These must be set on your Netlify site. Your deploy script should resolve them from git and push them to the Netlify environment before deploying. `finishRequest` will throw an error if any are missing.
+
+| Variable | Description | How to resolve |
 |---|---|---|
-| `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 self-hosted recording | Replay API key for uploading recordings |
-| `APP_REPOSITORY_URL` | For self-hosted recording | Git repository URL for container cloning |
+| `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) |
+
+### Required for self-hosted recording (Option B)
+
+| Variable | Description |
+|---|---|
+| `RECORD_REPLAY_API_KEY` | Replay API key for uploading recordings |
+| `APP_REPOSITORY_URL` | Git repository URL for container cloning |
 
 ## How It Works
 

package/dist/index.d.ts

@@ -46,6 +46,7 @@ interface FinishRequestCallbacks {
         blobUrl: string;
         commitSha: string;
         branchName: string;
+        repositoryUrl: string;
         handlerPath: string;
     }) => Promise<string>;
 }
@@ -109,6 +110,12 @@ interface HandlerResponse {
 }
 interface FinishRequestOptions {
     handlerPath?: string;
+    /** Override COMMIT_SHA env var. */
+    commitSha?: string;
+    /** Override BRANCH_NAME env var. */
+    branchName?: string;
+    /** Override REPOSITORY_URL env var. */
+    repositoryUrl?: string;
 }
 /**
  * Called at the end of the handler execution.
@@ -220,4 +227,4 @@ interface SpawnRecordingContainerOptions {
  */
 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, remoteCallbacks, spawnRecordingContainer, startRequest };
+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 };

package/dist/index.js

@@ -168,6 +168,7 @@ var ENV_ALLOW_LIST = /* @__PURE__ */ new Set([
   "LOGNAME",
   // Deploy metadata (non-secret identifiers)
   "COMMIT_SHA",
+  "BRANCH_NAME",
   // Common non-secret Netlify build vars
   "NETLIFY",
   "NETLIFY_DEV",
@@ -274,8 +275,21 @@ async function finishRequest(requestContext, callbacks, response, options) {
   if (globalThis.__REPLAY_RECORDING_MODE__ === true) {
     return response;
   }
-  const commitSha = process.env.COMMIT_SHA ?? "HEAD";
-  const branchName = process.env.BRANCH_NAME ?? "main";
+  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 missing = [];
+  if (!rawCommitSha) missing.push("COMMIT_SHA");
+  if (!rawBranchName) missing.push("BRANCH_NAME");
+  if (!rawRepositoryUrl) missing.push("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.`
+    );
+  }
+  const commitSha = rawCommitSha;
+  const branchName = rawBranchName;
+  const repositoryUrl = rawRepositoryUrl;
   const rawBlobData = {
     requestInfo: requestContext.requestInfo,
     capturedData: requestContext.capturedData,
@@ -290,6 +304,7 @@ async function finishRequest(requestContext, callbacks, response, options) {
     blobUrl,
     commitSha,
     branchName,
+    repositoryUrl,
     handlerPath: options?.handlerPath ?? "unknown"
   });
   return {
@@ -327,7 +342,8 @@ function remoteCallbacks(serviceUrl) {
             blobData,
             handlerPath: metadata.handlerPath,
             commitSha: metadata.commitSha,
-            branchName: metadata.branchName
+            branchName: metadata.branchName,
+            repositoryUrl: metadata.repositoryUrl
           })
         }
       );

package/package.json

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