@codefionn/llmleaf-client 0.1.2

package/scripts/gen.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Regenerate the TypeScript typed model from the single proto source of truth.
+#
+#   clients/typescript/scripts/gen.sh   (or: npm run gen)
+#
+# Toolchain:
+#   - protoc          (libprotoc 35; the schema compiler, must be on PATH)
+#   - protoc-gen-es   (the protobuf-es plugin; provided by the npm devDependency
+#                      @bufbuild/protoc-gen-es — run `npm install` first so it lands
+#                      in node_modules/.bin)
+#
+# This emits clients/typescript/src/gen/llmleaf/v1/llmleaf_pb.ts — the protobuf-es
+# codegen artifact (committed). The hand-written transport in src/ maps those typed
+# messages to / from the OpenAI/OpenRouter-shaped JSON the llmleaf core speaks.
+set -euo pipefail
+
+# Run from the typescript client root regardless of the caller's cwd.
+cd "$(dirname "$0")/.."
+
+PLUGIN="./node_modules/.bin/protoc-gen-es"
+
+if [ ! -x "$PLUGIN" ]; then
+  echo "error: $PLUGIN not found." >&2
+  echo "       run 'npm install' first to fetch @bufbuild/protoc-gen-es." >&2
+  exit 1
+fi
+
+if ! command -v protoc >/dev/null 2>&1; then
+  echo "error: protoc not found on PATH (need libprotoc 35)." >&2
+  exit 1
+fi
+
+mkdir -p src/gen
+
+protoc \
+  --plugin=protoc-gen-es="$PLUGIN" \
+  --es_out=src/gen \
+  --es_opt=target=ts \
+  --proto_path=../proto \
+  ../proto/llmleaf/v1/llmleaf.proto
+
+echo "generated: src/gen/llmleaf/v1/llmleaf_pb.ts"

package/src/client.ts

@@ -0,0 +1,353 @@
+// LlmleafClient — the fetch-based HTTP transport. One method per SPEC.md endpoint.
+//
+// Runtime-agnostic: relies only on global fetch / Request / Response / FormData /
+// Blob / AbortController, all present in Node 20+, Deno, Bun and browsers. A custom
+// fetch can be injected (testing, proxies, custom agents).
+
+import { ApiError, apiErrorFromResponse } from "./error.js";
+import { parseSseData, parseNdjson } from "./stream.js";
+import {
+  encodeChatRequest,
+  decodeChatResponse,
+  decodeChatCompletionChunk,
+  encodeEmbeddingRequest,
+  decodeEmbeddingResponse,
+  encodeSpeechRequest,
+  decodeVoicesResponse,
+  decodeTranscriptionResponse,
+  decodeListModelsResponse,
+  encodeBatchCreateRequest,
+  decodeBatchHandle,
+  decodeBatchResultLine,
+} from "./wire.js";
+import type {
+  ChatRequest,
+  ChatResponse,
+  ChatCompletionChunk,
+  EmbeddingRequest,
+  EmbeddingResponse,
+  SpeechRequest,
+  SpeechResult,
+  VoicesResponse,
+  TranscriptionRequest,
+  TranscriptionResponse,
+  ListModelsResponse,
+  ListModelsOptions,
+  BatchCreateRequest,
+  BatchHandle,
+  BatchResultLine,
+} from "./types.js";
+
+/** The subset of the WHATWG `fetch` signature this client uses. */
+export type FetchLike = (
+  input: string | URL,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export interface LlmleafClientOptions {
+  /** Gateway base URL, e.g. "https://gateway.example.com". */
+  baseUrl: string;
+  /** API key sent as `Authorization: Bearer <apiKey>`. */
+  apiKey: string;
+  /** Per-request timeout in milliseconds. 0 / omitted disables the timeout. */
+  timeoutMs?: number;
+  /** Optional admin token; sent as `x-admin-token` when an endpoint opts in. */
+  adminToken?: string;
+  /** Inject a custom fetch (defaults to the global `fetch`). */
+  fetch?: FetchLike;
+}
+
+/** Audio file input for transcriptions: bytes + a filename. */
+export interface TranscriptionFile {
+  /** A Blob/File, or raw bytes. */
+  data: Blob | Uint8Array | ArrayBuffer;
+  /** Filename for the multipart part (e.g. "audio.mp3"). */
+  filename: string;
+  /** Optional content type when `data` is not already a Blob. */
+  contentType?: string;
+}
+
+const SPEECH_CONTENT_TYPES: Record<string, string> = {
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  opus: "audio/ogg",
+  aac: "audio/aac",
+  flac: "audio/flac",
+  pcm: "audio/pcm",
+};
+
+export class LlmleafClient {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+  private readonly timeoutMs: number;
+  private readonly adminToken?: string;
+  private readonly fetchImpl: FetchLike;
+
+  constructor(options: LlmleafClientOptions) {
+    if (!options.baseUrl) throw new TypeError("LlmleafClient: baseUrl is required");
+    if (!options.apiKey) throw new TypeError("LlmleafClient: apiKey is required");
+    // Strip a single trailing slash so path joins are predictable.
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.timeoutMs = options.timeoutMs ?? 0;
+    this.adminToken = options.adminToken;
+    const f = options.fetch ?? (globalThis.fetch as FetchLike | undefined);
+    if (!f) {
+      throw new TypeError(
+        "LlmleafClient: no global fetch available; pass `fetch` in the options (Node <18, or a non-fetch runtime).",
+      );
+    }
+    this.fetchImpl = f;
+  }
+
+  // -------------------------------------------------------------------------
+  // Internal request plumbing
+  // -------------------------------------------------------------------------
+
+  private url(path: string, query?: Record<string, string | undefined>): string {
+    let u = this.baseUrl + path;
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== undefined) params.set(k, v);
+      }
+      const qs = params.toString();
+      if (qs) u += "?" + qs;
+    }
+    return u;
+  }
+
+  private headers(extra?: Record<string, string>): Headers {
+    const h = new Headers({ authorization: `Bearer ${this.apiKey}` });
+    if (extra) for (const [k, v] of Object.entries(extra)) h.set(k, v);
+    return h;
+  }
+
+  /** Issue a request with the configured timeout; returns the raw Response. */
+  private async send(url: string, init: RequestInit): Promise<Response> {
+    if (this.timeoutMs <= 0) {
+      return this.fetchImpl(url, init);
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await this.fetchImpl(url, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /** Send a JSON request and return the parsed JSON body, or throw ApiError. */
+  private async sendJson(
+    url: string,
+    body: unknown,
+    headers?: Record<string, string>,
+  ): Promise<unknown> {
+    const res = await this.send(url, {
+      method: "POST",
+      headers: this.headers({ "content-type": "application/json", ...headers }),
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) throw await apiErrorFromResponse(res);
+    return res.json();
+  }
+
+  // -------------------------------------------------------------------------
+  // Chat completions
+  // -------------------------------------------------------------------------
+
+  /** POST /v1/chat/completions (non-streaming). */
+  async chat(req: ChatRequest): Promise<ChatResponse> {
+    const body = encodeChatRequest(req, false);
+    const json = await this.sendJson(this.url("/v1/chat/completions"), body);
+    return decodeChatResponse(json);
+  }
+
+  /**
+   * POST /v1/chat/completions with `stream:true`. Returns an async iterable of
+   * {@link ChatCompletionChunk}; stops at the `data: [DONE]` sentinel.
+   */
+  async *chatStream(
+    req: ChatRequest,
+  ): AsyncGenerator<ChatCompletionChunk, void, unknown> {
+    const body = encodeChatRequest(req, true);
+    const res = await this.send(this.url("/v1/chat/completions"), {
+      method: "POST",
+      headers: this.headers({
+        "content-type": "application/json",
+        accept: "text/event-stream",
+      }),
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) throw await apiErrorFromResponse(res);
+    if (!res.body) {
+      throw new ApiError(res.status, "streaming response had no body");
+    }
+    for await (const payload of parseSseData(res.body)) {
+      yield decodeChatCompletionChunk(JSON.parse(payload));
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Embeddings
+  // -------------------------------------------------------------------------
+
+  /** POST /v1/embeddings. Base64 embeddings are decoded to float arrays. */
+  async embeddings(req: EmbeddingRequest): Promise<EmbeddingResponse> {
+    const body = encodeEmbeddingRequest(req);
+    const json = await this.sendJson(this.url("/v1/embeddings"), body);
+    return decodeEmbeddingResponse(json);
+  }
+
+  // -------------------------------------------------------------------------
+  // Model catalog
+  // -------------------------------------------------------------------------
+
+  /** GET /v1/models. Pass `admin:true` to include per-model `endpoints`. */
+  async listModels(opts: ListModelsOptions = {}): Promise<ListModelsResponse> {
+    const headers: Record<string, string> = {};
+    if (opts.admin) {
+      if (!this.adminToken) {
+        throw new TypeError(
+          "listModels({ admin:true }) requires an adminToken in the client options",
+        );
+      }
+      headers["x-admin-token"] = this.adminToken;
+    }
+    const url = this.url("/v1/models", { type: opts.type, search: opts.search });
+    const res = await this.send(url, {
+      method: "GET",
+      headers: this.headers(headers),
+    });
+    if (!res.ok) throw await apiErrorFromResponse(res);
+    return decodeListModelsResponse(await res.json());
+  }
+
+  // -------------------------------------------------------------------------
+  // Audio
+  // -------------------------------------------------------------------------
+
+  /** POST /v1/audio/speech. Returns the raw audio bytes + Content-Type. */
+  async speech(req: SpeechRequest): Promise<SpeechResult> {
+    const body = encodeSpeechRequest(req);
+    const res = await this.send(this.url("/v1/audio/speech"), {
+      method: "POST",
+      headers: this.headers({ "content-type": "application/json" }),
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) throw await apiErrorFromResponse(res);
+    const buf = await res.arrayBuffer();
+    const contentType =
+      res.headers.get("content-type") ??
+      (req.responseFormat ? SPEECH_CONTENT_TYPES[req.responseFormat] : undefined) ??
+      "application/octet-stream";
+    return { bytes: new Uint8Array(buf), contentType };
+  }
+
+  /** GET /v1/audio/voices?model=<id>. */
+  async voices(model: string): Promise<VoicesResponse> {
+    const url = this.url("/v1/audio/voices", { model });
+    const res = await this.send(url, { method: "GET", headers: this.headers() });
+    if (!res.ok) throw await apiErrorFromResponse(res);
+    return decodeVoicesResponse(await res.json());
+  }
+
+  /**
+   * POST /v1/audio/transcriptions (multipart/form-data).
+   *
+   * For `responseFormat` json/verbose_json the structured
+   * {@link TranscriptionResponse} is returned; for text/srt/vtt the response is a
+   * plain-text body and the returned object carries it in `.text` (other fields empty).
+   */
+  async transcribe(
+    file: TranscriptionFile,
+    req: TranscriptionRequest,
+  ): Promise<TranscriptionResponse> {
+    const form = new FormData();
+    const blob =
+      file.data instanceof Blob
+        ? file.data
+        : new Blob(
+            [file.data instanceof Uint8Array ? bytesToArrayBuffer(file.data) : file.data],
+            file.contentType ? { type: file.contentType } : undefined,
+          );
+    form.set("file", blob, file.filename);
+    form.set("model", req.model);
+    if (req.language !== undefined) form.set("language", req.language);
+    if (req.prompt !== undefined) form.set("prompt", req.prompt);
+    if (req.responseFormat !== undefined) form.set("response_format", req.responseFormat);
+    if (req.temperature !== undefined) form.set("temperature", String(req.temperature));
+
+    // Do NOT set content-type: the runtime sets it with the multipart boundary.
+    const res = await this.send(this.url("/v1/audio/transcriptions"), {
+      method: "POST",
+      headers: this.headers(),
+      body: form,
+    });
+    if (!res.ok) throw await apiErrorFromResponse(res);
+
+    const ct = res.headers.get("content-type") ?? "";
+    if (ct.includes("application/json")) {
+      return decodeTranscriptionResponse(await res.json());
+    }
+    // text / srt / vtt: a plain-text body. Surface it directly in `.text`.
+    return { text: await res.text() };
+  }
+
+  // -------------------------------------------------------------------------
+  // Batches
+  // -------------------------------------------------------------------------
+
+  /** POST /v1/batches. */
+  async createBatch(req: BatchCreateRequest): Promise<BatchHandle> {
+    const body = encodeBatchCreateRequest(req);
+    const json = await this.sendJson(this.url("/v1/batches"), body);
+    return decodeBatchHandle(json);
+  }
+
+  /** GET /v1/batches/{id}. */
+  async getBatch(id: string): Promise<BatchHandle> {
+    const res = await this.send(this.url(`/v1/batches/${encodeURIComponent(id)}`), {
+      method: "GET",
+      headers: this.headers(),
+    });
+    if (!res.ok) throw await apiErrorFromResponse(res);
+    return decodeBatchHandle(await res.json());
+  }
+
+  /** POST /v1/batches/{id}/cancel. */
+  async cancelBatch(id: string): Promise<BatchHandle> {
+    const res = await this.send(
+      this.url(`/v1/batches/${encodeURIComponent(id)}/cancel`),
+      { method: "POST", headers: this.headers() },
+    );
+    if (!res.ok) throw await apiErrorFromResponse(res);
+    return decodeBatchHandle(await res.json());
+  }
+
+  /**
+   * GET /v1/batches/{id}/results — an async iterable of {@link BatchResultLine}
+   * (one per NDJSON line).
+   */
+  async *batchResults(
+    id: string,
+  ): AsyncGenerator<BatchResultLine, void, unknown> {
+    const res = await this.send(
+      this.url(`/v1/batches/${encodeURIComponent(id)}/results`),
+      { method: "GET", headers: this.headers({ accept: "application/x-ndjson" }) },
+    );
+    if (!res.ok) throw await apiErrorFromResponse(res);
+    if (!res.body) throw new ApiError(res.status, "batch results had no body");
+    for await (const line of parseNdjson(res.body)) {
+      yield decodeBatchResultLine(line);
+    }
+  }
+}
+
+/** Copy a Uint8Array's bytes into a fresh ArrayBuffer (handles non-zero byteOffset). */
+function bytesToArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  return bytes.buffer.slice(
+    bytes.byteOffset,
+    bytes.byteOffset + bytes.byteLength,
+  ) as ArrayBuffer;
+}

package/src/enums.ts

@@ -0,0 +1,73 @@
+// Enum <-> wire-token mapping (SPEC.md "Enum ⇄ wire mapping").
+//
+// Every closed-set enum maps to its wire token by LOWERCASING the value name:
+//   TOOL_CALLS -> "tool_calls", ASSISTANT -> "assistant", IN_PROGRESS -> "in_progress".
+// The `*_UNSPECIFIED` zero value <-> field absent on the wire (undefined here).
+//
+// The generated protobuf-es file emits these as TypeScript string-keyed numeric enums
+// (e.g. `Role.ASSISTANT`). A TS numeric enum is bidirectional at runtime: indexing by
+// the numeric value yields the member NAME, which is exactly the proto value name. We
+// reuse that to derive the wire token mechanically — one helper pair for every enum,
+// no per-enum hand mapping (SPEC.md).
+
+import { Role, FinishReason, BatchStatus } from "./gen/llmleaf/v1/llmleaf_pb.js";
+
+export { Role, FinishReason, BatchStatus };
+
+/** A TS numeric enum object: name<->value reverse-mappable at runtime. */
+type NumericEnum = Record<string, string | number>;
+
+function unspecifiedName(e: NumericEnum): string | undefined {
+  // The zero value is the `*_UNSPECIFIED` member; its name is what 0 maps to.
+  const name = e[0];
+  return typeof name === "string" ? name : undefined;
+}
+
+/**
+ * Encode an enum value to its wire token, or `undefined` for the unspecified zero
+ * value (which means "field absent on the wire").
+ */
+export function enumToWire<E extends number>(
+  enumObj: NumericEnum,
+  value: E | undefined,
+): string | undefined {
+  if (value === undefined) return undefined;
+  const name = enumObj[value as number];
+  if (typeof name !== "string") return undefined;
+  if (name === unspecifiedName(enumObj)) return undefined;
+  return name.toLowerCase();
+}
+
+/**
+ * Decode a wire token back into the enum value. An absent/empty token, or a token
+ * that matches no member, maps to the unspecified zero value (0).
+ */
+export function enumFromWire<E extends number>(
+  enumObj: NumericEnum,
+  token: string | null | undefined,
+): E {
+  if (token === null || token === undefined || token === "") return 0 as E;
+  const want = token.toLowerCase();
+  for (const [name, value] of Object.entries(enumObj)) {
+    if (typeof value !== "number") continue;
+    if (name.toLowerCase() === want) return value as E;
+  }
+  return 0 as E;
+}
+
+// Convenience typed wrappers for the three enums on the surface.
+
+export const roleToWire = (v: Role | undefined): string | undefined =>
+  enumToWire<Role>(Role as unknown as NumericEnum, v);
+export const roleFromWire = (t: string | null | undefined): Role =>
+  enumFromWire<Role>(Role as unknown as NumericEnum, t);
+
+export const finishReasonToWire = (v: FinishReason | undefined): string | undefined =>
+  enumToWire<FinishReason>(FinishReason as unknown as NumericEnum, v);
+export const finishReasonFromWire = (t: string | null | undefined): FinishReason =>
+  enumFromWire<FinishReason>(FinishReason as unknown as NumericEnum, t);
+
+export const batchStatusToWire = (v: BatchStatus | undefined): string | undefined =>
+  enumToWire<BatchStatus>(BatchStatus as unknown as NumericEnum, v);
+export const batchStatusFromWire = (t: string | null | undefined): BatchStatus =>
+  enumFromWire<BatchStatus>(BatchStatus as unknown as NumericEnum, t);

package/src/error.ts

@@ -0,0 +1,71 @@
+// Typed error surface. Any non-2xx response carries the envelope
+//   {"error":{"message":"...", "type"?:"...", "code"?:"..."}}
+// (SPEC.md "Errors"). We parse it into ApiError and throw.
+
+/**
+ * Thrown for any non-2xx HTTP response from the gateway.
+ *
+ * Status codes (SPEC.md): 400 bad request · 401 missing/invalid key ·
+ * 403 blocked or model-not-allowed · 404 no route for model ·
+ * 429 key suspended (limiter) · 502 all upstreams failed.
+ */
+export class ApiError extends Error {
+  readonly status: number;
+  /** present on some dialects; absent on the llmleaf core envelope. */
+  readonly type?: string;
+  readonly code?: string;
+
+  constructor(
+    status: number,
+    message: string,
+    opts?: { type?: string; code?: string },
+  ) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.type = opts?.type;
+    this.code = opts?.code;
+    // Restore prototype chain for instanceof across transpile targets.
+    Object.setPrototypeOf(this, ApiError.prototype);
+  }
+}
+
+interface WireErrorBody {
+  message?: unknown;
+  type?: unknown;
+  code?: unknown;
+}
+
+/**
+ * Build an {@link ApiError} from a non-2xx response. Reads the body once. Falls back
+ * to the HTTP status text when the body is missing or not the expected envelope.
+ */
+export async function apiErrorFromResponse(res: Response): Promise<ApiError> {
+  const fallback = res.statusText || `HTTP ${res.status}`;
+  let text: string;
+  try {
+    text = await res.text();
+  } catch {
+    return new ApiError(res.status, fallback);
+  }
+  if (!text) return new ApiError(res.status, fallback);
+
+  try {
+    const parsed = JSON.parse(text) as { error?: WireErrorBody } | WireErrorBody;
+    const body: WireErrorBody | undefined =
+      parsed && typeof parsed === "object" && "error" in parsed
+        ? (parsed as { error?: WireErrorBody }).error
+        : (parsed as WireErrorBody);
+    if (body && typeof body === "object") {
+      const message =
+        typeof body.message === "string" && body.message ? body.message : fallback;
+      return new ApiError(res.status, message, {
+        type: typeof body.type === "string" ? body.type : undefined,
+        code: typeof body.code === "string" ? body.code : undefined,
+      });
+    }
+  } catch {
+    // Not JSON — fall through and surface the raw text.
+  }
+  return new ApiError(res.status, text.slice(0, 2048));
+}