@foam-ai/node-cliengo 0.1.0-alpha.14 → 0.1.0-alpha.16

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

@@ -8,8 +8,7 @@
  *   through individual files.
  *
  * Edge cases covered:
- *   - FOAM_OTEL_ENDPOINT is hardcoded (not read from env) to prevent
- *     misconfiguration; services override via `options.endpoint` only.
+ *   - FOAM_OTEL_ENDPOINT is hardcoded — not configurable via env or options.
  *   - 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

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

@@ -9,8 +9,7 @@
  *   through individual files.
  *
  * Edge cases covered:
- *   - FOAM_OTEL_ENDPOINT is hardcoded (not read from env) to prevent
- *     misconfiguration; services override via `options.endpoint` only.
+ *   - FOAM_OTEL_ENDPOINT is hardcoded — not configurable via env or options.
  *   - 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
@@ -31,6 +30,10 @@ exports.REDACTED_KEYS = new Set([
     'secret',
     'creditcard',
     'credit_card',
+    'api_key',
+    'apikey',
+    'access_token',
+    'accesstoken',
 ]);
 exports.HEALTH_ROUTES = new Set(['/health', '/healthz', '/ready', '/status']);
 exports.REQUEST_CONTEXT_FIELDS = [

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

@@ -44,6 +44,7 @@ const trace_bridge_1 = require("../trace-bridge");
 const request_context_1 = require("./request-context");
 const SPAN_KEY = Symbol.for('foam.shadow.span');
 const TRACE_CTX_KEY = Symbol.for('foam.trace.context');
+const ERROR_RECORDED_KEY = Symbol.for('foam.shadow.errorRecorded');
 /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */
 function createExpressMiddleware(tracer) {
     let errorHandlerRegistered = false;
@@ -94,7 +95,10 @@ function createExpressMiddleware(tracer) {
                 span.setAttribute('http.route', route);
                 span.setAttribute('http.response_content_length', String(contentLength));
                 span.setAttribute('http.duration_ms', Date.now() - startTime);
-                if (statusCode >= 500) {
+                if (req[ERROR_RECORDED_KEY]) {
+                    // Error handler already set status — don't overwrite
+                }
+                else if (statusCode >= 500) {
                     span.setStatus({ code: api_1.SpanStatusCode.ERROR });
                     if (!errorHandlerRegistered && !warnedMissingErrorHandler) {
                         warnedMissingErrorHandler = true;
@@ -171,6 +175,7 @@ function createExpressErrorHandler(middlewareRef) {
                     stack: error.stack,
                 });
                 span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
+                req[ERROR_RECORDED_KEY] = true;
             }
         }
         catch {

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

@@ -5,7 +5,8 @@
  * 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
+ *   - onRequest: creates the shadow span, reads NR's traceId, sets the span as
+ *     the active OTel context so route handlers inherit it via AsyncLocalStorage
  *   - 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
@@ -15,13 +16,13 @@
  * 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).
+ *     even for 400s. Once onError sets ERROR status, onResponse never overwrites 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.
+ *   - onError/onResponse use async hooks (Fastify 5 forward-compat).
+ *     onRequest uses callback style intentionally for context.with() propagation.
  */
 import { type Tracer } from '@opentelemetry/api';
 import type { FastifyPluginAsync } from '../types';

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

@@ -6,7 +6,8 @@
  * 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
+ *   - onRequest: creates the shadow span, reads NR's traceId, sets the span as
+ *     the active OTel context so route handlers inherit it via AsyncLocalStorage
  *   - 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
@@ -16,13 +17,13 @@
  * 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).
+ *     even for 400s. Once onError sets ERROR status, onResponse never overwrites 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.
+ *   - onError/onResponse use async hooks (Fastify 5 forward-compat).
+ *     onRequest uses callback style intentionally for context.with() propagation.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getRequestTraceContext = getRequestTraceContext;
@@ -33,6 +34,7 @@ const request_context_1 = require("./request-context");
 const SPAN_KEY = Symbol.for('foam.shadow.span');
 const START_KEY = Symbol.for('foam.shadow.start');
 const TRACE_CTX_KEY = Symbol.for('foam.trace.context');
+const ERROR_RECORDED_KEY = Symbol.for('foam.shadow.errorRecorded');
 /**
  * Reads the trace context that was captured on the request at hook time.
  * Use this in Fastify's logger mixin or serializers to get trace IDs even
@@ -54,6 +56,10 @@ function getRequestTraceContext(request) {
 /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */
 function createFastifyPlugin(tracer) {
     return async (fastify) => {
+        // onRequest uses callback style intentionally — otelContext.with(ctx, done)
+        // propagates the shadow span as the active OTel context via AsyncLocalStorage
+        // to all downstream hooks and the route handler. Async hooks would lose the
+        // context after the awaited promise resolves.
         fastify.addHook('onRequest', (request, _reply, done) => {
             try {
                 const method = request.method ?? 'UNKNOWN';
@@ -82,25 +88,16 @@ function createFastifyPlugin(tracer) {
                     spanId: sc.spanId,
                     traceparent: `00-${sc.traceId}-${sc.spanId}-01`,
                 };
+                const activeCtx = api_1.trace.setSpan(parentCtx ?? api_1.ROOT_CONTEXT, span);
+                api_1.context.with(activeCtx, () => done());
+                return;
             }
             catch {
                 /* never crash */
             }
             done();
         });
-        // Set the shadow span as the active context for route handlers so
-        // buildTraceparent() returns the same traceId — even without NR.
-        fastify.addHook('preHandler', (request, _reply, done) => {
-            const span = request[SPAN_KEY];
-            if (span) {
-                const activeCtx = api_1.trace.setSpan(api_1.ROOT_CONTEXT, span);
-                api_1.context.with(activeCtx, () => done());
-            }
-            else {
-                done();
-            }
-        });
-        fastify.addHook('onError', (request, _reply, error, done) => {
+        fastify.addHook('onError', async (request, _reply, error) => {
             try {
                 const span = request[SPAN_KEY];
                 if (span) {
@@ -110,14 +107,14 @@ function createFastifyPlugin(tracer) {
                         stack: error.stack,
                     });
                     span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
+                    request[ERROR_RECORDED_KEY] = true;
                 }
             }
             catch {
                 /* never crash */
             }
-            done();
         });
-        fastify.addHook('onResponse', (request, reply, done) => {
+        fastify.addHook('onResponse', async (request, reply) => {
             try {
                 const span = request[SPAN_KEY];
                 if (span) {
@@ -127,8 +124,13 @@ function createFastifyPlugin(tracer) {
                     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 (!request[ERROR_RECORDED_KEY]) {
+                        if (statusCode >= 500) {
+                            span.setStatus({ code: api_1.SpanStatusCode.ERROR });
+                        }
+                        else {
+                            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);
@@ -139,7 +141,6 @@ function createFastifyPlugin(tracer) {
             catch {
                 /* never crash */
             }
-            done();
         });
     };
 }

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

@@ -11,7 +11,9 @@
  *
  *   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 foam instance.
+ *   access to the foam instance. createFastifyPlugin is NOT exported standalone
+ *   because the raw function takes a tracer argument — use foam.createFastifyPlugin()
+ *   instead.
  */
 export { init, getFoam } from './init';
 export { buildTraceparent, extractParentContext, getTraceContext } from './trace-bridge';
@@ -19,8 +21,9 @@ export { injectSnsAttributes } from './sns';
 export { injectJobData, wrapJobConsumer } from './job';
 export { wrapSqsConsumer } from './sqs';
 export { createExpressMiddleware, createExpressErrorHandler, getRequestTraceContext, createPinoHttpOptions } from './http/express';
-export { createFastifyPlugin, getRequestTraceContext as getFastifyRequestTraceContext } from './http/fastify';
+export { getRequestTraceContext as getFastifyRequestTraceContext } from './http/fastify';
 export { createWinstonFormat } from './logs/winston-format';
 export { createPinoMixin } from './logs/pino-mixin';
+export { loadNewRelic } from './nr';
 export { FOAM_OTEL_ENDPOINT } from './constants';
 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

@@ -12,10 +12,12 @@
  *
  *   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 foam instance.
+ *   access to the foam instance. createFastifyPlugin is NOT exported standalone
+ *   because the raw function takes a tracer argument — use foam.createFastifyPlugin()
+ *   instead.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FOAM_OTEL_ENDPOINT = exports.createPinoMixin = exports.createWinstonFormat = exports.getFastifyRequestTraceContext = exports.createFastifyPlugin = exports.createPinoHttpOptions = exports.getRequestTraceContext = exports.createExpressErrorHandler = exports.createExpressMiddleware = exports.wrapSqsConsumer = exports.wrapJobConsumer = exports.injectJobData = exports.injectSnsAttributes = exports.getTraceContext = exports.extractParentContext = exports.buildTraceparent = exports.getFoam = exports.init = void 0;
+exports.FOAM_OTEL_ENDPOINT = exports.loadNewRelic = exports.createPinoMixin = exports.createWinstonFormat = exports.getFastifyRequestTraceContext = exports.createPinoHttpOptions = exports.getRequestTraceContext = exports.createExpressErrorHandler = exports.createExpressMiddleware = exports.wrapSqsConsumer = exports.wrapJobConsumer = exports.injectJobData = exports.injectSnsAttributes = exports.getTraceContext = exports.extractParentContext = exports.buildTraceparent = exports.getFoam = exports.init = void 0;
 var init_1 = require("./init");
 Object.defineProperty(exports, "init", { enumerable: true, get: function () { return init_1.init; } });
 Object.defineProperty(exports, "getFoam", { enumerable: true, get: function () { return init_1.getFoam; } });
@@ -36,11 +38,12 @@ Object.defineProperty(exports, "createExpressErrorHandler", { enumerable: true,
 Object.defineProperty(exports, "getRequestTraceContext", { enumerable: true, get: function () { return express_1.getRequestTraceContext; } });
 Object.defineProperty(exports, "createPinoHttpOptions", { enumerable: true, get: function () { return express_1.createPinoHttpOptions; } });
 var fastify_1 = require("./http/fastify");
-Object.defineProperty(exports, "createFastifyPlugin", { enumerable: true, get: function () { return fastify_1.createFastifyPlugin; } });
 Object.defineProperty(exports, "getFastifyRequestTraceContext", { enumerable: true, get: function () { return fastify_1.getRequestTraceContext; } });
 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 nr_1 = require("./nr");
+Object.defineProperty(exports, "loadNewRelic", { enumerable: true, get: function () { return nr_1.loadNewRelic; } });
 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.js

@@ -75,6 +75,7 @@ const sns_1 = require("./sns");
 const sqs_1 = require("./sqs");
 const trace_bridge_1 = require("./trace-bridge");
 const instances = new Map();
+let _processHandlersRegistered = false;
 function createInertInstance(serviceName) {
     const resource = (0, resources_1.resourceFromAttributes)({ 'service.name': serviceName });
     const traceProvider = new sdk_trace_base_1.BasicTracerProvider({ resource });
@@ -86,7 +87,6 @@ function createInertInstance(serviceName) {
     return {
         tracer,
         meter,
-        logger: loggerProvider,
         traceProvider,
         meterProvider,
         loggerProvider,
@@ -104,16 +104,14 @@ function createInertInstance(serviceName) {
         createPinoDestination: () => new node_stream_1.Writable({
             write: (_c, _e, cb) => cb(),
         }),
-        createPinoLogger: (opts = {}) => {
-            const pino = require('pino');
-            return pino({ ...opts });
-        },
-        createPinoHttpConfig: () => ({}),
+        createPinoLogger: () => console,
+        createPinoHttpConfig: (opts) => (opts?.logger ? { logger: opts.logger } : {}),
+        createFastifyLoggerConfig: (opts) => ({ level: opts?.level ?? 'info' }),
         buildTraceparent: trace_bridge_1.buildTraceparent,
         injectSnsAttributes: sns_1.injectSnsAttributes,
         injectJobData: job_1.injectJobData,
-        wrapSqsConsumer: async (_t, _s, _m, fn) => fn(),
-        wrapJobConsumer: async (_t, _s, _j, fn) => fn(),
+        wrapSqsConsumer: async (_s, _m, fn) => fn(),
+        wrapJobConsumer: async (_s, _j, fn) => fn(),
         extractParentContext: () => {
             const { ROOT_CONTEXT } = require('@opentelemetry/api');
             return ROOT_CONTEXT;
@@ -227,46 +225,54 @@ function init(serviceName, options = {}) {
         process.on('SIGTERM', () => void handler());
         process.on('SIGINT', () => void handler());
     }
-    // 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 {
-            const span = tracer.startSpan('uncaughtException', {
-                attributes: { 'process.event': 'uncaughtException' },
-            });
-            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 {
-            void shutdown();
-        }
-    });
-    process.on('unhandledRejection', (reason) => {
-        try {
-            const err = reason instanceof Error ? reason : new Error(String(reason));
-            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 */
-        }
-    });
+    else {
+        process.once('beforeExit', () => {
+            if (!_isShutdown) {
+                // eslint-disable-next-line no-console
+                console.warn('[foam] autoShutdown is false but shutdown() was never called — OTel data may be lost');
+            }
+        });
+    }
+    if (!_processHandlersRegistered) {
+        _processHandlersRegistered = true;
+        process.on('uncaughtException', (err) => {
+            try {
+                const span = tracer.startSpan('uncaughtException', {
+                    attributes: { 'process.event': 'uncaughtException' },
+                });
+                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 {
+                void shutdown();
+            }
+        });
+        process.on('unhandledRejection', (reason) => {
+            try {
+                const err = reason instanceof Error ? reason : new Error(String(reason));
+                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 */
+            }
+        });
+    }
     // Winston auto-wiring
     if (options.winston) {
         const winstonLogger = options.winston;
@@ -331,7 +337,6 @@ function init(serviceName, options = {}) {
     const foam = {
         tracer,
         meter,
-        logger: loggerProvider,
         traceProvider,
         meterProvider,
         loggerProvider,
@@ -349,20 +354,35 @@ function init(serviceName, options = {}) {
             const pino = require('pino');
             const mixin = (0, pino_mixin_1.createPinoMixin)();
             const dest = (0, pino_destination_1.createPinoDestination)(loggerProvider, serviceName);
-            return pino({ ...opts, mixin }, pino.multistream([
+            const { streams: userStreams, ...pinoOpts } = opts;
+            const outputStreams = userStreams ?? [
                 { stream: process.stdout },
-                { stream: dest },
-            ]));
+            ];
+            return pino({ ...pinoOpts, mixin }, pino.multistream([...outputStreams, { stream: dest }]));
         },
-        createPinoHttpConfig: () => {
+        createPinoHttpConfig: (opts) => {
             const pinoHttpOpts = (0, express_1.createPinoHttpOptions)();
-            return { ...pinoHttpOpts };
+            return { ...pinoHttpOpts, ...(opts?.logger && { logger: opts.logger }) };
+        },
+        createFastifyLoggerConfig: (opts = {}) => {
+            const pino = require('pino');
+            const mixin = (0, pino_mixin_1.createPinoMixin)();
+            const dest = (0, pino_destination_1.createPinoDestination)(loggerProvider, serviceName);
+            const { streams: userStreams, ...pinoOpts } = opts;
+            const outputStreams = userStreams ?? [
+                { stream: process.stdout },
+            ];
+            return {
+                ...pinoOpts,
+                mixin,
+                stream: pino.multistream([...outputStreams, { stream: dest }]),
+            };
         },
         buildTraceparent: trace_bridge_1.buildTraceparent,
         injectSnsAttributes: sns_1.injectSnsAttributes,
         injectJobData: job_1.injectJobData,
-        wrapSqsConsumer: (t, s, m, fn) => (0, sqs_1.wrapSqsConsumer)(t, s, m, fn, metrics),
-        wrapJobConsumer: (t, s, j, fn) => (0, job_1.wrapJobConsumer)(t, s, j, fn, metrics),
+        wrapSqsConsumer: (s, m, fn) => (0, sqs_1.wrapSqsConsumer)(tracer, s, m, fn, metrics),
+        wrapJobConsumer: (s, j, fn) => (0, job_1.wrapJobConsumer)(tracer, s, j, fn, metrics),
         extractParentContext: trace_bridge_1.extractParentContext,
         shutdown,
     };

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

@@ -33,3 +33,20 @@ import type { NewRelicAgent } from './types';
 export declare function resolveNewRelic(explicit?: NewRelicAgent): NewRelicAgent;
 export declare function getNr(): NewRelicAgent;
 export declare function isNrLoaded(): boolean;
+/**
+ * Loads the New Relic agent via CJS require — safe to call from ESM services.
+ * Eliminates the createRequire boilerplate:
+ *
+ *   // Before (ESM service):
+ *   import { createRequire } from 'node:module';
+ *   const require = createRequire(import.meta.url);
+ *   let nr; try { nr = require('newrelic'); } catch {}
+ *   init('kori', { newrelic: nr });
+ *
+ *   // After:
+ *   import { init, loadNewRelic } from '@foam-ai/node-cliengo';
+ *   init('kori', { newrelic: loadNewRelic() });
+ *
+ * Returns undefined if the newrelic package is not installed.
+ */
+export declare function loadNewRelic(): NewRelicAgent | undefined;

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

@@ -34,6 +34,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveNewRelic = resolveNewRelic;
 exports.getNr = getNr;
 exports.isNrLoaded = isNrLoaded;
+exports.loadNewRelic = loadNewRelic;
 const NOOP_NR = {
     getTransaction: () => null,
     startBackgroundTransaction: (_name, _group, handler) => typeof handler === 'function' ? handler() : undefined,
@@ -69,3 +70,31 @@ function getNr() {
 function isNrLoaded() {
     return cachedNr !== null && cachedNr !== NOOP_NR;
 }
+/**
+ * Loads the New Relic agent via CJS require — safe to call from ESM services.
+ * Eliminates the createRequire boilerplate:
+ *
+ *   // Before (ESM service):
+ *   import { createRequire } from 'node:module';
+ *   const require = createRequire(import.meta.url);
+ *   let nr; try { nr = require('newrelic'); } catch {}
+ *   init('kori', { newrelic: nr });
+ *
+ *   // After:
+ *   import { init, loadNewRelic } from '@foam-ai/node-cliengo';
+ *   init('kori', { newrelic: loadNewRelic() });
+ *
+ * Returns undefined if the newrelic package is not installed.
+ */
+function loadNewRelic() {
+    try {
+        /* eslint-disable @typescript-eslint/no-require-imports */
+        const nr = require('newrelic');
+        /* eslint-enable @typescript-eslint/no-require-imports */
+        cachedNr = nr;
+        return nr;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -49,7 +49,6 @@ export interface FoamMetrics {
 export interface FoamInstance {
     tracer: Tracer;
     meter: Meter;
-    logger: LoggerProvider;
     traceProvider: BasicTracerProvider;
     meterProvider: MeterProvider;
     loggerProvider: LoggerProvider;
@@ -65,15 +64,40 @@ export interface FoamInstance {
         customProps: (req: any) => Record<string, string>;
     };
     createPinoDestination(): NodeJS.WritableStream;
+    /**
+     * Creates a Pino logger with trace-context mixin and OTLP destination pre-wired.
+     * Pass `streams` to replace the default stdout output (e.g., for pino-pretty):
+     *
+     *   foam.createPinoLogger({ streams: [{ stream: pinoPretty() }] })
+     *
+     * The OTLP destination is always appended automatically.
+     */
     createPinoLogger(options?: Record<string, any>): any;
-    createPinoHttpConfig(): Record<string, any>;
+    createPinoHttpConfig(opts?: {
+        logger?: any;
+    }): Record<string, any>;
+    /**
+     * Returns a Pino config object for Fastify's `logger` constructor option.
+     * Fastify constructs its own Pino instance from this, so request.log gets
+     * child loggers with request context automatically.
+     *
+     *   Fastify({ logger: foam.createFastifyLoggerConfig({ level: 'info' }) })
+     *
+     * Pass `streams` to replace stdout (e.g., pino-pretty in dev):
+     *
+     *   foam.createFastifyLoggerConfig({
+     *     level: 'debug',
+     *     streams: [{ stream: pinoPretty() }],
+     *   })
+     */
+    createFastifyLoggerConfig(opts?: Record<string, any>): Record<string, any>;
     buildTraceparent(): string;
     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>;
+    wrapSqsConsumer(spanName: string, msg: SqsMessage, fn: () => Promise<void>): Promise<void>;
+    wrapJobConsumer(spanName: string, jobData: Record<string, unknown>, fn: () => Promise<void>): Promise<void>;
     extractParentContext(traceparent: string): Context;
     shutdown(): Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foam-ai/node-cliengo",
-  "version": "0.1.0-alpha.14",
+  "version": "0.1.0-alpha.16",
   "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",