@justanalyticsapp/node 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,301 @@
+/**
+ * @file packages/node-sdk/src/index.ts
+ * @description Public API surface for @justanalyticsapp/node SDK.
+ *
+ * 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
+ *
+ * This module creates a singleton JustAnalyticsClient instance and exports
+ * both a default namespace object (`JA`) and individual named exports for
+ * tree-shaking.
+ *
+ * Usage (default import):
+ * ```typescript
+ * import JA from '@justanalyticsapp/node';
+ * JA.init({ siteId: '...', apiKey: '...', serviceName: 'api-server' });
+ * ```
+ *
+ * Usage (named imports):
+ * ```typescript
+ * import { init, startSpan, setUser, flush, captureException } from '@justanalyticsapp/node';
+ * init({ siteId: '...', apiKey: '...', serviceName: 'api-server' });
+ * ```
+ *
+ * References:
+ * - Expansion Roadmap: "SDK auto-instruments by default. Users get value with two lines of code."
+ */
+import { JustAnalyticsOptions } from './client';
+import { Span, SpanOptions, SpanKind, SpanStatus, SpanPayload, SpanEvent } from './span';
+import { UserContext, TraceContext } from './context';
+import { CaptureOptions, ServerErrorPayload } from './errors';
+import { Logger, LogPayload, LogLevel } from './logger';
+import { parseTraceparent, serializeTraceparent, TraceparentData } from './utils/headers';
+import { generateTraceId, generateSpanId } from './utils/id';
+import { HttpIntegrationOptions } from './integrations/http';
+import { PgIntegrationOptions } from './integrations/pg';
+import { RedisIntegrationOptions } from './integrations/redis';
+import { MetricsIntegrationOptions, MetricPayload } from './integrations/metrics';
+import { expressMiddleware as createExpressMiddleware } from './integrations/express';
+import type { NextJustAnalyticsOptions, NextRequestLike, NextResponseLike, NextRouteHandler, NextMiddlewareFunction, ServerComponentFunction } from './integrations/next';
+/**
+ * Initialize the JustAnalytics SDK.
+ *
+ * Must be called before any other SDK method. Can only be called once;
+ * subsequent calls log a warning and are ignored.
+ *
+ * @param options - SDK configuration (siteId, apiKey, serviceName are required)
+ * @throws Error if required fields are missing
+ *
+ * @example
+ * ```typescript
+ * import JA from '@justanalyticsapp/node';
+ *
+ * JA.init({
+ *   siteId: 'site_abc123',
+ *   apiKey: 'ja_sk_your_api_key_here',
+ *   serviceName: 'api-server',
+ *   environment: 'production',
+ *   debug: false,
+ * });
+ * ```
+ */
+declare function init(options: JustAnalyticsOptions): void;
+/**
+ * Whether `init()` has been called successfully.
+ *
+ * @returns true if the SDK is initialized, false otherwise
+ */
+declare function isInitialized(): boolean;
+/**
+ * Create and execute a span.
+ *
+ * The callback runs inside an AsyncLocalStorage context with the span
+ * as the active span. Nested `startSpan()` calls automatically create
+ * parent-child relationships.
+ *
+ * @param name - Operation name for the span
+ * @param callback - Function to execute within the span
+ * @returns The return value of the callback
+ *
+ * @example
+ * ```typescript
+ * // Simple sync span
+ * const result = JA.startSpan('process-order', (span) => {
+ *   span.setAttribute('order.id', '12345');
+ *   return processOrder();
+ * });
+ *
+ * // Async span
+ * const data = await JA.startSpan('fetch-user', async (span) => {
+ *   span.setAttribute('user.id', userId);
+ *   return await db.users.findUnique({ where: { id: userId } });
+ * });
+ *
+ * // With options
+ * JA.startSpan('http-call', { kind: 'client' }, async (span) => {
+ *   return await fetch('https://api.example.com/data');
+ * });
+ * ```
+ */
+declare function startSpan<T>(name: string, callback: (span: Span) => T): T;
+declare function startSpan<T>(name: string, options: SpanOptions, callback: (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 (non-Error values are coerced to string)
+ * @param options - Optional tags, extra, user, level, fingerprint
+ * @returns A unique eventId for correlation, or empty string if SDK is disabled
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   JA.captureException(error, { tags: { module: 'payments' } });
+ * }
+ * ```
+ */
+declare function captureException(error: unknown, options?: CaptureOptions): string;
+/**
+ * Capture a message and send it to JustAnalytics.
+ *
+ * @param message - The message string
+ * @param level - Severity level (default: 'info')
+ * @param options - Optional tags, extra, user, fingerprint
+ * @returns A unique eventId for correlation, or empty string if SDK is disabled
+ *
+ * @example
+ * ```typescript
+ * JA.captureMessage('User exceeded rate limit', 'warning', {
+ *   tags: { userId: user.id },
+ *   extra: { requestCount: count },
+ * });
+ * ```
+ */
+declare function captureMessage(message: string, level?: 'debug' | 'info' | 'warning' | 'error' | 'fatal', options?: CaptureOptions): string;
+/**
+ * Set user context for the current async scope.
+ *
+ * User information is attached as attributes on all spans created
+ * within the current AsyncLocalStorage scope.
+ *
+ * @param user - User context (id, email, username)
+ *
+ * @example
+ * ```typescript
+ * JA.setUser({ id: 'user-123', email: 'alice@example.com' });
+ * ```
+ */
+declare function setUser(user: UserContext): void;
+/**
+ * Set a tag for the current async scope.
+ *
+ * Tags are attached as attributes on all spans created within the
+ * current AsyncLocalStorage scope.
+ *
+ * @param key - Tag key
+ * @param value - Tag value
+ *
+ * @example
+ * ```typescript
+ * JA.setTag('feature', 'checkout');
+ * JA.setTag('region', 'us-east-1');
+ * ```
+ */
+declare function 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
+ */
+declare function getActiveSpan(): Span | null;
+/**
+ * Get the current trace ID from AsyncLocalStorage.
+ *
+ * @returns The trace ID string, or null if not in a traced context
+ */
+declare function getTraceId(): string | null;
+/**
+ * Manually flush all pending spans and errors to the server.
+ *
+ * Useful for ensuring data is sent before a serverless function
+ * completes, or in tests.
+ *
+ * @returns Promise that resolves when the flush completes
+ *
+ * @example
+ * ```typescript
+ * // In a serverless handler
+ * export async function handler(event) {
+ *   const result = await JA.startSpan('handler', async (span) => {
+ *     return await processEvent(event);
+ *   });
+ *   await JA.flush(); // Ensure spans are sent
+ *   return result;
+ * }
+ * ```
+ */
+declare function flush(): Promise<void>;
+/**
+ * Get an Express middleware function that updates server span operation
+ * names with the matched Express route pattern.
+ *
+ * Register with `app.use(JA.expressMiddleware())` to have span names
+ * reflect Express route patterns (e.g., `GET /api/users/:id`) instead
+ * of raw URL paths (e.g., `GET /api/users/42`).
+ *
+ * @returns Express-compatible middleware: `(req, res, next) => void`
+ *
+ * @example
+ * ```typescript
+ * import JA from '@justanalyticsapp/node';
+ * import express from 'express';
+ *
+ * JA.init({ siteId: '...', apiKey: '...', serviceName: 'api' });
+ *
+ * const app = express();
+ * app.use(JA.expressMiddleware());
+ *
+ * app.get('/api/users/:id', handler);
+ * ```
+ */
+declare function expressMiddleware(): ReturnType<typeof createExpressMiddleware>;
+/**
+ * Shut down the SDK: flush remaining spans, stop timers, deregister handlers.
+ *
+ * Call this during graceful shutdown of your application.
+ *
+ * @returns Promise that resolves when shutdown is complete
+ *
+ * @example
+ * ```typescript
+ * process.on('SIGTERM', async () => {
+ *   await JA.close();
+ *   process.exit(0);
+ * });
+ * ```
+ */
+declare function close(): Promise<void>;
+/**
+ * Record a custom infrastructure metric.
+ *
+ * @param metricName - Metric name using dot notation (e.g., 'custom.queue_size')
+ * @param value - Numeric value
+ * @param tags - Optional additional tags
+ *
+ * @example
+ * ```typescript
+ * JA.recordMetric('custom.queue_size', 42, { queue: 'emails' });
+ * JA.recordMetric('custom.request_duration_ms', 150.5);
+ * ```
+ */
+declare function recordMetric(metricName: string, value: number, tags?: Record<string, unknown>): void;
+/**
+ * JustAnalytics SDK namespace object.
+ *
+ * Provides all SDK methods as a single object for convenient default import:
+ * ```typescript
+ * import JA from '@justanalyticsapp/node';
+ * JA.init({ ... });
+ * JA.startSpan('op', (span) => { ... });
+ * JA.captureException(error);
+ * JA.captureMessage('hello', 'info');
+ * ```
+ */
+declare const JA: {
+    init: typeof init;
+    isInitialized: typeof isInitialized;
+    startSpan: typeof startSpan;
+    captureException: typeof captureException;
+    captureMessage: typeof captureMessage;
+    setUser: typeof setUser;
+    setTag: typeof setTag;
+    getActiveSpan: typeof getActiveSpan;
+    getTraceId: typeof getTraceId;
+    expressMiddleware: typeof expressMiddleware;
+    flush: typeof flush;
+    close: typeof close;
+    recordMetric: typeof recordMetric;
+    /**
+     * Logger instance for structured logging with automatic trace correlation.
+     *
+     * Returns a no-op Logger before `init()` is called or after `close()`.
+     * Safe to access at any time -- never null, never throws.
+     *
+     * @example
+     * ```typescript
+     * JA.logger.info('User logged in', { userId: 'u123' });
+     * JA.logger.error('Payment failed', { orderId, reason });
+     * ```
+     */
+    readonly logger: Logger;
+};
+export default JA;
+export { init, isInitialized, startSpan, captureException, captureMessage, setUser, setTag, getActiveSpan, getTraceId, expressMiddleware, flush, close, recordMetric, };
+export type { JustAnalyticsOptions, SpanOptions, SpanKind, SpanStatus, SpanPayload, SpanEvent, UserContext, TraceContext, TraceparentData, HttpIntegrationOptions, PgIntegrationOptions, RedisIntegrationOptions, CaptureOptions, ServerErrorPayload, NextJustAnalyticsOptions, NextRequestLike, NextResponseLike, NextRouteHandler, NextMiddlewareFunction, ServerComponentFunction, LogPayload, LogLevel, MetricPayload, MetricsIntegrationOptions, };
+export { Span, parseTraceparent, serializeTraceparent, generateTraceId, generateSpanId, Logger };

package/dist/index.js

@@ -0,0 +1,314 @@
+"use strict";
+/**
+ * @file packages/node-sdk/src/index.ts
+ * @description Public API surface for @justanalyticsapp/node SDK.
+ *
+ * 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
+ *
+ * This module creates a singleton JustAnalyticsClient instance and exports
+ * both a default namespace object (`JA`) and individual named exports for
+ * tree-shaking.
+ *
+ * Usage (default import):
+ * ```typescript
+ * import JA from '@justanalyticsapp/node';
+ * JA.init({ siteId: '...', apiKey: '...', serviceName: 'api-server' });
+ * ```
+ *
+ * Usage (named imports):
+ * ```typescript
+ * import { init, startSpan, setUser, flush, captureException } from '@justanalyticsapp/node';
+ * init({ siteId: '...', apiKey: '...', serviceName: 'api-server' });
+ * ```
+ *
+ * References:
+ * - Expansion Roadmap: "SDK auto-instruments by default. Users get value with two lines of code."
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = exports.generateSpanId = exports.generateTraceId = exports.serializeTraceparent = exports.parseTraceparent = exports.Span = void 0;
+exports.init = init;
+exports.isInitialized = isInitialized;
+exports.startSpan = startSpan;
+exports.captureException = captureException;
+exports.captureMessage = captureMessage;
+exports.setUser = setUser;
+exports.setTag = setTag;
+exports.getActiveSpan = getActiveSpan;
+exports.getTraceId = getTraceId;
+exports.expressMiddleware = expressMiddleware;
+exports.flush = flush;
+exports.close = close;
+exports.recordMetric = recordMetric;
+const client_1 = require("./client");
+const span_1 = require("./span");
+Object.defineProperty(exports, "Span", { enumerable: true, get: function () { return span_1.Span; } });
+const logger_1 = require("./logger");
+Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return logger_1.Logger; } });
+const headers_1 = require("./utils/headers");
+Object.defineProperty(exports, "parseTraceparent", { enumerable: true, get: function () { return headers_1.parseTraceparent; } });
+Object.defineProperty(exports, "serializeTraceparent", { enumerable: true, get: function () { return headers_1.serializeTraceparent; } });
+const id_1 = require("./utils/id");
+Object.defineProperty(exports, "generateTraceId", { enumerable: true, get: function () { return id_1.generateTraceId; } });
+Object.defineProperty(exports, "generateSpanId", { enumerable: true, get: function () { return id_1.generateSpanId; } });
+// ---------- Singleton Client ----------
+/** Singleton client instance */
+const client = new client_1.JustAnalyticsClient();
+// ---------- Public API Functions ----------
+/**
+ * Initialize the JustAnalytics SDK.
+ *
+ * Must be called before any other SDK method. Can only be called once;
+ * subsequent calls log a warning and are ignored.
+ *
+ * @param options - SDK configuration (siteId, apiKey, serviceName are required)
+ * @throws Error if required fields are missing
+ *
+ * @example
+ * ```typescript
+ * import JA from '@justanalyticsapp/node';
+ *
+ * JA.init({
+ *   siteId: 'site_abc123',
+ *   apiKey: 'ja_sk_your_api_key_here',
+ *   serviceName: 'api-server',
+ *   environment: 'production',
+ *   debug: false,
+ * });
+ * ```
+ */
+function init(options) {
+    client.init(options);
+}
+/**
+ * Whether `init()` has been called successfully.
+ *
+ * @returns true if the SDK is initialized, false otherwise
+ */
+function isInitialized() {
+    return client.isInitialized();
+}
+function startSpan(name, callbackOrOptions, maybeCallback) {
+    return client.startSpan(name, callbackOrOptions, maybeCallback);
+}
+/**
+ * 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 (non-Error values are coerced to string)
+ * @param options - Optional tags, extra, user, level, fingerprint
+ * @returns A unique eventId for correlation, or empty string if SDK is disabled
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   JA.captureException(error, { tags: { module: 'payments' } });
+ * }
+ * ```
+ */
+function captureException(error, options) {
+    return client.captureException(error, options);
+}
+/**
+ * Capture a message and send it to JustAnalytics.
+ *
+ * @param message - The message string
+ * @param level - Severity level (default: 'info')
+ * @param options - Optional tags, extra, user, fingerprint
+ * @returns A unique eventId for correlation, or empty string if SDK is disabled
+ *
+ * @example
+ * ```typescript
+ * JA.captureMessage('User exceeded rate limit', 'warning', {
+ *   tags: { userId: user.id },
+ *   extra: { requestCount: count },
+ * });
+ * ```
+ */
+function captureMessage(message, level, options) {
+    return client.captureMessage(message, level, options);
+}
+/**
+ * Set user context for the current async scope.
+ *
+ * User information is attached as attributes on all spans created
+ * within the current AsyncLocalStorage scope.
+ *
+ * @param user - User context (id, email, username)
+ *
+ * @example
+ * ```typescript
+ * JA.setUser({ id: 'user-123', email: 'alice@example.com' });
+ * ```
+ */
+function setUser(user) {
+    client.setUser(user);
+}
+/**
+ * Set a tag for the current async scope.
+ *
+ * Tags are attached as attributes on all spans created within the
+ * current AsyncLocalStorage scope.
+ *
+ * @param key - Tag key
+ * @param value - Tag value
+ *
+ * @example
+ * ```typescript
+ * JA.setTag('feature', 'checkout');
+ * JA.setTag('region', 'us-east-1');
+ * ```
+ */
+function setTag(key, value) {
+    client.setTag(key, value);
+}
+/**
+ * Get the currently active span from AsyncLocalStorage.
+ *
+ * @returns The active Span, or null if not in a traced context
+ */
+function getActiveSpan() {
+    return client.getActiveSpan();
+}
+/**
+ * Get the current trace ID from AsyncLocalStorage.
+ *
+ * @returns The trace ID string, or null if not in a traced context
+ */
+function getTraceId() {
+    return client.getTraceId();
+}
+/**
+ * Manually flush all pending spans and errors to the server.
+ *
+ * Useful for ensuring data is sent before a serverless function
+ * completes, or in tests.
+ *
+ * @returns Promise that resolves when the flush completes
+ *
+ * @example
+ * ```typescript
+ * // In a serverless handler
+ * export async function handler(event) {
+ *   const result = await JA.startSpan('handler', async (span) => {
+ *     return await processEvent(event);
+ *   });
+ *   await JA.flush(); // Ensure spans are sent
+ *   return result;
+ * }
+ * ```
+ */
+function flush() {
+    return client.flush();
+}
+/**
+ * Get an Express middleware function that updates server span operation
+ * names with the matched Express route pattern.
+ *
+ * Register with `app.use(JA.expressMiddleware())` to have span names
+ * reflect Express route patterns (e.g., `GET /api/users/:id`) instead
+ * of raw URL paths (e.g., `GET /api/users/42`).
+ *
+ * @returns Express-compatible middleware: `(req, res, next) => void`
+ *
+ * @example
+ * ```typescript
+ * import JA from '@justanalyticsapp/node';
+ * import express from 'express';
+ *
+ * JA.init({ siteId: '...', apiKey: '...', serviceName: 'api' });
+ *
+ * const app = express();
+ * app.use(JA.expressMiddleware());
+ *
+ * app.get('/api/users/:id', handler);
+ * ```
+ */
+function expressMiddleware() {
+    return client.expressMiddleware();
+}
+/**
+ * Shut down the SDK: flush remaining spans, stop timers, deregister handlers.
+ *
+ * Call this during graceful shutdown of your application.
+ *
+ * @returns Promise that resolves when shutdown is complete
+ *
+ * @example
+ * ```typescript
+ * process.on('SIGTERM', async () => {
+ *   await JA.close();
+ *   process.exit(0);
+ * });
+ * ```
+ */
+function close() {
+    return client.close();
+}
+/**
+ * Record a custom infrastructure metric.
+ *
+ * @param metricName - Metric name using dot notation (e.g., 'custom.queue_size')
+ * @param value - Numeric value
+ * @param tags - Optional additional tags
+ *
+ * @example
+ * ```typescript
+ * JA.recordMetric('custom.queue_size', 42, { queue: 'emails' });
+ * JA.recordMetric('custom.request_duration_ms', 150.5);
+ * ```
+ */
+function recordMetric(metricName, value, tags) {
+    client.recordMetric(metricName, value, tags);
+}
+// ---------- Default Export: JA namespace object ----------
+/**
+ * JustAnalytics SDK namespace object.
+ *
+ * Provides all SDK methods as a single object for convenient default import:
+ * ```typescript
+ * import JA from '@justanalyticsapp/node';
+ * JA.init({ ... });
+ * JA.startSpan('op', (span) => { ... });
+ * JA.captureException(error);
+ * JA.captureMessage('hello', 'info');
+ * ```
+ */
+const JA = {
+    init,
+    isInitialized,
+    startSpan,
+    captureException,
+    captureMessage,
+    setUser,
+    setTag,
+    getActiveSpan,
+    getTraceId,
+    expressMiddleware,
+    flush,
+    close,
+    recordMetric,
+    /**
+     * Logger instance for structured logging with automatic trace correlation.
+     *
+     * Returns a no-op Logger before `init()` is called or after `close()`.
+     * Safe to access at any time -- never null, never throws.
+     *
+     * @example
+     * ```typescript
+     * JA.logger.info('User logged in', { userId: 'u123' });
+     * JA.logger.error('Payment failed', { orderId, reason });
+     * ```
+     */
+    get logger() {
+        return client.logger;
+    },
+};
+exports.default = JA;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/integrations/express.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @file packages/node-sdk/src/integrations/express.ts
+ * @description Express middleware for route pattern extraction in JustAnalytics spans.
+ *
+ * Implements Story 036 - HTTP Auto-Instrumentation
+ *
+ * When the HTTP integration creates a server span for an incoming request,
+ * the operation name defaults to `{method} {raw URL}` (e.g., `GET /api/users/42`).
+ * This middleware updates the operation name to use Express route patterns
+ * (e.g., `GET /api/users/:id`) for more meaningful span names.
+ *
+ * The middleware uses `res.on('finish')` to read `req.route` after Express
+ * completes route matching, ensuring it works regardless of middleware ordering.
+ *
+ * Usage:
+ * ```typescript
+ * import JA from '@justanalyticsapp/node';
+ * import express from 'express';
+ *
+ * const app = express();
+ * app.use(JA.expressMiddleware());
+ *
+ * app.get('/api/users/:id', (req, res) => {
+ *   // Span operation name will be updated to "GET /api/users/:id"
+ *   res.json({ id: req.params.id });
+ * });
+ * ```
+ *
+ * References:
+ * - Express routing: req.route is populated after route matching
+ * - Story 035 - Node.js SDK Core (Span class, context module)
+ */
+/**
+ * Minimal Express types to avoid a runtime dependency on the express package.
+ * We only need the shapes for req, res, and next.
+ */
+interface ExpressRequest {
+    method?: string;
+    path?: string;
+    route?: {
+        path?: string;
+    };
+}
+interface ExpressResponse {
+    on(event: string, listener: (...args: unknown[]) => void): void;
+}
+type ExpressNextFunction = (err?: unknown) => void;
+/**
+ * Express middleware that extracts `req.route.path` and updates the
+ * active span's operation name to use the route pattern instead
+ * of the raw URL.
+ *
+ * Must be registered via `app.use()` so it runs for all routes.
+ * The route pattern extraction happens in `res.on('finish')`,
+ * which fires after route matching is complete.
+ *
+ * If the SDK is not initialized or no active span exists, the
+ * middleware is a no-op and simply calls `next()`.
+ *
+ * @returns Express-compatible middleware function: `(req, res, next) => void`
+ *
+ * @example
+ * ```typescript
+ * import JA from '@justanalyticsapp/node';
+ * import express from 'express';
+ *
+ * JA.init({ siteId: '...', apiKey: '...', serviceName: 'api' });
+ *
+ * const app = express();
+ * app.use(JA.expressMiddleware());
+ *
+ * app.get('/api/users/:id', handler);
+ * // Span operationName: "GET /api/users/:id" (instead of "GET /api/users/42")
+ * ```
+ */
+export declare function expressMiddleware(): (req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => void;
+export {};