@mate-academy/prompt-client 2.0.0 → 2.1.0

package/README.md

@@ -102,11 +102,20 @@ Error model (only when NO `fallback` is provided):
   existence probe).
 - `LLMPromptFetchError` — infrastructure failure (network/HTTP) or a
   wrong-shape prompt (a chat prompt fetched via `getPrompt`, or vice versa).
-  Both extend `LLMPromptError` and carry `promptName` + `cause`.
+  Both extend `LLMPromptError` and carry `promptName`. `cause` is set when an
+  underlying provider error is available.
 
-With `fallback` set, `getPrompt` never rejects: on any failure it resolves to
-the fallback text with `version: 0` and `isFallback: true`, and the logger
-receives a warning.
+`LLMPromptListError` (thrown only by `listPrompts`, see [Catalog](#catalog-for-codegen))
+sits outside this hierarchy on purpose: it is **selection-scoped**, not
+prompt-scoped, so it extends `Error` directly and carries the requested
+`label` + `tag` plus `cause` instead of `promptName`. A broad `catch (error) {
+if (error instanceof LLMPromptError) ... }` will **not** catch it — handle it
+explicitly, or match on `error.name === 'LLMPromptListError'`.
+
+With `fallback` set, `getPrompt` never rejects: it resolves to the fallback text
+with `version: 0` and `isFallback: true`, and logs the fallback resolution. If
+the SDK throws instead of returning its fallback, the client also logs the
+underlying fetch error before building the same fallback locally.
 
 ### Chat prompts
 
@@ -128,8 +137,9 @@ prompt.compile({ leadName: 'Maria' }); // substitutes {{var}} in each message's
 Fallback is an `LLMPromptMessage[]` instead of a string, with the same
 never-throw / `version: 0` / `isFallback: true` semantics as `getPrompt`.
 Langfuse placeholder entries and messages with an unrecognized role are
-silently skipped from `messages`/`compile()`, with a warning logged so the
-gap is visible without breaking the call.
+filtered when the prompt is fetched. A warning is logged once at fetch time so
+the gap is visible without breaking the call; `messages` and `compile()` then
+use the filtered result.
 
 ### Catalog (for codegen)
 
@@ -139,6 +149,7 @@ Langfuse-prompt codegen (the gateway's `generateSnapshot`):
 ```typescript
 const { promptNames, page, totalPages } = await promptClient.listPrompts({
   label: 'production',
+  tag: 'catalog', // optional; omit to list every prompt carrying the label
   page: 1,      // default 1
   pageSize: 100, // default 100
 });
@@ -149,6 +160,12 @@ const record = await promptClient.getPromptRecord('chatAgent.instructions', {
 // record.type === LLMPromptTypes.Text | LLMPromptTypes.Chat
 ```
 
+`label` is required and `tag` narrows the same listing further — a prompt is
+returned only when it carries **both**. The filter is applied by the provider,
+never by widening the query and post-filtering names, so an unmatched tag
+yields an empty `promptNames` page rather than the full label listing.
+Pagination applies to the filtered set.
+
 Both methods are uncached and never fall back — they **throw** on failure
 (`LLMPromptListError` for `listPrompts`, `LLMPromptNotFoundError` /
 `LLMPromptFetchError` for `getPromptRecord`) so a codegen run can fail loudly
@@ -260,6 +277,10 @@ never applies to `getPromptRecord` — a missing seed always throws
 `LLMPromptNotFoundError`, since the catalog must report seeded truth for
 codegen tests.
 
+Seeds accept an optional `tags` array so `listPrompts({ label, tag })` filters
+the same way it does against Langfuse. Tags have no default: a seed without
+`tags` matches every tag-less listing and no tag-filtered one.
+
 ## Provider notes (Langfuse)
 
 - `label` and `version` are mutually exclusive; when `version` is set the

package/dist/LLMPromptClient.errors.d.ts

@@ -1,3 +1,4 @@
+import { type LLMPromptListSelection } from './LLMPromptClient.typedefs';
 export declare class LLMPromptError extends Error {
     readonly promptName: string;
     readonly cause?: unknown | undefined;
@@ -11,6 +12,7 @@ export declare class LLMPromptFetchError extends LLMPromptError {
 }
 export declare class LLMPromptListError extends Error {
     readonly label: string;
-    readonly cause?: unknown | undefined;
-    constructor(label: string, cause?: unknown | undefined);
+    readonly tag?: string;
+    readonly cause?: unknown;
+    constructor(selection: LLMPromptListSelection, cause?: unknown);
 }

package/dist/LLMPromptClient.errors.js

@@ -25,9 +25,11 @@ class LLMPromptFetchError extends LLMPromptError {
 }
 exports.LLMPromptFetchError = LLMPromptFetchError;
 class LLMPromptListError extends Error {
-    constructor(label, cause) {
-        super(`Failed to list LLM prompts for label: ${label}`);
-        this.label = label;
+    constructor(selection, cause) {
+        super(`Failed to list LLM prompts for label: ${selection.label}`
+            + (selection.tag === undefined ? '' : `, tag: ${selection.tag}`));
+        this.label = selection.label;
+        this.tag = selection.tag;
         this.cause = cause;
         this.name = 'LLMPromptListError';
     }

package/dist/LLMPromptClient.typedefs.d.ts

@@ -14,7 +14,7 @@ export interface LLMPromptMessage {
 export interface LLMPrompt {
     name: string;
     version: number;
-    type: LLMPromptTypes;
+    type: LLMPromptTypes.Text;
     prompt: string;
     config: unknown;
     isFallback: boolean;
@@ -28,7 +28,7 @@ export interface LLMPrompt {
 export interface LLMChatPrompt {
     name: string;
     version: number;
-    type: LLMPromptTypes;
+    type: LLMPromptTypes.Chat;
     messages: LLMPromptMessage[];
     config: unknown;
     isFallback: boolean;
@@ -60,8 +60,15 @@ interface GetChatPromptByLabelOptions extends GetChatPromptCommonOptions {
     label?: string;
 }
 export type GetChatPromptOptions = GetChatPromptByVersionOptions | GetChatPromptByLabelOptions;
-export interface ListPromptsOptions {
+/**
+ * Which prompts a catalog listing selects: a required label, narrowed further
+ * by an optional tag.
+ */
+export interface LLMPromptListSelection {
     label: string;
+    tag?: string;
+}
+export interface ListPromptsOptions extends LLMPromptListSelection {
     page?: number;
     pageSize?: number;
 }

package/dist/providers/InMemory/InMemory.typedefs.d.ts

@@ -8,12 +8,14 @@ export interface InMemorySeedPrompt {
     version?: number;
     config?: unknown;
     labels?: string[];
+    tags?: string[];
 }
 export interface InMemorySeedChatPrompt {
     messages: LLMPromptMessage[];
     version?: number;
     config?: unknown;
     labels?: string[];
+    tags?: string[];
 }
 export interface InMemoryProviderOptions {
     prompts?: Record<string, InMemorySeedPrompt>;

package/dist/providers/InMemory/InMemoryPrompt.client.d.ts

@@ -19,7 +19,9 @@ export declare class InMemoryPromptClient implements LLMPromptClient {
     private buildFallbackChatPrompt;
     private compileMessages;
     private collectMatchingNames;
+    private matchesSelection;
     private matchesLabel;
+    private matchesTag;
     private buildTextPromptRecord;
     private buildChatPromptRecord;
 }

package/dist/providers/InMemory/InMemoryPrompt.client.js

@@ -47,7 +47,7 @@ class InMemoryPromptClient {
         throw new LLMPromptClient_errors_1.LLMPromptNotFoundError(name);
     }
     async listPrompts(options) {
-        const matchingNames = this.collectMatchingNames(options.label);
+        const matchingNames = this.collectMatchingNames(options);
         const page = options.page ?? LLMPromptClient_constants_1.DEFAULT_PROMPT_LIST_PAGE;
         const pageSize = options.pageSize ?? LLMPromptClient_constants_1.DEFAULT_PROMPT_LIST_PAGE_SIZE;
         const startIndex = (page - 1) * pageSize;
@@ -131,12 +131,12 @@ class InMemoryPromptClient {
             content: (0, template_1.compileTemplateVariables)(message.content, variables),
         }));
     }
-    collectMatchingNames(label) {
+    collectMatchingNames(selection) {
         const matchingNames = [];
         const seenNames = new Set();
         const collect = (entries) => {
             entries.forEach(([name, seedPrompt]) => {
-                if (seenNames.has(name) || !this.matchesLabel(seedPrompt.labels, label)) {
+                if (seenNames.has(name) || !this.matchesSelection(seedPrompt, selection)) {
                     return;
                 }
                 matchingNames.push(name);
@@ -147,9 +147,17 @@ class InMemoryPromptClient {
         collect([...this.chatPrompts.entries()]);
         return matchingNames;
     }
+    matchesSelection(seedPrompt, selection) {
+        return this.matchesLabel(seedPrompt.labels, selection.label)
+            && this.matchesTag(seedPrompt.tags, selection.tag);
+    }
     matchesLabel(labels, label) {
         return (labels ?? [LLMPromptClient_constants_1.DEFAULT_PROMPT_LABEL]).includes(label);
     }
+    matchesTag(tags, tag) {
+        const requestedTag = tag ?? undefined;
+        return requestedTag === undefined || (tags ?? []).includes(requestedTag);
+    }
     buildTextPromptRecord(name, seedPrompt) {
         return {
             name,

package/dist/providers/Langfuse/Langfuse.constants.d.ts

@@ -0,0 +1 @@
+export declare const MILLISECONDS_PER_SECOND = 1000;

package/dist/providers/Langfuse/Langfuse.constants.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MILLISECONDS_PER_SECOND = void 0;
+exports.MILLISECONDS_PER_SECOND = 1000;

package/dist/providers/Langfuse/Langfuse.factory.js

@@ -2,15 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createLangfusePromptManagement = void 0;
 const client_1 = require("@langfuse/client");
+const Langfuse_constants_1 = require("../../providers/Langfuse/Langfuse.constants");
 const LangfusePrompt_client_1 = require("../../providers/Langfuse/LangfusePrompt.client");
-const MILLISECONDS_PER_SECOND = 1000;
 const createLangfusePromptManagement = (options, logger) => {
     const client = new client_1.LangfuseClient({
         publicKey: options.credentials.publicKey,
         secretKey: options.credentials.secretKey,
         baseUrl: options.credentials.baseUrl,
         ...(options.fetchTimeoutMs !== undefined
-            ? { timeout: Math.ceil(options.fetchTimeoutMs / MILLISECONDS_PER_SECOND) }
+            ? { timeout: Math.ceil(options.fetchTimeoutMs / Langfuse_constants_1.MILLISECONDS_PER_SECOND) }
             : {}),
     });
     return {

package/dist/providers/Langfuse/LangfusePrompt.client.d.ts

@@ -14,6 +14,7 @@ export declare class LangfusePromptClient implements LLMPromptClient {
     shutdown(): Promise<void>;
     private fetchTextPrompt;
     private fetchChatPrompt;
+    private reportFallbackFetchError;
     private resolveSelectionOptions;
     private resolveCacheTtlSeconds;
     private buildTextFallbackPrompt;
@@ -24,6 +25,7 @@ export declare class LangfusePromptClient implements LLMPromptClient {
     private ensureChatPrompt;
     private reportPromptResolution;
     private reportSkippedChatEntries;
+    private resolveListSelection;
     private fetchRawPrompt;
     private buildRequestOptions;
 }

package/dist/providers/Langfuse/LangfusePrompt.client.js

@@ -7,9 +7,10 @@ const LLMPromptClient_constants_1 = require("../../LLMPromptClient.constants");
 const LLMPromptClient_errors_1 = require("../../LLMPromptClient.errors");
 const Langfuse_helpers_1 = require("../../providers/Langfuse/Langfuse.helpers");
 const LangfusePrompt_1 = require("../../providers/Langfuse/LangfusePrompt");
+const Langfuse_constants_1 = require("../../providers/Langfuse/Langfuse.constants");
 const LANGFUSE_TEXT_PROMPT_TYPE = 'text';
 const LANGFUSE_CHAT_PROMPT_TYPE = 'chat';
-const MILLISECONDS_PER_SECOND = 1000;
+const FALLBACK_PROMPT_VERSION = 0;
 class LangfusePromptClient {
     constructor(client, providerOptions, logger) {
         this.client = client;
@@ -30,9 +31,10 @@ class LangfusePromptClient {
         return new LangfusePrompt_1.LangfuseChatPrompt(nativePrompt);
     }
     async listPrompts(options) {
+        const selection = this.resolveListSelection(options);
         try {
             const promptListPage = await this.client.api.prompts.list({
-                label: options.label,
+                ...selection,
                 page: options.page ?? LLMPromptClient_constants_1.DEFAULT_PROMPT_LIST_PAGE,
                 limit: options.pageSize ?? LLMPromptClient_constants_1.DEFAULT_PROMPT_LIST_PAGE_SIZE,
             }, this.buildRequestOptions());
@@ -45,9 +47,9 @@ class LangfusePromptClient {
         catch (error) {
             this.logger.error('Failed to list Langfuse prompts', {
                 error,
-                label: options.label,
+                ...selection,
             });
-            throw new LLMPromptClient_errors_1.LLMPromptListError(options.label, error);
+            throw new LLMPromptClient_errors_1.LLMPromptListError(selection, error);
         }
     }
     async getPromptRecord(name, options) {
@@ -87,6 +89,7 @@ class LangfusePromptClient {
         }
         catch (error) {
             if (options?.fallback !== undefined) {
+                this.reportFallbackFetchError(name, error);
                 return this.buildTextFallbackPrompt(name, options.fallback, options);
             }
             throw this.classifyFetchError(name, error);
@@ -105,11 +108,18 @@ class LangfusePromptClient {
         }
         catch (error) {
             if (options?.fallback !== undefined) {
+                this.reportFallbackFetchError(name, error);
                 return this.buildChatFallbackPrompt(name, options.fallback, options);
             }
             throw this.classifyFetchError(name, error);
         }
     }
+    reportFallbackFetchError(name, error) {
+        this.logger.error('Failed to fetch Langfuse prompt; using fallback', {
+            error,
+            promptName: name,
+        });
+    }
     resolveSelectionOptions(options) {
         if (options?.version !== undefined) {
             return { version: options.version };
@@ -128,7 +138,7 @@ class LangfusePromptClient {
     buildTextFallbackPrompt(name, fallback, options) {
         return new client_1.TextPromptClient({
             name,
-            version: options?.version ?? 0,
+            version: FALLBACK_PROMPT_VERSION,
             labels: this.resolveFallbackLabels(options),
             tags: [],
             config: {},
@@ -143,7 +153,7 @@ class LangfusePromptClient {
     buildChatFallbackPrompt(name, fallback, options) {
         return new client_1.ChatPromptClient({
             name,
-            version: options?.version ?? 0,
+            version: FALLBACK_PROMPT_VERSION,
             labels: this.resolveFallbackLabels(options),
             tags: [],
             config: {},
@@ -208,6 +218,13 @@ class LangfusePromptClient {
             });
         }
     }
+    resolveListSelection(options) {
+        const requestedTag = options.tag ?? undefined;
+        return {
+            label: options.label,
+            ...(requestedTag === undefined ? {} : { tag: requestedTag }),
+        };
+    }
     async fetchRawPrompt(name, options) {
         try {
             return await this.client.api.prompts.get(name, { label: options.label }, this.buildRequestOptions());
@@ -223,7 +240,7 @@ class LangfusePromptClient {
                 : {}),
             ...(this.providerOptions.fetchTimeoutMs !== undefined
                 ? {
-                    timeoutInSeconds: Math.ceil(this.providerOptions.fetchTimeoutMs / MILLISECONDS_PER_SECOND),
+                    timeoutInSeconds: Math.ceil(this.providerOptions.fetchTimeoutMs / Langfuse_constants_1.MILLISECONDS_PER_SECOND),
                 }
                 : {}),
         };

package/dist/providers/Langfuse/LangfusePrompt.d.ts

@@ -1,7 +1,7 @@
 import { type ChatPromptClient, type TextPromptClient } from '@langfuse/client';
 import { LLMPromptTypes, type LLMChatPrompt, type LLMPrompt, type LLMPromptMessage } from '../../LLMPromptClient.typedefs';
 export declare class LangfusePrompt implements LLMPrompt {
-    readonly nativePrompt: TextPromptClient;
+    private readonly nativePrompt;
     readonly type = LLMPromptTypes.Text;
     constructor(nativePrompt: TextPromptClient);
     get name(): string;
@@ -12,7 +12,7 @@ export declare class LangfusePrompt implements LLMPrompt {
     compile(variables?: Record<string, string>): string;
 }
 export declare class LangfuseChatPrompt implements LLMChatPrompt {
-    readonly nativePrompt: ChatPromptClient;
+    private readonly nativePrompt;
     readonly type = LLMPromptTypes.Chat;
     constructor(nativePrompt: ChatPromptClient);
     get name(): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mate-academy/prompt-client",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Provider-agnostic LLM prompt management client (Langfuse, InMemory)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",