@justanalyticsapp/node 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,286 @@
+/**
+ * @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)
+ */
+import { Span, SpanOptions } from './span';
+import { UserContext } from './context';
+import { CaptureOptions } from './errors';
+import { Logger } from './logger';
+import { HttpIntegrationOptions } from './integrations/http';
+import { PgIntegrationOptions } from './integrations/pg';
+import { RedisIntegrationOptions } from './integrations/redis';
+import { MetricsIntegrationOptions } from './integrations/metrics';
+import { expressMiddleware as createExpressMiddleware } from './integrations/express';
+/**
+ * Configuration options for initializing the JustAnalytics SDK.
+ */
+export interface JustAnalyticsOptions {
+    /** Site ID from JustAnalytics dashboard (required) */
+    siteId: string;
+    /** API key from JustAnalytics dashboard, format: ja_sk_... (required) */
+    apiKey: string;
+    /** Service name, e.g. "api-server", "worker" (required) */
+    serviceName: string;
+    /** Deployment environment, e.g. "production", "staging" */
+    environment?: string;
+    /** Release/version string, e.g. "1.2.3", git SHA */
+    release?: string;
+    /** Base URL of JustAnalytics server (default: JUSTANALYTICS_URL env or production URL) */
+    serverUrl?: string;
+    /** Enable debug logging to console.debug (default: false) */
+    debug?: boolean;
+    /** Flush interval in milliseconds (default: 2000) */
+    flushIntervalMs?: number;
+    /** Maximum spans per batch before immediate flush (default: 100) */
+    maxBatchSize?: number;
+    /** Enable/disable the SDK (default: true). When false, all methods are no-ops */
+    enabled?: boolean;
+    /**
+     * Register a process.on('uncaughtException') handler that captures the
+     * error, flushes pending data, and exits with code 1.
+     * (default: true)
+     */
+    enableUncaughtExceptionHandler?: boolean;
+    /**
+     * Register a process.on('unhandledRejection') handler that captures the
+     * rejection reason as an error event.
+     * (default: true)
+     */
+    enableUnhandledRejectionHandler?: boolean;
+    /**
+     * Integration configuration.
+     * - `http: true` enables HTTP auto-instrumentation with defaults
+     * - `http: false` disables HTTP auto-instrumentation
+     * - `http: { ... }` enables with custom options (HttpIntegrationOptions)
+     */
+    integrations?: {
+        http?: boolean | HttpIntegrationOptions;
+        pg?: boolean | PgIntegrationOptions;
+        redis?: boolean | RedisIntegrationOptions;
+        metrics?: boolean | MetricsIntegrationOptions;
+    };
+}
+/**
+ * JustAnalyticsClient manages the SDK lifecycle, span creation, error capture,
+ * context propagation, and batched transport.
+ */
+export declare class JustAnalyticsClient {
+    private _initialized;
+    private _enabled;
+    private _serviceName;
+    private _environment;
+    private _release;
+    private _debug;
+    private _transport;
+    private _logger;
+    private _httpIntegration;
+    private _pgIntegration;
+    private _redisIntegration;
+    private _metricsIntegration;
+    private _exitHandlersRegistered;
+    private _boundBeforeExitHandler;
+    private _boundSigtermHandler;
+    private _boundSigintHandler;
+    private _boundUncaughtExceptionHandler;
+    private _boundUnhandledRejectionHandler;
+    private static _noopLogger;
+    /**
+     * 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).
+     */
+    private static getNoopLogger;
+    /**
+     * 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: JustAnalyticsOptions): void;
+    /**
+     * Whether `init()` has been called successfully.
+     */
+    isInitialized(): boolean;
+    /**
+     * 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(): Logger;
+    /**
+     * 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<T>(name: string, callbackOrOptions: ((span: Span) => T) | SpanOptions, maybeCallback?: (span: Span) => T): T;
+    /**
+     * 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: unknown, options?: CaptureOptions): string;
+    /**
+     * 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: string, levelOrOptions?: 'debug' | 'info' | 'warning' | 'error' | 'fatal' | CaptureOptions, options?: CaptureOptions): string;
+    /**
+     * 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: UserContext): void;
+    /**
+     * 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: string, value: string): void;
+    /**
+     * Get the currently active span from AsyncLocalStorage.
+     *
+     * @returns The active Span, or null if not in a traced context
+     */
+    getActiveSpan(): Span | null;
+    /**
+     * Get the current trace ID from AsyncLocalStorage.
+     *
+     * @returns The trace ID string, or null if not in a traced context
+     */
+    getTraceId(): string | null;
+    /**
+     * 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(): ReturnType<typeof createExpressMiddleware>;
+    /**
+     * 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: string, value: number, tags?: Record<string, unknown>): void;
+    /**
+     * Manually flush all pending spans and errors to the server.
+     *
+     * @returns Promise that resolves when the flush completes
+     */
+    flush(): Promise<void>;
+    /**
+     * Shut down the SDK: flush remaining data, stop timers, deregister handlers.
+     *
+     * After calling `close()`, the SDK cannot be used again until `init()` is called.
+     */
+    close(): Promise<void>;
+    /**
+     * Enqueue an ended span for transport.
+     *
+     * @param span - The ended span to enqueue
+     */
+    private enqueueSpan;
+    /**
+     * Enqueue an error event payload for transport.
+     *
+     * @param payload - The error event payload to enqueue
+     */
+    private enqueueError;
+    /**
+     * Get tags from the current AsyncLocalStorage context.
+     *
+     * @returns Current context tags, or empty object if none
+     */
+    private getContextTags;
+    /**
+     * 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
+     */
+    private registerProcessErrorHandlers;
+    /**
+     * Deregister process error handlers.
+     *
+     * Called by `close()` to clean up uncaughtException and unhandledRejection listeners.
+     */
+    private deregisterProcessErrorHandlers;
+    /**
+     * Register process exit handlers to flush remaining spans on shutdown.
+     *
+     * Handlers are registered only once (tracked by `_exitHandlersRegistered`).
+     */
+    private registerExitHandlers;
+    /**
+     * Deregister process exit handlers.
+     *
+     * Called by `close()` to clean up all registered handlers.
+     */
+    private deregisterExitHandlers;
+}