@replayio-app-building/netlify-recorder 0.34.0 → 0.35.0

package/README.md

@@ -113,7 +113,63 @@ export default createRecordingRequestHandler(
 
 > **Note:** Always use the response returned by the wrapper (or `finishRequest`), not your original response object. The wrapper adds the `X-Replay-Request-Id` header to the response it returns.
 
-### 4. Create recordings via the Netlify Recorder service
+### 4. Expose a recording endpoint for other services
+
+Use `createRecordingEndpoint` to create a standalone Netlify function that other services can call to trigger recording creation or check recording status. This is the simplest way to let external services interact with the `backend_requests` table without importing the full package.
+
+```typescript
+// netlify/functions/ensure-recording.ts
+import { createRecordingEndpoint } from "@replayio-app-building/netlify-recorder";
+import { neon } from "@neondatabase/serverless";
+
+const sql = neon(process.env.DATABASE_URL!);
+
+export default createRecordingEndpoint({
+  sql,
+  recorderUrl: "https://netlify-recorder-bm4wmw.netlify.app",
+  // Optional: require callers to authenticate with a shared secret
+  secret: process.env.RECORDER_ENDPOINT_SECRET,
+  // Optional: receive a webhook when the recording completes
+  webhookUrl: "https://my-app.netlify.app/.netlify/functions/recording-webhook",
+});
+```
+
+**Calling the endpoint from another service:**
+
+```typescript
+// Trigger recording creation (POST)
+const res = await fetch("https://my-app.netlify.app/.netlify/functions/ensure-recording", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    // Include if `secret` is configured:
+    "Authorization": "Bearer my-shared-secret",
+  },
+  body: JSON.stringify({ requestId: "a1b2c3d4-..." }),
+});
+const result = await res.json();
+// { status: "queued", requestId: "a1b2c3d4-..." }
+// or { status: "recorded", recordingId: "...", requestId: "..." }
+// or { status: "pending", requestId: "..." }
+
+// Check status without triggering (GET)
+const status = await fetch(
+  "https://my-app.netlify.app/.netlify/functions/ensure-recording?requestId=a1b2c3d4-...",
+  { headers: { "Authorization": "Bearer my-shared-secret" } },
+);
+```
+
+**Response statuses:**
+
+| Status | HTTP Code | Meaning |
+|--------|-----------|---------|
+| `recorded` | 200 | Recording exists — `recordingId` is included |
+| `pending` | 200 | Recording is queued or processing — check back later |
+| `queued` | 202 | Recording was just queued by this POST call |
+| `not_found` | 404 | Request ID not found in `backend_requests` |
+| `error` | 4xx/5xx | Validation error, auth failure, or recording failure |
+
+### 5. Create recordings programmatically
 
 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 passes the stored blob data URL to the Netlify Recorder service and updates the row status to `"queued"`.
 
@@ -150,7 +206,7 @@ On failure:
 { "status": "failed", "error": "Error message" }
 ```
 
-### 5. Manage stored requests
+### 6. Manage stored requests
 
 Use the `backendRequests*` helpers to query and manage captured requests in your database:
 
@@ -410,6 +466,30 @@ Ensures a Replay recording exists (or is being created) for a backend request. L
 
 **Throws:** If the request ID is not found in `backend_requests`, or if the service call fails.
 
+### `createRecordingEndpoint(options): (req: Request) => Promise<Response>`
+
+Creates a Netlify Function v2 handler that other services can call to trigger recording creation or check recording status for entries in the `backend_requests` table.
+
+Supports **POST** (trigger recording) and **GET** (check status). When `secret` is provided, all requests must include an `Authorization: Bearer <secret>` header.
+
+**Parameters:**
+- `options.sql` — A Neon SQL tagged-template function
+- `options.recorderUrl` — Base URL of the Netlify Recorder service
+- `options.secret` — Shared secret for authentication (optional — when omitted, the endpoint is open)
+- `options.webhookUrl` — URL to POST the recording result to when complete (optional)
+
+**Returns:** An async function `(req: Request) => Promise<Response>` suitable as a Netlify Functions v2 default export.
+
+**POST body:** `{ "requestId": "<uuid>" }` — triggers recording if needed.
+
+**GET query:** `?requestId=<uuid>` — returns current status without triggering.
+
+**Response body** (`RecordingEndpointResponse`):
+- `status` — `"recorded"`, `"pending"`, `"queued"`, `"not_found"`, or `"error"`
+- `recordingId` — Present when `status` is `"recorded"`
+- `requestId` — The request ID echoed back
+- `error` — Error message when `status` is `"not_found"` or `"error"`
+
 ### `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

@@ -235,7 +235,7 @@ interface RecordingResult {
  */
 declare function createRequestRecording(blobUrlOrData: string | BlobData, handlerPath: string, requestInfo: RequestInfo): Promise<RecordingResult>;
 
-type SqlFunction$1 = (...args: any[]) => Promise<any[]>;
+type SqlFunction$2 = (...args: any[]) => Promise<any[]>;
 interface BackendRequest {
     id: string;
     blob_data_url: string;
@@ -256,8 +256,8 @@ interface BackendRequest {
  * using this table. The blob data (captured network calls, env reads, etc.)
  * is uploaded to UploadThing at capture time and only the URL is stored.
  */
-declare function backendRequestsEnsureTable(sql: SqlFunction$1): Promise<void>;
-declare function backendRequestsInsert(sql: SqlFunction$1, data: {
+declare function backendRequestsEnsureTable(sql: SqlFunction$2): Promise<void>;
+declare function backendRequestsInsert(sql: SqlFunction$2, data: {
     id?: string;
     blobDataUrl: string;
     handlerPath: string;
@@ -265,13 +265,13 @@ declare function backendRequestsInsert(sql: SqlFunction$1, data: {
     branchName: string;
     repositoryUrl?: string | null;
 }): Promise<string>;
-declare function backendRequestsGet(sql: SqlFunction$1, id: string): Promise<BackendRequest | null>;
-declare function backendRequestsGetBlobUrl(sql: SqlFunction$1, id: string): Promise<string | null>;
-declare function backendRequestsList(sql: SqlFunction$1, filters?: {
+declare function backendRequestsGet(sql: SqlFunction$2, id: string): Promise<BackendRequest | null>;
+declare function backendRequestsGetBlobUrl(sql: SqlFunction$2, id: string): Promise<string | null>;
+declare function backendRequestsList(sql: SqlFunction$2, filters?: {
     status?: string;
     limit?: number;
 }): Promise<BackendRequest[]>;
-declare function backendRequestsUpdateStatus(sql: SqlFunction$1, id: string, status: string, recordingId?: string, errorMessage?: string): Promise<void>;
+declare function backendRequestsUpdateStatus(sql: SqlFunction$2, id: string, status: string, recordingId?: string, errorMessage?: string): Promise<void>;
 /**
  * Convenience helper: creates `FinishRequestCallbacks` that upload
  * captured request data to UploadThing and store the URL in the
@@ -279,7 +279,15 @@ declare function backendRequestsUpdateStatus(sql: SqlFunction$1, id: string, sta
  *
  * Requires `UPLOADTHING_TOKEN` environment variable and the `uploadthing` package.
  */
-declare function databaseCallbacks(sql: SqlFunction$1): FinishRequestCallbacks;
+declare function databaseCallbacks(sql: SqlFunction$2): FinishRequestCallbacks;
+/**
+ * Creates `FinishRequestCallbacks` that POST captured request data to a
+ * remote Netlify Recorder service's `/api/store-request` endpoint.
+ *
+ * Use this instead of `databaseCallbacks` when the app does not own the
+ * recorder database — the hosted service handles blob upload and storage.
+ */
+declare function remoteCallbacks(recorderUrl: string): FinishRequestCallbacks;
 interface EnsureRequestRecordingOptions {
     /** Base URL of the Netlify Recorder service (e.g. "https://netlify-recorder-bm4wmw.netlify.app"). */
     recorderUrl: string;
@@ -299,9 +307,9 @@ interface EnsureRequestRecordingOptions {
  * 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>;
+declare function ensureRequestRecording(sql: SqlFunction$2, requestId: string, options: EnsureRequestRecordingOptions): Promise<string | null>;
 
-type SqlFunction = (...args: any[]) => Promise<any[]>;
+type SqlFunction$1 = (...args: any[]) => Promise<any[]>;
 /**
  * Creates the `audit_log` table and a generic PL/pgSQL trigger function
  * (`audit_trigger_function`) that records INSERT, UPDATE, and DELETE
@@ -309,20 +317,56 @@ type SqlFunction = (...args: any[]) => Promise<any[]>;
  *
  * Call this once during schema initialization.
  */
-declare function databaseAuditEnsureLogTable(sql: SqlFunction): Promise<void>;
+declare function databaseAuditEnsureLogTable(sql: SqlFunction$1): Promise<void>;
 /**
  * Creates a trigger on the specified table that calls
  * `audit_trigger_function` for INSERT, UPDATE, and DELETE operations.
  *
  * Throws if `tableName` is `'audit_log'` (cannot monitor itself).
  */
-declare function databaseAuditMonitorTable(sql: SqlFunction, tableName: string, primaryKeyColumn?: string): Promise<void>;
+declare function databaseAuditMonitorTable(sql: SqlFunction$1, tableName: string, primaryKeyColumn?: string): Promise<void>;
 /**
  * Returns all rows from the `audit_log` table, ordered by `performed_at` DESC.
  */
-declare function databaseAuditDumpLogTable(sql: SqlFunction): Promise<Record<string, unknown>[]>;
+declare function databaseAuditDumpLogTable(sql: SqlFunction$1): Promise<Record<string, unknown>[]>;
+
+type SqlFunction = (...args: any[]) => Promise<any[]>;
+interface CreateRecordingEndpointOptions {
+    sql: SqlFunction;
+    recorderUrl: string;
+    secret?: string;
+    webhookUrl?: string;
+}
+interface RecordingEndpointResponse {
+    status: "recorded" | "pending" | "queued" | "not_found" | "error";
+    recordingId?: string;
+    requestId?: string;
+    error?: string;
+}
+/**
+ * Creates a Netlify Function handler that other services can call to trigger
+ * recording creation for a backend request (or retrieve its current status).
+ *
+ * **POST** with `{ "requestId": "<uuid>" }` — triggers recording creation if
+ * needed and returns the current status. Idempotent: re-posting the same
+ * request ID will not re-queue an already-queued or recorded request.
+ *
+ * **GET** with `?requestId=<uuid>` — returns the current recording status
+ * without triggering any recording.
+ *
+ * When `secret` is provided, every request must include an
+ * `Authorization: Bearer <secret>` header or receive a 401 response.
+ *
+ * Response body shape (`RecordingEndpointResponse`):
+ * - `{ status: "recorded", recordingId, requestId }` — recording exists
+ * - `{ status: "pending", requestId }` — recording is queued or processing
+ * - `{ status: "queued", requestId }` — recording was just queued by this call
+ * - `{ status: "not_found", error }` — request ID not in backend_requests
+ * - `{ status: "error", requestId?, error }` — recording failed or server error
+ */
+declare function createRecordingEndpoint(options: CreateRecordingEndpointOptions): (req: Request) => Promise<Response>;
 
 declare function runInRequestContext<T>(requestId: string | null, fn: () => Promise<T>): Promise<T>;
 declare function getCurrentRequestId(): string | null;
 
-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, backendRequestsGetBlobUrl, backendRequestsInsert, backendRequestsList, backendRequestsUpdateStatus, createRecordingRequestHandler, createRequestRecording, databaseAuditDumpLogTable, databaseAuditEnsureLogTable, databaseAuditMonitorTable, databaseCallbacks, ensureRequestRecording, finishRequest, getCurrentRequestId, redactBlobData, runInRequestContext, startRequest };
+export { type BackendRequest, type BlobData, type CapturedData, type CreateRecordingEndpointOptions, type CreateRecordingRequestHandlerOptions, type EnsureRequestRecordingOptions, type EnvRead, type FinishRequestCallbacks, type FinishRequestOptions, type HandlerResponse$1 as HandlerResponse, type NetlifyEvent, type NetlifyV2Request, type NetworkCall, type RecordingEndpointResponse, type RecordingResult, type RequestContext, type RequestInfo, backendRequestsEnsureTable, backendRequestsGet, backendRequestsGetBlobUrl, backendRequestsInsert, backendRequestsList, backendRequestsUpdateStatus, createRecordingEndpoint, createRecordingRequestHandler, createRequestRecording, databaseAuditDumpLogTable, databaseAuditEnsureLogTable, databaseAuditMonitorTable, databaseCallbacks, ensureRequestRecording, finishRequest, getCurrentRequestId, redactBlobData, remoteCallbacks, runInRequestContext, startRequest };

package/dist/index.js

@@ -974,6 +974,9 @@ async function createRequestRecording(blobUrlOrData, handlerPath, requestInfo) {
         headers["content-type"] = "application/json";
         return new ResponseShim(body, { ...init, headers });
       }
+      get body() {
+        return this._body;
+      }
       async text() {
         return this._body ?? "";
       }
@@ -1280,6 +1283,33 @@ function databaseCallbacks(sql) {
     }
   };
 }
+function remoteCallbacks(recorderUrl) {
+  const baseUrl = recorderUrl.replace(/\/+$/, "");
+  return {
+    storeRequest: async (data) => {
+      const res = await fetch(`${baseUrl}/api/store-request`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          blobData: data.blobData,
+          commitSha: data.commitSha,
+          branchName: data.branchName,
+          repositoryUrl: data.repositoryUrl,
+          handlerPath: data.handlerPath,
+          requestId: data.requestId
+        })
+      });
+      if (!res.ok) {
+        const errBody = await res.text().catch(() => "(unreadable)");
+        throw new Error(
+          `netlify-recorder: remote store-request failed: ${res.status} ${errBody}`
+        );
+      }
+      const result = await res.json();
+      return result.requestId;
+    }
+  };
+}
 async function ensureRequestRecording(sql, requestId, options) {
   const request = await backendRequestsGet(sql, requestId);
   if (!request) {
@@ -1405,6 +1435,92 @@ async function databaseAuditDumpLogTable(sql) {
   const rows = await sql`SELECT * FROM audit_log ORDER BY performed_at DESC`;
   return rows;
 }
+
+// src/createRecordingEndpoint.ts
+function jsonResponse(body, status) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+function formatStatus(request) {
+  if (request.status === "recorded" && request.recording_id) {
+    return { status: "recorded", recordingId: request.recording_id, requestId: request.id };
+  }
+  if (request.status === "queued" || request.status === "processing") {
+    return { status: "pending", requestId: request.id };
+  }
+  if (request.status === "failed") {
+    return { status: "error", requestId: request.id, error: request.error_message ?? "Recording failed" };
+  }
+  return { status: "pending", requestId: request.id };
+}
+function createRecordingEndpoint(options) {
+  const { sql, recorderUrl, secret, webhookUrl } = options;
+  return async (req) => {
+    if (secret) {
+      const auth = req.headers.get("authorization");
+      if (auth !== `Bearer ${secret}`) {
+        return jsonResponse({ status: "error", error: "Unauthorized" }, 401);
+      }
+    }
+    try {
+      if (req.method === "GET") {
+        const url = new URL(req.url);
+        const requestId = url.searchParams.get("requestId");
+        if (!requestId) {
+          return jsonResponse({ status: "error", error: "Missing requestId query parameter" }, 400);
+        }
+        const request = await backendRequestsGet(sql, requestId);
+        if (!request) {
+          return jsonResponse({ status: "not_found", error: `Request ${requestId} not found` }, 404);
+        }
+        return jsonResponse(formatStatus(request), 200);
+      }
+      if (req.method === "POST") {
+        const body = await req.json();
+        const requestId = body.requestId;
+        if (!requestId) {
+          return jsonResponse({ status: "error", error: "Missing requestId in request body" }, 400);
+        }
+        const request = await backendRequestsGet(sql, requestId);
+        if (!request) {
+          return jsonResponse({ status: "not_found", error: `Request ${requestId} not found` }, 404);
+        }
+        if (request.status === "recorded" && request.recording_id) {
+          return jsonResponse(
+            { status: "recorded", recordingId: request.recording_id, requestId },
+            200
+          );
+        }
+        if (request.status === "queued" || request.status === "processing") {
+          return jsonResponse({ status: "pending", requestId }, 200);
+        }
+        try {
+          const recordingId = await ensureRequestRecording(sql, requestId, {
+            recorderUrl,
+            webhookUrl
+          });
+          if (recordingId) {
+            return jsonResponse({ status: "recorded", recordingId, requestId }, 200);
+          }
+          return jsonResponse({ status: "queued", requestId }, 202);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          await backendRequestsUpdateStatus(sql, requestId, "failed", void 0, message).catch(
+            () => {
+            }
+          );
+          return jsonResponse({ status: "error", requestId, error: message }, 502);
+        }
+      }
+      return jsonResponse({ status: "error", error: "Method not allowed" }, 405);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return jsonResponse({ status: "error", error: message }, 500);
+    }
+  };
+}
 export {
   backendRequestsEnsureTable,
   backendRequestsGet,
@@ -1412,6 +1528,7 @@ export {
   backendRequestsInsert,
   backendRequestsList,
   backendRequestsUpdateStatus,
+  createRecordingEndpoint,
   createRecordingRequestHandler,
   createRequestRecording,
   databaseAuditDumpLogTable,
@@ -1422,6 +1539,7 @@ export {
   finishRequest,
   getCurrentRequestId,
   redactBlobData,
+  remoteCallbacks,
   runInRequestContext,
   startRequest
 };

package/package.json

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