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
package/package.json ADDED
@@ -0,0 +1,150 @@
1
+ {
2
+ "name": "ezlogs-nextjs",
3
+ "version": "0.1.0",
4
+ "description": "EZLogs agent for Next.js — capture HTTP, database, and background-job events as plain-English Action cards.",
5
+ "license": "MIT",
6
+ "author": "EZLogs",
7
+ "homepage": "https://ezlogs.io",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "https://github.com/dezsirazvan/ez_logs_agent_nextjs"
11
+ },
12
+ "bugs": {
13
+ "url": "https://github.com/dezsirazvan/ez_logs_agent_nextjs/issues"
14
+ },
15
+ "type": "module",
16
+ "sideEffects": false,
17
+ "engines": {
18
+ "node": ">=18.17"
19
+ },
20
+ "files": [
21
+ "dist",
22
+ "sql",
23
+ "bin",
24
+ "LICENSE",
25
+ "README.md"
26
+ ],
27
+ "bin": {
28
+ "install-triggers": "./bin/install-triggers.cjs"
29
+ },
30
+ "exports": {
31
+ ".": {
32
+ "types": "./dist/index.d.ts",
33
+ "import": "./dist/index.js",
34
+ "require": "./dist/index.cjs"
35
+ },
36
+ "./prisma": {
37
+ "types": "./dist/db/prisma.d.ts",
38
+ "import": "./dist/db/prisma.js",
39
+ "require": "./dist/db/prisma.cjs"
40
+ },
41
+ "./drizzle": {
42
+ "types": "./dist/db/drizzle.d.ts",
43
+ "import": "./dist/db/drizzle.js",
44
+ "require": "./dist/db/drizzle.cjs"
45
+ },
46
+ "./supabase": {
47
+ "types": "./dist/db/supabase.d.ts",
48
+ "import": "./dist/db/supabase.js",
49
+ "require": "./dist/db/supabase.cjs"
50
+ },
51
+ "./bullmq": {
52
+ "types": "./dist/jobs/bullmq.d.ts",
53
+ "import": "./dist/jobs/bullmq.js",
54
+ "require": "./dist/jobs/bullmq.cjs"
55
+ },
56
+ "./inngest": {
57
+ "types": "./dist/jobs/inngest.d.ts",
58
+ "import": "./dist/jobs/inngest.js",
59
+ "require": "./dist/jobs/inngest.cjs"
60
+ },
61
+ "./trigger": {
62
+ "types": "./dist/jobs/trigger.d.ts",
63
+ "import": "./dist/jobs/trigger.js",
64
+ "require": "./dist/jobs/trigger.cjs"
65
+ },
66
+ "./supabase-queues": {
67
+ "types": "./dist/jobs/supabase-queues.d.ts",
68
+ "import": "./dist/jobs/supabase-queues.js",
69
+ "require": "./dist/jobs/supabase-queues.cjs"
70
+ },
71
+ "./upstash-workflow": {
72
+ "types": "./dist/jobs/upstash-workflow.d.ts",
73
+ "import": "./dist/jobs/upstash-workflow.js",
74
+ "require": "./dist/jobs/upstash-workflow.cjs"
75
+ },
76
+ "./plugin": {
77
+ "types": "./dist/nextjs-plugin/index.d.ts",
78
+ "import": "./dist/nextjs-plugin/index.js",
79
+ "require": "./dist/nextjs-plugin/index.cjs"
80
+ },
81
+ "./actors": {
82
+ "types": "./dist/actors/index.d.ts",
83
+ "import": "./dist/actors/index.js",
84
+ "require": "./dist/actors/index.cjs"
85
+ },
86
+ "./triggers": {
87
+ "types": "./dist/triggers/index.d.ts",
88
+ "import": "./dist/triggers/index.js",
89
+ "require": "./dist/triggers/index.cjs"
90
+ },
91
+ "./sql/postgres/install.sql": "./sql/postgres/00_install.sql"
92
+ },
93
+ "scripts": {
94
+ "build": "tsup",
95
+ "test": "vitest run",
96
+ "test:watch": "vitest",
97
+ "test:parity": "vitest run tests/parity",
98
+ "typecheck": "tsc --noEmit",
99
+ "pack:dry": "npm pack --dry-run"
100
+ },
101
+ "peerDependencies": {
102
+ "@prisma/client": ">=5",
103
+ "@supabase/supabase-js": ">=2",
104
+ "@trigger.dev/sdk": ">=3",
105
+ "@upstash/qstash": ">=2",
106
+ "@upstash/workflow": ">=1",
107
+ "bullmq": ">=4",
108
+ "drizzle-orm": ">=0.30",
109
+ "inngest": ">=3",
110
+ "next": ">=14"
111
+ },
112
+ "peerDependenciesMeta": {
113
+ "@prisma/client": {
114
+ "optional": true
115
+ },
116
+ "@supabase/supabase-js": {
117
+ "optional": true
118
+ },
119
+ "@trigger.dev/sdk": {
120
+ "optional": true
121
+ },
122
+ "@upstash/qstash": {
123
+ "optional": true
124
+ },
125
+ "@upstash/workflow": {
126
+ "optional": true
127
+ },
128
+ "bullmq": {
129
+ "optional": true
130
+ },
131
+ "drizzle-orm": {
132
+ "optional": true
133
+ },
134
+ "inngest": {
135
+ "optional": true
136
+ },
137
+ "next": {
138
+ "optional": true
139
+ }
140
+ },
141
+ "devDependencies": {
142
+ "@types/node": "^20.11.0",
143
+ "@types/pg": "^8.20.0",
144
+ "pg": "^8.20.0",
145
+ "sucrase": "^3.35.0",
146
+ "tsup": "^8.0.2",
147
+ "typescript": "^5.4.0",
148
+ "vitest": "^1.4.0"
149
+ }
150
+ }
@@ -0,0 +1,205 @@
1
+ -- ezlogs-nextjs — Postgres trigger-based change-data-capture install.
2
+ --
3
+ -- Run once per database. Idempotent: safe to re-run after upgrades.
4
+ -- After this, attach the trigger to specific tables with:
5
+ --
6
+ -- SELECT ezlogs_track('users');
7
+ -- SELECT ezlogs_track('orders');
8
+ --
9
+ -- The agent then reads ezlogs_audit_log per request and ships full
10
+ -- OLD/NEW diffs to the EZLogs server, so every UPDATE/DELETE event
11
+ -- in the dashboard carries real before/after values regardless of
12
+ -- which client wrote the row (Drizzle, Supabase, Prisma, raw SQL).
13
+ --
14
+ -- Customers using PgBouncer in transaction-mode pooling (Supabase,
15
+ -- Neon, Vercel Postgres): set ezlogs.actor_id / ezlogs.correlation_id
16
+ -- with `SET LOCAL` inside an explicit transaction. The agent's
17
+ -- `withDatabaseContext` helper does this automatically.
18
+
19
+ -- ---------------------------------------------------------------------
20
+ -- 1. Audit log table — single JSONB-keyed table for all audited tables.
21
+ -- Avoids per-table schema sprawl (Supabase audit-log pattern).
22
+ -- ---------------------------------------------------------------------
23
+
24
+ CREATE TABLE IF NOT EXISTS ezlogs_audit_log (
25
+ id bigserial PRIMARY KEY,
26
+ table_name text NOT NULL,
27
+ op text NOT NULL CHECK (op IN ('INSERT','UPDATE','DELETE')),
28
+ -- old_row is NULL on INSERT; new_row is NULL on DELETE.
29
+ old_row jsonb,
30
+ new_row jsonb,
31
+ -- Stringified resource id for fast lookup. Falls back to NULL when
32
+ -- the row has no `id` column (composite PKs, junction tables).
33
+ resource_id text,
34
+ -- App-supplied context. NULL when the customer's request handler
35
+ -- didn't set them via SET LOCAL — the trigger still fires.
36
+ actor_id text,
37
+ correlation_id text,
38
+ -- Postgres transaction id — groups multiple statements from one
39
+ -- application-level operation.
40
+ txid bigint NOT NULL DEFAULT txid_current(),
41
+ -- clock_timestamp() (real wall time), not transaction_timestamp(),
42
+ -- so rows in the same transaction sort in execution order.
43
+ captured_at timestamptz NOT NULL DEFAULT clock_timestamp()
44
+ );
45
+
46
+ -- Hot-path index: agent reader scans WHERE correlation_id = $current.
47
+ -- Partial index keeps it small — most rows have correlation_id set.
48
+ CREATE INDEX IF NOT EXISTS ezlogs_audit_log_correlation_idx
49
+ ON ezlogs_audit_log (correlation_id, captured_at)
50
+ WHERE correlation_id IS NOT NULL;
51
+
52
+ -- Secondary index for cleanup / retention queries
53
+ -- (DELETE FROM ezlogs_audit_log WHERE captured_at < now() - interval '7 days').
54
+ CREATE INDEX IF NOT EXISTS ezlogs_audit_log_captured_at_idx
55
+ ON ezlogs_audit_log (captured_at);
56
+
57
+ -- ---------------------------------------------------------------------
58
+ -- 2. Generic trigger function — one function audits every table.
59
+ -- No per-table code generation; we introspect via TG_TABLE_NAME and
60
+ -- to_jsonb(NEW)/to_jsonb(OLD) at trigger-fire time.
61
+ -- ---------------------------------------------------------------------
62
+
63
+ CREATE OR REPLACE FUNCTION public.ezlogs_audit_trigger() RETURNS trigger
64
+ LANGUAGE plpgsql
65
+ SECURITY DEFINER -- run as the function owner so triggers fire even
66
+ -- when the caller has narrow privileges
67
+ -- Pin search_path so the function works under any caller context.
68
+ -- Supabase's PostgREST runs requests with `search_path = ''` for
69
+ -- security; without this clause, the unqualified `ezlogs_audit_log`
70
+ -- below would fail with "relation does not exist" and BLOCK the
71
+ -- customer's mutation. The agent must never break the host app.
72
+ -- pg_temp is appended last to keep the recommended Supabase
73
+ -- security-definer pattern.
74
+ SET search_path = public, pg_temp
75
+ AS $$
76
+ DECLARE
77
+ resource_id_value text;
78
+ pk_column_name text;
79
+ BEGIN
80
+ -- The PK column name is passed as a per-trigger argument by
81
+ -- ezlogs_track(). Defaults to 'id' when missing (older installs)
82
+ -- or empty (composite-PK tables — those legitimately have no
83
+ -- single resource id). Per-table hooked at attach time, not
84
+ -- looked up here, so this is a constant-time read.
85
+ pk_column_name := COALESCE(NULLIF(TG_ARGV[0], ''), 'id');
86
+
87
+ -- Prefer NEW's PK value when present (INSERT/UPDATE), fall back to
88
+ -- OLD's (DELETE). `to_jsonb(NEW)->>X` returns NULL when X doesn't
89
+ -- exist or is itself NULL — both are fine for our use.
90
+ resource_id_value := COALESCE(
91
+ (to_jsonb(NEW)->>pk_column_name),
92
+ (to_jsonb(OLD)->>pk_column_name)
93
+ );
94
+
95
+ -- Schema-qualified for double-safety. With search_path pinned above
96
+ -- the unqualified form would also work, but explicit-public removes
97
+ -- one whole class of "unexpected schema in path" failures.
98
+ INSERT INTO public.ezlogs_audit_log (
99
+ table_name, op,
100
+ old_row, new_row,
101
+ resource_id,
102
+ actor_id, correlation_id
103
+ ) VALUES (
104
+ TG_TABLE_NAME, TG_OP,
105
+ CASE WHEN TG_OP = 'INSERT' THEN NULL ELSE to_jsonb(OLD) END,
106
+ CASE WHEN TG_OP = 'DELETE' THEN NULL ELSE to_jsonb(NEW) END,
107
+ resource_id_value,
108
+ -- `current_setting(_, true)` returns NULL when the GUC is unset
109
+ -- (the second arg = missing_ok). Without `true`, an unsignaled
110
+ -- request would raise and roll back the user's mutation — we
111
+ -- never want that.
112
+ --
113
+ -- NULLIF(_, '') normalizes empty strings to NULL. Postgres caches
114
+ -- references to a custom GUC in a session — once any function in
115
+ -- the session has read it, subsequent reads return '' (not NULL)
116
+ -- when the GUC is unset on the next request. The agent reader
117
+ -- treats both as "no actor" — coercing here means downstream
118
+ -- (TS code, dashboard) only has to check one shape.
119
+ NULLIF(current_setting('ezlogs.actor_id', true), ''),
120
+ NULLIF(current_setting('ezlogs.correlation_id', true), '')
121
+ );
122
+
123
+ -- AFTER triggers ignore the return value, but plpgsql requires one.
124
+ -- COALESCE handles INSERT (NEW), UPDATE (NEW), DELETE (OLD).
125
+ RETURN COALESCE(NEW, OLD);
126
+ EXCEPTION
127
+ -- HARD CONTRACT: the agent's audit logic must NEVER break the
128
+ -- customer's mutation. If anything in this trigger raises (audit
129
+ -- log dropped, permissions revoked, disk full, schema drift, etc.)
130
+ -- we swallow it, raise a WARNING for the DBA, and let the user's
131
+ -- INSERT/UPDATE/DELETE proceed. Losing audit data is recoverable;
132
+ -- breaking the customer's app is not.
133
+ WHEN others THEN
134
+ RAISE WARNING '[ezlogs] audit trigger on % failed (continuing): %',
135
+ TG_TABLE_NAME, SQLERRM;
136
+ RETURN COALESCE(NEW, OLD);
137
+ END;
138
+ $$;
139
+
140
+ -- ---------------------------------------------------------------------
141
+ -- 3. ezlogs_track() — attach the trigger to a named table.
142
+ -- Idempotent: drops + recreates so re-running is safe.
143
+ -- ---------------------------------------------------------------------
144
+
145
+ CREATE OR REPLACE FUNCTION public.ezlogs_track(target_table text) RETURNS void
146
+ LANGUAGE plpgsql
147
+ -- Same search_path pin as the trigger function — keeps the helper
148
+ -- working under any caller context (Supabase / PostgREST / locked
149
+ -- down search_path).
150
+ SET search_path = public, pg_temp
151
+ AS $$
152
+ DECLARE
153
+ pk_column_name text;
154
+ BEGIN
155
+ -- Detect the table's single-column primary key so the trigger can
156
+ -- populate `resource_id` correctly regardless of how the customer
157
+ -- named their PK column. Tables whose PK isn't `id` are a normal
158
+ -- pattern: foreign-keyed children, single-table-inheritance, slug
159
+ -- and uuid columns named to match their domain meaning.
160
+ --
161
+ -- We look up the column in the PK constraint via pg_index +
162
+ -- pg_attribute. For composite PKs we leave `pk_column_name` NULL —
163
+ -- there's no single resource id, and `resource_id` stays empty
164
+ -- (which is the correct outcome — those rows aren't a "resource"
165
+ -- in the activity sense; they're a join).
166
+ SELECT a.attname INTO pk_column_name
167
+ FROM pg_index i
168
+ JOIN pg_attribute a ON a.attrelid = i.indrelid
169
+ AND a.attnum = ANY(i.indkey)
170
+ WHERE i.indrelid = format('public.%I', target_table)::regclass
171
+ AND i.indisprimary
172
+ AND array_length(i.indkey, 1) = 1
173
+ LIMIT 1;
174
+
175
+ EXECUTE format(
176
+ 'DROP TRIGGER IF EXISTS ezlogs_audit ON %I', target_table
177
+ );
178
+ -- Pass the resolved PK column name as a literal trigger argument.
179
+ -- format(%L) quotes safely; NULL → 'null'-like which the trigger's
180
+ -- `COALESCE(NULLIF(TG_ARGV[0], ''), 'id')` falls back from to 'id'.
181
+ EXECUTE format(
182
+ 'CREATE TRIGGER ezlogs_audit '
183
+ 'AFTER INSERT OR UPDATE OR DELETE ON %I '
184
+ 'FOR EACH ROW EXECUTE FUNCTION public.ezlogs_audit_trigger(%L)',
185
+ target_table,
186
+ COALESCE(pk_column_name, '')
187
+ );
188
+ END;
189
+ $$;
190
+
191
+ -- ---------------------------------------------------------------------
192
+ -- 4. ezlogs_untrack() — detach the trigger from a named table.
193
+ -- Useful for retiring audited tables without touching the data.
194
+ -- ---------------------------------------------------------------------
195
+
196
+ CREATE OR REPLACE FUNCTION public.ezlogs_untrack(target_table text) RETURNS void
197
+ LANGUAGE plpgsql
198
+ SET search_path = public, pg_temp
199
+ AS $$
200
+ BEGIN
201
+ EXECUTE format(
202
+ 'DROP TRIGGER IF EXISTS ezlogs_audit ON %I', target_table
203
+ );
204
+ END;
205
+ $$;