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,305 @@
1
+ import { I as InitOptions } from './configuration-D9x9Gvds.cjs';
2
+ export { A as ActorContext, a as ActorFromRequest, D as DisplayNameMap } from './configuration-D9x9Gvds.cjs';
3
+
4
+ /**
5
+ * EventBuilder — port of ez_logs_agent/lib/ez_logs_agent/event_builder.rb.
6
+ *
7
+ * This module is the wire-format contract. The Node agent's only correctness
8
+ * requirement is that the JSON it ships matches what the Ruby agent ships
9
+ * for an equivalent invocation, byte-for-byte.
10
+ *
11
+ * KEY ORDERING IS LOAD-BEARING.
12
+ * The output object's top-level keys are emitted in this order:
13
+ * timestamp, source_type, source_data, outcome, correlation_id,
14
+ * resource_ids, context, duration_ms, error_message
15
+ * Do not refactor `build()` to use object spread or computed keys; the
16
+ * parity tests assert deep equality AND key ordering against the Ruby
17
+ * fixtures.
18
+ *
19
+ * Pure, side-effect-free. Validates, sanitizes, returns the event object.
20
+ * Does NOT buffer, ship, or generate correlation IDs.
21
+ */
22
+ type SourceType = "http_request" | "background_job" | "database_callback";
23
+ type Outcome = "success" | "failure";
24
+ interface ResourceId {
25
+ resource_type: string;
26
+ resource_id: string;
27
+ }
28
+ interface Event {
29
+ timestamp: string;
30
+ source_type: SourceType;
31
+ source_data: Record<string, unknown>;
32
+ outcome: Outcome;
33
+ correlation_id: string | null;
34
+ resource_ids: ResourceId[];
35
+ context: Record<string, unknown> | null;
36
+ duration_ms: number | null;
37
+ error_message: string | null;
38
+ }
39
+ interface BuildInput {
40
+ source_type: SourceType | string;
41
+ source_data: Record<string, unknown>;
42
+ outcome: Outcome | string;
43
+ correlation_id?: string | null;
44
+ resource_ids?: ResourceId[];
45
+ context?: Record<string, unknown> | null;
46
+ duration_ms?: number | null;
47
+ error_message?: string | null;
48
+ timestamp?: string | Date | null;
49
+ }
50
+ declare function build(input: BuildInput): Event;
51
+ /**
52
+ * Mirrors Ruby's ArgumentError. Thrown for any validation failure during
53
+ * `build()`. Callers in capturers wrap `build()` in try/catch and log+drop
54
+ * — never propagated to the host app.
55
+ */
56
+ declare class ArgError extends Error {
57
+ constructor(message: string);
58
+ }
59
+
60
+ declare function pushEvent(event: Event): void;
61
+ /**
62
+ * Drains and returns all buffered events. Atomic w.r.t. pushEvent() —
63
+ * no event can be added between the swap and the clear. Mirrors Ruby's
64
+ * `events = @queue.dup; @queue.clear; events`.
65
+ */
66
+ declare function drainEvents(): Event[];
67
+ declare function bufferSize(): number;
68
+ declare function clearBuffer(): void;
69
+
70
+ declare const bufferOps_bufferSize: typeof bufferSize;
71
+ declare const bufferOps_clearBuffer: typeof clearBuffer;
72
+ declare const bufferOps_drainEvents: typeof drainEvents;
73
+ declare const bufferOps_pushEvent: typeof pushEvent;
74
+ declare namespace bufferOps {
75
+ export { bufferOps_bufferSize as bufferSize, bufferOps_clearBuffer as clearBuffer, bufferOps_drainEvents as drainEvents, bufferOps_pushEvent as pushEvent };
76
+ }
77
+
78
+ /**
79
+ * HTTP capture entry points.
80
+ *
81
+ * Next.js doesn't expose a "wrap every inbound request" hook the way
82
+ * Rack does (instrumentation.ts is for server-startup tooling, not
83
+ * per-request interception). The reliable pattern — used by Sentry,
84
+ * Highlight, OpenTelemetry's Next.js packages, and now us — is:
85
+ *
86
+ * 1. `captureRoute(handler)` — wrap App Router Route Handlers /
87
+ * Pages Router API handlers / Server Actions. The user opts in
88
+ * per-route. Programmatic, fully typed, no magic.
89
+ *
90
+ * 2. `withMiddlewareCapture(middleware)` — wrap the user's root
91
+ * `middleware.ts` so every request that hits the Next.js Edge
92
+ * middleware seeds a correlation id and (optionally) an actor.
93
+ * Downstream Route Handlers see them via current().
94
+ *
95
+ * 3. `onRequestError(error, request, context)` — wire this in
96
+ * `instrumentation.ts` so unhandled errors still produce events.
97
+ *
98
+ * All three feed the same internal `captureHttpEvent()` so the wire
99
+ * shape is identical regardless of entry point.
100
+ */
101
+ interface CaptureContext {
102
+ routeModulePath?: string | null;
103
+ serverActionName?: string | null;
104
+ }
105
+ /**
106
+ * Wrap a Route Handler / API handler / Server Action so each
107
+ * invocation produces an event.
108
+ *
109
+ * Generic over the handler signature so users keep their typed
110
+ * `(req: NextRequest) => Promise<Response>` shape.
111
+ */
112
+ declare function captureRoute<TArgs extends unknown[], TResult extends Response | Promise<Response>>(handler: (...args: TArgs) => TResult, context?: CaptureContext): (...args: TArgs) => Promise<Response>;
113
+ /**
114
+ * Structural shape of what we read from / write to. We avoid a hard
115
+ * dep on `next/server` (NextRequest / NextResponse types) because
116
+ * `next` is an optional peer dep — typing against the WHATWG fetch
117
+ * primitives keeps the agent decoupled from the Next.js version.
118
+ *
119
+ * We need `url` and `method` for page-navigation event emission, in
120
+ * addition to headers. NextRequest extends Request, so it satisfies
121
+ * this shape.
122
+ */
123
+ interface MiddlewareRequest {
124
+ headers: Headers;
125
+ url: string;
126
+ method: string;
127
+ }
128
+ interface ResponseWithHeaders {
129
+ headers: Headers;
130
+ status?: number;
131
+ }
132
+ declare function withMiddlewareCapture<TRequest extends MiddlewareRequest, TResponse extends ResponseWithHeaders>(middleware: (request: TRequest, ...rest: unknown[]) => Promise<TResponse> | TResponse): (request: TRequest, ...rest: unknown[]) => Promise<TResponse>;
133
+ /**
134
+ * Pages Router API wrapper. Pages Router handlers use the older
135
+ * Node-style `(req, res) => void | Promise<void>` signature instead
136
+ * of the WHATWG `(request) => Response` signature App Router uses.
137
+ *
138
+ * We snapshot enough off the Node `req` to build the same source_data
139
+ * shape, observe `res.statusCode` after the user's handler resolves,
140
+ * and emit the event. Any thrown error is captured then re-raised so
141
+ * the user's error handling still works.
142
+ *
143
+ * Used by the build-time auto-wrap loader for `pages/api/**` routes.
144
+ * Also exported publicly for users who want to wrap manually.
145
+ */
146
+ declare function capturePagesApi<TArgs extends [PagesApiReq, PagesApiRes, ...unknown[]]>(handler: (...args: TArgs) => unknown, context?: CaptureContext): (...args: TArgs) => Promise<unknown>;
147
+ interface PagesApiReq {
148
+ url?: string;
149
+ method?: string;
150
+ headers: Record<string, string | string[] | undefined> | Headers;
151
+ query?: Record<string, string | string[] | undefined>;
152
+ body?: unknown;
153
+ socket?: {
154
+ remoteAddress?: string;
155
+ };
156
+ }
157
+ interface PagesApiRes {
158
+ statusCode?: number;
159
+ [key: string]: unknown;
160
+ }
161
+ /**
162
+ * Server Action wrapper.
163
+ *
164
+ * Server Actions don't fit the Request -> Response model — they're
165
+ * async functions invoked by the Next.js RSC pipeline with whatever
166
+ * args their signature defines (commonly FormData). They also don't
167
+ * have a URL, status code, or query string.
168
+ *
169
+ * We can't auto-wrap them via the build plugin without risking
170
+ * Next.js's internal binding mechanism (the compiler attaches
171
+ * `$$id` / `$$bound` to action exports for client/server linking).
172
+ * So Server Actions are a manual opt-in:
173
+ *
174
+ * "use server"
175
+ * import { captureServerAction } from "ezlogs-nextjs"
176
+ *
177
+ * export const updateProfile = captureServerAction(
178
+ * async (formData: FormData) => {
179
+ * // ... your action body ...
180
+ * },
181
+ * "updateProfile",
182
+ * )
183
+ *
184
+ * The wrapped function preserves async/sync shape and re-throws on
185
+ * failure so Next.js's error handling still works.
186
+ */
187
+ declare function captureServerAction<TArgs extends unknown[], TResult>(action: (...args: TArgs) => TResult | Promise<TResult>, actionName: string): (...args: TArgs) => Promise<TResult>;
188
+ /**
189
+ * Runtime-conditional Server Action wrapper. Build-time auto-wrap
190
+ * doesn't know whether each exported symbol from a "use server" file
191
+ * is a function (an actual action) or an unrelated value (constants,
192
+ * re-exported types, etc.). This helper guards the wrap at runtime:
193
+ *
194
+ * - If the value is a function, return captureServerAction(value, name).
195
+ * - Otherwise return the value untouched.
196
+ *
197
+ * Designed to be a drop-in for `export const NAME = <expr>` rewrites
198
+ * by the Server Action loader.
199
+ */
200
+ declare function captureServerActionExport<T>(value: T, actionName: string): T;
201
+ /**
202
+ * Capture an inline `"use server"` action declared inside an RSC
203
+ * component (page / layout / etc.). The build-time loader rewrites
204
+ *
205
+ * async function deletePost(formData) {
206
+ * "use server"
207
+ * ...body...
208
+ * }
209
+ *
210
+ * into
211
+ *
212
+ * async function deletePost(formData) {
213
+ * "use server"
214
+ * return await __ezlogs_run_inline_server_action("deletePost", async () => {
215
+ * ...body...
216
+ * })
217
+ * }
218
+ *
219
+ * so SWC's Server Reference registration still sees the declaration
220
+ * and the `"use server"` prologue. The wrap fires only at call time
221
+ * and reuses every guarantee `captureServerAction` provides:
222
+ * correlation/actor scope, redirect()/notFound() handling, structural
223
+ * `{success: false}` classification, and (on serverless) an end-of-call
224
+ * flush.
225
+ *
226
+ * The action name is passed as a string literal at build time — we
227
+ * can't read it off the function reference because SWC's Server
228
+ * Reference registration rebinds the symbol to a wrapper whose
229
+ * `.name` is empty or `$$ACTION_*`.
230
+ *
231
+ * `args: undefined` is intentional — inline declarations don't expose
232
+ * a stable parameter shape to the wrap layer. v2 enhancement.
233
+ */
234
+ declare function __ezlogs_run_inline_server_action<TResult>(actionName: string, body: () => TResult | Promise<TResult>): Promise<TResult>;
235
+ /**
236
+ * Standalone capture entry — exposed for advanced users (e.g. custom
237
+ * frameworks, tests, third-party integrations) who already have a
238
+ * (request, response, error) tuple and just want an event recorded.
239
+ */
240
+ declare function captureHttpEvent(input: {
241
+ request: Request;
242
+ response: Response | null;
243
+ error: Error | null;
244
+ durationMs: number;
245
+ startedAt?: Date;
246
+ context?: CaptureContext;
247
+ }): Promise<void>;
248
+
249
+ /**
250
+ * ezlogs-nextjs — public entry point.
251
+ *
252
+ * `ezlogs.init()` configures the agent and starts the periodic flush
253
+ * scheduler. `ezlogs.flush()` drains the in-memory buffer and ships
254
+ * synchronously — call this before serverless handlers return.
255
+ *
256
+ * Capture surfaces (HTTP, DB, jobs) attach themselves via subpath
257
+ * imports (`ezlogs-nextjs/prisma`, etc.). The core entry point only
258
+ * runs the pipeline.
259
+ */
260
+
261
+ declare const ezlogs: {
262
+ init(options: InitOptions): void;
263
+ /**
264
+ * Drain the buffer and ship its contents now. Always call this before
265
+ * a serverless handler returns — Vercel/Lambda will freeze the
266
+ * process and the periodic flush timer will never fire.
267
+ */
268
+ flush(): Promise<void>;
269
+ /** Stop the periodic scheduler and flush remaining events. */
270
+ shutdown(): Promise<void>;
271
+ };
272
+ /**
273
+ * Conventional Postgres connection-string env vars used across the
274
+ * Next.js ecosystem. Order matters — the first match wins:
275
+ *
276
+ * - `DATABASE_URL` — Prisma's documented default,
277
+ * Drizzle starter convention,
278
+ * generic Node convention
279
+ * - `POSTGRES_URL` — Vercel Postgres / Neon (legacy),
280
+ * next-saas-starter convention
281
+ * - `POSTGRES_PRISMA_URL` — Vercel + Prisma's pooled URL
282
+ * - `POSTGRES_URL_NON_POOLING` — Vercel + Prisma's direct URL
283
+ * - `DIRECT_URL` — Supabase + Prisma direct URL
284
+ * - `SUPABASE_DB_URL` — explicit Supabase Postgres URL
285
+ *
286
+ * The agent uses the first non-empty value. Customers who run on
287
+ * something exotic can still pass `databaseUrl` explicitly.
288
+ *
289
+ * Validates the shape with a `postgres://`/`postgresql://` prefix so
290
+ * we don't accidentally use a non-Postgres URL stashed in one of
291
+ * these names.
292
+ */
293
+ declare function _detectDatabaseUrlFromEnvForTests(): string | null;
294
+ /** Test-only. Not exported from package entry. */
295
+ declare function _internalsForTests(): {
296
+ buffer: typeof bufferOps;
297
+ flushScheduler: {
298
+ start(): void;
299
+ stop(): Promise<void>;
300
+ isRunning(): boolean;
301
+ flushNow(): Promise<void>;
302
+ };
303
+ };
304
+
305
+ export { ArgError, type BuildInput, type Event, InitOptions, type Outcome, type ResourceId, type SourceType, __ezlogs_run_inline_server_action, _detectDatabaseUrlFromEnvForTests, _internalsForTests, build as buildEvent, captureHttpEvent, capturePagesApi, captureRoute, captureServerAction, captureServerActionExport, ezlogs, withMiddlewareCapture };
@@ -0,0 +1,305 @@
1
+ import { I as InitOptions } from './configuration-D9x9Gvds.js';
2
+ export { A as ActorContext, a as ActorFromRequest, D as DisplayNameMap } from './configuration-D9x9Gvds.js';
3
+
4
+ /**
5
+ * EventBuilder — port of ez_logs_agent/lib/ez_logs_agent/event_builder.rb.
6
+ *
7
+ * This module is the wire-format contract. The Node agent's only correctness
8
+ * requirement is that the JSON it ships matches what the Ruby agent ships
9
+ * for an equivalent invocation, byte-for-byte.
10
+ *
11
+ * KEY ORDERING IS LOAD-BEARING.
12
+ * The output object's top-level keys are emitted in this order:
13
+ * timestamp, source_type, source_data, outcome, correlation_id,
14
+ * resource_ids, context, duration_ms, error_message
15
+ * Do not refactor `build()` to use object spread or computed keys; the
16
+ * parity tests assert deep equality AND key ordering against the Ruby
17
+ * fixtures.
18
+ *
19
+ * Pure, side-effect-free. Validates, sanitizes, returns the event object.
20
+ * Does NOT buffer, ship, or generate correlation IDs.
21
+ */
22
+ type SourceType = "http_request" | "background_job" | "database_callback";
23
+ type Outcome = "success" | "failure";
24
+ interface ResourceId {
25
+ resource_type: string;
26
+ resource_id: string;
27
+ }
28
+ interface Event {
29
+ timestamp: string;
30
+ source_type: SourceType;
31
+ source_data: Record<string, unknown>;
32
+ outcome: Outcome;
33
+ correlation_id: string | null;
34
+ resource_ids: ResourceId[];
35
+ context: Record<string, unknown> | null;
36
+ duration_ms: number | null;
37
+ error_message: string | null;
38
+ }
39
+ interface BuildInput {
40
+ source_type: SourceType | string;
41
+ source_data: Record<string, unknown>;
42
+ outcome: Outcome | string;
43
+ correlation_id?: string | null;
44
+ resource_ids?: ResourceId[];
45
+ context?: Record<string, unknown> | null;
46
+ duration_ms?: number | null;
47
+ error_message?: string | null;
48
+ timestamp?: string | Date | null;
49
+ }
50
+ declare function build(input: BuildInput): Event;
51
+ /**
52
+ * Mirrors Ruby's ArgumentError. Thrown for any validation failure during
53
+ * `build()`. Callers in capturers wrap `build()` in try/catch and log+drop
54
+ * — never propagated to the host app.
55
+ */
56
+ declare class ArgError extends Error {
57
+ constructor(message: string);
58
+ }
59
+
60
+ declare function pushEvent(event: Event): void;
61
+ /**
62
+ * Drains and returns all buffered events. Atomic w.r.t. pushEvent() —
63
+ * no event can be added between the swap and the clear. Mirrors Ruby's
64
+ * `events = @queue.dup; @queue.clear; events`.
65
+ */
66
+ declare function drainEvents(): Event[];
67
+ declare function bufferSize(): number;
68
+ declare function clearBuffer(): void;
69
+
70
+ declare const bufferOps_bufferSize: typeof bufferSize;
71
+ declare const bufferOps_clearBuffer: typeof clearBuffer;
72
+ declare const bufferOps_drainEvents: typeof drainEvents;
73
+ declare const bufferOps_pushEvent: typeof pushEvent;
74
+ declare namespace bufferOps {
75
+ export { bufferOps_bufferSize as bufferSize, bufferOps_clearBuffer as clearBuffer, bufferOps_drainEvents as drainEvents, bufferOps_pushEvent as pushEvent };
76
+ }
77
+
78
+ /**
79
+ * HTTP capture entry points.
80
+ *
81
+ * Next.js doesn't expose a "wrap every inbound request" hook the way
82
+ * Rack does (instrumentation.ts is for server-startup tooling, not
83
+ * per-request interception). The reliable pattern — used by Sentry,
84
+ * Highlight, OpenTelemetry's Next.js packages, and now us — is:
85
+ *
86
+ * 1. `captureRoute(handler)` — wrap App Router Route Handlers /
87
+ * Pages Router API handlers / Server Actions. The user opts in
88
+ * per-route. Programmatic, fully typed, no magic.
89
+ *
90
+ * 2. `withMiddlewareCapture(middleware)` — wrap the user's root
91
+ * `middleware.ts` so every request that hits the Next.js Edge
92
+ * middleware seeds a correlation id and (optionally) an actor.
93
+ * Downstream Route Handlers see them via current().
94
+ *
95
+ * 3. `onRequestError(error, request, context)` — wire this in
96
+ * `instrumentation.ts` so unhandled errors still produce events.
97
+ *
98
+ * All three feed the same internal `captureHttpEvent()` so the wire
99
+ * shape is identical regardless of entry point.
100
+ */
101
+ interface CaptureContext {
102
+ routeModulePath?: string | null;
103
+ serverActionName?: string | null;
104
+ }
105
+ /**
106
+ * Wrap a Route Handler / API handler / Server Action so each
107
+ * invocation produces an event.
108
+ *
109
+ * Generic over the handler signature so users keep their typed
110
+ * `(req: NextRequest) => Promise<Response>` shape.
111
+ */
112
+ declare function captureRoute<TArgs extends unknown[], TResult extends Response | Promise<Response>>(handler: (...args: TArgs) => TResult, context?: CaptureContext): (...args: TArgs) => Promise<Response>;
113
+ /**
114
+ * Structural shape of what we read from / write to. We avoid a hard
115
+ * dep on `next/server` (NextRequest / NextResponse types) because
116
+ * `next` is an optional peer dep — typing against the WHATWG fetch
117
+ * primitives keeps the agent decoupled from the Next.js version.
118
+ *
119
+ * We need `url` and `method` for page-navigation event emission, in
120
+ * addition to headers. NextRequest extends Request, so it satisfies
121
+ * this shape.
122
+ */
123
+ interface MiddlewareRequest {
124
+ headers: Headers;
125
+ url: string;
126
+ method: string;
127
+ }
128
+ interface ResponseWithHeaders {
129
+ headers: Headers;
130
+ status?: number;
131
+ }
132
+ declare function withMiddlewareCapture<TRequest extends MiddlewareRequest, TResponse extends ResponseWithHeaders>(middleware: (request: TRequest, ...rest: unknown[]) => Promise<TResponse> | TResponse): (request: TRequest, ...rest: unknown[]) => Promise<TResponse>;
133
+ /**
134
+ * Pages Router API wrapper. Pages Router handlers use the older
135
+ * Node-style `(req, res) => void | Promise<void>` signature instead
136
+ * of the WHATWG `(request) => Response` signature App Router uses.
137
+ *
138
+ * We snapshot enough off the Node `req` to build the same source_data
139
+ * shape, observe `res.statusCode` after the user's handler resolves,
140
+ * and emit the event. Any thrown error is captured then re-raised so
141
+ * the user's error handling still works.
142
+ *
143
+ * Used by the build-time auto-wrap loader for `pages/api/**` routes.
144
+ * Also exported publicly for users who want to wrap manually.
145
+ */
146
+ declare function capturePagesApi<TArgs extends [PagesApiReq, PagesApiRes, ...unknown[]]>(handler: (...args: TArgs) => unknown, context?: CaptureContext): (...args: TArgs) => Promise<unknown>;
147
+ interface PagesApiReq {
148
+ url?: string;
149
+ method?: string;
150
+ headers: Record<string, string | string[] | undefined> | Headers;
151
+ query?: Record<string, string | string[] | undefined>;
152
+ body?: unknown;
153
+ socket?: {
154
+ remoteAddress?: string;
155
+ };
156
+ }
157
+ interface PagesApiRes {
158
+ statusCode?: number;
159
+ [key: string]: unknown;
160
+ }
161
+ /**
162
+ * Server Action wrapper.
163
+ *
164
+ * Server Actions don't fit the Request -> Response model — they're
165
+ * async functions invoked by the Next.js RSC pipeline with whatever
166
+ * args their signature defines (commonly FormData). They also don't
167
+ * have a URL, status code, or query string.
168
+ *
169
+ * We can't auto-wrap them via the build plugin without risking
170
+ * Next.js's internal binding mechanism (the compiler attaches
171
+ * `$$id` / `$$bound` to action exports for client/server linking).
172
+ * So Server Actions are a manual opt-in:
173
+ *
174
+ * "use server"
175
+ * import { captureServerAction } from "ezlogs-nextjs"
176
+ *
177
+ * export const updateProfile = captureServerAction(
178
+ * async (formData: FormData) => {
179
+ * // ... your action body ...
180
+ * },
181
+ * "updateProfile",
182
+ * )
183
+ *
184
+ * The wrapped function preserves async/sync shape and re-throws on
185
+ * failure so Next.js's error handling still works.
186
+ */
187
+ declare function captureServerAction<TArgs extends unknown[], TResult>(action: (...args: TArgs) => TResult | Promise<TResult>, actionName: string): (...args: TArgs) => Promise<TResult>;
188
+ /**
189
+ * Runtime-conditional Server Action wrapper. Build-time auto-wrap
190
+ * doesn't know whether each exported symbol from a "use server" file
191
+ * is a function (an actual action) or an unrelated value (constants,
192
+ * re-exported types, etc.). This helper guards the wrap at runtime:
193
+ *
194
+ * - If the value is a function, return captureServerAction(value, name).
195
+ * - Otherwise return the value untouched.
196
+ *
197
+ * Designed to be a drop-in for `export const NAME = <expr>` rewrites
198
+ * by the Server Action loader.
199
+ */
200
+ declare function captureServerActionExport<T>(value: T, actionName: string): T;
201
+ /**
202
+ * Capture an inline `"use server"` action declared inside an RSC
203
+ * component (page / layout / etc.). The build-time loader rewrites
204
+ *
205
+ * async function deletePost(formData) {
206
+ * "use server"
207
+ * ...body...
208
+ * }
209
+ *
210
+ * into
211
+ *
212
+ * async function deletePost(formData) {
213
+ * "use server"
214
+ * return await __ezlogs_run_inline_server_action("deletePost", async () => {
215
+ * ...body...
216
+ * })
217
+ * }
218
+ *
219
+ * so SWC's Server Reference registration still sees the declaration
220
+ * and the `"use server"` prologue. The wrap fires only at call time
221
+ * and reuses every guarantee `captureServerAction` provides:
222
+ * correlation/actor scope, redirect()/notFound() handling, structural
223
+ * `{success: false}` classification, and (on serverless) an end-of-call
224
+ * flush.
225
+ *
226
+ * The action name is passed as a string literal at build time — we
227
+ * can't read it off the function reference because SWC's Server
228
+ * Reference registration rebinds the symbol to a wrapper whose
229
+ * `.name` is empty or `$$ACTION_*`.
230
+ *
231
+ * `args: undefined` is intentional — inline declarations don't expose
232
+ * a stable parameter shape to the wrap layer. v2 enhancement.
233
+ */
234
+ declare function __ezlogs_run_inline_server_action<TResult>(actionName: string, body: () => TResult | Promise<TResult>): Promise<TResult>;
235
+ /**
236
+ * Standalone capture entry — exposed for advanced users (e.g. custom
237
+ * frameworks, tests, third-party integrations) who already have a
238
+ * (request, response, error) tuple and just want an event recorded.
239
+ */
240
+ declare function captureHttpEvent(input: {
241
+ request: Request;
242
+ response: Response | null;
243
+ error: Error | null;
244
+ durationMs: number;
245
+ startedAt?: Date;
246
+ context?: CaptureContext;
247
+ }): Promise<void>;
248
+
249
+ /**
250
+ * ezlogs-nextjs — public entry point.
251
+ *
252
+ * `ezlogs.init()` configures the agent and starts the periodic flush
253
+ * scheduler. `ezlogs.flush()` drains the in-memory buffer and ships
254
+ * synchronously — call this before serverless handlers return.
255
+ *
256
+ * Capture surfaces (HTTP, DB, jobs) attach themselves via subpath
257
+ * imports (`ezlogs-nextjs/prisma`, etc.). The core entry point only
258
+ * runs the pipeline.
259
+ */
260
+
261
+ declare const ezlogs: {
262
+ init(options: InitOptions): void;
263
+ /**
264
+ * Drain the buffer and ship its contents now. Always call this before
265
+ * a serverless handler returns — Vercel/Lambda will freeze the
266
+ * process and the periodic flush timer will never fire.
267
+ */
268
+ flush(): Promise<void>;
269
+ /** Stop the periodic scheduler and flush remaining events. */
270
+ shutdown(): Promise<void>;
271
+ };
272
+ /**
273
+ * Conventional Postgres connection-string env vars used across the
274
+ * Next.js ecosystem. Order matters — the first match wins:
275
+ *
276
+ * - `DATABASE_URL` — Prisma's documented default,
277
+ * Drizzle starter convention,
278
+ * generic Node convention
279
+ * - `POSTGRES_URL` — Vercel Postgres / Neon (legacy),
280
+ * next-saas-starter convention
281
+ * - `POSTGRES_PRISMA_URL` — Vercel + Prisma's pooled URL
282
+ * - `POSTGRES_URL_NON_POOLING` — Vercel + Prisma's direct URL
283
+ * - `DIRECT_URL` — Supabase + Prisma direct URL
284
+ * - `SUPABASE_DB_URL` — explicit Supabase Postgres URL
285
+ *
286
+ * The agent uses the first non-empty value. Customers who run on
287
+ * something exotic can still pass `databaseUrl` explicitly.
288
+ *
289
+ * Validates the shape with a `postgres://`/`postgresql://` prefix so
290
+ * we don't accidentally use a non-Postgres URL stashed in one of
291
+ * these names.
292
+ */
293
+ declare function _detectDatabaseUrlFromEnvForTests(): string | null;
294
+ /** Test-only. Not exported from package entry. */
295
+ declare function _internalsForTests(): {
296
+ buffer: typeof bufferOps;
297
+ flushScheduler: {
298
+ start(): void;
299
+ stop(): Promise<void>;
300
+ isRunning(): boolean;
301
+ flushNow(): Promise<void>;
302
+ };
303
+ };
304
+
305
+ export { ArgError, type BuildInput, type Event, InitOptions, type Outcome, type ResourceId, type SourceType, __ezlogs_run_inline_server_action, _detectDatabaseUrlFromEnvForTests, _internalsForTests, build as buildEvent, captureHttpEvent, capturePagesApi, captureRoute, captureServerAction, captureServerActionExport, ezlogs, withMiddlewareCapture };