@posthog/ai 7.9.5 → 7.11.0

package/dist/index.d.ts

@@ -23,6 +23,7 @@ import { BaseMessage } from '@langchain/core/messages';
 interface GetPromptOptions {
     cacheTtlSeconds?: number;
     fallback?: string;
+    version?: number;
 }
 /**
  * Variables for prompt compilation
@@ -383,6 +384,11 @@ type PromptsOptions = PromptsWithPostHogOptions | PromptsDirectOptions;
  *   fallback: 'You are a helpful assistant.',
  * })
  *
+ * // Or fetch an exact published version
+ * const v3Template = await prompts.get('support-system-prompt', {
+ *   version: 3,
+ * })
+ *
  * // Compile with variables
  * const systemPrompt = prompts.compile(template, {
  *   company: 'Acme Corp',
@@ -397,11 +403,14 @@ declare class Prompts {
     private defaultCacheTtlSeconds;
     private cache;
     constructor(options: PromptsOptions);
+    private getPromptCache;
+    private getOrCreatePromptCache;
+    private getPromptLabel;
     /**
      * 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
+     * @param options - Optional settings for caching, fallback, and exact version selection
      * @returns The prompt string
      * @throws Error if the prompt cannot be fetched and no fallback is provided
      */
@@ -420,9 +429,10 @@ declare class Prompts {
     /**
      * Clear the cache for a specific prompt or all prompts
      *
-     * @param name - Optional prompt name to clear. If not provided, clears all cached prompts.
+     * @param name - Optional prompt name to clear. If provided, clears all cached versions for that prompt unless a version is also provided.
+     * @param version - Optional prompt version to clear. Requires a prompt name.
      */
-    clearCache(name?: string): void;
+    clearCache(name?: string, version?: number): void;
     private fetchPromptFromApi;
 }
 

package/dist/index.mjs

@@ -5,7 +5,7 @@ import { uuidv7 } from '@posthog/core';
 import AnthropicOriginal from '@anthropic-ai/sdk';
 import { GoogleGenAI } from '@google/genai';
 
-var version = "7.9.5";
+var version = "7.11.0";
 
 // Type guards for safer type checking
 const isString = value => {
@@ -5162,6 +5162,11 @@ function isPromptsWithPostHog(options) {
  *   fallback: 'You are a helpful assistant.',
  * })
  *
+ * // Or fetch an exact published version
+ * const v3Template = await prompts.get('support-system-prompt', {
+ *   version: 3,
+ * })
+ *
  * // Compile with variables
  * const systemPrompt = prompts.compile(template, {
  *   company: 'Acme Corp',
@@ -5184,19 +5189,36 @@ class Prompts {
       this.host = options.host ?? 'https://us.posthog.com';
     }
   }
+  getPromptCache(name) {
+    return this.cache.get(name);
+  }
+  getOrCreatePromptCache(name) {
+    const cachedPromptVersions = this.cache.get(name);
+    if (cachedPromptVersions) {
+      return cachedPromptVersions;
+    }
+    const promptVersions = new Map();
+    this.cache.set(name, promptVersions);
+    return promptVersions;
+  }
+  getPromptLabel(name, version) {
+    return version === undefined ? `"${name}"` : `"${name}" version ${version}`;
+  }
   /**
    * 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
+   * @param options - Optional settings for caching, fallback, and exact version selection
    * @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;
+    const version = options?.version;
+    const promptLabel = this.getPromptLabel(name, version);
     // Check cache first
-    const cached = this.cache.get(name);
+    const cached = this.getPromptCache(name)?.get(version);
     const now = Date.now();
     if (cached) {
       const isFresh = now - cached.fetchedAt < cacheTtlSeconds * 1000;
@@ -5206,10 +5228,10 @@ class Prompts {
     }
     // Try to fetch from API
     try {
-      const prompt = await this.fetchPromptFromApi(name);
+      const prompt = await this.fetchPromptFromApi(name, version);
       const fetchedAt = Date.now();
       // Update cache
-      this.cache.set(name, {
+      this.getOrCreatePromptCache(name).set(version, {
         prompt,
         fetchedAt
       });
@@ -5218,12 +5240,12 @@ class Prompts {
       // Fallback order:
       // 1. Return stale cache (with warning)
       if (cached) {
-        console.warn(`[PostHog Prompts] Failed to fetch prompt "${name}", using stale cache:`, error);
+        console.warn(`[PostHog Prompts] Failed to fetch prompt ${promptLabel}, 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);
+        console.warn(`[PostHog Prompts] Failed to fetch prompt ${promptLabel}, using fallback:`, error);
         return fallback;
       }
       // 3. Throw error
@@ -5251,16 +5273,28 @@ class Prompts {
   /**
    * Clear the cache for a specific prompt or all prompts
    *
-   * @param name - Optional prompt name to clear. If not provided, clears all cached prompts.
+   * @param name - Optional prompt name to clear. If provided, clears all cached versions for that prompt unless a version is also provided.
+   * @param version - Optional prompt version to clear. Requires a prompt name.
    */
-  clearCache(name) {
-    if (name !== undefined) {
-      this.cache.delete(name);
-    } else {
+  clearCache(name, version) {
+    if (version !== undefined && name === undefined) {
+      throw new Error("'version' requires 'name' to be provided");
+    }
+    if (name === undefined) {
       this.cache.clear();
+      return;
+    }
+    if (version === undefined) {
+      this.cache.delete(name);
+      return;
+    }
+    const promptVersions = this.getPromptCache(name);
+    promptVersions?.delete(version);
+    if (promptVersions?.size === 0) {
+      this.cache.delete(name);
     }
   }
-  async fetchPromptFromApi(name) {
+  async fetchPromptFromApi(name, version) {
     if (!this.personalApiKey) {
       throw new Error('[PostHog Prompts] personalApiKey is required to fetch prompts. ' + 'Please provide it when initializing the Prompts instance.');
     }
@@ -5269,7 +5303,9 @@ class Prompts {
     }
     const encodedPromptName = encodeURIComponent(name);
     const encodedProjectApiKey = encodeURIComponent(this.projectApiKey);
-    const url = `${this.host}/api/environments/@current/llm_prompts/name/${encodedPromptName}/?token=${encodedProjectApiKey}`;
+    const versionQuery = version === undefined ? '' : `&version=${encodeURIComponent(String(version))}`;
+    const promptLabel = this.getPromptLabel(name, version);
+    const url = `${this.host}/api/environments/@current/llm_prompts/name/${encodedPromptName}/?token=${encodedProjectApiKey}${versionQuery}`;
     const response = await fetch(url, {
       method: 'GET',
       headers: {
@@ -5278,16 +5314,16 @@ class Prompts {
     });
     if (!response.ok) {
       if (response.status === 404) {
-        throw new Error(`[PostHog Prompts] Prompt "${name}" not found`);
+        throw new Error(`[PostHog Prompts] Prompt ${promptLabel} 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] Access denied for prompt ${promptLabel}. ` + '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}`);
+      throw new Error(`[PostHog Prompts] Failed to fetch prompt ${promptLabel}: HTTP ${response.status}`);
     }
     const data = await response.json();
     if (!isPromptApiResponse(data)) {
-      throw new Error(`[PostHog Prompts] Invalid response format for prompt "${name}"`);
+      throw new Error(`[PostHog Prompts] Invalid response format for prompt ${promptLabel}`);
     }
     return data.prompt;
   }