clark-platform-client-js 0.1.0

package/src/resources/chat_completions.js

@@ -0,0 +1,209 @@
+import { parseSSEStream } from "../sse.js";
+
+/**
+ * @typedef {Object} ChatMessageTextPart
+ * @property {"text"} type
+ * @property {string} text
+ *
+ * @typedef {Object} ChatMessage
+ * @property {"system"|"user"|"assistant"|"tool"|string} role
+ * @property {string|ChatMessageTextPart[]|null} [content]
+ * @property {string} [name]
+ * @property {string} [tool_call_id]
+ * @property {Array<Object>} [tool_calls]
+ *
+ * @typedef {Object} CreateChatCompletionParams
+ * @property {string} model Bare tier id or "tier:option". Use "clark-code" (or "clark-code:<option>") only via `createPassthrough`/`streamPassthrough`.
+ * @property {string} [tierModelId]
+ * @property {ChatMessage[]} messages
+ * @property {string} [conversationId]
+ * @property {"user"|"conversation"} [memoryScope]
+ * @property {string} [previousResponseId]
+ * @property {{include_usage?: boolean}} [streamOptions]
+ * @property {Record<string, unknown>} [metadata]
+ * @property {number} [temperature]
+ * @property {number} [topP]
+ * @property {number} [maxTokens]
+ * @property {string|string[]} [stop]
+ * @property {AbortSignal} [signal]
+ *
+ * @typedef {CreateChatCompletionParams} CreatePassthroughChatCompletionParams
+ * @property {Array<Object>} [tools]
+ * @property {string|Object} [toolChoice]
+ * @property {boolean} [parallelToolCalls]
+ * @property {"minimal"|"low"|"medium"|"high"|"xhigh"} [reasoningEffort]
+ *
+ * @typedef {Object} ChatCompletionChoice
+ * @property {number} index
+ * @property {{role: "assistant", content: string}} message
+ * @property {"stop"|"error"|"timeout"|string} finish_reason
+ *
+ * @typedef {Object} ChatCompletionObject
+ * @property {string} id
+ * @property {"chat.completion"} object
+ * @property {number} created
+ * @property {string} model
+ * @property {ChatCompletionChoice[]} choices
+ * @property {import("./responses.js").PublicUsage} [usage]
+ * @property {import("./responses.js").PublicResponseMetadata} [clark]
+ *
+ * @typedef {Object} ChatCompletionChunk
+ * @property {string} id
+ * @property {"chat.completion.chunk"} object
+ * @property {number} created
+ * @property {string} model
+ * @property {Array<{index: number, delta: Object, finish_reason: string|null}>} choices
+ * @property {import("./responses.js").PublicUsage|null} [usage]
+ * @property {import("./responses.js").PublicResponseMetadata|null} [clark]
+ */
+
+/**
+ * @param {CreateChatCompletionParams & CreatePassthroughChatCompletionParams & Record<string, unknown>} params
+ * @param {boolean} stream
+ */
+function buildChatBody(params, stream) {
+  const body = {
+    model: params.model,
+    messages: params.messages,
+    stream,
+  };
+
+  const tierModelId = params.tierModelId ?? params.tier_model_id;
+  if (tierModelId !== undefined) body.tier_model_id = tierModelId;
+
+  const conversationId = params.conversationId ?? params.conversation_id;
+  if (conversationId !== undefined) body.conversation_id = conversationId;
+
+  const memoryScope = params.memoryScope ?? params.memory_scope;
+  if (memoryScope !== undefined) body.memory_scope = memoryScope;
+
+  const previousResponseId = params.previousResponseId ?? params.previous_response_id;
+  if (previousResponseId !== undefined) body.previous_response_id = previousResponseId;
+
+  const streamOptions = params.streamOptions ?? params.stream_options;
+  if (streamOptions !== undefined) body.stream_options = streamOptions;
+
+  if (params.metadata !== undefined) body.metadata = params.metadata;
+  if (params.temperature !== undefined) body.temperature = params.temperature;
+
+  const topP = params.topP ?? params.top_p;
+  if (topP !== undefined) body.top_p = topP;
+
+  const maxTokens = params.maxTokens ?? params.max_tokens;
+  if (maxTokens !== undefined) body.max_tokens = maxTokens;
+
+  if (params.stop !== undefined) body.stop = params.stop;
+
+  if (params.tools !== undefined) body.tools = params.tools;
+
+  const toolChoice = params.toolChoice ?? params.tool_choice;
+  if (toolChoice !== undefined) body.tool_choice = toolChoice;
+
+  const parallelToolCalls = params.parallelToolCalls ?? params.parallel_tool_calls;
+  if (parallelToolCalls !== undefined) body.parallel_tool_calls = parallelToolCalls;
+
+  const reasoningEffort = params.reasoningEffort ?? params.reasoning_effort;
+  if (reasoningEffort !== undefined) body.reasoning_effort = reasoningEffort;
+
+  return body;
+}
+
+/**
+ * Iterate a `data:`-only SSE stream (no `event:` names), yielding parsed
+ * JSON chunks and stopping (without yielding) on the literal `data: [DONE]`
+ * sentinel. Shared by both the agentic and passthrough streaming paths,
+ * which use the same wire-level framing but different payload shapes.
+ *
+ * @param {Response} response
+ * @returns {AsyncGenerator<any, void, unknown>}
+ */
+async function* iterateDataOnlySSE(response) {
+  for await (const sseEvent of parseSSEStream(response)) {
+    if (!sseEvent.data) continue;
+    if (sseEvent.data === "[DONE]") return;
+    yield JSON.parse(sseEvent.data);
+  }
+}
+
+export class ChatCompletions {
+  /** @param {import("../http.js").HttpTransport} http */
+  constructor(http) {
+    this._http = http;
+  }
+
+  /**
+   * `POST /v1/chat/completions` for agentic tiers (`clark`, `clark_max`,
+   * `openrouter:*`) — non-streaming. Do NOT pass `tools`/`tool_choice` here;
+   * the server rejects them with `400 unsupported_parameter` for agentic
+   * tiers. Use `createPassthrough` for `model: "clark-code"` with tools.
+   *
+   * @param {CreateChatCompletionParams} params
+   * @returns {Promise<ChatCompletionObject>}
+   */
+  async create(params) {
+    const body = buildChatBody(params, false);
+    return this._http.requestJson("POST", "/v1/chat/completions", {
+      body,
+      signal: params.signal,
+    });
+  }
+
+  /**
+   * `POST /v1/chat/completions` with `stream: true` for agentic tiers.
+   * Returns an async generator over `chat.completion.chunk` objects; the
+   * stream ends (generator returns) when the server sends `data: [DONE]`.
+   * The final usage chunk only appears if `streamOptions.include_usage` (or
+   * `stream_options.include_usage`) was `true`.
+   *
+   * @param {CreateChatCompletionParams} params
+   * @returns {AsyncGenerator<ChatCompletionChunk, void, unknown>}
+   */
+  async *stream(params) {
+    const body = buildChatBody(params, true);
+    const response = await this._http.requestStream("POST", "/v1/chat/completions", {
+      body,
+      signal: params.signal,
+    });
+    yield* iterateDataOnlySSE(response);
+  }
+
+  /**
+   * `POST /v1/chat/completions` with `model: "clark-code"` (or
+   * `"clark-code:<option>"`) — the passthrough tier. `tools`/`tool_choice`
+   * and the full `messages` array (including prior `tool_calls`/`tool`
+   * messages) are forwarded verbatim to the upstream OpenAI-compatible
+   * provider. The response is the RAW upstream OpenAI-shaped object, not a
+   * Clark `ChatCompletionObject` — do not assume the `clark`/Clark usage
+   * shape here. `conversationId`/`previousResponseId`/`memoryScope` are
+   * meaningless for this tier; omit them.
+   *
+   * @param {CreatePassthroughChatCompletionParams} params
+   * @returns {Promise<Object>} Raw upstream OpenAI-compatible chat completion object.
+   */
+  async createPassthrough(params) {
+    const body = buildChatBody(params, false);
+    return this._http.requestJson("POST", "/v1/chat/completions", {
+      body,
+      signal: params.signal,
+    });
+  }
+
+  /**
+   * Streaming counterpart of `createPassthrough`. Returns an async generator
+   * over the raw upstream provider's native `chat.completion.chunk`-shaped
+   * SSE payloads (including native `tool_calls` deltas) ending on
+   * `data: [DONE]`. The caller is responsible for running its own tool loop
+   * — Clark does not execute tools for this tier.
+   *
+   * @param {CreatePassthroughChatCompletionParams} params
+   * @returns {AsyncGenerator<Object, void, unknown>}
+   */
+  async *streamPassthrough(params) {
+    const body = buildChatBody(params, true);
+    const response = await this._http.requestStream("POST", "/v1/chat/completions", {
+      body,
+      signal: params.signal,
+    });
+    yield* iterateDataOnlySSE(response);
+  }
+}

package/src/resources/memories.js

@@ -0,0 +1,36 @@
+/**
+ * @typedef {Object} MemoryListParams
+ * @property {string} [q] Search string.
+ * @property {string} [tags]
+ * @property {string} [conversationId] Scope to a conversation's memory instead of the caller's user-scoped memory.
+ * @property {AbortSignal} [signal]
+ *
+ * @typedef {Object} MemoryList
+ * @property {"list"} object
+ * @property {Array<Object>} data Memory record shape is defined by clark_memory_service; treated as opaque here.
+ */
+
+export class Memories {
+  /** @param {import("../http.js").HttpTransport} http */
+  constructor(http) {
+    this._http = http;
+  }
+
+  /**
+   * `GET /v1/memories` — list durable memory records for the caller.
+   *
+   * @param {MemoryListParams} [params]
+   * @returns {Promise<MemoryList>}
+   */
+  async list(params = {}) {
+    const conversationId = params.conversationId ?? params.conversation_id;
+    return this._http.requestJson("GET", "/v1/memories", {
+      query: {
+        q: params.q,
+        tags: params.tags,
+        conversation_id: conversationId,
+      },
+      signal: params.signal,
+    });
+  }
+}

package/src/resources/models.js

@@ -0,0 +1,55 @@
+/**
+ * @typedef {Object} ClarkModelPricing
+ * @property {string} currency
+ * @property {string} unit
+ * @property {number} input
+ * @property {number} output
+ * @property {number} [cache_write]
+ * @property {number} [cache_read]
+ *
+ * @typedef {Object} ClarkModelCapabilities
+ * @property {string[]} public_input_modalities
+ * @property {string[]} model_input_modalities
+ * @property {string[]} output_modalities
+ * @property {string[]} features
+ * @property {boolean} public_file_upload
+ *
+ * @typedef {Object} ClarkModelDetail
+ * @property {string} tier_id
+ * @property {string} label
+ * @property {string} description
+ * @property {number} context_window_tokens
+ * @property {number} max_output_tokens
+ * @property {ClarkModelPricing} pricing
+ * @property {ClarkModelCapabilities} capabilities
+ * @property {ClarkModelEntry[]} [model_options]
+ *
+ * @typedef {Object} ClarkModelEntry
+ * @property {string} id
+ * @property {"model"} object
+ * @property {string} owned_by
+ * @property {ClarkModelDetail} clark
+ *
+ * @typedef {Object} ClarkModelList
+ * @property {"list"} object
+ * @property {ClarkModelEntry[]} data
+ */
+
+export class Models {
+  /** @param {import("../http.js").HttpTransport} http */
+  constructor(http) {
+    this._http = http;
+  }
+
+  /**
+   * `GET /v1/models` — list model tiers/options with pricing + capabilities.
+   * Treat the returned tier/option ids as dynamic; never hardcode them.
+   *
+   * @param {Object} [options]
+   * @param {AbortSignal} [options.signal]
+   * @returns {Promise<ClarkModelList>}
+   */
+  async list(options = {}) {
+    return this._http.requestJson("GET", "/v1/models", { signal: options.signal });
+  }
+}

package/src/resources/responses.js

@@ -0,0 +1,186 @@
+import { parseSSEStream } from "../sse.js";
+
+/**
+ * @typedef {"user"|"assistant"|string} ResponseInputRole
+ *
+ * @typedef {Object} ResponseInputTextPart
+ * @property {"text"|"input_text"} type
+ * @property {string} text
+ *
+ * @typedef {Object} ResponseInputItem
+ * @property {ResponseInputRole} [role]
+ * @property {string|ResponseInputTextPart[]} content
+ *
+ * @typedef {Object} CreateResponseParams
+ * @property {string} model Bare tier id (e.g. "clark") or "tier:option" (e.g. "openrouter:qwen35_flash").
+ * @property {string} [tierModelId] Explicit tier/model id; wins over `model` if both are present.
+ * @property {string|ResponseInputItem[]} input
+ * @property {string} [conversationId]
+ * @property {"user"|"conversation"} [memoryScope]
+ * @property {string} [previousResponseId]
+ * @property {boolean} [background]
+ * @property {Record<string, unknown>} [metadata]
+ * @property {AbortSignal} [signal]
+ *
+ * @typedef {Object} PublicUsageCost
+ * @property {string|null} amount
+ * @property {string} currency
+ * @property {"estimated"|"unavailable"|string} type
+ *
+ * @typedef {Object} PublicUsage
+ * @property {number} input_tokens
+ * @property {{cached_tokens: number}} input_tokens_details
+ * @property {number} output_tokens
+ * @property {{reasoning_tokens: number}} output_tokens_details
+ * @property {number} total_tokens
+ * @property {number} [artifact_bytes]
+ * @property {PublicUsageCost} cost
+ *
+ * @typedef {Object} PublicArtifact
+ * @property {string} id
+ * @property {string} name
+ * @property {string} kind
+ * @property {string} role
+ * @property {string} mime_type
+ * @property {number} size_bytes
+ * @property {string} [summary]
+ * @property {string} download_url
+ *
+ * @typedef {Object} PublicResponseMetadata
+ * @property {string} response_id
+ * @property {string} conversation_id
+ * @property {string} run_id
+ * @property {"in_progress"|"completed"|"failed"} status
+ * @property {PublicArtifact[]} artifacts
+ *
+ * @typedef {Object} ResponseObject
+ * @property {string} id
+ * @property {"response"} object
+ * @property {"in_progress"|"completed"|"failed"} status
+ * @property {number} created_at
+ * @property {string} model
+ * @property {string|null} previous_response_id
+ * @property {boolean} background
+ * @property {Array<Object>} output
+ * @property {PublicArtifact[]} artifacts
+ * @property {PublicUsage} [usage]
+ * @property {Record<string, unknown>} [metadata]
+ * @property {PublicResponseMetadata} clark
+ * @property {{type: string, message: string}|null} error
+ */
+
+/**
+ * Build the JSON body for POST /v1/responses from either camelCase or
+ * wire-native snake_case fields (both accepted for ergonomics).
+ *
+ * @param {CreateResponseParams & Record<string, unknown>} params
+ * @param {boolean} stream
+ */
+function buildResponsesBody(params, stream) {
+  const body = {
+    model: params.model,
+    input: params.input,
+    stream,
+  };
+  const tierModelId = params.tierModelId ?? params.tier_model_id;
+  if (tierModelId !== undefined) body.tier_model_id = tierModelId;
+
+  const conversationId = params.conversationId ?? params.conversation_id;
+  if (conversationId !== undefined) body.conversation_id = conversationId;
+
+  const memoryScope = params.memoryScope ?? params.memory_scope;
+  if (memoryScope !== undefined) body.memory_scope = memoryScope;
+
+  const previousResponseId = params.previousResponseId ?? params.previous_response_id;
+  if (previousResponseId !== undefined) body.previous_response_id = previousResponseId;
+
+  if (params.background !== undefined) body.background = params.background;
+  if (params.metadata !== undefined) body.metadata = params.metadata;
+
+  return body;
+}
+
+export class Responses {
+  /** @param {import("../http.js").HttpTransport} http */
+  constructor(http) {
+    this._http = http;
+  }
+
+  /**
+   * `POST /v1/responses` (non-streaming, or `background: true` to return
+   * immediately with an `in_progress` object for polling).
+   *
+   * @param {CreateResponseParams} params
+   * @returns {Promise<ResponseObject>}
+   */
+  async create(params) {
+    const body = buildResponsesBody(params, false);
+    return this._http.requestJson("POST", "/v1/responses", { body, signal: params.signal });
+  }
+
+  /**
+   * `POST /v1/responses` with `stream: true`. Returns an async generator over
+   * the named SSE events (`response.created`, `response.in_progress`,
+   * `response.output_text.delta`, `response.output_text.done`,
+   * `response.artifact.completed`, `response.usage.updated`,
+   * `response.completed` / `response.failed`).
+   *
+   * The full answer text arrives as a single `response.output_text.delta`
+   * event, not token-by-token — do not assume many small chunks.
+   *
+   * @param {CreateResponseParams} params
+   * @returns {AsyncGenerator<{type: string, sequence_number: number, [key: string]: unknown}, void, unknown>}
+   */
+  async *stream(params) {
+    const body = buildResponsesBody(params, true);
+    const response = await this._http.requestStream("POST", "/v1/responses", {
+      body,
+      signal: params.signal,
+    });
+    for await (const sseEvent of parseSSEStream(response)) {
+      if (!sseEvent.data) continue;
+      yield JSON.parse(sseEvent.data);
+    }
+  }
+
+  /**
+   * `GET /v1/responses/{response_id}` — poll a response by its stable id.
+   *
+   * @param {string} responseId
+   * @param {Object} [options]
+   * @param {AbortSignal} [options.signal]
+   * @returns {Promise<ResponseObject>}
+   */
+  async get(responseId, options = {}) {
+    return this._http.requestJson("GET", `/v1/responses/${encodeURIComponent(responseId)}`, {
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * `GET /v1/responses/{response_id}/events` — poll public progress events.
+   *
+   * @param {string} responseId
+   * @param {Object} [options]
+   * @param {number} [options.afterSeq] Default 0.
+   * @param {number} [options.limit] Default 200, max 500.
+   * @param {string[]|string} [options.types] Comma-separated allowlist filter.
+   * @param {AbortSignal} [options.signal]
+   * @returns {Promise<{object: "list", data: Array<Object>, next_after_seq: number}>}
+   */
+  async listEvents(responseId, options = {}) {
+    const types = Array.isArray(options.types) ? options.types.join(",") : options.types;
+    return this._http.requestJson(
+      "GET",
+      `/v1/responses/${encodeURIComponent(responseId)}/events`,
+      {
+        query: {
+          after_seq: options.afterSeq,
+          limit: options.limit,
+          types,
+        },
+        signal: options.signal,
+      }
+    );
+  }
+}

package/src/sse.js

@@ -0,0 +1,101 @@
+/**
+ * Minimal Server-Sent Events (SSE) line-protocol parser, built directly on
+ * the Web Streams API (`Response.body` as a `ReadableStream<Uint8Array>`),
+ * with no external dependency. Works identically in Node 18+ (native
+ * `fetch`/`ReadableStream`) and modern browsers.
+ *
+ * @typedef {Object} SSEEvent
+ * @property {string|null} event SSE `event:` field, or null if the stream
+ *   only sends bare `data:` lines (as `/v1/chat/completions` streaming does).
+ * @property {string} data The (possibly multi-line, newline-joined) `data:` payload.
+ * @property {string|null} id SSE `id:` field, if present.
+ */
+
+/**
+ * Parse a fetch Response body as an SSE stream, yielding one `SSEEvent` per
+ * blank-line-delimited block.
+ *
+ * @param {Response} response A fetch Response whose `.body` is a ReadableStream.
+ * @returns {AsyncGenerator<SSEEvent, void, unknown>}
+ */
+export async function* parseSSEStream(response) {
+  if (!response.body) {
+    throw new Error("Response has no readable body to stream from");
+  }
+
+  const decoder = new TextDecoder("utf-8");
+  const reader = response.body.getReader();
+  let buffer = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+
+      // SSE blocks are separated by a blank line. Support both \n\n and \r\n\r\n.
+      let boundary;
+      while ((boundary = findBlockBoundary(buffer)) !== -1) {
+        const rawBlock = buffer.slice(0, boundary.start);
+        buffer = buffer.slice(boundary.end);
+        const parsed = parseBlock(rawBlock);
+        if (parsed) yield parsed;
+      }
+    }
+
+    // Flush any trailing block without a final blank-line terminator.
+    buffer += decoder.decode();
+    const trimmed = buffer.trim();
+    if (trimmed.length > 0) {
+      const parsed = parseBlock(buffer);
+      if (parsed) yield parsed;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/**
+ * @param {string} buffer
+ * @returns {{start: number, end: number}|-1}
+ */
+function findBlockBoundary(buffer) {
+  const idxLfLf = buffer.indexOf("\n\n");
+  const idxCrLfCrLf = buffer.indexOf("\r\n\r\n");
+  if (idxCrLfCrLf !== -1 && (idxLfLf === -1 || idxCrLfCrLf < idxLfLf)) {
+    return { start: idxCrLfCrLf, end: idxCrLfCrLf + 4 };
+  }
+  if (idxLfLf !== -1) {
+    return { start: idxLfLf, end: idxLfLf + 2 };
+  }
+  return -1;
+}
+
+/**
+ * @param {string} block
+ * @returns {SSEEvent|null}
+ */
+function parseBlock(block) {
+  const lines = block.split(/\r\n|\n/);
+  /** @type {string|null} */
+  let event = null;
+  /** @type {string|null} */
+  let id = null;
+  const dataLines = [];
+
+  for (const line of lines) {
+    if (line === "" || line.startsWith(":")) continue;
+    const colonIdx = line.indexOf(":");
+    const field = colonIdx === -1 ? line : line.slice(0, colonIdx);
+    let value = colonIdx === -1 ? "" : line.slice(colonIdx + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+
+    if (field === "event") event = value;
+    else if (field === "data") dataLines.push(value);
+    else if (field === "id") id = value;
+    // "retry" and unknown fields are ignored — not used by the Clark API.
+  }
+
+  if (dataLines.length === 0 && event === null) return null;
+  return { event, data: dataLines.join("\n"), id };
+}