@promptlycms/prompts 0.1.2 → 0.2.0-canary.1db6dca

package/README.md

@@ -3,8 +3,9 @@
 TypeScript SDK for the [Promptly CMS](https://promptlycms.com) API. Stop hardcoding prompts in your codebase — manage them in a purpose-built CMS with versioning and instant publishing, then fetch them at runtime with full type safety.
 
 - **Zero hardcoded prompts** — fetch prompts at runtime; update wording, models, and settings from the [CMS](https://promptlycms.com) without code changes or redeploys
-- **Runtime client** — `getPrompt()` and `getPrompts()` with full TypeScript support
-- **Codegen CLI** — generates typed template variables via declaration merging
+- **Runtime client** — `getPrompt()`, `getPrompts()`, `getComposer()`, and `getComposers()` with full TypeScript support
+- **Composers** — fetch multi-segment documents that combine static HTML with prompt references, then assemble AI-generated output with `formatComposer()`
+- **Codegen CLI** — generates typed template variables and composer types via declaration merging
 - **AI SDK integration** — destructure directly into [Vercel AI SDK](https://ai-sdk.dev/) `generateText` / `streamText`
 - **Any AI provider** — supports [all providers](https://ai-sdk.dev/providers/ai-sdk-providers#provider-support) supported by the Vercel AI SDK
 - **Structured output** — Zod schemas built from CMS-defined output schemas
@@ -46,7 +47,7 @@ PROMPTLY_API_KEY=pk_live_...
 npx promptly generate
 ```
 
-This fetches all your prompts from the API and generates a `promptly-env.d.ts` file in your project root with typed autocomplete for every prompt ID and its template variables.
+This fetches all your prompts and composers from the API and generates a `promptly-env.d.ts` file in your project root with typed autocomplete for every prompt ID, composer ID, template variables, and prompt names.
 
 ```bash
 # Custom output path
@@ -135,6 +136,49 @@ const { text } = await generateText({
 
 The model configured in the CMS is auto-resolved to the correct AI SDK provider.
 
+## Fetching composers
+
+A composer is a document template that combines static HTML segments with prompt references. Fetch a composer and use `compose()` to run all prompts and assemble the output in one call:
+
+```typescript
+import { generateText } from 'ai';
+
+const composer = await promptly.getComposer('my-composer-id', {
+  input: { text: 'Hello world', targetLang: 'French' },
+});
+
+// One line — runs all prompts in parallel, assembles the output
+const output = await composer.compose(generateText);
+```
+
+Override parameters per prompt:
+
+```typescript
+const output = await composer.compose((prompt) =>
+  generateText({ ...prompt, maxTokens: 500 })
+);
+```
+
+For full control, use the manual flow with named prompts and `formatComposer()`:
+
+```typescript
+const { introPrompt, reviewPrompt, formatComposer } = composer;
+
+const output = formatComposer({
+  introPrompt: await generateText(introPrompt),
+  reviewPrompt: await generateText(reviewPrompt),
+});
+```
+
+Batch fetch multiple composers in parallel:
+
+```typescript
+const [first, second] = await promptly.getComposers([
+  { composerId: 'comp-a', input: { name: 'Dan' } },
+  { composerId: 'comp-b', input: { topic: 'AI' } },
+]);
+```
+
 ## Model auto-detection
 
 The SDK automatically resolves models configured in the CMS to the correct AI SDK provider based on the model name prefix:
@@ -146,7 +190,7 @@ The SDK automatically resolves models configured in the CMS to the correct AI SD
 | `gemini-*` | Google | `@ai-sdk/google` |
 | `mistral-*`, `mixtral-*`, `codestral-*` | Mistral | `@ai-sdk/mistral` |
 
-CMS model display names (e.g. `claude-sonnet-4.5`) are mapped to their full API model IDs automatically.
+CMS model display names (e.g. `claude-sonnet-4.6`) are mapped to their full API model IDs automatically.
 
 ### Custom model resolver
 
@@ -157,7 +201,7 @@ import { anthropic } from '@ai-sdk/anthropic';
 
 const promptly = createPromptlyClient({
   apiKey: process.env.PROMPTLY_API_KEY,
-  model: (modelId) => anthropic('claude-sonnet-4-5-20250929'),
+  model: (modelId) => anthropic('claude-sonnet-4-6'),
 });
 ```
 
@@ -187,7 +231,7 @@ declare module '@promptlycms/prompts' {
 }
 ```
 
-With this file present, `getPrompt()` and `getPrompts()` return typed `userMessage` functions with autocomplete. Unknown prompt IDs fall back to `Record<string, string>`.
+With this file present, `getPrompt()` and `getPrompts()` return typed `userMessage` functions with autocomplete. `getComposer()` and `getComposers()` get typed `input` and named prompt properties. Unknown IDs fall back to `Record<string, string>`.
 
 Add the generated file to version control so types are available without running codegen in CI. Re-run `npx promptly generate` whenever you add, remove, or rename template variables in the CMS.
 
@@ -221,7 +265,7 @@ try {
 | `baseUrl` | `string` | No       | API base URL (default: `https://api.promptlycms.com`) |
 | `model`   | `(modelId: string) => LanguageModel` | No | Custom model resolver — overrides auto-detection |
 
-Returns a `PromptlyClient` with `getPrompt()` and `getPrompts()` methods.
+Returns a `PromptlyClient` with `getPrompt()`, `getPrompts()`, `getComposer()`, and `getComposers()` methods.
 
 ### `client.getPrompt(promptId, options?)`
 
@@ -235,6 +279,19 @@ Fetch a single prompt. Returns `PromptResult` with typed `userMessage` when code
 
 Fetch multiple prompts in parallel. Accepts `PromptRequest[]` and returns a typed tuple matching the input order.
 
+### `client.getComposer(composerId, options?)`
+
+Fetch a single composer. Returns `ComposerResult` with named prompt properties, a `prompts` array, and `formatComposer()`.
+
+| Option    | Type                      | Description          |
+|-----------|---------------------------|----------------------|
+| `input`   | `Record<string, string>`  | Template variables to interpolate |
+| `version` | `string`                  | Specific version to fetch (default: latest) |
+
+### `client.getComposers(entries)`
+
+Fetch multiple composers in parallel. Accepts `ComposerRequest[]` and returns results in the same order.
+
 ### `@promptlycms/prompts/schema`
 
 Subpath export for working with Zod schemas from CMS schema fields:

package/dist/cli.js

@@ -65,6 +65,7 @@ var detectProviderName = (modelId) => {
   }
   return void 0;
 };
+var toCamelCase = (name) => name.replace(/[^a-zA-Z0-9]+(.)/g, (_, char) => char.toUpperCase()).replace(/^[A-Z]/, (char) => char.toLowerCase());
 
 // src/cli/generate.ts
 var PROVIDER_PACKAGES = {
@@ -98,6 +99,50 @@ var fetchAllPrompts = async (apiKey, baseUrl) => {
   }
   return response.json();
 };
+var fetchAllComposers = async (apiKey, baseUrl) => {
+  const url = new URL("/composers", baseUrl ?? DEFAULT_BASE_URL);
+  url.searchParams.set("include_versions", "true");
+  const response = await fetch(url.toString(), {
+    headers: {
+      Authorization: `Bearer ${apiKey}`
+    }
+  });
+  if (!response.ok) {
+    throw await createErrorFromResponse(response);
+  }
+  return response.json();
+};
+var extractComposerVariables = (composer) => {
+  const vars = /* @__PURE__ */ new Set();
+  for (const segment of composer.segments) {
+    if (segment.type !== "prompt") {
+      continue;
+    }
+    if (!segment.userMessage) {
+      continue;
+    }
+    for (const v of extractTemplateVariables(segment.userMessage)) {
+      vars.add(v);
+    }
+  }
+  return [...vars];
+};
+var extractComposerPromptNames = (composer) => {
+  const seen = /* @__PURE__ */ new Set();
+  const names = [];
+  for (const segment of composer.segments) {
+    if (segment.type !== "prompt") {
+      continue;
+    }
+    const camelName = toCamelCase(segment.promptName);
+    if (seen.has(camelName)) {
+      continue;
+    }
+    seen.add(camelName);
+    names.push(camelName);
+  }
+  return names;
+};
 var compareSemver = (a, b) => {
   const pa = a.split(".").map(Number);
   const pb = b.split(".").map(Number);
@@ -209,7 +254,7 @@ var generateMappedTypeBlock = (group, indent) => {
   }
   return lines;
 };
-var generateTypeDeclaration = (prompts) => {
+var generateTypeDeclaration = (prompts, composers = []) => {
   const lines = [
     "// Auto-generated by @promptlycms/prompts \u2014 do not edit",
     "import '@promptlycms/prompts';",
@@ -243,27 +288,91 @@ var generateTypeDeclaration = (prompts) => {
     }
   }
   lines.push("  }");
+  if (composers.length > 0) {
+    lines.push("  interface ComposerVariableMap {");
+    for (const composer of composers) {
+      const variables = extractComposerVariables(composer);
+      const versions = ["'latest'"];
+      if (composer.publishedVersions) {
+        for (const pv of composer.publishedVersions) {
+          versions.push(`'${pv.version}'`);
+        }
+      } else {
+        versions.push(`'${composer.version}'`);
+      }
+      lines.push(`    '${composer.composerId}': {`);
+      if (versions.length === 1) {
+        if (variables.length === 0) {
+          lines.push(`      [V in ${versions[0]}]: Record<string, never>;`);
+        } else {
+          lines.push(`      [V in ${versions[0]}]: {`);
+          for (const v of variables) {
+            lines.push(`        ${v}: string;`);
+          }
+          lines.push("      };");
+        }
+      } else {
+        const versionUnion = versions.join(" | ");
+        if (variables.length === 0) {
+          lines.push(`      [V in ${versionUnion}]: Record<string, never>;`);
+        } else {
+          lines.push(`      [V in ${versionUnion}]: {`);
+          for (const v of variables) {
+            lines.push(`        ${v}: string;`);
+          }
+          lines.push("      };");
+        }
+      }
+      lines.push("    };");
+    }
+    lines.push("  }");
+    lines.push("  interface ComposerPromptMap {");
+    for (const composer of composers) {
+      const names = extractComposerPromptNames(composer);
+      if (names.length === 0) {
+        lines.push(`    '${composer.composerId}': never;`);
+      } else {
+        const union = names.map((n) => `'${n}'`).join(" | ");
+        lines.push(`    '${composer.composerId}': ${union};`);
+      }
+    }
+    lines.push("  }");
+  }
   lines.push("}");
   lines.push("");
   return lines.join("\n");
 };
-var warnMissingProviders = (prompts) => {
+var warnMissingProviders = (prompts, composers = []) => {
   const require2 = createRequire(import.meta.url);
   const needed = /* @__PURE__ */ new Map();
-  for (const prompt of prompts) {
-    const provider = detectProviderName(prompt.config.model);
+  const trackModel = (modelId, label) => {
+    const provider = detectProviderName(modelId);
     if (!provider) {
-      continue;
+      return;
     }
     const pkg = PROVIDER_PACKAGES[provider];
     if (!pkg) {
-      continue;
+      return;
     }
     const existing = needed.get(pkg);
     if (existing) {
-      existing.push(prompt.promptName);
+      existing.push(label);
     } else {
-      needed.set(pkg, [prompt.promptName]);
+      needed.set(pkg, [label]);
+    }
+  };
+  for (const prompt of prompts) {
+    trackModel(prompt.config.model, prompt.promptName);
+  }
+  for (const composer of composers) {
+    for (const segment of composer.segments) {
+      if (segment.type !== "prompt") {
+        continue;
+      }
+      const modelId = segment.config.model;
+      if (modelId) {
+        trackModel(modelId, `${composer.composerName}/${segment.promptName}`);
+      }
     }
   }
   for (const [pkg, promptNames] of needed) {
@@ -278,14 +387,22 @@ var warnMissingProviders = (prompts) => {
   }
 };
 var generate = async (apiKey, outputPath, baseUrl) => {
-  const prompts = await fetchAllPrompts(apiKey, baseUrl);
-  if (prompts.length === 0) {
-    console.log("  No prompts found for this API key.");
+  const [prompts, composers] = await Promise.all([
+    fetchAllPrompts(apiKey, baseUrl),
+    fetchAllComposers(apiKey, baseUrl).catch(() => [])
+  ]);
+  if (prompts.length === 0 && composers.length === 0) {
+    console.log("  No prompts or composers found for this API key.");
     return;
   }
-  console.log(`  Found ${prompts.length} prompt(s)`);
-  warnMissingProviders(prompts);
-  const content = generateTypeDeclaration(prompts);
+  if (prompts.length > 0) {
+    console.log(`  Found ${prompts.length} prompt(s)`);
+  }
+  if (composers.length > 0) {
+    console.log(`  Found ${composers.length} composer(s)`);
+  }
+  warnMissingProviders(prompts, composers);
+  const content = generateTypeDeclaration(prompts, composers);
   await writeFile(outputPath, content, "utf-8");
   console.log(`  Generated ${outputPath}`);
 };
@@ -355,7 +472,7 @@ var formatPromptlyError = (error) => {
 var generateCommand = defineCommand({
   meta: {
     name: "generate",
-    description: "Generate typed TypeScript declarations from Promptly CMS prompts"
+    description: "Generate typed TypeScript declarations from Promptly CMS prompts and composers"
   },
   args: {
     output: {

package/dist/index.cjs

@@ -33,7 +33,9 @@ __export(src_exports, {
   PromptlyError: () => PromptlyError,
   createPromptlyClient: () => createPromptlyClient,
   getSdkModelId: () => getSdkModelId,
-  interpolate: () => interpolate
+  interpolate: () => interpolate,
+  interpolateStaticSegment: () => interpolateStaticSegment,
+  toCamelCase: () => toCamelCase
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -76,6 +78,7 @@ var DEFAULT_BASE_URL = "https://api.promptlycms.com";
 var MODEL_ID_MAP = {
   // Anthropic: CMS display IDs → API model IDs
   "claude-opus-4.6": "claude-opus-4-6-20250917",
+  "claude-sonnet-4.6": "claude-sonnet-4-6",
   "claude-sonnet-4.5": "claude-sonnet-4-5-20250929",
   "claude-haiku-4.5": "claude-haiku-4-5-20251001",
   "claude-opus-4": "claude-opus-4-20250514",
@@ -179,6 +182,26 @@ var createModelResolver = (config) => {
     );
   };
 };
+var toCamelCase = (name) => name.replace(/[^a-zA-Z0-9]+(.)/g, (_, char) => char.toUpperCase()).replace(/^[A-Z]/, (char) => char.toLowerCase());
+var VARIABLE_REF_REGEX = /<span[^>]*\sdata-variable-ref(?:="[^"]*")?[^>]*\sdata-field-path="([^"]+)"[^>]*><\/span>/g;
+var VARIABLE_REF_ALT_REGEX = /<span[^>]*\sdata-field-path="([^"]+)"[^>]*\sdata-variable-ref(?:="[^"]*")?[^>]*><\/span>/g;
+var MUSTACHE_REGEX = /\{\{(\w[\w.]*)\}\}/g;
+var interpolateStaticSegment = (content, input) => {
+  let result = content;
+  result = result.replace(
+    VARIABLE_REF_REGEX,
+    (_, fieldPath) => input[fieldPath] ?? ""
+  );
+  result = result.replace(
+    VARIABLE_REF_ALT_REGEX,
+    (_, fieldPath) => input[fieldPath] ?? ""
+  );
+  result = result.replace(
+    MUSTACHE_REGEX,
+    (_, fieldPath) => input[fieldPath] ?? ""
+  );
+  return result;
+};
 var createPromptlyClient = (config) => {
   const apiKey = config?.apiKey ?? process.env.PROMPTLY_API_KEY;
   if (!apiKey) {
@@ -223,12 +246,119 @@ var createPromptlyClient = (config) => {
     );
     return results;
   };
-  return { getPrompt, getPrompts };
+  const fetchComposer = async (composerId, options) => {
+    const url = new URL(`/composers/${composerId}`, baseUrl);
+    if (options?.version) {
+      url.searchParams.set("version", options.version);
+    }
+    const response = await fetch(url.toString(), {
+      headers: {
+        Authorization: `Bearer ${apiKey}`
+      }
+    });
+    if (!response.ok) {
+      throw await createErrorFromResponse(response);
+    }
+    return response.json();
+  };
+  const getComposer = async (composerId, options) => {
+    const response = await fetchComposer(composerId, options);
+    const input = options?.input ?? {};
+    const promptsByName = /* @__PURE__ */ new Map();
+    const promptsOrdered = [];
+    const processedSegments = [];
+    for (const segment of response.segments) {
+      if (segment.type === "static") {
+        processedSegments.push({
+          type: "static",
+          content: interpolateStaticSegment(segment.content, input)
+        });
+        continue;
+      }
+      const camelName = toCamelCase(segment.promptName);
+      if (!promptsByName.has(camelName)) {
+        const segmentConfig = segment.config;
+        const model = await modelResolver(segmentConfig.model ?? "");
+        const userMessage = segment.userMessage ? interpolate(segment.userMessage, input) : "";
+        const temperature = segmentConfig.temperature ?? 0.7;
+        const composerPrompt = {
+          model,
+          system: segment.systemMessage ?? void 0,
+          prompt: userMessage,
+          temperature,
+          promptId: segment.promptId,
+          promptName: segment.promptName
+        };
+        promptsByName.set(camelName, composerPrompt);
+        promptsOrdered.push(composerPrompt);
+      }
+      processedSegments.push({ type: "prompt", camelName });
+    }
+    const formatComposer = (results) => {
+      const parts = [];
+      for (const seg of processedSegments) {
+        if (seg.type === "static") {
+          parts.push(seg.content);
+          continue;
+        }
+        const val = results[seg.camelName];
+        if (val === void 0) {
+          continue;
+        }
+        parts.push(typeof val === "string" ? val : val.text);
+      }
+      return parts.join("");
+    };
+    const compose = async (generate) => {
+      const entries = [...promptsByName.entries()];
+      const results = await Promise.all(
+        entries.map(([, prompt]) => generate(prompt))
+      );
+      const resultMap = {};
+      entries.forEach(([name], i) => {
+        resultMap[name] = results[i] ?? "";
+      });
+      return formatComposer(resultMap);
+    };
+    const result = {
+      composerId: response.composerId,
+      composerName: response.composerName,
+      version: response.version,
+      config: response.config,
+      segments: response.segments,
+      prompts: promptsOrdered,
+      formatComposer,
+      compose
+    };
+    for (const [name, prompt] of promptsByName) {
+      result[name] = prompt;
+    }
+    return result;
+  };
+  const getComposers = async (entries) => {
+    const results = await Promise.all(
+      entries.map(
+        (entry) => getComposer(entry.composerId, {
+          input: entry.input,
+          version: entry.version
+        })
+      )
+    );
+    return results;
+  };
+  return {
+    getPrompt,
+    getPrompts,
+    getComposer,
+    getComposers
+  };
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   PromptlyError,
   createPromptlyClient,
   getSdkModelId,
-  interpolate
+  interpolate,
+  interpolateStaticSegment,
+  toCamelCase
 });

package/dist/index.d.cts

@@ -1,9 +1,11 @@
-import { P as PromptlyClientConfig, a as PromptlyClient, E as ErrorCode } from './types-BbNpKJej.cjs';
-export { b as ErrorResponse, G as GetOptions, c as PromptConfig, d as PromptId, e as PromptMessage, f as PromptRequest, g as PromptResponse, h as PromptResult, i as PromptVariableMap, j as PromptVersion, k as PublishedVersion, S as SchemaField, l as SchemaFieldParams, V as ValidationRule } from './types-BbNpKJej.cjs';
+import { P as PromptlyClientConfig, a as PromptlyClient, E as ErrorCode } from './types-DyMq5QKO.cjs';
+export { C as ComposerConfig, b as ComposerFormatFn, c as ComposerGenerateFn, d as ComposerId, e as ComposerInputFor, f as ComposerPrompt, g as ComposerPromptMap, h as ComposerPromptNamesFor, i as ComposerPromptSegment, j as ComposerRequest, k as ComposerResponse, l as ComposerResult, m as ComposerSegment, n as ComposerStaticSegment, o as ComposerVariableMap, p as ComposerVersion, q as ErrorResponse, F as FormatInput, G as GetComposerOptions, r as GetOptions, s as PromptConfig, t as PromptId, u as PromptMessage, v as PromptRequest, w as PromptResponse, x as PromptResult, y as PromptVariableMap, z as PromptVersion, A as PublishedVersion, S as SchemaField, B as SchemaFieldParams, V as ValidationRule } from './types-DyMq5QKO.cjs';
 import 'ai';
 
 declare const getSdkModelId: (modelId: string) => string;
 declare const interpolate: (template: string, variables: Record<string, string>) => string;
+declare const toCamelCase: (name: string) => string;
+declare const interpolateStaticSegment: (content: string, input: Record<string, string>) => string;
 declare const createPromptlyClient: (config?: PromptlyClientConfig) => PromptlyClient;
 
 declare class PromptlyError extends Error {
@@ -14,4 +16,4 @@ declare class PromptlyError extends Error {
     constructor(message: string, code: ErrorCode, status: number, usage?: unknown, upgradeUrl?: string);
 }
 
-export { ErrorCode, PromptlyClient, PromptlyClientConfig, PromptlyError, createPromptlyClient, getSdkModelId, interpolate };
+export { ErrorCode, PromptlyClient, PromptlyClientConfig, PromptlyError, createPromptlyClient, getSdkModelId, interpolate, interpolateStaticSegment, toCamelCase };

package/dist/index.d.ts

@@ -1,9 +1,11 @@
-import { P as PromptlyClientConfig, a as PromptlyClient, E as ErrorCode } from './types-BbNpKJej.js';
-export { b as ErrorResponse, G as GetOptions, c as PromptConfig, d as PromptId, e as PromptMessage, f as PromptRequest, g as PromptResponse, h as PromptResult, i as PromptVariableMap, j as PromptVersion, k as PublishedVersion, S as SchemaField, l as SchemaFieldParams, V as ValidationRule } from './types-BbNpKJej.js';
+import { P as PromptlyClientConfig, a as PromptlyClient, E as ErrorCode } from './types-DyMq5QKO.js';
+export { C as ComposerConfig, b as ComposerFormatFn, c as ComposerGenerateFn, d as ComposerId, e as ComposerInputFor, f as ComposerPrompt, g as ComposerPromptMap, h as ComposerPromptNamesFor, i as ComposerPromptSegment, j as ComposerRequest, k as ComposerResponse, l as ComposerResult, m as ComposerSegment, n as ComposerStaticSegment, o as ComposerVariableMap, p as ComposerVersion, q as ErrorResponse, F as FormatInput, G as GetComposerOptions, r as GetOptions, s as PromptConfig, t as PromptId, u as PromptMessage, v as PromptRequest, w as PromptResponse, x as PromptResult, y as PromptVariableMap, z as PromptVersion, A as PublishedVersion, S as SchemaField, B as SchemaFieldParams, V as ValidationRule } from './types-DyMq5QKO.js';
 import 'ai';
 
 declare const getSdkModelId: (modelId: string) => string;
 declare const interpolate: (template: string, variables: Record<string, string>) => string;
+declare const toCamelCase: (name: string) => string;
+declare const interpolateStaticSegment: (content: string, input: Record<string, string>) => string;
 declare const createPromptlyClient: (config?: PromptlyClientConfig) => PromptlyClient;
 
 declare class PromptlyError extends Error {
@@ -14,4 +16,4 @@ declare class PromptlyError extends Error {
     constructor(message: string, code: ErrorCode, status: number, usage?: unknown, upgradeUrl?: string);
 }
 
-export { ErrorCode, PromptlyClient, PromptlyClientConfig, PromptlyError, createPromptlyClient, getSdkModelId, interpolate };
+export { ErrorCode, PromptlyClient, PromptlyClientConfig, PromptlyError, createPromptlyClient, getSdkModelId, interpolate, interpolateStaticSegment, toCamelCase };