@promptlycms/prompts 0.1.0 → 0.1.1-canary.5fc554c

package/README.md

@@ -1,16 +1,35 @@
 # @promptlycms/prompts
 
-TypeScript SDK for the [Promptly CMS](https://promptlycms.com) API. Fetch prompts at runtime, get typed template variables via codegen, and integrate with the [Vercel AI SDK](https://sdk.vercel.ai).
+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
+- **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
 
 ## Install
 
 ```bash
 npm install @promptlycms/prompts
-# or
-bun add @promptlycms/prompts
 ```
 
-Peer dependencies: `zod@^4`, `ai@^4 || ^5 || ^6`, `typescript@^5`
+Peer dependencies:
+
+```bash
+npm install zod ai typescript
+```
+
+You'll also need at least one AI provider SDK for model resolution:
+
+```bash
+# Install the provider(s) your prompts use
+npm install @ai-sdk/anthropic  # Claude models
+npm install @ai-sdk/openai     # GPT / o-series models
+npm install @ai-sdk/google     # Gemini models
+npm install @ai-sdk/mistral    # Mistral / Mixtral models
+```
 
 ## Quick start
 
@@ -27,7 +46,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. This gives you typed autocomplete on `userMessage()` variables for every prompt ID.
+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.
 
 ```bash
 # Custom output path
@@ -40,9 +59,9 @@ npx promptly generate --api-key pk_live_...
 ### 3. Create a client
 
 ```typescript
-import { createPromptClient } from '@promptlycms/prompts';
+import { createPromptlyClient } from '@promptlycms/prompts';
 
-const promptly = createPromptClient({
+const promptly = createPromptlyClient({
   apiKey: process.env.PROMPTLY_API_KEY,
 });
 ```
@@ -52,13 +71,14 @@ const promptly = createPromptClient({
 ### Single prompt
 
 ```typescript
-const result = await promptly.get('JPxlUpstuhXB5OwOtKPpj');
+const result = await promptly.getPrompt('JPxlUpstuhXB5OwOtKPpj');
 
 // Access prompt metadata
 result.promptId;      // 'JPxlUpstuhXB5OwOtKPpj'
 result.promptName;    // 'Review Prompt'
 result.systemMessage; // 'You are a helpful assistant.'
 result.temperature;   // 0.7
+result.model;         // LanguageModel (auto-resolved from CMS config)
 
 // Interpolate template variables (typed if you ran codegen)
 const message = result.userMessage({
@@ -74,7 +94,7 @@ const template = String(result.userMessage);
 Fetch a specific version:
 
 ```typescript
-const result = await promptly.get('JPxlUpstuhXB5OwOtKPpj', {
+const result = await promptly.getPrompt('JPxlUpstuhXB5OwOtKPpj', {
   version: '2.0.0',
 });
 ```
@@ -98,27 +118,52 @@ welcomePrompt.userMessage({ email: 'a@b.com', subject: 'Hi' });
 
 ## AI SDK integration
 
-`aiParams()` returns an object you can spread directly into Vercel AI SDK functions:
+Destructure `getPrompt()` and pass the properties directly to Vercel AI SDK functions:
 
 ```typescript
 import { generateText } from 'ai';
-import { anthropic } from '@ai-sdk/anthropic';
 
-const params = await promptly.aiParams('my-prompt', {
-  variables: { name: 'Alice', task: 'coding' },
-});
+const { userMessage, systemMessage, temperature, model } = await promptly.getPrompt('my-prompt');
 
 const { text } = await generateText({
-  model: anthropic('claude-sonnet-4-5-20250929'),
-  ...params,
+  model,
+  system: systemMessage,
+  prompt: userMessage({ name: 'Alice', task: 'coding' }),
+  temperature,
 });
 ```
 
-If the prompt has a structured output schema defined in the CMS, `params.output` is automatically populated with a Zod schema wrapped in `Output.object()`.
+The model configured in the CMS is auto-resolved to the correct AI SDK provider.
+
+## Model auto-detection
+
+The SDK automatically resolves models configured in the CMS to the correct AI SDK provider based on the model name prefix:
+
+| Prefix | Provider | Package |
+|--------|----------|---------|
+| `claude-*` | Anthropic | `@ai-sdk/anthropic` |
+| `gpt-*`, `o1-*`, `o3-*`, `o4-*`, `chatgpt-*` | OpenAI | `@ai-sdk/openai` |
+| `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.
+
+### Custom model resolver
+
+If you need full control over model resolution, pass a `model` function:
+
+```typescript
+import { anthropic } from '@ai-sdk/anthropic';
+
+const promptly = createPromptlyClient({
+  apiKey: process.env.PROMPTLY_API_KEY,
+  model: (modelId) => anthropic('claude-sonnet-4-5-20250929'),
+});
+```
 
 ## Type generation
 
-Running `npx promptly generate` creates a `promptly-env.d.ts` file that uses [declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html) to narrow types:
+Running `npx promptly generate` creates a `promptly-env.d.ts` file that uses [declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html) to type your prompts:
 
 ```typescript
 // Auto-generated by @promptlycms/prompts — do not edit
@@ -127,26 +172,24 @@ import '@promptlycms/prompts';
 declare module '@promptlycms/prompts' {
   interface PromptVariableMap {
     'JPxlUpstuhXB5OwOtKPpj': {
-      pickupLocation: string;
-      items: string;
+      [V in 'latest' | '2.0.0' | '1.0.0']: {
+        pickupLocation: string;
+        items: string;
+      };
     };
     'abc123': {
-      email: string;
-      subject: string;
+      [V in 'latest' | '1.0.0']: {
+        email: string;
+        subject: string;
+      };
     };
   }
 }
 ```
 
-With this file present, `get()` and `getPrompts()` return typed `userMessage` functions with autocomplete. Unknown prompt IDs fall back to `Record<string, string>`.
-
-Add the generated file to version control so types are available without running codegen in CI:
+With this file present, `getPrompt()` and `getPrompts()` return typed `userMessage` functions with autocomplete. Unknown prompt IDs fall back to `Record<string, string>`.
 
-```bash
-# .gitignore — do NOT ignore promptly-env.d.ts
-```
-
-Re-run `npx promptly generate` whenever you add, remove, or rename template variables in the CMS.
+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.
 
 ## Error handling
 
@@ -156,7 +199,7 @@ All API errors throw `PromptlyError`:
 import { PromptlyError } from '@promptlycms/prompts';
 
 try {
-  await promptly.get('nonexistent');
+  await promptly.getPrompt('nonexistent');
 } catch (err) {
   if (err instanceof PromptlyError) {
     err.code;       // 'NOT_FOUND' | 'INVALID_KEY' | 'USAGE_LIMIT_EXCEEDED' | ...
@@ -170,26 +213,38 @@ try {
 
 ## API reference
 
-### `createPromptClient(config)`
+### `createPromptlyClient(config?)`
 
 | Option    | Type     | Required | Description                                        |
 |-----------|----------|----------|----------------------------------------------------|
-| `apiKey`  | `string` | Yes      | Your Promptly CMS API key                          |
+| `apiKey`  | `string` | No       | Your Promptly API key (defaults to `PROMPTLY_API_KEY` env var) |
 | `baseUrl` | `string` | No       | API base URL (default: `https://api.promptlycms.com`) |
+| `model`   | `(modelId: string) => LanguageModel` | No | Custom model resolver — overrides auto-detection |
 
-Returns a `PromptClient` with `get()`, `getPrompts()`, and `aiParams()` methods.
+Returns a `PromptlyClient` with `getPrompt()` and `getPrompts()` methods.
 
-### `client.get(promptId, options?)`
+### `client.getPrompt(promptId, options?)`
 
 Fetch a single prompt. Returns `PromptResult` with typed `userMessage` when codegen types are present.
 
+| Option    | Type     | Description          |
+|-----------|----------|----------------------|
+| `version` | `string` | Specific version to fetch (default: latest) |
+
 ### `client.getPrompts(entries)`
 
 Fetch multiple prompts in parallel. Accepts `PromptRequest[]` and returns a typed tuple matching the input order.
 
-### `client.aiParams(promptId, options?)`
+### `@promptlycms/prompts/schema`
+
+Subpath export for working with Zod schemas from CMS schema fields:
+
+```typescript
+import { buildZodSchema, schemaFieldsToZodSource } from '@promptlycms/prompts/schema';
+```
 
-Fetch a prompt and return params ready to spread into AI SDK functions (`system`, `prompt`, `temperature`, and optionally `output`).
+- `buildZodSchema(fields)` — builds a Zod object schema at runtime from `SchemaField[]`
+- `schemaFieldsToZodSource(fields)` — generates Zod source code as a string for codegen
 
 ### CLI: `npx promptly generate`
 
@@ -197,3 +252,7 @@ Fetch a prompt and return params ready to spread into AI SDK functions (`system`
 |-------------|-------|------------------------------------------------------|
 | `--api-key` |       | API key (defaults to `PROMPTLY_API_KEY` env var)     |
 | `--output`  | `-o`  | Output path (default: `./promptly-env.d.ts`)         |
+
+## License
+
+MIT

package/dist/cli.js

@@ -41,6 +41,38 @@ var createErrorFromResponse = async (response) => {
 
 // src/cli/generate.ts
 import { writeFile } from "fs/promises";
+import { createRequire } from "module";
+
+// src/client.ts
+var PROVIDER_PREFIXES = [
+  ["claude", "anthropic"],
+  ["gpt", "openai"],
+  ["o1", "openai"],
+  ["o3", "openai"],
+  ["o4", "openai"],
+  ["chatgpt", "openai"],
+  ["gemini", "google"],
+  ["mistral", "mistral"],
+  ["mixtral", "mistral"],
+  ["codestral", "mistral"]
+];
+var detectProviderName = (modelId) => {
+  const lower = modelId.toLowerCase();
+  for (const [prefix, provider] of PROVIDER_PREFIXES) {
+    if (lower.startsWith(prefix)) {
+      return provider;
+    }
+  }
+  return void 0;
+};
+
+// src/cli/generate.ts
+var PROVIDER_PACKAGES = {
+  anthropic: "@ai-sdk/anthropic",
+  openai: "@ai-sdk/openai",
+  google: "@ai-sdk/google",
+  mistral: "@ai-sdk/mistral"
+};
 var DEFAULT_BASE_URL = "https://api.promptlycms.com";
 var extractTemplateVariables = (text) => {
   const matches = text.matchAll(/\$\{(\w+)\}/g);
@@ -215,6 +247,36 @@ var generateTypeDeclaration = (prompts) => {
   lines.push("");
   return lines.join("\n");
 };
+var warnMissingProviders = (prompts) => {
+  const require2 = createRequire(import.meta.url);
+  const needed = /* @__PURE__ */ new Map();
+  for (const prompt of prompts) {
+    const provider = detectProviderName(prompt.config.model);
+    if (!provider) {
+      continue;
+    }
+    const pkg = PROVIDER_PACKAGES[provider];
+    if (!pkg) {
+      continue;
+    }
+    const existing = needed.get(pkg);
+    if (existing) {
+      existing.push(prompt.promptName);
+    } else {
+      needed.set(pkg, [prompt.promptName]);
+    }
+  }
+  for (const [pkg, promptNames] of needed) {
+    try {
+      require2.resolve(pkg);
+    } catch {
+      const names = promptNames.map((n) => `"${n}"`).join(", ");
+      console.warn(
+        `  Warning: ${names} requires ${pkg} \u2014 install it: npm install ${pkg}`
+      );
+    }
+  }
+};
 var generate = async (apiKey, outputPath, baseUrl) => {
   const prompts = await fetchAllPrompts(apiKey, baseUrl);
   if (prompts.length === 0) {
@@ -222,6 +284,7 @@ var generate = async (apiKey, outputPath, baseUrl) => {
     return;
   }
   console.log(`  Found ${prompts.length} prompt(s)`);
+  warnMissingProviders(prompts);
   const content = generateTypeDeclaration(prompts);
   await writeFile(outputPath, content, "utf-8");
   console.log(`  Generated ${outputPath}`);