@autter/runtime-node 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# @autter/runtime-node
+
+Autter Runtime for Node.js — two halves in one package:
+
+1. **Same-origin browser relay** for `@autter/runtime-browser`
+2. **Curated OpenTelemetry server tracker** exporting OTLP/HTTP JSON
+
+## Install
+
+```bash
+npm install @autter/runtime-node
+```
+
+## 1. Browser relay
+
+The browser tracker posts to your backend; this handler validates and
+whitelist-sanitises the payload, attaches your private ingest key
+server-side, forwards asynchronously, and returns 202 immediately.
+
+Express / Node http:
+
+```ts
+import { createBrowserRelayHandler } from "@autter/runtime-node";
+
+app.post(
+  "/api/autter-runtime",
+  createBrowserRelayHandler({ apiKey: process.env.AUTTER_RUNTIME_KEY! }),
+);
+```
+
+Next.js App Router / any fetch-style runtime:
+
+```ts
+import { createBrowserRelayFetchHandler } from "@autter/runtime-node";
+
+export const POST = createBrowserRelayFetchHandler({
+  apiKey: process.env.AUTTER_RUNTIME_KEY!,
+});
+```
+
+Options: `endpoint` (default `https://otlp.autter.dev`), `maxBodyBytes`
+(default 64 KB), `onError`.
+
+## 2. Server tracker
+
+```ts
+// instrument.ts — must run before anything else creates connections
+import { initAutterServer } from "@autter/runtime-node";
+
+const autter = initAutterServer({
+  apiKey: process.env.AUTTER_RUNTIME_KEY!,
+  service: "payments-api",
+  environment: process.env.NODE_ENV,
+  release: process.env.GIT_SHA,
+});
+
+// handled errors — always recorded, never sampled out:
+autter.captureException(err, { "order.id": "…" });
+
+// warnings/info without an exception — same grouping+aggregation as
+// errors, just a lower severity ("fatal" | "error" | "warning" | "info"):
+autter.captureMessage("Legacy /orders lookup used", "warning");
+
+// graceful shutdown flushes exporters:
+await autter.shutdown();
+```
+
+Run it first: `node --require ./instrument.cjs server.js` (CJS), or for
+pure-ESM apps add OTel's loader hook
+(`node --import ./instrument.mjs --experimental-loader=@opentelemetry/instrumentation/hook.mjs server.js`)
+so `http` auto-instrumentation can patch ESM imports.
+
+Defaults (cheap by construction):
+
+| Signal | Default |
+| --- | --- |
+| Captured/unhandled exceptions | 100% (dedicated always-on tracer) |
+| Traces | 1% head sampling (`traceSampleRate`) |
+| Request metrics | exported every 60 s |
+| Logs | not collected |
+
+Crashes are observed via `process.uncaughtExceptionMonitor`, which does
+**not** change your process's exit behaviour; the final flush is
+best-effort. Framework instrumentations are opt-in:
+
+```ts
+import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
+initAutterServer({ ..., instrumentations: [new ExpressInstrumentation()] });
+```
+
+Note on usage rollups: requests are counted from the `http.server.duration`
+metric (100% accurate) and additionally from sampled server spans. At the
+default 1% sampling the span contribution is negligible; if you set
+`traceSampleRate: 1` in development, expect request counts roughly doubled.

package/dist/index.cjs

@@ -0,0 +1,374 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  captureException: () => captureException,
+  captureMessage: () => captureMessage,
+  createBrowserRelayFetchHandler: () => createBrowserRelayFetchHandler,
+  createBrowserRelayHandler: () => createBrowserRelayHandler,
+  initAutterServer: () => initAutterServer,
+  sanitizeBrowserPayload: () => sanitizeBrowserPayload
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/relay.ts
+var IpWindow = class {
+  constructor(limitPerMinute) {
+    this.limitPerMinute = limitPerMinute;
+  }
+  limitPerMinute;
+  windows = /* @__PURE__ */ new Map();
+  allow(ip) {
+    const start = Math.floor(Date.now() / 6e4) * 6e4;
+    const entry = this.windows.get(ip);
+    if (!entry || entry.start !== start) {
+      this.windows.set(ip, { start, count: 1 });
+      if (this.windows.size > 5e4) this.windows.clear();
+      return true;
+    }
+    entry.count += 1;
+    return entry.count <= this.limitPerMinute;
+  }
+};
+function firstForwardedFor(value) {
+  const raw = Array.isArray(value) ? value[0] : value;
+  return raw ? (raw.split(",")[0] ?? "").trim() : "";
+}
+var DEFAULT_ENDPOINT = "https://otlp.autter.dev";
+var DEFAULT_MAX_BODY = 64 * 1024;
+var MAX_EVENTS = 50;
+var EVENT_TYPES = /* @__PURE__ */ new Set([
+  "exception",
+  "unhandled_rejection",
+  "message",
+  "session_start",
+  "track_event"
+]);
+var SEVERITIES = /* @__PURE__ */ new Set(["fatal", "error", "warning", "info"]);
+function sanitizeBrowserPayload(raw) {
+  if (typeof raw !== "object" || raw === null) return null;
+  const p = raw;
+  if (p.version !== 1) return null;
+  if (typeof p.service !== "string" || !p.service) return null;
+  if (typeof p.environment !== "string" || !p.environment) return null;
+  if (!Array.isArray(p.events) || p.events.length > MAX_EVENTS) return null;
+  const events = [];
+  for (const rawEvent of p.events) {
+    if (typeof rawEvent !== "object" || rawEvent === null) return null;
+    const e = rawEvent;
+    if (typeof e.type !== "string" || !EVENT_TYPES.has(e.type)) return null;
+    if (typeof e.timestamp !== "string") return null;
+    events.push({
+      type: e.type,
+      timestamp: e.timestamp,
+      ...typeof e.severity === "string" && SEVERITIES.has(e.severity) ? { severity: e.severity } : {},
+      message: typeof e.message === "string" ? e.message.slice(0, 4e3) : "",
+      ...typeof e.name === "string" ? { name: e.name.slice(0, 200) } : {},
+      ...typeof e.stack === "string" ? { stack: e.stack.slice(0, 32e3) } : {},
+      ...typeof e.errorType === "string" ? { errorType: e.errorType.slice(0, 200) } : {},
+      ...typeof e.filename === "string" ? { filename: e.filename.split("?")[0].slice(0, 1e3) } : {},
+      ...typeof e.line === "number" ? { line: e.line } : {},
+      ...typeof e.column === "number" ? { column: e.column } : {},
+      ...typeof e.route === "string" ? { route: e.route.split("?")[0].slice(0, 1e3) } : {},
+      ...typeof e.context === "object" && e.context !== null ? { context: e.context } : {}
+    });
+  }
+  return {
+    version: 1,
+    ...typeof p.sessionId === "string" ? { sessionId: p.sessionId.slice(0, 100) } : {},
+    service: p.service.slice(0, 200),
+    environment: p.environment.slice(0, 100),
+    ...typeof p.release === "string" ? { release: p.release.slice(0, 200) } : {},
+    events
+  };
+}
+function forward(payload, opts) {
+  const url = `${(opts.endpoint ?? DEFAULT_ENDPOINT).replace(/\/$/, "")}/v1/browser`;
+  void fetch(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${opts.apiKey}`
+    },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(1e4)
+  }).catch((err) => {
+    (opts.onError ?? ((e) => console.warn("autter relay forward failed:", e)))(
+      err
+    );
+  });
+}
+function createBrowserRelayFetchHandler(opts) {
+  const maxBody = opts.maxBodyBytes ?? DEFAULT_MAX_BODY;
+  const limiter = opts.perIpRateLimit === false ? null : new IpWindow(opts.perIpRateLimit ?? 120);
+  return async (request) => {
+    if (request.method !== "POST") {
+      return new Response(null, { status: 405 });
+    }
+    if (limiter) {
+      const ip = firstForwardedFor(request.headers.get("x-forwarded-for")) || "unknown";
+      if (!limiter.allow(ip)) {
+        return new Response(JSON.stringify({ error: "rate limit exceeded" }), {
+          status: 429
+        });
+      }
+    }
+    const text = await request.text();
+    if (text.length > maxBody) {
+      return new Response(JSON.stringify({ error: "payload too large" }), {
+        status: 413
+      });
+    }
+    let raw;
+    try {
+      raw = JSON.parse(text);
+    } catch {
+      return new Response(JSON.stringify({ error: "invalid json" }), {
+        status: 400
+      });
+    }
+    const payload = sanitizeBrowserPayload(raw);
+    if (!payload) {
+      return new Response(JSON.stringify({ error: "invalid payload" }), {
+        status: 400
+      });
+    }
+    forward(payload, opts);
+    return new Response(null, { status: 202 });
+  };
+}
+function createBrowserRelayHandler(opts) {
+  const maxBody = opts.maxBodyBytes ?? DEFAULT_MAX_BODY;
+  const limiter = opts.perIpRateLimit === false ? null : new IpWindow(opts.perIpRateLimit ?? 120);
+  function respond(res, status, body) {
+    res.statusCode = status;
+    if (body) {
+      res.setHeader("content-type", "application/json");
+      res.end(JSON.stringify(body));
+    } else {
+      res.end();
+    }
+  }
+  function handleParsed(raw, res) {
+    const payload = sanitizeBrowserPayload(raw);
+    if (!payload) {
+      respond(res, 400, { error: "invalid payload" });
+      return;
+    }
+    forward(payload, opts);
+    respond(res, 202);
+  }
+  return (req, res) => {
+    if (req.method !== "POST") {
+      respond(res, 405);
+      return;
+    }
+    if (limiter) {
+      const ip = firstForwardedFor(req.headers["x-forwarded-for"]) || req.socket?.remoteAddress || "unknown";
+      if (!limiter.allow(ip)) {
+        respond(res, 429, { error: "rate limit exceeded" });
+        return;
+      }
+    }
+    if (req.body !== void 0) {
+      let raw = req.body;
+      if (typeof raw === "string" || Buffer.isBuffer(raw)) {
+        try {
+          raw = JSON.parse(raw.toString());
+        } catch {
+          respond(res, 400, { error: "invalid json" });
+          return;
+        }
+      }
+      handleParsed(raw, res);
+      return;
+    }
+    const chunks = [];
+    let size = 0;
+    let aborted = false;
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > maxBody) {
+        aborted = true;
+        respond(res, 413, { error: "payload too large" });
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (aborted) return;
+      try {
+        handleParsed(JSON.parse(Buffer.concat(chunks).toString()), res);
+      } catch {
+        respond(res, 400, { error: "invalid json" });
+      }
+    });
+    req.on("error", () => {
+      if (!aborted) respond(res, 400, { error: "read error" });
+    });
+  };
+}
+
+// src/server.ts
+var import_api = require("@opentelemetry/api");
+var import_exporter_metrics_otlp_http = require("@opentelemetry/exporter-metrics-otlp-http");
+var import_exporter_trace_otlp_http = require("@opentelemetry/exporter-trace-otlp-http");
+var import_instrumentation_http = require("@opentelemetry/instrumentation-http");
+var import_resources = require("@opentelemetry/resources");
+var import_sdk_metrics = require("@opentelemetry/sdk-metrics");
+var import_sdk_node = require("@opentelemetry/sdk-node");
+var import_sdk_trace_base = require("@opentelemetry/sdk-trace-base");
+var import_semantic_conventions = require("@opentelemetry/semantic-conventions");
+var active = null;
+function initAutterServer(options) {
+  if (active) return active;
+  const endpoint = (options.endpoint ?? "https://otlp.autter.dev").replace(
+    /\/$/,
+    ""
+  );
+  const headers = { authorization: `Bearer ${options.apiKey}` };
+  const environment = options.environment ?? process.env.NODE_ENV ?? "production";
+  const resource = new import_resources.Resource({
+    [import_semantic_conventions.ATTR_SERVICE_NAME]: options.service,
+    ...options.release ? { [import_semantic_conventions.ATTR_SERVICE_VERSION]: options.release } : {},
+    "deployment.environment": environment
+  });
+  const sdk = new import_sdk_node.NodeSDK({
+    resource,
+    sampler: new import_sdk_trace_base.ParentBasedSampler({
+      root: new import_sdk_trace_base.TraceIdRatioBasedSampler(options.traceSampleRate ?? 0.01)
+    }),
+    traceExporter: new import_exporter_trace_otlp_http.OTLPTraceExporter({
+      url: `${endpoint}/v1/traces`,
+      headers
+    }),
+    metricReader: new import_sdk_metrics.PeriodicExportingMetricReader({
+      exporter: new import_exporter_metrics_otlp_http.OTLPMetricExporter({
+        url: `${endpoint}/v1/metrics`,
+        headers
+      }),
+      exportIntervalMillis: options.metricIntervalMs ?? 6e4
+    }),
+    instrumentations: [
+      new import_instrumentation_http.HttpInstrumentation(),
+      ...options.instrumentations ?? []
+    ]
+  });
+  sdk.start();
+  const errorProvider = new import_sdk_trace_base.BasicTracerProvider({
+    resource,
+    sampler: new import_sdk_trace_base.AlwaysOnSampler(),
+    spanProcessors: [
+      new import_sdk_trace_base.BatchSpanProcessor(
+        new import_exporter_trace_otlp_http.OTLPTraceExporter({ url: `${endpoint}/v1/traces`, headers }),
+        { scheduledDelayMillis: 2e3 }
+      )
+    ]
+  });
+  const errorTracer = errorProvider.getTracer("autter-errors");
+  function captureException2(error, attributes) {
+    const isError = error instanceof Error;
+    const message = isError ? error.message : String(error);
+    const span = errorTracer.startSpan(isError ? error.name : "Error", {
+      attributes: { "autter.severity": "error", ...attributes }
+    });
+    if (isError) {
+      span.recordException(error);
+    } else {
+      span.addEvent("exception", {
+        "exception.type": "Error",
+        "exception.message": message
+      });
+    }
+    span.setStatus({ code: import_api.SpanStatusCode.ERROR, message });
+    span.end();
+  }
+  function captureMessage2(message, severity = "warning", attributes) {
+    const stack = new Error().stack?.split("\n").filter((line, i) => i === 0 || !line.includes("captureMessage")).join("\n");
+    const span = errorTracer.startSpan("Message", {
+      attributes: { "autter.severity": severity, ...attributes }
+    });
+    span.addEvent("exception", {
+      "exception.type": "Message",
+      "exception.message": message,
+      ...stack ? { "exception.stacktrace": stack } : {},
+      "autter.severity": severity
+    });
+    span.setStatus({ code: import_api.SpanStatusCode.ERROR, message });
+    span.end();
+  }
+  if (options.captureGlobalErrors !== false) {
+    process.on("uncaughtExceptionMonitor", (err) => {
+      captureException2(err, { "autter.unhandled": true });
+      void errorProvider.forceFlush().catch(() => {
+      });
+    });
+  }
+  const server = {
+    captureException: captureException2,
+    captureMessage: captureMessage2,
+    shutdown: async () => {
+      active = null;
+      await Promise.allSettled([errorProvider.shutdown(), sdk.shutdown()]);
+    }
+  };
+  active = server;
+  return server;
+}
+function captureException(error, attributes) {
+  if (active) {
+    active.captureException(error, attributes);
+    return;
+  }
+  const span = import_api.trace.getTracer("autter-errors").startSpan(error instanceof Error ? error.name : "Error", { attributes });
+  if (error instanceof Error) span.recordException(error);
+  span.setStatus({
+    code: import_api.SpanStatusCode.ERROR,
+    message: error instanceof Error ? error.message : String(error)
+  });
+  span.end();
+}
+function captureMessage(message, severity = "warning", attributes) {
+  if (active) {
+    active.captureMessage(message, severity, attributes);
+    return;
+  }
+  const span = import_api.trace.getTracer("autter-errors").startSpan("Message", {
+    attributes: { "autter.severity": severity, ...attributes }
+  });
+  span.addEvent("exception", {
+    "exception.type": "Message",
+    "exception.message": message,
+    "autter.severity": severity
+  });
+  span.setStatus({ code: import_api.SpanStatusCode.ERROR, message });
+  span.end();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  captureException,
+  captureMessage,
+  createBrowserRelayFetchHandler,
+  createBrowserRelayHandler,
+  initAutterServer,
+  sanitizeBrowserPayload
+});

package/dist/index.d.cts

@@ -0,0 +1,96 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { Attributes } from '@opentelemetry/api';
+
+/**
+ * Same-origin browser relay. The browser tracker posts to a route on the
+ * customer's own backend; this handler validates + sanitises the payload,
+ * attaches the private ingest key server-side, forwards asynchronously to
+ * the Autter ingester, and returns 202 immediately. The key never reaches
+ * the browser, and there is no CORS/CSP surface.
+ */
+interface RelayOptions {
+    /** Private ingest key (autter_rt_…). Keep it in an env var. */
+    apiKey: string;
+    /** Ingester base URL. Default: https://otlp.autter.dev */
+    endpoint?: string;
+    /** Max accepted request body. Default 64 KB. */
+    maxBodyBytes?: number;
+    /**
+     * The relay route is necessarily public (browsers must reach it), so it
+     * ships with a per-IP fixed-window limit. Default 120 req/min; set
+     * `false` to disable (e.g. when a WAF already rate-limits).
+     */
+    perIpRateLimit?: number | false;
+    /** Called when the async forward fails (default: console.warn). */
+    onError?: (err: unknown) => void;
+}
+declare function sanitizeBrowserPayload(raw: unknown): object | null;
+/**
+ * Fetch-style handler (Next.js App Router route, Remix, Hono, Bun, Deno):
+ *
+ *   export const POST = createBrowserRelayFetchHandler({ apiKey: env.AUTTER_RUNTIME_KEY });
+ */
+declare function createBrowserRelayFetchHandler(opts: RelayOptions): (request: Request) => Promise<Response>;
+/**
+ * Node http / Express / Fastify(raw) handler:
+ *
+ *   app.post("/api/autter-runtime", createBrowserRelayHandler({ apiKey: process.env.AUTTER_RUNTIME_KEY! }));
+ *
+ * Works with or without a body parser: uses `req.body` when a middleware
+ * already parsed it, otherwise reads the raw stream (capped).
+ */
+declare function createBrowserRelayHandler(opts: RelayOptions): (req: IncomingMessage & {
+    body?: unknown;
+}, res: ServerResponse) => void;
+
+/**
+ * Curated OpenTelemetry setup for Autter Runtime — deliberately NOT the
+ * auto-instrumentation metapackage. Default data-volume policy:
+ *
+ *   errors / captured exceptions : 100%  (dedicated always-on error tracer)
+ *   successful traces            : 1%    (head sampling, configurable)
+ *   request metrics              : aggregated every 60 s
+ *   logs                         : not collected
+ *
+ * Exports OTLP/HTTP JSON to the Autter ingester (`/v1/traces`,
+ * `/v1/metrics`) with the ingest key as a bearer header.
+ */
+interface AutterServerOptions {
+    /** Private ingest key (autter_rt_…). */
+    apiKey: string;
+    /** Ingester base URL. Default: https://otlp.autter.dev */
+    endpoint?: string;
+    service: string;
+    environment?: string;
+    /** e.g. a git SHA. Maps to service.version / release. */
+    release?: string;
+    /** Head-sampling ratio for regular traces. Default 0.01 (1%). */
+    traceSampleRate?: number;
+    /** Metric export interval. Default 60_000 ms. */
+    metricIntervalMs?: number;
+    /** Capture crashing exceptions via process.uncaughtExceptionMonitor (default true). */
+    captureGlobalErrors?: boolean;
+    /** Extra instrumentations (e.g. `new ExpressInstrumentation()`). */
+    instrumentations?: unknown[];
+}
+type AutterSeverity = "fatal" | "error" | "warning" | "info";
+interface AutterServer {
+    /** Report a handled exception. Always recorded (never sampled out). */
+    captureException(error: unknown, attributes?: Attributes): void;
+    /**
+     * Report a warning (or info) without an exception — deprecated code
+     * paths, recoverable failures, degraded dependencies. Stored alongside
+     * errors with a lower severity so aggregations can slice one dataset.
+     */
+    captureMessage(message: string, severity?: AutterSeverity, attributes?: Attributes): void;
+    /** Flush and stop all exporters. Call on graceful shutdown. */
+    shutdown(): Promise<void>;
+}
+declare function initAutterServer(options: AutterServerOptions): AutterServer;
+/** Module-level convenience — routes to the active server, or degrades to a
+ * span on the global tracer so libraries can call it unconditionally. */
+declare function captureException(error: unknown, attributes?: Attributes): void;
+/** Module-level convenience for warnings/info — see AutterServer.captureMessage. */
+declare function captureMessage(message: string, severity?: AutterSeverity, attributes?: Attributes): void;
+
+export { type AutterServer, type AutterServerOptions, type AutterSeverity, type RelayOptions, captureException, captureMessage, createBrowserRelayFetchHandler, createBrowserRelayHandler, initAutterServer, sanitizeBrowserPayload };

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { Attributes } from '@opentelemetry/api';
+
+/**
+ * Same-origin browser relay. The browser tracker posts to a route on the
+ * customer's own backend; this handler validates + sanitises the payload,
+ * attaches the private ingest key server-side, forwards asynchronously to
+ * the Autter ingester, and returns 202 immediately. The key never reaches
+ * the browser, and there is no CORS/CSP surface.
+ */
+interface RelayOptions {
+    /** Private ingest key (autter_rt_…). Keep it in an env var. */
+    apiKey: string;
+    /** Ingester base URL. Default: https://otlp.autter.dev */
+    endpoint?: string;
+    /** Max accepted request body. Default 64 KB. */
+    maxBodyBytes?: number;
+    /**
+     * The relay route is necessarily public (browsers must reach it), so it
+     * ships with a per-IP fixed-window limit. Default 120 req/min; set
+     * `false` to disable (e.g. when a WAF already rate-limits).
+     */
+    perIpRateLimit?: number | false;
+    /** Called when the async forward fails (default: console.warn). */
+    onError?: (err: unknown) => void;
+}
+declare function sanitizeBrowserPayload(raw: unknown): object | null;
+/**
+ * Fetch-style handler (Next.js App Router route, Remix, Hono, Bun, Deno):
+ *
+ *   export const POST = createBrowserRelayFetchHandler({ apiKey: env.AUTTER_RUNTIME_KEY });
+ */
+declare function createBrowserRelayFetchHandler(opts: RelayOptions): (request: Request) => Promise<Response>;
+/**
+ * Node http / Express / Fastify(raw) handler:
+ *
+ *   app.post("/api/autter-runtime", createBrowserRelayHandler({ apiKey: process.env.AUTTER_RUNTIME_KEY! }));
+ *
+ * Works with or without a body parser: uses `req.body` when a middleware
+ * already parsed it, otherwise reads the raw stream (capped).
+ */
+declare function createBrowserRelayHandler(opts: RelayOptions): (req: IncomingMessage & {
+    body?: unknown;
+}, res: ServerResponse) => void;
+
+/**
+ * Curated OpenTelemetry setup for Autter Runtime — deliberately NOT the
+ * auto-instrumentation metapackage. Default data-volume policy:
+ *
+ *   errors / captured exceptions : 100%  (dedicated always-on error tracer)
+ *   successful traces            : 1%    (head sampling, configurable)
+ *   request metrics              : aggregated every 60 s
+ *   logs                         : not collected
+ *
+ * Exports OTLP/HTTP JSON to the Autter ingester (`/v1/traces`,
+ * `/v1/metrics`) with the ingest key as a bearer header.
+ */
+interface AutterServerOptions {
+    /** Private ingest key (autter_rt_…). */
+    apiKey: string;
+    /** Ingester base URL. Default: https://otlp.autter.dev */
+    endpoint?: string;
+    service: string;
+    environment?: string;
+    /** e.g. a git SHA. Maps to service.version / release. */
+    release?: string;
+    /** Head-sampling ratio for regular traces. Default 0.01 (1%). */
+    traceSampleRate?: number;
+    /** Metric export interval. Default 60_000 ms. */
+    metricIntervalMs?: number;
+    /** Capture crashing exceptions via process.uncaughtExceptionMonitor (default true). */
+    captureGlobalErrors?: boolean;
+    /** Extra instrumentations (e.g. `new ExpressInstrumentation()`). */
+    instrumentations?: unknown[];
+}
+type AutterSeverity = "fatal" | "error" | "warning" | "info";
+interface AutterServer {
+    /** Report a handled exception. Always recorded (never sampled out). */
+    captureException(error: unknown, attributes?: Attributes): void;
+    /**
+     * Report a warning (or info) without an exception — deprecated code
+     * paths, recoverable failures, degraded dependencies. Stored alongside
+     * errors with a lower severity so aggregations can slice one dataset.
+     */
+    captureMessage(message: string, severity?: AutterSeverity, attributes?: Attributes): void;
+    /** Flush and stop all exporters. Call on graceful shutdown. */
+    shutdown(): Promise<void>;
+}
+declare function initAutterServer(options: AutterServerOptions): AutterServer;
+/** Module-level convenience — routes to the active server, or degrades to a
+ * span on the global tracer so libraries can call it unconditionally. */
+declare function captureException(error: unknown, attributes?: Attributes): void;
+/** Module-level convenience for warnings/info — see AutterServer.captureMessage. */
+declare function captureMessage(message: string, severity?: AutterSeverity, attributes?: Attributes): void;
+
+export { type AutterServer, type AutterServerOptions, type AutterSeverity, type RelayOptions, captureException, captureMessage, createBrowserRelayFetchHandler, createBrowserRelayHandler, initAutterServer, sanitizeBrowserPayload };

package/dist/index.js

@@ -0,0 +1,351 @@
+// src/relay.ts
+var IpWindow = class {
+  constructor(limitPerMinute) {
+    this.limitPerMinute = limitPerMinute;
+  }
+  limitPerMinute;
+  windows = /* @__PURE__ */ new Map();
+  allow(ip) {
+    const start = Math.floor(Date.now() / 6e4) * 6e4;
+    const entry = this.windows.get(ip);
+    if (!entry || entry.start !== start) {
+      this.windows.set(ip, { start, count: 1 });
+      if (this.windows.size > 5e4) this.windows.clear();
+      return true;
+    }
+    entry.count += 1;
+    return entry.count <= this.limitPerMinute;
+  }
+};
+function firstForwardedFor(value) {
+  const raw = Array.isArray(value) ? value[0] : value;
+  return raw ? (raw.split(",")[0] ?? "").trim() : "";
+}
+var DEFAULT_ENDPOINT = "https://otlp.autter.dev";
+var DEFAULT_MAX_BODY = 64 * 1024;
+var MAX_EVENTS = 50;
+var EVENT_TYPES = /* @__PURE__ */ new Set([
+  "exception",
+  "unhandled_rejection",
+  "message",
+  "session_start",
+  "track_event"
+]);
+var SEVERITIES = /* @__PURE__ */ new Set(["fatal", "error", "warning", "info"]);
+function sanitizeBrowserPayload(raw) {
+  if (typeof raw !== "object" || raw === null) return null;
+  const p = raw;
+  if (p.version !== 1) return null;
+  if (typeof p.service !== "string" || !p.service) return null;
+  if (typeof p.environment !== "string" || !p.environment) return null;
+  if (!Array.isArray(p.events) || p.events.length > MAX_EVENTS) return null;
+  const events = [];
+  for (const rawEvent of p.events) {
+    if (typeof rawEvent !== "object" || rawEvent === null) return null;
+    const e = rawEvent;
+    if (typeof e.type !== "string" || !EVENT_TYPES.has(e.type)) return null;
+    if (typeof e.timestamp !== "string") return null;
+    events.push({
+      type: e.type,
+      timestamp: e.timestamp,
+      ...typeof e.severity === "string" && SEVERITIES.has(e.severity) ? { severity: e.severity } : {},
+      message: typeof e.message === "string" ? e.message.slice(0, 4e3) : "",
+      ...typeof e.name === "string" ? { name: e.name.slice(0, 200) } : {},
+      ...typeof e.stack === "string" ? { stack: e.stack.slice(0, 32e3) } : {},
+      ...typeof e.errorType === "string" ? { errorType: e.errorType.slice(0, 200) } : {},
+      ...typeof e.filename === "string" ? { filename: e.filename.split("?")[0].slice(0, 1e3) } : {},
+      ...typeof e.line === "number" ? { line: e.line } : {},
+      ...typeof e.column === "number" ? { column: e.column } : {},
+      ...typeof e.route === "string" ? { route: e.route.split("?")[0].slice(0, 1e3) } : {},
+      ...typeof e.context === "object" && e.context !== null ? { context: e.context } : {}
+    });
+  }
+  return {
+    version: 1,
+    ...typeof p.sessionId === "string" ? { sessionId: p.sessionId.slice(0, 100) } : {},
+    service: p.service.slice(0, 200),
+    environment: p.environment.slice(0, 100),
+    ...typeof p.release === "string" ? { release: p.release.slice(0, 200) } : {},
+    events
+  };
+}
+function forward(payload, opts) {
+  const url = `${(opts.endpoint ?? DEFAULT_ENDPOINT).replace(/\/$/, "")}/v1/browser`;
+  void fetch(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${opts.apiKey}`
+    },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(1e4)
+  }).catch((err) => {
+    (opts.onError ?? ((e) => console.warn("autter relay forward failed:", e)))(
+      err
+    );
+  });
+}
+function createBrowserRelayFetchHandler(opts) {
+  const maxBody = opts.maxBodyBytes ?? DEFAULT_MAX_BODY;
+  const limiter = opts.perIpRateLimit === false ? null : new IpWindow(opts.perIpRateLimit ?? 120);
+  return async (request) => {
+    if (request.method !== "POST") {
+      return new Response(null, { status: 405 });
+    }
+    if (limiter) {
+      const ip = firstForwardedFor(request.headers.get("x-forwarded-for")) || "unknown";
+      if (!limiter.allow(ip)) {
+        return new Response(JSON.stringify({ error: "rate limit exceeded" }), {
+          status: 429
+        });
+      }
+    }
+    const text = await request.text();
+    if (text.length > maxBody) {
+      return new Response(JSON.stringify({ error: "payload too large" }), {
+        status: 413
+      });
+    }
+    let raw;
+    try {
+      raw = JSON.parse(text);
+    } catch {
+      return new Response(JSON.stringify({ error: "invalid json" }), {
+        status: 400
+      });
+    }
+    const payload = sanitizeBrowserPayload(raw);
+    if (!payload) {
+      return new Response(JSON.stringify({ error: "invalid payload" }), {
+        status: 400
+      });
+    }
+    forward(payload, opts);
+    return new Response(null, { status: 202 });
+  };
+}
+function createBrowserRelayHandler(opts) {
+  const maxBody = opts.maxBodyBytes ?? DEFAULT_MAX_BODY;
+  const limiter = opts.perIpRateLimit === false ? null : new IpWindow(opts.perIpRateLimit ?? 120);
+  function respond(res, status, body) {
+    res.statusCode = status;
+    if (body) {
+      res.setHeader("content-type", "application/json");
+      res.end(JSON.stringify(body));
+    } else {
+      res.end();
+    }
+  }
+  function handleParsed(raw, res) {
+    const payload = sanitizeBrowserPayload(raw);
+    if (!payload) {
+      respond(res, 400, { error: "invalid payload" });
+      return;
+    }
+    forward(payload, opts);
+    respond(res, 202);
+  }
+  return (req, res) => {
+    if (req.method !== "POST") {
+      respond(res, 405);
+      return;
+    }
+    if (limiter) {
+      const ip = firstForwardedFor(req.headers["x-forwarded-for"]) || req.socket?.remoteAddress || "unknown";
+      if (!limiter.allow(ip)) {
+        respond(res, 429, { error: "rate limit exceeded" });
+        return;
+      }
+    }
+    if (req.body !== void 0) {
+      let raw = req.body;
+      if (typeof raw === "string" || Buffer.isBuffer(raw)) {
+        try {
+          raw = JSON.parse(raw.toString());
+        } catch {
+          respond(res, 400, { error: "invalid json" });
+          return;
+        }
+      }
+      handleParsed(raw, res);
+      return;
+    }
+    const chunks = [];
+    let size = 0;
+    let aborted = false;
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > maxBody) {
+        aborted = true;
+        respond(res, 413, { error: "payload too large" });
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (aborted) return;
+      try {
+        handleParsed(JSON.parse(Buffer.concat(chunks).toString()), res);
+      } catch {
+        respond(res, 400, { error: "invalid json" });
+      }
+    });
+    req.on("error", () => {
+      if (!aborted) respond(res, 400, { error: "read error" });
+    });
+  };
+}
+
+// src/server.ts
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
+import { Resource } from "@opentelemetry/resources";
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import {
+  BatchSpanProcessor,
+  ParentBasedSampler,
+  TraceIdRatioBasedSampler,
+  AlwaysOnSampler,
+  BasicTracerProvider
+} from "@opentelemetry/sdk-trace-base";
+import {
+  ATTR_SERVICE_NAME,
+  ATTR_SERVICE_VERSION
+} from "@opentelemetry/semantic-conventions";
+var active = null;
+function initAutterServer(options) {
+  if (active) return active;
+  const endpoint = (options.endpoint ?? "https://otlp.autter.dev").replace(
+    /\/$/,
+    ""
+  );
+  const headers = { authorization: `Bearer ${options.apiKey}` };
+  const environment = options.environment ?? process.env.NODE_ENV ?? "production";
+  const resource = new Resource({
+    [ATTR_SERVICE_NAME]: options.service,
+    ...options.release ? { [ATTR_SERVICE_VERSION]: options.release } : {},
+    "deployment.environment": environment
+  });
+  const sdk = new NodeSDK({
+    resource,
+    sampler: new ParentBasedSampler({
+      root: new TraceIdRatioBasedSampler(options.traceSampleRate ?? 0.01)
+    }),
+    traceExporter: new OTLPTraceExporter({
+      url: `${endpoint}/v1/traces`,
+      headers
+    }),
+    metricReader: new PeriodicExportingMetricReader({
+      exporter: new OTLPMetricExporter({
+        url: `${endpoint}/v1/metrics`,
+        headers
+      }),
+      exportIntervalMillis: options.metricIntervalMs ?? 6e4
+    }),
+    instrumentations: [
+      new HttpInstrumentation(),
+      ...options.instrumentations ?? []
+    ]
+  });
+  sdk.start();
+  const errorProvider = new BasicTracerProvider({
+    resource,
+    sampler: new AlwaysOnSampler(),
+    spanProcessors: [
+      new BatchSpanProcessor(
+        new OTLPTraceExporter({ url: `${endpoint}/v1/traces`, headers }),
+        { scheduledDelayMillis: 2e3 }
+      )
+    ]
+  });
+  const errorTracer = errorProvider.getTracer("autter-errors");
+  function captureException2(error, attributes) {
+    const isError = error instanceof Error;
+    const message = isError ? error.message : String(error);
+    const span = errorTracer.startSpan(isError ? error.name : "Error", {
+      attributes: { "autter.severity": "error", ...attributes }
+    });
+    if (isError) {
+      span.recordException(error);
+    } else {
+      span.addEvent("exception", {
+        "exception.type": "Error",
+        "exception.message": message
+      });
+    }
+    span.setStatus({ code: SpanStatusCode.ERROR, message });
+    span.end();
+  }
+  function captureMessage2(message, severity = "warning", attributes) {
+    const stack = new Error().stack?.split("\n").filter((line, i) => i === 0 || !line.includes("captureMessage")).join("\n");
+    const span = errorTracer.startSpan("Message", {
+      attributes: { "autter.severity": severity, ...attributes }
+    });
+    span.addEvent("exception", {
+      "exception.type": "Message",
+      "exception.message": message,
+      ...stack ? { "exception.stacktrace": stack } : {},
+      "autter.severity": severity
+    });
+    span.setStatus({ code: SpanStatusCode.ERROR, message });
+    span.end();
+  }
+  if (options.captureGlobalErrors !== false) {
+    process.on("uncaughtExceptionMonitor", (err) => {
+      captureException2(err, { "autter.unhandled": true });
+      void errorProvider.forceFlush().catch(() => {
+      });
+    });
+  }
+  const server = {
+    captureException: captureException2,
+    captureMessage: captureMessage2,
+    shutdown: async () => {
+      active = null;
+      await Promise.allSettled([errorProvider.shutdown(), sdk.shutdown()]);
+    }
+  };
+  active = server;
+  return server;
+}
+function captureException(error, attributes) {
+  if (active) {
+    active.captureException(error, attributes);
+    return;
+  }
+  const span = trace.getTracer("autter-errors").startSpan(error instanceof Error ? error.name : "Error", { attributes });
+  if (error instanceof Error) span.recordException(error);
+  span.setStatus({
+    code: SpanStatusCode.ERROR,
+    message: error instanceof Error ? error.message : String(error)
+  });
+  span.end();
+}
+function captureMessage(message, severity = "warning", attributes) {
+  if (active) {
+    active.captureMessage(message, severity, attributes);
+    return;
+  }
+  const span = trace.getTracer("autter-errors").startSpan("Message", {
+    attributes: { "autter.severity": severity, ...attributes }
+  });
+  span.addEvent("exception", {
+    "exception.type": "Message",
+    "exception.message": message,
+    "autter.severity": severity
+  });
+  span.setStatus({ code: SpanStatusCode.ERROR, message });
+  span.end();
+}
+export {
+  captureException,
+  captureMessage,
+  createBrowserRelayFetchHandler,
+  createBrowserRelayHandler,
+  initAutterServer,
+  sanitizeBrowserPayload
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+	"name": "@autter/runtime-node",
+	"version": "0.1.0",
+	"description": "Autter Runtime for Node.js: same-origin browser relay handler + curated OpenTelemetry server tracker",
+	"license": "MIT",
+	"type": "module",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Autter-dev/autter-runtime.git",
+		"directory": "packages/runtime-node"
+	},
+	"scripts": {
+		"build": "tsup src/index.ts --format esm,cjs --dts --target node20 --clean"
+	},
+	"dependencies": {
+		"@opentelemetry/api": "^1.9.0",
+		"@opentelemetry/exporter-metrics-otlp-http": "^0.57.1",
+		"@opentelemetry/exporter-trace-otlp-http": "^0.57.1",
+		"@opentelemetry/instrumentation-http": "^0.57.1",
+		"@opentelemetry/resources": "^1.30.1",
+		"@opentelemetry/sdk-metrics": "^1.30.1",
+		"@opentelemetry/sdk-node": "^0.57.1",
+		"@opentelemetry/sdk-trace-base": "^1.30.1",
+		"@opentelemetry/semantic-conventions": "^1.28.0"
+	},
+	"devDependencies": {
+		"@types/node": "^22.10.0",
+		"tsup": "^8.3.5",
+		"typescript": "^5.7.0"
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"homepage": "https://github.com/Autter-dev/autter-runtime#readme",
+	"bugs": "https://github.com/Autter-dev/autter-runtime/issues",
+	"keywords": [
+		"opentelemetry",
+		"otlp",
+		"error-tracking",
+		"telemetry",
+		"nodejs",
+		"express"
+	]
+}