@foam-ai/node-cliengo 0.1.0-alpha.1

package/dist/node-cliengo/src/trace-bridge.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * W3C trace context bridge between New Relic and OpenTelemetry.
+ *
+ * Why this file exists:
+ *   NR owns the active trace (it creates transactions via http monkey-patching),
+ *   but our OTel spans need to share the same traceId so Foam and NR traces
+ *   correlate. This module reads NR's trace metadata and converts it to/from
+ *   W3C traceparent format (`00-{traceId}-{spanId}-{flags}`).
+ *
+ * Functions:
+ *   - buildTraceparent(): reads NR's active traceId/spanId, returns a W3C
+ *     traceparent string. Used by producers to inject into SNS attributes or
+ *     BullMQ/Bull job data. Returns undefined when NR is not loaded or no
+ *     active transaction exists.
+ *   - extractParentContext(): parses a traceparent string into an OTel Context
+ *     with a remote SpanContext. Used by consumers to link their OTel spans
+ *     back to the producer's trace. Returns ROOT_CONTEXT on malformed input.
+ *   - getTraceContext(): returns { traceId, spanId, traceparent } for log
+ *     enrichment. Called lazily at log-write time (not at format creation time)
+ *     so the trace context is always current.
+ *
+ * Edge cases covered:
+ *   - NR not loaded: getTraceMetadata() returns undefined — we default to
+ *     empty strings, buildTraceparent returns undefined, getTraceContext
+ *     returns empty strings. No crash.
+ *   - NR loaded but no active transaction: traceId/spanId are empty strings.
+ *     buildTraceparent returns undefined. Consumers create a fresh trace.
+ *   - Malformed traceparent (wrong number of parts, wrong hex lengths):
+ *     extractParentContext returns ROOT_CONTEXT — consumer creates a fresh
+ *     trace instead of crashing.
+ *   - Flags field always set to 01 (sampled) on buildTraceparent because we
+ *     want all async boundary crossings traced.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTraceparent = buildTraceparent;
+exports.extractParentContext = extractParentContext;
+exports.getTraceContext = getTraceContext;
+exports.getActiveContext = getActiveContext;
+const api_1 = require("@opentelemetry/api");
+const nr_1 = require("./nr");
+function buildTraceparent() {
+    const nr = (0, nr_1.getNr)();
+    const meta = nr.getTraceMetadata?.() ?? { traceId: '', spanId: '' };
+    const { traceId, spanId } = meta;
+    if (!traceId || !spanId) {
+        return undefined;
+    }
+    return `00-${traceId}-${spanId}-01`;
+}
+function extractParentContext(traceparent) {
+    const parts = traceparent.split('-');
+    if (parts.length < 4 || !parts[1] || !parts[2]) {
+        return api_1.ROOT_CONTEXT;
+    }
+    const traceId = parts[1];
+    const spanId = parts[2];
+    if (traceId.length !== 32 || spanId.length !== 16) {
+        return api_1.ROOT_CONTEXT;
+    }
+    const spanContext = {
+        traceId,
+        spanId,
+        traceFlags: parseInt(parts[3] ?? '0', 16),
+        isRemote: true,
+    };
+    return api_1.trace.setSpanContext(api_1.ROOT_CONTEXT, spanContext);
+}
+function getTraceContext() {
+    const nr = (0, nr_1.getNr)();
+    const meta = nr.getTraceMetadata?.() ?? { traceId: '', spanId: '' };
+    const traceId = meta.traceId ?? '';
+    const spanId = meta.spanId ?? '';
+    const traceparent = traceId && spanId ? `00-${traceId}-${spanId}-01` : '';
+    return { traceId, spanId, traceparent };
+}
+function getActiveContext() {
+    return api_1.context.active();
+}

package/dist/node-cliengo/src/types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * All public interfaces and minimal type stubs for @foam/node-cliengo.
+ *
+ * Why this file exists:
+ *   Defines every public type the library exposes (OtelBridge, InitOptions,
+ *   TraceContext, BridgeMetrics) plus lightweight stubs for external frameworks
+ *   (Express, Fastify, Winston, Pino, New Relic). These stubs exist so the
+ *   library never imports framework types at the top level — services that only
+ *   use Pino don't need Winston installed, and vice versa.
+ *
+ * Edge cases covered:
+ *   - NewRelicAgent: all methods are optional (?) because hsm-backend may have
+ *     NR disabled entirely, and the stub API returns empty values.
+ *   - WinstonLogger.add is optional because @cliengo/logger's internal Winston
+ *     instance may not expose it.
+ *   - SqsMessage.MessageAttributes uses { StringValue?, DataType? } to handle
+ *     both SQS-native attributes and SNS-envelope-wrapped attributes.
+ *   - Express/Fastify types use `any` deliberately — the library must work with
+ *     any Express 4/5 or Fastify 4/5 version without requiring their types as
+ *     dependencies.
+ *   - Meter/Histogram/Counter/ObservableGauge are derived from MeterProvider's
+ *     return types to stay in sync with whatever OTel SDK version is installed.
+ */
+import type { Context, Tracer } from '@opentelemetry/api';
+import type { LoggerProvider } from '@opentelemetry/sdk-logs';
+import type { MeterProvider } from '@opentelemetry/sdk-metrics';
+import type { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
+export interface InitOptions {
+    enabled?: boolean;
+    newrelic?: NewRelicAgent;
+    winston?: WinstonLogger;
+    enableTraces?: boolean;
+    enableLogs?: boolean;
+    enableMetrics?: boolean;
+    endpoint?: string;
+    forceExport?: boolean;
+    autoShutdown?: boolean;
+}
+export interface TraceContext {
+    traceId: string;
+    spanId: string;
+    traceparent: string;
+}
+export interface BridgeMetrics {
+    messageProcessingDuration: Histogram;
+    messageProcessingErrors: Counter;
+    messagesProcessed: Counter;
+    customHistogram(name: string, description: string, unit?: string): Histogram;
+    customCounter(name: string, description: string, unit?: string): Counter;
+    customGauge(name: string, description: string, unit?: string): ObservableGauge;
+}
+export interface OtelBridge {
+    tracer: Tracer;
+    meter: Meter;
+    logger: LoggerProvider;
+    traceProvider: BasicTracerProvider;
+    meterProvider: MeterProvider;
+    loggerProvider: LoggerProvider;
+    metrics: BridgeMetrics;
+    getTraceContext(): TraceContext;
+    createExpressMiddleware(): ExpressRequestHandler;
+    createExpressErrorHandler(): ExpressErrorHandler;
+    createFastifyPlugin(): FastifyPluginAsync;
+    createWinstonFormat(): WinstonFormat;
+    createWinstonTransport(): WinstonTransport;
+    createPinoMixin(): () => Record<string, string>;
+    createPinoDestination(): NodeJS.WritableStream;
+    buildTraceparent(): string | undefined;
+    injectSnsAttributes(attrs: Record<string, SnsMessageAttributeValue>): Record<string, SnsMessageAttributeValue>;
+    injectJobData<T extends Record<string, unknown>>(data: T): T & {
+        traceparent?: string;
+    };
+    wrapSqsConsumer(tracer: Tracer, spanName: string, msg: SqsMessage, fn: () => Promise<void>): Promise<void>;
+    wrapJobConsumer(tracer: Tracer, spanName: string, jobData: Record<string, unknown>, fn: () => Promise<void>): Promise<void>;
+    extractParentContext(traceparent: string): Context;
+    shutdown(): Promise<void>;
+}
+export interface NewRelicAgent {
+    getTransaction?(): unknown;
+    startBackgroundTransaction?(name: string, group: string, handler: () => unknown): unknown;
+    getTraceMetadata?(): {
+        traceId?: string;
+        spanId?: string;
+    };
+    acceptDistributedTraceHeaders?(transportType: string, headers: Record<string, string>): void;
+}
+export interface WinstonLogger {
+    add?(transport: unknown): void;
+    format?: unknown;
+    level?: string;
+}
+export interface SnsMessageAttributeValue {
+    DataType: string;
+    StringValue?: string;
+}
+export interface SqsMessage {
+    MessageId?: string;
+    Body?: string;
+    MessageAttributes?: Record<string, {
+        StringValue?: string;
+        DataType?: string;
+    }>;
+    ReceiptHandle?: string;
+}
+export type ExpressRequestHandler = (req: any, res: any, next: (err?: any) => void) => void;
+export type ExpressErrorHandler = (err: any, req: any, res: any, next: (err?: any) => void) => void;
+export type FastifyPluginAsync = (instance: any, opts: any) => Promise<void>;
+export type WinstonFormat = {
+    transform: (info: any) => any;
+};
+export type WinstonTransport = object;
+export type Meter = ReturnType<MeterProvider['getMeter']>;
+export type Histogram = ReturnType<Meter['createHistogram']>;
+export type Counter = ReturnType<Meter['createCounter']>;
+export type ObservableGauge = ReturnType<Meter['createObservableGauge']>;

package/dist/node-cliengo/src/types.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * All public interfaces and minimal type stubs for @foam/node-cliengo.
+ *
+ * Why this file exists:
+ *   Defines every public type the library exposes (OtelBridge, InitOptions,
+ *   TraceContext, BridgeMetrics) plus lightweight stubs for external frameworks
+ *   (Express, Fastify, Winston, Pino, New Relic). These stubs exist so the
+ *   library never imports framework types at the top level — services that only
+ *   use Pino don't need Winston installed, and vice versa.
+ *
+ * Edge cases covered:
+ *   - NewRelicAgent: all methods are optional (?) because hsm-backend may have
+ *     NR disabled entirely, and the stub API returns empty values.
+ *   - WinstonLogger.add is optional because @cliengo/logger's internal Winston
+ *     instance may not expose it.
+ *   - SqsMessage.MessageAttributes uses { StringValue?, DataType? } to handle
+ *     both SQS-native attributes and SNS-envelope-wrapped attributes.
+ *   - Express/Fastify types use `any` deliberately — the library must work with
+ *     any Express 4/5 or Fastify 4/5 version without requiring their types as
+ *     dependencies.
+ *   - Meter/Histogram/Counter/ObservableGauge are derived from MeterProvider's
+ *     return types to stay in sync with whatever OTel SDK version is installed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-enable @typescript-eslint/no-explicit-any */

package/dist/shared/constants.d.ts

@@ -0,0 +1 @@
+export declare const FOAM_OTEL_ENDPOINT = "https://otel.api.foam.ai";

package/dist/shared/constants.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FOAM_OTEL_ENDPOINT = void 0;
+exports.FOAM_OTEL_ENDPOINT = 'https://otel.api.foam.ai';

package/dist/shared/util.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Wraps a function to ensure it never throws by swallowing errors.
+ *
+ * @example
+ * export const init = safe((options: Options) => {
+ *   // Implementation that might throw
+ * });
+ */
+export declare function safe<T extends (...args: any[]) => any>(fn: T): T;

package/dist/shared/util.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safe = safe;
+/**
+ * Wraps a function to ensure it never throws by swallowing errors.
+ *
+ * @example
+ * export const init = safe((options: Options) => {
+ *   // Implementation that might throw
+ * });
+ */
+function safe(fn) {
+    return ((...args) => {
+        try {
+            return fn(...args);
+        }
+        catch {
+            return undefined;
+        }
+    });
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@foam-ai/node-cliengo",
+  "version": "0.1.0-alpha.1",
+  "description": "Unified observability (traces, logs, metrics) for Cliengo Node.js services, bridging New Relic APM with Foam's OTel collector.",
+  "main": "dist/node-cliengo/src/index.js",
+  "types": "dist/node-cliengo/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/node-cliengo/src/index.d.ts",
+      "import": "./dist/node-cliengo/src/index.js",
+      "require": "./dist/node-cliengo/src/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "newrelic": ">=12.0.0",
+    "winston": "^3.0.0",
+    "pino": "^8.0.0 || ^9.0.0"
+  },
+  "peerDependenciesMeta": {
+    "newrelic": {
+      "optional": true
+    },
+    "winston": {
+      "optional": true
+    },
+    "pino": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@opentelemetry/sdk-trace-base": "^2.0.0",
+    "@opentelemetry/sdk-logs": "^0.203.0",
+    "@opentelemetry/sdk-metrics": "^2.0.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.203.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.201.1",
+    "@opentelemetry/resources": "^2.0.1",
+    "@opentelemetry/api-logs": "^0.203.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "@types/node": "^20.11.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}