@heystack/otel 0.0.1 → 0.2.1

package/README.md

@@ -1,15 +1,99 @@
 # @heystack/otel
 
-One-call OpenTelemetry tracing that exports to Heystack.
+Runtime-aware OpenTelemetry tracing that exports to Heystack. One import per runtime, so the `.` entry stays safe to load anywhere (including Edge/Workers) without dragging in the Node SDK.
 
 ```bash
 npm install @heystack/otel
 ```
 
+Always read your key from the environment — never paste it into source:
+
+```bash
+# .env
+HEYSTACK_API_KEY=sk_live_…
+```
+
+> **Requires `@heystack/otel` `>=0.2.0`.** See [Migration](#migration--versioning) below.
+
+## Runtime matrix
+
+| Runtime | Import | Notes |
+| --- | --- | --- |
+| Next.js — **any** deploy target (Vercel/Node **and** Cloudflare/OpenNext) | `@heystack/otel/next` | `registerHeystack` in `instrumentation.ts`. Auto-detects Node vs Cloudflare workerd and picks the right exporter. No-op on Edge. |
+| Standalone Cloudflare Workers (hand-written `export default { fetch }`) | `@heystack/otel/workers` | `instrument()` wraps your handler. Fetch-based exporter, flushes via `ctx.waitUntil`. |
+| Node / Express / Fastify / NestJS (long-running server) | `@heystack/otel/node` | `initHeystack`: auto-instrumentations + graceful shutdown. |
+| Anywhere (pure helpers) | `@heystack/otel` | `buildExporterConfig`, types. No Node SDK loaded. |
+
+## Node / Express / etc.
+
 At the very top of your app's entry file:
+
+```ts
+import { initHeystack } from "@heystack/otel/node";
+
+initHeystack({ apiKey: process.env.HEYSTACK_API_KEY, service: "my-app" });
+```
+
+This enables auto-instrumentations (HTTP, Express, etc.) so you get spans without manual wiring.
+
+## Next.js (any deploy target, including Cloudflare/OpenNext)
+
+In `instrumentation.ts` at the project root:
+
+```ts
+export async function register() {
+  const { registerHeystack } = await import("@heystack/otel/next");
+  await registerHeystack({ service: "my-app" });
+}
+```
+
+`apiKey` defaults to `process.env.HEYSTACK_API_KEY`. `registerHeystack` is **runtime-aware** and safe to call unconditionally:
+
+- **Vercel / Node deploys** → uses the Node OTel SDK (auto-instrumentations).
+- **Cloudflare / OpenNext (workerd)** → Next still reports `NEXT_RUNTIME === "nodejs"`, but the code actually runs on workerd where the Node SDK's `node:http` OTLP exporter can't send (it initializes and silently exports nothing). `registerHeystack` detects workerd and registers the **fetch-based** exporter instead, so framework spans actually ship. No separate setup or import needed.
+- **Edge runtime** → no-op (neither SDK can run there).
+
+## Standalone Cloudflare Workers
+
+For a hand-written Worker (`export default { fetch }`), wrap the handler with `instrument()`:
+
+```ts
+import { instrument } from "@heystack/otel/workers";
+
+export default instrument(
+  {
+    async fetch(req, env, ctx) {
+      return new Response("ok");
+    },
+  },
+  { service: "my-worker" }, // apiKey defaults to env.HEYSTACK_API_KEY
+);
+```
+
+`instrument()` must be the **outermost** wrapper if other middleware also wraps the handler, so the request span covers everything inside:
+
 ```ts
-import { initHeystack } from "@heystack/otel";
-initHeystack({ apiKey: process.env.HEYSTACK_KEY!, service: "my-app" });
+export default instrument(withOtherMiddleware(worker), { service: "my-worker" });
 ```
 
+Set the key as a secret: `wrangler secret put HEYSTACK_API_KEY`.
+
+## Flushing
+
+On Workers/edge the export is a `fetch()` POST, and the isolate can be torn down the instant your handler returns. **You must let that POST complete or the trace is silently dropped** — this is the #1 cause of flaky Workers tracing. `flushHeystack()` and `instrument()`'s built-in flush both await the in-flight fetch (not just the OTel span processor, which does *not* wait for it).
+
+- **Standalone Workers (`instrument()`)** — flushes automatically. After the response it `ctx.waitUntil`s a promise that drains both the span processor and the exporter's in-flight fetch, so the POST finishes before the isolate is killed. No action needed.
+- **Next on workerd (`registerHeystack`)** — there's no per-request `ExecutionContext`, so spans are **not** auto-flushed. For guaranteed delivery, `import { flushHeystack } from "@heystack/otel/workers"` and call it from a response hook (or `ctx.waitUntil(flushHeystack())` if you have a ctx) after handling a request. `flushHeystack()` awaits the export fetch.
+- **Node (`initHeystack`)** — flushes on `SIGTERM`/`SIGINT` automatically.
+
+## Migration / versioning
+
+- **Pin `@heystack/otel` `>=0.2.0`** — the workerd-aware `/next` path and `initHeystackWorkers` / `flushHeystack` exports were added in 0.2.0.
+- The pre-0.1.0 top-level default `initHeystack({ apiKey })` is **gone**. Use the subpath entries: `@heystack/otel/node`, `@heystack/otel/next`, `@heystack/otel/workers`. The root `@heystack/otel` entry now exposes only pure helpers (`buildExporterConfig`, types).
+
+## Verify it's working
+
+- Pass `debug: true` to `initHeystack` to print OTel diagnostic/export logs to the console.
+- Short-lived processes: `initHeystack` registers `SIGTERM`/`SIGINT` handlers automatically, so the SDK flushes and shuts down before exit and you don't lose the last batch.
+
 Then run your app and make a request — traces appear in your Heystack dashboard within seconds.

package/dist/core.d.ts

@@ -0,0 +1,17 @@
+export declare const DEFAULT_ENDPOINT = "https://ingest.heystack.dev";
+export interface HeystackOptions {
+    /** Your Heystack ingest key (sk_live_...). Prefer process.env.HEYSTACK_API_KEY. */
+    apiKey: string;
+    /** OTel service.name this app reports as. */
+    service: string;
+    /** Override the ingest endpoint (defaults to Heystack production). */
+    endpoint?: string;
+}
+export interface ExporterConfig {
+    url: string;
+    headers: {
+        Authorization: string;
+    };
+}
+/** Pure: derive the OTLP/HTTP traces URL + auth header. Works in any runtime. */
+export declare function buildExporterConfig(o: HeystackOptions): ExporterConfig;

package/dist/core.js

@@ -0,0 +1,6 @@
+export const DEFAULT_ENDPOINT = "https://ingest.heystack.dev";
+/** Pure: derive the OTLP/HTTP traces URL + auth header. Works in any runtime. */
+export function buildExporterConfig(o) {
+    const base = (o.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, "");
+    return { url: `${base}/v1/traces`, headers: { Authorization: `Bearer ${o.apiKey}` } };
+}

package/dist/next.d.ts

@@ -0,0 +1,21 @@
+import type { HeystackOptions } from "./core.js";
+/**
+ * Call from Next.js instrumentation.ts:
+ *   export function register() { registerHeystack({ service: "my-app" }); }
+ * apiKey defaults to process.env.HEYSTACK_API_KEY.
+ *
+ * Runtime-aware: this runs on the Node.js runtime (NEXT_RUNTIME === "nodejs"),
+ * but that runtime can actually be Cloudflare workerd under OpenNext — where the
+ * Node SDK's node:http OTLP exporter silently sends nothing. We detect workerd
+ * and use the fetch-based exporter (@heystack/otel/workers) instead. On the Edge
+ * runtime neither SDK can run, so it's a no-op.
+ *
+ * FLUSH (workerd): there is no per-request `ExecutionContext` on this path, so
+ * spans are NOT auto-flushed and the export fetch may be cut off when the
+ * isolate is torn down. For guaranteed delivery, import and call
+ * `flushHeystack()` from `@heystack/otel/workers` in a response hook (or via
+ * `ctx.waitUntil(flushHeystack())` if you have a ctx) — it awaits the export.
+ */
+export declare function registerHeystack(o: Partial<HeystackOptions> & {
+    service: string;
+}): Promise<void>;

package/dist/next.js

@@ -0,0 +1,45 @@
+/**
+ * Call from Next.js instrumentation.ts:
+ *   export function register() { registerHeystack({ service: "my-app" }); }
+ * apiKey defaults to process.env.HEYSTACK_API_KEY.
+ *
+ * Runtime-aware: this runs on the Node.js runtime (NEXT_RUNTIME === "nodejs"),
+ * but that runtime can actually be Cloudflare workerd under OpenNext — where the
+ * Node SDK's node:http OTLP exporter silently sends nothing. We detect workerd
+ * and use the fetch-based exporter (@heystack/otel/workers) instead. On the Edge
+ * runtime neither SDK can run, so it's a no-op.
+ *
+ * FLUSH (workerd): there is no per-request `ExecutionContext` on this path, so
+ * spans are NOT auto-flushed and the export fetch may be cut off when the
+ * isolate is torn down. For guaranteed delivery, import and call
+ * `flushHeystack()` from `@heystack/otel/workers` in a response hook (or via
+ * `ctx.waitUntil(flushHeystack())` if you have a ctx) — it awaits the export.
+ */
+export async function registerHeystack(o) {
+    // Edge runtime can't run either SDK path — skip.
+    if (process.env.NEXT_RUNTIME === "edge")
+        return;
+    const apiKey = o.apiKey ?? process.env.HEYSTACK_API_KEY;
+    if (!apiKey) {
+        console.warn("[heystack] HEYSTACK_API_KEY not set — tracing disabled");
+        return;
+    }
+    // Detect Cloudflare workerd (OpenNext / Workers). NEXT_RUNTIME is "nodejs" there,
+    // but the Node SDK's node:http exporter can't send — use the fetch exporter instead.
+    const g = globalThis;
+    const onWorkerd = g.navigator?.userAgent === "Cloudflare-Workers" ||
+        (typeof g.caches?.default !== "undefined" && !g.process?.versions?.node);
+    if (onWorkerd) {
+        const { initHeystackWorkers } = await import("./workers.js");
+        initHeystackWorkers({ apiKey, service: o.service, endpoint: o.endpoint });
+    }
+    else {
+        const { initHeystack } = await import("./node.js");
+        initHeystack({
+            apiKey,
+            service: o.service,
+            endpoint: o.endpoint,
+            debug: o.debug,
+        });
+    }
+}

package/dist/node.d.ts

@@ -0,0 +1,12 @@
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { type HeystackOptions } from "./core.js";
+export interface NodeOptions extends HeystackOptions {
+    /** Enable OTel diagnostic logging to console to confirm export. */
+    debug?: boolean;
+    /** Set false to skip auto-instrumentations (you'll then only get framework/manual spans). Default true. */
+    autoInstrument?: boolean;
+}
+/** Initialise Heystack tracing on a Node runtime. Call once, as early as possible. Returns the started SDK. */
+export declare function initHeystack(o: NodeOptions): NodeSDK;
+/** Flush + shutdown the SDK on SIGTERM/SIGINT so short-lived processes don't lose the last batch. */
+export declare function shutdownOnSignals(sdk: NodeSDK): void;

package/dist/node.js

@@ -0,0 +1,30 @@
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
+import { buildExporterConfig } from "./core.js";
+/** Initialise Heystack tracing on a Node runtime. Call once, as early as possible. Returns the started SDK. */
+export function initHeystack(o) {
+    if (o.debug)
+        diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);
+    const cfg = buildExporterConfig(o);
+    const sdk = new NodeSDK({
+        serviceName: o.service,
+        traceExporter: new OTLPTraceExporter({ url: cfg.url, headers: cfg.headers }),
+        instrumentations: o.autoInstrument === false ? [] : [getNodeAutoInstrumentations()],
+    });
+    sdk.start();
+    shutdownOnSignals(sdk);
+    return sdk;
+}
+/** Flush + shutdown the SDK on SIGTERM/SIGINT so short-lived processes don't lose the last batch. */
+export function shutdownOnSignals(sdk) {
+    const stop = () => {
+        sdk
+            .shutdown()
+            .catch(() => { })
+            .finally(() => process.exit(0));
+    };
+    process.once("SIGTERM", stop);
+    process.once("SIGINT", stop);
+}

package/dist/workers.d.ts

@@ -0,0 +1,159 @@
+import { type Span } from "@opentelemetry/api";
+import { BasicTracerProvider, type ReadableSpan, type SpanExporter } from "@opentelemetry/sdk-trace-base";
+import { type HeystackOptions } from "./core.js";
+declare const ExportResultCode: {
+    readonly SUCCESS: 0;
+    readonly FAILED: 1;
+};
+interface ExportResult {
+    code: (typeof ExportResultCode)[keyof typeof ExportResultCode];
+    error?: Error;
+}
+interface OtlpAnyValue {
+    stringValue?: string;
+    intValue?: string;
+    doubleValue?: number;
+    boolValue?: boolean;
+    arrayValue?: {
+        values: OtlpAnyValue[];
+    };
+}
+interface OtlpKeyValue {
+    key: string;
+    value: OtlpAnyValue;
+}
+interface OtlpSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: OtlpKeyValue[];
+    status: {
+        code: number;
+        message?: string;
+    };
+}
+interface OtlpTracesPayload {
+    resourceSpans: {
+        resource: {
+            attributes: OtlpKeyValue[];
+        };
+        scopeSpans: {
+            spans: OtlpSpan[];
+        }[];
+    }[];
+}
+/**
+ * Serialize a batch of ended spans into a single OTLP/JSON traces payload.
+ *
+ * All spans in a SimpleSpanProcessor batch share the same per-request provider,
+ * hence the same resource, so we emit a single resourceSpans entry.
+ */
+export declare function serializeSpans(spans: ReadableSpan[]): OtlpTracesPayload;
+/**
+ * A WinterCG-compatible OTLP/JSON span exporter. POSTs ended spans to the
+ * Heystack ingest using the platform `fetch` — no Node built-ins.
+ */
+export declare class HeystackSpanExporter implements SpanExporter {
+    private readonly url;
+    private readonly headers;
+    private shutdownState;
+    /**
+     * In-flight export fetches. Each `export()` adds its settled-when-the-POST-
+     * completes promise here and removes it on `finally`. `forceFlush()` awaits
+     * this set so callers (and `ctx.waitUntil`) genuinely wait for the network
+     * write before the isolate is torn down — otherwise traces are silently
+     * dropped on fast-responding Workers/edge handlers.
+     */
+    private readonly pending;
+    constructor(options: HeystackOptions);
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+    /**
+     * Resolve only once every in-flight export fetch has settled. This is the
+     * guaranteed drain path: the OTel `SimpleSpanProcessor.forceFlush()` does not
+     * await our fire-and-forget fetch, so callers must await this directly (see
+     * `flushHeystack` and `instrument`).
+     */
+    forceFlush(): Promise<void>;
+}
+export interface WorkersConfig {
+    service: string;
+    /** Defaults to env.HEYSTACK_API_KEY at request time if omitted. */
+    apiKey?: string;
+    endpoint?: string;
+}
+/**
+ * A `BasicTracerProvider` with the underlying `HeystackSpanExporter` attached so
+ * flush paths can drain its in-flight fetches directly (the OTel processor's
+ * `forceFlush()` does not await our fire-and-forget fetch).
+ */
+export type HeystackTracerProvider = BasicTracerProvider & {
+    readonly heystackExporter: HeystackSpanExporter;
+};
+/**
+ * Build a `BasicTracerProvider` wired to a `HeystackSpanExporter` via a
+ * `SimpleSpanProcessor`. Exposed for advanced users who want to add manual
+ * spans; for typical use prefer {@link instrument}.
+ *
+ * On Workers each request should get its own short-lived provider so its spans
+ * can be flushed. IMPORTANT: to actually wait for the export network write you
+ * must drain the exporter — `await provider.heystackExporter.forceFlush()` (or
+ * `flushHeystack()`), not just `provider.forceFlush()`.
+ */
+export declare function createTracerProvider(config: HeystackOptions): HeystackTracerProvider;
+/**
+ * Register Heystack as the global tracer provider on a Workers/edge runtime
+ * (workerd). Spans from the host framework (e.g. Next.js) export over fetch.
+ * Use this instead of @heystack/otel/node when running on Cloudflare/edge.
+ *
+ * FLUSH: there is no per-request `ExecutionContext` on this path, so spans are
+ * NOT auto-flushed. To guarantee delivery on workerd, call `flushHeystack()`
+ * (which awaits the export fetch) from a response hook — or hand it to
+ * `ctx.waitUntil(flushHeystack())` if you do have a ctx. Returns the provider.
+ */
+export declare function initHeystackWorkers(config: WorkersConfig & {
+    apiKey: string;
+}): HeystackTracerProvider;
+/**
+ * Force-flush any pending spans AND wait for the export network write to
+ * complete. This awaits both the OTel provider's `forceFlush()` (drains the
+ * span processor) and the exporter's own pending-fetch set (the part the OTel
+ * processor does not await) — so on workerd you can hand this to
+ * `ctx.waitUntil(flushHeystack())` and the POST genuinely finishes before the
+ * isolate is torn down. Best-effort no-op if no provider is registered.
+ */
+export declare function flushHeystack(): Promise<void>;
+/** Reset the singleton global provider. Internal/testing helper. */
+export declare function __resetProvider(): void;
+/** Reset the once-only no-key warning. Internal/testing helper. */
+export declare function __resetWarnings(): void;
+interface FetchHandler<E> {
+    fetch: (req: Request, env: E, ctx: ExecutionContext) => Promise<Response> | Response;
+}
+/**
+ * Wrap a Worker's default export so every request is auto-traced with a SERVER
+ * span.
+ *
+ * FLUSH (CRITICAL on Workers/edge): the export is a `fetch()` POST. After
+ * `span.end()` we `ctx.waitUntil` a promise that awaits BOTH the provider's
+ * span processor AND the exporter's in-flight fetch, so the network write
+ * completes before the isolate is torn down. Without this, fast-responding
+ * handlers return before the POST finishes and the trace is silently dropped.
+ *
+ *   import { instrument } from "@heystack/otel/workers";
+ *   export default instrument(
+ *     { async fetch(req, env, ctx) { return new Response("ok"); } },
+ *     { service: "my-worker" },
+ *   );
+ *
+ * If no API key is available (neither `config.apiKey` nor
+ * `env.HEYSTACK_API_KEY`), the handler runs untraced.
+ */
+export declare function instrument<E = unknown>(handler: FetchHandler<E>, config: WorkersConfig): {
+    fetch: (req: Request, env: E, ctx: ExecutionContext) => Promise<Response>;
+};
+export type { Span };

package/dist/workers.js

@@ -0,0 +1,338 @@
+/// <reference types="@cloudflare/workers-types" />
+//
+// Native Cloudflare Workers / Vercel Edge tracing path for Heystack.
+//
+// Unlike `@heystack/otel/node`, this entry contains NO Node built-ins. It uses
+// only `@opentelemetry/api`, `@opentelemetry/sdk-trace-base`,
+// `@opentelemetry/resources` and the platform `fetch` — all WinterCG-safe — and
+// ships its own OTLP/JSON-over-fetch span exporter so it runs on Workers/Edge
+// where the Node SDK cannot.
+import { context, trace, SpanKind, SpanStatusCode, } from "@opentelemetry/api";
+import { Resource } from "@opentelemetry/resources";
+import { BasicTracerProvider, SimpleSpanProcessor, } from "@opentelemetry/sdk-trace-base";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { buildExporterConfig } from "./core.js";
+// `ExportResult` / `ExportResultCode` mirror `@opentelemetry/core`. We define
+// them inline (structurally identical) rather than import them: core is only a
+// transitive dep of sdk-trace-base and isn't reliably resolvable, and keeping it
+// out guarantees no extra (potentially node-platform) code in the bundle.
+const ExportResultCode = { SUCCESS: 0, FAILED: 1 };
+/** Convert an OTel HrTime `[seconds, nanos]` tuple to a nanosecond string. */
+function hrTimeToUnixNano(time) {
+    // BigInt math keeps full nanosecond precision without float rounding.
+    return (BigInt(time[0]) * 1000000000n + BigInt(time[1])).toString();
+}
+/** Map a single attribute value to the OTLP/JSON tagged-union form. */
+function toAnyValue(value) {
+    if (typeof value === "string")
+        return { stringValue: value };
+    if (typeof value === "boolean")
+        return { boolValue: value };
+    if (typeof value === "number") {
+        // OTLP distinguishes int from double; Number.isInteger picks the int tag.
+        return Number.isInteger(value)
+            ? { intValue: String(value) }
+            : { doubleValue: value };
+    }
+    if (Array.isArray(value)) {
+        return { arrayValue: { values: value.map(toAnyValue) } };
+    }
+    // Fallback: stringify anything else (objects, bigint, etc.).
+    return { stringValue: String(value) };
+}
+function toKeyValues(attrs) {
+    const out = [];
+    if (!attrs)
+        return out;
+    for (const key of Object.keys(attrs)) {
+        const v = attrs[key];
+        if (v === undefined || v === null)
+            continue;
+        out.push({ key, value: toAnyValue(v) });
+    }
+    return out;
+}
+/**
+ * Map the OTel API `SpanKind` enum to the OTLP wire encoding.
+ *
+ * The API enum is INTERNAL=0, SERVER=1, CLIENT=2, PRODUCER=3, CONSUMER=4, but
+ * the OTLP/JSON wire format (and Heystack's schema `SPAN_KIND` map) is
+ * UNSPECIFIED=0, INTERNAL=1, SERVER=2, CLIENT=3, PRODUCER=4, CONSUMER=5 — i.e.
+ * shifted by one. Without this shift, SERVER spans would be ingested as
+ * INTERNAL.
+ */
+function toOtlpKind(kind) {
+    return kind + 1;
+}
+function toStatus(status) {
+    // SpanStatusCode is the int enum (UNSET=0, OK=1, ERROR=2) the schema expects.
+    const out = { code: status.code };
+    if (status.message)
+        out.message = status.message;
+    return out;
+}
+function readableSpanToOtlp(span) {
+    const ctx = span.spanContext();
+    return {
+        traceId: ctx.traceId,
+        spanId: ctx.spanId,
+        parentSpanId: span.parentSpanId ?? "",
+        name: span.name,
+        kind: toOtlpKind(span.kind),
+        startTimeUnixNano: hrTimeToUnixNano(span.startTime),
+        endTimeUnixNano: hrTimeToUnixNano(span.endTime),
+        attributes: toKeyValues(span.attributes),
+        status: toStatus(span.status),
+    };
+}
+/**
+ * Serialize a batch of ended spans into a single OTLP/JSON traces payload.
+ *
+ * All spans in a SimpleSpanProcessor batch share the same per-request provider,
+ * hence the same resource, so we emit a single resourceSpans entry.
+ */
+export function serializeSpans(spans) {
+    const resourceAttrs = spans[0]
+        ? spans[0].resource.attributes
+        : {};
+    return {
+        resourceSpans: [
+            {
+                resource: { attributes: toKeyValues(resourceAttrs) },
+                scopeSpans: [{ spans: spans.map(readableSpanToOtlp) }],
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Exporter
+// ---------------------------------------------------------------------------
+/**
+ * A WinterCG-compatible OTLP/JSON span exporter. POSTs ended spans to the
+ * Heystack ingest using the platform `fetch` — no Node built-ins.
+ */
+export class HeystackSpanExporter {
+    url;
+    headers;
+    shutdownState = false;
+    /**
+     * In-flight export fetches. Each `export()` adds its settled-when-the-POST-
+     * completes promise here and removes it on `finally`. `forceFlush()` awaits
+     * this set so callers (and `ctx.waitUntil`) genuinely wait for the network
+     * write before the isolate is torn down — otherwise traces are silently
+     * dropped on fast-responding Workers/edge handlers.
+     */
+    pending = new Set();
+    constructor(options) {
+        const cfg = buildExporterConfig(options);
+        this.url = cfg.url;
+        this.headers = {
+            ...cfg.headers,
+            "content-type": "application/json",
+        };
+    }
+    export(spans, resultCallback) {
+        if (this.shutdownState) {
+            resultCallback({
+                code: ExportResultCode.FAILED,
+                error: new Error("HeystackSpanExporter has been shut down"),
+            });
+            return;
+        }
+        if (spans.length === 0) {
+            resultCallback({ code: ExportResultCode.SUCCESS });
+            return;
+        }
+        const body = JSON.stringify(serializeSpans(spans));
+        // Build the fetch chain as a promise we retain, so forceFlush() can await
+        // the actual network write. It resolves (never rejects) once the POST has
+        // completed (success or fail) and resultCallback has been invoked.
+        const p = fetch(this.url, { method: "POST", headers: this.headers, body })
+            .then((res) => {
+            if (res.ok) {
+                resultCallback({ code: ExportResultCode.SUCCESS });
+            }
+            else {
+                resultCallback({
+                    code: ExportResultCode.FAILED,
+                    error: new Error(`Heystack ingest responded ${res.status} ${res.statusText}`),
+                });
+            }
+        })
+            .catch((error) => {
+            resultCallback({
+                code: ExportResultCode.FAILED,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        });
+        this.pending.add(p);
+        p.finally(() => this.pending.delete(p));
+    }
+    shutdown() {
+        return this.forceFlush().then(() => {
+            this.shutdownState = true;
+        });
+    }
+    /**
+     * Resolve only once every in-flight export fetch has settled. This is the
+     * guaranteed drain path: the OTel `SimpleSpanProcessor.forceFlush()` does not
+     * await our fire-and-forget fetch, so callers must await this directly (see
+     * `flushHeystack` and `instrument`).
+     */
+    async forceFlush() {
+        await Promise.allSettled([...this.pending]);
+    }
+}
+/**
+ * Build a `BasicTracerProvider` wired to a `HeystackSpanExporter` via a
+ * `SimpleSpanProcessor`. Exposed for advanced users who want to add manual
+ * spans; for typical use prefer {@link instrument}.
+ *
+ * On Workers each request should get its own short-lived provider so its spans
+ * can be flushed. IMPORTANT: to actually wait for the export network write you
+ * must drain the exporter — `await provider.heystackExporter.forceFlush()` (or
+ * `flushHeystack()`), not just `provider.forceFlush()`.
+ */
+export function createTracerProvider(config) {
+    const exporter = new HeystackSpanExporter(config);
+    const provider = new BasicTracerProvider({
+        resource: new Resource({ [ATTR_SERVICE_NAME]: config.service }),
+        spanProcessors: [new SimpleSpanProcessor(exporter)],
+    });
+    // Attach the exporter so flush paths can await its in-flight fetches.
+    return Object.assign(provider, { heystackExporter: exporter });
+}
+// ---------------------------------------------------------------------------
+// Global tracer provider registration (for host frameworks, e.g. Next.js)
+// ---------------------------------------------------------------------------
+let _provider = null;
+/**
+ * Register Heystack as the global tracer provider on a Workers/edge runtime
+ * (workerd). Spans from the host framework (e.g. Next.js) export over fetch.
+ * Use this instead of @heystack/otel/node when running on Cloudflare/edge.
+ *
+ * FLUSH: there is no per-request `ExecutionContext` on this path, so spans are
+ * NOT auto-flushed. To guarantee delivery on workerd, call `flushHeystack()`
+ * (which awaits the export fetch) from a response hook — or hand it to
+ * `ctx.waitUntil(flushHeystack())` if you do have a ctx. Returns the provider.
+ */
+export function initHeystackWorkers(config) {
+    if (_provider)
+        return _provider;
+    _provider = createTracerProvider(config);
+    // register as the global provider so framework spans flow to our exporter.
+    // BasicTracerProvider.register() also wires context/propagation, but on
+    // workerd we only need the global tracer provider — set it directly so it's
+    // deterministic and doesn't pull in a context manager that may not run here.
+    trace.setGlobalTracerProvider(_provider);
+    return _provider;
+}
+/**
+ * Force-flush any pending spans AND wait for the export network write to
+ * complete. This awaits both the OTel provider's `forceFlush()` (drains the
+ * span processor) and the exporter's own pending-fetch set (the part the OTel
+ * processor does not await) — so on workerd you can hand this to
+ * `ctx.waitUntil(flushHeystack())` and the POST genuinely finishes before the
+ * isolate is torn down. Best-effort no-op if no provider is registered.
+ */
+export async function flushHeystack() {
+    if (!_provider)
+        return;
+    if (typeof _provider.forceFlush === "function") {
+        await _provider.forceFlush();
+    }
+    // The processor's forceFlush does not await our fire-and-forget fetch, so
+    // drain the exporter's in-flight POSTs explicitly.
+    await _provider.heystackExporter.forceFlush();
+}
+/** Reset the singleton global provider. Internal/testing helper. */
+export function __resetProvider() {
+    _provider = null;
+}
+let warnedNoKey = false;
+function warnOnceNoKey() {
+    if (warnedNoKey)
+        return;
+    warnedNoKey = true;
+    console.warn("[heystack] HEYSTACK_API_KEY not set — Workers tracing disabled, handler runs untraced.");
+}
+/** Reset the once-only no-key warning. Internal/testing helper. */
+export function __resetWarnings() {
+    warnedNoKey = false;
+}
+/**
+ * Wrap a Worker's default export so every request is auto-traced with a SERVER
+ * span.
+ *
+ * FLUSH (CRITICAL on Workers/edge): the export is a `fetch()` POST. After
+ * `span.end()` we `ctx.waitUntil` a promise that awaits BOTH the provider's
+ * span processor AND the exporter's in-flight fetch, so the network write
+ * completes before the isolate is torn down. Without this, fast-responding
+ * handlers return before the POST finishes and the trace is silently dropped.
+ *
+ *   import { instrument } from "@heystack/otel/workers";
+ *   export default instrument(
+ *     { async fetch(req, env, ctx) { return new Response("ok"); } },
+ *     { service: "my-worker" },
+ *   );
+ *
+ * If no API key is available (neither `config.apiKey` nor
+ * `env.HEYSTACK_API_KEY`), the handler runs untraced.
+ */
+export function instrument(handler, config) {
+    return {
+        async fetch(req, env, ctx) {
+            const apiKey = config.apiKey ?? env?.HEYSTACK_API_KEY;
+            // No key → run untraced (warn once).
+            if (!apiKey) {
+                warnOnceNoKey();
+                return handler.fetch(req, env, ctx);
+            }
+            const provider = createTracerProvider({
+                apiKey,
+                service: config.service,
+                endpoint: config.endpoint,
+            });
+            const tracer = provider.getTracer("@heystack/otel/workers");
+            const url = new URL(req.url);
+            const span = tracer.startSpan(`${req.method} ${url.pathname}`, {
+                kind: SpanKind.SERVER,
+                attributes: {
+                    "http.request.method": req.method,
+                    "url.full": req.url,
+                    "url.path": url.pathname,
+                    "server.address": url.host,
+                },
+            });
+            // waitUntil a promise that drains BOTH the provider's span processor and
+            // the exporter's in-flight fetch. Awaiting only provider.forceFlush()
+            // would return before the export POST completes, letting the isolate be
+            // torn down and silently dropping the trace.
+            const flush = () => ctx.waitUntil((async () => {
+                await provider.forceFlush().catch(() => { });
+                await provider.heystackExporter.forceFlush().catch(() => { });
+            })());
+            try {
+                const response = await context.with(trace.setSpan(context.active(), span), () => handler.fetch(req, env, ctx));
+                span.setAttribute("http.response.status_code", response.status);
+                span.setStatus({
+                    code: response.status >= 500 ? SpanStatusCode.ERROR : SpanStatusCode.UNSET,
+                });
+                span.end();
+                flush();
+                return response;
+            }
+            catch (error) {
+                if (error instanceof Error)
+                    span.recordException(error);
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.end();
+                flush();
+                throw error;
+            }
+        },
+    };
+}

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "@heystack/otel",
-  "version": "0.0.1",
-  "description": "One-call OpenTelemetry tracing that exports to Heystack.",
+  "version": "0.2.1",
+  "description": "Runtime-aware OpenTelemetry tracing that exports to Heystack (Node, Next.js, Workers).",
   "license": "MIT",
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "main": "./dist/core.js",
+  "types": "./dist/core.d.ts",
+  "exports": {
+    ".": { "types": "./dist/core.d.ts", "import": "./dist/core.js" },
+    "./node": { "types": "./dist/node.d.ts", "import": "./dist/node.js" },
+    "./next": { "types": "./dist/next.d.ts", "import": "./dist/next.js" },
+    "./workers": { "types": "./dist/workers.d.ts", "import": "./dist/workers.js" }
+  },
   "files": ["dist", "README.md"],
   "publishConfig": { "access": "public" },
   "scripts": {
@@ -16,14 +21,18 @@
     "prepublishOnly": "pnpm build"
   },
   "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/sdk-node": "^0.57.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.57.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.55.0",
+    "@opentelemetry/sdk-trace-base": "^1.30.0",
     "@opentelemetry/resources": "^1.30.0",
     "@opentelemetry/semantic-conventions": "^1.30.0"
   },
   "devDependencies": {
     "vitest": "^2.1.0",
     "typescript": "^5.7.0",
-    "@types/node": "^22.0.0"
+    "@types/node": "^22.0.0",
+    "@cloudflare/workers-types": "^4"
   }
 }

package/dist/index.d.ts

@@ -1,22 +0,0 @@
-import { NodeSDK } from "@opentelemetry/sdk-node";
-export interface HeystackOptions {
-    /** Your Heystack ingest key (sk_live_...). */
-    apiKey: string;
-    /** The OTel service.name this app reports as (must match the app's service in Heystack). */
-    service: string;
-    /** Override the ingest endpoint (defaults to Heystack production). */
-    endpoint?: string;
-}
-export interface ExporterConfig {
-    url: string;
-    headers: {
-        Authorization: string;
-    };
-}
-/** Pure: derive the OTLP/HTTP exporter URL + auth header. Unit-tested. */
-export declare function buildExporterConfig(o: HeystackOptions): ExporterConfig;
-/**
- * Initialise Heystack OpenTelemetry tracing. Call once, as early as possible in
- * your app's entry point. Returns the started NodeSDK.
- */
-export declare function initHeystack(o: HeystackOptions): NodeSDK;

package/dist/index.js

@@ -1,21 +0,0 @@
-import { NodeSDK } from "@opentelemetry/sdk-node";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
-const DEFAULT_ENDPOINT = "https://ingest.heystack.dev";
-/** Pure: derive the OTLP/HTTP exporter URL + auth header. Unit-tested. */
-export function buildExporterConfig(o) {
-    const base = (o.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, "");
-    return { url: `${base}/v1/traces`, headers: { Authorization: `Bearer ${o.apiKey}` } };
-}
-/**
- * Initialise Heystack OpenTelemetry tracing. Call once, as early as possible in
- * your app's entry point. Returns the started NodeSDK.
- */
-export function initHeystack(o) {
-    const cfg = buildExporterConfig(o);
-    const sdk = new NodeSDK({
-        serviceName: o.service,
-        traceExporter: new OTLPTraceExporter({ url: cfg.url, headers: cfg.headers }),
-    });
-    sdk.start();
-    return sdk;
-}