@posthog/ai 7.14.0 → 7.16.0

package/dist/index.d.ts

@@ -22,7 +22,42 @@ interface GetPromptOptions {
     cacheTtlSeconds?: number;
     fallback?: string;
     version?: number;
+    /**
+     * When true, returns a `PromptResult` object with metadata (source, name, version)
+     * instead of a plain string.
+     *
+     * Omitting this option or setting it to false is deprecated and will be removed
+     * in a future major version.
+     */
+    withMetadata?: boolean;
+}
+/**
+ * Result from the Prompts API or local cache — carries real metadata.
+ */
+interface PromptRemoteResult {
+    source: 'api' | 'cache' | 'stale_cache';
+    prompt: string;
+    name: string;
+    version: number;
 }
+/**
+ * Result when the fetch failed and no cache was available — fell back to the
+ * hardcoded fallback string. name and version are undefined so they remain
+ * accessible on the PromptResult union without a type guard.
+ */
+interface PromptCodeFallbackResult {
+    source: 'code_fallback';
+    prompt: string;
+    name: undefined;
+    version: undefined;
+}
+/**
+ * Discriminated union returned by `Prompts.get()` when `withMetadata: true`.
+ *
+ * Narrow on `source` to guarantee metadata, or access `result.name` /
+ * `result.version` directly as `string | undefined` / `number | undefined`.
+ */
+type PromptResult = PromptRemoteResult | PromptCodeFallbackResult;
 /**
  * Variables for prompt compilation
  */
@@ -340,19 +375,28 @@ declare class Prompts {
     private host;
     private defaultCacheTtlSeconds;
     private cache;
+    private hasWarnedDeprecation;
     constructor(options: PromptsOptions);
     private getPromptCache;
     private getOrCreatePromptCache;
     private getPromptLabel;
     /**
-     * Fetch a prompt by name from the PostHog API
+     * Fetch a prompt by name from the PostHog API.
      *
-     * @param name - The name of the prompt to fetch
-     * @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
+     * When `withMetadata` is `true`, returns a `PromptResult` object with `source`,
+     * `name`, and `version` metadata. When omitted or `false`, returns a plain string
+     * (deprecated — will be removed in a future major version).
      */
+    get(name: string, options: GetPromptOptions & {
+        withMetadata: true;
+    }): Promise<PromptResult>;
+    /** @deprecated Omitting `withMetadata` is deprecated. Pass `{ withMetadata: true }` to receive a `PromptResult`. */
     get(name: string, options?: GetPromptOptions): Promise<string>;
+    /**
+     * Internal method that handles cache + fetch logic, returning full metadata.
+     * Does NOT handle the string `fallback` option — callers handle that.
+     */
+    private getInternal;
     /**
      * Compile a prompt template with variable substitution
      *
@@ -374,4 +418,4 @@ declare class Prompts {
     private fetchPromptFromApi;
 }
 
-export { PostHogAnthropic as Anthropic, PostHogAzureOpenAI as AzureOpenAI, PostHogGoogleGenAI as GoogleGenAI, LangChainCallbackHandler, PostHogOpenAI as OpenAI, Prompts, wrapVercelLanguageModel as withTracing };
+export { PostHogAnthropic as Anthropic, PostHogAzureOpenAI as AzureOpenAI, PostHogGoogleGenAI as GoogleGenAI, LangChainCallbackHandler, PostHogOpenAI as OpenAI, type PromptCodeFallbackResult, type PromptRemoteResult, type PromptResult, Prompts, wrapVercelLanguageModel as withTracing };

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.14.0";
+var version = "7.16.0";
 
 // Type guards for safer type checking
 const isString = value => {
@@ -4437,7 +4437,11 @@ 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';
+  if (typeof data !== 'object' || data === null) {
+    return false;
+  }
+  const record = data;
+  return typeof record.prompt === 'string' && typeof record.name === 'string' && typeof record.version === 'number';
 }
 function isPromptsWithPostHog(options) {
   return 'posthog' in options;
@@ -4478,6 +4482,7 @@ function isPromptsWithPostHog(options) {
 class Prompts {
   constructor(options) {
     this.cache = new Map();
+    this.hasWarnedDeprecation = false;
     this.defaultCacheTtlSeconds = options.defaultCacheTtlSeconds ?? DEFAULT_CACHE_TTL_SECONDS;
     if (isPromptsWithPostHog(options)) {
       this.personalApiKey = options.posthog.options.personalApiKey ?? '';
@@ -4505,17 +4510,42 @@ class Prompts {
   getPromptLabel(name, version) {
     return version === undefined ? `"${name}"` : `"${name}" version ${version}`;
   }
+  async get(name, options) {
+    const withMetadata = options?.withMetadata;
+    if (withMetadata === undefined && !this.hasWarnedDeprecation) {
+      this.hasWarnedDeprecation = true;
+      console.warn('[PostHog Prompts] Calling get() without { withMetadata: true } is deprecated and will be ' + 'removed in a future major version. Pass { withMetadata: true } to receive a PromptResult ' + 'object with source, name, and version metadata. ' + 'You can pass { withMetadata: false } to silence this warning, but the plain-string return ' + 'will still be removed in the next major version.');
+    }
+    try {
+      const result = await this.getInternal(name, options);
+      if (withMetadata) {
+        return result;
+      }
+      return result.prompt;
+    } catch (error) {
+      const fallback = options?.fallback;
+      if (fallback !== undefined) {
+        const promptLabel = this.getPromptLabel(name, options?.version);
+        console.warn(`[PostHog Prompts] Failed to fetch prompt ${promptLabel}, using fallback:`, error);
+        if (withMetadata) {
+          return {
+            source: 'code_fallback',
+            prompt: fallback,
+            name: undefined,
+            version: undefined
+          };
+        }
+        return fallback;
+      }
+      throw error;
+    }
+  }
   /**
-   * Fetch a prompt by name from the PostHog API
-   *
-   * @param name - The name of the prompt to fetch
-   * @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
+   * Internal method that handles cache + fetch logic, returning full metadata.
+   * Does NOT handle the string `fallback` option — callers handle that.
    */
-  async get(name, options) {
+  async getInternal(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
@@ -4524,32 +4554,41 @@ class Prompts {
     if (cached) {
       const isFresh = now - cached.fetchedAt < cacheTtlSeconds * 1000;
       if (isFresh) {
-        return cached.prompt;
+        const {
+          fetchedAt: _,
+          ...cachedResult
+        } = cached;
+        return {
+          source: 'cache',
+          ...cachedResult
+        };
       }
     }
     // Try to fetch from API
     try {
-      const prompt = await this.fetchPromptFromApi(name, version);
-      const fetchedAt = Date.now();
+      const fetched = await this.fetchPromptFromApi(name, version);
       // Update cache
       this.getOrCreatePromptCache(name).set(version, {
-        prompt,
-        fetchedAt
+        ...fetched,
+        fetchedAt: Date.now()
       });
-      return prompt;
+      return {
+        source: 'api',
+        ...fetched
+      };
     } catch (error) {
-      // Fallback order:
-      // 1. Return stale cache (with warning)
+      // Return stale cache (with warning)
       if (cached) {
+        const {
+          fetchedAt: _,
+          ...cachedResult
+        } = cached;
         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 ${promptLabel}, using fallback:`, error);
-        return fallback;
+        return {
+          source: 'stale_cache',
+          ...cachedResult
+        };
       }
-      // 3. Throw error
       throw error;
     }
   }
@@ -4626,7 +4665,11 @@ class Prompts {
     if (!isPromptApiResponse(data)) {
       throw new Error(`[PostHog Prompts] Invalid response format for prompt ${promptLabel}`);
     }
-    return data.prompt;
+    return {
+      prompt: data.prompt,
+      name: data.name,
+      version: data.version
+    };
   }
 }