@justanalyticsapp/node 0.1.0

package/dist/integrations/next.js

@@ -0,0 +1,480 @@
+"use strict";
+/**
+ * @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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withJustAnalytics = withJustAnalytics;
+exports.register = register;
+exports.extractRoutePattern = extractRoutePattern;
+exports.withTracing = withTracing;
+exports.withMiddlewareTracing = withMiddlewareTracing;
+exports.traceServerComponent = traceServerComponent;
+// Import SDK functions lazily via require to avoid circular dependencies
+// and to ensure we use the singleton from index.ts. We import the client
+// class directly since the singleton is created in index.ts.
+const client_1 = require("../client");
+/**
+ * Internal reference to the singleton SDK client.
+ *
+ * We create our own singleton reference here rather than importing from
+ * index.ts to avoid circular dependency issues when this file is imported
+ * via the `./next` export path. The `withJustAnalytics()` function creates
+ * and initializes this client.
+ */
+let _client = null;
+/**
+ * Get the SDK client, creating it if necessary.
+ *
+ * @returns The JustAnalyticsClient instance, or null if not yet initialized
+ */
+function getClient() {
+    return _client;
+}
+// ---------------------------------------------------------------------------
+// withJustAnalytics()
+// ---------------------------------------------------------------------------
+/**
+ * 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
+ */
+function withJustAnalytics(config) {
+    try {
+        // Skip initialization on edge runtime (SDK uses Node.js APIs)
+        if (typeof process !== 'undefined' && process.env.NEXT_RUNTIME === 'edge') {
+            return;
+        }
+        // Read environment variables
+        const envSiteId = typeof process !== 'undefined' ? process.env.JUSTANALYTICS_SITE_ID : undefined;
+        const envApiKey = typeof process !== 'undefined' ? process.env.JUSTANALYTICS_API_KEY : undefined;
+        const envServiceName = typeof process !== 'undefined' ? process.env.JUSTANALYTICS_SERVICE_NAME : undefined;
+        const envEnvironment = typeof process !== 'undefined' ? process.env.JUSTANALYTICS_ENVIRONMENT : undefined;
+        const envUrl = typeof process !== 'undefined' ? process.env.JUSTANALYTICS_URL : undefined;
+        const envNodeEnv = typeof process !== 'undefined' ? process.env.NODE_ENV : undefined;
+        // Merge: explicit config > env vars > defaults
+        const siteId = config?.siteId || envSiteId || '';
+        const apiKey = config?.apiKey || envApiKey || '';
+        const serviceName = config?.serviceName || envServiceName || 'next-app';
+        const environment = config?.environment || envEnvironment || envNodeEnv || 'development';
+        const serverUrl = config?.serverUrl || envUrl;
+        // Validate required fields
+        if (!siteId || !apiKey) {
+            console.warn('[JustAnalytics] Missing siteId or apiKey. SDK will not initialize.');
+            return;
+        }
+        // Create client if not already created
+        if (!_client) {
+            _client = new client_1.JustAnalyticsClient();
+        }
+        // Build init options, stripping Next.js-specific fields
+        const initOptions = {
+            siteId,
+            apiKey,
+            serviceName,
+            environment,
+            ...(serverUrl ? { serverUrl } : {}),
+            ...(config?.release ? { release: config.release } : {}),
+            ...(config?.debug !== undefined ? { debug: config.debug } : {}),
+            ...(config?.flushIntervalMs !== undefined ? { flushIntervalMs: config.flushIntervalMs } : {}),
+            ...(config?.maxBatchSize !== undefined ? { maxBatchSize: config.maxBatchSize } : {}),
+            ...(config?.enabled !== undefined ? { enabled: config.enabled } : {}),
+            ...(config?.integrations ? { integrations: config.integrations } : {}),
+            ...(config?.enableUncaughtExceptionHandler !== undefined
+                ? { enableUncaughtExceptionHandler: config.enableUncaughtExceptionHandler }
+                : {}),
+            ...(config?.enableUnhandledRejectionHandler !== undefined
+                ? { enableUnhandledRejectionHandler: config.enableUnhandledRejectionHandler }
+                : {}),
+        };
+        _client.init(initOptions);
+    }
+    catch {
+        // Never throw from initialization -- the user's app must not be affected
+    }
+}
+// ---------------------------------------------------------------------------
+// register()
+// ---------------------------------------------------------------------------
+/**
+ * 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.
+ */
+function register() {
+    try {
+        // Skip on edge runtime -- SDK uses Node.js-only APIs
+        if (typeof process !== 'undefined' && process.env.NEXT_RUNTIME === 'edge') {
+            return;
+        }
+        withJustAnalytics();
+    }
+    catch {
+        // Never throw from the register hook
+    }
+}
+// ---------------------------------------------------------------------------
+// extractRoutePattern()
+// ---------------------------------------------------------------------------
+/**
+ * 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]')
+ */
+function extractRoutePattern(req) {
+    try {
+        let pattern = null;
+        // Check Next.js internal headers in priority order
+        if (req.headers && typeof req.headers.get === 'function') {
+            pattern = req.headers.get('x-invoke-path');
+            if (!pattern) {
+                pattern = req.headers.get('x-matched-path');
+            }
+            if (!pattern) {
+                pattern = req.headers.get('x-nextjs-page');
+            }
+        }
+        // Fallback to nextUrl.pathname or raw URL pathname
+        if (!pattern) {
+            if (req.nextUrl?.pathname) {
+                pattern = req.nextUrl.pathname;
+            }
+            else if (req.url) {
+                try {
+                    const url = new URL(req.url, 'http://localhost');
+                    pattern = url.pathname;
+                }
+                catch {
+                    pattern = req.url;
+                }
+            }
+            else {
+                pattern = '/';
+            }
+        }
+        // Strip query strings if present
+        const queryIndex = pattern.indexOf('?');
+        if (queryIndex !== -1) {
+            pattern = pattern.substring(0, queryIndex);
+        }
+        return pattern;
+    }
+    catch {
+        // Fallback: return root path on any error
+        return '/';
+    }
+}
+// ---------------------------------------------------------------------------
+// withTracing()
+// ---------------------------------------------------------------------------
+/**
+ * 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);
+ * });
+ * ```
+ */
+function withTracing(handler) {
+    return async function tracedHandler(req, context) {
+        // Pass through if SDK is not initialized
+        const client = getClient();
+        if (!client || !client.isInitialized()) {
+            try {
+                return await handler(req, context);
+            }
+            catch (err) {
+                throw err;
+            }
+        }
+        try {
+            // Extract route pattern and method
+            const routePattern = extractRoutePattern(req);
+            const method = (req.method || 'GET').toUpperCase();
+            const spanName = `${method} ${routePattern}`;
+            const runtime = typeof process !== 'undefined'
+                ? (process.env.NEXT_RUNTIME || 'nodejs')
+                : 'nodejs';
+            return await client.startSpan(spanName, { kind: 'server' }, async (span) => {
+                // Set Next.js-specific attributes
+                span.setAttribute('next.route', routePattern);
+                span.setAttribute('next.runtime', runtime);
+                span.setAttribute('http.method', method);
+                span.setAttribute('http.url', req.url || '');
+                span.setAttribute('http.route', routePattern);
+                let response;
+                try {
+                    response = await handler(req, context);
+                }
+                catch (err) {
+                    // Handler threw -- span will be auto-ended with error by startSpan
+                    throw err;
+                }
+                // Set response attributes
+                const statusCode = response.status;
+                span.setAttribute('http.status_code', statusCode);
+                if (statusCode >= 500) {
+                    span.setStatus('error', `HTTP ${statusCode}`);
+                }
+                return response;
+            });
+        }
+        catch (err) {
+            // If it's a handler error, re-throw it (startSpan already re-throws)
+            // If it's an instrumentation error, fall through to original handler
+            if (err instanceof Error && err.message === '[JustAnalytics] startSpan() requires a callback function.') {
+                return await handler(req, context);
+            }
+            throw err;
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// withMiddlewareTracing()
+// ---------------------------------------------------------------------------
+/**
+ * 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();
+ * });
+ * ```
+ */
+function withMiddlewareTracing(middleware) {
+    return async function tracedMiddleware(req) {
+        // Pass through if SDK is not initialized
+        const client = getClient();
+        if (!client || !client.isInitialized()) {
+            try {
+                return await middleware(req);
+            }
+            catch (err) {
+                throw err;
+            }
+        }
+        try {
+            return await client.startSpan('middleware', { kind: 'server' }, async (span) => {
+                // Set middleware-specific attributes
+                span.setAttribute('next.middleware', true);
+                let response;
+                try {
+                    response = await middleware(req);
+                }
+                catch (err) {
+                    // Middleware threw -- span will be auto-ended with error by startSpan
+                    throw err;
+                }
+                // Set response status
+                if (typeof response.status === 'number') {
+                    span.setAttribute('http.status_code', response.status);
+                    if (response.status >= 500) {
+                        span.setStatus('error', `HTTP ${response.status}`);
+                    }
+                }
+                // Capture middleware-specific headers
+                if (response.headers && typeof response.headers.get === 'function') {
+                    const rewriteUrl = response.headers.get('x-middleware-rewrite');
+                    if (rewriteUrl) {
+                        span.setAttribute('next.middleware.rewrite', rewriteUrl);
+                    }
+                    const redirectUrl = response.headers.get('x-middleware-redirect');
+                    if (redirectUrl) {
+                        span.setAttribute('next.middleware.redirect', redirectUrl);
+                    }
+                }
+                return response;
+            });
+        }
+        catch (err) {
+            // If it's a middleware error, re-throw it (startSpan already re-throws)
+            if (err instanceof Error && err.message === '[JustAnalytics] startSpan() requires a callback function.') {
+                return await middleware(req);
+            }
+            throw err;
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// traceServerComponent()
+// ---------------------------------------------------------------------------
+/**
+ * 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} />;
+ *   });
+ * }
+ * ```
+ */
+function traceServerComponent(name, fn) {
+    // Pass through if SDK is not initialized
+    const client = getClient();
+    if (!client || !client.isInitialized()) {
+        try {
+            return fn();
+        }
+        catch (err) {
+            throw err;
+        }
+    }
+    try {
+        return client.startSpan(`RSC ${name}`, { kind: 'internal' }, (span) => {
+            // Set RSC-specific attribute
+            span.setAttribute('next.rsc', true);
+            return fn();
+        });
+    }
+    catch (err) {
+        // If it's a user function error, re-throw it
+        if (err instanceof Error && err.message === '[JustAnalytics] startSpan() requires a callback function.') {
+            return fn();
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=next.js.map

package/dist/integrations/next.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.js","sourceRoot":"","sources":["../../src/integrations/next.ts"],"names":[],"mappings":"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"}

package/dist/integrations/pg.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @file packages/node-sdk/src/integrations/pg.ts
+ * @description PostgreSQL auto-instrumentation integration for the JustAnalytics Node.js SDK.
+ *
+ * Implements Story 039 - PostgreSQL Auto-Instrumentation
+ *
+ * Monkey-patches `pg.Client.prototype.query`, `pg.Pool.prototype.query`, and
+ * `pg.Pool.prototype.connect` to automatically create `db.query` and `db.connect`
+ * spans for all PostgreSQL operations. This captures all PostgreSQL traffic regardless
+ * of which ORM or query builder sits on top (Prisma, Knex, TypeORM, Sequelize, Drizzle).
+ *
+ * Follows the same monkey-patching pattern established in Story 036 (HTTP Auto-Instrumentation):
+ * - Integration class with `enable()`/`disable()` lifecycle methods
+ * - Original function preservation for clean teardown
+ * - Integration with AsyncLocalStorage context for automatic parent-child span relationships
+ * - Fail-open design: if instrumentation code fails, the original query executes normally
+ *
+ * SQL sanitization is a critical security requirement: all literal values (strings,
+ * numbers, booleans) are replaced with `$?` placeholders. Actual query parameter
+ * values are NEVER included in span attributes.
+ *
+ * References:
+ * - OpenTelemetry Database Semantic Conventions (db.system, db.statement, etc.)
+ * - Story 035 - Node.js SDK Core (Span, context, transport)
+ * - Story 036 - HTTP Auto-Instrumentation (integration pattern)
+ */
+import { Span } from '../span';
+/**
+ * Configuration for the PostgreSQL auto-instrumentation integration.
+ */
+export interface PgIntegrationOptions {
+    /** Enable/disable the integration (default: true) */
+    enabled?: boolean;
+    /**
+     * Maximum character length for the db.statement attribute.
+     * SQL queries longer than this are truncated with '...' suffix.
+     * (default: 2048)
+     */
+    maxQueryLength?: number;
+}
+/**
+ * Sanitize a SQL query by replacing literal values with placeholders.
+ *
+ * Rules (applied in order):
+ * 1. Strip block comments (/* ... *​/)
+ * 2. Strip line comments (-- ...)
+ * 3. Replace string literals ('...') with $?
+ * 4. Replace numeric literals with $? (preserving $N parameter placeholders)
+ * 5. Replace boolean literals (TRUE/FALSE) with $?
+ * 6. Normalize whitespace (collapse multiple spaces, trim)
+ * 7. Truncate to maxLength
+ *
+ * @param sql - Raw SQL query string
+ * @param maxLength - Maximum length for the sanitized output (default: 2048)
+ * @returns Sanitized SQL with literals replaced
+ */
+export declare function sanitizeSql(sql: string, maxLength?: number): string;
+/**
+ * Extract the SQL operation keyword from a query string.
+ *
+ * Handles: SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP,
+ * BEGIN, COMMIT, ROLLBACK, TRUNCATE, COPY, EXPLAIN, ANALYZE, WITH (CTE)
+ *
+ * @param sql - Raw or sanitized SQL query
+ * @returns Uppercase operation keyword (e.g., "SELECT"), or "UNKNOWN" if not recognized
+ */
+export declare function extractSqlOperation(sql: string): string;
+/**
+ * Extract the primary table name from a SQL query (best effort).
+ *
+ * Patterns handled:
+ * - SELECT ... FROM table_name
+ * - INSERT INTO table_name
+ * - UPDATE table_name
+ * - DELETE FROM table_name
+ * - Handles schema-qualified names: schema.table
+ * - Handles quoted identifiers: "table_name"
+ *
+ * @param sql - Raw or sanitized SQL query
+ * @returns Table name, or null if extraction fails
+ */
+export declare function extractTableName(sql: string): string | null;
+/**
+ * Build a sanitized connection string from pg client config.
+ * Replaces password with '***'.
+ *
+ * @param connStr - Raw connection string potentially containing a password
+ * @returns Sanitized connection string with password masked
+ */
+export declare function sanitizeConnectionString(connStr: string): string;
+/**
+ * PgIntegration monkey-patches pg.Client.prototype.query,
+ * pg.Pool.prototype.query, and pg.Pool.prototype.connect to auto-create
+ * db.query and db.connect spans for all PostgreSQL operations.
+ *
+ * Follows the same pattern as HttpIntegration (Story 036):
+ * - Constructor accepts serviceName, options, onSpanEnd callback
+ * - enable() patches, disable() restores
+ * - Original functions preserved for clean teardown
+ * - Fail-open design: instrumentation failures never crash the host process
+ */
+export declare class PgIntegration {
+    private _enabled;
+    private _options;
+    private _serviceName;
+    private _onSpanEnd;
+    private _originalClientQuery;
+    private _originalPoolQuery;
+    private _originalPoolConnect;
+    private _pgClient;
+    private _pgPool;
+    /**
+     * Create a new PgIntegration.
+     *
+     * @param serviceName - The service name for span attribution
+     * @param options - Integration configuration options
+     * @param onSpanEnd - Callback invoked when a span ends (enqueues to transport)
+     */
+    constructor(serviceName: string, options: PgIntegrationOptions | undefined, onSpanEnd: (span: Span) => void);
+    /**
+     * Activate the integration: load pg module and patch prototypes.
+     *
+     * Calling enable() when already enabled is a no-op (idempotent).
+     */
+    enable(): void;
+    /**
+     * Deactivate: restore original pg functions.
+     *
+     * Calling disable() when not enabled is a no-op (idempotent).
+     */
+    disable(): void;
+    /**
+     * Restore all patched functions to their originals.
+     */
+    private _restoreOriginals;
+    /**
+     * Wrap pg.Client.prototype.query to create db.query spans.
+     *
+     * Handles all pg query signatures:
+     * 1. client.query(text, callback)
+     * 2. client.query(text, values, callback)
+     * 3. client.query(text) -- promise
+     * 4. client.query(text, values) -- promise
+     * 5. client.query(config) -- QueryConfig object, promise
+     * 6. client.query(config, callback) -- QueryConfig object, callback
+     *
+     * @param original - The original query function
+     * @returns A wrapped version of the query function
+     */
+    private _wrapClientQuery;
+    /**
+     * Wrap pg.Pool.prototype.query to create db.query spans.
+     *
+     * Pool.query is a convenience method that acquires a client, runs the query,
+     * and releases the client. We patch it separately to track pool-level queries.
+     *
+     * @param original - The original Pool.prototype.query function
+     * @returns A wrapped version of the query function
+     */
+    private _wrapPoolQuery;
+    /**
+     * Wrap pg.Pool.prototype.connect to create db.connect spans that measure
+     * the time to acquire a connection from the pool.
+     *
+     * @param original - The original Pool.prototype.connect function
+     * @returns A wrapped version of the connect function
+     */
+    private _wrapPoolConnect;
+}