@telemetry-dev/tanstack-ai 0.1.0 → 0.1.1

package/dist/index.d.mts

@@ -17,7 +17,7 @@ interface TelemetryDevOptions {
   /** Serverless extender (e.g. Cloudflare `ctx.waitUntil`). When provided, `onFinish` does not await the POST. */
   waitUntil?: (p: Promise<unknown>) => void;
   /** Receives any error raised while emitting telemetry; the integration never throws into the SDK. */
-  onError?: (error: unknown) => void;
+  onError?: (cause: unknown) => void;
 }
 //#endregion
 //#region src/otel.d.ts

package/dist/index.mjs

@@ -6,7 +6,7 @@ import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
 //#region src/config.ts
 const DEFAULT_BASE_URL = "https://ingest.telemetry.dev";
 function resolveConfig(options = {}) {
-	const env = typeof process !== "undefined" && process.env ? process.env : {};
+	const env = globalThis.process?.env ?? {};
 	const baseUrl = (options.baseUrl ?? env.TELEMETRY_DEV_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
 	return {
 		apiKey: options.apiKey ?? env.TELEMETRY_DEV_API_KEY,
@@ -86,6 +86,7 @@ const postOtlp = async ({ fetchImpl, url, headers, body }) => {
 		await delay(RETRY_DELAYS_MS[attempt]);
 	}
 };
+const isReadableSpan = (span) => "resource" in span && "instrumentationScope" in span && "events" in span;
 const cache = /* @__PURE__ */ new Map();
 const buildCore = (config) => {
 	const { apiKey, baseUrl, environment, serviceName } = config;
@@ -95,7 +96,8 @@ const buildCore = (config) => {
 	});
 	const headers = {
 		"content-type": "application/x-protobuf",
-		authorization: `Bearer ${apiKey}`
+		authorization: `Bearer ${apiKey}`,
+		"x-telemetry-dev-sdk": "@telemetry-dev/tanstack-ai"
 	};
 	const tracer = new BasicTracerProvider({ resource }).getTracer(SCOPE_NAME, SCOPE_VERSION);
 	const sendSpans = async (spans, transport) => {
@@ -137,11 +139,11 @@ const buildCore = (config) => {
 								return;
 							}
 							resultCallback({ code: 0 });
-						}).catch((error) => {
-							onError?.(error);
+						}).catch((cause) => {
+							onError?.(cause);
 							resultCallback({
 								code: 1,
-								error: error instanceof Error ? error : void 0
+								error: cause instanceof Error ? cause : void 0
 							});
 						});
 					},
@@ -199,14 +201,14 @@ const createEmitter = (config, overrides) => {
 		metrics = void 0;
 		const p = (async () => {
 			try {
-				await sendSpans(spans);
+				await sendSpans(spans.filter(isReadableSpan));
 			} catch (e) {
-				onError?.(e);
+				onError?.(e instanceof Error ? e : new Error(String(e)));
 			}
 			try {
 				if (pipeline) await pipeline.shutdown();
 			} catch (e) {
-				onError?.(e);
+				onError?.(e instanceof Error ? e : new Error(String(e)));
 			}
 		})();
 		if (config.waitUntil) {
@@ -224,6 +226,10 @@ const createEmitter = (config, overrides) => {
 };
 //#endregion
 //#region src/middleware.ts
+const isString = (value) => typeof value === "string";
+const isNumber = (value) => typeof value === "number";
+const isBigInt = (value) => typeof value === "bigint";
+const isObject = (value) => value !== null && typeof value === "object";
 function omitUndefined(attributes) {
 	const out = {};
 	for (const key of Object.keys(attributes)) {
@@ -233,13 +239,13 @@ function omitUndefined(attributes) {
 	return out;
 }
 function readId(value) {
-	if (typeof value === "string") return value.length > 0 ? value : null;
-	if (typeof value === "number" || typeof value === "bigint") return value.toString();
+	if (isString(value)) return value.length > 0 ? value : null;
+	if (isNumber(value) || isBigInt(value)) return value.toString();
 	return null;
 }
 function jsonAttr(value) {
 	if (value === void 0) return void 0;
-	if (typeof value === "string") return value;
+	if (isString(value)) return value;
 	try {
 		return JSON.stringify(value);
 	} catch {
@@ -247,22 +253,22 @@ function jsonAttr(value) {
 	}
 }
 function firstNumber(...candidates) {
-	for (const candidate of candidates) if (typeof candidate === "number" && Number.isFinite(candidate)) return candidate;
+	for (const candidate of candidates) if (isNumber(candidate) && Number.isFinite(candidate)) return candidate;
 }
 function errorTypeName(err) {
 	if (err instanceof Error) return err.name || "Error";
-	if (err && typeof err === "object" && "name" in err) {
+	if (err && isObject(err) && "name" in err) {
 		const n = err.name;
-		if (typeof n === "string" && n.length > 0) return n;
+		if (isString(n) && n.length > 0) return n;
 	}
 	return "Error";
 }
 function errorMessage(err) {
 	if (err instanceof Error) return err.message;
-	if (typeof err === "string") return err;
-	if (err && typeof err === "object" && "message" in err) {
+	if (isString(err)) return err;
+	if (err && isObject(err) && "message" in err) {
 		const m = err.message;
-		if (typeof m === "string") return m;
+		if (isString(m)) return m;
 	}
 	return String(err);
 }
@@ -278,7 +284,7 @@ const MAX_TOKENS_KEYS = [
 ];
 function samplingAttributes(modelOptions) {
 	const sampling = modelOptions ?? {};
-	const nested = sampling["options"] && typeof sampling["options"] === "object" ? sampling["options"] : void 0;
+	const nested = sampling["options"] && isObject(sampling["options"]) ? sampling["options"] : void 0;
 	return omitUndefined({
 		"gen_ai.request.temperature": firstNumber(sampling["temperature"], nested?.["temperature"]),
 		"gen_ai.request.top_p": firstNumber(sampling["top_p"], sampling["topP"], nested?.["top_p"]),
@@ -337,7 +343,7 @@ function telemetryDev(options, overrides) {
 			...state.rootSampling
 		}));
 		if (state.restMetadata) for (const [key, value] of Object.entries(state.restMetadata)) {
-			const attr = typeof value === "string" ? value : jsonAttr(value);
+			const attr = isString(value) ? value : jsonAttr(value);
 			if (attr !== void 0) state.rootSpan.setAttribute(`td.metadata.${key}`, attr);
 		}
 	};
@@ -398,7 +404,7 @@ function telemetryDev(options, overrides) {
 		onStart(ctx) {
 			try {
 				const rawMetadata = ctx.options?.["metadata"];
-				const metadata = rawMetadata && typeof rawMetadata === "object" ? rawMetadata : void 0;
+				const metadata = rawMetadata && isObject(rawMetadata) ? rawMetadata : void 0;
 				const userId = readId(metadata?.["userId"]);
 				const sessionId = readId(metadata?.["sessionId"]) ?? ctx.threadId;
 				let restMetadata;
@@ -444,7 +450,7 @@ function telemetryDev(options, overrides) {
 				const inputMessages = [];
 				for (const prompt of chatConfig.systemPrompts) inputMessages.push({
 					role: "system",
-					content: typeof prompt === "string" ? prompt : prompt.content
+					content: isString(prompt) ? prompt : prompt.content
 				});
 				for (const message of chatConfig.messages) inputMessages.push({
 					role: message.role,
@@ -493,7 +499,7 @@ function telemetryDev(options, overrides) {
 				if (chunk.type === "CUSTOM") {
 					if (iteration.structured && chunk.name === "structured-output.complete") {
 						const raw = chunk.value?.raw;
-						if (typeof raw === "string") iteration.outputText = raw;
+						if (isString(raw)) iteration.outputText = raw;
 					}
 					return;
 				}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemetry-dev/tanstack-ai",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "TanStack AI telemetry integration for telemetry.dev: chat() middleware emitting OpenTelemetry GenAI spans.",
   "keywords": [
     "genai",

package/src/config.ts

@@ -12,7 +12,7 @@ export interface TelemetryDevOptions {
   /** Serverless extender (e.g. Cloudflare `ctx.waitUntil`). When provided, `onFinish` does not await the POST. */
   waitUntil?: (p: Promise<unknown>) => void;
   /** Receives any error raised while emitting telemetry; the integration never throws into the SDK. */
-  onError?: (error: unknown) => void;
+  onError?: (cause: unknown) => void;
 }
 
 export interface ResolvedConfig {
@@ -22,16 +22,13 @@ export interface ResolvedConfig {
   serviceName: string;
   fetchImpl: typeof fetch;
   waitUntil?: (p: Promise<unknown>) => void;
-  onError?: (error: unknown) => void;
+  onError?: (cause: unknown) => void;
 }
 
 const DEFAULT_BASE_URL = "https://ingest.telemetry.dev";
 
 export function resolveConfig(options: TelemetryDevOptions = {}): ResolvedConfig {
-  const env =
-    typeof process !== "undefined" && process.env
-      ? process.env
-      : ({} as Record<string, string | undefined>);
+  const env = globalThis.process?.env ?? {};
   const baseUrl = (options.baseUrl ?? env.TELEMETRY_DEV_BASE_URL ?? DEFAULT_BASE_URL).replace(
     /\/+$/,
     "",

package/src/middleware.ts

@@ -24,6 +24,22 @@ import type {
 import { resolveConfig, type TelemetryDevOptions } from "./config.ts";
 import { createEmitter, type EmitterOverrides } from "./otel.ts";
 
+type JsonValue =
+  | string
+  | number
+  | bigint
+  | boolean
+  | null
+  | undefined
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+const isString = (value: unknown): value is string => typeof value === "string";
+const isNumber = (value: unknown): value is number => typeof value === "number";
+const isBigInt = (value: unknown): value is bigint => typeof value === "bigint";
+const isObject = <T>(value: T): value is T & { [key: string]: JsonValue } =>
+  value !== null && typeof value === "object";
+
 function omitUndefined(attributes: Attributes): Attributes {
   const out: Attributes = {};
   for (const key of Object.keys(attributes)) {
@@ -35,11 +51,11 @@ function omitUndefined(attributes: Attributes): Attributes {
   return out;
 }
 
-function readId(value: unknown): string | null {
-  if (typeof value === "string") {
+function readId<T>(value: T): string | null {
+  if (isString(value)) {
     return value.length > 0 ? value : null;
   }
-  if (typeof value === "number" || typeof value === "bigint") {
+  if (isNumber(value) || isBigInt(value)) {
     return value.toString();
   }
   return null;
@@ -47,9 +63,9 @@ function readId(value: unknown): string | null {
 
 // Stringify structured content (messages / tool args) for the gen_ai.* string attributes the
 // ingest parses back into JSON. Returns undefined so omitUndefined drops absent content.
-function jsonAttr(value: unknown): string | undefined {
+function jsonAttr<T>(value: T): string | undefined {
   if (value === undefined) return undefined;
-  if (typeof value === "string") return value;
+  if (isString(value)) return value;
   try {
     return JSON.stringify(value);
   } catch {
@@ -57,30 +73,30 @@ function jsonAttr(value: unknown): string | undefined {
   }
 }
 
-function firstNumber(...candidates: unknown[]): number | undefined {
+function firstNumber<T>(...candidates: T[]): number | undefined {
   for (const candidate of candidates) {
-    if (typeof candidate === "number" && Number.isFinite(candidate)) {
+    if (isNumber(candidate) && Number.isFinite(candidate)) {
       return candidate;
     }
   }
   return undefined;
 }
 
-function errorTypeName(err: unknown): string {
+function errorTypeName<T>(err: T): string {
   if (err instanceof Error) return err.name || "Error";
-  if (err && typeof err === "object" && "name" in err) {
+  if (err && isObject(err) && "name" in err) {
     const n = (err as { name?: unknown }).name;
-    if (typeof n === "string" && n.length > 0) return n;
+    if (isString(n) && n.length > 0) return n;
   }
   return "Error";
 }
 
-function errorMessage(err: unknown): string {
+function errorMessage<T>(err: T): string {
   if (err instanceof Error) return err.message;
-  if (typeof err === "string") return err;
-  if (err && typeof err === "object" && "message" in err) {
+  if (isString(err)) return err;
+  if (err && isObject(err) && "message" in err) {
     const m = (err as { message?: unknown }).message;
-    if (typeof m === "string") return m;
+    if (isString(m)) return m;
   }
   return String(err);
 }
@@ -101,11 +117,11 @@ const MAX_TOKENS_KEYS = [
 
 // Sampling options live in opaque provider-native `modelOptions`; pick the first numeric value
 // among the known spellings (including Ollama's nested `options`) for the gen_ai.request.* attrs.
-function samplingAttributes(modelOptions: Record<string, unknown> | undefined): Attributes {
+function samplingAttributes(modelOptions: Record<string, JsonValue> | undefined): Attributes {
   const sampling = modelOptions ?? {};
   const nested =
-    sampling["options"] && typeof sampling["options"] === "object"
-      ? (sampling["options"] as Record<string, unknown>)
+    sampling["options"] && isObject(sampling["options"])
+      ? (sampling["options"] as Record<string, JsonValue>)
       : undefined;
   return omitUndefined({
     "gen_ai.request.temperature": firstNumber(sampling["temperature"], nested?.["temperature"]),
@@ -136,7 +152,7 @@ interface RunState {
   responseModel: string | null;
   userId: string | null;
   sessionId: string;
-  restMetadata: Record<string, unknown> | undefined;
+  restMetadata: Record<string, JsonValue> | undefined;
   rootInput: string | undefined;
   rootSampling: Attributes;
   rootCaptured: boolean;
@@ -229,7 +245,7 @@ export function telemetryDev(
     );
     if (state.restMetadata) {
       for (const [key, value] of Object.entries(state.restMetadata)) {
-        const attr = typeof value === "string" ? value : jsonAttr(value);
+        const attr = isString(value) ? value : jsonAttr(value);
         if (attr !== undefined) {
           state.rootSpan.setAttribute(`td.metadata.${key}`, attr);
         }
@@ -297,14 +313,14 @@ export function telemetryDev(
       try {
         const rawMetadata = ctx.options?.["metadata"];
         const metadata =
-          rawMetadata && typeof rawMetadata === "object"
-            ? (rawMetadata as Record<string, unknown>)
+          rawMetadata && isObject(rawMetadata)
+            ? (rawMetadata as Record<string, JsonValue>)
             : undefined;
         const userId = readId(metadata?.["userId"]);
         const sessionId = readId(metadata?.["sessionId"]) ?? ctx.threadId;
-        let restMetadata: Record<string, unknown> | undefined;
+        let restMetadata: Record<string, JsonValue> | undefined;
         if (metadata) {
-          const rest: Record<string, unknown> = {};
+          const rest: Record<string, JsonValue> = {};
           for (const [key, value] of Object.entries(metadata)) {
             if (key !== "userId" && key !== "sessionId") {
               rest[key] = value;
@@ -360,14 +376,16 @@ export function telemetryDev(
         for (const prompt of chatConfig.systemPrompts) {
           inputMessages.push({
             role: "system",
-            content: typeof prompt === "string" ? prompt : prompt.content,
+            content: isString(prompt) ? prompt : prompt.content,
           });
         }
         for (const message of chatConfig.messages) {
           inputMessages.push({ role: message.role, content: message.content });
         }
         const inputJson = jsonAttr(inputMessages);
-        const sampling = samplingAttributes(chatConfig.modelOptions ?? ctx.modelOptions);
+        const sampling = samplingAttributes(
+          (chatConfig.modelOptions ?? ctx.modelOptions) as Record<string, JsonValue> | undefined,
+        );
         if (!state.rootCaptured) {
           state.rootCaptured = true;
           state.rootInput = inputJson;
@@ -418,7 +436,7 @@ export function telemetryDev(
           // still holds the agent loop's text, so this is the structured span's only output.
           if (iteration.structured && chunk.name === "structured-output.complete") {
             const raw = (chunk.value as { raw?: unknown } | null | undefined)?.raw;
-            if (typeof raw === "string") iteration.outputText = raw;
+            if (isString(raw)) iteration.outputText = raw;
           }
           return undefined;
         }

package/src/otel.ts

@@ -44,7 +44,7 @@ export interface EmitterOverrides {
   recordTokens?: (tokenType: "input" | "output", count: number, attributes: Attributes) => void;
 }
 
-type Transport = { fetchImpl: typeof fetch; onError?: (error: unknown) => void };
+type Transport = { fetchImpl: typeof fetch; onError?: (cause: unknown) => void };
 
 const RETRY_DELAYS_MS = [100, 500] as const;
 
@@ -97,6 +97,9 @@ interface EmitterCore {
   buildMetrics: (transport: Transport) => MetricsPipeline;
 }
 
+const isReadableSpan = (span: Span): span is Span & ReadableSpan =>
+  "resource" in span && "instrumentationScope" in span && "events" in span;
+
 const cache = new Map<string, EmitterCore>();
 
 const buildCore = (config: ResolvedConfig): EmitterCore => {
@@ -108,6 +111,7 @@ const buildCore = (config: ResolvedConfig): EmitterCore => {
   const headers = {
     "content-type": "application/x-protobuf",
     authorization: `Bearer ${apiKey}`,
+    "x-telemetry-dev-sdk": "@telemetry-dev/tanstack-ai",
   };
 
   const provider = new BasicTracerProvider({ resource });
@@ -148,9 +152,9 @@ const buildCore = (config: ResolvedConfig): EmitterCore => {
             }
             resultCallback({ code: 0 });
           })
-          .catch((error: unknown) => {
-            onError?.(error);
-            resultCallback({ code: 1, error: error instanceof Error ? error : undefined });
+          .catch((cause: unknown) => {
+            onError?.(cause);
+            resultCallback({ code: 1, error: cause instanceof Error ? cause : undefined });
           });
       },
       selectAggregationTemporality: () => AggregationTemporality.DELTA,
@@ -226,14 +230,15 @@ export const createEmitter = (config: ResolvedConfig, overrides?: EmitterOverrid
     metrics = undefined;
     const p = (async () => {
       try {
-        await sendSpans(spans as unknown as ReadableSpan[]);
+        const readableSpans = spans.filter(isReadableSpan);
+        await sendSpans(readableSpans);
       } catch (e) {
-        onError?.(e);
+        onError?.(e instanceof Error ? e : new Error(String(e)));
       }
       try {
         if (pipeline) await pipeline.shutdown();
       } catch (e) {
-        onError?.(e);
+        onError?.(e instanceof Error ? e : new Error(String(e)));
       }
     })();
     if (config.waitUntil) {