ql-agent-sdk 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,247 @@
-# Temporary Holding Version
+# ql-agent-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript SDK for the **Quanton Labs** agent platform API (v1). Integrates your application with the 8 specialized agents, capabilities, workflows, and background tasks. Zero runtime dependencies — built on native `fetch` and Web Streams.
+
+> Base URL defaults to `https://app.quantonlabs.com`. Override with `baseUrl` or the `QL_BASE_URL` env var.
+
+## Install
+
+```bash
+npm install ql-agent-sdk
+# or
+pnpm add ql-agent-sdk
+```
+
+Requires **Node.js 18+** (native `fetch`). Works in Node, Bun, Deno, and browser/edge runtimes that provide `fetch` and Web Streams.
+
+## Quick start
+
+```ts
+import { QLClient } from "ql-agent-sdk";
+
+const ql = new QLClient({ apiKey: process.env.QL_API_KEY! });
+
+// Discover agents
+const { agents } = await ql.agents.list();
+console.log(agents.map((a) => a.id));
+
+// Chat with an agent (non-streaming)
+const reply = await ql.agents.chat({
+  agentId: "governing",
+  messages: [{ role: "user", content: "Summarize this quarter's revenue." }],
+});
+console.log(reply.content);
+```
+
+## Configuration
+
+```ts
+new QLClient({
+  apiKey,                 // required — your Bearer API key (never logged/exposed)
+  baseUrl,                // optional — defaults to QL_BASE_URL or https://app.quantonlabs.com
+  fetch: customFetch,     // optional — override for tests/proxies/custom runtimes
+});
+```
+
+`apiKey` is held in a private field and is never returned by the client, included in errors, or logged.
+
+## API reference
+
+### Workspace
+```ts
+const ws = await ql.workspace.get();          // -> { _id, name, plan, createdAt, updatedAt }
+```
+
+### Agents
+```ts
+const { agents } = await ql.agents.list();                 // AgentListResult
+const detail = await ql.agents.get("finance");             // AgentDetail (agent + capabilities)
+const caps   = await ql.agents.capabilities("finance");    // CapabilitiesResult
+
+// Run a capability ("feature"). The result is a discriminated union:
+const { result } = await ql.agents.runCapability("finance", {
+  capId: "invoice",
+  params: { data: "Revenue | 12000\nCosts | 4000" },
+});
+if (result.type === "html") render(result.html);
+else if (result.type === "json") use(result.data);
+else if (result.type === "text") print(result.content);
+// result.type === "file" -> { url, filename, mime }
+
+// Chat (non-streaming)
+const out = await ql.agents.chat({ agentId: "marketing", messages: [...] }); // ChatResult
+```
+
+### Streaming chat (SSE)
+`agents.chatStream` returns an **async iterable** of events. Stop it with an `AbortController`.
+
+```ts
+import { QLClient } from "ql-agent-sdk";
+
+const ql = new QLClient({ apiKey: process.env.QL_API_KEY! });
+const controller = new AbortController();
+
+// e.g. abort after 30s or on user action
+const timer = setTimeout(() => controller.abort(), 30_000);
+
+let full = "";
+try {
+  for await (const ev of ql.agents.chatStream(
+    { agentId: "governing", messages: [{ role: "user", content: "Hello" }] },
+    { signal: controller.signal },
+  )) {
+    if (ev.type === "delta") {
+      process.stdout.write(ev.content ?? "");   // incremental text
+      full += ev.content ?? "";
+    } else if (ev.type === "done") {
+      full = ev.content;                        // final accumulated text
+    }
+  }
+} catch (err) {
+  if ((err as any)?.code === "aborted") console.log("stopped by user");
+} finally {
+  clearTimeout(timer);
+}
+```
+
+The stream is robust to chunk boundaries, CRLF/LF endings, multiple events per chunk, a final event without a trailing newline, `[DONE]`, and malformed JSON (skipped).
+
+### History / pagination
+`agents.history` returns newest-first pages. Walk them with the `nextBefore` cursor until it is `null`.
+
+```ts
+const ids: string[] = [];
+let before: string | undefined;
+do {
+  const page = await ql.agents.history("finance", { limit: 50, before });
+  for (const m of page.items) ids.push(m.id);
+  before = page.nextBefore ?? undefined;   // null when exhausted
+} while (before);
+```
+
+### Workflows
+```ts
+const start = await ql.workflows.run("6adf929d6f87c9ab86f32c19", { input: { a: 1 } }); // 202 -> { runId, status: "running" }
+const run = await ql.workflows.getRun(start.runId);   // poll -> WorkflowRun (status/output/error/durationMs/...)
+```
+
+### Tasks (background)
+```ts
+const created = await ql.tasks.create({ agentId: "finance", title: "Monthly report", priority: "high" }); // 201 -> { taskId, status }
+const handle = ql.tasks.handle(created.taskId);
+
+// One-shot poll
+const snapshot = await handle.poll();
+
+// Wait until terminal (completed/failed/cancelled) with backoff + timeout + cancellation
+const done = await handle.wait({
+  intervalMs: 2000,      // initial delay
+  maxIntervalMs: 15000,  // backoff cap
+  timeoutMs: 5 * 60_000, // throw QLError(code="timeout") if exceeded
+  signal: controller.signal, // throw QLError(code="aborted") if aborted
+});
+```
+
+> **Task execution limitation:** `tasks.create` only **enqueues** a task. It may remain in the `queued` state until an existing worker/execution mechanism on the backend processes it — creating a task via this SDK does **not** trigger execution. `wait()` simply polls until the task reaches a terminal status (or you time out / abort).
+
+## Errors
+
+All failures throw a typed `QLError`:
+
+```ts
+import { QLClient, QLError } from "ql-agent-sdk";
+
+try {
+  await ql.agents.chat({ ... });
+} catch (err) {
+  if (err instanceof QLError) {
+    err.status;    // HTTP status (401/403/404/409/400/500) when from an HTTP response
+    err.code;      // stable code: unauthorized | forbidden | not_found | conflict |
+                   //             validation_error | internal_error | network | aborted | timeout
+    err.message;   // human-readable (never includes the API key)
+    err.isAuthError / err.isAborted / err.isTimeout / err.isNetworkError
+  }
+}
+```
+
+| HTTP status | `code` | Meaning |
+|---|---|---|
+| 401 | `unauthorized` | missing/invalid/revoked API key |
+| 403 | `forbidden` | key lacks the required scope |
+| 404 | `not_found` | resource not found in this workspace |
+| 409 | `conflict` | conflict (e.g. duplicate) |
+| 400 | `validation_error` | bad request / invalid params |
+| 5xx | `internal_error` | server error |
+
+Transport-level failures map to `network` (no HTTP response), `aborted` (caller aborted), and `timeout` (`wait()` exceeded its budget).
+
+## TypeScript
+
+The package ships full type declarations (`dist/index.d.ts` / `.d.cts`). All request/response types are exported:
+
+```ts
+import type {
+  QLClientOptions, ChatInput, ChatResult, ChatStreamEvent,
+  AgentSummary, CapabilityInfo, CapabilityResult, HistoryPage,
+  WorkflowRun, Task, TaskCreateInput, WaitOptions, QLError,
+} from "ql-agent-sdk";
+```
+
+## Using it in a Next.js App Router (server-side)
+
+In a **Route Handler** (`app/api/.../route.ts`) or a server Component — the SDK is safe to use on the server:
+
+```ts
+// app/api/agent/route.ts
+import { QLClient, QLError } from "ql-agent-sdk";
+
+export const runtime = "nodejs"; // uses native fetch + Web Streams
+
+const ql = new QLClient({ apiKey: process.env.QL_API_KEY! });
+
+export async function POST(req: Request) {
+  try {
+    const { prompt } = await req.json();
+    const res = await ql.agents.chat({
+      agentId: "governing",
+      messages: [{ role: "user", content: prompt }],
+    });
+    return Response.json({ ok: true, content: res.content });
+  } catch (err) {
+    if (err instanceof QLError) {
+      return Response.json({ ok: false, code: err.code, message: err.message }, { status: err.status ?? 500 });
+    }
+    throw err;
+  }
+}
+```
+
+For **streaming** to the browser from a Route Handler, forward the SDK's events as an SSE `ReadableStream` (see the streaming example above for consuming them).
+
+## Development
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit
+npm run lint        # eslint (typescript-eslint)
+npm test            # vitest (unit: fetch, errors, SSE, polling, timeout, cancellation, pagination)
+npm run build       # tsup -> dist (ESM + CJS + .d.ts)
+```
+
+## Publishing
+
+This package is **not** published. To publish when ready (requires an npm account/org):
+
+```bash
+npm login
+# from packages/sdk:
+npm run build
+npm publish --access public        # or --access restricted for a scoped/owned package
+```
+
+To install from a local tarball instead of publishing:
+
+```bash
+cd packages/sdk && npm pack        # -> ql-agent-sdk-0.1.0.tgz
+npm install /absolute/path/to/ql-agent-sdk-0.1.0.tgz
+```