@darqlabs/curator-sdk 0.1.0

package/dist/cjs/sse.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Tiny SSE parser.
+ *
+ * Reads a `ReadableStream<Uint8Array>` (the body returned by `fetch`)
+ * and yields SSE frames as `{ event, data }`. Spec essentials: lines
+ * separated by `\n` (or `\r\n`), blank line terminates a message,
+ * `event:` and `data:` fields are accumulated until the terminator,
+ * `:` lines are comments and ignored. We don't track ids or retries —
+ * not needed for the wait-for-terminal use case.
+ *
+ * Used by Chat.stream() to turn the backend's SSE response into typed
+ * stream events.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSseStream = parseSseStream;
+async function* parseSseStream(stream) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder("utf-8");
+    let buffer = "";
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            // Split on blank-line terminators (either \n\n or \r\n\r\n). The
+            // last chunk in the buffer may be a partial frame; we keep it for
+            // the next read.
+            let boundary = findBoundary(buffer);
+            while (boundary !== -1) {
+                const rawFrame = buffer.slice(0, boundary);
+                buffer = buffer.slice(boundary).replace(/^(\r?\n)+/, "");
+                const frame = parseFrame(rawFrame);
+                if (frame)
+                    yield frame;
+                boundary = findBoundary(buffer);
+            }
+        }
+        // Flush any trailing complete frame (no blank line, but the stream ended).
+        if (buffer.trim().length > 0) {
+            const frame = parseFrame(buffer);
+            if (frame)
+                yield frame;
+        }
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+function findBoundary(s) {
+    const a = s.indexOf("\n\n");
+    const b = s.indexOf("\r\n\r\n");
+    if (a === -1)
+        return b;
+    if (b === -1)
+        return a;
+    return Math.min(a, b);
+}
+function parseFrame(raw) {
+    let event = "message";
+    const dataLines = [];
+    for (const line of raw.split(/\r?\n/)) {
+        if (line.length === 0)
+            continue;
+        if (line.startsWith(":"))
+            continue; // comment / heartbeat
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        // Spec: a single leading space after the colon is stripped.
+        let value = colon === -1 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        if (field === "event")
+            event = value;
+        else if (field === "data")
+            dataLines.push(value);
+        // ignore id / retry
+    }
+    if (dataLines.length === 0 && event === "message")
+        return null;
+    return { event, data: dataLines.join("\n") };
+}
+//# sourceMappingURL=sse.js.map

package/dist/cjs/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/sse.ts"],"names":[],"mappings":"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"}

package/dist/cjs/streamEventParse.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Stable mapping from SSE frames emitted by `POST /messages?stream=true`
+ * to the public `StreamEvent` discriminated union.
+ *
+ * Extracted from the client so each branch can be unit-tested in
+ * isolation — bug-prone because it lives at the contract boundary
+ * between backend and SDK and silently mis-mapped fields would surface
+ * as confusing UX, not loud errors.
+ */
+import type { SseFrame } from "./sse.js";
+import type { StreamEvent } from "./streamEvents.js";
+export declare function frameToStreamEvent(frame: SseFrame): StreamEvent | null;
+//# sourceMappingURL=streamEventParse.d.ts.map

package/dist/cjs/streamEventParse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamEventParse.d.ts","sourceRoot":"","sources":["../../src/streamEventParse.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,GAAG,WAAW,GAAG,IAAI,CAkEtE"}

package/dist/cjs/streamEventParse.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Stable mapping from SSE frames emitted by `POST /messages?stream=true`
+ * to the public `StreamEvent` discriminated union.
+ *
+ * Extracted from the client so each branch can be unit-tested in
+ * isolation — bug-prone because it lives at the contract boundary
+ * between backend and SDK and silently mis-mapped fields would surface
+ * as confusing UX, not loud errors.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.frameToStreamEvent = frameToStreamEvent;
+function frameToStreamEvent(frame) {
+    let data;
+    try {
+        data = frame.data ? JSON.parse(frame.data) : {};
+    }
+    catch {
+        return null;
+    }
+    switch (frame.event) {
+        case "delta":
+            return { type: "delta", text: String(data.text ?? "") };
+        case "tool_call.started":
+            return {
+                type: "tool_call.started",
+                toolCallId: String(data.tool_call_id),
+                toolName: String(data.tool_name),
+                capabilityId: String(data.capability_id),
+            };
+        case "tool_call.completed":
+            return {
+                type: "tool_call.completed",
+                toolCallId: String(data.tool_call_id),
+                toolName: String(data.tool_name),
+                capabilityId: String(data.capability_id),
+                durationMs: Number(data.duration_ms ?? 0),
+            };
+        case "done": {
+            const m = data.message;
+            return {
+                type: "done",
+                runId: String(data.run_id ?? ""),
+                conversationId: String(data.conversation_id ?? ""),
+                message: m
+                    ? {
+                        role: "assistant",
+                        content: String(m.content ?? ""),
+                        sequence: Number(m.sequence ?? 0),
+                        stepId: m.step_id ?? null,
+                        createdAt: String(m.created_at ?? ""),
+                        runId: String(data.run_id ?? ""),
+                        conversationId: String(data.conversation_id ?? ""),
+                    }
+                    : null,
+            };
+        }
+        case "error":
+            return {
+                type: "error",
+                failureClass: data.failure_class,
+                isPermanent: !!data.is_permanent,
+                message: String(data.message ?? ""),
+                stepId: data.step_id ?? null,
+                runId: String(data.run_id ?? ""),
+                conversationId: String(data.conversation_id ?? ""),
+            };
+        case "paused_for_approval":
+            return {
+                type: "paused_for_approval",
+                approval: data.approval,
+                runId: String(data.run_id ?? ""),
+                conversationId: String(data.conversation_id ?? ""),
+            };
+        default:
+            // Unknown event types are dropped so the SDK stays forward-compatible
+            // with future backend additions.
+            return null;
+    }
+}
+//# sourceMappingURL=streamEventParse.js.map

package/dist/cjs/streamEventParse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamEventParse.js","sourceRoot":"","sources":["../../src/streamEventParse.ts"],"names":[],"mappings":"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"}

package/dist/cjs/streamEvents.d.ts

@@ -0,0 +1,58 @@
+/**
+ * SDK-facing stream event types — what `chat.stream(...)` yields.
+ *
+ * Mirrors the SSE frames the backend emits on `POST /messages?stream=true`.
+ * Stable across backend refactors; the bus-event → stream-event mapping
+ * lives on the server.
+ *
+ * Terminal events (`done`, `error`, `paused_for_approval`) end the
+ * iterator. `delta` and `tool_call.*` events arrive incrementally.
+ */
+import type { AgentFailureClass, ApprovalDetails, AssistantMessage } from "./types";
+/** Incremental token delta from the agent. */
+export interface StreamDelta {
+    type: "delta";
+    text: string;
+}
+/** Agent started a tool call. */
+export interface StreamToolCallStarted {
+    type: "tool_call.started";
+    toolCallId: string;
+    toolName: string;
+    capabilityId: string;
+}
+/** Agent finished a tool call. */
+export interface StreamToolCallCompleted {
+    type: "tool_call.completed";
+    toolCallId: string;
+    toolName: string;
+    capabilityId: string;
+    durationMs: number;
+}
+/** Terminal: assistant finished, no more tokens. */
+export interface StreamDone {
+    type: "done";
+    message: AssistantMessage | null;
+    runId: string;
+    conversationId: string;
+}
+/** Terminal: agent failed. */
+export interface StreamError {
+    type: "error";
+    failureClass: AgentFailureClass;
+    isPermanent: boolean;
+    message: string;
+    stepId: string | null;
+    runId: string;
+    conversationId: string;
+}
+/** Terminal: run paused waiting for HITL approval. */
+export interface StreamPausedForApproval {
+    type: "paused_for_approval";
+    approval: ApprovalDetails;
+    runId: string;
+    conversationId: string;
+}
+export type StreamEvent = StreamDelta | StreamToolCallStarted | StreamToolCallCompleted | StreamDone | StreamError | StreamPausedForApproval;
+export declare function isTerminalStreamEvent(e: StreamEvent): boolean;
+//# sourceMappingURL=streamEvents.d.ts.map

package/dist/cjs/streamEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamEvents.d.ts","sourceRoot":"","sources":["../../src/streamEvents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAEnF,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACb;AAED,iCAAiC;AACjC,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,mBAAmB,CAAA;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,kCAAkC;AAClC,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,qBAAqB,CAAA;IAC3B,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAA;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,8BAA8B;AAC9B,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAA;IACb,YAAY,EAAE,iBAAiB,CAAA;IAC/B,WAAW,EAAE,OAAO,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,sDAAsD;AACtD,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,qBAAqB,CAAA;IAC3B,QAAQ,EAAE,eAAe,CAAA;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,MAAM,WAAW,GACnB,WAAW,GACX,qBAAqB,GACrB,uBAAuB,GACvB,UAAU,GACV,WAAW,GACX,uBAAuB,CAAA;AAQ3B,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,WAAW,GAAG,OAAO,CAE7D"}

package/dist/cjs/streamEvents.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * SDK-facing stream event types — what `chat.stream(...)` yields.
+ *
+ * Mirrors the SSE frames the backend emits on `POST /messages?stream=true`.
+ * Stable across backend refactors; the bus-event → stream-event mapping
+ * lives on the server.
+ *
+ * Terminal events (`done`, `error`, `paused_for_approval`) end the
+ * iterator. `delta` and `tool_call.*` events arrive incrementally.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTerminalStreamEvent = isTerminalStreamEvent;
+const TERMINAL_TYPES = new Set([
+    "done",
+    "error",
+    "paused_for_approval",
+]);
+function isTerminalStreamEvent(e) {
+    return TERMINAL_TYPES.has(e.type);
+}
+//# sourceMappingURL=streamEvents.js.map

package/dist/cjs/streamEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamEvents.js","sourceRoot":"","sources":["../../src/streamEvents.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AAoEH,sDAEC;AARD,MAAM,cAAc,GAAqC,IAAI,GAAG,CAAC;IAC/D,MAAM;IACN,OAAO;IACP,qBAAqB;CACtB,CAAC,CAAA;AAEF,SAAgB,qBAAqB,CAAC,CAAc;IAClD,OAAO,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;AACnC,CAAC"}

package/dist/cjs/types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Shapes exposed by the SDK.
+ *
+ * These mirror the backend response shapes but are intentionally
+ * decoupled from `@darq/shared-types` so the SDK can be published
+ * without dragging the entire internal type surface along with it.
+ */
+export type Environment = "production" | "staging" | "development";
+export interface AssistantMessage {
+    role: "assistant";
+    content: string;
+    /** Monotonic per-conversation sequence number. */
+    sequence: number;
+    /** The agent step that produced this message, if known. */
+    stepId: string | null;
+    /** ISO-8601 timestamp. */
+    createdAt: string;
+    /** Run that produced this message. */
+    runId: string;
+    conversationId: string;
+}
+export interface UserMessage {
+    role: "user";
+    content: string;
+    sequence: number;
+    createdAt: string;
+}
+export interface ToolMessage {
+    role: "tool";
+    content: string;
+    sequence: number;
+    toolCallId: string | null;
+    createdAt: string;
+}
+export type ConversationMessage = AssistantMessage | UserMessage | ToolMessage;
+export interface FileAttachment {
+    /** Path of the artifact in object storage. */
+    storageKey: string;
+    mimeType: string;
+    filename: string;
+    size: number;
+    /** Artifact id, when one has been recorded. */
+    artifactId?: string;
+}
+export type AgentFailureClass = "provider_quota_exhausted" | "provider_auth" | "provider_bad_request" | "provider_rate_limited" | "provider_unavailable" | "internal" | "unknown";
+export interface ApprovalDetails {
+    approval_id: string;
+    tool_call_id: string;
+    capability_id: string;
+    tool_name: string;
+    arguments: Record<string, unknown>;
+    nested_approval?: {
+        agent_id: string;
+        agent_name: string;
+        tool_name: string;
+        capability_id: string;
+        arguments?: Record<string, unknown>;
+        depth: number;
+    };
+}
+export interface SendOptions {
+    /** Optional file attachments. */
+    files?: FileAttachment[];
+    /** Override the SDK-default wait timeout for this call. */
+    timeoutMs?: number;
+}
+export interface HistoryOptions {
+    /** Max messages to return (server-capped at 500). */
+    limit?: number;
+    /** Pagination cursor — pass the oldest sequence returned previously. */
+    beforeSequence?: number;
+}
+export interface HistoryPage {
+    messages: ConversationMessage[];
+    hasMore: boolean;
+    oldestSequence: number | null;
+    totalMessageCount: number;
+}
+/**
+ * Read-only, per-deployment client config. Resolved server-side from the
+ * owning org's subscription — the SDK never decides these itself. Fetched
+ * once on widget mount via `agent(...).config()`.
+ */
+export interface DeploymentConfig {
+    branding: {
+        /**
+         * When true, the org's tier entitles it to run the widget without the
+         * "Powered by Curator" footer. `false` for tiers without white-label.
+         */
+        hidePoweredBy: boolean;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cjs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,SAAS,GAAG,aAAa,CAAA;AAElE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,WAAW,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAA;IAChB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,GAAG,WAAW,GAAG,WAAW,CAAA;AAE9E,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,MAAM,iBAAiB,GACzB,0BAA0B,GAC1B,eAAe,GACf,sBAAsB,GACtB,uBAAuB,GACvB,sBAAsB,GACtB,UAAU,GACV,SAAS,CAAA;AAEb,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,eAAe,CAAC,EAAE;QAChB,QAAQ,EAAE,MAAM,CAAA;QAChB,UAAU,EAAE,MAAM,CAAA;QAClB,SAAS,EAAE,MAAM,CAAA;QACjB,aAAa,EAAE,MAAM,CAAA;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACnC,KAAK,EAAE,MAAM,CAAA;KACd,CAAA;CACF;AAED,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,KAAK,CAAC,EAAE,cAAc,EAAE,CAAA;IACxB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,mBAAmB,EAAE,CAAA;IAC/B,OAAO,EAAE,OAAO,CAAA;IAChB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,iBAAiB,EAAE,MAAM,CAAA;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE;QACR;;;WAGG;QACH,aAAa,EAAE,OAAO,CAAA;KACvB,CAAA;CACF"}

package/dist/cjs/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Shapes exposed by the SDK.
+ *
+ * These mirror the backend response shapes but are intentionally
+ * decoupled from `@darq/shared-types` so the SDK can be published
+ * without dragging the entire internal type surface along with it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/dist/esm/client.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Public surface of the Curator SDK.
+ *
+ *   const curator = new Curator({ apiKey, project, environment })
+ *   const reply = await curator.agent("support-bot").run("hello")
+ *
+ *   const chat = curator.agent("support-bot").chat()
+ *   const r1 = await chat.send("first")
+ *   const r2 = await chat.send("follow up")
+ *
+ *   const chat = curator.agent("support-bot").conversation("conv_xxx")
+ *   const r = await chat.send("continuing later")
+ *
+ * Both helpers route through `?wait=true` under the hood — the caller
+ * never sees `run_id` or has to poll. Non-completion states (HITL
+ * pause, terminal agent error, timeout) surface as typed errors from
+ * `./errors`. HITL approvals are NOT resolved through the SDK — the
+ * pause is surfaced as an error so the calling app can tell its user
+ * to contact an administrator, who handles it in the dashboard.
+ */
+import { Files } from "./files.js";
+import { HttpClient, type DeploymentRoute, type EndUserJwtProvider } from "./http.js";
+import type { StreamEvent } from "./streamEvents.js";
+import type { AssistantMessage, DeploymentConfig, Environment, HistoryOptions, HistoryPage, SendOptions } from "./types.js";
+export interface CuratorOptions {
+    /** Org-scoped API key from Settings → Developer. `curator_live_*` for production, `curator_test_*` for staging / development. */
+    apiKey: string;
+    /**
+     * Base URL of the Curator deployment. Defaults to the public host.
+     * Override for self-hosted or staging environments.
+     */
+    baseUrl?: string;
+    /** Default project slug. Can be overridden per-call via `agent(slug, { project })`. */
+    project?: string;
+    /** Default environment. Can be overridden per-call via `agent(slug, { environment })`. */
+    environment?: Environment;
+    /** Default sync-wait timeout, in ms. The server caps this at 300s. */
+    defaultTimeoutMs?: number;
+    /** Custom fetch implementation (test stubs, older Node, etc.). */
+    fetch?: typeof fetch;
+    /** Extra headers attached to every request. */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * End-user JWT — proves which user on the customer's platform is driving
+     * the agent. Required when the org has opted into verified end-user
+     * identity. Accepts either a static string or a sync/async function the
+     * SDK calls per-request (typical for browsers refreshing short-lived
+     * tokens via their backend). See {@link EndUserJwtProvider}.
+     */
+    endUserJwt?: EndUserJwtProvider;
+}
+export interface AgentLocator {
+    /** Project slug. Defaults to the value passed to `new Curator({ project })`. */
+    project?: string;
+    /** Environment. Defaults to the value passed to `new Curator({ environment })`. */
+    environment?: Environment;
+    /**
+     * Set to true to address a system-scoped deployment (no project /
+     * environment in the path). Mutually exclusive with `project`.
+     */
+    system?: boolean;
+}
+export declare class Curator {
+    private readonly http;
+    private readonly defaultProject?;
+    private readonly defaultEnvironment;
+    private readonly defaultTimeoutMs;
+    /** File-upload surface — see {@link Files}. */
+    readonly files: Files;
+    constructor(opts: CuratorOptions);
+    /**
+     * Address an agent deployment by its slug. Project / environment fall
+     * back to the constructor defaults; pass overrides via the second arg.
+     */
+    agent(slug: string, locator?: AgentLocator): Agent;
+    private resolveRoute;
+}
+export declare class Agent {
+    private readonly http;
+    private readonly defaultTimeoutMs;
+    private readonly route;
+    /** @internal */
+    constructor(http: HttpClient, defaultTimeoutMs: number, route: DeploymentRoute);
+    /**
+     * Open a fresh conversation, send `content`, await the reply, and
+     * return it. Equivalent to `agent.chat().send(content)` but one line.
+     */
+    run(content: string, opts?: SendOptions): Promise<AssistantMessage>;
+    /**
+     * Open a fresh conversation and stream the reply as it's generated.
+     * Equivalent to `agent.chat().stream(content)`.
+     */
+    stream(content: string, opts?: SendOptions): AsyncIterable<StreamEvent>;
+    /**
+     * Return a Chat handle whose conversation is created lazily on the
+     * first `send(...)`. Subsequent sends reuse the same conversation.
+     */
+    chat(): Chat;
+    /**
+     * Reattach to an existing conversation by id (e.g. resuming a chat
+     * across processes or restoring from durable state).
+     */
+    conversation(conversationId: string): Chat;
+    /**
+     * Fetch this deployment's read-only client config (branding entitlements,
+     * etc.). Resolved server-side from the org's subscription tier. No side
+     * effects — safe to call on widget mount. `<CuratorChat />` uses this to
+     * decide whether to render the "Powered by Curator" footer.
+     */
+    config(): Promise<DeploymentConfig>;
+}
+export declare class Chat {
+    private readonly http;
+    private readonly defaultTimeoutMs;
+    private readonly route;
+    private conversationId;
+    /** Cached promise for an in-flight `POST /conversations`. */
+    private pendingCreate;
+    /** @internal */
+    constructor(http: HttpClient, defaultTimeoutMs: number, route: DeploymentRoute, initialConversationId: string | null);
+    /**
+     * Conversation id, or `null` until the first send creates one.
+     * Use `.ensureId()` if you need to materialize the conversation
+     * eagerly without sending a message.
+     */
+    get id(): string | null;
+    /** Force conversation creation now and return its id. */
+    ensureId(): Promise<string>;
+    /**
+     * Send a user message and await the assistant's reply. Lazily creates
+     * the conversation if needed. Returns the final assistant message.
+     *
+     * Throws:
+     *   - CuratorApprovalRequiredError if the run pauses for HITL (an
+     *     administrator must resolve it in the dashboard)
+     *   - CuratorAgentError on terminal agent failure
+     *   - CuratorTimeoutError if the wait expires (the run keeps running)
+     */
+    send(content: string, opts?: SendOptions): Promise<AssistantMessage>;
+    /**
+     * Send a user message and stream the agent's response back as it's
+     * generated. Each yielded event is one of `delta` / `tool_call.*` /
+     * `done` / `error` / `paused_for_approval`. The iterator ends on the
+     * first terminal event.
+     *
+     *   for await (const e of chat.stream("hello")) {
+     *     if (e.type === "delta") process.stdout.write(e.text)
+     *     if (e.type === "done") console.log("\nfinal:", e.message?.content)
+     *   }
+     *
+     * Aborting the iteration (breaking out of the loop, or calling
+     * `.return()`) closes the underlying HTTP connection — the server-
+     * side run keeps going independently. Use `chat.history()` later to
+     * fetch what landed.
+     */
+    stream(content: string, opts?: SendOptions): AsyncGenerator<StreamEvent, void, void>;
+    /** Fetch (paginated) conversation history. */
+    history(opts?: HistoryOptions): Promise<HistoryPage>;
+    private createConversation;
+    /**
+     * Continue waiting for the next terminal state on an already-running
+     * conversation. Used to back `CuratorTimeoutError.continueWaiting()`.
+     *
+     * The server-side wait endpoint hangs off `POST /messages`, so to
+     * re-wait without sending a new user message we poll history for an
+     * assistant message whose `sequence` exceeds the baseline established
+     * before the wait began. For a still-in-flight run, the assistant
+     * reply typically lands within seconds.
+     */
+    private waitForNextReply;
+    private latestSequence;
+    private unwrapWaitOutcome;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/esm/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}