@promptlycms/prompts 0.0.1 → 0.1.0-canary.1509501

package/README.md

@@ -1,45 +1,199 @@
 # @promptlycms/prompts
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+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).
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+## Install
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+```bash
+npm install @promptlycms/prompts
+# or
+bun add @promptlycms/prompts
+```
 
-## Purpose
+Peer dependencies: `zod@^4`, `ai@^4 || ^5 || ^6`, `typescript@^5`
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@promptlycms/prompts`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## Quick start
 
-## What is OIDC Trusted Publishing?
+### 1. Set your API key
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+```bash
+# .env
+PROMPTLY_API_KEY=pk_live_...
+```
 
-## Setup Instructions
+### 2. Generate types (optional but recommended)
 
-To properly configure OIDC trusted publishing for this package:
+```bash
+npx promptly generate
+```
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+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.
 
-## DO NOT USE THIS PACKAGE
+```bash
+# Custom output path
+npx promptly generate --output ./types/promptly-env.d.ts
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+# Pass API key directly
+npx promptly generate --api-key pk_live_...
+```
 
-## More Information
+### 3. Create a client
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```typescript
+import { createPromptClient } from '@promptlycms/prompts';
 
----
+const promptly = createPromptClient({
+  apiKey: process.env.PROMPTLY_API_KEY,
+});
+```
 
-**Maintained for OIDC setup purposes only**
+## Fetching prompts
+
+### Single prompt
+
+```typescript
+const result = await promptly.get('JPxlUpstuhXB5OwOtKPpj');
+
+// Access prompt metadata
+result.promptId;      // 'JPxlUpstuhXB5OwOtKPpj'
+result.promptName;    // 'Review Prompt'
+result.systemMessage; // 'You are a helpful assistant.'
+result.temperature;   // 0.7
+
+// Interpolate template variables (typed if you ran codegen)
+const message = result.userMessage({
+  pickupLocation: 'London',
+  items: 'sofa',
+});
+
+// Get the raw template string
+const template = String(result.userMessage);
+// => 'Help with ${pickupLocation} moving ${items}.'
+```
+
+Fetch a specific version:
+
+```typescript
+const result = await promptly.get('JPxlUpstuhXB5OwOtKPpj', {
+  version: '2.0.0',
+});
+```
+
+### Batch fetch
+
+Fetch multiple prompts in parallel with typed results per position:
+
+```typescript
+import type { PromptRequest } from '@promptlycms/prompts';
+
+const [reviewPrompt, welcomePrompt] = await promptly.getPrompts([
+  { promptId: 'JPxlUpstuhXB5OwOtKPpj' },
+  { promptId: 'abc123', version: '2.0.0' },
+]);
+
+// Each result is typed to its own prompt's variables
+reviewPrompt.userMessage({ pickupLocation: 'London', items: 'sofa' });
+welcomePrompt.userMessage({ email: 'a@b.com', subject: 'Hi' });
+```
+
+## AI SDK integration
+
+`aiParams()` returns an object you can spread directly into 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 { text } = await generateText({
+  model: anthropic('claude-sonnet-4-5-20250929'),
+  ...params,
+});
+```
+
+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()`.
+
+## 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:
+
+```typescript
+// Auto-generated by @promptlycms/prompts — do not edit
+import '@promptlycms/prompts';
+
+declare module '@promptlycms/prompts' {
+  interface PromptVariableMap {
+    'JPxlUpstuhXB5OwOtKPpj': {
+      pickupLocation: string;
+      items: string;
+    };
+    'abc123': {
+      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:
+
+```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.
+
+## Error handling
+
+All API errors throw `PromptlyError`:
+
+```typescript
+import { PromptlyError } from '@promptlycms/prompts';
+
+try {
+  await promptly.get('nonexistent');
+} catch (err) {
+  if (err instanceof PromptlyError) {
+    err.code;       // 'NOT_FOUND' | 'INVALID_KEY' | 'USAGE_LIMIT_EXCEEDED' | ...
+    err.status;     // HTTP status code
+    err.message;    // Human-readable error message
+    err.usage;      // Usage data (on 429s)
+    err.upgradeUrl; // Upgrade link (on 429s)
+  }
+}
+```
+
+## API reference
+
+### `createPromptClient(config)`
+
+| Option    | Type     | Required | Description                                        |
+|-----------|----------|----------|----------------------------------------------------|
+| `apiKey`  | `string` | Yes      | Your Promptly CMS API key                          |
+| `baseUrl` | `string` | No       | API base URL (default: `https://api.promptlycms.com`) |
+
+Returns a `PromptClient` with `get()`, `getPrompts()`, and `aiParams()` methods.
+
+### `client.get(promptId, options?)`
+
+Fetch a single prompt. Returns `PromptResult` with typed `userMessage` when codegen types are present.
+
+### `client.getPrompts(entries)`
+
+Fetch multiple prompts in parallel. Accepts `PromptRequest[]` and returns a typed tuple matching the input order.
+
+### `client.aiParams(promptId, options?)`
+
+Fetch a prompt and return params ready to spread into AI SDK functions (`system`, `prompt`, `temperature`, and optionally `output`).
+
+### CLI: `npx promptly generate`
+
+| Flag        | Alias | Description                                          |
+|-------------|-------|------------------------------------------------------|
+| `--api-key` |       | API key (defaults to `PROMPTLY_API_KEY` env var)     |
+| `--output`  | `-o`  | Output path (default: `./promptly-env.d.ts`)         |

package/dist/chunk-GZIUWN6H.js

@@ -0,0 +1,284 @@
+// src/schema/builder.ts
+import { z } from "zod";
+var resolveTypeString = (typeStr) => {
+  const builder = TYPE_BUILDERS.get(typeStr);
+  if (builder) {
+    return builder({
+      id: "",
+      name: "",
+      type: typeStr,
+      validations: [],
+      params: {}
+    });
+  }
+  return z.string();
+};
+var buildCoercible = (params, coerced, standard) => {
+  if (params.coerce) {
+    return coerced;
+  }
+  return standard;
+};
+var TYPE_BUILDERS = /* @__PURE__ */ new Map([
+  ["string", (f) => buildCoercible(f.params, z.coerce.string(), z.string())],
+  ["number", (f) => buildCoercible(f.params, z.coerce.number(), z.number())],
+  ["boolean", (f) => buildCoercible(f.params, z.coerce.boolean(), z.boolean())],
+  ["date", (f) => buildCoercible(f.params, z.coerce.date(), z.date())],
+  ["bigint", (f) => buildCoercible(f.params, z.coerce.bigint(), z.bigint())],
+  ["null", () => z.null()],
+  ["undefined", () => z.undefined()],
+  ["void", () => z.void()],
+  ["any", () => z.any()],
+  ["unknown", () => z.unknown()],
+  ["never", () => z.never()],
+  ["nan", () => z.nan()],
+  ["symbol", () => z.symbol()],
+  [
+    "enum",
+    (f) => {
+      const values = f.params.enumValues ?? [];
+      return z.enum(values);
+    }
+  ],
+  [
+    "literal",
+    (f) => {
+      const value = f.params.enumValues?.[0] ?? "";
+      return z.literal(value);
+    }
+  ],
+  [
+    "array",
+    (f) => {
+      if (f.params.isTuple && f.params.tupleTypes) {
+        const types = f.params.tupleTypes.map(resolveTypeString);
+        return z.tuple(types);
+      }
+      const elementSchema = f.params.elementType ? resolveTypeString(f.params.elementType) : z.unknown();
+      return z.array(elementSchema);
+    }
+  ],
+  [
+    "object",
+    (f) => {
+      const schema = z.object({});
+      if (f.params.isStrict) {
+        return schema.strict();
+      }
+      if (f.params.isPassthrough) {
+        return schema.passthrough();
+      }
+      return schema;
+    }
+  ],
+  [
+    "record",
+    (f) => {
+      const keySchema = f.params.keyType ? resolveTypeString(f.params.keyType) : z.string();
+      const valueSchema = f.params.valueType ? resolveTypeString(f.params.valueType) : z.unknown();
+      return z.record(keySchema, valueSchema);
+    }
+  ],
+  [
+    "map",
+    (f) => {
+      const keySchema = f.params.keyType ? resolveTypeString(f.params.keyType) : z.string();
+      const valueSchema = f.params.valueType ? resolveTypeString(f.params.valueType) : z.unknown();
+      return z.map(keySchema, valueSchema);
+    }
+  ],
+  [
+    "set",
+    (f) => {
+      const elementSchema = f.params.elementType ? resolveTypeString(f.params.elementType) : z.unknown();
+      return z.set(elementSchema);
+    }
+  ],
+  [
+    "union",
+    (f) => {
+      if (f.params.isDiscriminatedUnion && f.params.discriminatedUnion) {
+        const { discriminator, cases } = f.params.discriminatedUnion;
+        const schemas = Object.values(cases).map(
+          (c) => z.object({
+            [discriminator]: z.literal(c.value),
+            ...Object.fromEntries(
+              c.fields.map((field) => [field.name, buildFieldSchema(field)])
+            )
+          })
+        );
+        return z.discriminatedUnion(
+          discriminator,
+          schemas
+        );
+      }
+      const types = (f.params.unionTypes ?? []).map(resolveTypeString);
+      return z.union(types);
+    }
+  ],
+  [
+    "intersection",
+    (f) => {
+      const types = (f.params.unionTypes ?? []).map(resolveTypeString);
+      return z.intersection(types[0] ?? z.unknown(), types[1] ?? z.unknown());
+    }
+  ]
+]);
+var coerceDefaultValue = (value, fieldType) => {
+  const coercers = /* @__PURE__ */ new Map([
+    ["number", (v) => Number(v)],
+    ["boolean", (v) => v === "true"],
+    ["bigint", (v) => BigInt(v)]
+  ]);
+  const coercer = coercers.get(fieldType);
+  if (coercer) {
+    return coercer(value);
+  }
+  return value;
+};
+var applySizeValidation = (schema, type, value, message) => {
+  const num = Number(value);
+  if (schema instanceof z.ZodString) {
+    const methods = {
+      min: (n, m) => schema.min(n, m),
+      max: (n, m) => schema.max(n, m),
+      length: (n, m) => schema.length(n, m)
+    };
+    return methods[type]?.(num, message) ?? schema;
+  }
+  if (schema instanceof z.ZodNumber) {
+    const methods = {
+      min: (n, m) => schema.min(n, m),
+      max: (n, m) => schema.max(n, m)
+    };
+    return methods[type]?.(num, message) ?? schema;
+  }
+  if (schema instanceof z.ZodArray) {
+    const methods = {
+      min: (n) => schema.min(n),
+      max: (n) => schema.max(n),
+      length: (n) => schema.length(n)
+    };
+    return methods[type]?.(num) ?? schema;
+  }
+  return schema;
+};
+var VALIDATION_APPLICATORS = /* @__PURE__ */ new Map([
+  // Size validations
+  ["min", (s, r) => applySizeValidation(s, "min", r.value, r.message)],
+  ["max", (s, r) => applySizeValidation(s, "max", r.value, r.message)],
+  ["length", (s, r) => applySizeValidation(s, "length", r.value, r.message)],
+  // String validations
+  ["email", (s, r) => s instanceof z.ZodString ? s.email(r.message) : s],
+  ["url", (s, r) => s instanceof z.ZodString ? s.url(r.message) : s],
+  ["uuid", (s, r) => s instanceof z.ZodString ? s.uuid(r.message) : s],
+  ["cuid", (s, r) => s instanceof z.ZodString ? s.cuid(r.message) : s],
+  ["cuid2", (s, r) => s instanceof z.ZodString ? s.cuid2(r.message) : s],
+  ["ulid", (s, r) => s instanceof z.ZodString ? s.ulid(r.message) : s],
+  [
+    "regex",
+    (s, r) => s instanceof z.ZodString ? s.regex(new RegExp(r.value), r.message) : s
+  ],
+  [
+    "startsWith",
+    (s, r) => s instanceof z.ZodString ? s.startsWith(r.value, r.message) : s
+  ],
+  [
+    "endsWith",
+    (s, r) => s instanceof z.ZodString ? s.endsWith(r.value, r.message) : s
+  ],
+  [
+    "datetime",
+    (s, _r, f) => {
+      if (!(s instanceof z.ZodString)) {
+        return s;
+      }
+      const opts = f.params.stringOptions?.datetime;
+      return s.datetime(opts);
+    }
+  ],
+  [
+    "ip",
+    (s, _r, f) => {
+      if (!(s instanceof z.ZodString)) {
+        return s;
+      }
+      const version = f.params.stringOptions?.ip?.version;
+      if (version === "v6") {
+        return s.ipv6();
+      }
+      return s.ipv4();
+    }
+  ],
+  // String transforms
+  ["trim", (s) => s instanceof z.ZodString ? s.trim() : s],
+  ["toLowerCase", (s) => s instanceof z.ZodString ? s.toLowerCase() : s],
+  ["toUpperCase", (s) => s instanceof z.ZodString ? s.toUpperCase() : s],
+  // Number validations
+  ["int", (s, r) => s instanceof z.ZodNumber ? s.int(r.message) : s],
+  [
+    "positive",
+    (s, r) => s instanceof z.ZodNumber ? s.positive(r.message) : s
+  ],
+  [
+    "negative",
+    (s, r) => s instanceof z.ZodNumber ? s.negative(r.message) : s
+  ],
+  [
+    "multipleOf",
+    (s, r) => s instanceof z.ZodNumber ? s.multipleOf(Number(r.value), r.message) : s
+  ],
+  ["finite", (s, r) => s instanceof z.ZodNumber ? s.finite(r.message) : s],
+  ["safe", (s, r) => s instanceof z.ZodNumber ? s.safe(r.message) : s],
+  // Collection
+  [
+    "nonempty",
+    (s) => {
+      if (s instanceof z.ZodString) {
+        return s.min(1);
+      }
+      if (s instanceof z.ZodArray) {
+        return s.nonempty();
+      }
+      return s;
+    }
+  ],
+  // Wrapping modifiers
+  ["optional", (s) => s.optional()],
+  ["nullable", (s) => s.nullable()],
+  ["nullish", (s) => s.nullish()],
+  // Default & catch
+  ["default", (s, r, f) => s.default(coerceDefaultValue(r.value, f.type))],
+  ["catch", (s, r, f) => s.catch(coerceDefaultValue(r.value, f.type))],
+  // Readonly
+  ["readonly", (s) => s.readonly()]
+]);
+var buildFieldSchema = (field) => {
+  const builder = TYPE_BUILDERS.get(field.type);
+  if (!builder) {
+    return z.unknown();
+  }
+  let schema = builder(field);
+  for (const rule of field.validations) {
+    const applicator = VALIDATION_APPLICATORS.get(rule.type);
+    if (applicator) {
+      schema = applicator(schema, rule, field);
+    }
+  }
+  if (field.params.description) {
+    schema = schema.describe(field.params.description);
+  }
+  return schema;
+};
+var buildZodSchema = (fields) => {
+  const shape = {};
+  for (const field of fields) {
+    shape[field.name] = buildFieldSchema(field);
+  }
+  return z.object(shape);
+};
+
+export {
+  buildFieldSchema,
+  buildZodSchema
+};