@foam-ai/node 0.1.0-alpha.2 → 0.1.0-alpha.4

package/dist/network-capture/undici.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUndiciNetworkCaptureHooks = createUndiciNetworkCaptureHooks;
+const api_1 = require("@opentelemetry/api");
+const node_diagnostics_channel_1 = require("node:diagnostics_channel");
+const utils_js_1 = require("../utils.js");
+const collector_js_1 = require("./collector.js");
+const undiciSessions = new WeakMap();
+let undiciBodyChannelsBound = false;
+function appendHeader(headers, rawName, value) {
+    const name = String(rawName).toLowerCase();
+    const existing = headers[name];
+    if (existing === undefined)
+        headers[name] = value;
+    else if (Array.isArray(existing))
+        existing.push(value);
+    else
+        headers[name] = [existing, value];
+}
+function undiciRequestHeaders(value) {
+    const headers = {};
+    if (typeof value === "string") {
+        for (const line of value.split("\r\n")) {
+            const separator = line.indexOf(":");
+            if (separator <= 0)
+                continue;
+            appendHeader(headers, line.slice(0, separator).trim(), line.slice(separator + 1).trim());
+        }
+    }
+    else if (Array.isArray(value)) {
+        for (let index = 0; index + 1 < value.length; index += 2) {
+            appendHeader(headers, value[index], value[index + 1]);
+        }
+    }
+    return headers;
+}
+function undiciResponseHeaders(value) {
+    if (!Array.isArray(value))
+        return {};
+    const headers = {};
+    for (let index = 0; index + 1 < value.length; index += 2) {
+        const name = value[index];
+        const headerValue = value[index + 1];
+        appendHeader(headers, Buffer.isBuffer(name) ? name.toString("latin1") : name, Buffer.isBuffer(headerValue)
+            ? headerValue.toString("latin1")
+            : headerValue);
+    }
+    return headers;
+}
+function undiciRequest(message) {
+    if (!message || typeof message !== "object" || !("request" in message)) {
+        return undefined;
+    }
+    const request = message.request;
+    return request && typeof request === "object"
+        ? request
+        : undefined;
+}
+function undiciCollector(session, direction) {
+    const field = direction === "request" ? "requestBody" : "responseBody";
+    const existing = session[field];
+    if (existing)
+        return existing;
+    const headers = direction === "request" ? session.requestHeaders : session.responseHeaders;
+    if (!headers)
+        return undefined;
+    const created = collector_js_1.BodyCollector.create(session.span, "client", direction, () => headers);
+    if (created)
+        session[field] = created;
+    return created;
+}
+function finishUndici(request, complete) {
+    const session = undiciSessions.get(request);
+    if (!session)
+        return;
+    undiciSessions.delete(request);
+    session.requestBody?.finalize(complete);
+    session.responseBody?.finalize(complete);
+}
+function bindUndiciChannel(name, handle) {
+    (0, node_diagnostics_channel_1.subscribe)(name, (message) => {
+        (0, utils_js_1.safely)(() => {
+            const request = undiciRequest(message);
+            if (!request)
+                return;
+            const session = undiciSessions.get(request);
+            if (!session)
+                return;
+            handle(message, request, session);
+        });
+    });
+}
+function bindUndiciBodyChannels() {
+    if (undiciBodyChannelsBound)
+        return;
+    undiciBodyChannelsBound = true;
+    // Subscribe before UndiciInstrumentation.enable() so trailers run while
+    // the span is still recording. BodyCollector is created on first chunk.
+    bindUndiciChannel("undici:request:bodyChunkSent", (message, _request, session) => {
+        undiciCollector(session, "request")?.observe(message.chunk);
+    });
+    bindUndiciChannel("undici:request:bodySent", (_message, _request, session) => {
+        session.requestBody?.finalize(true);
+    });
+    bindUndiciChannel("undici:request:bodyChunkReceived", (message, _request, session) => {
+        undiciCollector(session, "response")?.observe(message.chunk);
+    });
+    bindUndiciChannel("undici:request:trailers", (_message, request) => {
+        finishUndici(request, true);
+    });
+    bindUndiciChannel("undici:request:error", (_message, request) => {
+        finishUndici(request, false);
+    });
+}
+/**
+ * Builds OTel Undici/fetch hooks. Headers use the same allowlist as Node HTTP.
+ * Bodies are copied from diagnostics_channel chunks — never from fetch streams.
+ */
+function createUndiciNetworkCaptureHooks(bodyCaptureEnabled = true) {
+    if (bodyCaptureEnabled)
+        bindUndiciBodyChannels();
+    return {
+        requestHook(span, request) {
+            const headers = undiciRequestHeaders(request.headers);
+            (0, collector_js_1.setHeaderAttributes)(span, "request", headers);
+            if (!bodyCaptureEnabled ||
+                !span.isRecording() ||
+                (span.spanContext().traceFlags & api_1.TraceFlags.SAMPLED) !==
+                    api_1.TraceFlags.SAMPLED) {
+                return;
+            }
+            undiciSessions.set(request, { span, requestHeaders: headers });
+        },
+        responseHook(span, info) {
+            const headers = undiciResponseHeaders(info.response.headers);
+            (0, collector_js_1.setHeaderAttributes)(span, "response", headers);
+            if (!bodyCaptureEnabled || info.request === undefined)
+                return;
+            const session = undiciSessions.get(info.request);
+            if (session)
+                session.responseHeaders = headers;
+        },
+    };
+}

package/dist/propagation.d.ts

@@ -0,0 +1,5 @@
+import { type Context } from "@opentelemetry/api";
+export declare function injectTraceContext(carrier: Record<string, string>): void;
+export declare function extractTraceContext(carrier: Record<string, string>): Context;
+export declare const setBaggage: (key: string, value: string) => void;
+export declare function getBaggage(key: string): string | undefined;

package/dist/propagation.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setBaggage = void 0;
+exports.injectTraceContext = injectTraceContext;
+exports.extractTraceContext = extractTraceContext;
+exports.getBaggage = getBaggage;
+const node_async_hooks_1 = require("node:async_hooks");
+const api_1 = require("@opentelemetry/api");
+const core_1 = require("@opentelemetry/core");
+const utils_js_1 = require("./utils.js");
+const state_js_1 = require("./state.js");
+// pcga11: Below are some definitios you may find helpful to understand this file.
+// CompositePropagator is a local propagator used on custom transports (Kafka, SQS, Redis, WebSocket)
+// An "injector/extractor" turns the context into headers and vice versa for distributed tracing
+// Carrier is the headers object can be kafka message, queue payload or any other transport headers
+// Context.active() returns the process' context. Think of it like a local RAM for this request in this Node process. Another service, process or even another Kafka in the same service will have a different context.active().
+const propagator = new core_1.CompositePropagator({
+    propagators: [new core_1.W3CTraceContextPropagator(), new core_1.W3CBaggagePropagator()],
+});
+const baggageStorage = new node_async_hooks_1.AsyncLocalStorage();
+function contextWithBaggage() {
+    const entries = Object.fromEntries(api_1.propagation.getBaggage(api_1.context.active())?.getAllEntries() ?? []);
+    for (const [key, value] of baggageStorage.getStore() ?? []) {
+        entries[key] = { value };
+    }
+    const baggage = api_1.propagation.createBaggage(entries);
+    return api_1.propagation.setBaggage(api_1.context.active(), baggage);
+}
+function injectTraceContext(carrier) {
+    (0, utils_js_1.safely)(() => {
+        propagator.inject(contextWithBaggage(), carrier, api_1.defaultTextMapSetter);
+    });
+}
+function extractTraceContext(carrier) {
+    return (0, utils_js_1.safely)(() => propagator.extract(api_1.context.active(), carrier, api_1.defaultTextMapGetter), api_1.context.active());
+}
+exports.setBaggage = (0, utils_js_1.whenInitialized)(state_js_1.Signals.baggage, (key, value) => {
+    const next = new Map(baggageStorage.getStore() ?? []);
+    next.set(key, value);
+    baggageStorage.enterWith(next);
+});
+function getBaggage(key) {
+    return (0, utils_js_1.safely)(() => baggageStorage.getStore()?.get(key) ??
+        api_1.propagation.getBaggage(api_1.context.active())?.getEntry(key)?.value, undefined);
+}

package/dist/resource.d.ts

@@ -0,0 +1,3 @@
+import type { Attributes } from "@opentelemetry/api";
+import { type Resource } from "@opentelemetry/resources";
+export declare function createFoamResource(name: string, environment: string, version?: string, additionalResourceAttributes?: Attributes): Resource;

package/dist/resource.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFoamResource = createFoamResource;
+const resources_1 = require("@opentelemetry/resources");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const constants_js_1 = require("./constants.js");
+function createFoamResource(name, environment, version, additionalResourceAttributes) {
+    return (0, resources_1.defaultResource)()
+        .merge((0, resources_1.detectResources)({
+        detectors: [resources_1.envDetector, resources_1.processDetector, resources_1.hostDetector, resources_1.osDetector],
+    }))
+        // pcga11: Later merges overwrite colliding keys, so Foam name/env/version will win over detectors.
+        // This is the desired behavior. Do not change.
+        .merge((0, resources_1.resourceFromAttributes)({
+        ...additionalResourceAttributes,
+        [semantic_conventions_1.ATTR_SERVICE_NAME]: name,
+        [semantic_conventions_1.ATTR_DEPLOYMENT_ENVIRONMENT_NAME]: environment,
+        ...(version
+            ? { [semantic_conventions_1.ATTR_SERVICE_VERSION]: version }
+            : {}),
+        [semantic_conventions_1.ATTR_TELEMETRY_DISTRO_NAME]: constants_js_1.FOAM_DISTRO_NAME,
+        [semantic_conventions_1.ATTR_TELEMETRY_DISTRO_VERSION]: constants_js_1.FOAM_DISTRO_VERSION,
+    }));
+}

package/dist/state.d.ts

@@ -0,0 +1,19 @@
+export declare enum Signals {
+    traces = "traces",
+    metrics = "metrics",
+    logs = "logs",
+    baggage = "baggage",
+    profile = "profile"
+}
+/** Read-only view of the SDK state; mutated only via the setters in state.ts. */
+export interface State {
+    readonly initialized: boolean;
+    readonly instrumentations: readonly string[];
+    readonly signals: Readonly<Record<Signals, boolean>>;
+}
+export declare const setInstrumentations: (names: readonly string[]) => void;
+export declare const setSignal: (signal: Signals, enabled: boolean) => void;
+export declare const getSignal: (signal: Signals) => boolean;
+export declare const setInitialized: (initialized: boolean) => void;
+export declare const getInitialized: () => boolean;
+export declare const getState: () => State;

package/dist/state.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getState = exports.getInitialized = exports.setInitialized = exports.getSignal = exports.setSignal = exports.setInstrumentations = exports.Signals = void 0;
+var Signals;
+(function (Signals) {
+    Signals["traces"] = "traces";
+    Signals["metrics"] = "metrics";
+    Signals["logs"] = "logs";
+    Signals["baggage"] = "baggage";
+    Signals["profile"] = "profile";
+})(Signals || (exports.Signals = Signals = {}));
+const state = {
+    initialized: false,
+    instrumentations: [],
+    signals: {
+        traces: false,
+        metrics: false,
+        logs: false,
+        baggage: false,
+        profile: false,
+    },
+};
+const setInstrumentations = (names) => {
+    state.instrumentations = [...names];
+};
+exports.setInstrumentations = setInstrumentations;
+const setSignal = (signal, enabled) => {
+    state.signals[signal] = enabled;
+};
+exports.setSignal = setSignal;
+const getSignal = (signal) => state.signals[signal];
+exports.getSignal = getSignal;
+const setInitialized = (initialized) => {
+    state.initialized = initialized;
+};
+exports.setInitialized = setInitialized;
+const getInitialized = () => state.initialized;
+exports.getInitialized = getInitialized;
+const getState = () => ({
+    initialized: state.initialized,
+    instrumentations: [...state.instrumentations],
+    signals: { ...state.signals },
+});
+exports.getState = getState;

package/dist/utils.d.ts

@@ -0,0 +1,4 @@
+import { Signals } from "./state.js";
+export declare function safely<T>(operation: () => T, fallback: T): T;
+export declare function safely(operation: () => void): void;
+export declare function whenInitialized<A extends unknown[]>(signal: Signals, operation: (...args: A) => void): (...args: A) => void;

package/dist/utils.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safely = safely;
+exports.whenInitialized = whenInitialized;
+const state_js_1 = require("./state.js");
+function safely(operation, fallback) {
+    try {
+        return operation();
+    }
+    catch {
+        return fallback;
+    }
+}
+function whenInitialized(signal, operation) {
+    return (...args) => {
+        if (!(0, state_js_1.getSignal)(signal))
+            return;
+        safely(() => operation(...args));
+    };
+}

package/package.json

@@ -1,35 +1,63 @@
 {
   "name": "@foam-ai/node",
-  "version": "0.1.0-alpha.2",
-  "main": "dist/node/src/index.js",
-  "types": "dist/node/src/index.d.ts",
+  "version": "0.1.0-alpha.4",
+  "description": "Foam JavaScript Node.js SDK",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/foam-ai/js-node.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "engines": {
+    "node": "^18.19.0 || >=20.6.0"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/node/src/index.d.ts",
-      "import": "./dist/node/src/index.js",
-      "require": "./dist/node/src/index.js"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json"
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/api-logs": "^0.214.0",
-    "@opentelemetry/exporter-logs-otlp-http": "^0.214.0",
-    "@opentelemetry/exporter-metrics-otlp-http": "^0.214.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.214.0",
-    "@opentelemetry/instrumentation": "^0.214.0",
-    "@opentelemetry/resources": "^2.6.1",
-    "@opentelemetry/sdk-logs": "^0.214.0",
-    "@opentelemetry/sdk-metrics": "^2.6.1",
-    "@opentelemetry/sdk-trace-base": "^2.6.1",
-    "@opentelemetry/sdk-trace-node": "^2.6.1"
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/api-logs": "^0.221.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.79.0",
+    "@opentelemetry/context-async-hooks": "^2.10.0",
+    "@opentelemetry/core": "^2.10.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.221.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.221.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.221.0",
+    "@opentelemetry/instrumentation": "^0.221.0",
+    "@opentelemetry/instrumentation-console": "^0.3.0",
+    "@opentelemetry/instrumentation-http": "^0.221.0",
+    "@opentelemetry/instrumentation-undici": "^0.31.0",
+    "@opentelemetry/otlp-transformer": "^0.221.0",
+    "@opentelemetry/resources": "^2.10.0",
+    "@opentelemetry/sdk-logs": "^0.221.0",
+    "@opentelemetry/sdk-metrics": "^2.10.0",
+    "@opentelemetry/sdk-trace-base": "^2.10.0",
+    "@opentelemetry/semantic-conventions": "^1.43.0",
+    "@opentelemetry/winston-transport": "^0.31.0"
   },
   "devDependencies": {
-    "typescript": "^6.0.2"
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
   }
 }

package/dist/node/src/capture-exception.d.ts

@@ -1,9 +0,0 @@
-/**
- * Captures an exception and sends it to Foam.
- *
- * - Records on the active span if one exists (for trace-level visibility)
- * - Always emits an OTEL log record so the error reaches Foam even when
- *   there is no active span or auto-instrumentation
- * - Safe to call at any time — silently no-ops if the SDK isn't initialized
- */
-export declare const captureException: (error: unknown) => void;

package/dist/node/src/capture-exception.js

@@ -1,31 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.captureException = void 0;
-const api_1 = require("@opentelemetry/api");
-const api_logs_1 = require("@opentelemetry/api-logs");
-const util_1 = require("../../shared/util");
-/**
- * Captures an exception and sends it to Foam.
- *
- * - Records on the active span if one exists (for trace-level visibility)
- * - Always emits an OTEL log record so the error reaches Foam even when
- *   there is no active span or auto-instrumentation
- * - Safe to call at any time — silently no-ops if the SDK isn't initialized
- */
-exports.captureException = (0, util_1.safe)((error) => {
-    const err = error instanceof Error ? error : new Error(String(error));
-    const span = api_1.trace.getActiveSpan();
-    if (span) {
-        span.recordException(err);
-        span.setStatus({ code: api_1.SpanStatusCode.ERROR });
-    }
-    api_logs_1.logs.getLogger('foam').emit({
-        severityNumber: api_logs_1.SeverityNumber.ERROR,
-        severityText: 'ERROR',
-        body: err.message,
-        attributes: {
-            'exception.type': err.name,
-            'exception.stacktrace': err.stack ?? '',
-        },
-    });
-});

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

@@ -1,9 +0,0 @@
-import { captureException } from './capture-exception';
-import { init } from './init';
-export { captureException, init };
-export type { FoamNodeInitOptions } from './init';
-declare const foam: {
-    captureException: (error: unknown) => void;
-    init: (options: import("./init").FoamNodeInitOptions) => void;
-};
-export default foam;

package/dist/node/src/index.js

@@ -1,12 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.init = exports.captureException = void 0;
-const capture_exception_1 = require("./capture-exception");
-Object.defineProperty(exports, "captureException", { enumerable: true, get: function () { return capture_exception_1.captureException; } });
-const init_1 = require("./init");
-Object.defineProperty(exports, "init", { enumerable: true, get: function () { return init_1.init; } });
-const foam = {
-    captureException: capture_exception_1.captureException,
-    init: init_1.init,
-};
-exports.default = foam;

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

@@ -1,27 +0,0 @@
-import type { InstrumentationBase } from '@opentelemetry/instrumentation';
-export interface FoamNodeInitOptions {
-    apiKey: string;
-    serviceName: string;
-    isProduction: boolean;
-    /**
-     * OpenTelemetry instrumentations to register (e.g. getNodeAutoInstrumentations()).
-     * None are registered by default to keep the SDK webpack/Turbopack-safe.
-     * For plain Node.js servers, pass getNodeAutoInstrumentations() to get
-     * automatic HTTP, Express, DNS, etc. instrumentation.
-     */
-    instrumentations?: InstrumentationBase[];
-}
-/**
- * Initializes the Foam SDK for Node.js.
- *
- * - Production-only: silently no-ops when `isProduction` is false.
- * - Zero latency: all setup is synchronous object construction; actual telemetry
- *   export happens asynchronously in background batch intervals.
- * - Crash-safe: every signal is wrapped in its own try/catch so a failure in
- *   one (e.g. traces) never prevents the others (logs, metrics) from starting.
- * - Provider-aware: detects each OTEL signal independently. If another SDK
- *   (Sentry, @vercel/otel, etc.) already registered a provider, Foam attaches
- *   its exporters on top. If no provider exists, Foam creates one. This
- *   guarantees all three signals always reach Foam regardless of environment.
- */
-export declare const init: (options: FoamNodeInitOptions) => void;