@justanalyticsapp/node 0.1.0

package/dist/client.js

@@ -0,0 +1,681 @@
+"use strict";
+/**
+ * @file packages/node-sdk/src/client.ts
+ * @description JustAnalyticsClient - the core SDK class managing configuration,
+ * lifecycle, span creation, error capture, context, and transport.
+ *
+ * Implements Story 035 - Node.js SDK Core
+ * Updated for Story 041 - Server-Side Error Tracking via SDK
+ * Updated for Story 046 - SDK Log Integration
+ * Updated for Story 048 - Infrastructure Metrics Collection
+ *
+ * The client is the central orchestrator:
+ * - Validates and stores configuration from `init()`
+ * - Creates spans via `startSpan()` and runs callbacks in AsyncLocalStorage context
+ * - Captures errors via `captureException()` and `captureMessage()`
+ * - Manages the BatchTransport for periodic flushing
+ * - Registers process exit handlers for graceful shutdown
+ * - Registers process error handlers for uncaughtException/unhandledRejection
+ * - Provides `setUser()`, `setTag()`, `getActiveSpan()`, `getTraceId()` context APIs
+ *
+ * When `enabled: false`, all methods become no-ops (spans are not created,
+ * errors are not captured, transport does not flush). This allows toggling
+ * the SDK off in environments where tracing is not desired.
+ *
+ * References:
+ * - src/app/api/ingest/spans/route.ts (target endpoint)
+ * - src/app/api/ingest/errors/route.ts (error ingestion endpoint)
+ * - Expansion Roadmap (architecture decisions, SDK design)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JustAnalyticsClient = void 0;
+const span_1 = require("./span");
+const context_1 = require("./context");
+const transport_1 = require("./transport");
+const id_1 = require("./utils/id");
+const errors_1 = require("./errors");
+const logger_1 = require("./logger");
+const http_1 = require("./integrations/http");
+const pg_1 = require("./integrations/pg");
+const redis_1 = require("./integrations/redis");
+const metrics_1 = require("./integrations/metrics");
+const express_1 = require("./integrations/express");
+/** Default JustAnalytics server URL */
+const DEFAULT_SERVER_URL = 'https://justanalytics.up.railway.app';
+/**
+ * JustAnalyticsClient manages the SDK lifecycle, span creation, error capture,
+ * context propagation, and batched transport.
+ */
+class JustAnalyticsClient {
+    constructor() {
+        this._initialized = false;
+        this._enabled = true;
+        this._serviceName = '';
+        this._debug = false;
+        this._transport = null;
+        this._logger = null;
+        this._httpIntegration = null;
+        this._pgIntegration = null;
+        this._redisIntegration = null;
+        this._metricsIntegration = null;
+        this._exitHandlersRegistered = false;
+        // Store references to bound handlers so we can remove them
+        this._boundBeforeExitHandler = null;
+        this._boundSigtermHandler = null;
+        this._boundSigintHandler = null;
+        // Process error handlers (Story 041)
+        this._boundUncaughtExceptionHandler = null;
+        this._boundUnhandledRejectionHandler = null;
+    }
+    /**
+     * Get a shared no-op Logger instance.
+     * Used when the SDK is not initialized or has been closed.
+     * All methods on this logger are no-ops (enabled: false, transport: null).
+     */
+    static getNoopLogger() {
+        if (!JustAnalyticsClient._noopLogger) {
+            JustAnalyticsClient._noopLogger = new logger_1.Logger({
+                serviceName: 'unknown',
+                transport: null,
+                debug: false,
+                enabled: false,
+            });
+        }
+        return JustAnalyticsClient._noopLogger;
+    }
+    /**
+     * Initialize the SDK with the given options.
+     *
+     * Must be called before any other method. Can only be called once;
+     * subsequent calls log a warning and are ignored (idempotent guard).
+     *
+     * @param options - SDK configuration
+     * @throws Error if required fields (siteId, apiKey, serviceName) are missing
+     */
+    init(options) {
+        if (this._initialized) {
+            console.warn('[JustAnalytics] Warning: init() already called. Ignoring.');
+            return;
+        }
+        // Validate required fields
+        if (!options.siteId) {
+            throw new Error('[JustAnalytics] init() requires "siteId". Get it from your JustAnalytics dashboard.');
+        }
+        if (!options.apiKey) {
+            throw new Error('[JustAnalytics] init() requires "apiKey". Create one in your JustAnalytics site settings.');
+        }
+        if (!options.serviceName) {
+            throw new Error('[JustAnalytics] init() requires "serviceName" (e.g. "api-server", "worker").');
+        }
+        this._enabled = options.enabled !== false;
+        this._serviceName = options.serviceName;
+        this._environment = options.environment;
+        this._release = options.release;
+        this._debug = options.debug === true;
+        const serverUrl = options.serverUrl ||
+            process.env.JUSTANALYTICS_URL ||
+            DEFAULT_SERVER_URL;
+        if (this._debug) {
+            const keyPrefix = options.apiKey.substring(0, 10);
+            console.debug(`[JustAnalytics] Initializing SDK: service=${options.serviceName}, ` +
+                `server=${serverUrl}, apiKey=${keyPrefix}..., enabled=${this._enabled}`);
+        }
+        if (this._enabled) {
+            this._transport = new transport_1.BatchTransport({
+                serverUrl,
+                apiKey: options.apiKey,
+                flushIntervalMs: options.flushIntervalMs ?? 2000,
+                maxBatchSize: options.maxBatchSize ?? 100,
+                debug: this._debug,
+            });
+            this._transport.start();
+            this.registerExitHandlers();
+            // Create Logger instance with transport connected (Story 046)
+            this._logger = new logger_1.Logger({
+                serviceName: this._serviceName,
+                transport: this._transport,
+                debug: this._debug,
+                enabled: this._enabled,
+                environment: this._environment,
+                release: this._release,
+            });
+            // Initialize HTTP auto-instrumentation integration
+            const httpConfig = options.integrations?.http;
+            if (httpConfig !== false) {
+                const httpOptions = typeof httpConfig === 'object' ? httpConfig : undefined;
+                this._httpIntegration = new http_1.HttpIntegration(this._serviceName, serverUrl, httpOptions, (span) => this.enqueueSpan(span));
+                this._httpIntegration.enable();
+            }
+            // Initialize PostgreSQL auto-instrumentation integration
+            const pgConfig = options.integrations?.pg;
+            if (pgConfig !== false) {
+                const pgOptions = typeof pgConfig === 'object' ? pgConfig : undefined;
+                this._pgIntegration = new pg_1.PgIntegration(this._serviceName, pgOptions, (span) => this.enqueueSpan(span));
+                this._pgIntegration.enable();
+            }
+            // Initialize Redis auto-instrumentation integration
+            const redisConfig = options.integrations?.redis;
+            if (redisConfig !== false) {
+                const redisOptions = typeof redisConfig === 'object' ? redisConfig : undefined;
+                this._redisIntegration = new redis_1.RedisIntegration(this._serviceName, redisOptions, (span) => this.enqueueSpan(span));
+                this._redisIntegration.enable();
+            }
+            // Initialize infrastructure metrics integration (Story 048)
+            const metricsConfig = options.integrations?.metrics;
+            if (metricsConfig !== false) {
+                const metricsOptions = typeof metricsConfig === 'object' ? metricsConfig : undefined;
+                this._metricsIntegration = new metrics_1.MetricsIntegration(this._serviceName, this._transport, this._debug, this._environment, metricsOptions);
+                this._metricsIntegration.enable();
+            }
+            // Register process error handlers (Story 041)
+            this.registerProcessErrorHandlers(options);
+        }
+        this._initialized = true;
+    }
+    /**
+     * Whether `init()` has been called successfully.
+     */
+    isInitialized() {
+        return this._initialized;
+    }
+    /**
+     * Get the Logger instance.
+     *
+     * Returns a no-op Logger if init() has not been called yet,
+     * if the SDK is disabled, or after close() has been called.
+     * Never returns null -- always safe to call methods on the result.
+     */
+    get logger() {
+        return this._logger || JustAnalyticsClient.getNoopLogger();
+    }
+    /**
+     * Create and execute a span.
+     *
+     * Creates a new Span, runs the callback inside an AsyncLocalStorage context
+     * with the span as the active span, and ends the span when the callback
+     * completes (sync or async).
+     *
+     * If the callback throws, the span is ended with `status: 'error'` and the
+     * error is re-thrown.
+     *
+     * Supports two signatures:
+     * - `startSpan(name, callback)` -- default options
+     * - `startSpan(name, options, callback)` -- with SpanOptions
+     *
+     * @param name - Operation name for the span
+     * @param callbackOrOptions - Either the callback or SpanOptions
+     * @param maybeCallback - The callback (if options were provided)
+     * @returns The return value of the callback
+     */
+    startSpan(name, callbackOrOptions, maybeCallback) {
+        // Parse overloaded arguments
+        let options;
+        let callback;
+        if (typeof callbackOrOptions === 'function') {
+            callback = callbackOrOptions;
+            options = undefined;
+        }
+        else {
+            options = callbackOrOptions;
+            if (!maybeCallback) {
+                throw new Error('[JustAnalytics] startSpan() requires a callback function.');
+            }
+            callback = maybeCallback;
+        }
+        // No-op if not initialized or disabled
+        if (!this._initialized || !this._enabled) {
+            // Create a dummy span for the callback, but don't enqueue it
+            const dummySpan = new span_1.Span({
+                operationName: name,
+                serviceName: this._serviceName || 'unknown',
+                kind: options?.kind || 'internal',
+                traceId: (0, id_1.generateTraceId)(),
+                parentSpanId: null,
+            });
+            return callback(dummySpan);
+        }
+        // Determine parent span and trace ID
+        let parentSpan = options?.parentSpan || (0, context_1.getActiveSpan)();
+        let traceId;
+        let parentSpanId;
+        if (parentSpan) {
+            traceId = parentSpan.traceId;
+            parentSpanId = parentSpan.id;
+        }
+        else {
+            traceId = (0, id_1.generateTraceId)();
+            parentSpanId = null;
+        }
+        // Merge context tags into initial attributes
+        const contextTags = this.getContextTags();
+        const initialAttributes = {
+            ...contextTags,
+            ...(options?.attributes || {}),
+        };
+        // Add environment and release as attributes if set
+        if (this._environment) {
+            initialAttributes['environment'] = this._environment;
+        }
+        if (this._release) {
+            initialAttributes['release'] = this._release;
+        }
+        // Create the span
+        const span = new span_1.Span({
+            operationName: name,
+            serviceName: this._serviceName,
+            kind: options?.kind || 'internal',
+            traceId,
+            parentSpanId,
+            attributes: initialAttributes,
+        });
+        // Create child context with this span as active
+        const childContext = (0, context_1.createChildContext)({
+            activeSpan: span,
+            traceId,
+        });
+        // Run callback in context
+        return (0, context_1.runWithContext)(childContext, () => {
+            try {
+                const result = callback(span);
+                // Handle async callbacks
+                if (result instanceof Promise) {
+                    return result.then((value) => {
+                        if (!span.isEnded) {
+                            span.end();
+                            this.enqueueSpan(span);
+                        }
+                        return value;
+                    }, (error) => {
+                        if (!span.isEnded) {
+                            span.setStatus('error', error instanceof Error ? error.message : String(error));
+                            span.end();
+                            this.enqueueSpan(span);
+                        }
+                        throw error;
+                    });
+                }
+                // Sync callback completed successfully
+                if (!span.isEnded) {
+                    span.end();
+                    this.enqueueSpan(span);
+                }
+                return result;
+            }
+            catch (error) {
+                // Sync callback threw an error
+                if (!span.isEnded) {
+                    span.setStatus('error', error instanceof Error ? error.message : String(error));
+                    span.end();
+                    this.enqueueSpan(span);
+                }
+                throw error;
+            }
+        });
+    }
+    /**
+     * Capture an exception and send it to JustAnalytics.
+     *
+     * Automatically attaches the current traceId, spanId, user context,
+     * and tags from the AsyncLocalStorage context.
+     *
+     * @param error - Error object (or any value, which will be coerced)
+     * @param options - Optional tags, extra, user, level, fingerprint
+     * @returns A unique eventId string, or empty string if SDK is disabled
+     */
+    captureException(error, options) {
+        if (!this._initialized || !this._enabled)
+            return '';
+        try {
+            const payload = (0, errors_1.buildErrorPayload)(error, options, 'manual', true, this._serviceName, this._environment, this._release, 'error');
+            this.enqueueError(payload);
+            return payload.eventId;
+        }
+        catch (err) {
+            if (this._debug) {
+                console.debug('[JustAnalytics] captureException() internal error:', err);
+            }
+            return '';
+        }
+    }
+    /**
+     * Capture a message and send it to JustAnalytics.
+     *
+     * @param message - The message string
+     * @param levelOrOptions - Severity level or CaptureOptions
+     * @param options - CaptureOptions (if level was provided as second arg)
+     * @returns A unique eventId string, or empty string if SDK is disabled
+     */
+    captureMessage(message, levelOrOptions, options) {
+        if (!this._initialized || !this._enabled)
+            return '';
+        try {
+            let resolvedLevel = 'info';
+            let resolvedOptions;
+            if (typeof levelOrOptions === 'string') {
+                resolvedLevel = levelOrOptions;
+                resolvedOptions = options;
+            }
+            else if (typeof levelOrOptions === 'object') {
+                resolvedOptions = levelOrOptions;
+                resolvedLevel = levelOrOptions.level || 'info';
+            }
+            const payload = (0, errors_1.buildErrorPayload)(message, { ...resolvedOptions, level: resolvedLevel }, 'manual', true, this._serviceName, this._environment, this._release, resolvedLevel);
+            // Override type to 'Message' for captureMessage
+            payload.error.type = 'Message';
+            this.enqueueError(payload);
+            return payload.eventId;
+        }
+        catch (err) {
+            if (this._debug) {
+                console.debug('[JustAnalytics] captureMessage() internal error:', err);
+            }
+            return '';
+        }
+    }
+    /**
+     * Set user context for the current async scope.
+     *
+     * The user context is available to all spans created within this scope.
+     * Uses copy-on-write semantics via AsyncLocalStorage.
+     *
+     * @param user - User context (id, email, username)
+     */
+    setUser(user) {
+        if (!this._initialized || !this._enabled)
+            return;
+        (0, context_1.setUserInContext)(user);
+    }
+    /**
+     * Set a tag for the current async scope.
+     *
+     * Tags are attached as attributes on all spans created within this scope.
+     * Uses copy-on-write semantics via AsyncLocalStorage.
+     *
+     * @param key - Tag key
+     * @param value - Tag value
+     */
+    setTag(key, value) {
+        if (!this._initialized || !this._enabled)
+            return;
+        (0, context_1.setTagInContext)(key, value);
+    }
+    /**
+     * Get the currently active span from AsyncLocalStorage.
+     *
+     * @returns The active Span, or null if not in a traced context
+     */
+    getActiveSpan() {
+        if (!this._initialized || !this._enabled)
+            return null;
+        return (0, context_1.getActiveSpan)();
+    }
+    /**
+     * Get the current trace ID from AsyncLocalStorage.
+     *
+     * @returns The trace ID string, or null if not in a traced context
+     */
+    getTraceId() {
+        if (!this._initialized || !this._enabled)
+            return null;
+        return (0, context_1.getActiveTraceId)();
+    }
+    /**
+     * Get an Express middleware function that updates server span operation
+     * names with the matched Express route pattern.
+     *
+     * @returns Express-compatible middleware: `(req, res, next) => void`
+     */
+    expressMiddleware() {
+        return (0, express_1.expressMiddleware)();
+    }
+    /**
+     * Record a custom infrastructure metric.
+     *
+     * Constructs a MetricPayload with the provided name, value, and tags,
+     * plus serviceName, timestamp, and default tags (hostname, environment).
+     *
+     * @param metricName - Metric name using dot notation (e.g., 'custom.queue_size')
+     * @param value - Numeric value
+     * @param tags - Optional additional tags
+     */
+    recordMetric(metricName, value, tags) {
+        if (!this._initialized || !this._enabled)
+            return;
+        try {
+            const payload = {
+                metricName,
+                value,
+                serviceName: this._serviceName,
+                timestamp: new Date().toISOString(),
+                tags: {
+                    hostname: require('os').hostname(),
+                    ...(this._environment ? { environment: this._environment } : {}),
+                    ...(tags || {}),
+                },
+            };
+            this._transport?.enqueueMetric(payload);
+        }
+        catch (err) {
+            if (this._debug) {
+                console.debug('[JustAnalytics] recordMetric() internal error:', err);
+            }
+        }
+    }
+    /**
+     * Manually flush all pending spans and errors to the server.
+     *
+     * @returns Promise that resolves when the flush completes
+     */
+    async flush() {
+        if (!this._transport)
+            return;
+        await this._transport.flush();
+    }
+    /**
+     * Shut down the SDK: flush remaining data, stop timers, deregister handlers.
+     *
+     * After calling `close()`, the SDK cannot be used again until `init()` is called.
+     */
+    async close() {
+        if (!this._initialized)
+            return;
+        if (this._debug) {
+            console.debug('[JustAnalytics] Closing SDK...');
+        }
+        // Disable HTTP integration (restore original functions)
+        if (this._httpIntegration) {
+            this._httpIntegration.disable();
+            this._httpIntegration = null;
+        }
+        // Disable PostgreSQL integration (restore original functions)
+        if (this._pgIntegration) {
+            this._pgIntegration.disable();
+            this._pgIntegration = null;
+        }
+        // Disable Redis integration (restore original functions)
+        if (this._redisIntegration) {
+            this._redisIntegration.disable();
+            this._redisIntegration = null;
+        }
+        // Disable metrics integration (Story 048)
+        if (this._metricsIntegration) {
+            this._metricsIntegration.disable();
+            this._metricsIntegration = null;
+        }
+        // Flush remaining spans, errors, logs, and metrics
+        if (this._transport) {
+            await this._transport.flush();
+            this._transport.stop();
+            this._transport = null;
+        }
+        // Set logger to null after flush (Story 046)
+        // The getter will return the no-op logger after this
+        this._logger = null;
+        this.deregisterExitHandlers();
+        this.deregisterProcessErrorHandlers();
+        this._initialized = false;
+        if (this._debug) {
+            console.debug('[JustAnalytics] SDK closed.');
+        }
+    }
+    /**
+     * Enqueue an ended span for transport.
+     *
+     * @param span - The ended span to enqueue
+     */
+    enqueueSpan(span) {
+        if (!this._transport)
+            return;
+        this._transport.enqueue(span.toJSON());
+    }
+    /**
+     * Enqueue an error event payload for transport.
+     *
+     * @param payload - The error event payload to enqueue
+     */
+    enqueueError(payload) {
+        if (!this._transport)
+            return;
+        this._transport.enqueueError(payload);
+    }
+    /**
+     * Get tags from the current AsyncLocalStorage context.
+     *
+     * @returns Current context tags, or empty object if none
+     */
+    getContextTags() {
+        return (0, context_1.getTags)();
+    }
+    /**
+     * Register process error handlers for uncaught exceptions and unhandled rejections.
+     *
+     * These handlers capture the error via the SDK and ensure it is sent to the server.
+     * For uncaughtException, the process exits after a 2-second safety timeout.
+     * For unhandledRejection, the error is batched (process continues).
+     *
+     * @param options - SDK configuration options
+     */
+    registerProcessErrorHandlers(options) {
+        // Register uncaught exception handler
+        if (options.enableUncaughtExceptionHandler !== false) {
+            this._boundUncaughtExceptionHandler = (error) => {
+                try {
+                    const payload = (0, errors_1.buildErrorPayload)(error, { level: 'fatal', tags: { 'error.mechanism': 'uncaughtException' } }, 'uncaughtException', false, this._serviceName, this._environment, this._release, 'fatal');
+                    // Send immediately (not batched) since process is about to exit
+                    if (this._transport) {
+                        this._transport.sendErrorImmediate(payload);
+                        // Also flush any pending spans and errors
+                        this._transport.flush().catch(() => { });
+                    }
+                }
+                catch {
+                    // Never throw from the handler
+                }
+                // Safety net: exit after 2 seconds regardless
+                const exitTimer = setTimeout(() => process.exit(1), 2000);
+                if (typeof exitTimer.unref === 'function') {
+                    exitTimer.unref();
+                }
+            };
+            process.on('uncaughtException', this._boundUncaughtExceptionHandler);
+        }
+        // Register unhandled rejection handler
+        if (options.enableUnhandledRejectionHandler !== false) {
+            this._boundUnhandledRejectionHandler = (reason) => {
+                try {
+                    const payload = (0, errors_1.buildErrorPayload)(reason, { level: 'error', tags: { 'error.mechanism': 'unhandledRejection' } }, 'unhandledRejection', false, this._serviceName, this._environment, this._release, 'error');
+                    this.enqueueError(payload);
+                }
+                catch {
+                    // Never throw from the handler
+                }
+            };
+            process.on('unhandledRejection', this._boundUnhandledRejectionHandler);
+        }
+    }
+    /**
+     * Deregister process error handlers.
+     *
+     * Called by `close()` to clean up uncaughtException and unhandledRejection listeners.
+     */
+    deregisterProcessErrorHandlers() {
+        if (this._boundUncaughtExceptionHandler) {
+            process.removeListener('uncaughtException', this._boundUncaughtExceptionHandler);
+            this._boundUncaughtExceptionHandler = null;
+        }
+        if (this._boundUnhandledRejectionHandler) {
+            process.removeListener('unhandledRejection', this._boundUnhandledRejectionHandler);
+            this._boundUnhandledRejectionHandler = null;
+        }
+    }
+    /**
+     * Register process exit handlers to flush remaining spans on shutdown.
+     *
+     * Handlers are registered only once (tracked by `_exitHandlersRegistered`).
+     */
+    registerExitHandlers() {
+        if (this._exitHandlersRegistered)
+            return;
+        this._boundBeforeExitHandler = () => {
+            if (this._transport && this._transport.pendingCount > 0) {
+                if (this._debug) {
+                    console.debug(`[JustAnalytics] Process beforeExit: flushing ${this._transport.pendingCount} pending span(s)...`);
+                }
+                // beforeExit allows async work that will re-trigger the event
+                this._transport.flush().catch(() => { });
+            }
+        };
+        this._boundSigtermHandler = () => {
+            if (this._debug) {
+                console.debug('[JustAnalytics] Received SIGTERM, flushing...');
+            }
+            if (this._transport) {
+                this._transport.flush().then(() => process.exit(0), () => process.exit(0));
+            }
+            else {
+                process.exit(0);
+            }
+        };
+        this._boundSigintHandler = () => {
+            if (this._debug) {
+                console.debug('[JustAnalytics] Received SIGINT, flushing...');
+            }
+            if (this._transport) {
+                this._transport.flush().then(() => process.exit(0), () => process.exit(0));
+            }
+            else {
+                process.exit(0);
+            }
+        };
+        process.on('beforeExit', this._boundBeforeExitHandler);
+        process.on('SIGTERM', this._boundSigtermHandler);
+        process.on('SIGINT', this._boundSigintHandler);
+        this._exitHandlersRegistered = true;
+    }
+    /**
+     * Deregister process exit handlers.
+     *
+     * Called by `close()` to clean up all registered handlers.
+     */
+    deregisterExitHandlers() {
+        if (!this._exitHandlersRegistered)
+            return;
+        if (this._boundBeforeExitHandler) {
+            process.removeListener('beforeExit', this._boundBeforeExitHandler);
+            this._boundBeforeExitHandler = null;
+        }
+        if (this._boundSigtermHandler) {
+            process.removeListener('SIGTERM', this._boundSigtermHandler);
+            this._boundSigtermHandler = null;
+        }
+        if (this._boundSigintHandler) {
+            process.removeListener('SIGINT', this._boundSigintHandler);
+            this._boundSigintHandler = null;
+        }
+        this._exitHandlersRegistered = false;
+    }
+}
+exports.JustAnalyticsClient = JustAnalyticsClient;
+// Lazy no-op logger for pre-init access (Story 046)
+JustAnalyticsClient._noopLogger = null;
+//# sourceMappingURL=client.js.map