@replayio-app-building/netlify-recorder 0.2.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, 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
 
@@ -74,40 +96,21 @@ When you want to turn a captured request into a Replay recording, POST to the se
 
 ```typescript
 const response = await fetch(
-  `${RECORDER_URL}/.netlify/functions/create-recording`,
-  {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ requestId }),
-  }
-);
-```
-
-The service looks up the stored blob data, dispatches the work to a pool container, and creates the recording. You can check the recording status via the service's Requests page, or provide a webhook to be notified on completion.
-
-### 3. (Optional) Get notified when recordings complete
-
-If you want to be notified when a recording finishes, call the blob endpoint directly with a `webhookUrl`:
-
-```typescript
-await fetch(
-  `${RECORDER_URL}/.netlify/functions/create-recording-from-blob-background`,
+  `${RECORDER_URL}/api/create-recording`,
   {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({
-      blobUrl: "https://...",         // blob URL from the service
-      handlerPath: "netlify/functions/my-handler",
-      commitSha: "a1b2c3d4...",
-      branchName: "main",
-      repositoryUrl: "https://github.com/your-org/your-repo",
-      webhookUrl: "https://your-app.netlify.app/.netlify/functions/on-recording-complete",
+      requestId,
+      webhookUrl: "https://your-app.netlify.app/api/on-recording-complete", // optional
     }),
   }
 );
 ```
 
-**Webhook payload (POSTed to `webhookUrl`):**
+The service looks up the stored blob data, dispatches the work to a pool container, and creates the recording.
+
+If `webhookUrl` is provided, the service will POST the result to that URL when the recording completes (or fails):
 
 On success:
 ```json
@@ -119,13 +122,30 @@ On failure:
 { "status": "failed", "error": "Error message" }
 ```
 
+### 3. Check recording status
+
+You can poll the recording status at any time:
+
+```typescript
+const res = await fetch(
+  `${RECORDER_URL}/api/get-request?requestId=${requestId}`
+);
+const { status, recordingId } = await res.json();
+// status: "captured" | "processing" | "recorded" | "failed"
+// recordingId: string | null
+```
+
 ---
 
 ## Option B: Self-Hosted
 
 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:
 
@@ -156,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;
@@ -180,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'
@@ -196,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";
@@ -240,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`:
 
@@ -294,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`
 
@@ -329,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.
@@ -124,8 +131,8 @@ declare function finishRequest(requestContext: RequestContext, callbacks: Finish
  * to set up its own blob storage or database tables.
  *
  * The callbacks upload blob data and store request metadata via the
- * service's `store-request` endpoint, which handles UploadThing storage
- * and database insertion.
+ * service's `/api/store-request` endpoint, which handles UploadThing
+ * storage and database insertion.
  *
  * @param serviceUrl - Base URL of the Netlify Recorder service
  *   (e.g. "https://netlify-recorder-bm4wmw.netlify.app")
@@ -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 {
@@ -319,7 +334,7 @@ function remoteCallbacks(serviceUrl) {
         );
       }
       const res = await fetch(
-        `${base}/.netlify/functions/store-request`,
+        `${base}/api/store-request`,
         {
           method: "POST",
           headers: { "Content-Type": "application/json" },
@@ -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.2.0",
+  "version": "0.4.0",
   "description": "Capture and replay Netlify function executions as Replay recordings",
   "type": "module",
   "exports": {