@posthog/ai 8.10.4 → 8.11.0

package/dist/index.d.ts

@@ -151,6 +151,9 @@ type PromptsOptions = PromptsWithPostHogOptions | PromptsDirectOptions;
  *   label: 'production',
  * })
  *
+ * // Or fetch all prompts at a label in one request and warm the cache
+ * const prodPrompts = await prompts.getAll({ label: 'production' })
+ *
  * // Compile with variables
  * const systemPrompt = prompts.compile(result.prompt, {
  *   company: 'Acme Corp',
@@ -177,6 +180,25 @@ declare class Prompts {
    * configuration stored with the version.
    */
   get(name: string, options?: GetPromptOptions): Promise<PromptResult>;
+  /**
+   * Fetch every prompt that carries a label, in one batch.
+   *
+   * Returns an object mapping prompt name to `PromptRemoteResult`, with each
+   * prompt at the version the label points to. Prompts without the label are
+   * not included.
+   *
+   * Each fetched prompt is stored in the cache, so later
+   * `get(name, { label })` calls are served from cache within the TTL. An app
+   * with many prompts can call this once per cache cycle instead of making one
+   * `get()` request per prompt.
+   *
+   * Throws if the request fails, or if the server does not support fetching
+   * prompts by label on the list endpoint (PostHog releases from before
+   * September 2026).
+   */
+  getAll(options: {
+    label: string;
+  }): Promise<Record<string, PromptRemoteResult>>;
   /**
    * Internal method that handles cache + fetch logic, returning full metadata.
    * Does NOT handle the string `fallback` option — callers handle that.
@@ -201,6 +223,12 @@ declare class Prompts {
    * @param version - Optional prompt version to clear. Requires a prompt name.
    */
   clearCache(name?: string, version?: number): void;
+  private requireCredentials;
+  /**
+   * Fetch all prompts at a label from the paginated list endpoint.
+   * Follows pagination links until the last page and returns the raw rows.
+   */
+  private fetchPromptListFromApi;
   private fetchPromptFromApi;
 }
 //#endregion

package/dist/index.mjs

@@ -391,7 +391,7 @@ function sanitizeValues(obj) {
 }
 //#endregion
 //#region package.json
-var version = "8.10.4";
+var version = "8.11.0";
 //#endregion
 //#region src/serializeError.ts
 const DEFAULT_MAX_DEPTH = 3;
@@ -1083,6 +1083,7 @@ const wrapVercelLanguageModel = (model, phClient, options) => {
 //#region src/prompts.ts
 const DEFAULT_CACHE_TTL_SECONDS = 300;
 const DEFAULT_PROMPTS_HOST = "https://us.posthog.com";
+const MAX_PROMPT_LIST_PAGES = 100;
 const DEFAULT_REFETCH_COOLDOWN_SECONDS = 60;
 const MAX_REFETCH_COOLDOWN_SECONDS = 3600;
 function normalizeApiKey(value) {
@@ -1120,6 +1121,31 @@ function isPromptApiResponse(data) {
 	const record = data;
 	return typeof record.prompt === "string" && typeof record.name === "string" && typeof record.version === "number" && (record.label === void 0 || typeof record.label === "string");
 }
+function isSameOrigin(url, host) {
+	try {
+		return new URL(url).origin === new URL(host).origin;
+	} catch {
+		return false;
+	}
+}
+/**
+* Classify how a list row relates to the requested label, via its all_labels
+* field.
+*
+* 'resolved': the row is the version the label points to.
+* 'moved': the prompt carries the label, but on another version. Happens when
+* the label moves between the query and the response.
+* 'absent': the prompt does not carry the label at any version. A server that
+* filters by label never returns such a row, so this means the server ignored
+* the label param (an older PostHog release) and served latest versions.
+*/
+function rowLabelState(row, label) {
+	const allLabels = row.all_labels;
+	if (!Array.isArray(allLabels)) return "absent";
+	const entry = allLabels.find((candidate) => typeof candidate === "object" && candidate !== null && candidate.name === label);
+	if (entry === void 0) return "absent";
+	return entry.version === row.version ? "resolved" : "moved";
+}
 function isPromptsWithPostHog(options) {
 	return "posthog" in options;
 }
@@ -1154,6 +1180,9 @@ function isPromptsWithPostHog(options) {
 *   label: 'production',
 * })
 *
+* // Or fetch all prompts at a label in one request and warm the cache
+* const prodPrompts = await prompts.getAll({ label: 'production' })
+*
 * // Compile with variables
 * const systemPrompt = prompts.compile(result.prompt, {
 *   company: 'Acme Corp',
@@ -1220,6 +1249,61 @@ var Prompts = class {
 		}
 	}
 	/**
+	* Fetch every prompt that carries a label, in one batch.
+	*
+	* Returns an object mapping prompt name to `PromptRemoteResult`, with each
+	* prompt at the version the label points to. Prompts without the label are
+	* not included.
+	*
+	* Each fetched prompt is stored in the cache, so later
+	* `get(name, { label })` calls are served from cache within the TTL. An app
+	* with many prompts can call this once per cache cycle instead of making one
+	* `get()` request per prompt.
+	*
+	* Throws if the request fails, or if the server does not support fetching
+	* prompts by label on the list endpoint (PostHog releases from before
+	* September 2026).
+	*/
+	async getAll(options) {
+		const label = options.label;
+		const rows = await this.fetchPromptListFromApi(label);
+		const resolvedRows = [];
+		const skipped = [];
+		for (const row of rows) {
+			if (!isPromptApiResponse(row)) throw new Error(`[PostHog Prompts] Invalid response format for prompts with label "${label}"`);
+			const labelState = rowLabelState(row, label);
+			if (labelState === "absent") throw new Error(`[PostHog Prompts] The server returned a prompt that does not carry label "${label}". It may not support fetching prompts by label on the list endpoint yet. Upgrade PostHog, or fetch prompts one by one with get().`);
+			if (labelState === "moved") {
+				skipped.push(row.name);
+				continue;
+			}
+			resolvedRows.push(row);
+		}
+		const now = Date.now();
+		const results = /* @__PURE__ */ new Map();
+		for (const row of resolvedRows) {
+			const config = extractConfig(row.config);
+			this.getOrCreatePromptCache(row.name).set(label, {
+				prompt: row.prompt,
+				name: row.name,
+				version: row.version,
+				label,
+				config,
+				fetchedAt: now
+			});
+			results.set(row.name, {
+				source: "api",
+				prompt: row.prompt,
+				name: row.name,
+				version: row.version,
+				label,
+				config: cloneConfig(config)
+			});
+		}
+		if (skipped.length > 0) console.warn(`[PostHog Prompts] Skipped ${skipped.length} prompt(s) that did not resolve label "${label}": ${skipped.join(", ")}`);
+		return Object.fromEntries(results);
+	}
+	/**
 	* Internal method that handles cache + fetch logic, returning full metadata.
 	* Does NOT handle the string `fallback` option — callers handle that.
 	*/
@@ -1309,9 +1393,43 @@ var Prompts = class {
 		promptVersions?.delete(version);
 		if (promptVersions?.size === 0) this.cache.delete(name);
 	}
-	async fetchPromptFromApi(name, version, label) {
+	requireCredentials() {
 		if (!this.personalApiKey) throw new Error("[PostHog Prompts] personalApiKey is required to fetch prompts. Please provide it when initializing the Prompts instance.");
 		if (!this.projectApiKey) throw new Error("[PostHog Prompts] projectApiKey is required to fetch prompts. Please provide it when initializing the Prompts instance.");
+	}
+	/**
+	* Fetch all prompts at a label from the paginated list endpoint.
+	* Follows pagination links until the last page and returns the raw rows.
+	*/
+	async fetchPromptListFromApi(label) {
+		this.requireCredentials();
+		const query = `token=${encodeURIComponent(this.projectApiKey)}&label=${encodeURIComponent(label)}&content=full`;
+		let url = `${this.host}/api/environments/@current/llm_prompts/?${query}`;
+		const reference = `prompts with label "${label}"`;
+		const rows = [];
+		let pages = 0;
+		while (url !== void 0) {
+			if (pages >= MAX_PROMPT_LIST_PAGES) throw new Error(`[PostHog Prompts] ${reference} spans more than ${MAX_PROMPT_LIST_PAGES} pages. Refusing to return an incomplete result.`);
+			const response = await fetch(url, {
+				method: "GET",
+				headers: { Authorization: `Bearer ${this.personalApiKey}` }
+			});
+			if (!response.ok) {
+				if (response.status === 403) throw new Error(`[PostHog Prompts] Access denied for ${reference}. Check that your personalApiKey has the correct permissions and the LLM prompts feature is enabled.`);
+				throw new PromptFetchError(`[PostHog Prompts] Failed to fetch ${reference}: HTTP ${response.status}`, response.status === 429 ? parseRetryAfterSeconds(response.headers?.get("Retry-After")) : void 0);
+			}
+			const data = await response.json();
+			if (typeof data !== "object" || data === null || !Array.isArray(data.results)) throw new Error(`[PostHog Prompts] Invalid response format for ${reference}`);
+			rows.push(...data.results);
+			const nextUrl = data.next;
+			if (nextUrl !== null && nextUrl !== void 0 && (typeof nextUrl !== "string" || !isSameOrigin(nextUrl, this.host))) throw new Error(`[PostHog Prompts] Refusing to follow a pagination link off the configured host while fetching ${reference}.`);
+			url = nextUrl === null || nextUrl === void 0 ? void 0 : nextUrl;
+			pages += 1;
+		}
+		return rows;
+	}
+	async fetchPromptFromApi(name, version, label) {
+		this.requireCredentials();
 		const encodedPromptName = encodeURIComponent(name);
 		const encodedProjectApiKey = encodeURIComponent(this.projectApiKey);
 		const versionQuery = version === void 0 ? "" : `&version=${encodeURIComponent(String(version))}`;