@replayio-app-building/netlify-recorder 0.15.1 → 0.15.3

package/README.md

@@ -305,6 +305,90 @@ Self-hosted recording requires these environment variables:
 
 ---
 
+## Audit Log Support
+
+The package includes helpers that automatically track database mutations (INSERT, UPDATE, DELETE) in an `audit_log` table and link each change to the Replay request that caused it. This makes it easy to trace exactly which incoming request triggered a given database change.
+
+### Setup
+
+#### 1. Create the audit log table
+
+Call `databaseAuditEnsureLogTable` once during schema initialization. This creates the `audit_log` table, its indexes, and a reusable PL/pgSQL trigger function:
+
+```typescript
+import { databaseAuditEnsureLogTable } from "@replayio-app-building/netlify-recorder";
+
+await databaseAuditEnsureLogTable(sql);
+```
+
+#### 2. Monitor tables
+
+For each table you want to audit, call `databaseAuditMonitorTable`. This attaches a trigger that logs every INSERT, UPDATE, and DELETE:
+
+```typescript
+import { databaseAuditMonitorTable } from "@replayio-app-building/netlify-recorder";
+
+await databaseAuditMonitorTable(sql, "users");
+await databaseAuditMonitorTable(sql, "orders");
+```
+
+#### 3. Use audited SQL in your handlers
+
+Wrap your Neon SQL function with `createAuditedSql` inside handlers that are wrapped with `createRecordingRequestHandler`. This ensures each audit log entry is stamped with the current Replay request ID and a per-request call index:
+
+```typescript
+import {
+  createRecordingRequestHandler,
+  remoteCallbacks,
+  createAuditedSql,
+} from "@replayio-app-building/netlify-recorder";
+
+export default createRecordingRequestHandler(
+  async (req) => {
+    const auditedSql = createAuditedSql(sql);
+    // Queries through auditedSql automatically tag audit_log rows
+    // with the replay request ID — no extra code needed.
+    await auditedSql`INSERT INTO orders (product, qty) VALUES (${product}, ${qty})`;
+
+    return { statusCode: 200, body: "OK" };
+  },
+  {
+    callbacks: remoteCallbacks(RECORDER_URL),
+    handlerPath: "netlify/functions/create-order",
+  }
+);
+```
+
+#### 4. Query the audit log
+
+Use `databaseAuditDumpLogTable` to retrieve all audit entries (ordered by most recent first):
+
+```typescript
+import { databaseAuditDumpLogTable } from "@replayio-app-building/netlify-recorder";
+
+const entries = await databaseAuditDumpLogTable(sql);
+```
+
+Each entry contains:
+
+| Field | Description |
+|---|---|
+| `table_name` | The table where the change occurred |
+| `record_id` | The `id` of the affected row |
+| `action` | `INSERT`, `UPDATE`, or `DELETE` |
+| `old_data` | Previous row data (UPDATE/DELETE only) |
+| `new_data` | New row data (INSERT/UPDATE only) |
+| `changed_fields` | Array of column names that changed (UPDATE only) |
+| `performed_at` | Timestamp of the change |
+| `replay_request_id` | The Replay request ID that caused the change (when using `createAuditedSql`) |
+| `replay_request_call_index` | The sequential query index within the request |
+
+### How it works
+
+`createAuditedSql` wraps each query in a transaction that first calls `SET LOCAL` to inject the current request ID and call index into PostgreSQL session variables. The trigger function reads these via `current_setting()` and stamps audit rows atomically — no separate UPDATE required. If no request context is available (e.g. queries outside a handler), the query executes normally without audit metadata.
+
+---
+
 ## API Reference
 
 ### `createRecordingRequestHandler(handler, options): Handler`
@@ -386,6 +470,39 @@ Called inside a container running under `replay-node`. Downloads the captured da
 - `handlerPath` — Path to the handler module to execute
 - `requestInfo` — The original request info to replay
 
+### `databaseAuditEnsureLogTable(sql): Promise<void>`
+
+Creates the `audit_log` table, its indexes, and a reusable PL/pgSQL trigger function (`audit_trigger_function`). Call once during schema initialization.
+
+**Parameters:**
+- `sql` — A Neon SQL tagged-template function
+
+### `databaseAuditMonitorTable(sql, tableName): 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_]*$`)
+
+### `databaseAuditDumpLogTable(sql): Promise<Record<string, unknown>[]>`
+
+Returns all rows from the `audit_log` table, ordered by `performed_at` DESC.
+
+**Parameters:**
+- `sql` — A Neon SQL tagged-template function
+
+### `createAuditedSql(sql): SqlFunction`
+
+Wraps a Neon SQL tagged-template function so that each query runs inside a transaction that injects the current Replay request ID and call index via `SET LOCAL`. The audit trigger reads these values and stamps audit rows automatically.
+
+Falls back to non-audited execution when no request context is active or if the transaction fails.
+
+**Parameters:**
+- `sql` — A Neon SQL tagged-template function (must have a `.transaction()` method, as provided by the Neon HTTP driver)
+
+**Returns:** A wrapped SQL function with the same tagged-template interface.
+
 ## Environment Variables
 
 ### Required for all setups (read by `finishRequest`)

package/dist/index.js

@@ -126,6 +126,10 @@ function installNetworkInterceptor(mode, calls) {
 function installEnvironmentInterceptor(mode, reads) {
   const originalEnv = process.env;
   if (mode === "capture") {
+    const now = Date.now();
+    for (const key of Object.keys(originalEnv)) {
+      reads.push({ key, value: originalEnv[key], timestamp: now });
+    }
     process.env = new Proxy(originalEnv, {
       get(target, prop) {
         const value = target[prop];
@@ -862,6 +866,16 @@ async function createRequestRecording(blobUrlOrData, handlerPath, requestInfo) {
     };
     g.File = FileShim;
   }
+  if (typeof g.crypto === "undefined") {
+    try {
+      const nodeCrypto = __require("crypto");
+      g.crypto = {
+        randomUUID: () => nodeCrypto.randomUUID(),
+        getRandomValues: (buf) => nodeCrypto.getRandomValues(buf)
+      };
+    } catch {
+    }
+  }
   if (typeof g.Headers === "undefined") {
     const HeadersShim = class Headers {
       _map;
@@ -1174,12 +1188,11 @@ async function databaseAuditMonitorTable(sql, tableName) {
     throw new Error(`Invalid table name: ${tableName}`);
   }
   const triggerName = `audit_trigger_${tableName}`;
-  const asTemplate = (s) => Object.assign([s], { raw: [s] });
   await sql(
-    asTemplate(`DROP TRIGGER IF EXISTS ${triggerName} ON "${tableName}"`)
+    `DROP TRIGGER IF EXISTS ${triggerName} ON "${tableName}"`
   );
   await sql(
-    asTemplate(`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()`
   );
 }
 async function databaseAuditDumpLogTable(sql) {

package/package.json

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