@posthog/ai 7.6.1 → 7.8.0

package/dist/index.cjs

@@ -30,7 +30,7 @@ function _interopNamespace(e) {
 var uuid__namespace = /*#__PURE__*/_interopNamespace(uuid);
 var AnthropicOriginal__default = /*#__PURE__*/_interopDefault(AnthropicOriginal);
 
-var version = "7.6.1";
+var version = "7.8.0";
 
 // Type guards for safer type checking
 const isString = value => {
@@ -746,6 +746,7 @@ const sendEventToPosthog = async ({
   input,
   output,
   latency,
+  timeToFirstToken,
   baseURL,
   params,
   httpStatus = 200,
@@ -812,6 +813,9 @@ const sendEventToPosthog = async ({
     } : {}),
     ...additionalTokenValues,
     $ai_latency: latency,
+    ...(timeToFirstToken !== undefined ? {
+      $ai_time_to_first_token: timeToFirstToken
+    } : {}),
     $ai_trace_id: traceId,
     $ai_base_url: baseURL,
     ...params.posthogProperties,
@@ -883,6 +887,14 @@ function formatOpenAIResponsesInput(input, instructions) {
   return messages;
 }
 
+/**
+ * Checks if a ResponseStreamEvent chunk represents the first token/content from the model.
+ * This includes various content types like text, reasoning, audio, and refusals.
+ */
+function isResponseTokenChunk(chunk) {
+  return chunk.type === 'response.output_item.added' || chunk.type === 'response.content_part.added' || chunk.type === 'response.output_text.delta' || chunk.type === 'response.reasoning_text.delta' || chunk.type === 'response.reasoning_summary_text.delta' || chunk.type === 'response.audio.delta' || chunk.type === 'response.audio.transcript.delta' || chunk.type === 'response.refusal.delta';
+}
+
 const Chat = openai.OpenAI.Chat;
 const Completions = Chat.Completions;
 const Responses = openai.OpenAI.Responses;
@@ -932,6 +944,7 @@ let WrappedCompletions$1 = class WrappedCompletions extends Completions {
               const contentBlocks = [];
               let accumulatedContent = '';
               let modelFromResponse;
+              let firstTokenTime;
               let usage = {
                 inputTokens: 0,
                 outputTokens: 0,
@@ -953,11 +966,17 @@ let WrappedCompletions$1 = class WrappedCompletions extends Completions {
                 // Handle text content
                 const deltaContent = choice?.delta?.content;
                 if (deltaContent) {
+                  if (firstTokenTime === undefined) {
+                    firstTokenTime = Date.now();
+                  }
                   accumulatedContent += deltaContent;
                 }
                 // Handle tool calls
                 const deltaToolCalls = choice?.delta?.tool_calls;
                 if (deltaToolCalls && Array.isArray(deltaToolCalls)) {
+                  if (firstTokenTime === undefined) {
+                    firstTokenTime = Date.now();
+                  }
                   for (const toolCall of deltaToolCalls) {
                     const index = toolCall.index;
                     if (index !== undefined) {
@@ -1029,6 +1048,7 @@ let WrappedCompletions$1 = class WrappedCompletions extends Completions {
                 }]
               }];
               const latency = (Date.now() - startTime) / 1000;
+              const timeToFirstToken = firstTokenTime !== undefined ? (firstTokenTime - startTime) / 1000 : undefined;
               const availableTools = extractAvailableToolCalls('openai', openAIParams);
               await sendEventToPosthog({
                 client: this.phClient,
@@ -1038,6 +1058,7 @@ let WrappedCompletions$1 = class WrappedCompletions extends Completions {
                 input: sanitizeOpenAI(openAIParams.messages),
                 output: formattedOutput,
                 latency,
+                timeToFirstToken,
                 baseURL: this.baseURL,
                 params: body,
                 httpStatus: 200,
@@ -1152,6 +1173,7 @@ let WrappedResponses$1 = class WrappedResponses extends Responses {
             try {
               let finalContent = [];
               let modelFromResponse;
+              let firstTokenTime;
               let usage = {
                 inputTokens: 0,
                 outputTokens: 0,
@@ -1159,6 +1181,10 @@ let WrappedResponses$1 = class WrappedResponses extends Responses {
               };
               let rawUsageData;
               for await (const chunk of stream1) {
+                // Track first token time on content delta events
+                if (firstTokenTime === undefined && isResponseTokenChunk(chunk)) {
+                  firstTokenTime = Date.now();
+                }
                 if ('response' in chunk && chunk.response) {
                   // Extract model from response object in chunk (for stored prompts)
                   if (!modelFromResponse && chunk.response.model) {
@@ -1184,6 +1210,7 @@ let WrappedResponses$1 = class WrappedResponses extends Responses {
                 }
               }
               const latency = (Date.now() - startTime) / 1000;
+              const timeToFirstToken = firstTokenTime !== undefined ? (firstTokenTime - startTime) / 1000 : undefined;
               const availableTools = extractAvailableToolCalls('openai', openAIParams);
               await sendEventToPosthog({
                 client: this.phClient,
@@ -1193,6 +1220,7 @@ let WrappedResponses$1 = class WrappedResponses extends Responses {
                 input: formatOpenAIResponsesInput(sanitizeOpenAIResponse(openAIParams.input), openAIParams.instructions),
                 output: finalContent,
                 latency,
+                timeToFirstToken,
                 baseURL: this.baseURL,
                 params: body,
                 httpStatus: 200,
@@ -1431,12 +1459,17 @@ class WrappedTranscriptions extends Transcriptions {
           (async () => {
             try {
               let finalContent = '';
+              let firstTokenTime;
               let usage = {
                 inputTokens: 0,
                 outputTokens: 0
               };
               const doneEvent = 'transcript.text.done';
               for await (const chunk of stream1) {
+                // Track first token on text delta events
+                if (firstTokenTime === undefined && chunk.type === 'transcript.text.delta') {
+                  firstTokenTime = Date.now();
+                }
                 if (chunk.type === doneEvent && 'text' in chunk && chunk.text && chunk.text.length > 0) {
                   finalContent = chunk.text;
                 }
@@ -1449,6 +1482,7 @@ class WrappedTranscriptions extends Transcriptions {
                 }
               }
               const latency = (Date.now() - startTime) / 1000;
+              const timeToFirstToken = firstTokenTime !== undefined ? (firstTokenTime - startTime) / 1000 : undefined;
               const availableTools = extractAvailableToolCalls('openai', openAIParams);
               await sendEventToPosthog({
                 client: this.phClient,
@@ -1458,6 +1492,7 @@ class WrappedTranscriptions extends Transcriptions {
                 input: openAIParams.prompt,
                 output: finalContent,
                 latency,
+                timeToFirstToken,
                 baseURL: this.baseURL,
                 params: body,
                 httpStatus: 200,
@@ -1576,6 +1611,7 @@ class WrappedCompletions extends openai.AzureOpenAI.Chat.Completions {
               const contentBlocks = [];
               let accumulatedContent = '';
               let modelFromResponse;
+              let firstTokenTime;
               let usage = {
                 inputTokens: 0,
                 outputTokens: 0
@@ -1591,11 +1627,17 @@ class WrappedCompletions extends openai.AzureOpenAI.Chat.Completions {
                 // Handle text content
                 const deltaContent = choice?.delta?.content;
                 if (deltaContent) {
+                  if (firstTokenTime === undefined) {
+                    firstTokenTime = Date.now();
+                  }
                   accumulatedContent += deltaContent;
                 }
                 // Handle tool calls
                 const deltaToolCalls = choice?.delta?.tool_calls;
                 if (deltaToolCalls && Array.isArray(deltaToolCalls)) {
+                  if (firstTokenTime === undefined) {
+                    firstTokenTime = Date.now();
+                  }
                   for (const toolCall of deltaToolCalls) {
                     const index = toolCall.index;
                     if (index !== undefined) {
@@ -1665,6 +1707,7 @@ class WrappedCompletions extends openai.AzureOpenAI.Chat.Completions {
                 }]
               }];
               const latency = (Date.now() - startTime) / 1000;
+              const timeToFirstToken = firstTokenTime !== undefined ? (firstTokenTime - startTime) / 1000 : undefined;
               await sendEventToPosthog({
                 client: this.phClient,
                 ...posthogParams,
@@ -1673,6 +1716,7 @@ class WrappedCompletions extends openai.AzureOpenAI.Chat.Completions {
                 input: sanitizeOpenAI(openAIParams.messages),
                 output: formattedOutput,
                 latency,
+                timeToFirstToken,
                 baseURL: this.baseURL,
                 params: body,
                 httpStatus: 200,
@@ -1774,11 +1818,16 @@ class WrappedResponses extends openai.AzureOpenAI.Responses {
             try {
               let finalContent = [];
               let modelFromResponse;
+              let firstTokenTime;
               let usage = {
                 inputTokens: 0,
                 outputTokens: 0
               };
               for await (const chunk of stream1) {
+                // Track first token time on content delta events
+                if (firstTokenTime === undefined && isResponseTokenChunk(chunk)) {
+                  firstTokenTime = Date.now();
+                }
                 if ('response' in chunk && chunk.response) {
                   // Extract model from response if not in params (for stored prompts)
                   if (!modelFromResponse && chunk.response.model) {
@@ -1798,6 +1847,7 @@ class WrappedResponses extends openai.AzureOpenAI.Responses {
                 }
               }
               const latency = (Date.now() - startTime) / 1000;
+              const timeToFirstToken = firstTokenTime !== undefined ? (firstTokenTime - startTime) / 1000 : undefined;
               await sendEventToPosthog({
                 client: this.phClient,
                 ...posthogParams,
@@ -1806,6 +1856,7 @@ class WrappedResponses extends openai.AzureOpenAI.Responses {
                 input: formatOpenAIResponsesInput(openAIParams.input, openAIParams.instructions),
                 output: finalContent,
                 latency,
+                timeToFirstToken,
                 baseURL: this.baseURL,
                 params: body,
                 httpStatus: 200,
@@ -2375,6 +2426,7 @@ const wrapVercelLanguageModel = (model, phClient, options) => {
     doStream: {
       value: async params => {
         const startTime = Date.now();
+        let firstTokenTime;
         let generatedText = '';
         let reasoningText = '';
         let usage = {};
@@ -2398,13 +2450,22 @@ const wrapVercelLanguageModel = (model, phClient, options) => {
             transform(chunk, controller) {
               // Handle streaming patterns - compatible with both V2 and V3
               if (chunk.type === 'text-delta') {
+                if (firstTokenTime === undefined) {
+                  firstTokenTime = Date.now();
+                }
                 generatedText += chunk.delta;
               }
               if (chunk.type === 'reasoning-delta') {
+                if (firstTokenTime === undefined) {
+                  firstTokenTime = Date.now();
+                }
                 reasoningText += chunk.delta;
               }
               // Handle tool call chunks
               if (chunk.type === 'tool-input-start') {
+                if (firstTokenTime === undefined) {
+                  firstTokenTime = Date.now();
+                }
                 // Initialize a new tool call
                 toolCallsInProgress.set(chunk.id, {
                   toolCallId: chunk.id,
@@ -2423,6 +2484,9 @@ const wrapVercelLanguageModel = (model, phClient, options) => {
                 // Tool call is complete, keep it in the map for final processing
               }
               if (chunk.type === 'tool-call') {
+                if (firstTokenTime === undefined) {
+                  firstTokenTime = Date.now();
+                }
                 // Direct tool call chunk (complete tool call)
                 toolCallsInProgress.set(chunk.toolCallId, {
                   toolCallId: chunk.toolCallId,
@@ -2446,6 +2510,7 @@ const wrapVercelLanguageModel = (model, phClient, options) => {
             },
             flush: async () => {
               const latency = (Date.now() - startTime) / 1000;
+              const timeToFirstToken = firstTokenTime !== undefined ? (firstTokenTime - startTime) / 1000 : undefined;
               // Build content array similar to mapVercelOutput structure
               const content = [];
               if (reasoningText) {
@@ -2498,6 +2563,7 @@ const wrapVercelLanguageModel = (model, phClient, options) => {
                 input: mergedOptions.posthogPrivacyMode ? '' : mapVercelPrompt(params.prompt),
                 output: output,
                 latency,
+                timeToFirstToken,
                 baseURL,
                 params: mergedParams,
                 httpStatus: 200,
@@ -2572,6 +2638,7 @@ class WrappedMessages extends AnthropicOriginal__default.default.Messages {
         const contentBlocks = [];
         const toolsInProgress = new Map();
         let currentTextBlock = null;
+        let firstTokenTime;
         const usage = {
           inputTokens: 0,
           outputTokens: 0,
@@ -2594,6 +2661,9 @@ class WrappedMessages extends AnthropicOriginal__default.default.Messages {
                     };
                     contentBlocks.push(currentTextBlock);
                   } else if (chunk.content_block?.type === 'tool_use') {
+                    if (firstTokenTime === undefined) {
+                      firstTokenTime = Date.now();
+                    }
                     const toolBlock = {
                       type: 'function',
                       id: chunk.content_block.id,
@@ -2614,6 +2684,9 @@ class WrappedMessages extends AnthropicOriginal__default.default.Messages {
                 if ('delta' in chunk) {
                   if ('text' in chunk.delta) {
                     const delta = chunk.delta.text;
+                    if (firstTokenTime === undefined) {
+                      firstTokenTime = Date.now();
+                    }
                     accumulatedContent += delta;
                     if (currentTextBlock) {
                       currentTextBlock.text += delta;
@@ -2669,6 +2742,7 @@ class WrappedMessages extends AnthropicOriginal__default.default.Messages {
               }
               usage.rawUsage = lastRawUsage;
               const latency = (Date.now() - startTime) / 1000;
+              const timeToFirstToken = firstTokenTime !== undefined ? (firstTokenTime - startTime) / 1000 : undefined;
               const availableTools = extractAvailableToolCalls('anthropic', anthropicParams);
               // Format output to match non-streaming version
               const formattedOutput = contentBlocks.length > 0 ? [{
@@ -2689,6 +2763,7 @@ class WrappedMessages extends AnthropicOriginal__default.default.Messages {
                 input: sanitizeAnthropic(mergeSystemPrompt(anthropicParams, 'anthropic')),
                 output: formattedOutput,
                 latency,
+                timeToFirstToken,
                 baseURL: this.baseURL,
                 params: body,
                 httpStatus: 200,
@@ -2850,6 +2925,7 @@ class WrappedModels {
     } = extractPosthogParams(params);
     const startTime = Date.now();
     const accumulatedContent = [];
+    let firstTokenTime;
     let usage = {
       inputTokens: 0,
       outputTokens: 0,
@@ -2859,6 +2935,10 @@ class WrappedModels {
     try {
       const stream = await this.client.models.generateContentStream(geminiParams);
       for await (const chunk of stream) {
+        // Track first token time when we get text content
+        if (firstTokenTime === undefined && chunk.text) {
+          firstTokenTime = Date.now();
+        }
         const chunkWebSearchCount = calculateGoogleWebSearchCount(chunk);
         if (chunkWebSearchCount > 0 && chunkWebSearchCount > (usage.webSearchCount ?? 0)) {
           usage.webSearchCount = chunkWebSearchCount;
@@ -2889,6 +2969,9 @@ class WrappedModels {
               for (const part of candidate.content.parts) {
                 // Type-safe check for functionCall
                 if ('functionCall' in part) {
+                  if (firstTokenTime === undefined) {
+                    firstTokenTime = Date.now();
+                  }
                   const funcCall = part.functionCall;
                   if (funcCall?.name) {
                     accumulatedContent.push({
@@ -2919,6 +3002,7 @@ class WrappedModels {
         yield chunk;
       }
       const latency = (Date.now() - startTime) / 1000;
+      const timeToFirstToken = firstTokenTime !== undefined ? (firstTokenTime - startTime) / 1000 : undefined;
       const availableTools = extractAvailableToolCalls('gemini', geminiParams);
       // Format output similar to formatResponseGemini
       const output = accumulatedContent.length > 0 ? [{
@@ -2933,6 +3017,7 @@ class WrappedModels {
         input: this.formatInputForPostHog(geminiParams),
         output,
         latency,
+        timeToFirstToken,
         baseURL: 'https://generativelanguage.googleapis.com',
         params: params,
         httpStatus: 200,
@@ -4286,10 +4371,163 @@ class LangChainCallbackHandler extends BaseCallbackHandler {
   }
 }
 
+/// <reference lib="dom" />
+const DEFAULT_CACHE_TTL_SECONDS = 300; // 5 minutes
+function isPromptApiResponse(data) {
+  return typeof data === 'object' && data !== null && 'prompt' in data && typeof data.prompt === 'string';
+}
+function isPromptsWithPostHog(options) {
+  return 'posthog' in options;
+}
+/**
+ * Prompts class for fetching and compiling LLM prompts from PostHog
+ *
+ * @example
+ * ```ts
+ * // With PostHog client
+ * const prompts = new Prompts({ posthog })
+ *
+ * // Or with direct options (no PostHog client needed)
+ * const prompts = new Prompts({
+ *   personalApiKey: 'phx_xxx',
+ *   host: 'https://us.i.posthog.com',
+ * })
+ *
+ * // Fetch with caching and fallback
+ * const template = await prompts.get('support-system-prompt', {
+ *   cacheTtlSeconds: 300,
+ *   fallback: 'You are a helpful assistant.',
+ * })
+ *
+ * // Compile with variables
+ * const systemPrompt = prompts.compile(template, {
+ *   company: 'Acme Corp',
+ *   tier: 'premium',
+ * })
+ * ```
+ */
+class Prompts {
+  constructor(options) {
+    this.cache = new Map();
+    this.defaultCacheTtlSeconds = options.defaultCacheTtlSeconds ?? DEFAULT_CACHE_TTL_SECONDS;
+    if (isPromptsWithPostHog(options)) {
+      this.personalApiKey = options.posthog.options.personalApiKey ?? '';
+      this.host = options.posthog.host;
+    } else {
+      // Direct options
+      this.personalApiKey = options.personalApiKey;
+      this.host = options.host ?? 'https://us.i.posthog.com';
+    }
+  }
+  /**
+   * Fetch a prompt by name from the PostHog API
+   *
+   * @param name - The name of the prompt to fetch
+   * @param options - Optional settings for caching and fallback
+   * @returns The prompt string
+   * @throws Error if the prompt cannot be fetched and no fallback is provided
+   */
+  async get(name, options) {
+    const cacheTtlSeconds = options?.cacheTtlSeconds ?? this.defaultCacheTtlSeconds;
+    const fallback = options?.fallback;
+    // Check cache first
+    const cached = this.cache.get(name);
+    const now = Date.now();
+    if (cached) {
+      const isFresh = now - cached.fetchedAt < cacheTtlSeconds * 1000;
+      if (isFresh) {
+        return cached.prompt;
+      }
+    }
+    // Try to fetch from API
+    try {
+      const prompt = await this.fetchPromptFromApi(name);
+      const fetchedAt = Date.now();
+      // Update cache
+      this.cache.set(name, {
+        prompt,
+        fetchedAt
+      });
+      return prompt;
+    } catch (error) {
+      // Fallback order:
+      // 1. Return stale cache (with warning)
+      if (cached) {
+        console.warn(`[PostHog Prompts] Failed to fetch prompt "${name}", using stale cache:`, error);
+        return cached.prompt;
+      }
+      // 2. Return fallback (with warning)
+      if (fallback !== undefined) {
+        console.warn(`[PostHog Prompts] Failed to fetch prompt "${name}", using fallback:`, error);
+        return fallback;
+      }
+      // 3. Throw error
+      throw error;
+    }
+  }
+  /**
+   * Compile a prompt template with variable substitution
+   *
+   * Variables in the format `{{variableName}}` will be replaced with values from the variables object.
+   * Unmatched variables are left unchanged.
+   *
+   * @param prompt - The prompt template string
+   * @param variables - Object containing variable values
+   * @returns The compiled prompt string
+   */
+  compile(prompt, variables) {
+    return prompt.replace(/\{\{([\w.-]+)\}\}/g, (match, variableName) => {
+      if (variableName in variables) {
+        return String(variables[variableName]);
+      }
+      return match;
+    });
+  }
+  /**
+   * Clear the cache for a specific prompt or all prompts
+   *
+   * @param name - Optional prompt name to clear. If not provided, clears all cached prompts.
+   */
+  clearCache(name) {
+    if (name !== undefined) {
+      this.cache.delete(name);
+    } else {
+      this.cache.clear();
+    }
+  }
+  async fetchPromptFromApi(name) {
+    if (!this.personalApiKey) {
+      throw new Error('[PostHog Prompts] personalApiKey is required to fetch prompts. ' + 'Please provide it when initializing the Prompts instance.');
+    }
+    const url = `${this.host}/api/projects/@current/llm_prompts/name/${encodeURIComponent(name)}/`;
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${this.personalApiKey}`
+      }
+    });
+    if (!response.ok) {
+      if (response.status === 404) {
+        throw new Error(`[PostHog Prompts] Prompt "${name}" not found`);
+      }
+      if (response.status === 403) {
+        throw new Error(`[PostHog Prompts] Access denied for prompt "${name}". ` + 'Check that your personalApiKey has the correct permissions and the LLM prompts feature is enabled.');
+      }
+      throw new Error(`[PostHog Prompts] Failed to fetch prompt "${name}": HTTP ${response.status}`);
+    }
+    const data = await response.json();
+    if (!isPromptApiResponse(data)) {
+      throw new Error(`[PostHog Prompts] Invalid response format for prompt "${name}"`);
+    }
+    return data.prompt;
+  }
+}
+
 exports.Anthropic = PostHogAnthropic;
 exports.AzureOpenAI = PostHogAzureOpenAI;
 exports.GoogleGenAI = PostHogGoogleGenAI;
 exports.LangChainCallbackHandler = LangChainCallbackHandler;
 exports.OpenAI = PostHogOpenAI;
+exports.Prompts = Prompts;
 exports.withTracing = wrapVercelLanguageModel;
 //# sourceMappingURL=index.cjs.map