@nirmos/sdk 0.1.0

package/src/index.ts

@@ -0,0 +1,83 @@
+export { Nirmos, NirmosClient } from "./client.js";
+export type { NirmosOptions } from "./client.js";
+
+export {
+  APIError,
+  AuthenticationError,
+  ConfigurationError,
+  ConflictError,
+  NetworkError,
+  NirmosError,
+  NotFoundError,
+  PermissionDeniedError,
+  PromptRenderError,
+  RateLimitError,
+  RequestAbortedError,
+  ServerError,
+  StreamError,
+  TimeoutError,
+  ValidationError,
+} from "./core/errors.js";
+
+export type {
+  HeadersInput,
+  JsonPrimitive,
+  JsonValue,
+  Page,
+  RequestMetadata,
+  RequestOptions,
+  Usage,
+} from "./core/types.js";
+
+export { ChatStream } from "./gateway/chat-stream.js";
+export type {
+  AudioContentPart,
+  ChatChoice,
+  ChatCompletion,
+  ChatContentPart,
+  ChatCreateParams,
+  ChatMessage,
+  ChatRole,
+  ChatStreamEvent,
+  Embedding,
+  EmbeddingCreateParams,
+  EmbeddingResponse,
+  FinishReason,
+  FunctionTool,
+  FunctionToolCall,
+  GeneratedImage,
+  ImageContentPart,
+  ImageGenerateParams,
+  ImageGeneration,
+  ImageSize,
+  PromptReference,
+  ResponseFormat,
+  RoutingStrategy,
+  TextContentPart,
+  ToolChoice,
+} from "./gateway/types.js";
+
+export type {
+  ChatPromptContent,
+  Prompt,
+  PromptCacheConfig,
+  PromptCacheMode,
+  PromptContent,
+  PromptCreateParams,
+  PromptIdentifier,
+  PromptRenderOptions,
+  PromptRenderReference,
+  PromptRetrieveOptions,
+  PromptStatus,
+  PromptUpdateParams,
+  PromptVariable,
+  PromptVariableType,
+  PromptVariableValue,
+  PromptVariableValues,
+  PromptVersion,
+  PromptVersionCreateParams,
+  PromptVersionListOptions,
+  PromptVersionPage,
+  RenderedPrompt,
+  TextPromptContent,
+} from "./prompts/types.js";

package/src/prompts/cache.ts

@@ -0,0 +1,50 @@
+export interface CacheEntry<T> {
+  value: T;
+  expiresAt: number;
+}
+
+export class MemoryCache<T> {
+  readonly #entries = new Map<string, CacheEntry<T>>();
+  readonly #maxEntries: number;
+  readonly #ttlMs: number;
+
+  constructor(maxEntries: number, ttlMs: number) {
+    this.#maxEntries = maxEntries;
+    this.#ttlMs = ttlMs;
+  }
+
+  get(key: string): T | undefined {
+    const entry = this.#entries.get(key);
+    if (!entry) return undefined;
+    if (entry.expiresAt <= Date.now()) {
+      this.#entries.delete(key);
+      return undefined;
+    }
+    this.#entries.delete(key);
+    this.#entries.set(key, entry);
+    return entry.value;
+  }
+
+  set(key: string, value: T): void {
+    this.#entries.delete(key);
+    this.#entries.set(key, {
+      value,
+      expiresAt: Date.now() + this.#ttlMs,
+    });
+    while (this.#entries.size > this.#maxEntries) {
+      const oldest = this.#entries.keys().next().value as string | undefined;
+      if (oldest === undefined) break;
+      this.#entries.delete(oldest);
+    }
+  }
+
+  deleteMatching(predicate: (key: string) => boolean): void {
+    for (const key of this.#entries.keys()) {
+      if (predicate(key)) this.#entries.delete(key);
+    }
+  }
+
+  clear(): void {
+    this.#entries.clear();
+  }
+}

package/src/prompts/mappers.ts

@@ -0,0 +1,318 @@
+import {
+  asUnknownRecord,
+  compactMetadata,
+  extractMetadata,
+  readArray,
+  readBoolean,
+  readNumber,
+  readString,
+} from "../core/metadata.js";
+import type { JsonValue, Page } from "../core/types.js";
+import { normalizeMessage, toWireMessage } from "../gateway/mappers.js";
+import type {
+  Prompt,
+  PromptContent,
+  PromptCreateParams,
+  PromptVariable,
+  PromptVersion,
+  PromptVersionCreateParams,
+} from "./types.js";
+
+export function toWirePromptCreate(
+  params: PromptCreateParams,
+): Record<string, unknown> {
+  return {
+    name: params.name,
+    slug: params.slug,
+    description: params.description,
+    content: toWireContent(params.content),
+    variables: params.variables?.map(toWireVariable),
+    metadata: params.metadata,
+    tags: params.tags,
+    folder: params.folder,
+    commit_message: params.commitMessage,
+    activate: params.activate,
+  };
+}
+
+export function toWireVersionCreate(
+  params: PromptVersionCreateParams,
+): Record<string, unknown> {
+  return {
+    content: toWireContent(params.content),
+    variables: params.variables?.map(toWireVariable),
+    metadata: params.metadata,
+    commit_message: params.commitMessage,
+    activate: params.activate,
+  };
+}
+
+export function normalizePrompt(payload: unknown, response: Response): Prompt {
+  const root = unwrap(payload);
+  const promptRecord = asUnknownRecord(root.prompt ?? root);
+  const versionCandidate =
+    root.version ??
+    root.active_version ??
+    root.activeVersion ??
+    root.latest_version ??
+    root.latestVersion ??
+    promptRecord.version ??
+    promptRecord.active_version ??
+    promptRecord.activeVersion ??
+    promptRecord.latest_version ??
+    promptRecord.latestVersion;
+  const versionRecord = isRecord(versionCandidate)
+    ? asUnknownRecord(versionCandidate)
+    : promptRecord;
+  const content = normalizeContent(
+    versionRecord.content ?? promptRecord.content,
+    versionRecord.messages ?? promptRecord.messages,
+  );
+  const variables = normalizeVariables(
+    versionRecord.variables ?? promptRecord.variables,
+    versionRecord.messages ?? promptRecord.messages,
+  );
+
+  return {
+    id: readString(promptRecord, "id") ?? "",
+    name: readString(promptRecord, "name") ?? "",
+    slug: readString(promptRecord, "slug") ?? "",
+    description: readString(promptRecord, "description"),
+    status:
+      readString(promptRecord, "status") ??
+      readString(versionRecord, "status") ??
+      "draft",
+    version: normalizeVersionRecord(versionRecord, content, variables),
+    content,
+    variables,
+    metadata: normalizeJsonRecord(promptRecord.metadata),
+    tags: normalizeTags(promptRecord.tags),
+    folder: readString(promptRecord, "folder", "folder_path", "folderPath"),
+    createdAt: normalizeDate(promptRecord.created_at ?? promptRecord.createdAt),
+    updatedAt: normalizeDate(promptRecord.updated_at ?? promptRecord.updatedAt),
+    requestMetadata: compactMetadata(extractMetadata(response, payload)),
+  };
+}
+
+export function normalizeVersion(payload: unknown): PromptVersion {
+  const root = unwrap(payload);
+  const versionRecord = isRecord(root.version)
+    ? asUnknownRecord(root.version)
+    : root;
+  const content = normalizeContent(
+    versionRecord.content,
+    versionRecord.messages,
+  );
+  const variables = normalizeVariables(
+    versionRecord.variables,
+    versionRecord.messages,
+  );
+  return normalizeVersionRecord(versionRecord, content, variables);
+}
+
+export function normalizeVersionPage(payload: unknown): Page<PromptVersion> {
+  const root = asUnknownRecord(payload);
+  const unwrapped = asUnknownRecord(root.data ?? root);
+  const entries = Array.isArray(root.data)
+    ? root.data
+    : readArray(unwrapped, "data", "versions");
+  return {
+    data: entries.map((entry) => normalizeVersion(entry)),
+    hasMore:
+      readBoolean(root, "has_more", "hasMore") ??
+      readBoolean(unwrapped, "has_more", "hasMore") ??
+      false,
+    nextCursor:
+      readString(root, "next_cursor", "nextCursor") ??
+      readString(unwrapped, "next_cursor", "nextCursor"),
+  };
+}
+
+function normalizeVersionRecord(
+  version: Record<string, unknown>,
+  content: PromptContent,
+  variables: readonly PromptVariable[],
+): PromptVersion {
+  const status = readString(version, "status") ?? "draft";
+  return {
+    id: readString(version, "id") ?? "",
+    number: readNumber(version, "number", "version") ?? 0,
+    status,
+    active:
+      readBoolean(version, "active", "is_active", "isActive") ??
+      (status === "active" || status === "published"),
+    content,
+    variables,
+    metadata: normalizeJsonRecord(version.metadata),
+    commitMessage: readString(
+      version,
+      "commit_message",
+      "commitMessage",
+      "message",
+    ),
+    createdAt: normalizeDate(version.created_at ?? version.createdAt),
+    updatedAt: normalizeDate(version.updated_at ?? version.updatedAt),
+  };
+}
+
+function normalizeContent(
+  value: unknown,
+  messagesValue: unknown,
+): PromptContent {
+  const content = asUnknownRecord(value);
+  const type = readString(content, "type");
+  const messages = Array.isArray(messagesValue)
+    ? messagesValue
+    : readArray(content, "messages");
+
+  if (type === "chat" || messages.length > 0) {
+    return {
+      type: "chat",
+      messages: messages.map(normalizePromptMessage),
+    };
+  }
+  if (type === "text") {
+    return {
+      type: "text",
+      text: readString(content, "text") ?? "",
+      role: (readString(content, "role") ?? "user") as
+        "system" | "developer" | "user" | "assistant",
+    };
+  }
+  if (typeof value === "string") {
+    return { type: "text", text: value, role: "user" };
+  }
+  return {
+    type: "text",
+    text: readString(content, "text") ?? "",
+    role: "user",
+  };
+}
+
+function normalizePromptMessage(value: unknown) {
+  const message = asUnknownRecord(value);
+  const blocks = readArray(message, "content_blocks", "contentBlocks");
+  if (blocks.length === 0) return normalizeMessage(message);
+
+  const text = blocks
+    .map((entry) => {
+      const block = asUnknownRecord(entry);
+      return readString(block, "text") ?? "";
+    })
+    .join("");
+  return normalizeMessage({ ...message, content: text });
+}
+
+function normalizeVariables(
+  value: unknown,
+  messagesValue: unknown,
+): readonly PromptVariable[] {
+  const direct = Array.isArray(value) ? value : [];
+  if (direct.length > 0) return direct.map(normalizeVariable);
+
+  const variables = new Map<string, PromptVariable>();
+  for (const rawMessage of Array.isArray(messagesValue) ? messagesValue : []) {
+    const message = asUnknownRecord(rawMessage);
+    for (const rawBlock of readArray(
+      message,
+      "content_blocks",
+      "contentBlocks",
+    )) {
+      const block = asUnknownRecord(rawBlock);
+      const metadata = asUnknownRecord(block.metadata);
+      for (const rawVariable of readArray(metadata, "variables")) {
+        const variable = normalizeVariable(rawVariable);
+        if (variable.name) variables.set(variable.name, variable);
+      }
+    }
+  }
+  return [...variables.values()];
+}
+
+function normalizeVariable(value: unknown): PromptVariable {
+  const variable = asUnknownRecord(value);
+  return {
+    name: readString(variable, "name") ?? "",
+    type: (readString(variable, "type") ?? "string") as PromptVariable["type"],
+    required: readBoolean(variable, "required"),
+    description: readString(variable, "description"),
+    default: variable.default as JsonValue | undefined,
+    values: readArray(variable, "values", "enum").filter(
+      (entry): entry is string => typeof entry === "string",
+    ),
+    min: readNumber(variable, "min"),
+    max: readNumber(variable, "max"),
+    minLength: readNumber(variable, "min_length", "minLength"),
+    maxLength: readNumber(variable, "max_length", "maxLength"),
+    itemType: readString(
+      variable,
+      "item_type",
+      "itemType",
+    ) as PromptVariable["itemType"],
+  };
+}
+
+function toWireContent(content: PromptContent): Record<string, unknown> {
+  if (content.type === "text") {
+    return { type: "text", text: content.text, role: content.role };
+  }
+  return {
+    type: "chat",
+    messages: content.messages.map(toWireMessage),
+  };
+}
+
+function toWireVariable(variable: PromptVariable): Record<string, unknown> {
+  return {
+    name: variable.name,
+    type: variable.type,
+    required: variable.required,
+    description: variable.description,
+    default: variable.default,
+    enum: variable.values,
+    min: variable.min,
+    max: variable.max,
+    min_length: variable.minLength,
+    max_length: variable.maxLength,
+    item_type: variable.itemType,
+  };
+}
+
+function normalizeJsonRecord(
+  value: unknown,
+): Readonly<Record<string, JsonValue>> {
+  const record = asUnknownRecord(value);
+  return record as Readonly<Record<string, JsonValue>>;
+}
+
+function normalizeTags(value: unknown): readonly string[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((tag) =>
+      typeof tag === "string"
+        ? tag
+        : readString(asUnknownRecord(tag), "name", "slug"),
+    )
+    .filter((tag): tag is string => tag !== undefined);
+}
+
+function normalizeDate(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (typeof value === "number") {
+    const milliseconds = value < 1_000_000_000_000 ? value * 1_000 : value;
+    return new Date(milliseconds).toISOString();
+  }
+  return undefined;
+}
+
+function unwrap(payload: unknown): Record<string, unknown> {
+  const root = asUnknownRecord(payload);
+  if (root.success === true && root.data !== undefined) {
+    return asUnknownRecord(root.data);
+  }
+  return root;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/prompts/prompts.ts

@@ -0,0 +1,188 @@
+import type { HttpTransport } from "../core/transport.js";
+import type { RequestOptions } from "../core/types.js";
+import { MemoryCache } from "./cache.js";
+import { normalizePrompt, toWirePromptCreate } from "./mappers.js";
+import { renderPrompt } from "./render.js";
+import type {
+  Prompt,
+  PromptCacheConfig,
+  PromptCreateParams,
+  PromptIdentifier,
+  PromptRenderOptions,
+  PromptRenderReference,
+  PromptRetrieveOptions,
+  PromptUpdateParams,
+  PromptVariableValues,
+  RenderedPrompt,
+} from "./types.js";
+import { PromptVersions } from "./versions.js";
+
+export class Prompts {
+  readonly versions: PromptVersions;
+  readonly #transport: HttpTransport;
+  readonly #cache?: MemoryCache<Prompt>;
+  readonly #inflight = new Map<string, Promise<Prompt>>();
+
+  constructor(
+    transport: HttpTransport,
+    config: PromptCacheConfig | false = {},
+  ) {
+    this.#transport = transport;
+    if (config !== false && config.enabled !== false) {
+      this.#cache = new MemoryCache(
+        positiveInteger(config.maxEntries, 100),
+        nonNegativeNumber(config.ttlMs, 60_000),
+      );
+    }
+    this.versions = new PromptVersions(transport, () => this.clearCache());
+  }
+
+  async create(
+    params: PromptCreateParams,
+    options?: RequestOptions,
+  ): Promise<Prompt> {
+    const { data, response } = await this.#transport.request<unknown>({
+      method: "POST",
+      path: "/v1/prompts",
+      body: toWirePromptCreate(params),
+      options,
+    });
+    this.clearCache();
+    return normalizePrompt(data, response);
+  }
+
+  async retrieve(
+    identifier: PromptIdentifier,
+    options: PromptRetrieveOptions = {},
+  ): Promise<Prompt> {
+    const {
+      version = "active",
+      cache = "default",
+      ...requestOptions
+    } = options;
+    const key = cacheKey(identifier, version);
+
+    if (cache === "default") {
+      const cached = this.#cache?.get(key);
+      if (cached) return cached;
+      const pending = this.#inflight.get(key);
+      if (pending) return pending;
+    }
+
+    const pending = this.#retrieveFromApi(
+      identifier,
+      version,
+      requestOptions,
+    ).then((prompt) => {
+      if (cache !== "no-store") this.#cache?.set(key, prompt);
+      return prompt;
+    });
+
+    if (cache === "default") this.#inflight.set(key, pending);
+    try {
+      return await pending;
+    } finally {
+      this.#inflight.delete(key);
+    }
+  }
+
+  async retrieveActive(
+    identifier: PromptIdentifier,
+    options: Omit<PromptRetrieveOptions, "version"> = {},
+  ): Promise<Prompt> {
+    return this.retrieve(identifier, { ...options, version: "active" });
+  }
+
+  async retrieveLatest(
+    identifier: PromptIdentifier,
+    options: Omit<PromptRetrieveOptions, "version"> = {},
+  ): Promise<Prompt> {
+    return this.retrieve(identifier, { ...options, version: "latest" });
+  }
+
+  async update(
+    identifier: PromptIdentifier,
+    params: PromptUpdateParams,
+    options?: RequestOptions,
+  ): Promise<Prompt> {
+    const { data, response } = await this.#transport.request<unknown>({
+      method: "PATCH",
+      path: `/v1/prompts/${encodeURIComponent(identifier)}`,
+      body: {
+        name: params.name,
+        slug: params.slug,
+        description: params.description,
+        metadata: params.metadata,
+        tags: params.tags,
+        folder: params.folder,
+        status: params.status,
+      },
+      options,
+    });
+    this.clearCache();
+    return normalizePrompt(data, response);
+  }
+
+  async render(
+    promptOrReference: Prompt | PromptRenderReference,
+    values: PromptVariableValues = {},
+    options: PromptRenderOptions = {},
+  ): Promise<RenderedPrompt> {
+    const prompt =
+      "content" in promptOrReference
+        ? promptOrReference
+        : await this.retrieve(promptOrReference.id, {
+            version: promptOrReference.version,
+            cache: promptOrReference.cache,
+          });
+    return renderPrompt(prompt, values, options);
+  }
+
+  clearCache(identifier?: PromptIdentifier): void {
+    if (!identifier) {
+      this.#cache?.clear();
+      return;
+    }
+    const encoded = encodeURIComponent(identifier);
+    this.#cache?.deleteMatching(
+      (key) => key.startsWith(`${encoded}:`) || key.includes(`:${encoded}:`),
+    );
+  }
+
+  async #retrieveFromApi(
+    identifier: PromptIdentifier,
+    version: number | "active" | "latest",
+    options: RequestOptions,
+  ): Promise<Prompt> {
+    const encoded = encodeURIComponent(identifier);
+    const { data, response } = await this.#transport.request<unknown>({
+      method: "GET",
+      path: `/v1/prompts/${encoded}`,
+      query: version === "active" ? undefined : { version },
+      options,
+    });
+    return normalizePrompt(data, response);
+  }
+}
+
+function cacheKey(
+  identifier: PromptIdentifier,
+  version: number | "active" | "latest",
+): string {
+  return `${encodeURIComponent(identifier)}:${version}`;
+}
+
+function positiveInteger(value: number | undefined, fallback: number): number {
+  return value !== undefined && Number.isInteger(value) && value > 0
+    ? value
+    : fallback;
+}
+
+function nonNegativeNumber(
+  value: number | undefined,
+  fallback: number,
+): number {
+  return value !== undefined && Number.isFinite(value) && value >= 0
+    ? value
+    : fallback;
+}