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

package/README.md

@@ -0,0 +1,123 @@
+# @foam-ai/node
+
+Foam observability SDK for Node.js. Sends traces, logs, and metrics to Foam with zero configuration overhead.
+
+## Install
+
+```bash
+npm install @foam-ai/node
+```
+
+## Quick start
+
+Call `init()` as early as possible in your application entry point:
+
+```typescript
+import foam from '@foam-ai/node';
+
+foam.init({
+  apiKey: process.env.FOAM_API_KEY,
+  serviceName: 'my-service',
+  isProduction: process.env.NODE_ENV === 'production',
+});
+```
+
+That's it. In production, Foam will automatically collect:
+
+- **Traces** — distributed traces via OpenTelemetry
+- **Logs** — console.log/info/error/warn/debug output
+- **Metrics** — runtime and custom metrics
+- **Uncaught errors** — process-level `uncaughtException` and `unhandledRejection`
+
+In non-production environments, `init()` is a silent no-op.
+
+## Capturing errors
+
+Unhandled exceptions and rejections are captured automatically. For caught errors you want to report, use `captureException`:
+
+```typescript
+import { captureException } from '@foam-ai/node';
+
+try {
+  await chargeCustomer(order);
+} catch (err) {
+  captureException(err);
+  return res.status(500).json({ error: 'Payment failed' });
+}
+```
+
+`captureException` works with or without an active trace span. It always emits an OpenTelemetry log record so errors reach Foam regardless of instrumentation setup.
+
+## Auto-instrumentation (optional)
+
+By default, no auto-instrumentations are registered. This keeps the SDK webpack/Turbopack-safe with no bundler configuration needed.
+
+For plain Node.js servers (Express, Fastify, etc.), you can opt into automatic HTTP, DNS, and framework instrumentation:
+
+```typescript
+import foam from '@foam-ai/node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+
+foam.init({
+  apiKey: process.env.FOAM_API_KEY,
+  serviceName: 'my-api',
+  isProduction: process.env.NODE_ENV === 'production',
+  instrumentations: getNodeAutoInstrumentations(),
+});
+```
+
+```bash
+npm install @opentelemetry/auto-instrumentations-node
+```
+
+## Next.js
+
+In a Next.js app, create an `instrumentation.ts` file at the project root:
+
+```typescript
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    const foam = await import('@foam-ai/node');
+    foam.init({
+      apiKey: process.env.FOAM_API_KEY!,
+      serviceName: 'my-nextjs-app',
+      isProduction: process.env.NODE_ENV === 'production',
+    });
+  }
+}
+```
+
+No webpack externals or bundler config needed.
+
+## Coexistence with other SDKs
+
+Foam detects each OpenTelemetry signal independently. If another SDK (Sentry, @vercel/otel, Datadog, etc.) has already registered a TracerProvider, LoggerProvider, or MeterProvider, Foam attaches its exporters on top rather than replacing them. Both SDKs receive data.
+
+If no providers exist, Foam creates its own. This means Foam works in any combination:
+
+- Foam alone
+- Foam + Sentry
+- Foam + @vercel/otel
+- Foam + any OpenTelemetry-compatible SDK
+
+## API
+
+### `init(options)`
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `apiKey` | `string` | Yes | Your Foam API key |
+| `serviceName` | `string` | Yes | Name of your service (appears in Foam dashboard) |
+| `isProduction` | `boolean` | Yes | Set to `true` to enable telemetry. `false` = no-op. |
+| `instrumentations` | `InstrumentationBase[]` | No | OpenTelemetry instrumentations to register |
+
+### `captureException(error)`
+
+Captures a caught error and sends it to Foam. Works with or without an active span.
+
+## Design
+
+- **HTTP-only exporters** — no gRPC, no Node.js built-in dependencies that break bundlers
+- **Zero latency** — all setup is synchronous; exporting happens in background batch intervals
+- **Crash-safe** — each signal (traces, logs, metrics, console, process handlers) is independently wrapped in try/catch
+- **Idempotent** — safe to call `init()` multiple times; console patching and process handlers use Symbols to prevent double-registration

package/dist/node/src/init.js

@@ -190,8 +190,18 @@ function patchConsole() {
         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) });
+            const ctx = api_1.context.active();
+            const spanContext = api_1.trace.getSpanContext(ctx);
+            const traceAttributes = spanContext && (0, api_1.isSpanContextValid)(spanContext)
+                ? { 'trace.id': spanContext.traceId, 'span.id': spanContext.spanId }
+                : undefined;
+            logger.emit({
+                context: ctx,
+                severityNumber,
+                severityText,
+                body: (0, util_1.format)(...args),
+                attributes: traceAttributes,
+            });
         };
     };
     patch('log', api_logs_1.SeverityNumber.INFO, 'INFO');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foam-ai/node",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "main": "dist/node/src/index.js",
   "types": "dist/node/src/index.d.ts",
   "exports": {