raindrop-ai 0.0.64 → 0.0.66

package/dist/index-BnPIaY-L.d.mts

@@ -0,0 +1,581 @@
+import { Span as Span$1, HrTime, Attributes, SpanKind, SpanContext, SpanStatus, Link, Context } from '@opentelemetry/api';
+import { z } from 'zod';
+import { Resource } from '@opentelemetry/resources';
+import { SpanProcessorOptions } from '@traceloop/node-server-sdk';
+
+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$1;
+    /**
+     * 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>;
+};
+
+/**
+ * An instrumentation scope consists of the name and optional version
+ * used to obtain a tracer or meter from a provider. This metadata is made
+ * available on ReadableSpan and MetricRecord for use by the export pipeline.
+ */
+interface InstrumentationScope {
+    readonly name: string;
+    readonly version?: string;
+    readonly schemaUrl?: string;
+}
+
+/**
+ * Represents a timed event.
+ * A timed event is an event with a timestamp.
+ */
+interface TimedEvent {
+    time: HrTime;
+    /** The name of the event. */
+    name: string;
+    /** The attributes of the event. */
+    attributes?: Attributes;
+    /** Count of attributes of the event that were dropped due to collection limits */
+    droppedAttributesCount?: number;
+}
+
+interface ReadableSpan {
+    readonly name: string;
+    readonly kind: SpanKind;
+    readonly spanContext: () => SpanContext;
+    readonly parentSpanContext?: SpanContext;
+    readonly startTime: HrTime;
+    readonly endTime: HrTime;
+    readonly status: SpanStatus;
+    readonly attributes: Attributes;
+    readonly links: Link[];
+    readonly events: TimedEvent[];
+    readonly duration: HrTime;
+    readonly ended: boolean;
+    readonly resource: Resource;
+    readonly instrumentationScope: InstrumentationScope;
+    readonly droppedAttributesCount: number;
+    readonly droppedEventsCount: number;
+    readonly droppedLinksCount: number;
+}
+
+/**
+ * This type provides the properties of @link{ReadableSpan} at the same time
+ * of the Span API
+ */
+type Span = Span$1 & ReadableSpan;
+
+/**
+ * SpanProcessor is the interface Tracer SDK uses to allow synchronous hooks
+ * for when a {@link Span} is started or when a {@link Span} is ended.
+ */
+interface SpanProcessor {
+    /**
+     * Forces to export all finished spans
+     */
+    forceFlush(): Promise<void>;
+    /**
+     * Called when a {@link Span} is started, if the `span.isRecording()`
+     * returns true.
+     * @param span the Span that just started.
+     */
+    onStart(span: Span, parentContext: Context): void;
+    /**
+     * Called when a {@link ReadableSpan} is ended, if the `span.isRecording()`
+     * returns true.
+     * @param span the Span that just ended.
+     */
+    onEnd(span: ReadableSpan): void;
+    /**
+     * Shuts down the processor. Called when SDK is shut down. This is an
+     * opportunity for processor to do any cleanup required.
+     */
+    shutdown(): Promise<void>;
+}
+
+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): SpanProcessor;
+    /**
+     * 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 as A, type BeginInteractionOptions as B, type FinishInteractionOptions as F, type Interaction as I, MAX_INGEST_SIZE_BYTES as M, type PartialAiTrackEvent as P, Raindrop as R, type SpanProcessor as S, type Tracer as T, type WorkflowParams as W, type Attachment as a, type AttachmentType as b, type IdentifyEvent as c, type SignalEvent as d, type SpanParams as e, type ToolParams as f, type TraceContext as g };