ezlogs-nextjs 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +779 -0
- package/bin/install-triggers.cjs +75 -0
- package/dist/actors/index.cjs +111 -0
- package/dist/actors/index.d.cts +52 -0
- package/dist/actors/index.d.ts +52 -0
- package/dist/actors/index.js +107 -0
- package/dist/configuration-D9x9Gvds.d.cts +190 -0
- package/dist/configuration-D9x9Gvds.d.ts +190 -0
- package/dist/db/drizzle.cjs +898 -0
- package/dist/db/drizzle.d.cts +68 -0
- package/dist/db/drizzle.d.ts +68 -0
- package/dist/db/drizzle.js +893 -0
- package/dist/db/prisma.cjs +826 -0
- package/dist/db/prisma.d.cts +3 -0
- package/dist/db/prisma.d.ts +3 -0
- package/dist/db/prisma.js +824 -0
- package/dist/db/supabase.cjs +1027 -0
- package/dist/db/supabase.d.cts +32 -0
- package/dist/db/supabase.d.ts +32 -0
- package/dist/db/supabase.js +1024 -0
- package/dist/index.cjs +3329 -0
- package/dist/index.d.cts +305 -0
- package/dist/index.d.ts +305 -0
- package/dist/index.js +3317 -0
- package/dist/jobs/bullmq.cjs +624 -0
- package/dist/jobs/bullmq.d.cts +33 -0
- package/dist/jobs/bullmq.d.ts +33 -0
- package/dist/jobs/bullmq.js +621 -0
- package/dist/jobs/inngest.cjs +645 -0
- package/dist/jobs/inngest.d.cts +21 -0
- package/dist/jobs/inngest.d.ts +21 -0
- package/dist/jobs/inngest.js +642 -0
- package/dist/jobs/supabase-queues.cjs +661 -0
- package/dist/jobs/supabase-queues.d.cts +37 -0
- package/dist/jobs/supabase-queues.d.ts +37 -0
- package/dist/jobs/supabase-queues.js +657 -0
- package/dist/jobs/trigger.cjs +622 -0
- package/dist/jobs/trigger.d.cts +46 -0
- package/dist/jobs/trigger.d.ts +46 -0
- package/dist/jobs/trigger.js +619 -0
- package/dist/jobs/upstash-workflow.cjs +673 -0
- package/dist/jobs/upstash-workflow.d.cts +57 -0
- package/dist/jobs/upstash-workflow.d.ts +57 -0
- package/dist/jobs/upstash-workflow.js +669 -0
- package/dist/nextjs-plugin/index.cjs +232 -0
- package/dist/nextjs-plugin/index.d.cts +68 -0
- package/dist/nextjs-plugin/index.d.ts +68 -0
- package/dist/nextjs-plugin/index.js +229 -0
- package/dist/nextjs-plugin/loader.cjs +16248 -0
- package/dist/nextjs-plugin/loader.d.cts +61 -0
- package/dist/nextjs-plugin/loader.d.ts +61 -0
- package/dist/nextjs-plugin/loader.js +16242 -0
- package/dist/triggers/index.cjs +1354 -0
- package/dist/triggers/index.d.cts +243 -0
- package/dist/triggers/index.d.ts +243 -0
- package/dist/triggers/index.js +1337 -0
- package/package.json +150 -0
- package/sql/postgres/00_install.sql +205 -0
package/dist/index.d.cts
ADDED
|
@@ -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 };
|
package/dist/index.d.ts
ADDED
|
@@ -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 };
|