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.
Files changed (59) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +779 -0
  3. package/bin/install-triggers.cjs +75 -0
  4. package/dist/actors/index.cjs +111 -0
  5. package/dist/actors/index.d.cts +52 -0
  6. package/dist/actors/index.d.ts +52 -0
  7. package/dist/actors/index.js +107 -0
  8. package/dist/configuration-D9x9Gvds.d.cts +190 -0
  9. package/dist/configuration-D9x9Gvds.d.ts +190 -0
  10. package/dist/db/drizzle.cjs +898 -0
  11. package/dist/db/drizzle.d.cts +68 -0
  12. package/dist/db/drizzle.d.ts +68 -0
  13. package/dist/db/drizzle.js +893 -0
  14. package/dist/db/prisma.cjs +826 -0
  15. package/dist/db/prisma.d.cts +3 -0
  16. package/dist/db/prisma.d.ts +3 -0
  17. package/dist/db/prisma.js +824 -0
  18. package/dist/db/supabase.cjs +1027 -0
  19. package/dist/db/supabase.d.cts +32 -0
  20. package/dist/db/supabase.d.ts +32 -0
  21. package/dist/db/supabase.js +1024 -0
  22. package/dist/index.cjs +3329 -0
  23. package/dist/index.d.cts +305 -0
  24. package/dist/index.d.ts +305 -0
  25. package/dist/index.js +3317 -0
  26. package/dist/jobs/bullmq.cjs +624 -0
  27. package/dist/jobs/bullmq.d.cts +33 -0
  28. package/dist/jobs/bullmq.d.ts +33 -0
  29. package/dist/jobs/bullmq.js +621 -0
  30. package/dist/jobs/inngest.cjs +645 -0
  31. package/dist/jobs/inngest.d.cts +21 -0
  32. package/dist/jobs/inngest.d.ts +21 -0
  33. package/dist/jobs/inngest.js +642 -0
  34. package/dist/jobs/supabase-queues.cjs +661 -0
  35. package/dist/jobs/supabase-queues.d.cts +37 -0
  36. package/dist/jobs/supabase-queues.d.ts +37 -0
  37. package/dist/jobs/supabase-queues.js +657 -0
  38. package/dist/jobs/trigger.cjs +622 -0
  39. package/dist/jobs/trigger.d.cts +46 -0
  40. package/dist/jobs/trigger.d.ts +46 -0
  41. package/dist/jobs/trigger.js +619 -0
  42. package/dist/jobs/upstash-workflow.cjs +673 -0
  43. package/dist/jobs/upstash-workflow.d.cts +57 -0
  44. package/dist/jobs/upstash-workflow.d.ts +57 -0
  45. package/dist/jobs/upstash-workflow.js +669 -0
  46. package/dist/nextjs-plugin/index.cjs +232 -0
  47. package/dist/nextjs-plugin/index.d.cts +68 -0
  48. package/dist/nextjs-plugin/index.d.ts +68 -0
  49. package/dist/nextjs-plugin/index.js +229 -0
  50. package/dist/nextjs-plugin/loader.cjs +16248 -0
  51. package/dist/nextjs-plugin/loader.d.cts +61 -0
  52. package/dist/nextjs-plugin/loader.d.ts +61 -0
  53. package/dist/nextjs-plugin/loader.js +16242 -0
  54. package/dist/triggers/index.cjs +1354 -0
  55. package/dist/triggers/index.d.cts +243 -0
  56. package/dist/triggers/index.d.ts +243 -0
  57. package/dist/triggers/index.js +1337 -0
  58. package/package.json +150 -0
  59. 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 };