raindrop-ai 0.0.69 → 0.0.70

package/dist/index.d.mts

@@ -1,5 +1,514 @@
-export { A as AiTrackEvent, a as Attachment, b as AttachmentType, B as BeginInteractionOptions, F as FinishInteractionOptions, c as IdentifyEvent, I as Interaction, M as MAX_INGEST_SIZE_BYTES, P as PartialAiTrackEvent, R as Raindrop, d as SignalEvent, e as SpanParams, f as ToolParams, g as TraceContext, T as Tracer, W as WorkflowParams, R as default } from './index-BnPIaY-L.mjs';
-import '@traceloop/node-server-sdk';
-import '@opentelemetry/api';
-import 'zod';
-import '@opentelemetry/resources';
+import { Span } from '@opentelemetry/api';
+import { z } from 'zod';
+import { SpanProcessorOptions } from '@traceloop/node-server-sdk';
+
+/**
+ * Version-agnostic SpanProcessor interface.
+ *
+ * This interface avoids direct dependency on OTEL's Span and ReadableSpan types
+ * which can cause compatibility issues across minor OTEL versions. Using `any`
+ * allows the processor to work with any version of OTEL without type conflicts.
+ */
+interface RaindropSpanProcessor {
+    forceFlush(): Promise<void>;
+    onStart(span: any, parentContext: any): void;
+    onEnd(span: any): void;
+    shutdown(): Promise<void>;
+}
+type BaseAttachment = {
+    attachment_id?: string;
+    name?: string;
+    value: string;
+    role: "input" | "output";
+};
+type CodeAttachment = BaseAttachment & {
+    type: "code";
+    language?: string;
+};
+type OtherAttachment = BaseAttachment & {
+    type: "text" | "image" | "iframe";
+};
+type Attachment = CodeAttachment | OtherAttachment;
+/**
+ * Interface for tracking events.
+ *
+ * @param eventId - An optional event ID for the event.
+ * @param event - The name of the event.
+ * @param properties - An optional record of properties for the event.
+ * @param timestamp - An optional timestamp for the event.
+ * @param userId - The ID of the user. This is a required field.
+ * @param anonymousId - An optional anonymous ID for the user.
+ */
+interface TrackEvent {
+    eventId?: string;
+    event: string;
+    properties?: Record<string, any>;
+    timestamp?: string;
+    userId: string;
+}
+type BasicSignal = {
+    eventId: string;
+    name: "thumbs_up" | "thumbs_down" | string;
+    sentiment?: "POSITIVE" | "NEGATIVE";
+    timestamp?: string;
+    properties?: {
+        [key: string]: any;
+    };
+    attachmentId?: string;
+};
+type DefaultSignal = BasicSignal & {
+    type?: "default";
+};
+type FeedbackSignal = BasicSignal & {
+    type: "feedback";
+    comment?: string;
+};
+type EditSignal = BasicSignal & {
+    type: "edit";
+    after?: string;
+};
+type SignalEvent = DefaultSignal | FeedbackSignal | EditSignal;
+/**
+ * Interface for identifying events.
+ *
+ * @param userId - The ID of the user. This is a required field.
+ * @param traits - An optional object of traits for the user.
+ * @param anonymousId - An optional anonymous ID for the user.
+ * TODO: ensure at least one out of userId or anonymousId is present
+ */
+interface IdentifyEvent {
+    userId: string;
+    traits?: object;
+}
+/**
+ * Type definition for AI tracking events.
+ * In addition to the properties of a TrackEvent, an AiTrackEvent may have a 'model' property.
+ * It must have at least one of 'input' or 'output' property.
+ *
+ * @property model - An optional model property for the even
+ * @property input - An optional input property for the event, required if output is not provided.
+ * @property output - An optional output property for the event, required if input is not provided.
+ */
+type AiTrackEvent = Omit<TrackEvent, "type"> & {
+    model?: string;
+    convoId?: string;
+    attachments?: Attachment[];
+} & ({
+    input: string;
+    output?: string;
+} | {
+    input?: string;
+    output: string;
+});
+/**
+ * Type definition for partial AI tracking events used with trackAiPartial.
+ * Requires an eventId to correlate partial updates. All other fields are optional.
+ */
+type PartialAiTrackEvent = Partial<AiTrackEvent> & {
+    eventId: string;
+    isPending?: boolean;
+};
+declare const AttachmentTypeSchema: z.ZodEnum<["code", "text", "image", "iframe"]>;
+type AttachmentType = z.infer<typeof AttachmentTypeSchema>;
+/**
+ * Configuration for initializing a trace interaction.
+ *
+ * This interface defines the context required to create and track an AI
+ * interaction through its lifecycle. It includes identifiers for the user
+ * and conversation, as well as input/output content and attachments.
+ *
+ * @property userId - Optional unique identifier for the user
+ * @property convoId - Optional unique identifier for the conversation
+ * @property eventId - Optional unique identifier for this specific interaction event
+ * @property input - Optional input text from the user
+ * @property attachments - Optional array of attachments associated with this interaction
+ * @property properties - Optional key-value pairs for additional custom metadata
+ */
+interface TraceContext {
+    userId?: string;
+    convoId?: string;
+    eventId?: string;
+    input?: string;
+    event?: string;
+    attachments?: Attachment[];
+    properties?: Record<string, string>;
+}
+type BeginInteractionOptions = PartialAiTrackEvent & {
+    eventId: string;
+};
+type FinishInteractionOptions = Omit<PartialAiTrackEvent, "eventId"> & {
+    output: string;
+    eventId?: string;
+};
+/**
+ * Configuration for a traced workflow.
+ *
+ * Workflows represent higher-level operations that might contain multiple
+ * tasks. They help organize traces into logical units of work.
+ *
+ * @property name - Name of the workflow for identification in traces
+ * @property inputParameters - Optional array of input parameters for the workflow
+ * @property properties - Optional key-value pairs for additional metadata
+ */
+interface WorkflowParams {
+    name: string;
+    inputParameters?: unknown[];
+    properties?: Record<string, string>;
+}
+/**
+ * Configuration for a traced task.
+ *
+ * Tasks represent individual operations within a workflow, such as an LLM call,
+ * a tool invocation, a retrieval operation, or internal processing.
+ *
+ * @property name - Name of the task for identification in traces
+ * @property kind - Category of the task (llm, tool, retrival, or internal)
+ * @property properties - Optional key-value pairs for additional metadata
+ * @property inputParameters - Optional array of input parameters for the task
+ * @property traceContent - Optional flag to control whether content is traced
+ * @property suppressTracing - Optional flag to suppress tracing for this task
+ */
+interface SpanParams {
+    name: string;
+    properties?: Record<string, string>;
+    inputParameters?: unknown[];
+    traceContent?: boolean;
+    suppressTracing?: boolean;
+}
+/**
+ * Configuration for a traced tool.
+ *
+ * Tools represent external utilities or services that are invoked during an AI interaction,
+ * such as search engines, calculators, or other specialized functions.
+ *
+ * @property name - Name of the tool for identification in traces
+ * @property version - Optional version number of the tool
+ * @property properties - Optional key-value pairs for additional metadata
+ * @property inputParameters - Optional record of input parameters for the tool
+ * @property traceContent - Optional flag to control whether content is traced
+ * @property suppressTracing - Optional flag to suppress tracing for this tool invocation
+ */
+interface ToolParams {
+    name: string;
+    version?: number;
+    properties?: Record<string, string>;
+    inputParameters?: Record<string, any>;
+    traceContent?: boolean;
+    suppressTracing?: boolean;
+}
+/**
+ * Represents an active tracing interaction for tracking and analyzing AI interactions.
+ *
+ * An Interaction is the core entity for tracing and instrumenting AI operations,
+ * allowing you to organize your code into workflows and tasks while capturing
+ * important metadata and contextual information. Use the methods on this interface
+ * to record your AI interaction's lifecycle from input to output, and to add
+ * structured context about the operation.
+ *
+ * Interactions are typically created using the `tracing.begin()` method and ended
+ * with the `end()` method. Between these calls, you can add properties, attachments,
+ * and nested traced operations.
+ *
+ * @example
+ * // Basic usage pattern
+ * const interaction = tracing.begin({
+ *   userId: "user-123",
+ *   convoId: "conversation-456"
+ * });
+ *
+ * // Set the user's input
+ * interaction.setInput("Tell me a joke about AI");
+ *
+ * // Add context properties
+ * interaction.setProperty("intent", "entertainment");
+ *
+ * // Run a traced workflow
+ * const result = await interaction.withWorkflow("joke_generation", async () => {
+ *   // Run a traced task for the LLM call
+ *   return await interaction.withTask({
+ *     name: "llm_completion",
+ *     kind: "llm"
+ *   }, async () => {
+ *     const completion = await openai.chat.completions.create({
+ *       model: "gpt-4",
+ *       messages: [{ role: "user", content: "Tell me a joke about AI" }]
+ *     });
+ *     return completion.choices[0].message.content;
+ *   });
+ * });
+ *
+ * // End the interaction with the result
+ * interaction.end(result);
+ */
+type Interaction = {
+    /**
+     * Creates a traced task that executes the provided function.
+     *
+     * @param params TaskParams object with task configuration
+     * @returns A span that can be used to record a task
+     */
+    withSpan<T>(params: SpanParams, fn: (...args: any[]) => Promise<T> | T, thisArg?: any, ...args: any[]): Promise<T>;
+    /**
+     * Creates a traced tool that executes the provided function.
+     *
+     * Tools represent external utilities or services that are invoked during an AI interaction.
+     * This method wraps a function call with tracing to capture the tool's inputs and outputs.
+     *
+     * @param params ToolParams object with tool configuration
+     * @param fn Function to execute within the tool trace
+     * @param thisArg Optional 'this' context for the function
+     * @param args Optional arguments to pass to the function
+     * @returns A promise that resolves with the tool execution result
+     *
+     * @example
+     * // Basic tool usage
+     * const result = await interaction.withTool(
+     *   { name: "search_tool" },
+     *   async () => {
+     *     // Call to external API or service
+     *     return "Search results";
+     *   }
+     * );
+     *
+     * @example
+     * // Basic tool usage
+     * const result = await interaction.withTool(
+     *   {
+     *     name: "calculator",
+     *     properties: { operation: "multiply" },
+     *     inputParameters: { a: 5, b: 10 }
+     *   },
+     *   async () => {
+     *     // Tool implementation
+     *     return "Result: 50";
+     *   }
+     * );
+     */
+    withTool<T>(params: ToolParams, fn: (...args: any[]) => Promise<T> | T, thisArg?: any, ...args: any[]): Promise<T>;
+    /**
+     * Creates a task span that can be used to manually record a task.
+     *
+     * @param params TaskParams object with task configuration
+     * @returns A span that can be used to record a task
+     */
+    startSpan(params: SpanParams): Span;
+    /**
+     * Sets multiple properties on the interaction context.
+     *
+     * @param properties Object containing properties to set
+     */
+    setProperties(properties: Record<string, string>): void;
+    /**
+     * Sets a single property on the interaction context.
+     *
+     * @param key The property key
+     * @param value The property value
+     */
+    setProperty(key: string, value: string): void;
+    /**
+     * Adds an attachment to the interaction.
+     *
+     * @param attachment The attachment to add
+     *
+     * @example
+     * // Adding various attachment types to an interaction
+     *
+     * // 1. Text attachment for context
+     * interaction.addAttachment([{
+     *   type: "text",
+     *   name: "Additional Info",
+     *   value: "A very long document",
+     *   role: "input",
+     * }]);
+     *
+     * // 2. Image attachment (output)
+     * interaction.addAttachment([{
+     *   type: "image",
+     *   value: "https://example.com/image.png",
+     *   role: "output"
+     * }]);
+     *
+     * // 3. Iframe for embedded content
+     * interaction.addAttachment([{
+     *   type: "iframe",
+     *   name: "Generated UI",
+     *   value: "https://newui.generated.com",
+     *   role: "output",
+     * }]);
+     *
+     * // 4. Code snippet
+     * interaction.addAttachment([{
+     *   type: "code",
+     *   name: "Generated SQL Query",
+     *   value: "SELECT * FROM users WHERE os_build = '17.1'",
+     *   role: "output",
+     *   language: "sql"
+     * }]);
+     *
+     * // All attachments are included when the interaction ends
+     * interaction.end("The weather is sunny and warm.");
+     */
+    addAttachments(attachments: Attachment[]): void;
+    /**
+     * Sets the input for the interaction.
+     *
+     * @param input The input string
+     */
+    setInput(input: string): void;
+    /**
+     * Ends the interaction and sends analytics data.
+     *
+     * This method completes the interaction lifecycle by:
+     * 1. Setting the trace_id as a property (if available)
+     * 2. Sending analytics data including the event ID, conversation ID,
+     *    user ID, input, output, attachments, and any custom properties
+     *
+     * @param output The final output string for this interaction
+     *
+     * @example
+     * // Start and end an interaction
+     * const interaction = tracing.begin({
+     *   userId: "user-123",
+     *   convoId: "convo-456"
+     * });
+     *
+     * interaction.setInput("What can you help me with today?");
+     * // ... process the request ...
+     *
+     * // End the interaction with the response
+     * interaction.end("I can help you with various tasks. Here are some examples...");
+     */
+    finish(resultEvent: FinishInteractionOptions): void;
+};
+type Tracer = {
+    /**
+     * Creates a traced task that executes the provided function.
+     *
+     * @param params TaskParams object with task configuration
+     * @returns A span that can be used to record a task
+     */
+    withSpan<T>(params: SpanParams, fn: (...args: any[]) => Promise<T> | T, thisArg?: any, ...args: any[]): Promise<T>;
+};
+
+interface AnalyticsConfig {
+    writeKey: string;
+    bufferSize?: number;
+    bufferTimeout?: number;
+    debugLogs?: boolean;
+    endpoint?: string;
+    redactPii?: boolean;
+    /**
+     * false by default. If true, raindrop doesn't initialize OTEL tracing.
+     * you can then use the span processor using raindrop.createSpanProcessor()
+     */
+    disableTracing?: boolean;
+    /**
+     * false by default. If true, the SDK will not send any events or initialize tracing.
+     * Useful for development/test environments.
+     */
+    disabled?: boolean;
+}
+declare const MAX_INGEST_SIZE_BYTES: number;
+declare class Raindrop {
+    private writeKey;
+    private apiUrl;
+    private buffer;
+    private bufferSize;
+    private bufferTimeout;
+    private flushTimer;
+    private redactPii;
+    private disabled;
+    private context;
+    private _tracing;
+    private partialEventBuffer;
+    private partialEventTimeouts;
+    private inFlightRequests;
+    debugLogs: boolean;
+    constructor(config: AnalyticsConfig);
+    private formatEndpoint;
+    /**
+     * Begins a new interaction.
+     *
+     * @param traceContext - The trace context for the interaction.
+     * @returns The interaction object.
+     */
+    begin(traceContext: PartialAiTrackEvent & {
+        event: string;
+        userId: string;
+    }): Interaction;
+    /**
+     * Returns a tracer object that can be used to create spans and tools that aren't tied to any interaction.
+     * For chat interaction use-case `begin` should be used.
+     * This is meant for batch jobs or other non-interactive use-cases where you only care about tracing and token usage.
+     *
+     * @param globalProperties - Optional global properties to be associated with all spans and tools.
+     * @returns The tracer object.
+     */
+    tracer(globalProperties?: Record<string, string>): Tracer;
+    createSpanProcessor(processorOptions?: SpanProcessorOptions): RaindropSpanProcessor;
+    /**
+     * Resumes an existing interaction.
+     *
+     * @param eventId - The ID of the interaction to resume.
+     * @returns The interaction object.
+     */
+    resumeInteraction(eventId: string): Interaction;
+    /**
+     * Track AI events. In addiiton to normal event properties, you can provide an "input", "output", or "model" parameter.
+     * It takes an AiTrackEvent as input and sends it to the /track-ai endpoint of the raindrop api.
+     *
+     * @param event - The AiTrackEvent (you must specify at least one of input/output properties)
+     * @returns A Promise that resolves when the event has been successfully sent.
+     *
+     * Example usage:
+     * ```typescript
+     * raindrop.track_ai({
+     *   event: "chat", //name of the event
+     *   model: "claude", //optional
+     *   input: "what's up?", // input or output is required
+     *   output: "not much human, how are you?", //input or output is required
+     *   userId: "cn123456789",
+     * });
+     * ```
+     */
+    trackAi(event: AiTrackEvent | AiTrackEvent[]): string | Array<string | undefined> | undefined;
+    private isEnvWithLocalStorage;
+    setUserDetails(event: IdentifyEvent): void;
+    trackSignal(signal: SignalEvent | SignalEvent[]): void | void[];
+    private getSize;
+    private saveToBuffer;
+    private flush;
+    private sendBatchToApi;
+    private getContext;
+    private formatZodError;
+    /**
+     * Deeply merges properties of the source object into the target object.
+     * Modifies the target object in place. Handles nested plain objects.
+     */
+    private deepMergeObjects;
+    /**
+     * Internal method for tracking partial AI events. use .begin() to start an interaction instead.
+     *
+     * @param event - The PartialAiTrackEvent, requires eventId.
+     */
+    _trackAiPartial(event: PartialAiTrackEvent): void;
+    /**
+     * Flushes a single accumulated partial event by its ID.
+     * This is called internally by the timeout or by the close method.
+     * @param eventId - The ID of the partial event to flush.
+     */
+    private flushPartialEvent;
+    /**
+     * Internal implementation of flushPartialEvent without request tracking.
+     * @param eventId - The ID of the partial event to flush.
+     */
+    private _flushPartialEventInternal;
+    /**
+     * Sends a single prepared event object to the 'events/track_partial' endpoint.
+     * @param event - The event data conforming to ClientAiTrack schema.
+     */
+    private sendPartialEvent;
+    close(): Promise<void>;
+}
+
+export { type AiTrackEvent, type Attachment, type AttachmentType, type BeginInteractionOptions, type FinishInteractionOptions, type IdentifyEvent, type Interaction, MAX_INGEST_SIZE_BYTES, type PartialAiTrackEvent, Raindrop, type RaindropSpanProcessor, type SignalEvent, type SpanParams, type ToolParams, type TraceContext, type Tracer, type WorkflowParams, Raindrop as default };