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

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

@@ -1,5 +1,5 @@
 /**
- * Shared constants for the @foam/node-cliengo bridge.
+ * Shared constants for @foam/node-cliengo.
  *
  * Why this file exists:
  *   Centralizes all hardcoded values (endpoint, limits, redaction keys, health

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

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * Shared constants for the @foam/node-cliengo bridge.
+ * Shared constants for @foam/node-cliengo.
  *
  * Why this file exists:
  *   Centralizes all hardcoded values (endpoint, limits, redaction keys, health

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

@@ -7,11 +7,11 @@
  *   (buildTraceparent, injectSnsAttributes, etc.), and all public types.
  *
  *   Most services only need: import { init } from '@foam/node-cliengo'
- *   Everything else is accessed via the returned OtelBridge object.
+ *   Everything else is accessed via the returned FoamInstance.
  *
  *   The individual function exports exist for tree-shaking and for cases where
  *   a service needs to call e.g. injectJobData() from a file that doesn't have
- *   access to the bridge instance.
+ *   access to the foam instance.
  */
 export { init } from './init';
 export { buildTraceparent, extractParentContext, getTraceContext } from './trace-bridge';
@@ -23,4 +23,4 @@ export { createFastifyPlugin } from './http/fastify';
 export { createWinstonFormat } from './logs/winston-format';
 export { createPinoMixin } from './logs/pino-mixin';
 export { FOAM_OTEL_ENDPOINT } from './constants';
-export type { BridgeMetrics, Counter, ExpressErrorHandler, ExpressRequestHandler, FastifyPluginAsync, Histogram, InitOptions, NewRelicAgent, ObservableGauge, OtelBridge, SnsMessageAttributeValue, SqsMessage, TraceContext, WinstonFormat, WinstonLogger, WinstonTransport, } from './types';
+export type { FoamMetrics, Counter, ExpressErrorHandler, ExpressRequestHandler, FastifyPluginAsync, Histogram, InitOptions, NewRelicAgent, ObservableGauge, FoamInstance, SnsMessageAttributeValue, SqsMessage, TraceContext, WinstonFormat, WinstonLogger, WinstonTransport, } from './types';

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

@@ -8,11 +8,11 @@
  *   (buildTraceparent, injectSnsAttributes, etc.), and all public types.
  *
  *   Most services only need: import { init } from '@foam/node-cliengo'
- *   Everything else is accessed via the returned OtelBridge object.
+ *   Everything else is accessed via the returned FoamInstance.
  *
  *   The individual function exports exist for tree-shaking and for cases where
  *   a service needs to call e.g. injectJobData() from a file that doesn't have
- *   access to the bridge instance.
+ *   access to the foam instance.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FOAM_OTEL_ENDPOINT = exports.createPinoMixin = exports.createWinstonFormat = exports.createFastifyPlugin = exports.createExpressErrorHandler = exports.createExpressMiddleware = exports.wrapSqsConsumer = exports.wrapJobConsumer = exports.injectJobData = exports.injectSnsAttributes = exports.getTraceContext = exports.extractParentContext = exports.buildTraceparent = exports.init = void 0;

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

@@ -1,40 +1,43 @@
 /**
- * Main entry point — init() creates the OtelBridge singleton for a service.
+ * Main entry point — init() creates the Foam singleton for a service.
  *
  * Why this file exists:
  *   Orchestrates all three OTel signals (traces, logs, metrics) into a single
- *   init() call that returns an OtelBridge object. Services call init() once at
- *   startup and use the returned bridge for everything else. The bridge is
+ *   init() call that returns a FoamInstance. Services call init() once at
+ *   startup and use the returned instance for everything else. It is
  *   designed to coexist with New Relic APM without touching NR's globals.
  *
  * Two-gate system:
- *   1. Kill switch (FOAM_OTEL_ENABLED): if false, returns a fully inert bridge.
+ *   1. Kill switch (FOAM_OTEL_ENABLED): if false, returns a fully inert instance.
  *      Every API exists but does nothing — zero overhead, zero network, zero risk.
  *      This is the master emergency shutoff.
  *   2. Production gate (NODE_ENV): exporters are only attached when NODE_ENV is
- *      "production" (or forceExport is true). In dev/test, the bridge is fully
+ *      "production" (or forceExport is true). In dev/test, Foam is fully
  *      functional (trace propagation, log enrichment work) but nothing is sent
  *      to Foam. Developers without FOAM_OTEL_TOKEN get no crashes.
  *
  * Edge cases covered:
- *   - Double init(): logs a warning, returns the existing bridge (singleton
+ *   - Double init(): logs a warning, returns the existing instance (singleton
  *     per service name). Prevents duplicate providers/processors/handlers.
  *   - Token undefined in dev: silently accepted — no OTLP export anyway.
  *   - Token undefined in prod: logs warning, disables exporters. All other
  *     features (trace propagation, log enrichment, NR bridging) still work.
  *   - Token undefined + forceExport: throws (fail-fast — you asked to force
  *     export but provided no credentials).
+ *   - Custom endpoint without forceExport: throws. Production always uses the
+ *     default Foam endpoint; custom endpoints are only for dev/staging.
  *   - Auto-shutdown (SIGTERM/SIGINT): flushes all providers with 5s timeout,
  *     then calls process.exit(0). Without the explicit exit, registering
  *     process.on('SIGTERM') replaces Node's default terminate behavior — services
  *     without their own handler (gpt-intentions, cb-proxy) would hang forever.
  *   - Manual shutdown: services with ordered cleanup (hsm-backend, kori, combee)
- *     pass autoShutdown: false and call bridge.shutdown() in their own handler.
+ *     pass autoShutdown: false and call foam.shutdown() in their own handler.
  *   - shutdown() is idempotent — safe to call multiple times.
  *   - Process exception handlers use process.on() (not .once()) so they don't
  *     replace NR's or Winston's existing handlers. All handlers fire independently.
- *   - uncaughtException handler flushes via shutdown() — best effort to get the
- *     fatal log to Foam before the process dies. Never calls process.exit().
+ *   - uncaughtException/unhandledRejection create short-lived spans with
+ *     recordException() so they appear in otel_traces, then force-flush the
+ *     trace provider before shutdown. Never calls process.exit().
  *   - Winston auto-wiring: init({ winston: baseLogger }) calls logger.add() for
  *     the OTLP transport and rewrites logger.format to prepend trace enrichment.
  *     Both work post-construction. Avoids circular deps (main.ts imports logger,
@@ -46,5 +49,5 @@
  *     are NEVER registered globally (.register() never called). NR owns the
  *     global registrations.
  */
-import type { InitOptions, OtelBridge } from './types';
-export declare function init(serviceName: string, token?: string, options?: InitOptions): OtelBridge;
+import type { InitOptions, FoamInstance } from './types';
+export declare function init(serviceName: string, token?: string, options?: InitOptions): FoamInstance;

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

@@ -1,41 +1,44 @@
 "use strict";
 /**
- * Main entry point — init() creates the OtelBridge singleton for a service.
+ * Main entry point — init() creates the Foam singleton for a service.
  *
  * Why this file exists:
  *   Orchestrates all three OTel signals (traces, logs, metrics) into a single
- *   init() call that returns an OtelBridge object. Services call init() once at
- *   startup and use the returned bridge for everything else. The bridge is
+ *   init() call that returns a FoamInstance. Services call init() once at
+ *   startup and use the returned instance for everything else. It is
  *   designed to coexist with New Relic APM without touching NR's globals.
  *
  * Two-gate system:
- *   1. Kill switch (FOAM_OTEL_ENABLED): if false, returns a fully inert bridge.
+ *   1. Kill switch (FOAM_OTEL_ENABLED): if false, returns a fully inert instance.
  *      Every API exists but does nothing — zero overhead, zero network, zero risk.
  *      This is the master emergency shutoff.
  *   2. Production gate (NODE_ENV): exporters are only attached when NODE_ENV is
- *      "production" (or forceExport is true). In dev/test, the bridge is fully
+ *      "production" (or forceExport is true). In dev/test, Foam is fully
  *      functional (trace propagation, log enrichment work) but nothing is sent
  *      to Foam. Developers without FOAM_OTEL_TOKEN get no crashes.
  *
  * Edge cases covered:
- *   - Double init(): logs a warning, returns the existing bridge (singleton
+ *   - Double init(): logs a warning, returns the existing instance (singleton
  *     per service name). Prevents duplicate providers/processors/handlers.
  *   - Token undefined in dev: silently accepted — no OTLP export anyway.
  *   - Token undefined in prod: logs warning, disables exporters. All other
  *     features (trace propagation, log enrichment, NR bridging) still work.
  *   - Token undefined + forceExport: throws (fail-fast — you asked to force
  *     export but provided no credentials).
+ *   - Custom endpoint without forceExport: throws. Production always uses the
+ *     default Foam endpoint; custom endpoints are only for dev/staging.
  *   - Auto-shutdown (SIGTERM/SIGINT): flushes all providers with 5s timeout,
  *     then calls process.exit(0). Without the explicit exit, registering
  *     process.on('SIGTERM') replaces Node's default terminate behavior — services
  *     without their own handler (gpt-intentions, cb-proxy) would hang forever.
  *   - Manual shutdown: services with ordered cleanup (hsm-backend, kori, combee)
- *     pass autoShutdown: false and call bridge.shutdown() in their own handler.
+ *     pass autoShutdown: false and call foam.shutdown() in their own handler.
  *   - shutdown() is idempotent — safe to call multiple times.
  *   - Process exception handlers use process.on() (not .once()) so they don't
  *     replace NR's or Winston's existing handlers. All handlers fire independently.
- *   - uncaughtException handler flushes via shutdown() — best effort to get the
- *     fatal log to Foam before the process dies. Never calls process.exit().
+ *   - uncaughtException/unhandledRejection create short-lived spans with
+ *     recordException() so they appear in otel_traces, then force-flush the
+ *     trace provider before shutdown. Never calls process.exit().
  *   - Winston auto-wiring: init({ winston: baseLogger }) calls logger.add() for
  *     the OTLP transport and rewrites logger.format to prepend trace enrichment.
  *     Both work post-construction. Avoids circular deps (main.ts imports logger,
@@ -49,7 +52,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.init = init;
-const api_logs_1 = require("@opentelemetry/api-logs");
+const api_1 = require("@opentelemetry/api");
 const exporter_logs_otlp_http_1 = require("@opentelemetry/exporter-logs-otlp-http");
 const exporter_metrics_otlp_http_1 = require("@opentelemetry/exporter-metrics-otlp-http");
 const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-http");
@@ -71,15 +74,15 @@ const nr_1 = require("./nr");
 const sns_1 = require("./sns");
 const sqs_1 = require("./sqs");
 const trace_bridge_1 = require("./trace-bridge");
-const bridges = new Map();
-function createInertBridge(serviceName) {
+const instances = new Map();
+function createInertInstance(serviceName) {
     const resource = (0, resources_1.resourceFromAttributes)({ 'service.name': serviceName });
     const traceProvider = new sdk_trace_base_1.BasicTracerProvider({ resource });
     const loggerProvider = new sdk_logs_1.LoggerProvider({ resource });
     const meterProvider = new sdk_metrics_1.MeterProvider({ resource });
     const tracer = traceProvider.getTracer(serviceName);
     const meter = meterProvider.getMeter(serviceName);
-    const metrics = (0, instruments_1.createBridgeMetrics)(meterProvider, serviceName);
+    const metrics = (0, instruments_1.createFoamMetrics)(meterProvider, serviceName);
     return {
         tracer,
         meter,
@@ -114,19 +117,19 @@ function createInertBridge(serviceName) {
 }
 /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call */
 function init(serviceName, token, options = {}) {
-    const existing = bridges.get(serviceName);
+    const existing = instances.get(serviceName);
     if (existing) {
         // eslint-disable-next-line no-console
-        console.warn(`[foam] init() already called for "${serviceName}" — returning existing bridge`);
+        console.warn(`[foam] init() already called for "${serviceName}" — returning existing instance`);
         return existing;
     }
     // Kill switch
     const isEnabled = (options.enabled ??
         ((process.env.FOAM_OTEL_ENABLED ?? 'true').toLowerCase() === 'true')) === true;
     if (!isEnabled) {
-        const bridge = createInertBridge(serviceName);
-        bridges.set(serviceName, bridge);
-        return bridge;
+        const foam = createInertInstance(serviceName);
+        instances.set(serviceName, foam);
+        return foam;
     }
     // Resolve NR
     (0, nr_1.resolveNewRelic)(options.newrelic);
@@ -143,6 +146,9 @@ function init(serviceName, token, options = {}) {
     }
     const hasToken = Boolean(token);
     const canExport = shouldExport && hasToken;
+    if (options.endpoint && !options.forceExport) {
+        throw new Error('[foam] custom endpoint requires forceExport: true — production always uses the default Foam endpoint');
+    }
     const endpoint = options.endpoint ?? constants_1.FOAM_OTEL_ENDPOINT;
     const resource = (0, resources_1.resourceFromAttributes)({ 'service.name': serviceName });
     const authHeaders = token
@@ -193,7 +199,7 @@ function init(serviceName, token, options = {}) {
     });
     const tracer = traceProvider.getTracer(serviceName);
     const meter = meterProvider.getMeter(serviceName);
-    const metrics = (0, instruments_1.createBridgeMetrics)(meterProvider, serviceName);
+    const metrics = (0, instruments_1.createFoamMetrics)(meterProvider, serviceName);
     let _isShutdown = false;
     const shutdown = async () => {
         if (_isShutdown) {
@@ -217,41 +223,41 @@ function init(serviceName, token, options = {}) {
         process.on('SIGTERM', () => void handler());
         process.on('SIGINT', () => void handler());
     }
-    // Process-level exception capture
-    const otelLogger = loggerProvider.getLogger(serviceName);
+    // Process-level exception capture — recorded as span exceptions so they
+    // land in otel_traces (not otel_logs). Each creates a short-lived span,
+    // records the exception, ends it, then force-flushes the trace provider.
     process.on('uncaughtException', (err) => {
         try {
-            otelLogger.emit({
-                body: err.message,
-                severityNumber: api_logs_1.SeverityNumber.FATAL,
-                severityText: 'FATAL',
-                attributes: {
-                    'exception.type': err.constructor.name,
-                    'exception.message': err.message,
-                    'exception.stacktrace': err.stack ?? '',
-                    'process.event': 'uncaughtException',
-                },
+            const span = tracer.startSpan('uncaughtException', {
+                attributes: { 'process.event': 'uncaughtException' },
             });
-            void shutdown();
+            span.recordException({
+                name: err.constructor.name,
+                message: err.message,
+                stack: err.stack,
+            });
+            span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: err.message });
+            span.end();
+            void traceProvider.forceFlush().then(() => shutdown());
         }
         catch {
-            /* best effort */
+            void shutdown();
         }
     });
     process.on('unhandledRejection', (reason) => {
         try {
             const err = reason instanceof Error ? reason : new Error(String(reason));
-            otelLogger.emit({
-                body: err.message,
-                severityNumber: api_logs_1.SeverityNumber.ERROR,
-                severityText: 'ERROR',
-                attributes: {
-                    'exception.type': err.constructor.name,
-                    'exception.message': err.message,
-                    'exception.stacktrace': err.stack ?? '',
-                    'process.event': 'unhandledRejection',
-                },
+            const span = tracer.startSpan('unhandledRejection', {
+                attributes: { 'process.event': 'unhandledRejection' },
+            });
+            span.recordException({
+                name: err.constructor.name,
+                message: err.message,
+                stack: err.stack,
             });
+            span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: err.message });
+            span.end();
+            void traceProvider.forceFlush();
         }
         catch {
             /* best effort */
@@ -318,7 +324,7 @@ function init(serviceName, token, options = {}) {
         }
     }
     const expressMiddleware = (0, express_1.createExpressMiddleware)(tracer);
-    const bridge = {
+    const foam = {
         tracer,
         meter,
         logger: loggerProvider,
@@ -342,7 +348,7 @@ function init(serviceName, token, options = {}) {
         extractParentContext: trace_bridge_1.extractParentContext,
         shutdown,
     };
-    bridges.set(serviceName, bridge);
-    return bridge;
+    instances.set(serviceName, foam);
+    return foam;
 }
 /* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call */

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

@@ -24,8 +24,8 @@
  *     consistent exception recording.
  */
 import { type Tracer } from '@opentelemetry/api';
-import type { BridgeMetrics } from './types';
+import type { FoamMetrics } from './types';
 export declare function injectJobData<T extends Record<string, unknown>>(data: T): T & {
     traceparent?: string;
 };
-export declare function wrapJobConsumer(tracer: Tracer, spanName: string, jobData: Record<string, unknown>, fn: () => Promise<void>, metrics?: BridgeMetrics): Promise<void>;
+export declare function wrapJobConsumer(tracer: Tracer, spanName: string, jobData: Record<string, unknown>, fn: () => Promise<void>, metrics?: FoamMetrics): Promise<void>;

package/dist/node-cliengo/src/metrics/instruments.d.ts

@@ -1,6 +1,5 @@
 /**
- * Pre-built OTel metric instruments for queue processing, plus factories
- * for service-specific custom metrics.
+ * Pre-built OTel metric instruments for queue processing.
  *
  * Why this file exists:
  *   Provides three auto-recorded instruments that wrapSqsConsumer and
@@ -9,15 +8,14 @@
  *   - messageProcessingErrors (counter): how many processing attempts fail
  *   - messagesProcessed (counter): total messages processed (success + error)
  *
- *   Also provides customHistogram/customCounter/customGauge factories for
- *   service-specific domain metrics (LLM duration in gpt-intentions, webhook
- *   processing time in cb-proxy, automation duration in kori).
+ *   These follow OTel semantic conventions for messaging. They are NOT
+ *   Cliengo-specific — any service with queue consumers gets them for free.
+ *
+ *   For service-specific domain metrics (LLM duration, webhook processing time,
+ *   automation duration), services use foam.meter directly:
+ *     const h = foam.meter.createHistogram('llm.duration', { unit: 'ms' });
  *
  * Edge cases covered:
- *   - Custom instrument idempotency: calling customHistogram('llm.duration', ...)
- *     twice returns the same Histogram instance (cached by name). OTel SDKs
- *     already handle duplicate instrument creation, but caching avoids the
- *     overhead of repeated createHistogram calls in hot paths.
  *   - MeterProvider is non-global — our metrics never conflict with NR's
  *     internal metrics or any other OTel MeterProvider in the process.
  *   - PeriodicExportingMetricReader (configured in init.ts) exports every 60s
@@ -25,5 +23,5 @@
  *     attached and no timer runs.
  */
 import type { MeterProvider } from '@opentelemetry/sdk-metrics';
-import type { BridgeMetrics } from '../types';
-export declare function createBridgeMetrics(meterProvider: MeterProvider, serviceName: string): BridgeMetrics;
+import type { FoamMetrics } from '../types';
+export declare function createFoamMetrics(meterProvider: MeterProvider, serviceName: string): FoamMetrics;

package/dist/node-cliengo/src/metrics/instruments.js

@@ -1,7 +1,6 @@
 "use strict";
 /**
- * Pre-built OTel metric instruments for queue processing, plus factories
- * for service-specific custom metrics.
+ * Pre-built OTel metric instruments for queue processing.
  *
  * Why this file exists:
  *   Provides three auto-recorded instruments that wrapSqsConsumer and
@@ -10,15 +9,14 @@
  *   - messageProcessingErrors (counter): how many processing attempts fail
  *   - messagesProcessed (counter): total messages processed (success + error)
  *
- *   Also provides customHistogram/customCounter/customGauge factories for
- *   service-specific domain metrics (LLM duration in gpt-intentions, webhook
- *   processing time in cb-proxy, automation duration in kori).
+ *   These follow OTel semantic conventions for messaging. They are NOT
+ *   Cliengo-specific — any service with queue consumers gets them for free.
+ *
+ *   For service-specific domain metrics (LLM duration, webhook processing time,
+ *   automation duration), services use foam.meter directly:
+ *     const h = foam.meter.createHistogram('llm.duration', { unit: 'ms' });
  *
  * Edge cases covered:
- *   - Custom instrument idempotency: calling customHistogram('llm.duration', ...)
- *     twice returns the same Histogram instance (cached by name). OTel SDKs
- *     already handle duplicate instrument creation, but caching avoids the
- *     overhead of repeated createHistogram calls in hot paths.
  *   - MeterProvider is non-global — our metrics never conflict with NR's
  *     internal metrics or any other OTel MeterProvider in the process.
  *   - PeriodicExportingMetricReader (configured in init.ts) exports every 60s
@@ -26,53 +24,19 @@
  *     attached and no timer runs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createBridgeMetrics = createBridgeMetrics;
-function createBridgeMetrics(meterProvider, serviceName) {
+exports.createFoamMetrics = createFoamMetrics;
+function createFoamMetrics(meterProvider, serviceName) {
     const meter = meterProvider.getMeter(serviceName);
-    const messageProcessingDuration = meter.createHistogram('messaging.process.duration', {
-        description: 'Time to process a queue message',
-        unit: 'ms',
-    });
-    const messageProcessingErrors = meter.createCounter('messaging.process.errors', {
-        description: 'Number of queue message processing errors',
-    });
-    const messagesProcessed = meter.createCounter('messaging.process.count', {
-        description: 'Number of queue messages processed',
-    });
-    const instrumentCache = new Map();
     return {
-        messageProcessingDuration,
-        messageProcessingErrors,
-        messagesProcessed,
-        customHistogram(name, description, unit) {
-            const key = `histogram:${name}`;
-            const existing = instrumentCache.get(key);
-            if (existing) {
-                return existing;
-            }
-            const h = meter.createHistogram(name, { description, unit });
-            instrumentCache.set(key, h);
-            return h;
-        },
-        customCounter(name, description, unit) {
-            const key = `counter:${name}`;
-            const existing = instrumentCache.get(key);
-            if (existing) {
-                return existing;
-            }
-            const c = meter.createCounter(name, { description, unit });
-            instrumentCache.set(key, c);
-            return c;
-        },
-        customGauge(name, description, unit) {
-            const key = `gauge:${name}`;
-            const existing = instrumentCache.get(key);
-            if (existing) {
-                return existing;
-            }
-            const g = meter.createObservableGauge(name, { description, unit });
-            instrumentCache.set(key, g);
-            return g;
-        },
+        messageProcessingDuration: meter.createHistogram('messaging.process.duration', {
+            description: 'Time to process a queue message',
+            unit: 'ms',
+        }),
+        messageProcessingErrors: meter.createCounter('messaging.process.errors', {
+            description: 'Number of queue message processing errors',
+        }),
+        messagesProcessed: meter.createCounter('messaging.process.count', {
+            description: 'Number of queue messages processed',
+        }),
     };
 }

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

@@ -14,7 +14,7 @@
  *      hsm-backend (conditional NR loading).
  *   2. Module cache: `require.cache[require.resolve('newrelic')]` — works for
  *      CJS services (combee, gpt-intentions, cb-proxy) where NR is loaded at
- *      the top of the entry file before the bridge initializes.
+ *      the top of the entry file before Foam initializes.
  *   3. Fallback: NOOP_NR stub that returns empty trace metadata and calls
  *      handler functions directly without creating background transactions.
  *

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

@@ -15,7 +15,7 @@
  *      hsm-backend (conditional NR loading).
  *   2. Module cache: `require.cache[require.resolve('newrelic')]` — works for
  *      CJS services (combee, gpt-intentions, cb-proxy) where NR is loaded at
- *      the top of the entry file before the bridge initializes.
+ *      the top of the entry file before Foam initializes.
  *   3. Fallback: NOOP_NR stub that returns empty trace metadata and calls
  *      handler functions directly without creating background transactions.
  *

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

@@ -28,8 +28,8 @@
  *     service's own retry/DLQ logic is unaffected.
  *   - NR not loaded: execute() runs without startBackgroundTransaction — OTel
  *     span still created, metrics still recorded.
- *   - metrics is undefined (inert bridge): all metrics?.xxx calls are no-ops.
+ *   - metrics is undefined (inert foam instance): all metrics?.xxx calls are no-ops.
  */
 import { type Tracer } from '@opentelemetry/api';
-import type { BridgeMetrics, SqsMessage } from './types';
-export declare function wrapSqsConsumer(tracer: Tracer, spanName: string, msg: SqsMessage, fn: () => Promise<void>, metrics?: BridgeMetrics): Promise<void>;
+import type { FoamMetrics, SqsMessage } from './types';
+export declare function wrapSqsConsumer(tracer: Tracer, spanName: string, msg: SqsMessage, fn: () => Promise<void>, metrics?: FoamMetrics): Promise<void>;

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

@@ -29,7 +29,7 @@
  *     service's own retry/DLQ logic is unaffected.
  *   - NR not loaded: execute() runs without startBackgroundTransaction — OTel
  *     span still created, metrics still recorded.
- *   - metrics is undefined (inert bridge): all metrics?.xxx calls are no-ops.
+ *   - metrics is undefined (inert foam instance): all metrics?.xxx calls are no-ops.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.wrapSqsConsumer = wrapSqsConsumer;

package/dist/node-cliengo/src/trace-bridge.d.ts

@@ -1,5 +1,5 @@
 /**
- * W3C trace context bridge between New Relic and OpenTelemetry.
+ * W3C trace context utilities for New Relic and OpenTelemetry interop.
  *
  * Why this file exists:
  *   NR owns the active trace (it creates transactions via http monkey-patching),

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

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * W3C trace context bridge between New Relic and OpenTelemetry.
+ * W3C trace context utilities for New Relic and OpenTelemetry interop.
  *
  * Why this file exists:
  *   NR owns the active trace (it creates transactions via http monkey-patching),

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

@@ -2,8 +2,8 @@
  * 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
+ *   Defines every public type the library exposes (FoamInstance, InitOptions,
+ *   TraceContext, FoamMetrics) 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.
@@ -41,22 +41,19 @@ export interface TraceContext {
     spanId: string;
     traceparent: string;
 }
-export interface BridgeMetrics {
+export interface FoamMetrics {
     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 {
+export interface FoamInstance {
     tracer: Tracer;
     meter: Meter;
     logger: LoggerProvider;
     traceProvider: BasicTracerProvider;
     meterProvider: MeterProvider;
     loggerProvider: LoggerProvider;
-    metrics: BridgeMetrics;
+    metrics: FoamMetrics;
     getTraceContext(): TraceContext;
     createExpressMiddleware(): ExpressRequestHandler;
     createExpressErrorHandler(): ExpressErrorHandler;

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

@@ -3,8 +3,8 @@
  * 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
+ *   Defines every public type the library exposes (FoamInstance, InitOptions,
+ *   TraceContext, FoamMetrics) 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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "0.1.0-alpha.3",
+  "description": "Unified observability (traces, logs, metrics) for Cliengo Node.js services, connecting New Relic APM with Foam's OTel collector.",
   "main": "dist/node-cliengo/src/index.js",
   "types": "dist/node-cliengo/src/index.d.ts",
   "exports": {
@@ -20,8 +20,8 @@
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.0",
     "newrelic": ">=12.0.0",
-    "winston": "^3.0.0",
-    "pino": "^8.0.0 || ^9.0.0"
+    "pino": "^8.0.0 || ^9.0.0",
+    "winston": "^3.0.0"
   },
   "peerDependenciesMeta": {
     "newrelic": {
@@ -35,18 +35,20 @@
     }
   },
   "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/api-logs": "^0.203.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.203.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.201.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
     "@opentelemetry/resources": "^2.0.1",
-    "@opentelemetry/api-logs": "^0.203.0"
+    "@opentelemetry/sdk-logs": "^0.203.0",
+    "@opentelemetry/sdk-metrics": "^2.0.1",
+    "@opentelemetry/sdk-trace-base": "^2.0.0"
   },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@types/node": "^20.11.0",
     "typescript": "^6.0.2",
-    "@types/node": "^20.11.0"
+    "vitest": "^4.1.8"
   },
   "engines": {
     "node": ">=18"