@raindrop-ai/wizard 0.0.1 → 0.0.2

package/dist/src/docs/claude-agent-sdk.mdx

@@ -0,0 +1,382 @@
+---
+title: Claude Agent SDK
+description: >-
+  Reference for integrating Raindrop with the Claude Agent SDK.
+---
+
+The `@raindrop-ai/claude-agent-sdk` package wraps the
+[Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) so
+you can capture events and traces from `query()` calls. Pass `eventMetadata()`
+to the queries you want tracked in Raindrop.
+
+## Installation
+
+<CodeGroup>
+```bash npm
+npm install @raindrop-ai/claude-agent-sdk
+```
+
+```bash yarn
+yarn add @raindrop-ai/claude-agent-sdk
+```
+
+```bash pnpm
+pnpm add @raindrop-ai/claude-agent-sdk
+```
+
+```bash bun
+bun add @raindrop-ai/claude-agent-sdk
+```
+
+</CodeGroup>
+
+## Quick Start
+
+```typescript
+import * as claudeAgentSDK from '@anthropic-ai/claude-agent-sdk';
+import {
+  createRaindropClaudeAgentSDK,
+  eventMetadata,
+} from '@raindrop-ai/claude-agent-sdk';
+
+// 1. Create the Raindrop client
+const raindrop = createRaindropClaudeAgentSDK({
+  writeKey: process.env.RAINDROP_WRITE_KEY!,
+});
+
+// 2. Wrap the Claude Agent SDK
+const { query, createSdkMcpServer, ReadTool, EditTool } = raindrop.wrap(
+  claudeAgentSDK,
+  {
+    context: {
+      properties: {
+        wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
+      },
+    },
+  },
+);
+
+// 3. Add eventMetadata() on queries you want tracked
+for await (const message of query(
+  {
+    prompt: 'List files in the current directory',
+    options: {
+      allowedTools: ['Bash'],
+      model: 'claude-sonnet-4.5',
+    },
+  },
+  eventMetadata({
+    userId, // REQUIRED: authenticated user id from your app
+    eventName, // Optional: e.g. 'agent_query'
+  }),
+)) {
+  console.log(message);
+}
+
+// Optional: identify user traits
+await raindrop.users.identify({
+  userId,
+  traits: {
+    plan: userPlan,
+    email: userEmail,
+  },
+});
+
+// 4. Flush before shutdown (serverless/scripts)
+await raindrop.flush();
+```
+
+Queries with `eventMetadata()` are tracked with events and traces. Queries
+without it run normally and are not tracked.
+
+---
+
+## Configuration
+
+### Client Options
+
+```typescript
+const raindrop = createRaindropClaudeAgentSDK({
+  writeKey: process.env.RAINDROP_WRITE_KEY!, // REQUIRED
+  endpoint: 'https://api.raindrop.ai/v1', // Optional, defaults to production
+
+  traces: {
+    enabled: true, // Default: true
+    flushIntervalMs: 5000, // Default: 5000
+    maxBatchSize: 100, // Default: 100
+    maxQueueSize: 1000, // Default: 1000
+    debug: false, // Logs trace shipping
+    debugSpans: false, // Logs span parent relationships
+  },
+
+  events: {
+    enabled: true, // Default: true
+    partialFlushMs: 1000, // Debounce for streaming updates
+    debug: false, // Logs event shipping
+  },
+});
+```
+
+### Wrap Options
+
+```typescript
+const wrapped = raindrop.wrap(claudeAgentSDK, {
+  context: {
+    properties: {
+      wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
+    },
+  },
+});
+```
+
+## Per-Query Context
+
+Use `eventMetadata()` as the second argument when you want a query tracked.
+`userId` is required:
+
+```typescript
+import { eventMetadata } from '@raindrop-ai/claude-agent-sdk';
+
+const wrapped = raindrop.wrap(claudeAgentSDK, {
+  context: {
+    properties: {
+      wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
+    },
+  },
+});
+
+for await (const msg of wrapped.query(
+  { prompt: userPrompt, options: { model: modelName } },
+  eventMetadata({
+    userId, // REQUIRED
+    convoId, // Optional: conversation/thread id from your app
+    eventName, // Optional
+    properties: { tier: userTier },
+  }),
+)) {
+  console.log(msg);
+}
+```
+
+You can also set `convoId`, `eventName`, `properties`, or `eventId` per query.
+
+**Defaults:**
+
+- If `eventMetadata()` is omitted, the query runs normally but no events or
+  traces are captured by Raindrop
+- `eventName` defaults to `"agent_query"`
+- `convoId` is auto-captured from Claude's `session_id` if not provided
+- `eventId` is auto-generated if not provided
+
+---
+
+## Identifying Users
+
+Use `users.identify` to associate traits with a user:
+
+```typescript
+await raindrop.users.identify({
+  userId,
+  traits: {
+    email: userEmail,
+    plan: userPlan,
+    orgId,
+  },
+});
+```
+
+---
+
+## Signals (Feedback)
+
+Track user feedback on AI responses using the same `eventId`:
+
+```typescript
+import { eventMetadata } from '@raindrop-ai/claude-agent-sdk';
+
+const eventId = crypto.randomUUID();
+const wrapped = raindrop.wrap(claudeAgentSDK, {
+  context: {
+    properties: {
+      wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
+    },
+  },
+});
+
+for await (const msg of wrapped.query(
+  { prompt: userMessage, options: { model: 'claude-sonnet-4.5' } },
+  eventMetadata({ userId, eventId }),
+)) {
+  console.log(msg);
+}
+
+// Later, when user gives feedback
+await raindrop.signals.track({
+  eventId,
+  name: 'thumbs_down',
+  comment: 'Answer was incorrect',
+});
+```
+
+### Signal Types
+
+| Type         | Use Case                         |
+| ------------ | -------------------------------- |
+| `"default"`  | Generic signals (thumbs up/down) |
+| `"feedback"` | User comments about quality      |
+| `"edit"`     | User corrected the output        |
+
+```typescript
+// Thumbs up
+await raindrop.signals.track({
+  eventId,
+  name: 'thumbs_up',
+  sentiment: 'POSITIVE',
+});
+
+// User edit
+await raindrop.signals.track({
+  eventId,
+  name: 'user_edit',
+  type: 'edit',
+  after: 'The corrected response text',
+});
+```
+
+---
+
+## Manual Event Updates
+
+Update events after they're created (use `eventId` from `eventMetadata`):
+
+```typescript
+const eventId = crypto.randomUUID();
+const wrapped = raindrop.wrap(claudeAgentSDK, {
+  context: {
+    properties: {
+      wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
+    },
+  },
+});
+
+for await (const msg of wrapped.query(
+  { prompt, options },
+  eventMetadata({ userId, eventId }),
+)) {
+  // ...
+}
+
+// Add properties after the query completes
+await raindrop.events.setProperties(eventId, {
+  latencyMs: 1234,
+  cached: true,
+});
+
+// Add attachments
+await raindrop.events.addAttachments(eventId, [
+  {
+    type: 'code',
+    name: 'generated.py',
+    value: "print('hello')",
+    role: 'output',
+    language: 'python',
+  },
+]);
+
+// Mark as complete (triggers immediate shipping)
+await raindrop.events.finish(eventId);
+```
+
+<Info>
+  The event is automatically finalized when the query stream completes. Use
+  `finish()` only when you need to force immediate shipping before the stream
+  ends.
+</Info>
+
+---
+
+## Flush & Shutdown
+
+Always flush before your process exits to ensure all data is sent:
+
+```typescript
+import { eventMetadata } from '@raindrop-ai/claude-agent-sdk';
+
+// Serverless: flush at end of request
+export async function POST(request: Request) {
+  const wrapped = raindrop.wrap(claudeAgentSDK, {
+    context: {
+      properties: {
+        wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
+      },
+    },
+  });
+  const messages = [];
+  for await (const msg of wrapped.query(
+    { prompt, options },
+    eventMetadata({ userId }),
+  )) {
+    messages.push(msg);
+  }
+  await raindrop.flush();
+  return Response.json({ messages });
+}
+
+// Long-running: shutdown gracefully
+process.on('SIGTERM', async () => {
+  await raindrop.shutdown();
+  process.exit(0);
+});
+```
+
+---
+
+## Debugging
+
+Enable debug logging to troubleshoot issues:
+
+```typescript
+const raindrop = createRaindropClaudeAgentSDK({
+  writeKey: process.env.RAINDROP_WRITE_KEY!,
+  events: { debug: true },
+  traces: { debug: true, debugSpans: true },
+});
+```
+
+Or via environment variable:
+
+```bash
+RAINDROP_AI_DEBUG=1 node your-script.js
+```
+
+This logs:
+
+- Every event sent to Raindrop
+- Every trace batch shipped
+- Span parent/child relationships (with `debugSpans`)
+
+---
+
+## Troubleshooting
+
+### Events not appearing in dashboard
+
+1. **Ensure tracked queries include `eventMetadata()`**
+2. **Check your write key** - Ensure `RAINDROP_WRITE_KEY` is set correctly
+3. **Flush before exit** - Call `await raindrop.flush()` before your process
+   ends
+4. **Enable debug logging** - Set `events: { debug: true }` to see what's being
+   sent
+
+### Traces missing or incomplete
+
+1. **Enable trace debugging** - Set `traces: { debug: true, debugSpans: true }`
+2. **Check for errors** - Look for `[raindrop-ai/claude-agent-sdk]` prefixed
+   logs
+
+### Wrapper not capturing tool calls
+
+Ensure the wrapped `query` is the one you call. Tools are traced via SDK hooks;
+if you call the unwrapped SDK directly, no tracing occurs.
+
+---

package/dist/src/docs/{typescript.md → typescript.mdx}

@@ -71,7 +71,8 @@ const interaction = raindrop.begin({
   input: userMessage, // The actual user message/prompt
   model: modelName, // The model being called (e.g. 'gpt-4o')
   convoId: conversationId, // Your app's conversation/thread ID (if applicable)
-  properties: { // Optional: any custom metadata relevant to your app
+  properties: {
+    // Optional: any custom metadata relevant to your app
     system_prompt: systemPrompt,
   },
 });
@@ -137,7 +138,8 @@ raindrop.trackAi({
   model: modelName, // The model being called (e.g. 'gpt-4o-mini')
   input: userPrompt, // The actual prompt sent to the model
   output: modelResponse, // The actual response from the model
-  properties: { // Optional: any custom metadata relevant to your app
+  properties: {
+    // Optional: any custom metadata relevant to your app
     system_prompt: systemPrompt,
     tool_call: toolName,
   },
@@ -215,7 +217,8 @@ interaction.addAttachments([
 // Pass actual user data from your app's auth/session
 raindrop.setUserDetails({
   userId: userId, // The authenticated user's unique identifier
-  traits: { // Pass any user traits available in your app — all keys are optional and freeform
+  traits: {
+    // Pass any user traits available in your app — all keys are optional and freeform
     name: userName,
     email: userEmail,
   },
@@ -453,7 +456,8 @@ If automatic instrumentation fails due to module loading order or bundler
 behavior, use `instrumentModules` to explicitly specify modules to instrument:
 
 <Warning>
-  **Anthropic users:** You must use a module namespace import (`import * as ...`), not the default export.
+  **Anthropic users:** You must use a module namespace import (`import * as
+  ...`), not the default export.
 </Warning>
 
 ```typescript