@nirmos/sdk 0.1.0

package/dist/esm/prompts/versions.js

@@ -0,0 +1,47 @@
+import { normalizeVersion, normalizeVersionPage, toWireVersionCreate, } from "./mappers.js";
+export class PromptVersions {
+    #transport;
+    #invalidate;
+    constructor(transport, invalidate) {
+        this.#transport = transport;
+        this.#invalidate = invalidate;
+    }
+    async create(identifier, params, options) {
+        const { data } = await this.#transport.request({
+            method: "POST",
+            path: `/v1/prompts/${encodeURIComponent(identifier)}/versions`,
+            body: toWireVersionCreate(params),
+            options,
+        });
+        this.#invalidate();
+        return normalizeVersion(data);
+    }
+    async retrieve(identifier, version, options) {
+        const { data } = await this.#transport.request({
+            method: "GET",
+            path: `/v1/prompts/${encodeURIComponent(identifier)}/versions/${version}`,
+            options,
+        });
+        return normalizeVersion(data);
+    }
+    async list(identifier, options = {}) {
+        const { limit, cursor, ...requestOptions } = options;
+        const { data } = await this.#transport.request({
+            method: "GET",
+            path: `/v1/prompts/${encodeURIComponent(identifier)}/versions`,
+            query: { limit, cursor },
+            options: requestOptions,
+        });
+        return normalizeVersionPage(data);
+    }
+    async activate(identifier, version, options) {
+        const { data } = await this.#transport.request({
+            method: "POST",
+            path: `/v1/prompts/${encodeURIComponent(identifier)}/versions/${version}/activate`,
+            options,
+        });
+        this.#invalidate();
+        return normalizeVersion(data);
+    }
+}
+//# sourceMappingURL=versions.js.map

package/dist/esm/prompts/versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.js","sourceRoot":"","sources":["../../../src/prompts/versions.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAStB,MAAM,OAAO,cAAc;IAChB,UAAU,CAAgB;IAC1B,WAAW,CAAa;IAEjC,YAAY,SAAwB,EAAE,UAAsB;QAC1D,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC;IAChC,CAAC;IAED,KAAK,CAAC,MAAM,CACV,UAA4B,EAC5B,MAAiC,EACjC,OAAwB;QAExB,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAU;YACtD,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,eAAe,kBAAkB,CAAC,UAAU,CAAC,WAAW;YAC9D,IAAI,EAAE,mBAAmB,CAAC,MAAM,CAAC;YACjC,OAAO;SACR,CAAC,CAAC;QACH,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,UAA4B,EAC5B,OAAe,EACf,OAAwB;QAExB,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAU;YACtD,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,eAAe,kBAAkB,CAAC,UAAU,CAAC,aAAa,OAAO,EAAE;YACzE,OAAO;SACR,CAAC,CAAC;QACH,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,KAAK,CAAC,IAAI,CACR,UAA4B,EAC5B,UAAoC,EAAE;QAEtC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,GAAG,OAAO,CAAC;QACrD,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAU;YACtD,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,eAAe,kBAAkB,CAAC,UAAU,CAAC,WAAW;YAC9D,KAAK,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;YACxB,OAAO,EAAE,cAAc;SACxB,CAAC,CAAC;QACH,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,UAA4B,EAC5B,OAAe,EACf,OAAwB;QAExB,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAU;YACtD,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,eAAe,kBAAkB,CAAC,UAAU,CAAC,aAAa,OAAO,WAAW;YAClF,OAAO;SACR,CAAC,CAAC;QACH,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;CACF"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@nirmos/sdk",
+  "version": "0.1.0",
+  "description": "Official TypeScript SDK for the Nirmos AI platform.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "scripts": {
+    "build": "node ./scripts/clean.mjs && tsc -p tsconfig.build.json && tsc -p tsconfig.cjs.json && node ./scripts/write-cjs-package.mjs",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint src tests --max-warnings 0",
+    "prepack": "pnpm build",
+    "test": "pnpm build && tsc -p tests/tsconfig.json && node --test tests/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "nirmos",
+    "ai",
+    "llm",
+    "gateway",
+    "prompts",
+    "sdk"
+  ],
+  "devDependencies": {
+    "@repo/eslint-config": "workspace:*",
+    "@repo/typescript-config": "workspace:*",
+    "eslint": "^9.39.1",
+    "typescript": "5.9.2"
+  }
+}

package/src/client.ts

@@ -0,0 +1,89 @@
+import { ConfigurationError } from "./core/errors.js";
+import { HttpTransport } from "./core/transport.js";
+import type { HeadersInput } from "./core/types.js";
+import { Gateway } from "./gateway/gateway.js";
+import { Prompts } from "./prompts/prompts.js";
+import type { PromptCacheConfig } from "./prompts/types.js";
+
+export interface NirmosOptions {
+  /** Nirmos API key. Keep this key on trusted servers. */
+  apiKey: string;
+  /** API origin. Defaults to https://api.nirmos.com. */
+  baseUrl?: string;
+  /** Default request timeout. Defaults to 60 seconds. Set to 0 to disable. */
+  timeoutMs?: number;
+  /** Retry count for safe GET requests. Defaults to 2. */
+  maxRetries?: number;
+  /** Custom fetch implementation for tests or specialized runtimes. */
+  fetch?: typeof globalThis.fetch;
+  /** Headers added to every request. */
+  headers?: HeadersInput;
+  /** In-memory managed prompt cache configuration. Set false to disable. */
+  promptCache?: PromptCacheConfig | false;
+}
+
+export class Nirmos {
+  readonly gateway: Gateway;
+  readonly prompts: Prompts;
+
+  constructor(options: NirmosOptions) {
+    validateOptions(options);
+    const transport = new HttpTransport({
+      apiKey: options.apiKey,
+      baseUrl: normalizeBaseUrl(options.baseUrl ?? "https://api.nirmos.com"),
+      timeoutMs: nonNegative(options.timeoutMs, 60_000),
+      maxRetries: nonNegativeInteger(options.maxRetries, 2),
+      fetch: options.fetch ?? globalThis.fetch,
+      headers: options.headers,
+    });
+
+    this.prompts = new Prompts(transport, options.promptCache);
+    this.gateway = new Gateway(transport, this.prompts);
+  }
+}
+
+/** Explicit alias for codebases that prefer client-suffixed class names. */
+export { Nirmos as NirmosClient };
+
+function validateOptions(options: NirmosOptions): void {
+  if (!options || typeof options !== "object") {
+    throw configError("Nirmos options are required.");
+  }
+  if (!options.apiKey || !options.apiKey.trim()) {
+    throw configError("Nirmos apiKey is required.");
+  }
+  if (typeof (options.fetch ?? globalThis.fetch) !== "function") {
+    throw configError(
+      "No fetch implementation found. Provide options.fetch in this runtime.",
+    );
+  }
+}
+
+function normalizeBaseUrl(value: string): string {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw configError("Nirmos baseUrl must be a valid absolute URL.");
+  }
+  return url.toString().replace(/\/+$/, "");
+}
+
+function nonNegative(value: number | undefined, fallback: number): number {
+  return value !== undefined && Number.isFinite(value) && value >= 0
+    ? value
+    : fallback;
+}
+
+function nonNegativeInteger(
+  value: number | undefined,
+  fallback: number,
+): number {
+  return value !== undefined && Number.isInteger(value) && value >= 0
+    ? value
+    : fallback;
+}
+
+function configError(message: string): ConfigurationError {
+  return new ConfigurationError(message);
+}

package/src/core/errors.ts

@@ -0,0 +1,160 @@
+import type { RequestMetadata } from "./types.js";
+
+export interface NirmosErrorOptions {
+  cause?: unknown;
+  code?: string;
+  requestId?: string;
+  traceId?: string;
+}
+
+export class NirmosError extends Error {
+  readonly code?: string;
+  readonly requestId?: string;
+  readonly traceId?: string;
+
+  constructor(message: string, options: NirmosErrorOptions = {}) {
+    super(message, { cause: options.cause });
+    this.name = "NirmosError";
+    this.code = options.code;
+    this.requestId = options.requestId;
+    this.traceId = options.traceId;
+  }
+}
+
+export class ConfigurationError extends NirmosError {
+  constructor(message: string, options: NirmosErrorOptions = {}) {
+    super(message, {
+      ...options,
+      code: options.code ?? "SDK_CONFIGURATION_ERROR",
+    });
+    this.name = "ConfigurationError";
+  }
+}
+
+export interface APIErrorOptions extends NirmosErrorOptions {
+  status: number;
+  retryable?: boolean;
+  retryAfterMs?: number;
+  details?: unknown;
+  metadata?: RequestMetadata;
+  headers?: Headers;
+}
+
+export class APIError extends NirmosError {
+  readonly status: number;
+  readonly retryable: boolean;
+  readonly retryAfterMs?: number;
+  readonly details?: unknown;
+  readonly metadata?: RequestMetadata;
+  readonly headers?: Headers;
+
+  constructor(message: string, options: APIErrorOptions) {
+    super(message, options);
+    this.name = "APIError";
+    this.status = options.status;
+    this.retryable = options.retryable ?? false;
+    this.retryAfterMs = options.retryAfterMs;
+    this.details = options.details;
+    this.metadata = options.metadata;
+    this.headers = options.headers;
+  }
+}
+
+export class AuthenticationError extends APIError {
+  constructor(message: string, options: APIErrorOptions) {
+    super(message, options);
+    this.name = "AuthenticationError";
+  }
+}
+
+export class PermissionDeniedError extends APIError {
+  constructor(message: string, options: APIErrorOptions) {
+    super(message, options);
+    this.name = "PermissionDeniedError";
+  }
+}
+
+export class NotFoundError extends APIError {
+  constructor(message: string, options: APIErrorOptions) {
+    super(message, options);
+    this.name = "NotFoundError";
+  }
+}
+
+export class ConflictError extends APIError {
+  constructor(message: string, options: APIErrorOptions) {
+    super(message, options);
+    this.name = "ConflictError";
+  }
+}
+
+export class ValidationError extends APIError {
+  constructor(message: string, options: APIErrorOptions) {
+    super(message, options);
+    this.name = "ValidationError";
+  }
+}
+
+export class RateLimitError extends APIError {
+  constructor(message: string, options: APIErrorOptions) {
+    super(message, options);
+    this.name = "RateLimitError";
+  }
+}
+
+export class ServerError extends APIError {
+  constructor(message: string, options: APIErrorOptions) {
+    super(message, options);
+    this.name = "ServerError";
+  }
+}
+
+export class TimeoutError extends NirmosError {
+  readonly timeoutMs: number;
+
+  constructor(timeoutMs: number, options: NirmosErrorOptions = {}) {
+    super(`Request timed out after ${timeoutMs}ms.`, {
+      ...options,
+      code: options.code ?? "REQUEST_TIMEOUT",
+    });
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+export class RequestAbortedError extends NirmosError {
+  constructor(options: NirmosErrorOptions = {}) {
+    super("Request was aborted.", {
+      ...options,
+      code: options.code ?? "REQUEST_ABORTED",
+    });
+    this.name = "RequestAbortedError";
+  }
+}
+
+export class NetworkError extends NirmosError {
+  constructor(cause?: unknown) {
+    super("Unable to reach the Nirmos API.", {
+      cause,
+      code: "NETWORK_ERROR",
+    });
+    this.name = "NetworkError";
+  }
+}
+
+export class StreamError extends NirmosError {
+  constructor(message: string, options: NirmosErrorOptions = {}) {
+    super(message, { ...options, code: options.code ?? "STREAM_ERROR" });
+    this.name = "StreamError";
+  }
+}
+
+export class PromptRenderError extends NirmosError {
+  readonly missingVariables: readonly string[];
+
+  constructor(message: string, missingVariables: readonly string[] = []) {
+    super(message, { code: "PROMPT_RENDER_ERROR" });
+    this.name = "PromptRenderError";
+    this.missingVariables = missingVariables;
+  }
+}

package/src/core/metadata.ts

@@ -0,0 +1,141 @@
+import type { RequestMetadata } from "./types.js";
+
+type UnknownRecord = Record<string, unknown>;
+
+function asRecord(value: unknown): UnknownRecord | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as UnknownRecord)
+    : undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function numberValue(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
+function header(response: Response, ...names: string[]): string | undefined {
+  for (const name of names) {
+    const value = response.headers.get(name);
+    if (value) return value;
+  }
+  return undefined;
+}
+
+function numericHeader(
+  response: Response,
+  ...names: string[]
+): number | undefined {
+  const value = header(response, ...names);
+  if (!value) return undefined;
+  const number = Number.parseFloat(value.replace(/ms$/i, ""));
+  return Number.isFinite(number) ? number : undefined;
+}
+
+export function extractMetadata(
+  response: Response,
+  payload?: unknown,
+): RequestMetadata {
+  const root = asRecord(payload);
+  const bodyMeta =
+    asRecord(root?._meta) ?? asRecord(root?.meta) ?? asRecord(root?.metadata);
+
+  const metadata: RequestMetadata = {
+    requestId:
+      stringValue(bodyMeta?.request_id) ??
+      stringValue(bodyMeta?.requestId) ??
+      header(response, "x-nirmos-request-id", "x-request-id"),
+    traceId:
+      stringValue(bodyMeta?.trace_id) ??
+      stringValue(bodyMeta?.traceId) ??
+      header(response, "x-nirmos-trace-id", "x-trace-id"),
+    provider:
+      stringValue(bodyMeta?.provider) ?? header(response, "x-nirmos-provider"),
+    model: stringValue(bodyMeta?.model) ?? header(response, "x-nirmos-model"),
+    latencyMs:
+      numberValue(bodyMeta?.latency_ms) ??
+      numberValue(bodyMeta?.latencyMs) ??
+      numericHeader(response, "x-nirmos-response-time", "x-response-time"),
+  };
+
+  const cacheStatus = header(
+    response,
+    "x-nirmos-cache-status",
+    "x-promptnetra-cache-status",
+  );
+  const cacheLayer = header(
+    response,
+    "x-nirmos-cache-layer",
+    "x-promptnetra-cache-layer",
+  );
+  const remainingTtlSeconds = numericHeader(
+    response,
+    "x-nirmos-cache-remaining-ttl",
+    "x-promptnetra-cache-remaining-ttl",
+  );
+
+  if (cacheStatus || cacheLayer || remainingTtlSeconds !== undefined) {
+    metadata.cache = {
+      status: cacheStatus,
+      layer: cacheLayer,
+      remainingTtlSeconds,
+    };
+  }
+
+  return metadata;
+}
+
+export function compactMetadata(metadata: RequestMetadata): RequestMetadata {
+  return Object.fromEntries(
+    Object.entries(metadata).filter(([, value]) => value !== undefined),
+  ) as RequestMetadata;
+}
+
+export function asUnknownRecord(value: unknown): UnknownRecord {
+  return asRecord(value) ?? {};
+}
+
+export function readString(
+  record: UnknownRecord,
+  ...keys: string[]
+): string | undefined {
+  for (const key of keys) {
+    const value = stringValue(record[key]);
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+export function readNumber(
+  record: UnknownRecord,
+  ...keys: string[]
+): number | undefined {
+  for (const key of keys) {
+    const value = numberValue(record[key]);
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+export function readBoolean(
+  record: UnknownRecord,
+  ...keys: string[]
+): boolean | undefined {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "boolean") return value;
+  }
+  return undefined;
+}
+
+export function readArray(record: UnknownRecord, ...keys: string[]): unknown[] {
+  for (const key of keys) {
+    const value = record[key];
+    if (Array.isArray(value)) return value;
+  }
+  return [];
+}