@nirmos/sdk 0.1.0

package/src/core/transport.ts

@@ -0,0 +1,331 @@
+import {
+  APIError,
+  AuthenticationError,
+  ConflictError,
+  NetworkError,
+  NotFoundError,
+  PermissionDeniedError,
+  RateLimitError,
+  RequestAbortedError,
+  ServerError,
+  TimeoutError,
+  ValidationError,
+} from "./errors.js";
+import {
+  asUnknownRecord,
+  extractMetadata,
+  readBoolean,
+  readString,
+} from "./metadata.js";
+import type { HeadersInput, RequestOptions } from "./types.js";
+
+export interface TransportConfig {
+  apiKey: string;
+  baseUrl: string;
+  timeoutMs: number;
+  maxRetries: number;
+  fetch: typeof globalThis.fetch;
+  headers?: HeadersInput;
+}
+
+export interface TransportRequest {
+  method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+  path: string;
+  query?: Readonly<Record<string, string | number | boolean | undefined>>;
+  body?: unknown;
+  options?: RequestOptions;
+}
+
+export interface TransportResponse<T> {
+  data: T;
+  response: Response;
+}
+
+const SDK_VERSION = "1.0.0";
+
+export class HttpTransport {
+  readonly #config: TransportConfig;
+
+  constructor(config: TransportConfig) {
+    this.#config = config;
+  }
+
+  async request<T>(request: TransportRequest): Promise<TransportResponse<T>> {
+    const response = await this.fetch(request);
+    const data = await parseResponseBody(response);
+
+    if (!response.ok) {
+      throw createApiError(response, data);
+    }
+
+    return { data: data as T, response };
+  }
+
+  async ensureSuccess(response: Response): Promise<Response> {
+    if (response.ok) return response;
+    const data = await parseResponseBody(response);
+    throw createApiError(response, data);
+  }
+
+  async fetch(request: TransportRequest): Promise<Response> {
+    const maxRetries = request.options?.maxRetries ?? this.#config.maxRetries;
+    const retryableMethod =
+      request.method === "GET" || request.options?.idempotencyKey !== undefined;
+    let attempt = 0;
+
+    while (true) {
+      try {
+        const response = await this.#fetchOnce(request);
+        if (
+          retryableMethod &&
+          attempt < maxRetries &&
+          isRetryableStatus(response.status)
+        ) {
+          await response.body?.cancel();
+          await waitBeforeRetry(response, attempt, request.options?.signal);
+          attempt += 1;
+          continue;
+        }
+        return response;
+      } catch (error) {
+        if (
+          retryableMethod &&
+          attempt < maxRetries &&
+          error instanceof NetworkError
+        ) {
+          await wait(250 * 2 ** attempt, request.options?.signal);
+          attempt += 1;
+          continue;
+        }
+        throw error;
+      }
+    }
+  }
+
+  async #fetchOnce(request: TransportRequest): Promise<Response> {
+    const timeoutMs = request.options?.timeoutMs ?? this.#config.timeoutMs;
+    const controller = new AbortController();
+    let timedOut = false;
+    let externallyAborted = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let responseOwnsCleanup = false;
+    let cleanedUp = false;
+
+    const abortFromSignal = () => {
+      externallyAborted = true;
+      controller.abort(request.options?.signal?.reason);
+      cleanup();
+    };
+    const cleanup = () => {
+      if (cleanedUp) return;
+      cleanedUp = true;
+      if (timer) clearTimeout(timer);
+      request.options?.signal?.removeEventListener("abort", abortFromSignal);
+    };
+
+    if (request.options?.signal?.aborted) {
+      throw new RequestAbortedError({
+        cause: request.options.signal.reason,
+      });
+    }
+
+    request.options?.signal?.addEventListener("abort", abortFromSignal, {
+      once: true,
+    });
+
+    if (timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+        cleanup();
+      }, timeoutMs);
+    }
+
+    try {
+      const response = await this.#config.fetch(this.#url(request), {
+        method: request.method,
+        headers: this.#headers(request),
+        body:
+          request.body === undefined ? undefined : JSON.stringify(request.body),
+        signal: controller.signal,
+      });
+      if (!response.body) return response;
+
+      responseOwnsCleanup = true;
+      const reader = response.body.getReader();
+      const body = new ReadableStream<Uint8Array>({
+        async pull(streamController) {
+          try {
+            const { done, value } = await reader.read();
+            if (done) {
+              cleanup();
+              streamController.close();
+            } else {
+              streamController.enqueue(value);
+            }
+          } catch (error) {
+            cleanup();
+            if (timedOut) {
+              streamController.error(
+                new TimeoutError(timeoutMs, { cause: error }),
+              );
+            } else if (externallyAborted || request.options?.signal?.aborted) {
+              streamController.error(new RequestAbortedError({ cause: error }));
+            } else {
+              streamController.error(new NetworkError(error));
+            }
+          }
+        },
+        async cancel(reason) {
+          try {
+            await reader.cancel(reason);
+          } finally {
+            cleanup();
+          }
+        },
+      });
+
+      return new Response(body, {
+        headers: response.headers,
+        status: response.status,
+        statusText: response.statusText,
+      });
+    } catch (error) {
+      if (timedOut) throw new TimeoutError(timeoutMs, { cause: error });
+      if (externallyAborted || request.options?.signal?.aborted) {
+        throw new RequestAbortedError({ cause: error });
+      }
+      throw new NetworkError(error);
+    } finally {
+      if (!responseOwnsCleanup) cleanup();
+    }
+  }
+
+  #url(request: TransportRequest): string {
+    const url = new URL(
+      request.path.replace(/^\//, ""),
+      `${this.#config.baseUrl}/`,
+    );
+    for (const [key, value] of Object.entries(request.query ?? {})) {
+      if (value !== undefined) url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+  }
+
+  #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) {
+      headers.set("content-type", "application/json");
+    }
+    createHeaders(request.options?.headers).forEach((value, key) => {
+      if (key.toLowerCase() !== "x-api-key") headers.set(key, value);
+    });
+    if (request.options?.idempotencyKey) {
+      headers.set("idempotency-key", request.options.idempotencyKey);
+    }
+    return headers;
+  }
+}
+
+async function parseResponseBody(response: Response): Promise<unknown> {
+  if (response.status === 204) return undefined;
+  const text = await response.text();
+  if (!text) return undefined;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+function createApiError(response: Response, payload: unknown): APIError {
+  const root = asUnknownRecord(payload);
+  const error = asUnknownRecord(root.error);
+  const metadata = extractMetadata(response, payload);
+  const message =
+    (readString(error, "message") ??
+      readString(root, "message") ??
+      response.statusText) ||
+    "Nirmos API request failed.";
+  const code = readString(error, "code", "type") ?? readString(root, "code");
+  const retryable =
+    readBoolean(error, "retryable") ?? isRetryableStatus(response.status);
+  const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
+  const options = {
+    status: response.status,
+    code,
+    retryable,
+    retryAfterMs,
+    details: error.details,
+    metadata,
+    requestId: metadata.requestId,
+    traceId: metadata.traceId,
+    headers: response.headers,
+  };
+
+  if (response.status === 401) return new AuthenticationError(message, options);
+  if (response.status === 403)
+    return new PermissionDeniedError(message, options);
+  if (response.status === 404) return new NotFoundError(message, options);
+  if (response.status === 409) return new ConflictError(message, options);
+  if (response.status === 422 || response.status === 400) {
+    return new ValidationError(message, options);
+  }
+  if (response.status === 429) return new RateLimitError(message, options);
+  if (response.status >= 500) return new ServerError(message, options);
+  return new APIError(message, options);
+}
+
+function isRetryableStatus(status: number): boolean {
+  return status === 408 || status === 429 || status >= 500;
+}
+
+function parseRetryAfter(value: string | null): number | undefined {
+  if (!value) return undefined;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1_000);
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
+
+async function waitBeforeRetry(
+  response: Response,
+  attempt: number,
+  signal?: AbortSignal,
+): Promise<void> {
+  const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
+  await wait(retryAfter ?? 250 * 2 ** attempt, signal);
+}
+
+async function wait(milliseconds: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) {
+    throw new RequestAbortedError({ cause: signal.reason });
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    const finish = () => {
+      signal?.removeEventListener("abort", abort);
+      resolve();
+    };
+    const timer = setTimeout(finish, milliseconds);
+    const abort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      reject(new RequestAbortedError({ cause: signal?.reason }));
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+  });
+}
+
+function createHeaders(input?: HeadersInput): Headers {
+  if (!input) return new Headers();
+  if (Array.isArray(input)) {
+    return new Headers(
+      input.map(([key, value]) => [key, value] as [string, string]),
+    );
+  }
+  return new Headers(input as HeadersInit);
+}

package/src/core/types.ts

@@ -0,0 +1,51 @@
+export type JsonPrimitive = string | number | boolean | null;
+
+export type JsonValue =
+  JsonPrimitive | { readonly [key: string]: JsonValue } | readonly JsonValue[];
+
+export type HeadersInput =
+  | Headers
+  | Readonly<Record<string, string>>
+  | readonly (readonly [string, string])[];
+
+export interface RequestOptions {
+  /** Cancels this request when aborted. */
+  signal?: AbortSignal;
+  /** Overrides the client timeout for this request. Set to 0 to disable. */
+  timeoutMs?: number;
+  /** Adds headers to this request. Client authentication headers cannot be overridden. */
+  headers?: HeadersInput;
+  /** Enables safe retries for a mutation when the API supports this key. */
+  idempotencyKey?: string;
+  /** Overrides the configured retry count for this request. */
+  maxRetries?: number;
+}
+
+export interface RequestMetadata {
+  requestId?: string;
+  traceId?: string;
+  provider?: string;
+  model?: string;
+  latencyMs?: number;
+  cache?: {
+    status?: string;
+    layer?: string;
+    remainingTtlSeconds?: number;
+  };
+}
+
+export interface Usage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  cachedTokens?: number;
+  reasoningTokens?: number;
+}
+
+export interface Page<T> {
+  data: readonly T[];
+  hasMore: boolean;
+  nextCursor?: string;
+}
+
+export type ExtensibleString<T extends string> = T | (string & {});

package/src/gateway/chat-stream.ts

@@ -0,0 +1,307 @@
+import { NirmosError, StreamError } from "../core/errors.js";
+import {
+  asUnknownRecord,
+  compactMetadata,
+  extractMetadata,
+  readArray,
+  readNumber,
+  readString,
+} from "../core/metadata.js";
+import type { RequestMetadata, Usage } from "../core/types.js";
+import { normalizeToolCall, normalizeUsage } from "./mappers.js";
+import type {
+  ChatChoice,
+  ChatCompletion,
+  ChatMessage,
+  ChatStreamEvent,
+  FunctionToolCall,
+} from "./types.js";
+
+type MutableChoice = {
+  index: number;
+  role: ChatMessage["role"];
+  content: string;
+  finishReason: ChatChoice["finishReason"];
+  toolCalls: Map<number, FunctionToolCall>;
+};
+
+export class ChatStream implements AsyncIterable<ChatStreamEvent> {
+  readonly #response: Response;
+  readonly #metadata: RequestMetadata;
+  readonly #choices = new Map<number, MutableChoice>();
+  #id = "";
+  #model = "";
+  #createdAt = 0;
+  #usage: Usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+  #iterator?: AsyncGenerator<ChatStreamEvent>;
+  #done = false;
+  #consuming = false;
+  #completion?: ChatCompletion;
+  #error?: unknown;
+
+  constructor(response: Response) {
+    if (!response.body) {
+      throw new StreamError("Streaming response did not include a body.");
+    }
+    this.#response = response;
+    this.#metadata = compactMetadata(extractMetadata(response));
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<ChatStreamEvent> {
+    if (this.#consuming && !this.#done) {
+      throw new StreamError("Chat stream can only be consumed once.");
+    }
+    this.#consuming = true;
+    this.#iterator ??= this.#events();
+    return this.#iterator;
+  }
+
+  async finalResponse(): Promise<ChatCompletion> {
+    if (this.#error) throw this.#error;
+    if (!this.#done) {
+      if (this.#consuming) {
+        throw new StreamError(
+          "Wait for active stream iteration to finish before requesting finalResponse().",
+        );
+      }
+      for await (const event of this) {
+        // Drain stream and assemble normalized completion.
+        void event;
+      }
+    }
+    if (this.#error) throw this.#error;
+    if (!this.#completion) {
+      throw new StreamError("Chat stream ended before completion.", {
+        requestId: this.#metadata.requestId,
+        traceId: this.#metadata.traceId,
+      });
+    }
+    return this.#completion;
+  }
+
+  async text(): Promise<string> {
+    return (await this.finalResponse()).outputText;
+  }
+
+  async *#events(): AsyncGenerator<ChatStreamEvent> {
+    try {
+      for await (const data of parseSse(this.#response.body!)) {
+        if (data === "[DONE]") break;
+        let payload: unknown;
+        try {
+          payload = JSON.parse(data) as unknown;
+        } catch (cause) {
+          throw new StreamError("Received invalid JSON in chat stream.", {
+            cause,
+            requestId: this.#metadata.requestId,
+            traceId: this.#metadata.traceId,
+          });
+        }
+
+        const root = asUnknownRecord(payload);
+        const error = asUnknownRecord(root.error);
+        if (Object.keys(error).length > 0) {
+          throw new StreamError(
+            readString(error, "message") ?? "Nirmos stream failed.",
+            {
+              code: readString(error, "code"),
+              requestId: this.#metadata.requestId,
+              traceId: this.#metadata.traceId,
+            },
+          );
+        }
+
+        this.#id = readString(root, "id") ?? this.#id;
+        this.#model = readString(root, "model") ?? this.#model;
+        this.#createdAt =
+          readNumber(root, "created", "created_at", "createdAt") ??
+          this.#createdAt;
+        if (root.usage !== undefined) this.#usage = normalizeUsage(root.usage);
+
+        for (const rawChoice of readArray(root, "choices")) {
+          const choice = asUnknownRecord(rawChoice);
+          const index = readNumber(choice, "index") ?? 0;
+          const delta = asUnknownRecord(choice.delta);
+          const mutable = this.#choice(index);
+          mutable.role =
+            (readString(delta, "role") as ChatMessage["role"] | undefined) ??
+            mutable.role;
+          const finishReason = readString(
+            choice,
+            "finish_reason",
+            "finishReason",
+          );
+          if (finishReason) {
+            mutable.finishReason =
+              finishReason === "tool_calls"
+                ? "toolCalls"
+                : finishReason === "content_filter"
+                  ? "contentFilter"
+                  : finishReason;
+          }
+
+          const content = readString(delta, "content");
+          if (content) {
+            mutable.content += content;
+            yield {
+              type: "content.delta",
+              id: this.#id,
+              model: this.#model,
+              choiceIndex: index,
+              delta: content,
+              metadata: this.#metadata,
+            };
+          }
+
+          for (const rawToolCall of readArray(
+            delta,
+            "tool_calls",
+            "toolCalls",
+          )) {
+            const toolRecord = asUnknownRecord(rawToolCall);
+            const toolIndex = readNumber(toolRecord, "index") ?? 0;
+            const incoming = normalizeToolCall(toolRecord);
+            const current = mutable.toolCalls.get(toolIndex) ?? {
+              id: "",
+              type: "function" as const,
+              function: { name: "", arguments: "" },
+            };
+            const merged: FunctionToolCall = {
+              id: incoming.id || current.id,
+              type: "function",
+              function: {
+                name: incoming.function.name || current.function.name,
+                arguments:
+                  current.function.arguments + incoming.function.arguments,
+              },
+            };
+            mutable.toolCalls.set(toolIndex, merged);
+            yield {
+              type: "toolCall.delta",
+              id: this.#id,
+              model: this.#model,
+              choiceIndex: index,
+              toolCall: incoming,
+              metadata: this.#metadata,
+            };
+          }
+        }
+      }
+
+      this.#completion = this.#buildCompletion();
+      this.#done = true;
+      yield {
+        type: "completion.completed",
+        id: this.#completion.id,
+        model: this.#completion.model,
+        completion: this.#completion,
+        metadata: this.#metadata,
+      };
+    } catch (error) {
+      this.#error =
+        error instanceof NirmosError
+          ? error
+          : new StreamError("Chat stream ended unexpectedly.", {
+              cause: error,
+              requestId: this.#metadata.requestId,
+              traceId: this.#metadata.traceId,
+            });
+      throw this.#error;
+    } finally {
+      this.#done = true;
+    }
+  }
+
+  #choice(index: number): MutableChoice {
+    let choice = this.#choices.get(index);
+    if (!choice) {
+      choice = {
+        index,
+        role: "assistant",
+        content: "",
+        finishReason: null,
+        toolCalls: new Map(),
+      };
+      this.#choices.set(index, choice);
+    }
+    return choice;
+  }
+
+  #buildCompletion(): ChatCompletion {
+    const choices: ChatChoice[] = [...this.#choices.values()]
+      .sort((left, right) => left.index - right.index)
+      .map((choice) => ({
+        index: choice.index,
+        message: {
+          role: choice.role,
+          content: choice.content,
+          ...(choice.toolCalls.size > 0
+            ? { toolCalls: [...choice.toolCalls.values()] }
+            : {}),
+        },
+        finishReason: choice.finishReason,
+      }));
+
+    return {
+      id: this.#id || this.#metadata.requestId || "",
+      createdAt: this.#createdAt,
+      model: this.#model || this.#metadata.model || "",
+      choices,
+      outputText: choices
+        .map((choice) =>
+          typeof choice.message.content === "string"
+            ? choice.message.content
+            : "",
+        )
+        .join(""),
+      usage: this.#usage,
+      metadata: this.#metadata,
+    };
+  }
+}
+
+async function* parseSse(
+  body: ReadableStream<Uint8Array>,
+): AsyncGenerator<string> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let dataLines: string[] = [];
+  let completed = false;
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      buffer += decoder.decode(value, { stream: !done });
+      const lines = buffer.split(/\r?\n/);
+      buffer = done ? "" : (lines.pop() ?? "");
+
+      for (const line of lines) {
+        if (line === "") {
+          if (dataLines.length > 0) {
+            yield dataLines.join("\n");
+            dataLines = [];
+          }
+          continue;
+        }
+        if (line.startsWith(":")) continue;
+        if (line.startsWith("data:")) {
+          dataLines.push(line.slice(5).replace(/^ /, ""));
+        }
+      }
+
+      if (done) {
+        completed = true;
+        break;
+      }
+    }
+
+    if (buffer.startsWith("data:")) {
+      dataLines.push(buffer.slice(5).replace(/^ /, ""));
+    }
+    if (dataLines.length > 0) yield dataLines.join("\n");
+  } finally {
+    if (!completed) await reader.cancel();
+    reader.releaseLock();
+  }
+}