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

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

@@ -0,0 +1,26 @@
+/**
+ * Shared constants for the @foam/node-cliengo bridge.
+ *
+ * Why this file exists:
+ *   Centralizes all hardcoded values (endpoint, limits, redaction keys, health
+ *   routes, request fields) so they are defined once and shared across every
+ *   module. Changing a constant here propagates everywhere without hunting
+ *   through individual files.
+ *
+ * Edge cases covered:
+ *   - FOAM_OTEL_ENDPOINT is hardcoded (not read from env) to prevent
+ *     misconfiguration; services override via `options.endpoint` only.
+ *   - REDACTED_KEYS uses lowercase comparison so "Authorization", "PASSWORD",
+ *     "Token" all match. Includes both "creditcard" and "credit_card" variants.
+ *   - HEALTH_ROUTES covers the four most common patterns across all 5 Cliengo
+ *     services so health-check traffic doesn't bloat span events.
+ *   - REQUEST_CONTEXT_FIELDS lists every property the five services may put on
+ *     req (Express or Fastify): auth, user, jwtPayload, session, cookies, etc.
+ *     Missing properties are silently skipped at capture time.
+ */
+export declare const FOAM_OTEL_ENDPOINT = "https://otel.api.foam.ai";
+export declare const SHUTDOWN_TIMEOUT_MS = 5000;
+export declare const BODY_TRUNCATION_LIMIT = 4096;
+export declare const REDACTED_KEYS: Set<string>;
+export declare const HEALTH_ROUTES: Set<string>;
+export declare const REQUEST_CONTEXT_FIELDS: readonly ["params", "query", "body", "headers", "auth", "user", "jwtPayload", "session", "cookies", "ip", "hostname", "protocol"];

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

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Shared constants for the @foam/node-cliengo bridge.
+ *
+ * Why this file exists:
+ *   Centralizes all hardcoded values (endpoint, limits, redaction keys, health
+ *   routes, request fields) so they are defined once and shared across every
+ *   module. Changing a constant here propagates everywhere without hunting
+ *   through individual files.
+ *
+ * Edge cases covered:
+ *   - FOAM_OTEL_ENDPOINT is hardcoded (not read from env) to prevent
+ *     misconfiguration; services override via `options.endpoint` only.
+ *   - REDACTED_KEYS uses lowercase comparison so "Authorization", "PASSWORD",
+ *     "Token" all match. Includes both "creditcard" and "credit_card" variants.
+ *   - HEALTH_ROUTES covers the four most common patterns across all 5 Cliengo
+ *     services so health-check traffic doesn't bloat span events.
+ *   - REQUEST_CONTEXT_FIELDS lists every property the five services may put on
+ *     req (Express or Fastify): auth, user, jwtPayload, session, cookies, etc.
+ *     Missing properties are silently skipped at capture time.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUEST_CONTEXT_FIELDS = exports.HEALTH_ROUTES = exports.REDACTED_KEYS = exports.BODY_TRUNCATION_LIMIT = exports.SHUTDOWN_TIMEOUT_MS = exports.FOAM_OTEL_ENDPOINT = void 0;
+exports.FOAM_OTEL_ENDPOINT = 'https://otel.api.foam.ai';
+exports.SHUTDOWN_TIMEOUT_MS = 5000;
+exports.BODY_TRUNCATION_LIMIT = 4096;
+exports.REDACTED_KEYS = new Set([
+    'password',
+    'token',
+    'authorization',
+    'secret',
+    'creditcard',
+    'credit_card',
+]);
+exports.HEALTH_ROUTES = new Set(['/health', '/healthz', '/ready', '/status']);
+exports.REQUEST_CONTEXT_FIELDS = [
+    'params',
+    'query',
+    'body',
+    'headers',
+    'auth',
+    'user',
+    'jwtPayload',
+    'session',
+    'cookies',
+    'ip',
+    'hostname',
+    'protocol',
+];

package/dist/node-cliengo/src/http/express.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Express shadow HTTP middleware — creates one OTel span per request on our
+ * non-global provider, sharing NR's traceId for correlation.
+ *
+ * Why this file exists:
+ *   NR auto-instruments HTTP via monkey-patching, but those are NR segments —
+ *   not OTel spans. We can't inject into NR's provider (addSpanProcessor was
+ *   removed in OTel SDK v2). Instead, this middleware creates a "shadow" span
+ *   that mirrors the request lifecycle. Foam sees every HTTP request; NR is
+ *   completely untouched.
+ *
+ * Two functions required:
+ *   - createExpressMiddleware(): registered BEFORE routes. Creates the span on
+ *     request start, records status/route/duration on `res.on('finish')`, and
+ *     captures request context as a span event.
+ *   - createExpressErrorHandler(): registered AFTER routes. Records exception
+ *     details (type, message, stacktrace) on the shadow span. Must have the
+ *     4-argument Express error handler signature (err, req, res, next).
+ *
+ * Edge cases covered:
+ *   - Error handler not registered: if a 500 response finishes without the
+ *     error handler, we log a one-time warning so devs know they're missing
+ *     exception details. Shadow span still shows status 500 — just no
+ *     exception.type/message/stacktrace.
+ *   - NR not loaded: getTraceContext returns empty strings. Span still created
+ *     but without nr.traceId/nr.spanId attributes.
+ *   - Health routes (/health, /healthz, /ready, /status): no request.context
+ *     span event attached — avoids bloating spans with empty health check data.
+ *   - req.route is undefined for 404s or middleware-only errors: falls back to
+ *     req.originalUrl for the http.route attribute.
+ *   - Errors thrown as non-Error objects (e.g. strings): wrapped in new Error()
+ *     for consistent recording.
+ *   - All callbacks wrapped in try/catch — a crash in span logic never takes
+ *     down the request.
+ */
+import { type Tracer } from '@opentelemetry/api';
+import type { ExpressErrorHandler, ExpressRequestHandler } from '../types';
+export declare function createExpressMiddleware(tracer: Tracer): ExpressRequestHandler;
+export declare function createExpressErrorHandler(middlewareRef?: ExpressRequestHandler & {
+    _markErrorHandler?: () => void;
+}): ExpressErrorHandler;

package/dist/node-cliengo/src/http/express.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Express shadow HTTP middleware — creates one OTel span per request on our
+ * non-global provider, sharing NR's traceId for correlation.
+ *
+ * Why this file exists:
+ *   NR auto-instruments HTTP via monkey-patching, but those are NR segments —
+ *   not OTel spans. We can't inject into NR's provider (addSpanProcessor was
+ *   removed in OTel SDK v2). Instead, this middleware creates a "shadow" span
+ *   that mirrors the request lifecycle. Foam sees every HTTP request; NR is
+ *   completely untouched.
+ *
+ * Two functions required:
+ *   - createExpressMiddleware(): registered BEFORE routes. Creates the span on
+ *     request start, records status/route/duration on `res.on('finish')`, and
+ *     captures request context as a span event.
+ *   - createExpressErrorHandler(): registered AFTER routes. Records exception
+ *     details (type, message, stacktrace) on the shadow span. Must have the
+ *     4-argument Express error handler signature (err, req, res, next).
+ *
+ * Edge cases covered:
+ *   - Error handler not registered: if a 500 response finishes without the
+ *     error handler, we log a one-time warning so devs know they're missing
+ *     exception details. Shadow span still shows status 500 — just no
+ *     exception.type/message/stacktrace.
+ *   - NR not loaded: getTraceContext returns empty strings. Span still created
+ *     but without nr.traceId/nr.spanId attributes.
+ *   - Health routes (/health, /healthz, /ready, /status): no request.context
+ *     span event attached — avoids bloating spans with empty health check data.
+ *   - req.route is undefined for 404s or middleware-only errors: falls back to
+ *     req.originalUrl for the http.route attribute.
+ *   - Errors thrown as non-Error objects (e.g. strings): wrapped in new Error()
+ *     for consistent recording.
+ *   - All callbacks wrapped in try/catch — a crash in span logic never takes
+ *     down the request.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createExpressMiddleware = createExpressMiddleware;
+exports.createExpressErrorHandler = createExpressErrorHandler;
+const api_1 = require("@opentelemetry/api");
+const trace_bridge_1 = require("../trace-bridge");
+const request_context_1 = require("./request-context");
+const SPAN_KEY = Symbol.for('foam.shadow.span');
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */
+function createExpressMiddleware(tracer) {
+    let errorHandlerRegistered = false;
+    let warnedMissingErrorHandler = false;
+    const markErrorHandlerRegistered = () => {
+        errorHandlerRegistered = true;
+    };
+    const middleware = (req, res, next) => {
+        const method = req.method ?? 'UNKNOWN';
+        const target = req.originalUrl ?? req.url ?? '/';
+        const { traceId, spanId } = (0, trace_bridge_1.getTraceContext)();
+        const span = tracer.startSpan(`${method} ${target}`, {
+            attributes: {
+                'http.method': method,
+                'http.target': target,
+                ...(traceId ? { 'nr.traceId': traceId } : {}),
+                ...(spanId ? { 'nr.spanId': spanId } : {}),
+            },
+        });
+        req[SPAN_KEY] = span;
+        const startTime = Date.now();
+        const onFinish = () => {
+            try {
+                const statusCode = res.statusCode ?? 0;
+                const route = req.route?.path ?? target;
+                const contentLength = res.getHeader?.('content-length') ?? '';
+                span.setAttribute('http.status_code', statusCode);
+                span.setAttribute('http.route', route);
+                span.setAttribute('http.response_content_length', String(contentLength));
+                span.setAttribute('http.duration_ms', Date.now() - startTime);
+                if (statusCode >= 500) {
+                    span.setStatus({ code: api_1.SpanStatusCode.ERROR });
+                    if (!errorHandlerRegistered && !warnedMissingErrorHandler) {
+                        warnedMissingErrorHandler = true;
+                        // eslint-disable-next-line no-console
+                        console.warn('[foam] createExpressErrorHandler() not registered — exception details will be missing from shadow spans');
+                    }
+                }
+                else {
+                    span.setStatus({ code: api_1.SpanStatusCode.OK });
+                }
+                if (!(0, request_context_1.isHealthRoute)(route) && !(0, request_context_1.isHealthRoute)(target)) {
+                    (0, request_context_1.captureRequestContext)(span, req);
+                }
+            }
+            catch {
+                /* never crash on finish */
+            }
+            finally {
+                span.end();
+            }
+        };
+        res.on('finish', onFinish);
+        next();
+    };
+    middleware._markErrorHandler = markErrorHandlerRegistered;
+    return middleware;
+}
+function createExpressErrorHandler(middlewareRef) {
+    middlewareRef?._markErrorHandler?.();
+    return (err, req, _res, next) => {
+        try {
+            const span = req[SPAN_KEY];
+            if (span) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                span.recordException({
+                    name: error.constructor.name,
+                    message: error.message,
+                    stack: error.stack,
+                });
+                span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
+            }
+        }
+        catch {
+            /* never crash error handling */
+        }
+        next(err);
+    };
+}
+/* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */

package/dist/node-cliengo/src/http/fastify.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Fastify shadow HTTP plugin — creates one OTel span per request on our
+ * non-global provider, sharing NR's traceId for correlation.
+ *
+ * Why this file exists:
+ *   Same rationale as the Express middleware (see express.ts). Fastify's hook
+ *   system is different — we use three hooks instead of middleware + error handler:
+ *   - onRequest: creates the shadow span, reads NR's traceId
+ *   - onError: records exception details (fires BEFORE errorHandler, so we see
+ *     every error including ones mapped to non-500 responses like AppError.badRequest)
+ *   - onResponse: records status/route/duration, captures request context, ends span
+ *
+ * Used by kori (~230 Fastify routes).
+ *
+ * Edge cases covered:
+ *   - Fastify's onError fires for ALL errors including 4xx AppError variants.
+ *     We record the exception on the span regardless — Foam sees the full error
+ *     even for 400s. The span status is only set to ERROR by onError (not
+ *     overwritten to OK by onResponse for <500 codes, since onError already set it).
+ *   - request.routeOptions?.url may not exist in older Fastify versions — falls
+ *     back to request.url.
+ *   - Health routes skipped for request.context capture (same as Express).
+ *   - All hooks wrapped in try/catch — never crashes the request pipeline.
+ *   - done() always called even if our code throws — Fastify hook contract.
+ */
+import { type Tracer } from '@opentelemetry/api';
+import type { FastifyPluginAsync } from '../types';
+export declare function createFastifyPlugin(tracer: Tracer): FastifyPluginAsync;

package/dist/node-cliengo/src/http/fastify.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * Fastify shadow HTTP plugin — creates one OTel span per request on our
+ * non-global provider, sharing NR's traceId for correlation.
+ *
+ * Why this file exists:
+ *   Same rationale as the Express middleware (see express.ts). Fastify's hook
+ *   system is different — we use three hooks instead of middleware + error handler:
+ *   - onRequest: creates the shadow span, reads NR's traceId
+ *   - onError: records exception details (fires BEFORE errorHandler, so we see
+ *     every error including ones mapped to non-500 responses like AppError.badRequest)
+ *   - onResponse: records status/route/duration, captures request context, ends span
+ *
+ * Used by kori (~230 Fastify routes).
+ *
+ * Edge cases covered:
+ *   - Fastify's onError fires for ALL errors including 4xx AppError variants.
+ *     We record the exception on the span regardless — Foam sees the full error
+ *     even for 400s. The span status is only set to ERROR by onError (not
+ *     overwritten to OK by onResponse for <500 codes, since onError already set it).
+ *   - request.routeOptions?.url may not exist in older Fastify versions — falls
+ *     back to request.url.
+ *   - Health routes skipped for request.context capture (same as Express).
+ *   - All hooks wrapped in try/catch — never crashes the request pipeline.
+ *   - done() always called even if our code throws — Fastify hook contract.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFastifyPlugin = createFastifyPlugin;
+const api_1 = require("@opentelemetry/api");
+const trace_bridge_1 = require("../trace-bridge");
+const request_context_1 = require("./request-context");
+const SPAN_KEY = Symbol.for('foam.shadow.span');
+const START_KEY = Symbol.for('foam.shadow.start');
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */
+function createFastifyPlugin(tracer) {
+    return async (fastify) => {
+        fastify.addHook('onRequest', (request, _reply, done) => {
+            try {
+                const method = request.method ?? 'UNKNOWN';
+                const url = request.url ?? '/';
+                const { traceId, spanId } = (0, trace_bridge_1.getTraceContext)();
+                const span = tracer.startSpan(`${method} ${url}`, {
+                    attributes: {
+                        'http.method': method,
+                        'http.target': url,
+                        ...(traceId ? { 'nr.traceId': traceId } : {}),
+                        ...(spanId ? { 'nr.spanId': spanId } : {}),
+                    },
+                });
+                request[SPAN_KEY] = span;
+                request[START_KEY] = Date.now();
+            }
+            catch {
+                /* never crash */
+            }
+            done();
+        });
+        fastify.addHook('onError', (request, _reply, error, done) => {
+            try {
+                const span = request[SPAN_KEY];
+                if (span) {
+                    span.recordException({
+                        name: error.constructor.name,
+                        message: error.message,
+                        stack: error.stack,
+                    });
+                    span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
+                }
+            }
+            catch {
+                /* never crash */
+            }
+            done();
+        });
+        fastify.addHook('onResponse', (request, reply, done) => {
+            try {
+                const span = request[SPAN_KEY];
+                if (span) {
+                    const statusCode = reply.statusCode ?? 0;
+                    const route = request.routeOptions?.url ?? request.url ?? '/';
+                    const start = request[START_KEY] ?? Date.now();
+                    span.setAttribute('http.status_code', statusCode);
+                    span.setAttribute('http.route', route);
+                    span.setAttribute('http.duration_ms', Date.now() - start);
+                    if (statusCode < 500) {
+                        span.setStatus({ code: api_1.SpanStatusCode.OK });
+                    }
+                    if (!(0, request_context_1.isHealthRoute)(route) && !(0, request_context_1.isHealthRoute)(request.url ?? '/')) {
+                        (0, request_context_1.captureRequestContext)(span, request);
+                    }
+                    span.end();
+                }
+            }
+            catch {
+                /* never crash */
+            }
+            done();
+        });
+    };
+}
+/* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */

package/dist/node-cliengo/src/http/request-context.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Request context capture — always-on, fail-safe serialization of HTTP request
+ * inputs into a single OTel span event called "request.context".
+ *
+ * Why this file exists:
+ *   When a crash occurs, the exception alone (type + message + stack) often
+ *   isn't enough to reproduce it — you need the inputs: route params, query,
+ *   body, auth token, etc. This module generically captures whatever is on the
+ *   request object and attaches it as a span event (not span attributes — those
+ *   would blow up cardinality indexes).
+ *
+ * Why always-on:
+ *   If opt-in, nobody enables it. The safety controls make it safe on every request.
+ *
+ * Why generic field capture:
+ *   Different services put auth in different places (req.auth, req.user,
+ *   req.jwtPayload). Rather than maintaining a per-service mapping, we loop
+ *   over REQUEST_CONTEXT_FIELDS and serialize whatever is present.
+ *
+ * Safety controls:
+ *   - Body truncation: 4KB limit prevents span bloat from file uploads, bulk
+ *     CSV, or base64 media.
+ *   - Field redaction: password, token, authorization, secret, creditCard are
+ *     replaced with "[REDACTED]". Deep-redacts nested objects. Case-insensitive.
+ *   - Health route skip: /health, /healthz, /ready, /status produce no event.
+ *   - Fail-safe: every property access AND serialization is in its own try/catch.
+ *     A throwing getter, circular object, or proxy trap on one field can never
+ *     prevent other fields from being captured, and can never crash the request.
+ */
+import type { Span } from '@opentelemetry/api';
+export declare function isHealthRoute(path: string): boolean;
+export declare function captureRequestContext(span: Span, req: any): void;

package/dist/node-cliengo/src/http/request-context.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * Request context capture — always-on, fail-safe serialization of HTTP request
+ * inputs into a single OTel span event called "request.context".
+ *
+ * Why this file exists:
+ *   When a crash occurs, the exception alone (type + message + stack) often
+ *   isn't enough to reproduce it — you need the inputs: route params, query,
+ *   body, auth token, etc. This module generically captures whatever is on the
+ *   request object and attaches it as a span event (not span attributes — those
+ *   would blow up cardinality indexes).
+ *
+ * Why always-on:
+ *   If opt-in, nobody enables it. The safety controls make it safe on every request.
+ *
+ * Why generic field capture:
+ *   Different services put auth in different places (req.auth, req.user,
+ *   req.jwtPayload). Rather than maintaining a per-service mapping, we loop
+ *   over REQUEST_CONTEXT_FIELDS and serialize whatever is present.
+ *
+ * Safety controls:
+ *   - Body truncation: 4KB limit prevents span bloat from file uploads, bulk
+ *     CSV, or base64 media.
+ *   - Field redaction: password, token, authorization, secret, creditCard are
+ *     replaced with "[REDACTED]". Deep-redacts nested objects. Case-insensitive.
+ *   - Health route skip: /health, /healthz, /ready, /status produce no event.
+ *   - Fail-safe: every property access AND serialization is in its own try/catch.
+ *     A throwing getter, circular object, or proxy trap on one field can never
+ *     prevent other fields from being captured, and can never crash the request.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHealthRoute = isHealthRoute;
+exports.captureRequestContext = captureRequestContext;
+const constants_1 = require("../constants");
+function truncate(value, limit) {
+    if (value.length <= limit) {
+        return value;
+    }
+    return value.slice(0, limit) + '...[truncated]';
+}
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */
+function redactValue(obj) {
+    if (typeof obj === 'string') {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => redactValue(item));
+    }
+    if (obj !== null && typeof obj === 'object') {
+        const result = {};
+        for (const [key, val] of Object.entries(obj)) {
+            if (constants_1.REDACTED_KEYS.has(key.toLowerCase())) {
+                result[key] = '[REDACTED]';
+            }
+            else {
+                result[key] = redactValue(val);
+            }
+        }
+        return result;
+    }
+    return obj;
+}
+function redact(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return JSON.stringify(redactValue(parsed));
+    }
+    catch {
+        return raw;
+    }
+}
+/* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */
+function isHealthRoute(path) {
+    return constants_1.HEALTH_ROUTES.has(path);
+}
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */
+function captureRequestContext(span, req) {
+    try {
+        const attrs = {};
+        const fields = {};
+        for (const key of constants_1.REQUEST_CONTEXT_FIELDS) {
+            try {
+                const val = req[key];
+                if (val !== undefined && val !== null) {
+                    fields[key] = val;
+                }
+            }
+            catch {
+                /* skip inaccessible properties */
+            }
+        }
+        for (const [key, val] of Object.entries(fields)) {
+            try {
+                const raw = typeof val === 'string' ? val : JSON.stringify(val);
+                if (key === 'body') {
+                    attrs[key] = truncate(redact(raw), constants_1.BODY_TRUNCATION_LIMIT);
+                }
+                else {
+                    attrs[key] = redact(typeof val === 'object' ? raw : String(val));
+                }
+            }
+            catch {
+                /* skip unserializable values */
+            }
+        }
+        if (Object.keys(attrs).length > 0) {
+            span.addEvent('request.context', attrs);
+        }
+    }
+    catch {
+        /* never crash the request */
+    }
+}
+/* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */

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

@@ -0,0 +1,26 @@
+/**
+ * Barrel re-export for @foam/node-cliengo.
+ *
+ * Why this file exists:
+ *   Single entry point so consumers import from '@foam/node-cliengo' directly.
+ *   Re-exports init() (the main API), individual helpers for advanced usage
+ *   (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.
+ *
+ *   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.
+ */
+export { init } from './init';
+export { buildTraceparent, extractParentContext, getTraceContext } from './trace-bridge';
+export { injectSnsAttributes } from './sns';
+export { injectJobData, wrapJobConsumer } from './job';
+export { wrapSqsConsumer } from './sqs';
+export { createExpressMiddleware, createExpressErrorHandler } from './http/express';
+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';

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

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Barrel re-export for @foam/node-cliengo.
+ *
+ * Why this file exists:
+ *   Single entry point so consumers import from '@foam/node-cliengo' directly.
+ *   Re-exports init() (the main API), individual helpers for advanced usage
+ *   (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.
+ *
+ *   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.
+ */
+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;
+var init_1 = require("./init");
+Object.defineProperty(exports, "init", { enumerable: true, get: function () { return init_1.init; } });
+var trace_bridge_1 = require("./trace-bridge");
+Object.defineProperty(exports, "buildTraceparent", { enumerable: true, get: function () { return trace_bridge_1.buildTraceparent; } });
+Object.defineProperty(exports, "extractParentContext", { enumerable: true, get: function () { return trace_bridge_1.extractParentContext; } });
+Object.defineProperty(exports, "getTraceContext", { enumerable: true, get: function () { return trace_bridge_1.getTraceContext; } });
+var sns_1 = require("./sns");
+Object.defineProperty(exports, "injectSnsAttributes", { enumerable: true, get: function () { return sns_1.injectSnsAttributes; } });
+var job_1 = require("./job");
+Object.defineProperty(exports, "injectJobData", { enumerable: true, get: function () { return job_1.injectJobData; } });
+Object.defineProperty(exports, "wrapJobConsumer", { enumerable: true, get: function () { return job_1.wrapJobConsumer; } });
+var sqs_1 = require("./sqs");
+Object.defineProperty(exports, "wrapSqsConsumer", { enumerable: true, get: function () { return sqs_1.wrapSqsConsumer; } });
+var express_1 = require("./http/express");
+Object.defineProperty(exports, "createExpressMiddleware", { enumerable: true, get: function () { return express_1.createExpressMiddleware; } });
+Object.defineProperty(exports, "createExpressErrorHandler", { enumerable: true, get: function () { return express_1.createExpressErrorHandler; } });
+var fastify_1 = require("./http/fastify");
+Object.defineProperty(exports, "createFastifyPlugin", { enumerable: true, get: function () { return fastify_1.createFastifyPlugin; } });
+var winston_format_1 = require("./logs/winston-format");
+Object.defineProperty(exports, "createWinstonFormat", { enumerable: true, get: function () { return winston_format_1.createWinstonFormat; } });
+var pino_mixin_1 = require("./logs/pino-mixin");
+Object.defineProperty(exports, "createPinoMixin", { enumerable: true, get: function () { return pino_mixin_1.createPinoMixin; } });
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "FOAM_OTEL_ENDPOINT", { enumerable: true, get: function () { return constants_1.FOAM_OTEL_ENDPOINT; } });

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

@@ -0,0 +1,50 @@
+/**
+ * Main entry point — init() creates the OtelBridge 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
+ *   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.
+ *      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
+ *      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
+ *     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).
+ *   - 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.
+ *   - 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().
+ *   - 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,
+ *     not the other way around).
+ *   - First-export health check: monkey-patches the BatchSpanProcessor's exporter
+ *     to log success/failure on the first OTLP export. Non-critical — wrapped in
+ *     try/catch, uses internal OTel SDK APIs that may change.
+ *   - Non-global providers: BasicTracerProvider, LoggerProvider, MeterProvider
+ *     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;