@replayio-app-building/netlify-recorder 0.18.0 → 0.19.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.

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[]>;
 /**
@@ -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) {
@@ -1127,6 +1161,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.19.0",
   "description": "Capture and replay Netlify function executions as Replay recordings",
   "type": "module",
   "exports": {