Typescript
The Raindrop SDK allows you to track user events and AI interactions in your app. This documentation provides a brief overview of how to use the Typescript SDK.
Installation
Install with your package manager of choice:
Quick-start: the Interaction API
The new interaction workflow is a three-step pattern:
begin()
- creates an interaction object and logs the initial user input.- Update - optionally call
setProperty
,setProperties
, oraddAttachments
. finish()
- records the AI’s final output and closes the interaction.
Example: chat completion with the ai
SDK
Updating an interaction
You can update an interaction at any time using setProperty
, setProperties
, or addAttachments
.
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()
.
Interactions are subject to the global 1 MB event limit; oversized payloads will be truncated.
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:
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()
.
Parameter | Type | Description |
---|---|---|
eventId | string | The ID of the AI event you’re evaluating |
name | "thumbs_up", "thumbs_down" , string | Name of the signal (e.g. "thumbs_up" ) |
type | "default", "feedback", "edit" | Optional, defaults to "default" |
comment | string | For feedback signals |
after | string | For edit signals – the user’s final content |
sentiment | "POSITIVE", "NEGATIVE" | indicates whether the signal is positive (default is NEGATIVE) |
…others | See API reference |
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.
Supported types: code
, text
, image
, iframe
.
Identifying users
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:
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.
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.
Parameters
Parameter | Type | Description |
---|---|---|
name | string | Name of the task for identification in traces |
properties | Record<string, string> (optional) | Key-value pairs for additional metadata |
inputParameters | unknown[] (optional) | Array of input parameters for the task |
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.
Parameters
Parameter | Type | Description |
---|---|---|
name | string | Name of the tool for identification in traces |
version | number (optional) | Version number of the tool |
properties | Record<string, string> (optional) | Key-value pairs for additional metadata |
inputParameters | Record<string, any> (optional) | Record of input parameters for the tool |
traceContent | boolean (optional) | Flag to control whether content is traced |
suppressTracing | boolean (optional) | Flag to suppress tracing for this tool invocation |
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!