clark-platform-client-js 0.1.0

package/README.md

@@ -0,0 +1,234 @@
+# clark-platform-client-js
+
+A zero-build-step, plain-JavaScript client for the [Clark Platform
+API](../API_CONTRACT.md). Native ESM, no `tsc`/bundler required to consume it
+— the files you `import` are the files that ship. Works in Node 18+ and any
+modern browser that supports native ESM + `fetch`.
+
+This package is **not** the TypeScript client at `platform/clients/typescript`
+— see [How this differs from the TypeScript client](#how-this-differs-from-the-typescript-client)
+below.
+
+## Install
+
+Not published to npm yet. Use it locally:
+
+```bash
+npm install /Users/stan/Documents/git/clark/platform/clients/javascript
+# or, from another package in this monorepo:
+npm install ../../platform/clients/javascript
+```
+
+Or, in a browser, import it directly with no package manager at all:
+
+```html
+<script type="module">
+  import { ClarkClient } from "./node_modules/clark-platform-client-js/src/index.js";
+  const client = new ClarkClient({ apiKey: "clk_live_..." });
+</script>
+```
+
+## Quickstart: agentic (`clark`, `clark_max`, `openrouter:*`)
+
+```js
+import { ClarkClient } from "clark-platform-client-js";
+
+const client = new ClarkClient({
+  apiKey: process.env.CLARK_API_KEY, // clk_live_...
+  // baseUrl: "https://dev.clarkslabs.com", // defaults to https://www.clarkchat.com
+});
+
+// List available model tiers/options (never hardcode tier ids — they're dynamic).
+const { data: models } = await client.models.list();
+
+// One-shot Responses call.
+const response = await client.responses.create({
+  model: "clark",
+  input: "Summarize the latest Clark release notes.",
+});
+console.log(response.output[0].content[0].text);
+
+// Equivalent via the OpenAI-shaped chat.completions facade.
+const completion = await client.chat.completions.create({
+  model: "openrouter:qwen35_flash",
+  messages: [{ role: "user", content: "Summarize the latest Clark release notes." }],
+});
+console.log(completion.choices[0].message.content);
+
+// Multi-turn: resume a prior response's Clark conversation.
+const followUp = await client.responses.create({
+  model: "clark",
+  input: "Now do the same for last week.",
+  previousResponseId: response.id,
+});
+```
+
+`tools`/`tool_choice` are rejected with `400 unsupported_parameter` for these
+agentic tiers on both endpoints — Clark runs its own internal tool loop and
+only returns the final projected answer.
+
+## Streaming
+
+### `responses.stream()` — named SSE events
+
+```js
+for await (const event of client.responses.stream({ model: "clark", input: "hi" })) {
+  switch (event.type) {
+    case "response.output_text.delta":
+      // Note: the full answer arrives as ONE delta, not token-by-token.
+      process.stdout.write(event.delta);
+      break;
+    case "response.artifact.completed":
+      console.log("artifact:", event.artifact.name);
+      break;
+    case "response.completed":
+      console.log("done:", event.response.status);
+      break;
+    case "response.failed":
+      console.error("failed:", event.error ?? event.response?.error);
+      break;
+  }
+}
+```
+
+### `chat.completions.stream()` — OpenAI-style chunks, ending in `[DONE]`
+
+```js
+for await (const chunk of client.chat.completions.stream({
+  model: "clark",
+  messages: [{ role: "user", content: "hi" }],
+  streamOptions: { include_usage: true },
+})) {
+  const delta = chunk.choices[0]?.delta;
+  if (delta?.content) process.stdout.write(delta.content);
+  if (chunk.usage) console.log("\nusage:", chunk.usage);
+}
+```
+
+The generator returns (stream ends) when the server sends the literal
+`data: [DONE]` line — you never see `"[DONE]"` as a yielded value.
+
+## The `clark-code` passthrough tier
+
+`clark-code` behaves nothing like the agentic tiers: the **entire**
+`messages` array (including prior `assistant` messages with `tool_calls` and
+`tool` role messages) is forwarded verbatim to the upstream OpenAI-compatible
+provider, `tools`/`tool_choice` are required rather than rejected, and the
+response is the **raw upstream OpenAI-shaped object** — not a Clark
+`ResponseObject`/`ChatCompletionObject`. This client exposes it via distinct
+methods so you can't confuse the two shapes:
+
+```js
+const result = await client.chat.completions.createPassthrough({
+  model: "clark-code",
+  messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
+  tools: [
+    {
+      type: "function",
+      function: { name: "get_weather", parameters: { type: "object", properties: { city: { type: "string" } } } },
+    },
+  ],
+  toolChoice: "auto",
+});
+
+const toolCall = result.choices[0].message.tool_calls?.[0];
+if (toolCall) {
+  // Run the tool yourself — Clark does not execute tools for this tier —
+  // then append an assistant message (with tool_calls) and a `tool` message
+  // with the result, and call createPassthrough again with the full history.
+}
+```
+
+`streamPassthrough(...)` is the streaming counterpart, yielding the
+provider's native `chat.completion.chunk`-shaped deltas (including
+`tool_calls` deltas) and ending on `[DONE]`, same as above.
+
+Do not send `conversationId`/`previousResponseId`/`memoryScope` for this
+tier — there is no Clark conversation or memory scoping involved.
+
+## Other endpoints
+
+```js
+// Poll a response by id (e.g. after background: true, or to reconstruct
+// a timed-out chat-completions call via chatcmpl_<id> -> resp_<id>).
+const polled = await client.responses.get("resp_01jz4n8h2f7g9k4q2m6s");
+
+// Poll public progress events.
+const { data: events, next_after_seq } = await client.responses.listEvents(
+  "resp_01jz4n8h2f7g9k4q2m6s",
+  { afterSeq: 0, limit: 200 }
+);
+
+// Durable memory records.
+const { data: memories } = await client.memories.list({ q: "release notes" });
+
+// Prefer artifacts[].download_url; this is available for completeness.
+const fileResponse = await client.artifacts.download("conv-id", "analysis.md");
+const text = await fileResponse.text();
+```
+
+## Errors
+
+Every non-2xx response and network/parse failure raises `ClarkApiError`:
+
+```js
+import { ClarkApiError } from "clark-platform-client-js";
+
+try {
+  await client.chat.completions.create({ model: "clark", messages: [...], tools: [...] });
+} catch (err) {
+  if (err instanceof ClarkApiError) {
+    console.error(err.status, err.type, err.code, err.param, err.message);
+    // 400 invalid_request_error invalid_request_error tools "..."
+  }
+}
+```
+
+## Configuration
+
+```js
+new ClarkClient({
+  apiKey: "clk_live_...",       // required
+  baseUrl: "https://www.clarkchat.com", // default; also https://dev.clarkslabs.com
+  timeoutMs: 130_000,           // default; server-side non-background wait budget is ~120s
+  fetchFn: myCustomFetch,       // optional override, mainly for tests/non-global-fetch runtimes
+});
+```
+
+Every call also accepts a `signal: AbortSignal` for caller-driven
+cancellation; it's merged with the client's own timeout signal.
+
+## Testing
+
+```bash
+npm test          # node --test, fully offline against a local mock HTTP server
+npm run check     # node --check examples/live-smoke.js (syntax only, no network)
+```
+
+`examples/live-smoke.js` is an opt-in, real-network smoke test:
+
+```bash
+CLARK_API_BASE_URL=https://dev.clarkslabs.com \
+CLARK_API_KEY=clk_live_xxxx \
+CLARK_TEST_MODEL=openrouter:qwen35_flash \
+node examples/live-smoke.js
+```
+
+## How this differs from the TypeScript client
+
+`platform/clients/typescript` is a compiled TypeScript package meant for
+TypeScript projects with a build step. This package (`clark-platform-client-js`)
+is a **separate, independent implementation** built from the same
+[`API_CONTRACT.md`](../API_CONTRACT.md), for consumers who want:
+
+- Plain `.js` source with JSDoc comments for editor autocomplete/type-checking
+  (via `checkJs`), but no `tsc`/bundler step — the shipped files are the
+  source files.
+- Native ESM (`"type": "module"`) that works unmodified in both Node and
+  browsers via `<script type="module">`.
+- Zero runtime dependencies and a test suite on Node's built-in `node --test`
+  runner (no Jest/Vitest) for a genuinely lightweight footprint.
+
+A hand-written `types/index.d.ts` is included for TypeScript consumers who
+want IntelliSense against this package, but it is not required to use it and
+is not generated by a build step.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "clark-platform-client-js",
+  "version": "0.1.0",
+  "description": "Zero-build-step, plain-JavaScript client for the Clark Platform API (OpenAI-compatible-ish, with extras). Native ESM, no compile step required to consume.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "types": "./types/index.d.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src",
+    "types",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check examples/live-smoke.js"
+  },
+  "keywords": [
+    "clark",
+    "clark-platform",
+    "openai-compatible",
+    "sse",
+    "streaming"
+  ],
+  "license": "UNLICENSED",
+  "devDependencies": {},
+  "dependencies": {}
+}

package/src/client.js

@@ -0,0 +1,46 @@
+import { HttpTransport, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS } from "./http.js";
+import { Models } from "./resources/models.js";
+import { Responses } from "./resources/responses.js";
+import { ChatCompletions } from "./resources/chat_completions.js";
+import { Memories } from "./resources/memories.js";
+import { Artifacts } from "./resources/artifacts.js";
+
+/**
+ * Plain-JavaScript client for the Clark Platform API. No build step: import
+ * this module directly in Node (18+) or a browser via native ESM.
+ *
+ * @example
+ * import { ClarkClient } from "clark-platform-client-js";
+ * const client = new ClarkClient({ apiKey: process.env.CLARK_API_KEY });
+ * const { data } = await client.models.list();
+ */
+export class ClarkClient {
+  /**
+   * @param {Object} options
+   * @param {string} options.apiKey Bearer token, e.g. `clk_live_...`.
+   * @param {string} [options.baseUrl] Defaults to `https://www.clarkchat.com`.
+   * @param {number} [options.timeoutMs] Default request timeout; defaults to 130s to
+   *   comfortably exceed the server's ~120s non-background wait budget.
+   * @param {typeof fetch} [options.fetchFn] Override the fetch implementation (mainly for tests).
+   */
+  constructor(options) {
+    const http = new HttpTransport({
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      fetchFn: options.fetchFn,
+    });
+    this._http = http;
+
+    /** `GET /v1/models`. */
+    this.models = new Models(http);
+    /** `POST/GET /v1/responses`, `GET /v1/responses/{id}/events`. */
+    this.responses = new Responses(http);
+    /** `POST /v1/chat/completions` (agentic + `clark-code` passthrough). */
+    this.chat = { completions: new ChatCompletions(http) };
+    /** `GET /v1/memories`. */
+    this.memories = new Memories(http);
+    /** `GET /v1/artifacts/{conversation_id}/{artifact_name}`. */
+    this.artifacts = new Artifacts(http);
+  }
+}

package/src/errors.js

@@ -0,0 +1,103 @@
+/**
+ * @typedef {Object} ClarkErrorEnvelope
+ * @property {string} message
+ * @property {"invalid_request_error"|"authentication_error"|"permission_error"|"not_found_error"|"upstream_error"|"server_error"|string} type
+ * @property {string|null} [param]
+ * @property {string} [code]
+ */
+
+/**
+ * Error thrown for any non-2xx response from the Clark Platform API that
+ * carries the documented `{"error": {...}}` envelope (see API_CONTRACT.md).
+ *
+ * Also used (with a synthesized envelope) for network failures and
+ * malformed/unparseable responses so callers can catch a single error type.
+ */
+export class ClarkApiError extends Error {
+  /**
+   * @param {string} message
+   * @param {Object} [details]
+   * @param {number} [details.status] HTTP status code, if the error came from an HTTP response.
+   * @param {string} [details.type] Error type from the envelope (or a synthesized one).
+   * @param {string|null} [details.param]
+   * @param {string} [details.code]
+   * @param {unknown} [details.cause] Underlying cause (e.g. a fetch/network error).
+   * @param {Response} [details.response] The raw Response object, if available.
+   */
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "ClarkApiError";
+    this.status = details.status ?? null;
+    this.type = details.type ?? "client_error";
+    this.param = details.param ?? null;
+    this.code = details.code ?? details.type ?? "client_error";
+    this.cause = details.cause;
+    this.response = details.response;
+  }
+
+  /**
+   * Build a ClarkApiError from a fetch Response whose body is (expected to
+   * be) the standard `{"error": {...}}` JSON envelope. Falls back to a
+   * generic error if the body doesn't parse as JSON or doesn't match the
+   * envelope shape.
+   *
+   * @param {Response} response
+   * @returns {Promise<ClarkApiError>}
+   */
+  static async fromResponse(response) {
+    let bodyText = "";
+    try {
+      bodyText = await response.text();
+    } catch (err) {
+      return new ClarkApiError(
+        `Clark API request failed with status ${response.status} and an unreadable body`,
+        { status: response.status, type: "server_error", cause: err, response }
+      );
+    }
+
+    let parsed;
+    try {
+      parsed = bodyText ? JSON.parse(bodyText) : null;
+    } catch (err) {
+      return new ClarkApiError(
+        `Clark API request failed with status ${response.status}: ${bodyText.slice(0, 500)}`,
+        { status: response.status, type: "server_error", cause: err, response }
+      );
+    }
+
+    const envelope = parsed && typeof parsed === "object" ? parsed.error : null;
+    if (envelope && typeof envelope === "object" && typeof envelope.message === "string") {
+      return new ClarkApiError(envelope.message, {
+        status: response.status,
+        type: envelope.type,
+        param: envelope.param ?? null,
+        code: envelope.code ?? envelope.type,
+        response,
+      });
+    }
+
+    return new ClarkApiError(
+      `Clark API request failed with status ${response.status}`,
+      { status: response.status, type: "server_error", response }
+    );
+  }
+
+  /**
+   * Build a ClarkApiError representing a network-level failure (DNS, TLS,
+   * connection refused, abort, etc.) that never produced an HTTP response.
+   *
+   * @param {unknown} cause
+   * @returns {ClarkApiError}
+   */
+  static fromNetworkError(cause) {
+    const isAbort = cause && typeof cause === "object" && cause.name === "AbortError";
+    const message = isAbort
+      ? "Clark API request was aborted or timed out"
+      : `Clark API request failed: ${cause instanceof Error ? cause.message : String(cause)}`;
+    return new ClarkApiError(message, {
+      type: isAbort ? "timeout_error" : "network_error",
+      code: isAbort ? "timeout_error" : "network_error",
+      cause,
+    });
+  }
+}

package/src/http.js

@@ -0,0 +1,159 @@
+import { ClarkApiError } from "./errors.js";
+
+/** Default base URL for the Clark Platform API (production). */
+export const DEFAULT_BASE_URL = "https://www.clarkchat.com";
+
+/**
+ * Non-background `/v1/responses` and `/v1/chat/completions` calls can block
+ * server-side for up to `CLARK_PLATFORM_RESPONSE_WAIT_MS` (default 120000ms)
+ * per API_CONTRACT.md. Default client timeout is set generously above that.
+ */
+export const DEFAULT_TIMEOUT_MS = 130_000;
+
+/**
+ * Thin fetch wrapper: builds the URL, attaches Bearer auth, applies a
+ * timeout (merged with any caller-supplied AbortSignal), and normalizes
+ * both network failures and non-2xx HTTP responses into `ClarkApiError`.
+ */
+export class HttpTransport {
+  /**
+   * @param {Object} options
+   * @param {string} options.apiKey
+   * @param {string} [options.baseUrl]
+   * @param {number} [options.timeoutMs]
+   * @param {typeof fetch} [options.fetchFn] Override for testing or non-global fetch environments.
+   */
+  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL, timeoutMs = DEFAULT_TIMEOUT_MS, fetchFn }) {
+    if (!apiKey) {
+      throw new Error("Clark platform client requires an apiKey");
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.timeoutMs = timeoutMs;
+    /** @type {typeof fetch} */
+    this.fetchFn = fetchFn ?? globalThis.fetch;
+    if (!this.fetchFn) {
+      throw new Error(
+        "No global fetch is available in this environment; pass options.fetchFn explicitly"
+      );
+    }
+  }
+
+  /**
+   * @param {string} path
+   * @param {Record<string, string|number|boolean|undefined|null>} [query]
+   * @returns {string}
+   */
+  buildUrl(path, query) {
+    const url = new URL(this.baseUrl + path);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null) continue;
+        url.searchParams.set(key, String(value));
+      }
+    }
+    return url.toString();
+  }
+
+  /**
+   * Combine the client's default timeout with any caller-supplied signal.
+   * @param {AbortSignal} [callerSignal]
+   * @returns {{ signal: AbortSignal, cancel: () => void }}
+   */
+  _resolveSignal(callerSignal) {
+    const timeoutSignal = AbortSignal.timeout(this.timeoutMs);
+    const signals = callerSignal ? [callerSignal, timeoutSignal] : [timeoutSignal];
+    const combined =
+      typeof AbortSignal.any === "function" ? AbortSignal.any(signals) : timeoutSignal;
+    return { signal: combined, cancel: () => {} };
+  }
+
+  /**
+   * Perform a request and return the raw fetch Response, throwing
+   * ClarkApiError on network failure. Does NOT check response.ok — callers
+   * decide whether to parse JSON, stream, or raise on non-2xx.
+   *
+   * @param {string} method
+   * @param {string} path
+   * @param {Object} [options]
+   * @param {Record<string, string|number|boolean|undefined|null>} [options.query]
+   * @param {unknown} [options.body] JSON-serializable request body.
+   * @param {AbortSignal} [options.signal]
+   * @param {Record<string, string>} [options.headers]
+   * @returns {Promise<Response>}
+   */
+  async request(method, path, options = {}) {
+    const { query, body, signal, headers } = options;
+    const url = this.buildUrl(path, query);
+    const { signal: mergedSignal } = this._resolveSignal(signal);
+
+    /** @type {Record<string, string>} */
+    const reqHeaders = {
+      Authorization: `Bearer ${this.apiKey}`,
+      ...headers,
+    };
+    let payload;
+    if (body !== undefined) {
+      reqHeaders["Content-Type"] = "application/json";
+      payload = JSON.stringify(body);
+    }
+
+    try {
+      return await this.fetchFn(url, {
+        method,
+        headers: reqHeaders,
+        body: payload,
+        signal: mergedSignal,
+      });
+    } catch (err) {
+      throw ClarkApiError.fromNetworkError(err);
+    }
+  }
+
+  /**
+   * Perform a request and parse the JSON body, raising `ClarkApiError` for
+   * any non-2xx response using the documented error envelope.
+   *
+   * @param {string} method
+   * @param {string} path
+   * @param {Object} [options]
+   * @returns {Promise<any>}
+   */
+  async requestJson(method, path, options = {}) {
+    const response = await this.request(method, path, options);
+    if (!response.ok) {
+      throw await ClarkApiError.fromResponse(response);
+    }
+    const text = await response.text();
+    if (!text) return null;
+    try {
+      return JSON.parse(text);
+    } catch (err) {
+      throw new ClarkApiError(`Failed to parse Clark API response as JSON: ${err.message}`, {
+        status: response.status,
+        type: "server_error",
+        cause: err,
+      });
+    }
+  }
+
+  /**
+   * Perform a request expected to return an SSE stream, raising
+   * `ClarkApiError` for any non-2xx response before streaming begins.
+   *
+   * @param {string} method
+   * @param {string} path
+   * @param {Object} [options]
+   * @returns {Promise<Response>}
+   */
+  async requestStream(method, path, options = {}) {
+    const response = await this.request(method, path, {
+      ...options,
+      headers: { Accept: "text/event-stream", ...options.headers },
+    });
+    if (!response.ok) {
+      throw await ClarkApiError.fromResponse(response);
+    }
+    return response;
+  }
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export { ClarkClient } from "./client.js";
+export { ClarkApiError } from "./errors.js";
+export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS } from "./http.js";

package/src/resources/artifacts.js

@@ -0,0 +1,40 @@
+import { ClarkApiError } from "../errors.js";
+
+/**
+ * Thin wrapper for `GET /v1/artifacts/{conversation_id}/{artifact_name}`.
+ * Prefer the `download_url` returned inline on `ResponseObject.artifacts[]`
+ * over constructing this URL manually — this method exists for completeness
+ * (e.g. resuming a partial download via `Range`).
+ */
+export class Artifacts {
+  /** @param {import("../http.js").HttpTransport} http */
+  constructor(http) {
+    this._http = http;
+  }
+
+  /**
+   * Fetch the raw fetch `Response` for an artifact file so the caller can
+   * stream/read the body as needed (`.arrayBuffer()`, `.body` as a
+   * ReadableStream, etc.). Supports `Range` via `options.headers`.
+   *
+   * @param {string} conversationId
+   * @param {string} artifactName
+   * @param {Object} [options]
+   * @param {Record<string, string>} [options.headers] e.g. `{ Range: "bytes=0-1023" }`.
+   * @param {AbortSignal} [options.signal]
+   * @returns {Promise<Response>}
+   */
+  async download(conversationId, artifactName, options = {}) {
+    const path = `/v1/artifacts/${encodeURIComponent(conversationId)}/${encodeURIComponent(
+      artifactName
+    )}`;
+    const response = await this._http.request("GET", path, {
+      headers: options.headers,
+      signal: options.signal,
+    });
+    if (!response.ok) {
+      throw await ClarkApiError.fromResponse(response);
+    }
+    return response;
+  }
+}