Typescript

​

Installation

Install with your package manager of choice:

npm install raindrop-ai

import Raindrop from "raindrop-ai";

// Replace with the key from your Raindrop dashboard
const raindrop = new Raindrop({ writeKey: RAINDROP_API_KEY });

​

Quick-start: the Interaction API

The new interaction workflow is a three-step pattern:

1. begin() - creates an interaction object and logs the initial user input.
2. Update - optionally call setProperty, setProperties, or addAttachments.
3. finish() - records the AI’s final output and closes the interaction.

​

Example: chat completion with the ai SDK

import { openai } from '@ai-sdk/openai';
import { randomUUID } from "crypto";

const message = "What is love?"
const eventId = randomUUID() // generate your own ID so you can correlate logs

// 1️. Start the interaction
const interaction = raindrop.begin({
  eventId,
  event: "chat_message",
  userId : "user_123",
  input: message,
  model: "gpt-4o",
  convoId: "convo_123",
  properties: {
    systemPrompt: "text",
    os: "macOS",
  },
});

const { text } = await generateText({
  model: openai("gpt-4o"),
  prompt: message
})

// 3️ Finish and ship the event
interaction.finish({
  output: text,
});

​

Updating an interaction

You can update an interaction at any time using setProperty, setProperties, or addAttachments.

interaction.setProperty("stage", "embedding");
interaction.addAttachments([
  {
    type: "text",
    name: "Additional Info",
    value: "A very long document",
    role: "input",
  },
  { type: "image", value: "https://example.com/image.png", role: "output" },
  {
    type: "iframe",
    name: "Generated UI",
    value: "https://newui.generated.com",
    role: "output",
  },
]);

​

Resuming an interaction

If you don’t have access to the interaction object that was returned from begin(), you can resume an interaction by calling resumeInteraction().

const interaction = raindrop.resumeInteraction(eventId);

​

Single-shot tracking (legacy trackAi)

If your interaction is atomic (e.g. “user asked, model answered” in one function) you can still call trackAi() directly:

raindrop.trackAi({
  event: "user_message",
  userId: "user123",
  model: "gpt-4o-mini",
  input: "Who won the 2023 AFL Grand Final?",
  output: "Collingwood by four points!",
  properties: {
    systemPrompt: "text",
    os: "macOS",
  },
});

Heads‑up: We recommend migrating to begin() → finish() for all new code so you gain partial‑event buffering, tracing helpers, and upcoming features such as automatic token counts.

​

Tracking Signals (feedback)

Signals capture explicit or implicit quality ratings on an earlier AI event. Use trackSignal() with the same eventId you used in begin() or trackAi().

// User clicks a thumbs‑down button
await raindrop.trackSignal({
  eventId: "my_event_id",
  name: "thumbs_down",
  comment: "Answer was offtopic",
});

​

Attachments

Attachments allow you to include context from the user or that hte model outputted. These could be documents, generated images, code, or even an entire web page. They work the same way in begin() interactions and in single‑shot trackAi calls.

Each attachment is an object with the following properties:

• type (string): The type of attachment. Can be “code”, “text”, “image”, or “iframe”.
• name (optional string): A name for the attachment.
• value (string): The content or URL of the attachment.
• role (string): Either “input” or “output”, indicating whether the attachment is part of the user input or AI output.
• language (optional string): For code attachments, specifies the programming language.

interaction.addAttachments([
  {
    type: "code",
    role: "input",
    language: "typescript",
    name: "example.ts",
    value: "console.log('hello');",
  },
  {
    type: "text",
    name: "Additional Info",
    value: "Some extra text",
    role: "input",
  },
  { type: "image", value: "https://example.com/image.png", role: "output" },
  { type: "iframe", value: "https://example.com/embed", role: "output" },
]);

Supported types: code, text, image, iframe.

​

Identifying users

raindrop.setUserDetails({
  userId: "user123",
  traits: {
    name: "Jane",
    email: "jane@example.com",
    plan: "pro",
    os: "macOS",
  },
});

​

PII redaction

Read more on how Raindrop handles privacy and PII redaction here. You can enable client-side PII redaction when intializing the Analytics class like so:

new Raindrop({
  writeKey: RAINDROP_API_KEY,
  redactPii: true,
});

​

Error Handling

If an error occurs while sending events to Raindrop, an exception will be raised. Make sure to handle exceptions appropriately in your application.

​

Configuration & helpers

• Debug logs – debugLogs: true prints every queued event.
• Closing – call await raindrop.close() before your process exits to flush buffers.

new Raindrop({
  writeKey: RAINDROP_API_KEY,
  debugLogs: process.env.NODE_ENV !== "production",
});

​

AI Tracing

AI tracing allows you to track detailed AI pipeline execution, capturing step-by-step information of complex multi-model interactions or chained prompts. This helps you:

• Visualize the full execution flow of your AI application
• Debug and optimize complex prompt chains
• Understand intermediate steps that led to a specific generated output

​

Using withSpan for Task Tracing

The withSpan method allows you to trace specific tasks or operations within your AI application. This is especially useful for tracking LLM requests. Any LLM call within the span will be automatically tracked, no further work required.

// Basic task tracing
const result = await interaction.withSpan(
  { name: "generate_response" },
  async () => {
    // Task implementation
    return "Generated response";
  }
);

// Task with properties and input parameters
const result = await interaction.withSpan(
  {
    name: "embedding_generation",
    properties: { model: "text-embedding-3-large" },
    inputParameters: ["What is the weather today?"]
  },
  async () => {
    // Generate embeddings
    return [0.1, 0.2, 0.3, 0.4];
  }
);

​

Parameters

​

Using withTool for Tool Tracing

The withTool method allows you to trace any actions your agent takes. This could be as simple as saving or retrieving a memory, or using external services like web search or API calls. Tracing these actions helps you understand your agent’s behavior and what led up to the agent’s response.

// Basic tool usage
const result = await interaction.withTool(
  { name: "search_tool" },
  async () => {
    // Call to external API or service
    return "Search results";
  }
);

// Tool with properties and input parameters
const result = await interaction.withTool(
  {
    name: "calculator",
    properties: { operation: "multiply" },
    inputParameters: { a: 5, b: 10 }
  },
  async () => {
    // Tool implementation
    return "Result: 50";
  }
);

​

Parameters

That’s it! You’re ready to explore your events in the Raindrop dashboard. Ping us on Slack or email us if you get stuck!