@breadcrumb-sdk/ai-sdk 0.0.2

package/README.md

@@ -0,0 +1,87 @@
+# @breadcrumb-sdk/ai-sdk
+
+Trace Vercel AI SDK calls with Breadcrumb. Pass `experimental_telemetry` to any `generateText`, `streamText`, or `generateObject` call and it shows up in your dashboard automatically.
+
+## Install
+
+```bash
+npm install @breadcrumb-sdk/core @breadcrumb-sdk/ai-sdk
+```
+
+## Quick start
+
+```ts
+import { init } from "@breadcrumb-sdk/core";
+import { initAiSdk } from "@breadcrumb-sdk/ai-sdk";
+import { generateText } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+const bc = init({ apiKey: "bc_...", baseUrl: "https://your-breadcrumb-instance.com" });
+const { telemetry } = initAiSdk(bc);
+
+const { text } = await generateText({
+  model: anthropic("claude-opus-4-6"),
+  prompt: "What is TypeScript?",
+  experimental_telemetry: telemetry("answer-question"),
+});
+```
+
+Each call with `telemetry()` shows up as its own trace in the dashboard. No other setup needed.
+
+## Grouping calls into one trace
+
+If you want multiple calls to appear under a single trace, wrap them in `bc.trace()`:
+
+```ts
+await bc.trace("chat-request", async () => {
+  await generateText({ ..., experimental_telemetry: telemetry("plan") });
+  await generateText({ ..., experimental_telemetry: telemetry("respond") });
+});
+```
+
+You can also mix in manual steps — for example a retrieval step that isn't an LLM call:
+
+```ts
+await bc.trace("rag-pipeline", async () => {
+  const docs = await bc.span("retrieve", async (span) => {
+    span.set({ metadata: { source: "vector-db", top_k: 5 } });
+    return await vectorSearch(query);
+  }, { type: "retrieval" });
+
+  await generateText({
+    model,
+    prompt: `Context: ${docs.join("\n")}\n\nQuestion: ${query}`,
+    experimental_telemetry: telemetry("generate"),
+  });
+});
+```
+
+## API
+
+### `initAiSdk(bc)`
+
+Takes your `bc` instance and returns the `telemetry` helper. Call once after `init()`.
+
+```ts
+const { telemetry } = initAiSdk(bc);
+```
+
+---
+
+### `telemetry(functionId, metadata?)`
+
+Returns the config to pass to `experimental_telemetry`.
+
+```ts
+experimental_telemetry: telemetry("my-step")
+experimental_telemetry: telemetry("my-step", { userId: "u_123", temperature: 0.7 })
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `functionId` | `string` | Name shown in the trace UI |
+| `metadata` | `Record<string, string \| number \| boolean \| ...[]>` | Extra data attached to the span |
+
+## Compatibility
+
+Works with AI SDK 5 and AI SDK 6.

package/dist/index.cjs

@@ -0,0 +1,25 @@
+"use strict";
+
+//#region src/index.ts
+/**
+* Integrates Breadcrumb with the Vercel AI SDK (v5 and v6).
+*
+* The AI SDK emits OpenTelemetry spans automatically when
+* experimental_telemetry is enabled. Because init() registers the OTel
+* provider globally, those spans flow through the BreadcrumbSpanExporter
+* without any additional configuration.
+*
+* A single AI SDK call with no active trace() context becomes its own root
+* trace automatically — no wrapping needed.
+*/
+function initAiSdk(_bc) {
+	const telemetry = (functionId, metadata) => ({
+		isEnabled: true,
+		functionId,
+		...metadata !== void 0 ? { metadata } : {}
+	});
+	return { telemetry };
+}
+
+//#endregion
+exports.initAiSdk = initAiSdk

package/dist/index.d.cts

@@ -0,0 +1,29 @@
+import { Breadcrumb } from "@breadcrumb-sdk/core";
+
+//#region src/index.d.ts
+type AttributeValue = string | number | boolean | string[] | number[] | boolean[];
+type TelemetryFn = (functionId: string, metadata?: Record<string, AttributeValue>) => {
+  isEnabled: true;
+  functionId: string;
+  metadata?: Record<string, AttributeValue>;
+};
+/**
+ * Integrates Breadcrumb with the Vercel AI SDK (v5 and v6).
+ *
+ * The AI SDK emits OpenTelemetry spans automatically when
+ * experimental_telemetry is enabled. Because init() registers the OTel
+ * provider globally, those spans flow through the BreadcrumbSpanExporter
+ * without any additional configuration.
+ *
+ * A single AI SDK call with no active trace() context becomes its own root
+ * trace automatically — no wrapping needed.
+ */
+declare function initAiSdk(_bc: Breadcrumb): {
+  telemetry: TelemetryFn;
+};
+
+//#endregion
+//# sourceMappingURL=index.d.ts.map
+
+export { Breadcrumb, TelemetryFn, initAiSdk };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"sourcesContent":null,"mappings":";;;KAKK,cAAA;AAAA,KAQO,WAAA,GARO,CAAA,UAAA,EAAA,MAAA,EAAA,QAAA,CAAA,EAUN,MAVM,CAAA,MAAA,EAUS,cAVT,CAAA,EAAA,GAAA;EAQP,SAAA,EAAA,IAAW;EAAA,UAAA,EAAA,MAAA;EAAA,QAEK,CAAA,EAIf,MAJe,CAAA,MAAA,EAIA,cAJA,CAAA;CAAc;;;AAIvB;;;;;;;;;iBAcH,SAAA,MAAe;aAA0B;;;;AAAzD"}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { Breadcrumb } from "@breadcrumb-sdk/core";
+
+//#region src/index.d.ts
+type AttributeValue = string | number | boolean | string[] | number[] | boolean[];
+type TelemetryFn = (functionId: string, metadata?: Record<string, AttributeValue>) => {
+  isEnabled: true;
+  functionId: string;
+  metadata?: Record<string, AttributeValue>;
+};
+/**
+ * Integrates Breadcrumb with the Vercel AI SDK (v5 and v6).
+ *
+ * The AI SDK emits OpenTelemetry spans automatically when
+ * experimental_telemetry is enabled. Because init() registers the OTel
+ * provider globally, those spans flow through the BreadcrumbSpanExporter
+ * without any additional configuration.
+ *
+ * A single AI SDK call with no active trace() context becomes its own root
+ * trace automatically — no wrapping needed.
+ */
+declare function initAiSdk(_bc: Breadcrumb): {
+  telemetry: TelemetryFn;
+};
+
+//#endregion
+//# sourceMappingURL=index.d.ts.map
+
+export { Breadcrumb, TelemetryFn, initAiSdk };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":null,"mappings":";;;KAKK,cAAA;AAAA,KAQO,WAAA,GARO,CAAA,UAAA,EAAA,MAAA,EAAA,QAAA,CAAA,EAUN,MAVM,CAAA,MAAA,EAUS,cAVT,CAAA,EAAA,GAAA;EAQP,SAAA,EAAA,IAAW;EAAA,UAAA,EAAA,MAAA;EAAA,QAEK,CAAA,EAIf,MAJe,CAAA,MAAA,EAIA,cAJA,CAAA;CAAc;;;AAIvB;;;;;;;;;iBAcH,SAAA,MAAe;aAA0B;;;;AAAzD"}

package/dist/index.js

@@ -0,0 +1,24 @@
+//#region src/index.ts
+/**
+* Integrates Breadcrumb with the Vercel AI SDK (v5 and v6).
+*
+* The AI SDK emits OpenTelemetry spans automatically when
+* experimental_telemetry is enabled. Because init() registers the OTel
+* provider globally, those spans flow through the BreadcrumbSpanExporter
+* without any additional configuration.
+*
+* A single AI SDK call with no active trace() context becomes its own root
+* trace automatically — no wrapping needed.
+*/
+function initAiSdk(_bc) {
+	const telemetry = (functionId, metadata) => ({
+		isEnabled: true,
+		functionId,
+		...metadata !== void 0 ? { metadata } : {}
+	});
+	return { telemetry };
+}
+
+//#endregion
+export { initAiSdk };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["_bc: Breadcrumb","telemetry: TelemetryFn"],"sources":["../src/index.ts"],"sourcesContent":["import type { Breadcrumb } from \"@breadcrumb-sdk/core\";\n\nexport type { Breadcrumb };\n\n// OTel AttributeValue — what the AI SDK's experimental_telemetry.metadata accepts\ntype AttributeValue =\n  | string\n  | number\n  | boolean\n  | string[]\n  | number[]\n  | boolean[];\n\nexport type TelemetryFn = (\n  functionId: string,\n  metadata?: Record<string, AttributeValue>,\n) => {\n  isEnabled: true;\n  functionId: string;\n  metadata?: Record<string, AttributeValue>;\n};\n\n/**\n * Integrates Breadcrumb with the Vercel AI SDK (v5 and v6).\n *\n * The AI SDK emits OpenTelemetry spans automatically when\n * experimental_telemetry is enabled. Because init() registers the OTel\n * provider globally, those spans flow through the BreadcrumbSpanExporter\n * without any additional configuration.\n *\n * A single AI SDK call with no active trace() context becomes its own root\n * trace automatically — no wrapping needed.\n */\nexport function initAiSdk(_bc: Breadcrumb): { telemetry: TelemetryFn } {\n  const telemetry: TelemetryFn = (functionId, metadata) => ({\n    isEnabled: true,\n    functionId,\n    ...(metadata !== undefined ? { metadata } : {}),\n  });\n\n  return { telemetry };\n}\n"],"mappings":";;;;;;;;;;;;AAiCA,SAAgB,UAAUA,KAA6C;CACrE,MAAMC,YAAyB,CAAC,YAAY,cAAc;EACxD,WAAW;EACX;EACA,GAAI,sBAAyB,EAAE,SAAU,IAAG,CAAE;CAC/C;AAED,QAAO,EAAE,UAAW;AACrB"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@breadcrumb-sdk/ai-sdk",
+  "version": "0.0.2",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@breadcrumb-sdk/core": "*"
+  },
+  "devDependencies": {
+    "@breadcrumb-sdk/core": "*",
+    "tsdown": "^0.9",
+    "typescript": "^5.7",
+    "vitest": "^3"
+  }
+}