ezlogs-nextjs 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +779 -0
- package/bin/install-triggers.cjs +75 -0
- package/dist/actors/index.cjs +111 -0
- package/dist/actors/index.d.cts +52 -0
- package/dist/actors/index.d.ts +52 -0
- package/dist/actors/index.js +107 -0
- package/dist/configuration-D9x9Gvds.d.cts +190 -0
- package/dist/configuration-D9x9Gvds.d.ts +190 -0
- package/dist/db/drizzle.cjs +898 -0
- package/dist/db/drizzle.d.cts +68 -0
- package/dist/db/drizzle.d.ts +68 -0
- package/dist/db/drizzle.js +893 -0
- package/dist/db/prisma.cjs +826 -0
- package/dist/db/prisma.d.cts +3 -0
- package/dist/db/prisma.d.ts +3 -0
- package/dist/db/prisma.js +824 -0
- package/dist/db/supabase.cjs +1027 -0
- package/dist/db/supabase.d.cts +32 -0
- package/dist/db/supabase.d.ts +32 -0
- package/dist/db/supabase.js +1024 -0
- package/dist/index.cjs +3329 -0
- package/dist/index.d.cts +305 -0
- package/dist/index.d.ts +305 -0
- package/dist/index.js +3317 -0
- package/dist/jobs/bullmq.cjs +624 -0
- package/dist/jobs/bullmq.d.cts +33 -0
- package/dist/jobs/bullmq.d.ts +33 -0
- package/dist/jobs/bullmq.js +621 -0
- package/dist/jobs/inngest.cjs +645 -0
- package/dist/jobs/inngest.d.cts +21 -0
- package/dist/jobs/inngest.d.ts +21 -0
- package/dist/jobs/inngest.js +642 -0
- package/dist/jobs/supabase-queues.cjs +661 -0
- package/dist/jobs/supabase-queues.d.cts +37 -0
- package/dist/jobs/supabase-queues.d.ts +37 -0
- package/dist/jobs/supabase-queues.js +657 -0
- package/dist/jobs/trigger.cjs +622 -0
- package/dist/jobs/trigger.d.cts +46 -0
- package/dist/jobs/trigger.d.ts +46 -0
- package/dist/jobs/trigger.js +619 -0
- package/dist/jobs/upstash-workflow.cjs +673 -0
- package/dist/jobs/upstash-workflow.d.cts +57 -0
- package/dist/jobs/upstash-workflow.d.ts +57 -0
- package/dist/jobs/upstash-workflow.js +669 -0
- package/dist/nextjs-plugin/index.cjs +232 -0
- package/dist/nextjs-plugin/index.d.cts +68 -0
- package/dist/nextjs-plugin/index.d.ts +68 -0
- package/dist/nextjs-plugin/index.js +229 -0
- package/dist/nextjs-plugin/loader.cjs +16248 -0
- package/dist/nextjs-plugin/loader.d.cts +61 -0
- package/dist/nextjs-plugin/loader.d.ts +61 -0
- package/dist/nextjs-plugin/loader.js +16242 -0
- package/dist/triggers/index.cjs +1354 -0
- package/dist/triggers/index.d.cts +243 -0
- package/dist/triggers/index.d.ts +243 -0
- package/dist/triggers/index.js +1337 -0
- package/package.json +150 -0
- package/sql/postgres/00_install.sql +205 -0
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
interface ParsedArgs {
|
|
2
|
+
connection: string | null;
|
|
3
|
+
tables: string[];
|
|
4
|
+
/**
|
|
5
|
+
* Auto-detect mode. True when the user passes no `--tables=` flag or
|
|
6
|
+
* explicitly passes `--tables=auto`. The CLI then introspects
|
|
7
|
+
* `information_schema` and tracks every business table in the public
|
|
8
|
+
* schema, minus a built-in infrastructure skip list.
|
|
9
|
+
*/
|
|
10
|
+
autoTables: boolean;
|
|
11
|
+
print: boolean;
|
|
12
|
+
help: boolean;
|
|
13
|
+
}
|
|
14
|
+
declare function parseArgs(argv: string[]): ParsedArgs;
|
|
15
|
+
type Detected = {
|
|
16
|
+
engine: "postgres";
|
|
17
|
+
} | {
|
|
18
|
+
engine: "mysql";
|
|
19
|
+
} | {
|
|
20
|
+
engine: "planetscale";
|
|
21
|
+
} | {
|
|
22
|
+
engine: "unknown";
|
|
23
|
+
};
|
|
24
|
+
declare function detectEngine(connection: string | null): Detected;
|
|
25
|
+
declare function buildTrackingSql(tables: string[], engine: "postgres" | "mysql"): string;
|
|
26
|
+
interface RunOptions {
|
|
27
|
+
/** Async exec — caller passes a function that runs SQL against their DB. */
|
|
28
|
+
exec?: (sql: string) => Promise<unknown>;
|
|
29
|
+
/**
|
|
30
|
+
* Async query — returns `{ rows: ... }` (matches `pg`'s shape).
|
|
31
|
+
* Required for `--tables=auto` so we can introspect the schema before
|
|
32
|
+
* building the tracking SQL. Tests inject. The CLI shim wires this
|
|
33
|
+
* with `pg.Client.prototype.query`.
|
|
34
|
+
*/
|
|
35
|
+
query?: (sql: string) => Promise<{
|
|
36
|
+
rows: Array<{
|
|
37
|
+
table_name: string;
|
|
38
|
+
}>;
|
|
39
|
+
}>;
|
|
40
|
+
/** Output sink. Defaults to console.log. Tests inject. */
|
|
41
|
+
out?: (line: string) => void;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Programmatic entry. Returns 0 on success, non-zero on failure.
|
|
45
|
+
* Tests call this with a stubbed `exec`. The real CLI binary
|
|
46
|
+
* (`bin/install.cjs`) wraps this with a `pg`-backed exec.
|
|
47
|
+
*/
|
|
48
|
+
declare function runInstall(args: ParsedArgs, options?: RunOptions): Promise<number>;
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Minimal SQL executor shape. Anything that can `await fn(sql, params)`
|
|
52
|
+
* works — we deliberately don't depend on any specific driver type.
|
|
53
|
+
*
|
|
54
|
+
* `params` is positional Postgres-style (`$1`, `$2`, …). The result
|
|
55
|
+
* is ignored (we don't inspect it) so the return type is `unknown`.
|
|
56
|
+
*/
|
|
57
|
+
type SqlExecutor = (sql: string, params: ReadonlyArray<unknown>) => Promise<unknown>;
|
|
58
|
+
/**
|
|
59
|
+
* Snapshot of the values the trigger needs to see on the current
|
|
60
|
+
* transaction. Both fields are nullable — there's no guarantee a
|
|
61
|
+
* given request has either resolved by the time the customer's
|
|
62
|
+
* mutation runs.
|
|
63
|
+
*
|
|
64
|
+
* Returned as a primitive so customers on ORMs whose APIs don't fit
|
|
65
|
+
* the `(sql, params)` shape (Drizzle's tagged-template `sql` builder,
|
|
66
|
+
* Prisma's `$executeRaw`, postgres.js's `sql\`...\``) can compose
|
|
67
|
+
* the SET statement against their own query primitive without going
|
|
68
|
+
* through `applyDatabaseContext`.
|
|
69
|
+
*/
|
|
70
|
+
interface DatabaseContextSnapshot {
|
|
71
|
+
actorId: string | null;
|
|
72
|
+
correlationId: string | null;
|
|
73
|
+
}
|
|
74
|
+
declare function getDatabaseContext(): DatabaseContextSnapshot;
|
|
75
|
+
/**
|
|
76
|
+
* Runs `SELECT set_config('ezlogs.actor_id', $1, true)` and the
|
|
77
|
+
* matching correlation id call against `exec`.
|
|
78
|
+
*
|
|
79
|
+
* `is_local = true` scopes the setting to the current transaction —
|
|
80
|
+
* required for PgBouncer-pooled deployments (Supabase, Neon, Vercel
|
|
81
|
+
* Postgres) where the connection is shared between requests.
|
|
82
|
+
*
|
|
83
|
+
* The caller MUST be inside an explicit transaction when calling
|
|
84
|
+
* this. Outside a transaction, `set_config(_, _, true)` is a no-op
|
|
85
|
+
* (Postgres has nothing to scope to) and the trigger reads NULL.
|
|
86
|
+
*
|
|
87
|
+
* No-ops (skips the SQL entirely) when both actor and correlation
|
|
88
|
+
* are absent — saves two round-trips for un-instrumented callers.
|
|
89
|
+
*/
|
|
90
|
+
declare function applyDatabaseContext(exec: SqlExecutor): Promise<void>;
|
|
91
|
+
/**
|
|
92
|
+
* `pg`-style client: anything that accepts `client.query(sql)` /
|
|
93
|
+
* `client.query(sql, params)` and returns a Promise. Both
|
|
94
|
+
* `pg.Client` and `pg.PoolClient` match. Drizzle's `db.execute` and
|
|
95
|
+
* Prisma's `tx.$executeRawUnsafe` don't fit this shape directly —
|
|
96
|
+
* those callers should use `applyDatabaseContext` inside their own
|
|
97
|
+
* `db.transaction(...)` callback instead.
|
|
98
|
+
*/
|
|
99
|
+
interface PgLikeClient {
|
|
100
|
+
query(sql: string, params?: ReadonlyArray<unknown>): Promise<unknown>;
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* Convenience wrapper: opens BEGIN on a `pg`-style client, applies
|
|
104
|
+
* the current request's actor/correlation as session-local GUCs,
|
|
105
|
+
* runs `callback`, then COMMIT. ROLLBACK on any thrown error.
|
|
106
|
+
*
|
|
107
|
+
* Use this when your code path doesn't already have a transaction
|
|
108
|
+
* (e.g., a Server Action that does a single mutation). For code
|
|
109
|
+
* already inside `db.transaction(async tx => ...)`, call
|
|
110
|
+
* `applyDatabaseContext(tx-exec-fn)` at the top of the callback
|
|
111
|
+
* instead — wrapping a transaction in another transaction is an
|
|
112
|
+
* error in Postgres.
|
|
113
|
+
*
|
|
114
|
+
* The callback receives the same client back so the customer can
|
|
115
|
+
* issue their reads/writes against the in-flight transaction.
|
|
116
|
+
*/
|
|
117
|
+
declare function withDatabaseContext<T>(client: PgLikeClient, callback: (client: PgLikeClient) => Promise<T>): Promise<T>;
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* Shape of one row returned by the audit-log SELECT. Matches the
|
|
121
|
+
* column list in `00_install.sql` exactly. Drivers vary on how they
|
|
122
|
+
* deserialize jsonb (`pg` returns plain objects; some serverless
|
|
123
|
+
* drivers return strings) — `coerceJsonb` below handles both.
|
|
124
|
+
*/
|
|
125
|
+
interface AuditRow {
|
|
126
|
+
table_name: string;
|
|
127
|
+
op: "INSERT" | "UPDATE" | "DELETE";
|
|
128
|
+
old_row: Record<string, unknown> | string | null;
|
|
129
|
+
new_row: Record<string, unknown> | string | null;
|
|
130
|
+
resource_id: string | null;
|
|
131
|
+
}
|
|
132
|
+
/**
|
|
133
|
+
* Fetch audit rows tagged with `correlationId` in capture order.
|
|
134
|
+
*
|
|
135
|
+
* Returns rows oldest-first (matches the trigger's `clock_timestamp`
|
|
136
|
+
* within a transaction) so the dashboard renders them chronologically.
|
|
137
|
+
*
|
|
138
|
+
* Errors are caught and returned as `[]` — a failed audit read must
|
|
139
|
+
* never break the host request. The error is logged at debug.
|
|
140
|
+
*/
|
|
141
|
+
declare function readAuditRows(exec: SqlExecutor, correlationId: string,
|
|
142
|
+
/**
|
|
143
|
+
* Snapshot of `MAX(id)` taken at the start of the request. Used as
|
|
144
|
+
* the lower bound for the time-window fallback path that catches
|
|
145
|
+
* rows whose `correlation_id` is NULL — i.e., supabase-js writes
|
|
146
|
+
* that didn't go through SET LOCAL because PostgREST doesn't
|
|
147
|
+
* expose explicit transactions to the client.
|
|
148
|
+
*
|
|
149
|
+
* When null, the reader falls back to correlation-only matching
|
|
150
|
+
* (Phase 5 primary path).
|
|
151
|
+
*/
|
|
152
|
+
snapshotMaxId?: bigint | null): Promise<AuditRow[]>;
|
|
153
|
+
/**
|
|
154
|
+
* Take a snapshot of the current `MAX(id)` from `ezlogs_audit_log` and
|
|
155
|
+
* store it on the per-request scope. Called at the start of each HTTP
|
|
156
|
+
* request when `databaseReader` is configured. The reader's time-window
|
|
157
|
+
* fallback uses this as the lower bound for catching supabase-js writes
|
|
158
|
+
* (rows whose `correlation_id` is NULL because PostgREST didn't run
|
|
159
|
+
* inside our explicit transaction).
|
|
160
|
+
*
|
|
161
|
+
* Errors are swallowed — a failed snapshot just means the time-window
|
|
162
|
+
* fallback degrades to "match correlation_id only" for this request.
|
|
163
|
+
* Never break the host's request over a bookkeeping query.
|
|
164
|
+
*/
|
|
165
|
+
declare function takeAuditSnapshot(exec: SqlExecutor): Promise<void>;
|
|
166
|
+
/**
|
|
167
|
+
* Detect which tables have the `ezlogs_audit` trigger attached. Used
|
|
168
|
+
* by the per-ORM adapters to decide whether their per-mutation emit
|
|
169
|
+
* is redundant (the audit reader will surface the same write with
|
|
170
|
+
* full old/new state) or needs to fire (table isn't tracked, the
|
|
171
|
+
* adapter is the only path that captures it).
|
|
172
|
+
*
|
|
173
|
+
* Read once at agent startup. The result is a Set of table names —
|
|
174
|
+
* we don't read the schema, since `ezlogs_track` only attaches to
|
|
175
|
+
* `public.<table>` and the customer's mutations resolve through the
|
|
176
|
+
* default search_path the same way.
|
|
177
|
+
*
|
|
178
|
+
* Returns null on failure. Callers treat null as "detection unknown,
|
|
179
|
+
* fall back to original suppress-all behavior" — that's the
|
|
180
|
+
* conservative choice: silently double-emitting for trigger-tracked
|
|
181
|
+
* tables is worse than missing capture for an untracked one, because
|
|
182
|
+
* detection failure usually means the trigger install itself isn't
|
|
183
|
+
* complete and there's nothing to read anyway.
|
|
184
|
+
*/
|
|
185
|
+
declare function detectTriggerTrackedTables(exec: SqlExecutor): Promise<Set<string> | null>;
|
|
186
|
+
/**
|
|
187
|
+
* Push every fetched row into the existing `emitDbEvent` pipeline.
|
|
188
|
+
* Public so tests and advanced customers can call it directly.
|
|
189
|
+
*/
|
|
190
|
+
declare function emitAuditRows(rows: ReadonlyArray<AuditRow>): void;
|
|
191
|
+
/**
|
|
192
|
+
* End-of-request entry point. Reads rows for the current correlation
|
|
193
|
+
* id and emits each one. Skips when no correlation is in scope (no
|
|
194
|
+
* way to match rows back to this request) or no exec is supplied.
|
|
195
|
+
*
|
|
196
|
+
* The HTTP capturers call this after the user's handler returns,
|
|
197
|
+
* before they push the HTTP event itself, so DB events arrive
|
|
198
|
+
* grouped under the same correlation as the HTTP card.
|
|
199
|
+
*/
|
|
200
|
+
declare function flushAuditLog(exec: SqlExecutor | null | undefined): Promise<void>;
|
|
201
|
+
|
|
202
|
+
/** Read the current request's audit snapshot, if any. */
|
|
203
|
+
declare function currentAuditSnapshot(): bigint | null;
|
|
204
|
+
/** Run `callback` inside a fresh audit-snapshot scope. */
|
|
205
|
+
declare function runWithAuditSnapshotScope<R>(callback: () => R): R;
|
|
206
|
+
|
|
207
|
+
interface PgQueryConfig {
|
|
208
|
+
text?: string;
|
|
209
|
+
name?: string;
|
|
210
|
+
values?: unknown[];
|
|
211
|
+
rowMode?: string;
|
|
212
|
+
types?: unknown;
|
|
213
|
+
submit?: unknown;
|
|
214
|
+
[key: string]: unknown;
|
|
215
|
+
}
|
|
216
|
+
type PgQueryArg = string | PgQueryConfig;
|
|
217
|
+
/**
|
|
218
|
+
* Minimal shape of `pg.Client.prototype.query`. The real signature
|
|
219
|
+
* is overloaded across (text, values?, cb?) and (config, cb?). We
|
|
220
|
+
* forward both shapes through to the original.
|
|
221
|
+
*/
|
|
222
|
+
type PgClientQuery = (this: unknown, config: PgQueryArg, values?: unknown, callback?: unknown) => unknown;
|
|
223
|
+
interface PgClientCtor {
|
|
224
|
+
prototype: {
|
|
225
|
+
query: PgClientQuery;
|
|
226
|
+
_ezlogsPatched?: boolean;
|
|
227
|
+
};
|
|
228
|
+
}
|
|
229
|
+
interface PgModule {
|
|
230
|
+
Client: PgClientCtor;
|
|
231
|
+
}
|
|
232
|
+
/**
|
|
233
|
+
* Patch `pg.Client.prototype.query` to inject SET LOCAL for the
|
|
234
|
+
* current request's actor + correlation. Idempotent.
|
|
235
|
+
*
|
|
236
|
+
* Pass the customer's `pg` module (e.g. `import * as pg from "pg"; ezlogs.init({patchPgClient: pg})`)
|
|
237
|
+
* so we patch the instance the customer's code is using. Importing
|
|
238
|
+
* `pg` from inside the agent could pick up a *different* copy on
|
|
239
|
+
* monorepos and the patch wouldn't take effect.
|
|
240
|
+
*/
|
|
241
|
+
declare function patchPgClient(pgModule: PgModule): void;
|
|
242
|
+
|
|
243
|
+
export { type AuditRow, type DatabaseContextSnapshot, type Detected, type PgLikeClient, type SqlExecutor, applyDatabaseContext, buildTrackingSql, currentAuditSnapshot, detectEngine, detectTriggerTrackedTables, emitAuditRows, flushAuditLog, getDatabaseContext, parseArgs, patchPgClient, readAuditRows, runInstall, runWithAuditSnapshotScope, takeAuditSnapshot, withDatabaseContext };
|
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
interface ParsedArgs {
|
|
2
|
+
connection: string | null;
|
|
3
|
+
tables: string[];
|
|
4
|
+
/**
|
|
5
|
+
* Auto-detect mode. True when the user passes no `--tables=` flag or
|
|
6
|
+
* explicitly passes `--tables=auto`. The CLI then introspects
|
|
7
|
+
* `information_schema` and tracks every business table in the public
|
|
8
|
+
* schema, minus a built-in infrastructure skip list.
|
|
9
|
+
*/
|
|
10
|
+
autoTables: boolean;
|
|
11
|
+
print: boolean;
|
|
12
|
+
help: boolean;
|
|
13
|
+
}
|
|
14
|
+
declare function parseArgs(argv: string[]): ParsedArgs;
|
|
15
|
+
type Detected = {
|
|
16
|
+
engine: "postgres";
|
|
17
|
+
} | {
|
|
18
|
+
engine: "mysql";
|
|
19
|
+
} | {
|
|
20
|
+
engine: "planetscale";
|
|
21
|
+
} | {
|
|
22
|
+
engine: "unknown";
|
|
23
|
+
};
|
|
24
|
+
declare function detectEngine(connection: string | null): Detected;
|
|
25
|
+
declare function buildTrackingSql(tables: string[], engine: "postgres" | "mysql"): string;
|
|
26
|
+
interface RunOptions {
|
|
27
|
+
/** Async exec — caller passes a function that runs SQL against their DB. */
|
|
28
|
+
exec?: (sql: string) => Promise<unknown>;
|
|
29
|
+
/**
|
|
30
|
+
* Async query — returns `{ rows: ... }` (matches `pg`'s shape).
|
|
31
|
+
* Required for `--tables=auto` so we can introspect the schema before
|
|
32
|
+
* building the tracking SQL. Tests inject. The CLI shim wires this
|
|
33
|
+
* with `pg.Client.prototype.query`.
|
|
34
|
+
*/
|
|
35
|
+
query?: (sql: string) => Promise<{
|
|
36
|
+
rows: Array<{
|
|
37
|
+
table_name: string;
|
|
38
|
+
}>;
|
|
39
|
+
}>;
|
|
40
|
+
/** Output sink. Defaults to console.log. Tests inject. */
|
|
41
|
+
out?: (line: string) => void;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Programmatic entry. Returns 0 on success, non-zero on failure.
|
|
45
|
+
* Tests call this with a stubbed `exec`. The real CLI binary
|
|
46
|
+
* (`bin/install.cjs`) wraps this with a `pg`-backed exec.
|
|
47
|
+
*/
|
|
48
|
+
declare function runInstall(args: ParsedArgs, options?: RunOptions): Promise<number>;
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Minimal SQL executor shape. Anything that can `await fn(sql, params)`
|
|
52
|
+
* works — we deliberately don't depend on any specific driver type.
|
|
53
|
+
*
|
|
54
|
+
* `params` is positional Postgres-style (`$1`, `$2`, …). The result
|
|
55
|
+
* is ignored (we don't inspect it) so the return type is `unknown`.
|
|
56
|
+
*/
|
|
57
|
+
type SqlExecutor = (sql: string, params: ReadonlyArray<unknown>) => Promise<unknown>;
|
|
58
|
+
/**
|
|
59
|
+
* Snapshot of the values the trigger needs to see on the current
|
|
60
|
+
* transaction. Both fields are nullable — there's no guarantee a
|
|
61
|
+
* given request has either resolved by the time the customer's
|
|
62
|
+
* mutation runs.
|
|
63
|
+
*
|
|
64
|
+
* Returned as a primitive so customers on ORMs whose APIs don't fit
|
|
65
|
+
* the `(sql, params)` shape (Drizzle's tagged-template `sql` builder,
|
|
66
|
+
* Prisma's `$executeRaw`, postgres.js's `sql\`...\``) can compose
|
|
67
|
+
* the SET statement against their own query primitive without going
|
|
68
|
+
* through `applyDatabaseContext`.
|
|
69
|
+
*/
|
|
70
|
+
interface DatabaseContextSnapshot {
|
|
71
|
+
actorId: string | null;
|
|
72
|
+
correlationId: string | null;
|
|
73
|
+
}
|
|
74
|
+
declare function getDatabaseContext(): DatabaseContextSnapshot;
|
|
75
|
+
/**
|
|
76
|
+
* Runs `SELECT set_config('ezlogs.actor_id', $1, true)` and the
|
|
77
|
+
* matching correlation id call against `exec`.
|
|
78
|
+
*
|
|
79
|
+
* `is_local = true` scopes the setting to the current transaction —
|
|
80
|
+
* required for PgBouncer-pooled deployments (Supabase, Neon, Vercel
|
|
81
|
+
* Postgres) where the connection is shared between requests.
|
|
82
|
+
*
|
|
83
|
+
* The caller MUST be inside an explicit transaction when calling
|
|
84
|
+
* this. Outside a transaction, `set_config(_, _, true)` is a no-op
|
|
85
|
+
* (Postgres has nothing to scope to) and the trigger reads NULL.
|
|
86
|
+
*
|
|
87
|
+
* No-ops (skips the SQL entirely) when both actor and correlation
|
|
88
|
+
* are absent — saves two round-trips for un-instrumented callers.
|
|
89
|
+
*/
|
|
90
|
+
declare function applyDatabaseContext(exec: SqlExecutor): Promise<void>;
|
|
91
|
+
/**
|
|
92
|
+
* `pg`-style client: anything that accepts `client.query(sql)` /
|
|
93
|
+
* `client.query(sql, params)` and returns a Promise. Both
|
|
94
|
+
* `pg.Client` and `pg.PoolClient` match. Drizzle's `db.execute` and
|
|
95
|
+
* Prisma's `tx.$executeRawUnsafe` don't fit this shape directly —
|
|
96
|
+
* those callers should use `applyDatabaseContext` inside their own
|
|
97
|
+
* `db.transaction(...)` callback instead.
|
|
98
|
+
*/
|
|
99
|
+
interface PgLikeClient {
|
|
100
|
+
query(sql: string, params?: ReadonlyArray<unknown>): Promise<unknown>;
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* Convenience wrapper: opens BEGIN on a `pg`-style client, applies
|
|
104
|
+
* the current request's actor/correlation as session-local GUCs,
|
|
105
|
+
* runs `callback`, then COMMIT. ROLLBACK on any thrown error.
|
|
106
|
+
*
|
|
107
|
+
* Use this when your code path doesn't already have a transaction
|
|
108
|
+
* (e.g., a Server Action that does a single mutation). For code
|
|
109
|
+
* already inside `db.transaction(async tx => ...)`, call
|
|
110
|
+
* `applyDatabaseContext(tx-exec-fn)` at the top of the callback
|
|
111
|
+
* instead — wrapping a transaction in another transaction is an
|
|
112
|
+
* error in Postgres.
|
|
113
|
+
*
|
|
114
|
+
* The callback receives the same client back so the customer can
|
|
115
|
+
* issue their reads/writes against the in-flight transaction.
|
|
116
|
+
*/
|
|
117
|
+
declare function withDatabaseContext<T>(client: PgLikeClient, callback: (client: PgLikeClient) => Promise<T>): Promise<T>;
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* Shape of one row returned by the audit-log SELECT. Matches the
|
|
121
|
+
* column list in `00_install.sql` exactly. Drivers vary on how they
|
|
122
|
+
* deserialize jsonb (`pg` returns plain objects; some serverless
|
|
123
|
+
* drivers return strings) — `coerceJsonb` below handles both.
|
|
124
|
+
*/
|
|
125
|
+
interface AuditRow {
|
|
126
|
+
table_name: string;
|
|
127
|
+
op: "INSERT" | "UPDATE" | "DELETE";
|
|
128
|
+
old_row: Record<string, unknown> | string | null;
|
|
129
|
+
new_row: Record<string, unknown> | string | null;
|
|
130
|
+
resource_id: string | null;
|
|
131
|
+
}
|
|
132
|
+
/**
|
|
133
|
+
* Fetch audit rows tagged with `correlationId` in capture order.
|
|
134
|
+
*
|
|
135
|
+
* Returns rows oldest-first (matches the trigger's `clock_timestamp`
|
|
136
|
+
* within a transaction) so the dashboard renders them chronologically.
|
|
137
|
+
*
|
|
138
|
+
* Errors are caught and returned as `[]` — a failed audit read must
|
|
139
|
+
* never break the host request. The error is logged at debug.
|
|
140
|
+
*/
|
|
141
|
+
declare function readAuditRows(exec: SqlExecutor, correlationId: string,
|
|
142
|
+
/**
|
|
143
|
+
* Snapshot of `MAX(id)` taken at the start of the request. Used as
|
|
144
|
+
* the lower bound for the time-window fallback path that catches
|
|
145
|
+
* rows whose `correlation_id` is NULL — i.e., supabase-js writes
|
|
146
|
+
* that didn't go through SET LOCAL because PostgREST doesn't
|
|
147
|
+
* expose explicit transactions to the client.
|
|
148
|
+
*
|
|
149
|
+
* When null, the reader falls back to correlation-only matching
|
|
150
|
+
* (Phase 5 primary path).
|
|
151
|
+
*/
|
|
152
|
+
snapshotMaxId?: bigint | null): Promise<AuditRow[]>;
|
|
153
|
+
/**
|
|
154
|
+
* Take a snapshot of the current `MAX(id)` from `ezlogs_audit_log` and
|
|
155
|
+
* store it on the per-request scope. Called at the start of each HTTP
|
|
156
|
+
* request when `databaseReader` is configured. The reader's time-window
|
|
157
|
+
* fallback uses this as the lower bound for catching supabase-js writes
|
|
158
|
+
* (rows whose `correlation_id` is NULL because PostgREST didn't run
|
|
159
|
+
* inside our explicit transaction).
|
|
160
|
+
*
|
|
161
|
+
* Errors are swallowed — a failed snapshot just means the time-window
|
|
162
|
+
* fallback degrades to "match correlation_id only" for this request.
|
|
163
|
+
* Never break the host's request over a bookkeeping query.
|
|
164
|
+
*/
|
|
165
|
+
declare function takeAuditSnapshot(exec: SqlExecutor): Promise<void>;
|
|
166
|
+
/**
|
|
167
|
+
* Detect which tables have the `ezlogs_audit` trigger attached. Used
|
|
168
|
+
* by the per-ORM adapters to decide whether their per-mutation emit
|
|
169
|
+
* is redundant (the audit reader will surface the same write with
|
|
170
|
+
* full old/new state) or needs to fire (table isn't tracked, the
|
|
171
|
+
* adapter is the only path that captures it).
|
|
172
|
+
*
|
|
173
|
+
* Read once at agent startup. The result is a Set of table names —
|
|
174
|
+
* we don't read the schema, since `ezlogs_track` only attaches to
|
|
175
|
+
* `public.<table>` and the customer's mutations resolve through the
|
|
176
|
+
* default search_path the same way.
|
|
177
|
+
*
|
|
178
|
+
* Returns null on failure. Callers treat null as "detection unknown,
|
|
179
|
+
* fall back to original suppress-all behavior" — that's the
|
|
180
|
+
* conservative choice: silently double-emitting for trigger-tracked
|
|
181
|
+
* tables is worse than missing capture for an untracked one, because
|
|
182
|
+
* detection failure usually means the trigger install itself isn't
|
|
183
|
+
* complete and there's nothing to read anyway.
|
|
184
|
+
*/
|
|
185
|
+
declare function detectTriggerTrackedTables(exec: SqlExecutor): Promise<Set<string> | null>;
|
|
186
|
+
/**
|
|
187
|
+
* Push every fetched row into the existing `emitDbEvent` pipeline.
|
|
188
|
+
* Public so tests and advanced customers can call it directly.
|
|
189
|
+
*/
|
|
190
|
+
declare function emitAuditRows(rows: ReadonlyArray<AuditRow>): void;
|
|
191
|
+
/**
|
|
192
|
+
* End-of-request entry point. Reads rows for the current correlation
|
|
193
|
+
* id and emits each one. Skips when no correlation is in scope (no
|
|
194
|
+
* way to match rows back to this request) or no exec is supplied.
|
|
195
|
+
*
|
|
196
|
+
* The HTTP capturers call this after the user's handler returns,
|
|
197
|
+
* before they push the HTTP event itself, so DB events arrive
|
|
198
|
+
* grouped under the same correlation as the HTTP card.
|
|
199
|
+
*/
|
|
200
|
+
declare function flushAuditLog(exec: SqlExecutor | null | undefined): Promise<void>;
|
|
201
|
+
|
|
202
|
+
/** Read the current request's audit snapshot, if any. */
|
|
203
|
+
declare function currentAuditSnapshot(): bigint | null;
|
|
204
|
+
/** Run `callback` inside a fresh audit-snapshot scope. */
|
|
205
|
+
declare function runWithAuditSnapshotScope<R>(callback: () => R): R;
|
|
206
|
+
|
|
207
|
+
interface PgQueryConfig {
|
|
208
|
+
text?: string;
|
|
209
|
+
name?: string;
|
|
210
|
+
values?: unknown[];
|
|
211
|
+
rowMode?: string;
|
|
212
|
+
types?: unknown;
|
|
213
|
+
submit?: unknown;
|
|
214
|
+
[key: string]: unknown;
|
|
215
|
+
}
|
|
216
|
+
type PgQueryArg = string | PgQueryConfig;
|
|
217
|
+
/**
|
|
218
|
+
* Minimal shape of `pg.Client.prototype.query`. The real signature
|
|
219
|
+
* is overloaded across (text, values?, cb?) and (config, cb?). We
|
|
220
|
+
* forward both shapes through to the original.
|
|
221
|
+
*/
|
|
222
|
+
type PgClientQuery = (this: unknown, config: PgQueryArg, values?: unknown, callback?: unknown) => unknown;
|
|
223
|
+
interface PgClientCtor {
|
|
224
|
+
prototype: {
|
|
225
|
+
query: PgClientQuery;
|
|
226
|
+
_ezlogsPatched?: boolean;
|
|
227
|
+
};
|
|
228
|
+
}
|
|
229
|
+
interface PgModule {
|
|
230
|
+
Client: PgClientCtor;
|
|
231
|
+
}
|
|
232
|
+
/**
|
|
233
|
+
* Patch `pg.Client.prototype.query` to inject SET LOCAL for the
|
|
234
|
+
* current request's actor + correlation. Idempotent.
|
|
235
|
+
*
|
|
236
|
+
* Pass the customer's `pg` module (e.g. `import * as pg from "pg"; ezlogs.init({patchPgClient: pg})`)
|
|
237
|
+
* so we patch the instance the customer's code is using. Importing
|
|
238
|
+
* `pg` from inside the agent could pick up a *different* copy on
|
|
239
|
+
* monorepos and the patch wouldn't take effect.
|
|
240
|
+
*/
|
|
241
|
+
declare function patchPgClient(pgModule: PgModule): void;
|
|
242
|
+
|
|
243
|
+
export { type AuditRow, type DatabaseContextSnapshot, type Detected, type PgLikeClient, type SqlExecutor, applyDatabaseContext, buildTrackingSql, currentAuditSnapshot, detectEngine, detectTriggerTrackedTables, emitAuditRows, flushAuditLog, getDatabaseContext, parseArgs, patchPgClient, readAuditRows, runInstall, runWithAuditSnapshotScope, takeAuditSnapshot, withDatabaseContext };
|