@foam-ai/node 0.1.0-alpha.1

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

@@ -0,0 +1,9 @@
+/**
+ * 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

@@ -0,0 +1,31 @@
+"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

@@ -0,0 +1,9 @@
+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

@@ -0,0 +1,12 @@
+"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

@@ -0,0 +1,27 @@
+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;

package/dist/node/src/init.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = void 0;
+const sdk_trace_node_1 = require("@opentelemetry/sdk-trace-node");
+const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
+const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-http");
+const exporter_logs_otlp_http_1 = require("@opentelemetry/exporter-logs-otlp-http");
+const sdk_logs_1 = require("@opentelemetry/sdk-logs");
+const sdk_metrics_1 = require("@opentelemetry/sdk-metrics");
+const exporter_metrics_otlp_http_1 = require("@opentelemetry/exporter-metrics-otlp-http");
+const instrumentation_1 = require("@opentelemetry/instrumentation");
+const api_1 = require("@opentelemetry/api");
+const api_logs_1 = require("@opentelemetry/api-logs");
+const resources_1 = require("@opentelemetry/resources");
+const util_1 = require("util");
+const constants_1 = require("../../shared/constants");
+const util_2 = require("../../shared/util");
+const capture_exception_1 = require("./capture-exception");
+/**
+ * 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.
+ */
+exports.init = (0, util_2.safe)((options) => {
+    if (!options.isProduction) {
+        return;
+    }
+    const headers = { authorization: `Bearer ${options.apiKey}` };
+    const resource = (0, resources_1.resourceFromAttributes)({ 'service.name': options.serviceName });
+    // Each signal is independent — a failure in one must not block the others
+    safeRun(() => ensureTraces(headers, resource, options.instrumentations));
+    safeRun(() => ensureLogs(headers, resource));
+    safeRun(() => ensureMetrics(headers, resource));
+    safeRun(() => patchConsole());
+    safeRun(() => registerProcessErrorHandlers());
+});
+// ---------------------------------------------------------------------------
+// Per-signal setup
+//
+// For each signal the pattern is:
+//   1. Create a batch processor/reader with an HTTP OTLP exporter
+//   2. Check if a real provider is already registered globally
+//   3. If yes → attach the processor to the existing provider
+//   4. If no  → create a new provider and register it globally
+//
+// All exporters use HTTP (not gRPC) to stay webpack/Turbopack-compatible.
+// Batch processors buffer spans/logs in memory and flush asynchronously,
+// so init() returns instantly with zero latency impact on the caller.
+// ---------------------------------------------------------------------------
+function ensureTraces(headers, resource, instrumentations) {
+    const processor = new sdk_trace_base_1.BatchSpanProcessor(new exporter_trace_otlp_http_1.OTLPTraceExporter({ url: `${constants_1.FOAM_OTEL_ENDPOINT}/v1/traces`, headers }));
+    const existing = unwrapProvider(api_1.trace.getTracerProvider());
+    if (!addProcessor(existing, 'addSpanProcessor', '_activeSpanProcessor', processor)) {
+        new sdk_trace_node_1.NodeTracerProvider({ resource, spanProcessors: [processor] }).register();
+    }
+    if (instrumentations?.length) {
+        (0, instrumentation_1.registerInstrumentations)({ instrumentations });
+    }
+}
+function ensureLogs(headers, resource) {
+    const processor = new sdk_logs_1.BatchLogRecordProcessor(new exporter_logs_otlp_http_1.OTLPLogExporter({ url: `${constants_1.FOAM_OTEL_ENDPOINT}/v1/logs`, headers }));
+    const existing = unwrapProvider(api_logs_1.logs.getLoggerProvider());
+    if (!addProcessor(existing, 'addLogRecordProcessor', '_sharedState', processor)) {
+        const provider = new sdk_logs_1.LoggerProvider({ resource, processors: [processor] });
+        api_logs_1.logs.setGlobalLoggerProvider(provider);
+    }
+}
+function ensureMetrics(headers, resource) {
+    const reader = new sdk_metrics_1.PeriodicExportingMetricReader({
+        exporter: new exporter_metrics_otlp_http_1.OTLPMetricExporter({
+            url: `${constants_1.FOAM_OTEL_ENDPOINT}/v1/metrics`,
+            headers,
+        }),
+    });
+    const existing = unwrapProvider(api_1.metrics.getMeterProvider());
+    if (!addProcessor(existing, 'addMetricReader', '_sharedState', reader)) {
+        const provider = new sdk_metrics_1.MeterProvider({ resource, readers: [reader] });
+        api_1.metrics.setGlobalMeterProvider(provider);
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Runs a function, swallowing any error so one failed signal can't block others. */
+function safeRun(fn) {
+    try {
+        fn();
+    }
+    catch { /* intentionally swallowed */ }
+}
+/**
+ * Unwraps proxy/noop providers to get the real delegate.
+ *
+ * OTEL wraps every global provider in a Proxy (ProxyTracerProvider,
+ * ProxyLoggerProvider, etc.). Before checking for methods like
+ * addSpanProcessor we need the real underlying provider.
+ *
+ * Returns {} for noop providers so callers can safely check for methods
+ * with typeof without null guards.
+ */
+function unwrapProvider(provider) {
+    const delegate = typeof provider.getDelegate === 'function'
+        ? provider.getDelegate()
+        : provider._delegate ?? provider;
+    if (!delegate || delegate.constructor?.name?.startsWith('Noop'))
+        return {};
+    return delegate;
+}
+/**
+ * Attempts to add a processor/reader to an existing provider.
+ *
+ * Strategy:
+ *   1. Try the public v1 method (addSpanProcessor, addLogRecordProcessor, addMetricReader)
+ *   2. Fall back to pushing into internal arrays used by SDK v2:
+ *      - Traces: provider._activeSpanProcessor._spanProcessors
+ *      - Logs:   provider._sharedState.registeredLogRecordProcessors
+ *      - Metrics: provider._sharedState has no writable reader array, so metrics
+ *                 always creates a new provider if the public method is missing
+ *
+ * All internal access is guarded by Array.isArray — safe if internals change.
+ * Returns true if successfully attached, false if a new provider is needed.
+ */
+function addProcessor(provider, v1Method, v2Field, processor) {
+    if (typeof provider[v1Method] === 'function') {
+        provider[v1Method](processor);
+        return true;
+    }
+    const state = provider[v2Field];
+    if (!state)
+        return false;
+    const internal = state._spanProcessors ??
+        state._processors ??
+        state.registeredLogRecordProcessors;
+    if (Array.isArray(internal)) {
+        internal.push(processor);
+        return true;
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Uncaught error handlers
+//
+// Listens to process-level uncaughtException and unhandledRejection events
+// to capture errors that escape all try/catch blocks. Works for any framework
+// (Express, Fastify, Koa, Next.js, plain Node.js, background jobs, etc.).
+// Idempotent — safe to call multiple times. Never interferes with the app's
+// default crash behavior since we only listen (not override).
+// ---------------------------------------------------------------------------
+const PROCESS_HANDLERS_INSTALLED = Symbol.for('foam.process.handlers');
+function registerProcessErrorHandlers() {
+    if (globalThis[PROCESS_HANDLERS_INSTALLED])
+        return;
+    process.on('uncaughtException', (err) => {
+        try {
+            (0, capture_exception_1.captureException)(err);
+        }
+        catch { /* never interfere with the crash */ }
+    });
+    process.on('unhandledRejection', (reason) => {
+        try {
+            (0, capture_exception_1.captureException)(reason);
+        }
+        catch { /* never interfere with the crash */ }
+    });
+    globalThis[PROCESS_HANDLERS_INSTALLED] = true;
+}
+// ---------------------------------------------------------------------------
+// Console log capture
+//
+// Wraps console.log/info/error/warn/debug to emit OTel log records.
+// Uses a Symbol to ensure idempotency — safe to call multiple times
+// or if another SDK has already patched console.
+// The original console method is always called first so there's zero
+// impact on the application's logging behavior or latency.
+// ---------------------------------------------------------------------------
+const PATCHED = Symbol.for('foam.console.patched');
+function patchConsole() {
+    if (console[PATCHED])
+        return;
+    const logger = api_logs_1.logs.getLogger('console');
+    const patch = (method, severityNumber, severityText) => {
+        const original = console[method].bind(console);
+        console[method] = (...args) => {
+            original(...args);
+            // logger.emit is non-blocking — it queues into the BatchLogRecordProcessor
+            logger.emit({ severityNumber, severityText, body: (0, util_1.format)(...args) });
+        };
+    };
+    patch('log', api_logs_1.SeverityNumber.INFO, 'INFO');
+    patch('info', api_logs_1.SeverityNumber.INFO, 'INFO');
+    patch('error', api_logs_1.SeverityNumber.ERROR, 'ERROR');
+    patch('warn', api_logs_1.SeverityNumber.WARN, 'WARN');
+    patch('debug', api_logs_1.SeverityNumber.DEBUG, 'DEBUG');
+    console[PATCHED] = true;
+}

package/dist/shared/constants.d.ts

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

package/dist/shared/constants.js

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

package/dist/shared/util.d.ts

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

package/dist/shared/util.js

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

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@foam-ai/node",
+  "version": "0.1.0-alpha.1",
+  "main": "dist/node/src/index.js",
+  "types": "dist/node/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/node/src/index.d.ts",
+      "import": "./dist/node/src/index.js",
+      "require": "./dist/node/src/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "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"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2"
+  }
+}