@justanalyticsapp/node 0.1.0

package/dist/integrations/winston.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * @file packages/node-sdk/src/integrations/winston.ts
+ * @description Winston transport for JustAnalytics log integration.
+ *
+ * Implements Story 046 - SDK Log Integration
+ *
+ * Pipes Winston log entries through the JustAnalytics SDK logger,
+ * automatically attaching trace context and batching for transport.
+ *
+ * Usage:
+ * ```typescript
+ * import winston from 'winston';
+ * import { JustAnalyticsWinstonTransport } from '@justanalyticsapp/node/winston';
+ *
+ * const logger = winston.createLogger({
+ *   transports: [
+ *     new winston.transports.Console(),
+ *     new JustAnalyticsWinstonTransport(),
+ *   ],
+ * });
+ * ```
+ *
+ * The transport requires `winston` and `winston-transport` as peer dependencies.
+ * Install them separately: `npm install winston winston-transport`
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JustAnalyticsWinstonTransport = void 0;
+/** Winston to JustAnalytics level mapping */
+const DEFAULT_LEVEL_MAP = {
+    error: 'error',
+    warn: 'warn',
+    info: 'info',
+    http: 'debug',
+    verbose: 'debug',
+    debug: 'debug',
+    silly: 'debug',
+    fatal: 'fatal',
+};
+// Dynamically load winston-transport at runtime (optional peer dependency)
+let TransportStreamBase;
+try {
+    TransportStreamBase = require('winston-transport');
+}
+catch {
+    // winston-transport not installed -- class will throw on construction
+    TransportStreamBase = null;
+}
+/**
+ * Winston transport that forwards log entries to JustAnalytics.
+ *
+ * Extracts message, level, and metadata from Winston info objects
+ * and pipes them through JA.logger for batched transport with
+ * automatic trace context attachment.
+ */
+class JustAnalyticsWinstonTransport {
+    constructor(opts) {
+        if (!TransportStreamBase) {
+            throw new Error('[JustAnalytics] winston-transport is required for the Winston integration. ' +
+                'Install it with: npm install winston-transport');
+        }
+        // Call the parent TransportStream constructor
+        TransportStreamBase.call(this, opts);
+        this.levelMap = opts?.levelMap
+            ? { ...DEFAULT_LEVEL_MAP, ...opts.levelMap }
+            : { ...DEFAULT_LEVEL_MAP };
+    }
+    log(info, callback) {
+        try {
+            // Strip ANSI escape codes from the level string
+            const winstonLevel = (info.level || 'info').replace(/\u001b\[\d+m/g, '');
+            const mappedLevel = this.levelMap[winstonLevel] || 'info';
+            const message = info.message || '';
+            // Extract attributes (everything except level, message, and Winston symbols)
+            const attributes = {};
+            for (const key of Object.keys(info)) {
+                if (key !== 'level' && key !== 'message') {
+                    attributes[key] = info[key];
+                }
+            }
+            // Lazy require to avoid circular dependency at module load time
+            const JA = require('../index').default;
+            if (JA && JA.logger) {
+                JA.logger.log(mappedLevel, message, attributes);
+            }
+        }
+        catch {
+            // Never throw from a transport
+        }
+        callback();
+    }
+}
+exports.JustAnalyticsWinstonTransport = JustAnalyticsWinstonTransport;
+// Set up prototype chain to extend TransportStream
+if (TransportStreamBase) {
+    // Inherit from TransportStream
+    Object.setPrototypeOf(JustAnalyticsWinstonTransport.prototype, TransportStreamBase.prototype);
+}
+//# sourceMappingURL=winston.js.map

package/dist/integrations/winston.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"winston.js","sourceRoot":"","sources":["../../src/integrations/winston.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;;AAIH,6CAA6C;AAC7C,MAAM,iBAAiB,GAA6B;IAClD,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,OAAO;IACb,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;CACf,CAAC;AAaF,2EAA2E;AAC3E,IAAI,mBAAwB,CAAC;AAC7B,IAAI,CAAC;IACH,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;AACrD,CAAC;AAAC,MAAM,CAAC;IACP,sEAAsE;IACtE,mBAAmB,GAAG,IAAI,CAAC;AAC7B,CAAC;AAED;;;;;;GAMG;AACH,MAAa,6BAA6B;IAGxC,YAAY,IAA2C;QACrD,IAAI,CAAC,mBAAmB,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACb,6EAA6E;gBAC7E,gDAAgD,CACjD,CAAC;QACJ,CAAC;QAED,8CAA8C;QAC9C,mBAAmB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAErC,IAAI,CAAC,QAAQ,GAAG,IAAI,EAAE,QAAQ;YAC5B,CAAC,CAAC,EAAE,GAAG,iBAAiB,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE;YAC5C,CAAC,CAAC,EAAE,GAAG,iBAAiB,EAAE,CAAC;IAC/B,CAAC;IAED,GAAG,CAAC,IAAS,EAAE,QAAoB;QACjC,IAAI,CAAC;YACH,gDAAgD;YAChD,MAAM,YAAY,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC;YACzE,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,MAAM,CAAC;YAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;YAEnC,6EAA6E;YAC7E,MAAM,UAAU,GAA4B,EAAE,CAAC;YAC/C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBACpC,IAAI,GAAG,KAAK,OAAO,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;oBACzC,UAAU,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;gBAC9B,CAAC;YACH,CAAC;YAED,gEAAgE;YAChE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC;YACvC,IAAI,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC;gBACpB,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;YAClD,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,+BAA+B;QACjC,CAAC;QAED,QAAQ,EAAE,CAAC;IACb,CAAC;CACF;AA7CD,sEA6CC;AAED,mDAAmD;AACnD,IAAI,mBAAmB,EAAE,CAAC;IACxB,+BAA+B;IAC/B,MAAM,CAAC,cAAc,CACnB,6BAA6B,CAAC,SAAS,EACvC,mBAAmB,CAAC,SAAS,CAC9B,CAAC;AACJ,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,148 @@
+/**
+ * @file packages/node-sdk/src/logger.ts
+ * @description Structured logger with automatic trace context correlation.
+ *
+ * Implements Story 046 - SDK Log Integration
+ *
+ * The Logger class provides structured logging methods (debug, info, warn, error, fatal)
+ * that automatically attach traceId and spanId from the AsyncLocalStorage context.
+ * Log entries are buffered in the BatchTransport and flushed periodically to
+ * POST /api/ingest/logs.
+ *
+ * Usage:
+ * ```typescript
+ * JA.logger.info('User logged in', { userId: 'u123', method: 'oauth' });
+ * JA.logger.error('Payment failed', { orderId, amount, reason });
+ * JA.logger.debug('Cache hit', { key: 'prefs:u123', ttl: 3600 });
+ * ```
+ *
+ * All methods are no-ops when the SDK is not initialized or disabled.
+ * All methods are fail-safe (never throw).
+ *
+ * References:
+ * - src/app/api/ingest/logs/route.ts (target endpoint and expected payload format)
+ * - Story 045 (Log Ingestion Model and API)
+ */
+import type { BatchTransport } from './transport';
+/**
+ * Valid log severity levels matching the POST /api/ingest/logs Zod schema.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/**
+ * Serialized log entry payload matching the logEntrySchema in POST /api/ingest/logs.
+ *
+ * This is the wire format sent to the server. Field names and types match
+ * the Zod validation schema in src/app/api/ingest/logs/route.ts exactly.
+ */
+export interface LogPayload {
+    /** Log severity level */
+    level: LogLevel;
+    /** Log message (1-10000 chars, per server Zod schema) */
+    message: string;
+    /** Service name from SDK init config (1-128 chars) */
+    serviceName: string;
+    /** ISO 8601 timestamp of when the log was created */
+    timestamp: string;
+    /** 32-char hex trace ID from AsyncLocalStorage context, or null */
+    traceId: string | null;
+    /** 16-char hex span ID from AsyncLocalStorage context, or null */
+    spanId: string | null;
+    /** Arbitrary key-value metadata */
+    attributes: Record<string, unknown>;
+}
+/**
+ * Internal configuration for the Logger instance.
+ * Created by JustAnalyticsClient during init().
+ */
+export interface LoggerConfig {
+    /** Service name from SDK init config */
+    serviceName: string;
+    /** BatchTransport reference for enqueuing logs (null when disabled) */
+    transport: BatchTransport | null;
+    /** Whether debug logging is enabled */
+    debug: boolean;
+    /** Whether the SDK is enabled */
+    enabled: boolean;
+    /** Deployment environment (optional, attached as attribute) */
+    environment?: string;
+    /** Release version (optional, attached as attribute) */
+    release?: string;
+}
+/**
+ * Logger provides structured logging methods with automatic trace correlation.
+ *
+ * Log entries are buffered in the BatchTransport and flushed periodically
+ * to POST /api/ingest/logs. traceId and spanId are automatically attached
+ * from the AsyncLocalStorage context when logging inside a traced scope.
+ *
+ * All methods are no-ops when the SDK is not initialized or disabled.
+ * All methods are fail-safe (never throw).
+ */
+export declare class Logger {
+    private readonly _serviceName;
+    private readonly _transport;
+    private readonly _debug;
+    private readonly _enabled;
+    private readonly _environment?;
+    private readonly _release?;
+    constructor(config: LoggerConfig);
+    /**
+     * Log a debug-level message.
+     *
+     * @param message - Log message string
+     * @param attributes - Optional key-value metadata
+     */
+    debug(message: string, attributes?: Record<string, unknown>): void;
+    /**
+     * Log an info-level message.
+     *
+     * @param message - Log message string
+     * @param attributes - Optional key-value metadata
+     */
+    info(message: string, attributes?: Record<string, unknown>): void;
+    /**
+     * Log a warn-level message.
+     *
+     * @param message - Log message string
+     * @param attributes - Optional key-value metadata
+     */
+    warn(message: string, attributes?: Record<string, unknown>): void;
+    /**
+     * Log an error-level message.
+     *
+     * @param message - Log message string
+     * @param attributes - Optional key-value metadata
+     */
+    error(message: string, attributes?: Record<string, unknown>): void;
+    /**
+     * Log a fatal-level message.
+     *
+     * @param message - Log message string
+     * @param attributes - Optional key-value metadata
+     */
+    fatal(message: string, attributes?: Record<string, unknown>): void;
+    /**
+     * Log a message at the specified level.
+     *
+     * Generic method for programmatic level selection. All level-specific
+     * methods (debug, info, warn, error, fatal) delegate to this.
+     *
+     * @param level - Log severity level
+     * @param message - Log message string
+     * @param attributes - Optional key-value metadata
+     */
+    log(level: LogLevel, message: string, attributes?: Record<string, unknown>): void;
+    /**
+     * Internal log method that constructs the LogPayload and enqueues it.
+     *
+     * Reads traceId and spanId from the AsyncLocalStorage context automatically.
+     * Enriches attributes with environment and release if configured.
+     *
+     * Never throws -- all errors are caught and logged in debug mode.
+     *
+     * @param level - Log severity level
+     * @param message - Log message string
+     * @param attributes - Optional key-value metadata
+     */
+    private _log;
+}

package/dist/logger.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * @file packages/node-sdk/src/logger.ts
+ * @description Structured logger with automatic trace context correlation.
+ *
+ * Implements Story 046 - SDK Log Integration
+ *
+ * The Logger class provides structured logging methods (debug, info, warn, error, fatal)
+ * that automatically attach traceId and spanId from the AsyncLocalStorage context.
+ * Log entries are buffered in the BatchTransport and flushed periodically to
+ * POST /api/ingest/logs.
+ *
+ * Usage:
+ * ```typescript
+ * JA.logger.info('User logged in', { userId: 'u123', method: 'oauth' });
+ * JA.logger.error('Payment failed', { orderId, amount, reason });
+ * JA.logger.debug('Cache hit', { key: 'prefs:u123', ttl: 3600 });
+ * ```
+ *
+ * All methods are no-ops when the SDK is not initialized or disabled.
+ * All methods are fail-safe (never throw).
+ *
+ * References:
+ * - src/app/api/ingest/logs/route.ts (target endpoint and expected payload format)
+ * - Story 045 (Log Ingestion Model and API)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+const context_1 = require("./context");
+/**
+ * Logger provides structured logging methods with automatic trace correlation.
+ *
+ * Log entries are buffered in the BatchTransport and flushed periodically
+ * to POST /api/ingest/logs. traceId and spanId are automatically attached
+ * from the AsyncLocalStorage context when logging inside a traced scope.
+ *
+ * All methods are no-ops when the SDK is not initialized or disabled.
+ * All methods are fail-safe (never throw).
+ */
+class Logger {
+    constructor(config) {
+        this._serviceName = config.serviceName;
+        this._transport = config.transport;
+        this._debug = config.debug;
+        this._enabled = config.enabled;
+        this._environment = config.environment;
+        this._release = config.release;
+    }
+    /**
+     * Log a debug-level message.
+     *
+     * @param message - Log message string
+     * @param attributes - Optional key-value metadata
+     */
+    debug(message, attributes) {
+        this._log('debug', message, attributes);
+    }
+    /**
+     * Log an info-level message.
+     *
+     * @param message - Log message string
+     * @param attributes - Optional key-value metadata
+     */
+    info(message, attributes) {
+        this._log('info', message, attributes);
+    }
+    /**
+     * Log a warn-level message.
+     *
+     * @param message - Log message string
+     * @param attributes - Optional key-value metadata
+     */
+    warn(message, attributes) {
+        this._log('warn', message, attributes);
+    }
+    /**
+     * Log an error-level message.
+     *
+     * @param message - Log message string
+     * @param attributes - Optional key-value metadata
+     */
+    error(message, attributes) {
+        this._log('error', message, attributes);
+    }
+    /**
+     * Log a fatal-level message.
+     *
+     * @param message - Log message string
+     * @param attributes - Optional key-value metadata
+     */
+    fatal(message, attributes) {
+        this._log('fatal', message, attributes);
+    }
+    /**
+     * Log a message at the specified level.
+     *
+     * Generic method for programmatic level selection. All level-specific
+     * methods (debug, info, warn, error, fatal) delegate to this.
+     *
+     * @param level - Log severity level
+     * @param message - Log message string
+     * @param attributes - Optional key-value metadata
+     */
+    log(level, message, attributes) {
+        this._log(level, message, attributes);
+    }
+    /**
+     * Internal log method that constructs the LogPayload and enqueues it.
+     *
+     * Reads traceId and spanId from the AsyncLocalStorage context automatically.
+     * Enriches attributes with environment and release if configured.
+     *
+     * Never throws -- all errors are caught and logged in debug mode.
+     *
+     * @param level - Log severity level
+     * @param message - Log message string
+     * @param attributes - Optional key-value metadata
+     */
+    _log(level, message, attributes) {
+        // No-op if SDK is disabled or no transport
+        if (!this._enabled || !this._transport)
+            return;
+        // Validate message: must be a non-empty string
+        if (!message || typeof message !== 'string' || message.length === 0)
+            return;
+        try {
+            // Read trace context from AsyncLocalStorage
+            const activeSpan = (0, context_1.getActiveSpan)();
+            const traceId = (0, context_1.getActiveTraceId)();
+            const spanId = activeSpan?.id ?? null;
+            // Build enriched attributes
+            const enrichedAttributes = { ...(attributes || {}) };
+            if (this._environment) {
+                enrichedAttributes['environment'] = this._environment;
+            }
+            if (this._release) {
+                enrichedAttributes['release'] = this._release;
+            }
+            const payload = {
+                level,
+                message,
+                serviceName: this._serviceName,
+                timestamp: new Date().toISOString(),
+                traceId: traceId ?? null,
+                spanId: spanId ?? null,
+                attributes: enrichedAttributes,
+            };
+            if (this._debug) {
+                console.debug(`[JustAnalytics Logger] ${level.toUpperCase()} "${message}" traceId=${traceId || 'none'}`);
+            }
+            this._transport.enqueueLog(payload);
+        }
+        catch (err) {
+            if (this._debug) {
+                console.debug('[JustAnalytics Logger] Internal error:', err);
+            }
+            // Never throw from logger methods
+        }
+    }
+}
+exports.Logger = Logger;
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;;AAEH,uCAA4D;AAkD5D;;;;;;;;;GASG;AACH,MAAa,MAAM;IAQjB,YAAY,MAAoB;QAC9B,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC;IACjC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAe,EAAE,UAAoC;QACzD,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,OAAe,EAAE,UAAoC;QACxD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IACzC,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,OAAe,EAAE,UAAoC;QACxD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IACzC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAe,EAAE,UAAoC;QACzD,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAe,EAAE,UAAoC;QACzD,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;;;;;OASG;IACH,GAAG,CAAC,KAAe,EAAE,OAAe,EAAE,UAAoC;QACxE,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IACxC,CAAC;IAED;;;;;;;;;;;OAWG;IACK,IAAI,CAAC,KAAe,EAAE,OAAe,EAAE,UAAoC;QACjF,2CAA2C;QAC3C,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,OAAO;QAE/C,+CAA+C;QAC/C,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAE5E,IAAI,CAAC;YACH,4CAA4C;YAC5C,MAAM,UAAU,GAAG,IAAA,uBAAa,GAAE,CAAC;YACnC,MAAM,OAAO,GAAG,IAAA,0BAAgB,GAAE,CAAC;YACnC,MAAM,MAAM,GAAG,UAAU,EAAE,EAAE,IAAI,IAAI,CAAC;YAEtC,4BAA4B;YAC5B,MAAM,kBAAkB,GAA4B,EAAE,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE,CAAC;YAC9E,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;gBACtB,kBAAkB,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC;YACxD,CAAC;YACD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAClB,kBAAkB,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;YAChD,CAAC;YAED,MAAM,OAAO,GAAe;gBAC1B,KAAK;gBACL,OAAO;gBACP,WAAW,EAAE,IAAI,CAAC,YAAY;gBAC9B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,OAAO,EAAE,OAAO,IAAI,IAAI;gBACxB,MAAM,EAAE,MAAM,IAAI,IAAI;gBACtB,UAAU,EAAE,kBAAkB;aAC/B,CAAC;YAEF,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChB,OAAO,CAAC,KAAK,CACX,0BAA0B,KAAK,CAAC,WAAW,EAAE,KAAK,OAAO,aAAa,OAAO,IAAI,MAAM,EAAE,CAC1F,CAAC;YACJ,CAAC;YAED,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChB,OAAO,CAAC,KAAK,CAAC,wCAAwC,EAAE,GAAG,CAAC,CAAC;YAC/D,CAAC;YACD,kCAAkC;QACpC,CAAC;IACH,CAAC;CACF;AA3ID,wBA2IC"}

package/dist/span.d.ts

@@ -0,0 +1,192 @@
+/**
+ * @file packages/node-sdk/src/span.ts
+ * @description Span class for distributed tracing with high-resolution timing.
+ *
+ * Implements Story 035 - Node.js SDK Core
+ *
+ * Each Span records a timed operation within a trace. Spans are created by
+ * `JA.startSpan()` and automatically ended when the callback completes.
+ * The `toJSON()` method serializes the span to the exact format expected by
+ * `POST /api/ingest/spans` (see the Zod schema in route.ts).
+ *
+ * Timing uses `process.hrtime.bigint()` for nanosecond-resolution monotonic
+ * measurement, then converts to integer milliseconds via Math.round.
+ *
+ * References:
+ * - src/app/api/ingest/spans/route.ts (Zod schema the payload must match)
+ * - W3C Trace Context (traceId/spanId format)
+ */
+/** Valid span kinds (OpenTelemetry-compatible) */
+export type SpanKind = 'client' | 'server' | 'producer' | 'consumer' | 'internal';
+/** Valid span statuses */
+export type SpanStatus = 'ok' | 'error' | 'unset';
+/** Options for creating a new span via JA.startSpan() */
+export interface SpanOptions {
+    /** Span kind (default: 'internal') */
+    kind?: SpanKind;
+    /** Initial attributes to set on the span */
+    attributes?: Record<string, unknown>;
+    /** Explicit parent span (overrides AsyncLocalStorage context) */
+    parentSpan?: Span;
+}
+/** A timestamped event attached to a span */
+export interface SpanEvent {
+    /** Event name */
+    name: string;
+    /** ISO 8601 timestamp of the event */
+    timestamp: string;
+    /** Optional event attributes */
+    attributes?: Record<string, unknown>;
+}
+/** Serialized span payload matching the /api/ingest/spans Zod schema */
+export interface SpanPayload {
+    id: string;
+    traceId: string;
+    parentSpanId: string | null;
+    operationName: string;
+    serviceName: string;
+    kind: SpanKind;
+    startTime: string;
+    endTime: string | null;
+    duration: number | null;
+    status: SpanStatus;
+    statusMessage: string | null;
+    attributes: Record<string, unknown>;
+    events: SpanEvent[];
+}
+/** Parameters for constructing a Span */
+export interface SpanConstructorParams {
+    /** Operation/span name (e.g. "POST /api/users", "db.query") */
+    operationName: string;
+    /** Service that produced this span (e.g. "api-server", "worker") */
+    serviceName: string;
+    /** Span kind */
+    kind: SpanKind;
+    /** Trace ID (32-char hex) -- inherited from parent or newly generated */
+    traceId: string;
+    /** Parent span ID (16-char hex) or null for root spans */
+    parentSpanId: string | null;
+    /** Initial attributes */
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Span represents a single timed operation within a distributed trace.
+ *
+ * Spans are created by `JA.startSpan()` and ended either automatically
+ * when the callback completes, or manually via `span.end()`.
+ *
+ * @example
+ * ```typescript
+ * JA.startSpan('process-order', (span) => {
+ *   span.setAttribute('order.id', '12345');
+ *   span.addEvent('payment.processed');
+ *   // span.end() is called automatically
+ * });
+ * ```
+ */
+export declare class Span {
+    /** 16-character hex span ID */
+    readonly id: string;
+    /** 32-character hex trace ID (shared across all spans in a trace) */
+    readonly traceId: string;
+    /** Parent span ID, or null for root spans */
+    readonly parentSpanId: string | null;
+    /** Operation name (e.g. "POST /api/users", "db.query") */
+    readonly operationName: string;
+    /** Service name (e.g. "api-server") */
+    readonly serviceName: string;
+    /** Span kind */
+    readonly kind: SpanKind;
+    /** Wall-clock start time */
+    readonly startTime: Date;
+    /** High-resolution monotonic start time (nanoseconds) for precise duration */
+    readonly startHrTime: bigint;
+    private _endTime;
+    private _duration;
+    private _status;
+    private _statusMessage;
+    private _attributes;
+    private _events;
+    private _ended;
+    constructor(params: SpanConstructorParams);
+    /**
+     * Set a single attribute on the span.
+     *
+     * @param key - Attribute key (e.g. "http.method", "db.statement")
+     * @param value - Attribute value
+     * @returns this (for chaining)
+     */
+    setAttribute(key: string, value: unknown): this;
+    /**
+     * Set multiple attributes on the span.
+     *
+     * @param attrs - Key-value pairs to merge into attributes
+     * @returns this (for chaining)
+     */
+    setAttributes(attrs: Record<string, unknown>): this;
+    /**
+     * Set the span's status.
+     *
+     * @param status - One of 'ok', 'error', 'unset'
+     * @param message - Optional status message (typically for errors)
+     * @returns this (for chaining)
+     */
+    setStatus(status: SpanStatus, message?: string): this;
+    /**
+     * Add a timestamped event to the span.
+     *
+     * Events represent notable moments during the span's lifetime
+     * (e.g. "cache.miss", "retry.attempt", "payment.processed").
+     *
+     * @param name - Event name
+     * @param attributes - Optional event attributes
+     * @returns this (for chaining)
+     */
+    addEvent(name: string, attributes?: Record<string, unknown>): this;
+    /**
+     * Update the operation name after span creation.
+     *
+     * Used by auto-instrumentation integrations to refine the operation name
+     * after additional context is available (e.g., Express route matching
+     * provides `/api/users/:id` instead of the raw URL `/api/users/42`).
+     *
+     * No-op if the span has already ended.
+     *
+     * @param name - The new operation name
+     * @returns this (for chaining)
+     */
+    updateOperationName(name: string): this;
+    /**
+     * Mark the span as ended.
+     *
+     * Calculates duration using `process.hrtime.bigint()` for sub-millisecond
+     * precision, then rounds to an integer millisecond value to match the
+     * server's `z.number().int()` Zod validation.
+     *
+     * Calling `end()` multiple times is a no-op (idempotent).
+     */
+    end(): void;
+    /** Whether this span has been ended */
+    get isEnded(): boolean;
+    /**
+     * Serialize the span to the JSON payload format expected by
+     * `POST /api/ingest/spans`.
+     *
+     * The output matches the Zod schema defined in
+     * `src/app/api/ingest/spans/route.ts` exactly:
+     * - `id`: 16-char hex
+     * - `traceId`: 32-char hex
+     * - `parentSpanId`: 16-char hex or null
+     * - `operationName`: string (1-256 chars)
+     * - `serviceName`: string (1-128 chars)
+     * - `kind`: one of the SpanKind values
+     * - `startTime`: ISO 8601 string
+     * - `endTime`: ISO 8601 string or null
+     * - `duration`: integer milliseconds or null
+     * - `status`: one of the SpanStatus values
+     * - `statusMessage`: string or null
+     * - `attributes`: object
+     * - `events`: array of event objects
+     */
+    toJSON(): SpanPayload;
+}