@posthog/ai 7.9.5 → 7.10.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,13 @@ declare class Prompts {
     private defaultCacheTtlSeconds;
     private cache;
     constructor(options: PromptsOptions);
+    private getCacheKey;
+    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,7 +428,7 @@ 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.
      */
     clearCache(name?: string): 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.10.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,28 @@ class Prompts {
       this.host = options.host ?? 'https://us.posthog.com';
     }
   }
+  getCacheKey(name, version) {
+    return version === undefined ? `${name}::latest` : `${name}::version:${version}`;
+  }
+  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 cacheKey = this.getCacheKey(name, version);
+    const promptLabel = this.getPromptLabel(name, version);
     // Check cache first
-    const cached = this.cache.get(name);
+    const cached = this.cache.get(cacheKey);
     const now = Date.now();
     if (cached) {
       const isFresh = now - cached.fetchedAt < cacheTtlSeconds * 1000;
@@ -5206,10 +5220,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.cache.set(cacheKey, {
         prompt,
         fetchedAt
       });
@@ -5218,12 +5232,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 +5265,26 @@ 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.
    */
   clearCache(name) {
     if (name !== undefined) {
-      this.cache.delete(name);
+      const latestKey = this.getCacheKey(name);
+      const versionPrefix = `${name}::version:`;
+      for (const key of this.cache.keys()) {
+        if (key === latestKey) {
+          this.cache.delete(key);
+          continue;
+        }
+        if (key.startsWith(versionPrefix) && /^\d+$/.test(key.slice(versionPrefix.length))) {
+          this.cache.delete(key);
+        }
+      }
     } else {
       this.cache.clear();
     }
   }
-  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 +5293,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 +5304,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;
   }