@justanalyticsapp/node 0.1.0

package/dist/integrations/next.d.ts

@@ -0,0 +1,252 @@
+/**
+ * @file packages/node-sdk/src/integrations/next.ts
+ * @description Next.js integration for JustAnalytics Node.js SDK.
+ *
+ * Implements Story 044 - Next.js Integration
+ *
+ * Provides zero-config initialization via Next.js 15+ instrumentation.ts hook,
+ * API route tracing wrappers, middleware tracing, and Server Component helpers.
+ *
+ * Quick Start (Next.js 15+):
+ * ```typescript
+ * // instrumentation.ts
+ * export { register } from '@justanalyticsapp/node/next';
+ * ```
+ *
+ * With custom config:
+ * ```typescript
+ * // instrumentation.ts
+ * import { withJustAnalytics } from '@justanalyticsapp/node/next';
+ *
+ * export function register() {
+ *   withJustAnalytics({
+ *     siteId: 'site_abc123',
+ *     apiKey: 'ja_sk_...',
+ *     serviceName: 'my-next-app',
+ *     environment: 'production',
+ *   });
+ * }
+ * ```
+ *
+ * API Route Tracing:
+ * ```typescript
+ * // app/api/users/[id]/route.ts
+ * import { withTracing } from '@justanalyticsapp/node/next';
+ *
+ * export const GET = withTracing(async (req, { params }) => {
+ *   const user = await db.users.findUnique({ where: { id: params.id } });
+ *   return Response.json(user);
+ * });
+ * ```
+ *
+ * Middleware Tracing:
+ * ```typescript
+ * // middleware.ts
+ * import { withMiddlewareTracing } from '@justanalyticsapp/node/next';
+ *
+ * export default withMiddlewareTracing(async (req) => {
+ *   // your middleware logic
+ *   return NextResponse.next();
+ * });
+ * ```
+ *
+ * Server Component Tracing:
+ * ```typescript
+ * // app/users/[id]/page.tsx
+ * import { traceServerComponent } from '@justanalyticsapp/node/next';
+ *
+ * export default async function UserPage({ params }) {
+ *   return traceServerComponent('UserPage', async () => {
+ *     const user = await getUser(params.id);
+ *     return <UserProfile user={user} />;
+ *   });
+ * }
+ * ```
+ *
+ * References:
+ * - Story 035 - Node.js SDK Core (JA.init, JA.startSpan, context)
+ * - Story 036 - HTTP Auto-Instrumentation (parent span creation)
+ * - Next.js instrumentation.ts: https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation
+ */
+import { JustAnalyticsOptions } from '../client';
+/**
+ * Minimal NextRequest interface to avoid importing from 'next/server'.
+ * Follows the same pattern as express.ts's minimal Express types.
+ */
+export interface NextRequestLike {
+    /** HTTP method */
+    method: string;
+    /** Full request URL string */
+    url: string;
+    /** Next.js-specific parsed URL (available on NextRequest) */
+    nextUrl?: {
+        pathname: string;
+        searchParams?: URLSearchParams;
+    };
+    /** Request headers */
+    headers: {
+        get(name: string): string | null;
+    };
+}
+/**
+ * Minimal NextResponse-like interface.
+ */
+export interface NextResponseLike {
+    /** HTTP status code */
+    status: number;
+    /** Response headers */
+    headers: {
+        get(name: string): string | null;
+    };
+}
+/**
+ * A Next.js App Router API route handler signature.
+ */
+export type NextRouteHandler = (req: NextRequestLike, context?: {
+    params?: Record<string, string | string[]>;
+}) => Response | Promise<Response>;
+/**
+ * A Next.js middleware function signature.
+ */
+export type NextMiddlewareFunction = (req: NextRequestLike) => NextResponseLike | Response | Promise<NextResponseLike | Response>;
+/**
+ * An async Server Component render function.
+ */
+export type ServerComponentFunction<T> = () => T | Promise<T>;
+/**
+ * Configuration options specific to the Next.js integration.
+ * Extends JustAnalyticsOptions with Next.js-specific defaults.
+ */
+export interface NextJustAnalyticsOptions extends Partial<JustAnalyticsOptions> {
+    /**
+     * Whether to auto-detect configuration from environment variables.
+     * When true (default), reads JUSTANALYTICS_SITE_ID, JUSTANALYTICS_API_KEY,
+     * JUSTANALYTICS_SERVICE_NAME, JUSTANALYTICS_ENVIRONMENT, JUSTANALYTICS_URL.
+     */
+    autoDetectEnv?: boolean;
+}
+/**
+ * Initialize JustAnalytics with Next.js-optimized defaults.
+ *
+ * Reads configuration from environment variables when not explicitly provided.
+ * Safe to call multiple times (idempotent -- delegates to JA.init()'s guard).
+ *
+ * Environment variables (in order of priority: explicit config > env var > default):
+ * - `JUSTANALYTICS_SITE_ID` -- site ID
+ * - `JUSTANALYTICS_API_KEY` -- API key
+ * - `JUSTANALYTICS_SERVICE_NAME` -- service name (default: `'next-app'`)
+ * - `JUSTANALYTICS_ENVIRONMENT` -- environment (default: `NODE_ENV || 'development'`)
+ * - `JUSTANALYTICS_URL` -- server URL
+ *
+ * If `siteId` or `apiKey` are missing after merging config and env vars,
+ * the function logs a warning and returns without calling `init()`.
+ *
+ * @param config - Optional configuration overrides
+ */
+export declare function withJustAnalytics(config?: NextJustAnalyticsOptions): void;
+/**
+ * Next.js instrumentation.ts register() hook.
+ *
+ * Export this directly from your instrumentation.ts:
+ * ```typescript
+ * export { register } from '@justanalyticsapp/node/next';
+ * ```
+ *
+ * Only initializes on the Node.js runtime (skips edge runtime).
+ * Designed for Next.js 15+ where `instrumentation.ts` is stable.
+ * For Next.js 13-14, call `withJustAnalytics()` manually.
+ */
+export declare function register(): void;
+/**
+ * Extract the Next.js route pattern from a request.
+ *
+ * Checks Next.js internal headers in priority order:
+ * 1. `x-invoke-path` -- Next.js 14.1+ sets this to the file-system route
+ * 2. `x-matched-path` -- Some Next.js versions use this header
+ * 3. `x-nextjs-page` -- Older Next.js versions (13.x) may set this
+ * 4. Falls back to `req.nextUrl.pathname` or raw URL pathname
+ *
+ * Query strings are stripped from the returned pattern.
+ *
+ * @param req - The incoming request
+ * @returns The route pattern string (e.g., '/api/users/[id]')
+ */
+export declare function extractRoutePattern(req: NextRequestLike): string;
+/**
+ * Wrap a Next.js API route handler with tracing.
+ *
+ * Creates a server span wrapping the handler execution. The span is named
+ * `{METHOD} {routePattern}` (e.g., `GET /api/users/[id]`) and includes
+ * Next.js-specific attributes.
+ *
+ * If the SDK is not initialized, the handler is called directly (no-op pass-through).
+ * Never throws -- all instrumentation errors are caught silently.
+ *
+ * @param handler - The route handler function
+ * @returns A wrapped handler with automatic tracing
+ *
+ * @example
+ * ```typescript
+ * // app/api/users/[id]/route.ts
+ * import { withTracing } from '@justanalyticsapp/node/next';
+ *
+ * export const GET = withTracing(async (req, { params }) => {
+ *   const user = await db.users.findUnique({ where: { id: params.id } });
+ *   return Response.json(user);
+ * });
+ * ```
+ */
+export declare function withTracing(handler: NextRouteHandler): NextRouteHandler;
+/**
+ * Wrap Next.js middleware with tracing.
+ *
+ * Creates a span with operation name `middleware` and kind `'server'`.
+ * Captures the response status and any `x-middleware-rewrite` or
+ * `x-middleware-redirect` headers as span attributes.
+ *
+ * If the SDK is not initialized, the middleware is called directly (no-op pass-through).
+ * Never throws -- all instrumentation errors are caught silently.
+ *
+ * @param middleware - The middleware function
+ * @returns A wrapped middleware with automatic tracing
+ *
+ * @example
+ * ```typescript
+ * // middleware.ts
+ * import { withMiddlewareTracing } from '@justanalyticsapp/node/next';
+ *
+ * export default withMiddlewareTracing(async (req) => {
+ *   // your middleware logic
+ *   return NextResponse.next();
+ * });
+ * ```
+ */
+export declare function withMiddlewareTracing(middleware: NextMiddlewareFunction): NextMiddlewareFunction;
+/**
+ * Wrap an async Server Component render in a traced span.
+ *
+ * The span has kind `'internal'` and operation name `RSC {name}`
+ * (e.g., `RSC UserProfile`). It sets `next.rsc: true` to distinguish
+ * from API route spans.
+ *
+ * If the SDK is not initialized, the function is called directly (no-op pass-through).
+ * Never throws -- all instrumentation errors are caught silently.
+ *
+ * @param name - Component name for the span (e.g., 'UserProfile')
+ * @param fn - The async render function
+ * @returns The result of fn()
+ *
+ * @example
+ * ```typescript
+ * // app/users/[id]/page.tsx
+ * import { traceServerComponent } from '@justanalyticsapp/node/next';
+ *
+ * export default async function UserPage({ params }) {
+ *   return traceServerComponent('UserPage', async () => {
+ *     const user = await getUser(params.id);
+ *     return <UserProfile user={user} />;
+ *   });
+ * }
+ * ```
+ */
+export declare function traceServerComponent<T>(name: string, fn: ServerComponentFunction<T>): T | Promise<T>;