@spanhq/bullmq 0.1.0

package/dist/cjs/tracer.js

@@ -0,0 +1,259 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceWorker = traceWorker;
+exports.traceQueue = traceQueue;
+const node_crypto_1 = require("node:crypto");
+const context_js_1 = require("./context.js");
+/**
+ * Build a unique key for tracking a job's context in the global Map.
+ */
+function jobKey(queueName, jobId) {
+    return `${queueName}:${jobId}`;
+}
+/**
+ * Instrument a BullMQ Worker to emit spans for every job lifecycle event.
+ *
+ * Events tracked: active, completed, failed, stalled.
+ *
+ * Trace context propagation:
+ *   - On "active": Store trace context in the global activeJobContexts map.
+ *   - During processor: traceQueue.add() reads the context from the map.
+ *   - On "completed"/"failed": Remove context from the map, emit span.
+ *
+ * All errors are caught — this function NEVER crashes the host app.
+ */
+function traceWorker(worker, sender, config) {
+    const startTimes = new Map();
+    try {
+        // Track when a job becomes active
+        worker.on("active", (job) => {
+            try {
+                const j = job;
+                const jobId = j.id ?? (0, node_crypto_1.randomUUID)();
+                // Determine trace ID: inherit from parent job data or generate new
+                const traceId = j.data.__trace_id ?? (0, node_crypto_1.randomUUID)();
+                const spanId = (0, node_crypto_1.randomUUID)();
+                // Store start time for duration calculation
+                startTimes.set(jobId, Date.now());
+                // Build trace context for this job
+                const ctx = { traceId, spanId };
+                // Store context in job data (for completed/failed handlers to read)
+                j.data.__trace_context = { traceId: ctx.traceId, spanId: ctx.spanId };
+                // Register in the global active context map
+                const key = jobKey(j.queueName ?? worker.name, jobId);
+                (0, context_js_1.setJobContext)(key, ctx);
+                if (config.debug) {
+                    const parentId = j.data.__parent_id ?? null;
+                    console.log(`[spanhq] Job active: ${j.name} (${jobId}), trace: ${traceId}${parentId ? `, parent: ${parentId.slice(0, 8)}` : ""}`);
+                }
+            }
+            catch (err) {
+                if (config.debug) {
+                    console.error("[spanhq] Error in active handler:", err);
+                }
+            }
+        });
+        // Track job completion
+        worker.on("completed", (job) => {
+            try {
+                const j = job;
+                const jobId = j.id ?? "unknown";
+                const startTime = startTimes.get(jobId);
+                const now = Date.now();
+                startTimes.delete(jobId);
+                // Remove from global context map
+                const key = jobKey(j.queueName ?? worker.name, jobId);
+                (0, context_js_1.clearJobContext)(key);
+                const traceId = j.data.__trace_id ??
+                    j.data.__trace_context?.traceId ??
+                    (0, node_crypto_1.randomUUID)();
+                const spanId = j.data.__trace_context?.spanId ??
+                    (0, node_crypto_1.randomUUID)();
+                const parentId = j.data.__parent_id ?? null;
+                const startedAt = startTime ? new Date(startTime) : new Date();
+                const finishedAt = new Date(now);
+                const durationMs = startTime ? now - startTime : null;
+                const span = {
+                    id: spanId,
+                    project_id: "", // Will be overridden by the backend
+                    trace_id: traceId,
+                    parent_id: parentId,
+                    job_name: j.name,
+                    queue_name: j.queueName ?? worker.name,
+                    status: "completed",
+                    attempt: j.attemptsMade || 1,
+                    started_at: startedAt.toISOString(),
+                    finished_at: finishedAt.toISOString(),
+                    duration_ms: durationMs,
+                    error: null,
+                    stack_trace: null,
+                    metadata: filterMetadata(j.data),
+                };
+                sender.add(span);
+                if (config.debug) {
+                    console.log(`[spanhq] Job completed: ${j.name} (${durationMs}ms)`);
+                }
+            }
+            catch (err) {
+                if (config.debug) {
+                    console.error("[spanhq] Error in completed handler:", err);
+                }
+            }
+        });
+        // Track job failures
+        worker.on("failed", (job, error, prev) => {
+            try {
+                const j = job;
+                if (!j)
+                    return;
+                const jobId = j.id ?? "unknown";
+                const startTime = startTimes.get(jobId);
+                const now = Date.now();
+                startTimes.delete(jobId);
+                // Remove from global context map
+                const key = jobKey(j.queueName ?? worker.name, jobId);
+                (0, context_js_1.clearJobContext)(key);
+                const traceId = j.data.__trace_id ??
+                    j.data.__trace_context?.traceId ??
+                    (0, node_crypto_1.randomUUID)();
+                const spanId = j.data.__trace_context?.spanId ??
+                    (0, node_crypto_1.randomUUID)();
+                const parentId = j.data.__parent_id ?? null;
+                // Determine if this is a dead job (exhausted all retries)
+                const maxAttempts = j.opts.attempts ?? 1;
+                const isDead = j.attemptsMade >= maxAttempts;
+                if (config.debug) {
+                    console.log(`[spanhq] Failed event: ${j.name} (id=${jobId}), attemptsMade=${j.attemptsMade}, maxAttempts=${maxAttempts}, prev=${String(prev)}, isDead=${isDead}`);
+                }
+                const startedAt = startTime ? new Date(startTime) : new Date();
+                const finishedAt = new Date(now);
+                const durationMs = startTime ? now - startTime : null;
+                const errorMessage = j.failedReason ??
+                    (error instanceof Error ? error.message : String(error ?? "Unknown error"));
+                const stackTrace = j.stacktrace?.join("\n") ??
+                    (error instanceof Error ? error.stack ?? null : null);
+                const span = {
+                    id: spanId,
+                    project_id: "",
+                    trace_id: traceId,
+                    parent_id: parentId,
+                    job_name: j.name,
+                    queue_name: j.queueName ?? worker.name,
+                    status: isDead ? "dead" : "failed",
+                    attempt: j.attemptsMade || 1,
+                    started_at: startedAt.toISOString(),
+                    finished_at: finishedAt.toISOString(),
+                    duration_ms: durationMs,
+                    error: errorMessage,
+                    stack_trace: stackTrace,
+                    metadata: filterMetadata(j.data),
+                };
+                sender.add(span);
+                if (config.debug) {
+                    console.log(`[spanhq] Job ${isDead ? "💀 DEAD" : "⚠️ failed"}: ${j.name} — ${errorMessage}`);
+                }
+            }
+            catch (err) {
+                if (config.debug) {
+                    console.error("[spanhq] Error in failed handler:", err);
+                }
+            }
+        });
+        // Track stalled jobs
+        worker.on("stalled", (jobId) => {
+            try {
+                const id = String(jobId);
+                if (config.debug) {
+                    console.log(`[spanhq] Job stalled: ${id}`);
+                }
+                const span = {
+                    id: (0, node_crypto_1.randomUUID)(),
+                    project_id: "",
+                    trace_id: (0, node_crypto_1.randomUUID)(),
+                    parent_id: null,
+                    job_name: `stalled-${id}`,
+                    queue_name: worker.name,
+                    status: "failed",
+                    attempt: 1,
+                    started_at: new Date().toISOString(),
+                    finished_at: new Date().toISOString(),
+                    duration_ms: 0,
+                    error: `Job ${id} stalled`,
+                    stack_trace: null,
+                    metadata: { stalled_job_id: id },
+                };
+                sender.add(span);
+            }
+            catch (err) {
+                if (config.debug) {
+                    console.error("[spanhq] Error in stalled handler:", err);
+                }
+            }
+        });
+    }
+    catch (err) {
+        if (config.debug) {
+            console.error("[spanhq] Failed to instrument worker:", err);
+        }
+    }
+    return worker;
+}
+/**
+ * Instrument a BullMQ Queue to inject trace context into job data.
+ *
+ * When queue.add() is called inside a traced worker processor,
+ * the trace_id and parent span_id are automatically injected into
+ * the child job's data. This enables distributed trace propagation
+ * across job chains (e.g., ingest → transform → validate → publish).
+ *
+ * All errors are caught — this function NEVER crashes the host app.
+ */
+function traceQueue(queue, sender, config) {
+    try {
+        const originalAdd = queue.add.bind(queue);
+        queue.add = async (name, data, opts) => {
+            try {
+                // Look up the current trace context
+                const ctx = (0, context_js_1.getCurrentContext)();
+                if (ctx) {
+                    data.__trace_id = ctx.traceId;
+                    data.__parent_id = ctx.spanId;
+                    if (config.debug) {
+                        console.log(`[spanhq] Injected trace context into child job "${name}": trace=${ctx.traceId.slice(0, 8)}…, parent=${ctx.spanId.slice(0, 8)}…`);
+                    }
+                }
+                else if (config.debug) {
+                    console.log(`[spanhq] No active trace context for child job "${name}" — will start new trace`);
+                }
+            }
+            catch (err) {
+                if (config.debug) {
+                    console.error("[spanhq] Failed to inject trace context:", err);
+                }
+            }
+            return originalAdd(name, data, opts);
+        };
+    }
+    catch (err) {
+        if (config.debug) {
+            console.error("[spanhq] Failed to instrument queue:", err);
+        }
+    }
+    return queue;
+}
+/**
+ * Filter out internal SpanHQ metadata keys from job data
+ * before storing in the span metadata field.
+ */
+function filterMetadata(data) {
+    const filtered = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (key !== "__trace_id" &&
+            key !== "__parent_id" &&
+            key !== "__trace_context") {
+            filtered[key] = value;
+        }
+    }
+    return filtered;
+}
+//# sourceMappingURL=tracer.js.map

package/dist/cjs/tracer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.js","sourceRoot":"","sources":["../../src/tracer.ts"],"names":[],"mappings":"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"}

package/dist/esm/context.d.ts

@@ -0,0 +1,42 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/** Trace context propagated via AsyncLocalStorage */
+export interface TraceContext {
+    traceId: string;
+    spanId: string;
+}
+/** AsyncLocalStorage instance for trace context propagation */
+export declare const storage: AsyncLocalStorage<TraceContext>;
+/**
+ * Active job context tracking.
+ *
+ * We maintain a Map of ALL currently active job contexts (keyed by
+ * "queueName:jobId"). When a worker processor calls traceQueue.add(),
+ * we look up the context from the correct active job.
+ *
+ * Since BullMQ workers with concurrency > 1 may have multiple active
+ * jobs simultaneously, a single global variable is insufficient.
+ * Instead, we track each active job separately.
+ *
+ * The key insight: traceQueue.add() is called FROM WITHIN a worker
+ * processor, so the "current" context is the one for whichever job's
+ * processor is executing. We use a stack-like approach: each add()
+ * reads the MOST RECENT context that hasn't been completed yet.
+ *
+ * For single-concurrency queues (the pipeline use case), the Map
+ * will have at most one entry per queue, making lookups unambiguous.
+ */
+export declare const activeJobContexts: Map<string, TraceContext>;
+/**
+ * Set context for a specific active job.
+ */
+export declare function setJobContext(key: string, ctx: TraceContext): void;
+/**
+ * Remove context when a job completes or fails.
+ */
+export declare function clearJobContext(key: string): void;
+/**
+ * Get the current trace context.
+ * Priority: AsyncLocalStorage → most recently activated job context.
+ */
+export declare function getCurrentContext(): TraceContext | undefined;
+//# sourceMappingURL=context.d.ts.map

package/dist/esm/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,qDAAqD;AACrD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,+DAA+D;AAC/D,eAAO,MAAM,OAAO,iCAAwC,CAAC;AAE7D;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,iBAAiB,2BAAkC,CAAC;AAEjE;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,QAE3D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,QAE1C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,YAAY,GAAG,SAAS,CAY5D"}

package/dist/esm/context.js

@@ -0,0 +1,53 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/** AsyncLocalStorage instance for trace context propagation */
+export const storage = new AsyncLocalStorage();
+/**
+ * Active job context tracking.
+ *
+ * We maintain a Map of ALL currently active job contexts (keyed by
+ * "queueName:jobId"). When a worker processor calls traceQueue.add(),
+ * we look up the context from the correct active job.
+ *
+ * Since BullMQ workers with concurrency > 1 may have multiple active
+ * jobs simultaneously, a single global variable is insufficient.
+ * Instead, we track each active job separately.
+ *
+ * The key insight: traceQueue.add() is called FROM WITHIN a worker
+ * processor, so the "current" context is the one for whichever job's
+ * processor is executing. We use a stack-like approach: each add()
+ * reads the MOST RECENT context that hasn't been completed yet.
+ *
+ * For single-concurrency queues (the pipeline use case), the Map
+ * will have at most one entry per queue, making lookups unambiguous.
+ */
+export const activeJobContexts = new Map();
+/**
+ * Set context for a specific active job.
+ */
+export function setJobContext(key, ctx) {
+    activeJobContexts.set(key, ctx);
+}
+/**
+ * Remove context when a job completes or fails.
+ */
+export function clearJobContext(key) {
+    activeJobContexts.delete(key);
+}
+/**
+ * Get the current trace context.
+ * Priority: AsyncLocalStorage → most recently activated job context.
+ */
+export function getCurrentContext() {
+    const alsCtx = storage.getStore();
+    if (alsCtx)
+        return alsCtx;
+    // Fallback: return the most recently added active context.
+    // In single-concurrency workers this is always correct.
+    // In multi-concurrency workers, there's a small risk of picking
+    // the wrong context, but for tracing purposes this is acceptable.
+    if (activeJobContexts.size === 0)
+        return undefined;
+    const entries = Array.from(activeJobContexts.values());
+    return entries[entries.length - 1];
+}
+//# sourceMappingURL=context.js.map

package/dist/esm/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAQrD,+DAA+D;AAC/D,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAgB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAwB,CAAC;AAEjE;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,GAAiB;IAC1D,iBAAiB,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAChC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAClC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,2DAA2D;IAC3D,wDAAwD;IACxD,gEAAgE;IAChE,kEAAkE;IAClE,IAAI,iBAAiB,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAEnD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC;IACvD,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACrC,CAAC"}

package/dist/esm/index.d.ts

@@ -0,0 +1,47 @@
+import type { TracerConfig } from "@spanhq/shared";
+export { getCurrentContext } from "./context.js";
+export type { TraceContext } from "./context.js";
+export type { TracerConfig } from "@spanhq/shared";
+/** BullMQ Worker type (minimal interface) */
+interface BullMQWorker {
+    name: string;
+    on(event: string, callback: (...args: unknown[]) => void): unknown;
+}
+/** BullMQ Queue type (minimal interface) */
+interface BullMQQueue {
+    name: string;
+    add(name: string, data: Record<string, unknown>, opts?: Record<string, unknown>): Promise<unknown>;
+}
+/** The tracer object returned by createTracer */
+export interface Tracer {
+    /** Instrument a BullMQ Worker to emit tracing spans */
+    traceWorker<T extends BullMQWorker>(worker: T): T;
+    /** Instrument a BullMQ Queue to propagate trace context */
+    traceQueue<T extends BullMQQueue>(queue: T): T;
+    /** Gracefully shutdown — flushes remaining spans before resolving */
+    shutdown(): Promise<void>;
+}
+/**
+ * Create a SpanHQ instance.
+ *
+ * ```ts
+ * import { createTracer } from '@spanhq/bullmq'
+ *
+ * const tracer = createTracer({
+ *   apiKey: 'jt_live_xxxx',
+ *   endpoint: 'https://api.spanhq.dev',
+ *   debug: false,
+ * })
+ *
+ * const worker = tracer.traceWorker(new Worker(...))
+ * const queue  = tracer.traceQueue(new Queue(...))
+ *
+ * // On shutdown:
+ * await tracer.shutdown()
+ * ```
+ *
+ * @param config - API key (required), optional endpoint and debug flag
+ * @returns A tracer object with traceWorker, traceQueue, and shutdown methods
+ */
+export declare function createTracer(config: TracerConfig): Tracer;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,gBAAgB,CAAC;AAIjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAInD,6CAA6C;AAC7C,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC;CACpE;AAED,4CAA4C;AAC5C,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CACD,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED,iDAAiD;AACjD,MAAM,WAAW,MAAM;IACrB,uDAAuD;IACvD,WAAW,CAAC,CAAC,SAAS,YAAY,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;IAClD,2DAA2D;IAC3D,UAAU,CAAC,CAAC,SAAS,WAAW,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;IAC/C,qEAAqE;IACrE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAoCzD"}

package/dist/esm/index.js

@@ -0,0 +1,54 @@
+import { SpanSender } from "./sender.js";
+import { traceWorker, traceQueue } from "./tracer.js";
+export { getCurrentContext } from "./context.js";
+const DEFAULT_ENDPOINT = "https://api.spanhq.dev";
+/**
+ * Create a SpanHQ instance.
+ *
+ * ```ts
+ * import { createTracer } from '@spanhq/bullmq'
+ *
+ * const tracer = createTracer({
+ *   apiKey: 'jt_live_xxxx',
+ *   endpoint: 'https://api.spanhq.dev',
+ *   debug: false,
+ * })
+ *
+ * const worker = tracer.traceWorker(new Worker(...))
+ * const queue  = tracer.traceQueue(new Queue(...))
+ *
+ * // On shutdown:
+ * await tracer.shutdown()
+ * ```
+ *
+ * @param config - API key (required), optional endpoint and debug flag
+ * @returns A tracer object with traceWorker, traceQueue, and shutdown methods
+ */
+export function createTracer(config) {
+    const apiKey = config.apiKey || process.env.SPANHQ_API_KEY || "";
+    const endpoint = config.endpoint ||
+        process.env.SPANHQ_ENDPOINT ||
+        DEFAULT_ENDPOINT;
+    const debug = config.debug ?? false;
+    if (!apiKey && debug) {
+        console.warn("[spanhq] No API key provided. Spans will be buffered but will fail to send.");
+    }
+    const senderConfig = {
+        apiKey,
+        endpoint: endpoint.replace(/\/$/, ""), // Strip trailing slash
+        debug,
+    };
+    const sender = new SpanSender(senderConfig);
+    return {
+        traceWorker(worker) {
+            return traceWorker(worker, sender, senderConfig);
+        },
+        traceQueue(queue) {
+            return traceQueue(queue, sender, senderConfig);
+        },
+        async shutdown() {
+            await sender.shutdown();
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAIjD,MAAM,gBAAgB,GAAG,wBAAwB,CAAC;AA4BlD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,MAAM,MAAM,GACV,MAAM,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC;IACpD,MAAM,QAAQ,GACZ,MAAM,CAAC,QAAQ;QACf,OAAO,CAAC,GAAG,CAAC,eAAe;QAC3B,gBAAgB,CAAC;IACnB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,KAAK,CAAC;IAEpC,IAAI,CAAC,MAAM,IAAI,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CACV,6EAA6E,CAC9E,CAAC;IACJ,CAAC;IAED,MAAM,YAAY,GAAiB;QACjC,MAAM;QACN,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,uBAAuB;QAC9D,KAAK;KACN,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC;IAE5C,OAAO;QACL,WAAW,CAAyB,MAAS;YAC3C,OAAO,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAM,CAAC;QACxD,CAAC;QAED,UAAU,CAAwB,KAAQ;YACxC,OAAO,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,CAAM,CAAC;QACtD,CAAC;QAED,KAAK,CAAC,QAAQ;YACZ,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;QAC1B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/esm/sender.d.ts

@@ -0,0 +1,37 @@
+import type { Span, SenderConfig } from "@spanhq/shared";
+/**
+ * SpanSender batches spans and sends them to the SpanHQ backend.
+ *
+ * Safety guarantees:
+ * - NEVER throws an error — all exceptions are caught and optionally logged
+ * - Flushes remaining spans on shutdown before resolving
+ * - Uses a timer-based flush every 2 seconds + size-based flush at 10 spans
+ */
+export declare class SpanSender {
+    private batch;
+    private timer;
+    private readonly config;
+    private inflight;
+    constructor(config: SenderConfig);
+    /**
+     * Add a span to the batch buffer.
+     * Triggers an immediate flush if batch reaches MAX_BATCH_SIZE.
+     */
+    add(span: Span): void;
+    /**
+     * Flush the current batch to the backend.
+     * Copies the batch to a local variable and clears the buffer immediately
+     * to avoid blocking new span additions.
+     */
+    flush(): Promise<void>;
+    /**
+     * Send a batch of spans to the backend. Never throws.
+     */
+    private sendBatch;
+    /**
+     * Shutdown the sender. Clears the timer and flushes remaining spans.
+     * Await this to ensure no spans are lost on process exit.
+     */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=sender.d.ts.map

package/dist/esm/sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sender.d.ts","sourceRoot":"","sources":["../../src/sender.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAKzD;;;;;;;GAOG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAoC;gBAExC,MAAM,EAAE,YAAY;IAYhC;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAoBrB;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B;;OAEG;YACW,SAAS;IAoCvB;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAehC"}

package/dist/esm/sender.js

@@ -0,0 +1,112 @@
+const MAX_BATCH_SIZE = 10;
+const FLUSH_INTERVAL_MS = 2000;
+/**
+ * SpanSender batches spans and sends them to the SpanHQ backend.
+ *
+ * Safety guarantees:
+ * - NEVER throws an error — all exceptions are caught and optionally logged
+ * - Flushes remaining spans on shutdown before resolving
+ * - Uses a timer-based flush every 2 seconds + size-based flush at 10 spans
+ */
+export class SpanSender {
+    batch = [];
+    timer = null;
+    config;
+    inflight = Promise.resolve();
+    constructor(config) {
+        this.config = config;
+        this.timer = setInterval(() => {
+            void this.flush();
+        }, FLUSH_INTERVAL_MS);
+        // Prevent the timer from keeping the process alive
+        if (this.timer && typeof this.timer === "object" && "unref" in this.timer) {
+            this.timer.unref();
+        }
+    }
+    /**
+     * Add a span to the batch buffer.
+     * Triggers an immediate flush if batch reaches MAX_BATCH_SIZE.
+     */
+    add(span) {
+        try {
+            this.batch.push(span);
+            if (this.config.debug) {
+                console.log(`[spanhq] Span buffered: ${span.job_name} (${span.status}), batch size: ${this.batch.length}`);
+            }
+            if (this.batch.length >= MAX_BATCH_SIZE) {
+                void this.flush();
+            }
+        }
+        catch (err) {
+            if (this.config.debug) {
+                console.error("[spanhq] Failed to add span to batch:", err);
+            }
+        }
+    }
+    /**
+     * Flush the current batch to the backend.
+     * Copies the batch to a local variable and clears the buffer immediately
+     * to avoid blocking new span additions.
+     */
+    async flush() {
+        if (this.batch.length === 0)
+            return;
+        const toSend = this.batch.slice();
+        this.batch = [];
+        const promise = this.sendBatch(toSend);
+        this.inflight = this.inflight.then(() => promise);
+        await promise;
+    }
+    /**
+     * Send a batch of spans to the backend. Never throws.
+     */
+    async sendBatch(batch) {
+        try {
+            if (this.config.debug) {
+                console.log(`[spanhq] Flushing ${batch.length} spans to ${this.config.endpoint}`);
+            }
+            const response = await fetch(`${this.config.endpoint}/v1/spans`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "x-api-key": this.config.apiKey,
+                },
+                body: JSON.stringify({ spans: batch }),
+            });
+            if (!response.ok) {
+                const text = await response.text();
+                if (this.config.debug) {
+                    console.error(`[spanhq] Backend returned ${response.status}: ${text}`);
+                }
+            }
+            else if (this.config.debug) {
+                const data = await response.json();
+                console.log(`[spanhq] Successfully sent ${batch.length} spans`, data);
+            }
+        }
+        catch (err) {
+            if (this.config.debug) {
+                console.error("[spanhq] Failed to flush spans:", err);
+            }
+            // Silently drop — never crash the host application
+        }
+    }
+    /**
+     * Shutdown the sender. Clears the timer and flushes remaining spans.
+     * Await this to ensure no spans are lost on process exit.
+     */
+    async shutdown() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        // Flush any remaining spans
+        await this.flush();
+        // Wait for any in-flight requests
+        await this.inflight;
+        if (this.config.debug) {
+            console.log("[spanhq] Sender shut down successfully");
+        }
+    }
+}
+//# sourceMappingURL=sender.js.map

package/dist/esm/sender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sender.js","sourceRoot":"","sources":["../../src/sender.ts"],"names":[],"mappings":"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"}