@posthog/ai 7.6.1 → 7.7.0

package/dist/index.d.ts

@@ -15,6 +15,26 @@ import { AgentAction, AgentFinish } from '@langchain/core/agents';
 import { DocumentInterface } from '@langchain/core/documents';
 import { BaseMessage } from '@langchain/core/messages';
 
+/**
+ * Options for fetching a prompt
+ */
+interface GetPromptOptions {
+    cacheTtlSeconds?: number;
+    fallback?: string;
+}
+/**
+ * Variables for prompt compilation
+ */
+type PromptVariables = Record<string, string | number | boolean>;
+/**
+ * Direct options for initializing Prompts without a PostHog client
+ */
+interface PromptsDirectOptions {
+    personalApiKey: string;
+    host?: string;
+    defaultCacheTtlSeconds?: number;
+}
+
 interface MonitoringEventPropertiesWithDefaults {
     distinctId?: string;
     traceId: string;
@@ -272,4 +292,71 @@ declare class LangChainCallbackHandler extends BaseCallbackHandler {
     private parseUsage;
 }
 
-export { PostHogAnthropic as Anthropic, PostHogAzureOpenAI as AzureOpenAI, PostHogGoogleGenAI as GoogleGenAI, LangChainCallbackHandler, PostHogOpenAI as OpenAI, wrapVercelLanguageModel as withTracing };
+interface PromptsWithPostHogOptions {
+    posthog: PostHog;
+    defaultCacheTtlSeconds?: number;
+}
+type PromptsOptions = PromptsWithPostHogOptions | PromptsDirectOptions;
+/**
+ * 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',
+ * })
+ * ```
+ */
+declare class Prompts {
+    private personalApiKey;
+    private host;
+    private defaultCacheTtlSeconds;
+    private cache;
+    constructor(options: PromptsOptions);
+    /**
+     * 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
+     */
+    get(name: string, options?: GetPromptOptions): Promise<string>;
+    /**
+     * 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: string, variables: PromptVariables): string;
+    /**
+     * 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?: string): void;
+    private fetchPromptFromApi;
+}
+
+export { PostHogAnthropic as Anthropic, PostHogAzureOpenAI as AzureOpenAI, PostHogGoogleGenAI as GoogleGenAI, LangChainCallbackHandler, PostHogOpenAI as OpenAI, Prompts, wrapVercelLanguageModel as withTracing };

package/dist/index.mjs

@@ -6,7 +6,7 @@ import { uuidv7 } from '@posthog/core';
 import AnthropicOriginal from '@anthropic-ai/sdk';
 import { GoogleGenAI } from '@google/genai';
 
-var version = "7.6.1";
+var version = "7.7.0";
 
 // Type guards for safer type checking
 const isString = value => {
@@ -4262,5 +4262,157 @@ class LangChainCallbackHandler extends BaseCallbackHandler {
   }
 }
 
-export { PostHogAnthropic as Anthropic, PostHogAzureOpenAI as AzureOpenAI, PostHogGoogleGenAI as GoogleGenAI, LangChainCallbackHandler, PostHogOpenAI as OpenAI, wrapVercelLanguageModel as withTracing };
+/// <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;
+  }
+}
+
+export { PostHogAnthropic as Anthropic, PostHogAzureOpenAI as AzureOpenAI, PostHogGoogleGenAI as GoogleGenAI, LangChainCallbackHandler, PostHogOpenAI as OpenAI, Prompts, wrapVercelLanguageModel as withTracing };
 //# sourceMappingURL=index.mjs.map