raindrop-ai 0.0.25

package/dist/index-Dx0acc0k.d.mts

@@ -0,0 +1,549 @@
+import { Attachment } from '@dawn/schemas/ingest';
+import { Span } from '@opentelemetry/api';
+
+/**
+ * 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;
+    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;
+};
+type TraceContextOutput = 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
+ */
+interface TaskParams {
+    name: string;
+    kind: "llm" | "tool" | "retrival" | "internal";
+    properties?: Record<string, string>;
+    inputParameters?: unknown[];
+}
+/**
+ * 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 workflow that executes the provided function.
+     *
+     * @template T The return type of the function
+     * @param params Either a WorkflowParams object or a string representing the workflow name
+     * @param fn The function to execute within the traced workflow
+     * @param thisArg Optional. The value to use as `this` when executing the function.
+     *                Useful when passing methods from classes that require their class instance context.
+     * @param args Additional arguments to pass to the function
+     * @returns A promise that resolves to the function's return value
+     *
+     * @example
+     * // Content generation workflow with business context
+     * await interaction.withWorkflow({
+     *   name: "joke_generator_workflow",
+     *   properties: {
+     *     content_type: "humor",
+     *     audience: "developers",
+     *     distribution_channel: "slack",
+     *     priority: "normal"
+     *   }
+     * }, async () => {
+     *   const joke = await createJoke();
+     *   const translation = await translateToPirate(joke);
+     *   const signature = await generateSignature(translation);
+     *   return translation + "\n\n" + signature;
+     * });
+     *
+     * @example
+     * // Using thisArg to preserve class context in LLM service
+     * class AIServiceClient {
+     *   private apiKey: string;
+     *   private chatHistory: Message[];
+     *
+     *   async generateResponse(prompt: string) {
+     *     // Method that uses this.apiKey and this.chatHistory
+     *     const completion = await openai.chat.completions.create({
+     *       model: "gpt-4",
+     *       messages: [...this.chatHistory, { role: "user", content: prompt }],
+     *       api_key: this.apiKey
+     *     });
+     *     return completion.choices[0].message.content;
+     *   }
+     *
+     *   async processConversation(prompt: string, conversationId: string) {
+     *     // Pass this as thisArg to preserve context
+     *     return await interaction.withWorkflow(
+     *       {
+     *         name: "conversation_flow",
+     *         properties: {
+     *           request_source: "mobile_app",
+     *           conversation_stage: "follow_up",
+     *           user_subscription: "premium",
+     *           locale: "en-US"
+     *         }
+     *       },
+     *       this.generateResponse,
+     *       this, // thisArg to access this.apiKey and this.chatHistory
+     *       prompt
+     *     );
+     *   }
+     * }
+     */
+    withWorkflow<T>(params: WorkflowParams | string, fn: (...args: any[]) => Promise<T> | T, thisArg?: any, ...args: any[]): Promise<T>;
+    /**
+     * Creates a traced task that executes the provided function.
+     *
+     * @template T The return type of the function
+     * @param params Either a TaskParams object or a string representing the task name
+     * @param fn The function to execute within the traced task
+     * @param thisArg Optional. The value to use as `this` when executing the function.
+     *                Useful when passing methods from classes that require their class instance context.
+     * @param args Additional arguments to pass to the function
+     * @returns A promise that resolves to the function's return value
+     *
+     * @example
+     * // LLM task with business metadata
+     * await interaction.withTask({
+     *   name: "joke_creation",
+     *   kind: "llm",
+     *   properties: {
+     *     request_source: "web",
+     *     feature_flag: "beta_jokes",
+     *     experiment_group: "creative_boost",
+     *     user_segment: "developer"
+     *   }
+     * }, async () => {
+     *   const completion = await openai.chat.completions.create({
+     *     model: "gpt-3.5-turbo",
+     *     temperature: 0.7,
+     *     max_tokens: 2048,
+     *     messages: [
+     *       { role: "system", content: "You are a helpful assistant." },
+     *       { role: "user", content: "I can't log into my account." }
+     *     ]
+     *   });
+     *   return completion.choices[0].message.content;
+     * });
+     *
+     * @example
+     * // Using thisArg with an embedding service
+     * class EmbeddingService {
+     *   private embedModel: string;
+     *   private dimension: number;
+     *
+     *   async embedText(text: string) {
+     *     // Uses this.embedModel and this.dimension
+     *     const embedding = await openai.embeddings.create({
+     *       model: this.embedModel,
+     *       input: text
+     *     });
+     *     return embedding.data[0].embedding.slice(0, this.dimension);
+     *   }
+     *
+     *   async getEmbedding(document: string, docId: string) {
+     *     return interaction.withTask(
+     *       {
+     *         name: "text_embedding",
+     *         kind: "llm",
+     *         properties: {
+     *           document_type: "knowledge_base",
+     *           doc_id: docId,
+     *           language: "en",
+     *           content_source: "internal_wiki"
+     *         }
+     *       },
+     *       this.embedText,
+     *       this,     // thisArg preserves access to this.embedModel and this.dimension
+     *       document  // Text to be embedded
+     *     );
+     *   }
+     * }
+     */
+    withTask<T>(params: TaskParams | string, 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
+     */
+    createTask(params: TaskParams): Span;
+    /**
+     * Executes a function with additional context properties.
+     *
+     * @template T The return type of the function
+     * @param properties Object containing context properties to add
+     * @param fn The function to execute with additional context
+     * @param thisArg Optional. The value to use as `this` when executing the function.
+     *                Useful when passing methods from classes that require their class instance context.
+     * @param args Additional arguments to pass to the function
+     * @returns The function's return value or a promise that resolves to it
+     *
+     * @example
+     * // Adding business context to LLM calls
+     * const result = interaction.withContext(
+     *   {
+     *     user_intent: "troubleshooting",
+     *     product_area: "authentication",
+     *     session_priority: "high",
+     *     customer_tier: "enterprise"
+     *   },
+     *   async () => {
+     *     const completion = await openai.chat.completions.create({
+     *       model: "gpt-4",
+     *       temperature: 0.7,
+     *       max_tokens: 2048,
+     *       messages: [
+     *         { role: "system", content: "You are a helpful assistant." },
+     *         { role: "user", content: "I can't log into my account." }
+     *       ]
+     *     });
+     *     return completion.choices[0].message.content;
+     *   }
+     * );
+     *
+     * @example
+     * // Using thisArg with semantic search application
+     * class SearchService {
+     *   private vectorDB: VectorDatabase;
+     *   private queryProcessor: QueryProcessor;
+     *
+     *   async findRelevantDocuments(query: string) {
+     *     // Uses this.vectorDB and this.queryProcessor
+     *     const processedQuery = this.queryProcessor.enhance(query);
+     *     return this.vectorDB.similaritySearch(processedQuery, 5);
+     *   }
+     *
+     *   async search(userQuery: string, userId: string) {
+     *     return interaction.withContext(
+     *       {
+     *         search_type: "semantic",
+     *         user_history: "returning_user",
+     *         search_filter: "documentation",
+     *         analytics_source: "help_center"
+     *       },
+     *       this.findRelevantDocuments,
+     *       this,  // thisArg preserves access to this.vectorDB and this.queryProcessor
+     *       userQuery  // Search query to process
+     *     );
+     *   }
+     * }
+     */
+    withContext<T>(properties: Record<string, string>, fn: (...args: any[]) => Promise<T> | T, thisArg?: any, ...args: any[]): T | Promise<T>;
+    /**
+     * 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: TraceContextOutput): void;
+};
+
+interface AnalyticsConfig {
+    writeKey: string;
+    bufferSize?: number;
+    bufferTimeout?: number;
+    debugLogs?: boolean;
+    endpoint?: string;
+    redactPii?: boolean;
+}
+declare const MAX_INGEST_SIZE_BYTES: number;
+declare class Raindrop {
+    private writeKey;
+    private apiUrl;
+    private buffer;
+    private bufferSize;
+    private bufferTimeout;
+    private flushTimer;
+    private debugLogs;
+    private redactPii;
+    private context;
+    private _tracing;
+    private partialEventBuffer;
+    private partialEventTimeouts;
+    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;
+    /**
+     * 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 dawn 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
+     * dawnAnalytics.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;
+    /**
+     * 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, MAX_INGEST_SIZE_BYTES as M, Raindrop as R };