@nirmos/sdk 0.1.0

package/src/prompts/render.ts

@@ -0,0 +1,117 @@
+import { PromptRenderError } from "../core/errors.js";
+import type { JsonValue } from "../core/types.js";
+import type { ChatMessage } from "../gateway/types.js";
+import type {
+  Prompt,
+  PromptRenderOptions,
+  PromptVariable,
+  PromptVariableValues,
+  RenderedPrompt,
+} from "./types.js";
+
+const PLACEHOLDER = /\{\{\s*([a-zA-Z][a-zA-Z0-9_.-]*)\s*\}\}/g;
+
+export function renderPrompt(
+  prompt: Prompt,
+  values: PromptVariableValues = {},
+  options: PromptRenderOptions = {},
+): RenderedPrompt {
+  const resolved = resolveVariables(prompt.variables, values);
+  const sourceMessages: readonly ChatMessage[] =
+    prompt.content.type === "chat"
+      ? prompt.content.messages
+      : [
+          {
+            role: prompt.content.role ?? "user",
+            content: prompt.content.text,
+          },
+        ];
+
+  const messages = sourceMessages.map((message) => ({
+    ...message,
+    content:
+      typeof message.content === "string"
+        ? interpolate(message.content, resolved, options)
+        : message.content.map((part) => {
+            if (part.type === "text") {
+              return {
+                ...part,
+                text: interpolate(part.text, resolved, options),
+              };
+            }
+            if (part.type === "image") {
+              return {
+                ...part,
+                url: interpolate(part.url, resolved, options),
+              };
+            }
+            return part;
+          }),
+  }));
+
+  return {
+    promptId: prompt.id,
+    promptVersion: prompt.version.number,
+    messages,
+    variables: resolved,
+  };
+}
+
+function resolveVariables(
+  definitions: readonly PromptVariable[],
+  supplied: PromptVariableValues,
+): PromptVariableValues {
+  const resolved: Record<string, JsonValue | undefined> = { ...supplied };
+  const missing: string[] = [];
+
+  for (const variable of definitions) {
+    const value = resolved[variable.name];
+    if (value === undefined && variable.default !== undefined) {
+      resolved[variable.name] = variable.default;
+    } else if (value === undefined && variable.required) {
+      missing.push(variable.name);
+    }
+  }
+
+  if (missing.length > 0) {
+    throw new PromptRenderError(
+      `Missing required prompt variables: ${missing.join(", ")}.`,
+      missing,
+    );
+  }
+  return resolved;
+}
+
+function interpolate(
+  template: string,
+  values: PromptVariableValues,
+  options: PromptRenderOptions,
+): string {
+  const unresolved = new Set<string>();
+  const result = template.replace(PLACEHOLDER, (placeholder, name: string) => {
+    const value = values[name];
+    if (value === undefined) {
+      unresolved.add(name);
+      return placeholder;
+    }
+    return stringify(value);
+  });
+
+  if (unresolved.size > 0 && !options.allowUnresolved) {
+    const names = [...unresolved];
+    throw new PromptRenderError(
+      `Unresolved prompt variables: ${names.join(", ")}.`,
+      names,
+    );
+  }
+  return result;
+}
+
+function stringify(value: JsonValue): string {
+  if (value === null) return "null";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}

package/src/prompts/types.ts

@@ -0,0 +1,148 @@
+import type { ChatMessage, ChatRole } from "../gateway/types.js";
+import type {
+  ExtensibleString,
+  JsonValue,
+  Page,
+  RequestMetadata,
+  RequestOptions,
+} from "../core/types.js";
+
+export type PromptIdentifier = string;
+export type PromptCacheMode = "default" | "reload" | "no-store";
+export type PromptStatus = ExtensibleString<
+  "draft" | "active" | "archived" | "published"
+>;
+
+export type PromptVariableType =
+  "string" | "number" | "boolean" | "enum" | "array";
+
+export interface PromptVariable {
+  name: string;
+  type: PromptVariableType;
+  required?: boolean;
+  description?: string;
+  default?: JsonValue;
+  values?: readonly string[];
+  min?: number;
+  max?: number;
+  minLength?: number;
+  maxLength?: number;
+  itemType?: PromptVariableType;
+}
+
+export type PromptVariableValue = JsonValue | undefined;
+export type PromptVariableValues = Readonly<
+  Record<string, PromptVariableValue>
+>;
+
+export interface TextPromptContent {
+  type: "text";
+  text: string;
+  role?: Exclude<ChatRole, "tool">;
+}
+
+export interface ChatPromptContent {
+  type: "chat";
+  messages: readonly ChatMessage[];
+}
+
+export type PromptContent = TextPromptContent | ChatPromptContent;
+
+export interface Prompt {
+  id: string;
+  name: string;
+  slug: string;
+  description?: string;
+  status: PromptStatus;
+  version: PromptVersion;
+  content: PromptContent;
+  variables: readonly PromptVariable[];
+  metadata: Readonly<Record<string, JsonValue>>;
+  tags: readonly string[];
+  folder?: string;
+  createdAt?: string;
+  updatedAt?: string;
+  requestMetadata: RequestMetadata;
+}
+
+export interface PromptVersion {
+  id: string;
+  number: number;
+  status: PromptStatus;
+  active: boolean;
+  content: PromptContent;
+  variables: readonly PromptVariable[];
+  metadata: Readonly<Record<string, JsonValue>>;
+  commitMessage?: string;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface PromptCreateParams {
+  name: string;
+  slug?: string;
+  description?: string;
+  content: PromptContent;
+  variables?: readonly PromptVariable[];
+  metadata?: Readonly<Record<string, JsonValue>>;
+  tags?: readonly string[];
+  folder?: string;
+  commitMessage?: string;
+  activate?: boolean;
+}
+
+export interface PromptUpdateParams {
+  name?: string;
+  slug?: string;
+  description?: string | null;
+  metadata?: Readonly<Record<string, JsonValue>>;
+  tags?: readonly string[];
+  folder?: string | null;
+  status?: PromptStatus;
+}
+
+export interface PromptVersionCreateParams {
+  content: PromptContent;
+  variables?: readonly PromptVariable[];
+  metadata?: Readonly<Record<string, JsonValue>>;
+  commitMessage?: string;
+  activate?: boolean;
+}
+
+export interface PromptRetrieveOptions extends RequestOptions {
+  version?: number | "active" | "latest";
+  cache?: PromptCacheMode;
+}
+
+export interface PromptVersionListOptions extends RequestOptions {
+  limit?: number;
+  cursor?: string;
+}
+
+export interface PromptRenderReference {
+  id: PromptIdentifier;
+  version?: number | "active" | "latest";
+  cache?: PromptCacheMode;
+}
+
+export interface PromptRenderOptions {
+  allowUnresolved?: boolean;
+}
+
+export interface RenderedPrompt {
+  promptId: string;
+  promptVersion: number;
+  messages: readonly ChatMessage[];
+  variables: PromptVariableValues;
+}
+
+export interface PromptCacheConfig {
+  /** Cache active prompt retrievals in memory. Defaults to true. */
+  enabled?: boolean;
+  /** Freshness window. Defaults to 60 seconds. */
+  ttlMs?: number;
+  /** Maximum cached prompt variants per client. Defaults to 100. */
+  maxEntries?: number;
+}
+
+export type PromptVersionPage = Page<PromptVersion>;

package/src/prompts/versions.ts

@@ -0,0 +1,80 @@
+import type { HttpTransport } from "../core/transport.js";
+import type { RequestOptions } from "../core/types.js";
+import {
+  normalizeVersion,
+  normalizeVersionPage,
+  toWireVersionCreate,
+} from "./mappers.js";
+import type {
+  PromptIdentifier,
+  PromptVersion,
+  PromptVersionCreateParams,
+  PromptVersionListOptions,
+  PromptVersionPage,
+} from "./types.js";
+
+export class PromptVersions {
+  readonly #transport: HttpTransport;
+  readonly #invalidate: () => void;
+
+  constructor(transport: HttpTransport, invalidate: () => void) {
+    this.#transport = transport;
+    this.#invalidate = invalidate;
+  }
+
+  async create(
+    identifier: PromptIdentifier,
+    params: PromptVersionCreateParams,
+    options?: RequestOptions,
+  ): Promise<PromptVersion> {
+    const { data } = await this.#transport.request<unknown>({
+      method: "POST",
+      path: `/v1/prompts/${encodeURIComponent(identifier)}/versions`,
+      body: toWireVersionCreate(params),
+      options,
+    });
+    this.#invalidate();
+    return normalizeVersion(data);
+  }
+
+  async retrieve(
+    identifier: PromptIdentifier,
+    version: number,
+    options?: RequestOptions,
+  ): Promise<PromptVersion> {
+    const { data } = await this.#transport.request<unknown>({
+      method: "GET",
+      path: `/v1/prompts/${encodeURIComponent(identifier)}/versions/${version}`,
+      options,
+    });
+    return normalizeVersion(data);
+  }
+
+  async list(
+    identifier: PromptIdentifier,
+    options: PromptVersionListOptions = {},
+  ): Promise<PromptVersionPage> {
+    const { limit, cursor, ...requestOptions } = options;
+    const { data } = await this.#transport.request<unknown>({
+      method: "GET",
+      path: `/v1/prompts/${encodeURIComponent(identifier)}/versions`,
+      query: { limit, cursor },
+      options: requestOptions,
+    });
+    return normalizeVersionPage(data);
+  }
+
+  async activate(
+    identifier: PromptIdentifier,
+    version: number,
+    options?: RequestOptions,
+  ): Promise<PromptVersion> {
+    const { data } = await this.#transport.request<unknown>({
+      method: "POST",
+      path: `/v1/prompts/${encodeURIComponent(identifier)}/versions/${version}/activate`,
+      options,
+    });
+    this.#invalidate();
+    return normalizeVersion(data);
+  }
+}