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,75 @@
1
+ #!/usr/bin/env node
2
+ // CLI shim for `npx ezlogs-nextjs install-triggers`.
3
+ //
4
+ // Lazy-imports the dist CJS bundle + `pg` so we don't load either when
5
+ // the customer is just installing the package. `pg` is a devDependency
6
+ // of the agent for tests; in customer projects it's expected to be
7
+ // present transitively (drizzle-orm, prisma, etc. all pull it in) or
8
+ // the customer can install it explicitly. We don't list it as a peer
9
+ // because the only path that needs it is this CLI.
10
+ //
11
+ // Exits non-zero on any install failure so CI scripts can catch it.
12
+
13
+ (async () => {
14
+ const { runInstall, parseArgs } = require("../dist/triggers/index.cjs");
15
+
16
+ const argv = process.argv.slice(2);
17
+ const args = parseArgs(argv);
18
+
19
+ // For --help / --print / unknown-engine paths the programmatic entry
20
+ // doesn't need a real exec. Forward without a connection.
21
+ if (args.help || args.print) {
22
+ const code = await runInstall(args, { out: (l) => console.log(l) });
23
+ process.exit(code);
24
+ }
25
+
26
+ let pg;
27
+ try {
28
+ pg = require("pg");
29
+ } catch {
30
+ console.error(
31
+ "[ezlogs] install-triggers needs `pg` installed in your project " +
32
+ "(it ships as a devDependency of the agent itself, not a peer). " +
33
+ "Run `npm install --save-dev pg` and try again, or run with " +
34
+ "--print and pipe the SQL into your own tool.",
35
+ );
36
+ process.exit(1);
37
+ }
38
+
39
+ if (!args.connection) {
40
+ console.error(
41
+ "[ezlogs] No connection string. Pass --connection=<url> or set " +
42
+ "DATABASE_URL / POSTGRES_URL.",
43
+ );
44
+ process.exit(1);
45
+ }
46
+
47
+ const client = new pg.Client({ connectionString: args.connection });
48
+ try {
49
+ await client.connect();
50
+ } catch (err) {
51
+ console.error(
52
+ `[ezlogs] Could not connect to ${args.connection}: ${err.message}`,
53
+ );
54
+ process.exit(1);
55
+ }
56
+
57
+ let exitCode = 1;
58
+ try {
59
+ exitCode = await runInstall(args, {
60
+ out: (l) => console.log(l),
61
+ exec: (sql) => client.query(sql),
62
+ query: (sql) => client.query(sql),
63
+ });
64
+ } finally {
65
+ try {
66
+ await client.end();
67
+ } catch {
68
+ /* ignore */
69
+ }
70
+ }
71
+ process.exit(exitCode);
72
+ })().catch((err) => {
73
+ console.error(`[ezlogs] install-triggers failed: ${err && err.message}`);
74
+ process.exit(1);
75
+ });
@@ -0,0 +1,111 @@
1
+ 'use strict';
2
+
3
+ // src/logger.ts
4
+ var LEVEL_RANK = {
5
+ debug: 10,
6
+ info: 20,
7
+ warn: 30,
8
+ error: 40,
9
+ silent: 100
10
+ };
11
+ var LEVEL_KEY = /* @__PURE__ */ Symbol.for("ezlogs-nextjs:log-level");
12
+ function readLevel() {
13
+ const g = globalThis;
14
+ return g[LEVEL_KEY] ?? "warn";
15
+ }
16
+ function shouldLog(level) {
17
+ return LEVEL_RANK[level] >= LEVEL_RANK[readLevel()];
18
+ }
19
+ function safeWrite(level, message) {
20
+ try {
21
+ if (!shouldLog(level)) return;
22
+ const line = `[ezlogs] ${message}`;
23
+ if (level === "error" || level === "warn") {
24
+ console.error(line);
25
+ } else {
26
+ console.log(line);
27
+ }
28
+ } catch {
29
+ }
30
+ }
31
+ var logger = {
32
+ debug: (message) => safeWrite("debug", message),
33
+ info: (message) => safeWrite("info", message),
34
+ warn: (message) => safeWrite("warn", message),
35
+ error: (message) => safeWrite("error", message)
36
+ };
37
+
38
+ // src/actors/clerk.ts
39
+ function clerkActor() {
40
+ return async () => {
41
+ try {
42
+ const specifier = "@clerk/nextjs/server";
43
+ const mod = await Function(
44
+ "s",
45
+ "return import(s)"
46
+ )(specifier);
47
+ if (typeof mod?.auth !== "function") return null;
48
+ const result = await Promise.resolve(mod.auth());
49
+ const userId = result?.userId;
50
+ if (typeof userId !== "string" || userId.length === 0) return null;
51
+ const claims = result?.sessionClaims ?? {};
52
+ const label = typeof claims.email === "string" && claims.email || typeof claims.name === "string" && claims.name || typeof claims.username === "string" && claims.username || void 0;
53
+ return label ? { id: userId, label } : { id: userId };
54
+ } catch (error) {
55
+ logger.debug(
56
+ `clerkActor: extraction failed (${error instanceof Error ? error.message : String(error)})`
57
+ );
58
+ return null;
59
+ }
60
+ };
61
+ }
62
+
63
+ // src/actors/next-auth.ts
64
+ function nextAuthActor(options) {
65
+ return async () => {
66
+ try {
67
+ const specifier = "next-auth/next";
68
+ const mod = await Function(
69
+ "s",
70
+ "return import(s)"
71
+ )(specifier);
72
+ if (typeof mod?.getServerSession !== "function") return null;
73
+ const session = await mod.getServerSession(options.authOptions);
74
+ const user = session?.user;
75
+ if (!user) return null;
76
+ const id = (user.id ?? user.email) || null;
77
+ if (typeof id !== "string" || id.length === 0) return null;
78
+ const label = typeof user.name === "string" && user.name || typeof user.email === "string" && user.email || void 0;
79
+ return label ? { id, label } : { id };
80
+ } catch (error) {
81
+ logger.debug(
82
+ `nextAuthActor: extraction failed (${error instanceof Error ? error.message : String(error)})`
83
+ );
84
+ return null;
85
+ }
86
+ };
87
+ }
88
+
89
+ // src/actors/auth-js.ts
90
+ function authJsActor(options) {
91
+ return async () => {
92
+ try {
93
+ const session = await Promise.resolve(options.auth());
94
+ const user = session?.user;
95
+ if (!user) return null;
96
+ const id = (user.id ?? user.email) || null;
97
+ if (typeof id !== "string" || id.length === 0) return null;
98
+ const label = typeof user.name === "string" && user.name || typeof user.email === "string" && user.email || void 0;
99
+ return label ? { id, label } : { id };
100
+ } catch (error) {
101
+ logger.debug(
102
+ `authJsActor: extraction failed (${error instanceof Error ? error.message : String(error)})`
103
+ );
104
+ return null;
105
+ }
106
+ };
107
+ }
108
+
109
+ exports.authJsActor = authJsActor;
110
+ exports.clerkActor = clerkActor;
111
+ exports.nextAuthActor = nextAuthActor;
@@ -0,0 +1,52 @@
1
+ import { a as ActorFromRequest } from '../configuration-D9x9Gvds.cjs';
2
+
3
+ /**
4
+ * Returns an `ActorFromRequest` that pulls the current user from
5
+ * Clerk's `auth()` helper. Returns null when no user is signed in,
6
+ * when `@clerk/nextjs` isn't installed, or on any internal error.
7
+ *
8
+ * Compose with other extractors when an app uses multiple providers:
9
+ *
10
+ * actorFromRequest: async (req) =>
11
+ * (await clerkActor()(req)) ?? (await nextAuthActor(opts)(req)),
12
+ */
13
+ declare function clerkActor(): ActorFromRequest;
14
+
15
+ interface NextAuthActorOptions {
16
+ /**
17
+ * The same NextAuth config the customer passes to the auth handler
18
+ * (`/api/auth/[...nextauth]/route.ts`). We pass it straight through
19
+ * to `getServerSession`.
20
+ */
21
+ authOptions: unknown;
22
+ }
23
+ /**
24
+ * Returns an `ActorFromRequest` that resolves the current user via
25
+ * `getServerSession(authOptions)`. Returns null on no session, on any
26
+ * thrown error, or when `next-auth` isn't installed.
27
+ */
28
+ declare function nextAuthActor(options: NextAuthActorOptions): ActorFromRequest;
29
+
30
+ interface AuthJsSessionUser {
31
+ id?: string | null;
32
+ email?: string | null;
33
+ name?: string | null;
34
+ }
35
+ interface AuthJsSession {
36
+ user?: AuthJsSessionUser | null;
37
+ }
38
+ interface AuthJsActorOptions {
39
+ /**
40
+ * The user's `auth()` helper from their `auth.ts` config (Auth.js v5+).
41
+ * Called with no arguments; returns the current session or null.
42
+ */
43
+ auth: () => Promise<AuthJsSession | null> | AuthJsSession | null;
44
+ }
45
+ /**
46
+ * Returns an `ActorFromRequest` that resolves the current user via
47
+ * the user-supplied Auth.js v5 `auth()` helper. Returns null on no
48
+ * session or on any thrown error.
49
+ */
50
+ declare function authJsActor(options: AuthJsActorOptions): ActorFromRequest;
51
+
52
+ export { type AuthJsActorOptions, type NextAuthActorOptions, authJsActor, clerkActor, nextAuthActor };
@@ -0,0 +1,52 @@
1
+ import { a as ActorFromRequest } from '../configuration-D9x9Gvds.js';
2
+
3
+ /**
4
+ * Returns an `ActorFromRequest` that pulls the current user from
5
+ * Clerk's `auth()` helper. Returns null when no user is signed in,
6
+ * when `@clerk/nextjs` isn't installed, or on any internal error.
7
+ *
8
+ * Compose with other extractors when an app uses multiple providers:
9
+ *
10
+ * actorFromRequest: async (req) =>
11
+ * (await clerkActor()(req)) ?? (await nextAuthActor(opts)(req)),
12
+ */
13
+ declare function clerkActor(): ActorFromRequest;
14
+
15
+ interface NextAuthActorOptions {
16
+ /**
17
+ * The same NextAuth config the customer passes to the auth handler
18
+ * (`/api/auth/[...nextauth]/route.ts`). We pass it straight through
19
+ * to `getServerSession`.
20
+ */
21
+ authOptions: unknown;
22
+ }
23
+ /**
24
+ * Returns an `ActorFromRequest` that resolves the current user via
25
+ * `getServerSession(authOptions)`. Returns null on no session, on any
26
+ * thrown error, or when `next-auth` isn't installed.
27
+ */
28
+ declare function nextAuthActor(options: NextAuthActorOptions): ActorFromRequest;
29
+
30
+ interface AuthJsSessionUser {
31
+ id?: string | null;
32
+ email?: string | null;
33
+ name?: string | null;
34
+ }
35
+ interface AuthJsSession {
36
+ user?: AuthJsSessionUser | null;
37
+ }
38
+ interface AuthJsActorOptions {
39
+ /**
40
+ * The user's `auth()` helper from their `auth.ts` config (Auth.js v5+).
41
+ * Called with no arguments; returns the current session or null.
42
+ */
43
+ auth: () => Promise<AuthJsSession | null> | AuthJsSession | null;
44
+ }
45
+ /**
46
+ * Returns an `ActorFromRequest` that resolves the current user via
47
+ * the user-supplied Auth.js v5 `auth()` helper. Returns null on no
48
+ * session or on any thrown error.
49
+ */
50
+ declare function authJsActor(options: AuthJsActorOptions): ActorFromRequest;
51
+
52
+ export { type AuthJsActorOptions, type NextAuthActorOptions, authJsActor, clerkActor, nextAuthActor };
@@ -0,0 +1,107 @@
1
+ // src/logger.ts
2
+ var LEVEL_RANK = {
3
+ debug: 10,
4
+ info: 20,
5
+ warn: 30,
6
+ error: 40,
7
+ silent: 100
8
+ };
9
+ var LEVEL_KEY = /* @__PURE__ */ Symbol.for("ezlogs-nextjs:log-level");
10
+ function readLevel() {
11
+ const g = globalThis;
12
+ return g[LEVEL_KEY] ?? "warn";
13
+ }
14
+ function shouldLog(level) {
15
+ return LEVEL_RANK[level] >= LEVEL_RANK[readLevel()];
16
+ }
17
+ function safeWrite(level, message) {
18
+ try {
19
+ if (!shouldLog(level)) return;
20
+ const line = `[ezlogs] ${message}`;
21
+ if (level === "error" || level === "warn") {
22
+ console.error(line);
23
+ } else {
24
+ console.log(line);
25
+ }
26
+ } catch {
27
+ }
28
+ }
29
+ var logger = {
30
+ debug: (message) => safeWrite("debug", message),
31
+ info: (message) => safeWrite("info", message),
32
+ warn: (message) => safeWrite("warn", message),
33
+ error: (message) => safeWrite("error", message)
34
+ };
35
+
36
+ // src/actors/clerk.ts
37
+ function clerkActor() {
38
+ return async () => {
39
+ try {
40
+ const specifier = "@clerk/nextjs/server";
41
+ const mod = await Function(
42
+ "s",
43
+ "return import(s)"
44
+ )(specifier);
45
+ if (typeof mod?.auth !== "function") return null;
46
+ const result = await Promise.resolve(mod.auth());
47
+ const userId = result?.userId;
48
+ if (typeof userId !== "string" || userId.length === 0) return null;
49
+ const claims = result?.sessionClaims ?? {};
50
+ const label = typeof claims.email === "string" && claims.email || typeof claims.name === "string" && claims.name || typeof claims.username === "string" && claims.username || void 0;
51
+ return label ? { id: userId, label } : { id: userId };
52
+ } catch (error) {
53
+ logger.debug(
54
+ `clerkActor: extraction failed (${error instanceof Error ? error.message : String(error)})`
55
+ );
56
+ return null;
57
+ }
58
+ };
59
+ }
60
+
61
+ // src/actors/next-auth.ts
62
+ function nextAuthActor(options) {
63
+ return async () => {
64
+ try {
65
+ const specifier = "next-auth/next";
66
+ const mod = await Function(
67
+ "s",
68
+ "return import(s)"
69
+ )(specifier);
70
+ if (typeof mod?.getServerSession !== "function") return null;
71
+ const session = await mod.getServerSession(options.authOptions);
72
+ const user = session?.user;
73
+ if (!user) return null;
74
+ const id = (user.id ?? user.email) || null;
75
+ if (typeof id !== "string" || id.length === 0) return null;
76
+ const label = typeof user.name === "string" && user.name || typeof user.email === "string" && user.email || void 0;
77
+ return label ? { id, label } : { id };
78
+ } catch (error) {
79
+ logger.debug(
80
+ `nextAuthActor: extraction failed (${error instanceof Error ? error.message : String(error)})`
81
+ );
82
+ return null;
83
+ }
84
+ };
85
+ }
86
+
87
+ // src/actors/auth-js.ts
88
+ function authJsActor(options) {
89
+ return async () => {
90
+ try {
91
+ const session = await Promise.resolve(options.auth());
92
+ const user = session?.user;
93
+ if (!user) return null;
94
+ const id = (user.id ?? user.email) || null;
95
+ if (typeof id !== "string" || id.length === 0) return null;
96
+ const label = typeof user.name === "string" && user.name || typeof user.email === "string" && user.email || void 0;
97
+ return label ? { id, label } : { id };
98
+ } catch (error) {
99
+ logger.debug(
100
+ `authJsActor: extraction failed (${error instanceof Error ? error.message : String(error)})`
101
+ );
102
+ return null;
103
+ }
104
+ };
105
+ }
106
+
107
+ export { authJsActor, clerkActor, nextAuthActor };
@@ -0,0 +1,190 @@
1
+ /**
2
+ * Internal logger for the agent.
3
+ *
4
+ * Mirrors EzLogsAgent::Logger: prefixed messages, `:warn` default level,
5
+ * never throws. The host app must never see an exception from logging.
6
+ */
7
+ type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
8
+
9
+ /**
10
+ * Configuration mirrors EzLogsAgent::Configuration.
11
+ *
12
+ * Defaults match Ruby exactly. User-supplied excluded* arrays are MERGED with
13
+ * the DEFAULT_* constants via the `all*` getters — same semantics as
14
+ * Ruby's `all_excluded_paths`, `all_excluded_tables`, etc.
15
+ *
16
+ * Public surface is intentionally narrow. Anything not in InitOptions is
17
+ * not configurable.
18
+ */
19
+
20
+ interface ActorContext {
21
+ /** Stable identifier for the user (e.g. `user.id`). REQUIRED. */
22
+ id: string;
23
+ /** Human-readable label (e.g. `user.email`). Optional. */
24
+ label?: string;
25
+ }
26
+ /**
27
+ * Minimal request-shape contract for `actorFromRequest`. We don't import
28
+ * Next.js types here to keep the package framework-light; users pass
29
+ * whatever request object they're given by the runtime.
30
+ *
31
+ * The hook may return a value or a Promise — Phase 4 actor extractors
32
+ * (Clerk, NextAuth, Auth.js) are async because they call into the
33
+ * framework's auth helpers, which lazy-import the SDK.
34
+ */
35
+ type ActorFromRequest = (request: unknown) => ActorContext | null | undefined | Promise<ActorContext | null | undefined>;
36
+ /**
37
+ * Resolver for a display name. Either:
38
+ * - a column name on the row (e.g. "name"), or
39
+ * - a function that returns a string from the row (e.g.
40
+ * `(row) => \`${row.first_name} ${row.last_name}\``).
41
+ *
42
+ * Functions let users compose names from multiple columns when no
43
+ * single field is sufficient. Resolver functions are invoked inside a
44
+ * try/catch — a thrown resolver collapses to "no display name" so a
45
+ * buggy resolver can never crash the host application.
46
+ */
47
+ type DisplayNameResolver = string | ((row: Record<string, unknown>) => string | null | undefined);
48
+ /**
49
+ * Maps a model class name → resolver used to derive the human-readable
50
+ * display value, mirroring Ruby's `display_name_for`.
51
+ */
52
+ type DisplayNameMap = Record<string, DisplayNameResolver>;
53
+ /**
54
+ * Classifier for Server Action failure return values.
55
+ *
56
+ * Many Next.js codebases (next-safe-action templates, the
57
+ * Vercel App Router examples, tRPC) catch errors inside the action and
58
+ * return `{ success: false, error: "..." }` instead of throwing. The
59
+ * HTTP response is 200, so the agent can't tell the action failed
60
+ * without inspecting the return value.
61
+ *
62
+ * If this classifier returns true the event is recorded as a failure
63
+ * with the supplied `errorMessage`. A thrown classifier or one that
64
+ * returns undefined is treated as "no opinion" — the default heuristic
65
+ * (`{ success: false, error: <truthy string> }`) still applies.
66
+ *
67
+ * @param result the value the Server Action returned
68
+ * @returns true / failure descriptor when the result represents a
69
+ * failure, false / undefined otherwise
70
+ */
71
+ type ServerActionErrorClassifier = (result: unknown) => boolean | {
72
+ errorMessage: string;
73
+ } | null | undefined;
74
+ interface InitOptions {
75
+ /** Defaults to `https://app.ezlogs.io` (the hosted EZLogs service). Override for self-hosting. */
76
+ serverUrl?: string;
77
+ projectToken: string;
78
+ captureHttp?: boolean;
79
+ captureDb?: boolean;
80
+ captureJobs?: boolean;
81
+ bufferSize?: number;
82
+ /** Send interval in milliseconds. Ruby uses seconds (3); Node uses ms (3000). */
83
+ sendInterval?: number;
84
+ retryAttempts?: number;
85
+ excludedPaths?: string[];
86
+ excludedTables?: string[];
87
+ excludedJobClasses?: string[];
88
+ excludedGraphqlOperations?: string[];
89
+ excludedGraphqlVariableKeys?: string[];
90
+ actorFromRequest?: ActorFromRequest;
91
+ displayNameFor?: DisplayNameMap;
92
+ /**
93
+ * Detect when a Server Action's return value represents a failure.
94
+ * See {@link ServerActionErrorClassifier}. The default heuristic
95
+ * (`{ success: false, error: <string> }`) runs in addition to any
96
+ * classifier you supply.
97
+ */
98
+ isServerActionError?: ServerActionErrorClassifier;
99
+ /** Patch globalThis.fetch to inject X-Correlation-ID. Default true. */
100
+ patchGlobalFetch?: boolean;
101
+ /**
102
+ * When true (default), the HTTP capturer extracts the current actor
103
+ * from the most-recently-constructed Supabase client by calling
104
+ * `.auth.getUser()` once per request. Use the actorFromRequest hook
105
+ * to override or disable. Set to false to skip the extra auth call
106
+ * when you don't use Supabase or want a custom actor source only.
107
+ */
108
+ actorFromSupabase?: boolean;
109
+ /**
110
+ * Trigger-based DB capture path. When set, the HTTP capturers flush
111
+ * `ezlogs_audit_log` rows tagged with the current correlation_id at
112
+ * the end of each request and emit them as `database_callback`
113
+ * events. Run `npx ezlogs-nextjs install-triggers` once per
114
+ * database to set up the audit table + trigger function, then
115
+ * either:
116
+ * - set this option to a function that runs a single SQL
117
+ * statement (e.g. `(sql, params) => pg.query(sql, params)`),
118
+ * - or wrap your mutations in `withDatabaseContext(client, cb)`
119
+ * so the trigger sees the actor + correlation GUCs.
120
+ *
121
+ * `params` is positional Postgres-style (`$1`, `$2`). The result
122
+ * shape can be `{ rows: [...] }` (pg) or a bare array (drizzle's
123
+ * `db.execute`). The agent never inspects the return value.
124
+ */
125
+ databaseReader?: DatabaseReader;
126
+ /**
127
+ * If supplied, the agent monkey-patches `pgModule.Client.prototype.query`
128
+ * at init so every `client.query(...)` (and therefore `pool.query(...)`,
129
+ * which routes through the same Client method) auto-injects
130
+ * `SET LOCAL ezlogs.actor_id` / `ezlogs.correlation_id` for the
131
+ * current request. Without this you'd have to wrap each customer
132
+ * mutation with `getDatabaseContext()` + manual SET statements.
133
+ *
134
+ * Pass the customer's own `pg` import — NOT the agent's — so the
135
+ * patch lands on the same Client class their app code uses (in a
136
+ * monorepo there can be multiple copies of pg).
137
+ *
138
+ * import * as pg from "pg";
139
+ * ezlogs.init({ patchDatabaseClient: pg, databaseReader: ... });
140
+ *
141
+ * Idempotent. The shape is `unknown` so we don't import `pg` types
142
+ * in the configuration module — the actual structural check lives
143
+ * in `patchPgClient`.
144
+ */
145
+ patchDatabaseClient?: unknown;
146
+ /**
147
+ * Time-window fallback for stacks where SET LOCAL can't propagate
148
+ * (supabase-js, PostgREST, anything that auto-commits per request
149
+ * and doesn't expose explicit transactions). When true, the agent
150
+ * runs `SELECT MAX(id) FROM ezlogs_audit_log` at the start of every
151
+ * request and remembers the value. At end of request the reader
152
+ * drains rows whose `correlation_id` matches OR (`correlation_id`
153
+ * is NULL and `id` is greater than the snapshot) — i.e. rows the
154
+ * trigger fired during this request even though the customer's
155
+ * client couldn't tag them.
156
+ *
157
+ * Default false. Enable for supabase-js apps. Adds one cheap
158
+ * `SELECT MAX(id)` per request. See AGENT_PARITY_NOTES.md for the
159
+ * concurrency caveat (concurrent same-actor mutations may blur).
160
+ */
161
+ databaseSnapshotMode?: boolean;
162
+ /**
163
+ * One-line install for the trigger-based capture. Pass your Postgres
164
+ * connection string; the agent does the rest:
165
+ * 1. Lazy-imports `pg` and constructs a Pool (4 connections, max).
166
+ * `pg` must be in your project's dependencies — the agent will
167
+ * log a debug message and skip the trigger path if it's missing.
168
+ * 2. Wires that Pool as `databaseReader` for the audit-log drain.
169
+ * 3. Patches `pg.Client.prototype.query` so every customer query
170
+ * auto-injects SET LOCAL. Drizzle (node-postgres) and Prisma
171
+ * (`@prisma/adapter-pg`) both run on `pg` and inherit zero-touch
172
+ * capture without any extra wiring on the customer's side.
173
+ * 4. Enables `databaseSnapshotMode` — the time-window fallback
174
+ * that catches supabase-js / PostgREST writes whose audit row
175
+ * didn't get our SET LOCAL.
176
+ *
177
+ * Customers who want to override individual pieces can still pass
178
+ * `databaseReader` / `patchDatabaseClient` / `databaseSnapshotMode`
179
+ * directly; explicit values win over the auto-wired pieces.
180
+ */
181
+ databaseUrl?: string;
182
+ logLevel?: LogLevel;
183
+ }
184
+ /**
185
+ * SQL executor for the trigger-based capture path. See `databaseReader`
186
+ * on {@link InitOptions}.
187
+ */
188
+ type DatabaseReader = (sql: string, params: ReadonlyArray<unknown>) => Promise<unknown>;
189
+
190
+ export type { ActorContext as A, DisplayNameMap as D, InitOptions as I, ActorFromRequest as a };