@nirmos/sdk 0.1.0 → 0.3.1

package/src/client.ts

@@ -1,70 +1,303 @@
-import { ConfigurationError } from "./core/errors.js";
+import { ConfigurationError, type APIError } from "./core/errors.js";
 import { HttpTransport } from "./core/transport.js";
-import type { HeadersInput } from "./core/types.js";
+import type { HeadersInput, RequestOptions } from "./core/types.js";
+import { Memory } from "./memory/memory.js";
 import { Gateway } from "./gateway/gateway.js";
 import { Prompts } from "./prompts/prompts.js";
 import type { PromptCacheConfig } from "./prompts/types.js";
+import {
+  managementResources,
+  type ManagementResources,
+} from "./management/resources.js";
+import type {
+  StartEvaluationRunRequest,
+  RunMutationResponse,
+  EvaluationRun,
+  EvaluationRunResults,
+  EvaluationRunCases,
+  EvaluationRunCaseDetail,
+  EvaluationResultsQuery,
+} from "./management/execution-types.js";
 
+export type NirmosAuth =
+  | { type: "browser-session" }
+  | { type: "api-key"; key: string }
+  | { type: "access-token"; token: string };
 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. */
+  auth: NirmosAuth;
+  apiBaseUrl?: string;
+  runtimeBaseUrl?: string;
   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;
+  /** Observe HTTP failures centrally, without changing method error semantics. */
+  onError?: (error: APIError) => void;
 }
 
 export class Nirmos {
   readonly gateway: Gateway;
-  readonly prompts: Prompts;
+  readonly auth: ManagementResources["auth"];
+  readonly permissions: ManagementResources["permissions"];
+  /** Runtime prompt rendering/caching protocol; management uses prompts. */
+  readonly managedPrompts: Prompts;
+  readonly apiKeys: ManagementResources["apiKeys"];
+  readonly invitations: ManagementResources["invitations"];
+  readonly logs: ManagementResources["logs"];
+  readonly models: ManagementResources["models"];
+  readonly observability: ManagementResources["observability"];
+  readonly organizations: ManagementResources["organizations"];
+  readonly prompts: ManagementResources["prompts"] & {
+    test: (
+      body: PromptTestRequest,
+      options?: RequestOptions,
+    ) => Promise<PromptTestResponse>;
+  };
+  readonly providerCredentials: ManagementResources["providerCredentials"];
+  readonly providers: ManagementResources["providers"];
+  readonly routes: ManagementResources["routes"];
+  readonly traces: ManagementResources["traces"];
+  readonly users: ManagementResources["users"];
+  readonly vectorStores: ManagementResources["vectorStores"];
+  readonly workspace: ManagementResources["workspace"];
+  readonly endpoints: ManagementResources["endpoints"] & {
+    execute: (
+      id: string,
+      body: {
+        variables?: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
+      },
+      options?: RequestOptions,
+    ) => Promise<EndpointExecution>;
+  };
+  readonly memory: Memory;
+  readonly knowledge: ManagementResources["knowledge"] & {
+    search: (
+      id: string,
+      body: {
+        query: string;
+        topK?: number;
+        minScore?: number;
+        filters?: Record<string, string | number | boolean>;
+      },
+      options?: RequestOptions,
+    ) => Promise<KnowledgeMatch[]>;
+  };
+  readonly evaluations: Omit<ManagementResources["evaluations"], "runs"> & {
+    runs: ManagementResources["evaluations"]["runs"] & {
+      create: (
+        body: StartEvaluationRunRequest,
+        options?: RequestOptions,
+      ) => Promise<RunMutationResponse>;
+      get: (id: string, options?: RequestOptions) => Promise<EvaluationRun>;
+      cancel: (
+        id: string,
+        options?: RequestOptions,
+      ) => Promise<RunMutationResponse>;
+      retry: (
+        id: string,
+        options?: RequestOptions,
+      ) => Promise<RunMutationResponse>;
+      results: (
+        id: string,
+        query?: EvaluationResultsQuery,
+        options?: RequestOptions,
+      ) => Promise<EvaluationRunResults>;
+      cases: (
+        id: string,
+        query?: Pick<EvaluationResultsQuery, "page" | "pageSize">,
+        options?: RequestOptions,
+      ) => Promise<EvaluationRunCases>;
+      case: (
+        id: string,
+        caseId: string,
+        options?: RequestOptions,
+      ) => Promise<EvaluationRunCaseDetail>;
+    };
+  };
 
   constructor(options: NirmosOptions) {
-    validateOptions(options);
-    const transport = new HttpTransport({
-      apiKey: options.apiKey,
-      baseUrl: normalizeBaseUrl(options.baseUrl ?? "https://api.nirmos.com"),
+    if (
+      !options?.auth ||
+      typeof (options.fetch ?? globalThis.fetch) !== "function"
+    )
+      throw configError("Nirmos auth and a fetch implementation are required.");
+    if (options.auth.type === "api-key" && !options.auth.key.trim())
+      throw configError("Nirmos API key is required.");
+    if (options.auth.type === "access-token" && !options.auth.token.trim())
+      throw configError("Nirmos access token is required.");
+    const common = {
+      apiKey: options.auth.type === "api-key" ? options.auth.key : undefined,
+      accessToken:
+        options.auth.type === "access-token" ? options.auth.token : undefined,
+      credentials:
+        options.auth.type === "browser-session"
+          ? ("include" as const)
+          : undefined,
       timeoutMs: nonNegative(options.timeoutMs, 60_000),
       maxRetries: nonNegativeInteger(options.maxRetries, 2),
       fetch: options.fetch ?? globalThis.fetch,
       headers: options.headers,
+      onError: options.onError,
+    };
+    const api = new HttpTransport({
+      ...common,
+      baseUrl: normalizeBaseUrl(options.apiBaseUrl ?? "https://api.nirmos.com"),
     });
-
-    this.prompts = new Prompts(transport, options.promptCache);
-    this.gateway = new Gateway(transport, this.prompts);
+    const runtime = new HttpTransport({
+      ...common,
+      runtime: true,
+      baseUrl: normalizeBaseUrl(
+        options.runtimeBaseUrl ?? "https://gateway.nirmos.com",
+      ),
+    });
+    const resources = managementResources(api);
+    this.permissions = resources.permissions;
+    this.memory = new Memory(resources.memory, runtime);
+    this.auth = resources.auth;
+    this.apiKeys = resources.apiKeys;
+    this.invitations = resources.invitations;
+    this.logs = resources.logs;
+    this.models = resources.models;
+    this.observability = resources.observability;
+    this.organizations = resources.organizations;
+    this.prompts = {
+      ...resources.prompts,
+      test: async (body, options) =>
+        (
+          await runtime.request<PromptTestResponse>({
+            method: "POST",
+            path: "/v1/test/prompt",
+            body,
+            options,
+          })
+        ).data,
+    };
+    this.providerCredentials = resources.providerCredentials;
+    this.providers = resources.providers;
+    this.routes = resources.routes;
+    this.traces = resources.traces;
+    this.users = resources.users;
+    this.vectorStores = resources.vectorStores;
+    this.workspace = resources.workspace;
+    this.endpoints = {
+      ...resources.endpoints,
+      execute: async (id, body, options) =>
+        (
+          await runtime.request<EndpointExecution>({
+            method: "POST",
+            path: `/v1/endpoints/${encodeURIComponent(id)}/execute`,
+            body,
+            options,
+          })
+        ).data,
+    };
+    this.knowledge = {
+      ...resources.knowledge,
+      search: (id, body, options) =>
+        runtime.data<KnowledgeMatch[]>({
+          method: "POST",
+          path: `/v1/knowledge-bases/${encodeURIComponent(id)}/search`,
+          body,
+          options,
+        }),
+    };
+    const runPath = (id: string) =>
+      `/v1/evaluations/runs/${encodeURIComponent(id)}`;
+    const command = async (
+      path: string,
+      body: unknown,
+      options?: RequestOptions,
+    ) =>
+      (
+        await runtime.request<RunMutationResponse>({
+          method: "POST",
+          path,
+          body,
+          options,
+        })
+      ).data;
+    const read = async <T>(
+      path: string,
+      query?: EvaluationResultsQuery,
+      options?: RequestOptions,
+    ) =>
+      (
+        await runtime.request<T>({
+          method: "GET",
+          path,
+          query: { ...query },
+          options,
+        })
+      ).data;
+    this.evaluations = {
+      ...resources.evaluations,
+      runs: {
+        ...resources.evaluations.runs,
+        create: (body, options) =>
+          command("/v1/evaluations/runs", body, options),
+        get: (id, options) =>
+          read<EvaluationRun>(runPath(id), undefined, options),
+        cancel: (id, options) =>
+          command(runPath(id) + "/cancel", undefined, options),
+        retry: (id, options) =>
+          command(runPath(id) + "/retry", undefined, options),
+        results: (id, query, options) =>
+          read<EvaluationRunResults>(runPath(id) + "/results", query, options),
+        cases: (id, query, options) =>
+          read<EvaluationRunCases>(runPath(id) + "/cases", query, options),
+        case: (id, caseId, options) =>
+          read<EvaluationRunCaseDetail>(
+            runPath(id) + "/cases/" + encodeURIComponent(caseId),
+            undefined,
+            options,
+          ),
+      },
+    };
+    this.managedPrompts = new Prompts(runtime, options.promptCache);
+    this.gateway = new Gateway(runtime, this.managedPrompts);
   }
 }
 
-/** 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.",
-    );
-  }
+export interface KnowledgeMatch {
+  chunkId: string;
+  documentId: string;
+  content: string;
+  score: number;
+  metadata: Record<string, string | number | boolean> | null;
+  source: { title: string; uri: string | null; type: string };
+}
+export interface EndpointExecution {
+  success: boolean;
+  data: {
+    output: unknown;
+    raw_content?: string;
+    model: string;
+    provider: string;
+    output_valid: boolean;
+    repair_attempts: number;
+  };
+  usage: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+  meta: {
+    endpoint_id: string;
+    version_id: string;
+    prompt_version_id: string;
+    request_id: string;
+    trace_id: string;
+    latency_ms: number;
+  };
 }
-
 function normalizeBaseUrl(value: string): string {
   let url: URL;
   try {
     url = new URL(value);
   } catch {
-    throw configError("Nirmos baseUrl must be a valid absolute URL.");
+    throw configError("Nirmos base URL must be a valid absolute URL.");
   }
   return url.toString().replace(/\/+$/, "");
 }
@@ -87,3 +320,53 @@ function nonNegativeInteger(
 function configError(message: string): ConfigurationError {
   return new ConfigurationError(message);
 }
+
+export interface PromptTestRequest {
+  messages: Array<{
+    role: string;
+    name?: string | null;
+    order?: number;
+    contentBlocks: Array<{
+      order?: number;
+      type: string;
+      text?: string | null;
+      uri?: string | null;
+      mimeType?: string | null;
+      data?: unknown;
+    }>;
+  }>;
+  selectedModel?: string;
+  temperature?: number;
+  maxTokens?: number;
+  topP?: number;
+  variables?: string[];
+  variablesInput?: Record<string, unknown>;
+  provider?: string;
+  structuredOutput?: unknown;
+}
+export interface PromptTestResponse {
+  success: boolean;
+  data?: {
+    output?: unknown;
+    raw_content?: string;
+    model?: string;
+    provider?: string;
+    output_valid?: boolean;
+    repair_attempts?: number;
+    structuredOutput?: {
+      validationPassed?: boolean;
+      validationErrors?: string[];
+      healingDetails?: {
+        llmRetryUsed?: boolean;
+        programmaticApplied?: boolean;
+      };
+    };
+  };
+  error?: string;
+  usage?: {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+  };
+  meta?: { latency_ms?: number; request_id?: string; trace_id?: string };
+}

package/src/core/errors.ts

@@ -5,12 +5,16 @@ export interface NirmosErrorOptions {
   code?: string;
   requestId?: string;
   traceId?: string;
+  status?: number;
+  details?: unknown;
 }
 
 export class NirmosError extends Error {
   readonly code?: string;
   readonly requestId?: string;
   readonly traceId?: string;
+  readonly status?: number;
+  readonly details?: unknown;
 
   constructor(message: string, options: NirmosErrorOptions = {}) {
     super(message, { cause: options.cause });
@@ -18,6 +22,8 @@ export class NirmosError extends Error {
     this.code = options.code;
     this.requestId = options.requestId;
     this.traceId = options.traceId;
+    this.status = options.status;
+    this.details = options.details;
   }
 }
 
@@ -41,10 +47,10 @@ export interface APIErrorOptions extends NirmosErrorOptions {
 }
 
 export class APIError extends NirmosError {
-  readonly status: number;
+  declare readonly status: number;
   readonly retryable: boolean;
   readonly retryAfterMs?: number;
-  readonly details?: unknown;
+  declare readonly details?: unknown;
   readonly metadata?: RequestMetadata;
   readonly headers?: Headers;
 

package/src/core/metadata.ts

@@ -62,20 +62,11 @@ export function extractMetadata(
       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 cacheStatus = header(response, "nirmos-cache-status");
+  const cacheLayer = header(response, "nirmos-cache-layer");
   const remainingTtlSeconds = numericHeader(
     response,
-    "x-nirmos-cache-remaining-ttl",
-    "x-promptnetra-cache-remaining-ttl",
+    "nirmos-cache-remaining-ttl",
   );
 
   if (cacheStatus || cacheLayer || remainingTtlSeconds !== undefined) {

package/src/core/transport.ts

@@ -20,7 +20,11 @@ import {
 import type { HeadersInput, RequestOptions } from "./types.js";
 
 export interface TransportConfig {
-  apiKey: string;
+  apiKey?: string;
+  accessToken?: string;
+  credentials?: RequestCredentials;
+  runtime?: boolean;
+  onError?: (error: APIError) => void;
   baseUrl: string;
   timeoutMs: number;
   maxRetries: number;
@@ -31,7 +35,9 @@ export interface TransportConfig {
 export interface TransportRequest {
   method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
   path: string;
-  query?: Readonly<Record<string, string | number | boolean | undefined>>;
+  query?: Readonly<
+    Record<string, string | number | boolean | readonly string[] | undefined>
+  >;
   body?: unknown;
   options?: RequestOptions;
 }
@@ -41,7 +47,7 @@ export interface TransportResponse<T> {
   response: Response;
 }
 
-const SDK_VERSION = "1.0.0";
+const SDK_VERSION = "0.3.0";
 
 export class HttpTransport {
   readonly #config: TransportConfig;
@@ -55,16 +61,26 @@ export class HttpTransport {
     const data = await parseResponseBody(response);
 
     if (!response.ok) {
-      throw createApiError(response, data);
+      const error = createApiError(response, data);
+      this.#config.onError?.(error);
+      throw error;
     }
 
     return { data: data as T, response };
   }
 
+  /** Control-plane and Knowledge envelope decoder; no raw Response at callsites. */
+  async data<T>(request: TransportRequest): Promise<T> {
+    const { data } = await this.request<{ data: T } | undefined>(request);
+    return data?.data as T;
+  }
+
   async ensureSuccess(response: Response): Promise<Response> {
     if (response.ok) return response;
     const data = await parseResponseBody(response);
-    throw createApiError(response, data);
+    const error = createApiError(response, data);
+    this.#config.onError?.(error);
+    throw error;
   }
 
   async fetch(request: TransportRequest): Promise<Response> {
@@ -146,7 +162,12 @@ export class HttpTransport {
         method: request.method,
         headers: this.#headers(request),
         body:
-          request.body === undefined ? undefined : JSON.stringify(request.body),
+          request.body === undefined
+            ? undefined
+            : request.body instanceof FormData
+              ? request.body
+              : JSON.stringify(request.body),
+        credentials: this.#config.credentials,
         signal: controller.signal,
       });
       if (!response.body) return response;
@@ -207,7 +228,9 @@ export class HttpTransport {
       `${this.#config.baseUrl}/`,
     );
     for (const [key, value] of Object.entries(request.query ?? {})) {
-      if (value !== undefined) url.searchParams.set(key, String(value));
+      if (Array.isArray(value))
+        for (const item of value) url.searchParams.append(key + "[]", item);
+      else if (value !== undefined) url.searchParams.set(key, String(value));
     }
     return url.toString();
   }
@@ -215,14 +238,24 @@ export class HttpTransport {
   #headers(request: TransportRequest): Headers {
     const headers = createHeaders(this.#config.headers);
     headers.set("accept", "application/json");
-    headers.set("x-api-key", this.#config.apiKey);
     headers.set("x-nirmos-sdk-version", SDK_VERSION);
-    if (request.body !== undefined) {
+    if (request.body !== undefined && !(request.body instanceof FormData)) {
       headers.set("content-type", "application/json");
     }
     createHeaders(request.options?.headers).forEach((value, key) => {
-      if (key.toLowerCase() !== "x-api-key") headers.set(key, value);
+      if (!["x-api-key", "authorization"].includes(key.toLowerCase()))
+        headers.set(key, value);
     });
+    if (this.#config.apiKey) headers.set("x-api-key", this.#config.apiKey);
+    if (this.#config.accessToken)
+      headers.set("authorization", `Bearer ${this.#config.accessToken}`);
+    if (
+      this.#config.runtime &&
+      !["GET", "HEAD", "OPTIONS"].includes(request.method)
+    ) {
+      headers.set("x-request-timestamp", String(Date.now()));
+      headers.set("x-request-nonce", globalThis.crypto.randomUUID());
+    }
     if (request.options?.idempotencyKey) {
       headers.set("idempotency-key", request.options.idempotencyKey);
     }
@@ -261,7 +294,10 @@ function createApiError(response: Response, payload: unknown): APIError {
     retryAfterMs,
     details: error.details,
     metadata,
-    requestId: metadata.requestId,
+    requestId:
+      readString(error, "requestId") ??
+      readString(root, "requestId") ??
+      metadata.requestId,
     traceId: metadata.traceId,
     headers: response.headers,
   };

package/src/gateway/chat.ts

@@ -53,10 +53,8 @@ export class Chat {
     params: ChatCreateParams,
     stream: boolean,
   ): Promise<Record<string, unknown>> {
+    validateTarget(params);
     const messages = await this.#messages(params);
-    if (!params.model.trim()) {
-      throw localValidation("model", "Model is required.");
-    }
     if (messages.length === 0) {
       throw localValidation(
         "messages",
@@ -66,6 +64,7 @@ export class Chat {
 
     return {
       model: params.model,
+      route: params.route,
       messages: messages.map(toWireMessage),
       stream,
       temperature: params.temperature,
@@ -103,6 +102,27 @@ export class Chat {
   }
 }
 
+function validateTarget(params: ChatCreateParams): void {
+  const hasModel = params.model !== undefined;
+  const hasRoute = params.route !== undefined;
+
+  if (hasModel && hasRoute) {
+    throw localValidation(
+      "model,route",
+      "Provide either model or route, but not both.",
+    );
+  }
+  if (!hasModel && !hasRoute) {
+    throw localValidation("model,route", "Provide either model or route.");
+  }
+  if (hasModel && (typeof params.model !== "string" || !params.model.trim())) {
+    throw localValidation("model", "Model is required.");
+  }
+  if (hasRoute && (typeof params.route !== "string" || !params.route.trim())) {
+    throw localValidation("route", "Route is required.");
+  }
+}
+
 function toWireResponseFormat(
   format: ResponseFormat | undefined,
 ): Record<string, unknown> | undefined {