@replayio-app-building/netlify-recorder 0.15.4 → 0.15.6

package/README.md

@@ -31,8 +31,9 @@ The Netlify Recorder app (`https://netlify-recorder-bm4wmw.netlify.app`) provide
 | `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` |
+| `NETLIFY_RECORDER_SECRET` | Secret string for access control — restricts who can view and act on your captured requests | Set in Netlify site environment variables or via `set-branch-secret` |
 
-**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:
+The first three are **required** — `finishRequest` will throw an error if any are missing. `NETLIFY_RECORDER_SECRET` is strongly recommended to prevent other apps from accessing your captured request data. Your deploy script should resolve the git values and set them on the Netlify site before deploying. Example:
 
 ```typescript
 // In your deploy script:
@@ -46,7 +47,7 @@ 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. Set `secret` to restrict access to captured requests — only API calls providing the same secret can view or act on them.
 
 **v1 handler** (Netlify Functions v1 — `event` with `httpMethod`, `path`, etc.):
 
@@ -71,6 +72,7 @@ const handler = createRecordingRequestHandler(
   {
     callbacks: remoteCallbacks(RECORDER_URL),
     handlerPath: "netlify/functions/my-handler",
+    secret: process.env.NETLIFY_RECORDER_SECRET,
   }
 );
 
@@ -102,6 +104,7 @@ export default createRecordingRequestHandler(
   {
     callbacks: remoteCallbacks(RECORDER_URL),
     handlerPath: "netlify/functions/my-handler",
+    secret: process.env.NETLIFY_RECORDER_SECRET,
   }
 );
 ```
@@ -112,7 +115,7 @@ export default createRecordingRequestHandler(
 
 ### 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:
+When you want to turn a captured request into a Replay recording, POST to the service's `create-recording` endpoint with the request ID. If the request was created with a secret, you must include it:
 
 ```typescript
 const response = await fetch(
@@ -122,6 +125,7 @@ const response = await fetch(
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({
       requestId,
+      secret,
       webhookUrl: "https://your-app.netlify.app/api/on-recording-complete", // optional
     }),
   }
@@ -144,17 +148,19 @@ On failure:
 
 ### 3. Check recording status
 
-You can poll the recording status at any time:
+You can poll the recording status at any time. If the request was created with a secret, you must include it:
 
 ```typescript
 const res = await fetch(
-  `${RECORDER_URL}/api/get-request?requestId=${requestId}`
+  `${RECORDER_URL}/api/get-request?requestId=${requestId}&secret=${secret}`
 );
 const { status, recordingId } = await res.json();
 // status: "captured" | "processing" | "recorded" | "failed"
 // recordingId: string | null
 ```
 
+Requests created with a secret return 403 if the secret is missing or incorrect.
+
 ### 4. Access control with secrets
 
 You can restrict access to captured requests by setting a `secret` string. When a secret is set, the request is only accessible via API calls that provide the same secret value. This lets each app isolate its requests from other apps sharing the same Netlify Recorder service.
@@ -179,11 +185,11 @@ export default createRecordingRequestHandler(
 
 #### Listing requests by secret
 
-Use the `list-by-secret` endpoint to retrieve all requests associated with a secret, with optional filtering by status, handler path, and time range:
+Use the `requests` endpoint with a `secret` parameter to retrieve all requests associated with your secret, with optional filtering by status, handler path, and time range:
 
 ```typescript
 const res = await fetch(
-  `${RECORDER_URL}/api/list-by-secret?secret=${secret}&status=recorded&handlerPath=netlify/functions/my-handler&after=2025-01-01T00:00:00Z&before=2025-12-31T23:59:59Z`
+  `${RECORDER_URL}/api/requests?secret=${secret}&status=recorded&handlerPath=netlify/functions/my-handler&after=2025-01-01T00:00:00Z&before=2025-12-31T23:59:59Z`
 );
 const { rows, total, page, limit } = await res.json();
 ```
@@ -193,13 +199,16 @@ Query parameters:
 | Parameter | Description |
 |---|---|
 | `secret` | **(required)** The secret string used when creating the requests |
-| `status` | Filter by status: `captured`, `queued`, `processing`, `recorded`, `failed` |
+| `id` | Search by request ID prefix |
+| `status` | Filter by status: `captured`, `queued`, `processing`, `recorded`, `failed`, `all` |
 | `handlerPath` | Filter by handler path (exact match) |
 | `after` | Only include requests created at or after this ISO timestamp |
 | `before` | Only include requests created at or before this ISO timestamp |
 | `page` | Page number (default 1) |
 | `limit` | Page size (default 20, max 100) |
 
+Without a `secret` parameter, only requests created without a secret are returned.
+
 #### Checking request status with a secret
 
 When a request was created with a secret, you must include the secret when polling its status:
@@ -256,6 +265,7 @@ const handler = createRecordingRequestHandler(
     };
   },
   {
+    secret: process.env.NETLIFY_RECORDER_SECRET,
     callbacks: {
       uploadBlob: async (data) => {
         // Upload the JSON string to your blob storage (S3, R2, etc.)
@@ -266,10 +276,10 @@ const handler = createRecordingRequestHandler(
         const { url } = await res.json();
         return url;
       },
-      storeRequestData: async ({ blobUrl, commitSha, branchName, repositoryUrl, handlerPath }) => {
+      storeRequestData: async ({ blobUrl, commitSha, branchName, repositoryUrl, handlerPath, secret }) => {
         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')
+          INSERT INTO requests (blob_url, commit_sha, branch_name, repository_url, handler_path, secret, status)
+          VALUES (${blobUrl}, ${commitSha}, ${branchName}, ${repositoryUrl}, ${handlerPath}, ${secret}, 'captured')
           RETURNING id
         `;
         return row.id;
@@ -291,12 +301,15 @@ CREATE TABLE IF NOT EXISTS requests (
   branch_name TEXT,
   repository_url TEXT,
   handler_path TEXT,
+  secret TEXT,
   recording_id TEXT,
   status TEXT NOT NULL DEFAULT 'captured'
     CHECK (status IN ('captured', 'processing', 'recorded', 'failed')),
   created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
   updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
+
+CREATE INDEX IF NOT EXISTS idx_requests_secret ON requests (secret) WHERE secret IS NOT NULL;
 ```
 
 ### 4. Create a background function to produce recordings
@@ -428,6 +441,7 @@ export default createRecordingRequestHandler(
   {
     callbacks: remoteCallbacks(RECORDER_URL),
     handlerPath: "netlify/functions/create-order",
+    secret: process.env.NETLIFY_RECORDER_SECRET,
   }
 );
 ```
@@ -589,6 +603,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` |
 | `REPLAY_REPOSITORY_URL` | Git repository URL (no embedded credentials) | `git remote get-url origin` (strip tokens) |
+| `NETLIFY_RECORDER_SECRET` | Secret for access control (strongly recommended) | `openssl rand -base64 32` — store in Netlify site env vars |
 
 ### Required for self-hosted recording (Option B)
 

package/package.json

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