@replayio-app-building/netlify-recorder 0.18.0 → 0.20.0

package/README.md

@@ -114,47 +114,40 @@ export default createRecordingRequestHandler(
 
 ### 4. Create recordings via the Netlify Recorder service
 
-When you want to turn a captured request into a Replay recording, POST to the Netlify Recorder service's `create-recording` endpoint. You need to provide a `blobDataUrl` — a publicly accessible URL where the recording container can fetch the captured blob data.
-
-If your app exposes the blob data via an endpoint (e.g. using `backendRequestsGetBlobData`), construct the URL and pass it:
+Use `ensureRequestRecording` to turn a captured request into a Replay recording. It checks the `backend_requests` table first — if a recording already exists, it returns the recording ID immediately without calling the service. Otherwise it dispatches the work to the Netlify Recorder service and updates the row status to `"queued"`.
 
 ```typescript
+import { ensureRequestRecording } from "@replayio-app-building/netlify-recorder";
+
 const RECORDER_URL = "https://netlify-recorder-bm4wmw.netlify.app";
-const blobDataUrl = `https://your-app.netlify.app/api/get-backend-request-blob?requestId=${requestId}`;
 
-const response = await fetch(
-  `${RECORDER_URL}/api/create-recording`,
-  {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      blobDataUrl,
-      handlerPath: "netlify/functions/my-handler",
-      commitSha: "abc123",
-      branchName: "main",
-      repositoryUrl: "https://github.com/org/repo.git", // optional
-      webhookUrl: "https://your-app.netlify.app/api/on-recording-complete", // optional
-    }),
-  }
-);
+const recordingId = await ensureRequestRecording(sql, requestId, {
+  recorderUrl: RECORDER_URL,
+});
 
-const { requestId: serviceRequestId } = await response.json();
+if (recordingId) {
+  console.log(`Recording already exists: ${recordingId}`);
+} else {
+  console.log("Recording queued — check back later or use a webhook");
+}
 ```
 
-The `create-recording` endpoint accepts:
+The function is idempotent — calling it multiple times for the same request is safe:
+- **`status: "recorded"`** — returns the `recording_id` immediately
+- **`status: "queued"` or `"processing"`** — returns `null` without re-queuing
+- **`status: "captured"` or `"failed"`** — calls the service, updates status to `"queued"`, returns `null`
 
-| Parameter | Required | Description |
-|---|---|---|
-| `blobDataUrl` | Yes | URL where the recording container can fetch the captured blob JSON |
-| `handlerPath` | Yes | Path to the handler file (e.g. `netlify/functions/my-handler`) |
-| `commitSha` | Yes | Git commit SHA of the deployed code |
-| `branchName` | Yes | Git branch of the deployed code |
-| `repositoryUrl` | No | Git repository URL for the container to clone |
-| `webhookUrl` | No | URL to POST the result to when the recording completes or fails |
+By default, the blob data URL points to `${recorderUrl}/api/get-backend-request-blob?requestId=${requestId}`. If your app serves blob data from a different endpoint, pass a custom `blobDataUrl`:
 
-The service dispatches the work to a recording container, which fetches the blob data from `blobDataUrl`, replays the handler execution under `replay-node`, and produces a Replay recording.
+```typescript
+const recordingId = await ensureRequestRecording(sql, requestId, {
+  recorderUrl: RECORDER_URL,
+  blobDataUrl: `https://your-app.netlify.app/api/get-blob?id=${requestId}`,
+  webhookUrl: "https://your-app.netlify.app/api/on-recording-complete", // optional
+});
+```
 
-If `webhookUrl` is provided, the service will POST the result to that URL when the recording completes (or fails):
+When `webhookUrl` is provided, the service POSTs the result when the recording completes:
 
 On success:
 ```json
@@ -410,6 +403,21 @@ Updates the status of a request. Optionally sets `recording_id` (on success) or
 - `recordingId` — Replay recording ID (optional, for `"recorded"` status)
 - `errorMessage` — Error details (optional, for `"failed"` status)
 
+### `ensureRequestRecording(sql, requestId, options): Promise<string | null>`
+
+Ensures a Replay recording exists (or is being created) for a backend request. Looks up the request in `backend_requests`, returns the `recording_id` if already recorded, or calls the Netlify Recorder service to queue a recording. Idempotent — safe to call multiple times for the same request.
+
+**Parameters:**
+- `sql` — A Neon SQL tagged-template function
+- `requestId` — The backend request UUID
+- `options.recorderUrl` — Base URL of the Netlify Recorder service
+- `options.blobDataUrl` — Override the URL where the recording container fetches the blob JSON (defaults to `${recorderUrl}/api/get-backend-request-blob?requestId=${requestId}`)
+- `options.webhookUrl` — URL to POST the result to when the recording completes or fails
+
+**Returns:** The recording ID (`string`) if the request is already recorded, or `null` if the recording was queued or is in progress.
+
+**Throws:** If the request ID is not found in `backend_requests`, or if the service call fails.
+
 ### `createRequestRecording(blobUrlOrData, handlerPath, requestInfo): Promise<RecordingResult>`
 
 Called inside a recording container running under `replay-node`. Downloads the captured data blob (or accepts pre-parsed `BlobData`), installs replay-mode interceptors that return pre-recorded responses instead of making real calls, and executes the original handler so `replay-node` can record the execution.
@@ -456,13 +464,14 @@ Creates the `audit_log` table, its indexes, and a reusable PL/pgSQL trigger func
 **Parameters:**
 - `sql` — A Neon SQL tagged-template function
 
-### `databaseAuditMonitorTable(sql, tableName): Promise<void>`
+### `databaseAuditMonitorTable(sql, tableName, primaryKeyColumn?): Promise<void>`
 
 Attaches a trigger to the specified table that logs INSERT, UPDATE, and DELETE operations to the `audit_log` table. Throws if `tableName` is `'audit_log'`.
 
 **Parameters:**
 - `sql` — A Neon SQL tagged-template function
 - `tableName` — Name of the table to monitor (must match `^[a-zA-Z_][a-zA-Z0-9_]*$`)
+- `primaryKeyColumn` — Name of the primary key column (default: `"id"`, must match `^[a-zA-Z_][a-zA-Z0-9_]*$`)
 
 ### `databaseAuditDumpLogTable(sql): Promise<Record<string, unknown>[]>`
 

package/dist/index.d.ts

@@ -292,6 +292,30 @@ declare function backendRequestsUpdateStatus(sql: SqlFunction$1, id: string, sta
  * captured request data directly in the `backend_requests` table.
  */
 declare function databaseCallbacks(sql: SqlFunction$1): FinishRequestCallbacks;
+interface EnsureRequestRecordingOptions {
+    /** Base URL of the Netlify Recorder service (e.g. "https://netlify-recorder-bm4wmw.netlify.app"). */
+    recorderUrl: string;
+    /**
+     * Full URL where the recording container can fetch the blob JSON for this request.
+     * Defaults to `${recorderUrl}/api/get-backend-request-blob?requestId=${requestId}`.
+     */
+    blobDataUrl?: string;
+    /** URL to POST the result to when the recording completes or fails. */
+    webhookUrl?: string;
+}
+/**
+ * Ensures a Replay recording exists (or is being created) for a backend request.
+ *
+ * 1. Looks up the request in `backend_requests`.
+ * 2. If a recording already exists (`status === "recorded"`), returns the recording ID immediately.
+ * 3. If the request is already queued or processing, returns `null` without re-queuing.
+ * 4. Otherwise, calls the Netlify Recorder service's `create-recording` endpoint,
+ *    updates the row to `"queued"`, and returns `null`.
+ *
+ * This function is idempotent — calling it multiple times for the same request
+ * is safe. Once the recording completes, subsequent calls return the recording ID.
+ */
+declare function ensureRequestRecording(sql: SqlFunction$1, requestId: string, options: EnsureRequestRecordingOptions): Promise<string | null>;
 
 type SqlFunction = (...args: any[]) => Promise<any[]>;
 /**
@@ -308,7 +332,7 @@ declare function databaseAuditEnsureLogTable(sql: SqlFunction): Promise<void>;
  *
  * Throws if `tableName` is `'audit_log'` (cannot monitor itself).
  */
-declare function databaseAuditMonitorTable(sql: SqlFunction, tableName: string): Promise<void>;
+declare function databaseAuditMonitorTable(sql: SqlFunction, tableName: string, primaryKeyColumn?: string): Promise<void>;
 /**
  * Returns all rows from the `audit_log` table, ordered by `performed_at` DESC.
  */
@@ -316,4 +340,4 @@ declare function databaseAuditDumpLogTable(sql: SqlFunction): Promise<Record<str
 
 declare function getCurrentRequestId(): string | null;
 
-export { type BackendRequest, type BlobData, type CapturedData, type CreateRecordingRequestHandlerOptions, type EnvRead, type FinishRequestCallbacks, type FinishRequestOptions, type HandlerResponse$1 as HandlerResponse, type NetlifyEvent, type NetlifyV2Request, type NetworkCall, type RecordingResult, type RequestContext, type RequestInfo, backendRequestsEnsureTable, backendRequestsGet, backendRequestsGetBlobData, backendRequestsInsert, backendRequestsList, backendRequestsUpdateStatus, createRecordingRequestHandler, createRequestRecording, databaseAuditDumpLogTable, databaseAuditEnsureLogTable, databaseAuditMonitorTable, databaseCallbacks, finishRequest, getCurrentRequestId, redactBlobData, startRequest };
+export { type BackendRequest, type BlobData, type CapturedData, type CreateRecordingRequestHandlerOptions, type EnsureRequestRecordingOptions, type EnvRead, type FinishRequestCallbacks, type FinishRequestOptions, type HandlerResponse$1 as HandlerResponse, type NetlifyEvent, type NetlifyV2Request, type NetworkCall, type RecordingResult, type RequestContext, type RequestInfo, backendRequestsEnsureTable, backendRequestsGet, backendRequestsGetBlobData, backendRequestsInsert, backendRequestsList, backendRequestsUpdateStatus, createRecordingRequestHandler, createRequestRecording, databaseAuditDumpLogTable, databaseAuditEnsureLogTable, databaseAuditMonitorTable, databaseCallbacks, ensureRequestRecording, finishRequest, getCurrentRequestId, redactBlobData, startRequest };

package/dist/index.js

@@ -1034,6 +1034,40 @@ function databaseCallbacks(sql) {
     }
   };
 }
+async function ensureRequestRecording(sql, requestId, options) {
+  const request = await backendRequestsGet(sql, requestId);
+  if (!request) {
+    throw new Error(`Backend request ${requestId} not found`);
+  }
+  if (request.status === "recorded" && request.recording_id) {
+    return request.recording_id;
+  }
+  if (request.status === "queued" || request.status === "processing") {
+    return null;
+  }
+  const recorderUrl = options.recorderUrl.replace(/\/+$/, "");
+  const blobDataUrl = options.blobDataUrl ?? `${recorderUrl}/api/get-backend-request-blob?requestId=${requestId}`;
+  const res = await fetch(`${recorderUrl}/api/create-recording`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      blobDataUrl,
+      handlerPath: request.handler_path,
+      commitSha: request.commit_sha,
+      branchName: request.branch_name,
+      repositoryUrl: request.repository_url ?? void 0,
+      webhookUrl: options.webhookUrl
+    })
+  });
+  if (!res.ok) {
+    const errBody = await res.text().catch(() => "(unreadable)");
+    throw new Error(
+      `Netlify Recorder create-recording failed: ${res.status} ${errBody}`
+    );
+  }
+  await backendRequestsUpdateStatus(sql, requestId, "queued");
+  return null;
+}
 
 // src/databaseAudit.ts
 async function databaseAuditEnsureLogTable(sql) {
@@ -1061,7 +1095,12 @@ async function databaseAuditEnsureLogTable(sql) {
       changed_cols TEXT[];
       req_id TEXT;
       call_idx INTEGER;
+      pk_col TEXT;
+      pk_val TEXT;
     BEGIN
+      -- Primary key column name passed as trigger argument; default to 'id'
+      pk_col := COALESCE(TG_ARGV[0], 'id');
+
       -- Read application context injected by the network interceptor
       req_id := COALESCE(current_setting('app.replay_request_id', true), '');
       IF req_id = '' THEN req_id := NULL; END IF;
@@ -1073,21 +1112,24 @@ async function databaseAuditEnsureLogTable(sql) {
       END;
 
       IF TG_OP = 'INSERT' THEN
+        EXECUTE format('SELECT ($1).%I::TEXT', pk_col) USING NEW INTO pk_val;
         INSERT INTO audit_log (table_name, record_id, action, new_data, replay_request_id, replay_request_call_index)
-        VALUES (TG_TABLE_NAME, NEW.id::TEXT, 'INSERT', to_jsonb(NEW), req_id, call_idx);
+        VALUES (TG_TABLE_NAME, pk_val, 'INSERT', to_jsonb(NEW), req_id, call_idx);
         RETURN NEW;
       ELSIF TG_OP = 'UPDATE' THEN
+        EXECUTE format('SELECT ($1).%I::TEXT', pk_col) USING NEW INTO pk_val;
         SELECT ARRAY_AGG(n.key) INTO changed_cols
         FROM jsonb_each_text(to_jsonb(NEW)) n
         LEFT JOIN jsonb_each_text(to_jsonb(OLD)) o ON n.key = o.key
         WHERE o.value IS DISTINCT FROM n.value;
 
         INSERT INTO audit_log (table_name, record_id, action, old_data, new_data, changed_fields, replay_request_id, replay_request_call_index)
-        VALUES (TG_TABLE_NAME, NEW.id::TEXT, 'UPDATE', to_jsonb(OLD), to_jsonb(NEW), COALESCE(changed_cols, ARRAY[]::TEXT[]), req_id, call_idx);
+        VALUES (TG_TABLE_NAME, pk_val, 'UPDATE', to_jsonb(OLD), to_jsonb(NEW), COALESCE(changed_cols, ARRAY[]::TEXT[]), req_id, call_idx);
         RETURN NEW;
       ELSIF TG_OP = 'DELETE' THEN
+        EXECUTE format('SELECT ($1).%I::TEXT', pk_col) USING OLD INTO pk_val;
         INSERT INTO audit_log (table_name, record_id, action, old_data, replay_request_id, replay_request_call_index)
-        VALUES (TG_TABLE_NAME, OLD.id::TEXT, 'DELETE', to_jsonb(OLD), req_id, call_idx);
+        VALUES (TG_TABLE_NAME, pk_val, 'DELETE', to_jsonb(OLD), req_id, call_idx);
         RETURN OLD;
       END IF;
       RETURN NULL;
@@ -1095,19 +1137,22 @@ async function databaseAuditEnsureLogTable(sql) {
     $$ LANGUAGE plpgsql
   `;
 }
-async function databaseAuditMonitorTable(sql, tableName) {
+async function databaseAuditMonitorTable(sql, tableName, primaryKeyColumn = "id") {
   if (tableName === "audit_log") {
     throw new Error("Cannot monitor the audit_log table itself");
   }
   if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(tableName)) {
     throw new Error(`Invalid table name: ${tableName}`);
   }
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(primaryKeyColumn)) {
+    throw new Error(`Invalid primary key column name: ${primaryKeyColumn}`);
+  }
   const triggerName = `audit_trigger_${tableName}`;
   await sql(
     `DROP TRIGGER IF EXISTS ${triggerName} ON "${tableName}"`
   );
   await sql(
-    `CREATE TRIGGER ${triggerName} AFTER INSERT OR UPDATE OR DELETE ON "${tableName}" FOR EACH ROW EXECUTE FUNCTION audit_trigger_function()`
+    `CREATE TRIGGER ${triggerName} AFTER INSERT OR UPDATE OR DELETE ON "${tableName}" FOR EACH ROW EXECUTE FUNCTION audit_trigger_function('${primaryKeyColumn}')`
   );
 }
 async function databaseAuditDumpLogTable(sql) {
@@ -1127,6 +1172,7 @@ export {
   databaseAuditEnsureLogTable,
   databaseAuditMonitorTable,
   databaseCallbacks,
+  ensureRequestRecording,
   finishRequest,
   getCurrentRequestId,
   redactBlobData,

package/package.json

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