@raindrop-ai/wizard 0.0.1 → 0.0.2

package/dist/src/docs/vercel-ai-sdk.md

@@ -1,304 +0,0 @@
-## Vercel AI SDK Integration
-
-Two-step setup:
-
-1. Configure OpenTelemetry trace exporter (platform-specific)
-2. Instrument AI SDK calls with Raindrop metadata
-
----
-
-## Step 1: Configure OTEL Trace Exporter
-
-> Choose the section matching the project setup:
->
-> - **Next.js + Sentry** → [With Sentry (Next.js)](#with-sentry-nextjs)
-> - **Next.js (no Sentry)** → [Next.js](#nextjs)
-> - **Node.js** → [Node.js](#nodejs)
-> - **Cloudflare Workers** → [Cloudflare Workers](#cloudflare-workers)
-
-### With Sentry (Next.js)
-
-If already using Sentry, add Raindrop's exporter to Sentry's OTEL config to
-avoid duplicate registration issues.
-
-**Install dependencies:**
-
-```bash
-npm install @opentelemetry/exporter-trace-otlp-proto @opentelemetry/sdk-trace-base
-```
-
-**Configure:**
-
-```ts
-// sentry.server.config.ts
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
-import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
-import * as Sentry from '@sentry/nextjs';
-
-Sentry.init({
-  dsn: process.env.SENTRY_DSN,
-  tracesSampleRate: 1,
-  openTelemetrySpanProcessors: [
-    new BatchSpanProcessor(
-      new OTLPTraceExporter({
-        url: 'https://api.raindrop.ai/v1/traces',
-        headers: {
-          Authorization: `Bearer ${process.env.RAINDROP_WRITE_KEY}`,
-        },
-      }),
-    ),
-  ],
-});
-```
-
-### Next.js
-
-**Install dependencies:**
-
-```bash
-npm install raindrop-ai @opentelemetry/api @opentelemetry/sdk-trace-base @vercel/otel
-```
-
-**Configure:**
-
-```ts
-// instrumentation.ts
-import { registerOTel, OTLPHttpProtoTraceExporter } from '@vercel/otel';
-import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
-
-export function register() {
-  registerOTel({
-    serviceName: projectName, // Replace with your app/service name
-    spanProcessors: [
-      new BatchSpanProcessor(
-        new OTLPHttpProtoTraceExporter({
-          url: 'https://api.raindrop.ai/v1/traces',
-          headers: {
-            Authorization: `Bearer ${process.env.RAINDROP_WRITE_KEY}`,
-          },
-        }),
-      ),
-    ],
-  });
-}
-```
-
-> Error: "Cannot execute the operation on ended Span" → Use `runtime = 'nodejs'`
-> instead of `'edge'`.
-
-### Node.js
-
-**Install dependencies:**
-
-```bash
-npm install raindrop-ai @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto @opentelemetry/sdk-trace-node
-```
-
-**Configure:**
-
-```ts
-import { NodeSDK } from '@opentelemetry/sdk-node';
-import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';
-import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
-import { resourceFromAttributes } from '@opentelemetry/resources';
-
-const sdk = new NodeSDK({
-  resource: resourceFromAttributes({
-    [ATTR_SERVICE_NAME]: projectName, // Replace with your app/service name
-  }),
-  spanProcessors: [
-    new BatchSpanProcessor(
-      new OTLPTraceExporter({
-        url: 'https://api.raindrop.ai/v1/traces',
-        headers: {
-          Authorization: `Bearer ${process.env.RAINDROP_WRITE_KEY}`,
-        },
-      }),
-    ),
-  ],
-});
-
-sdk.start();
-```
-
-### Cloudflare Workers
-
-Cloudflare's native tracing does not support custom spans. Use
-`@microlabs/otel-cf-workers`.
-
-**Install dependencies:**
-
-```bash
-npm install raindrop-ai @opentelemetry/api @microlabs/otel-cf-workers
-```
-
-**Wrangler config:**
-
-```toml
-compatibility_flags = ["nodejs_compat"]
-```
-
-**OTEL config:**
-
-```ts
-// src/otel.ts
-import { instrument, type ResolveConfigFn } from '@microlabs/otel-cf-workers';
-
-export interface Env {
-  RAINDROP_WRITE_KEY: string;
-  [key: string]: unknown;
-}
-
-export const otelConfig: ResolveConfigFn<Env> = (env, _trigger) => ({
-  exporter: {
-    url: 'https://api.raindrop.ai/v1/traces',
-    headers: {
-      Authorization: `Bearer ${env.RAINDROP_WRITE_KEY}`,
-    },
-  },
-  service: {
-    name: workerName, // Replace with your worker/service name
-  },
-});
-
-export { instrument };
-```
-
-**Instrument handler:**
-
-```ts
-// src/index.ts — adapt AI provider imports to your project
-import { streamText } from 'ai';
-import { createOpenAI } from '@ai-sdk/openai'; // Adapt to your AI provider (e.g. @ai-sdk/anthropic)
-import raindrop from 'raindrop-ai/otel';
-import { instrument, otelConfig, Env } from './otel';
-
-const handler = {
-  async fetch(
-    request: Request,
-    env: Env,
-    ctx: ExecutionContext,
-  ): Promise<Response> {
-    const openai = createOpenAI({ apiKey: env.OPENAI_API_KEY }); // Adapt to your AI provider
-    const { prompt } = await request.json();
-
-    const result = streamText({
-      model: model, // Your app's AI model instance (e.g. 'gpt-4o','claude-3-opus')
-      prompt,
-      experimental_telemetry: {
-        isEnabled: true,
-        functionId: 'chat',
-        metadata: {
-          ...raindrop.metadata({ userId: userId }), // The authenticated user's ID from your app
-        },
-      },
-    });
-
-    ctx.waitUntil(result.text);
-    return result.toTextStreamResponse();
-  },
-};
-
-export default instrument(handler, otelConfig);
-```
-
----
-
-## Step 2: Instrumentation
-
-### Requirements
-
-1. Enable telemetry at **all** AI SDK call sites:
-   `experimental_telemetry: { isEnabled: true }`
-2. Add Raindrop metadata at top-level call using `raindrop.metadata()`
-
-### Usage
-
-```typescript
-// Adapt imports to your project's AI provider (e.g. @ai-sdk/openai, @ai-sdk/anthropic, etc.)
-import { generateText, tool } from 'ai';
-import { z } from 'zod';
-import raindrop from 'raindrop-ai/otel';
-
-// Nested call - only needs isEnabled: true
-const enhanceStory = tool({
-  description: 'Enhance story',
-  parameters: z.object({ story: z.string() }),
-  execute: async ({ story }) => {
-    const enhanced = await generateText({
-      model: model, // Your app's AI model instance (e.g. 'gpt-4o','claude-3-opus')
-      prompt: `Enhance: ${story}`,
-      experimental_telemetry: {
-        isEnabled: true, // Required at all call sites
-        functionId: 'enhance-story',
-      },
-    });
-    return { enhancedStory: enhanced.text };
-  },
-});
-
-// Top-level call - add raindrop.metadata()
-const result = await generateText({
-  model: model, // Your app's AI model instance
-  prompt: userPrompt,
-  tools: { enhanceStory },
-  experimental_telemetry: {
-    isEnabled: true, // Required
-    functionId: 'generate-text',
-    metadata: {
-      ...raindrop.metadata({
-        userId: userId, // Required — the authenticated user's ID from your app
-        eventName: eventName, // A descriptive name for this AI action (e.g. 'chat_message', 'code_generation')
-        convoId: conversationId, // Your app's conversation/thread ID (if applicable)
-        wizardSession: '__WIZARD_SESSION_UUID__', // Required
-      }),
-    },
-  },
-});
-```
-
-### Key Points
-
-- **All call sites** need `experimental_telemetry: { isEnabled: true }`
-- **Top-level call** adds `raindrop.metadata()` to capture user/event info
-- **Nested calls** only need `isEnabled: true`
-
-## Troubleshooting
-
-### Debug Logging
-
-```bash
-OTEL_LOG_LEVEL=debug npm run dev
-```
-
-### Missing Traces
-
-Ensure `experimental_telemetry: { isEnabled: true }` at **every** AI SDK call:
-
-```typescript
-// ❌ Not traced
-const result = await generateText({ model: openai('gpt-4o'), prompt: 'Hello' });
-
-// ✅ Traced
-const result = await generateText({
-  model: openai('gpt-4o'),
-  prompt: 'Hello',
-  experimental_telemetry: { isEnabled: true },
-});
-```
-
-### Cloudflare Workers: Incomplete Spans
-
-Streaming responses need `waitUntil()` to prevent premature flush:
-
-```typescript
-// ❌ Incomplete spans (1ms duration)
-const result = streamText({ ... });
-return result.toTextStreamResponse();
-
-// ✅ Complete spans
-const result = streamText({ ... });
-ctx.waitUntil(result.text);  // Delays flush until stream completes
-return result.toTextStreamResponse();
-```