@raindrop-ai/ai-sdk 0.0.32 → 0.0.34

package/README.md

@@ -55,6 +55,28 @@ await raindrop.users.identify({
 await raindrop.flush();
 ```
 
+## Payload size limits
+
+Text fields (event input/output, tool/LLM span payloads such as `ai.prompt`,
+`ai.toolCall.args`, `ai.toolCall.result`) are capped at **1,000,000 characters
+per field by default** and truncated with a `...[truncated by raindrop]`
+marker. The cap is enforced before (or during) serialization, so a multi-MB
+tool result costs the cap — not the payload — on your event loop, and
+oversized events land truncated instead of being dropped at the ingest size
+limit. Tune it via:
+
+```ts
+const raindrop = createRaindropAISDK({
+  writeKey: "...",
+  maxTextFieldChars: 250_000,
+});
+```
+
+A stricter `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` env var is honored. The
+bounded helpers are exported (`capText`, `boundedStringify`,
+`TRUNCATION_MARKER`, `DEFAULT_MAX_TEXT_FIELD_CHARS`) for use in custom
+`transformSpan` hooks and `buildEvent` builders.
+
 ## Manual Traces
 
 Create trace spans manually alongside, or instead of, auto-instrumented ones.
@@ -115,9 +137,50 @@ raindrop.traces.endSpan(agentTurn);
 await raindrop.flush();
 ```
 
-### AI SDK v7+ native telemetry (opt-in)
+### AI SDK v7 quick start: `registerTelemetry(raindrop())`
+
+On AI SDK v7, the simplest setup is the `raindrop()` factory, which returns a
+ready-to-register telemetry integration. The `writeKey` defaults to the
+`RAINDROP_WRITE_KEY` environment variable.
+
+```ts
+import { generateText, registerTelemetry } from "ai";
+import { OpenTelemetry } from "@ai-sdk/otel";
+import { raindrop } from "@raindrop-ai/ai-sdk";
+
+registerTelemetry(new OpenTelemetry(), raindrop());
+
+const result = await generateText({
+  model: anthropic("claude-sonnet-4-5"),
+  prompt: "what is the weather in Tokyo?",
+  telemetry: { functionId: "weather-agent" }, // no `isEnabled` needed in v7
+});
+```
+
+`raindrop()` is self-contained — `@ai-sdk/otel` is optional; you can register
+Raindrop on its own with `registerTelemetry(raindrop())`. Pass `context` and
+`subagentWrapping` to customise behaviour, e.g. `raindrop({ context: { userId: "user_123" } })`.
+
+For short-lived scripts that exit before the background flush timer fires, keep
+the reference and drain it before exiting:
+
+```ts
+const rd = raindrop();
+registerTelemetry(rd);
+// ... run your generations ...
+await rd.flush(); // or rd.shutdown()
+```
+
+Sub-agents (a `generateText`/`streamText` invoked from inside a tool's
+`execute`) nest automatically: the inner generation's spans are parented under
+the tool span so parent and child spans stay correctly nested.
+
+### AI SDK v7+ native telemetry (advanced)
 
-On AI SDK v7+, you can use the native `Telemetry` callback interface (formerly `TelemetryIntegration` before beta.111) instead of Proxy wrapping. This avoids Proxy overhead and works with all AI SDK entry points (including `ToolLoopAgent`).
+For finer control you can build the integration from a `createRaindropAISDK`
+client instead. The native `Telemetry` callback interface (formerly
+`TelemetryIntegration` before beta.111) avoids Proxy overhead and works with all
+AI SDK entry points (including `ToolLoopAgent`).
 
 ```ts
 // Option A: wrap() with nativeTelemetry flag
@@ -251,7 +314,7 @@ This package is tested against multiple Vercel AI SDK versions:
 | v4.x    | ✅ Supported | Proxy |
 | v5.x    | ✅ Supported | Proxy |
 | v6.x    | ✅ Supported | Proxy |
-| v7.x (beta) | ✅ Supported | Proxy (default) or native `Telemetry` (opt-in, formerly `TelemetryIntegration` pre-beta.111). Verified against beta.116. |
+| v7.x (beta/canary) | ✅ Supported | Proxy (default) or native `Telemetry` (opt-in, formerly `TelemetryIntegration` pre-beta.111). Verified against beta.116 and canary.171. |
 
 ### Version Differences Handled