ql-agent-sdk 0.0.0-stage → 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,416 @@
+interface JsonRequestOptions {
+    body?: unknown;
+    query?: Record<string, string | number | undefined>;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}
+/**
+ * Internal transport used by the API namespaces. Keeps the API key inside a
+ * closure (never exposed) and normalizes responses/errors for the caller.
+ */
+interface Transport {
+    /** Perform a JSON request and return the unwrapped `data` payload. */
+    json<T>(method: string, path: string, opts?: JsonRequestOptions): Promise<T>;
+    /**
+     * Perform a request expected to stream SSE. Returns the response body stream
+     * after verifying a 2xx + text/event-stream; throws QLError otherwise.
+     */
+    stream(method: string, path: string, opts?: JsonRequestOptions & {
+        acceptStream?: boolean;
+    }): Promise<ReadableStream<Uint8Array>>;
+}
+
+/**
+ * Public request/response types for the Quanton Labs agent platform API (v1).
+ *
+ * These mirror the verified Phase 1 endpoints. The public surface is enveloped:
+ *   success -> { ok: true, data }
+ *   error   -> { ok: false, error: { code, message } }
+ * The SDK unwraps `data` for you and surfaces errors as a typed QLError.
+ */
+/** Stable API error codes emitted by the backend. */
+declare const API_ERROR_CODES: {
+    readonly unauthorized: "unauthorized";
+    readonly forbidden: "forbidden";
+    readonly notFound: "not_found";
+    readonly validationError: "validation_error";
+    readonly conflict: "conflict";
+    readonly internalError: "internal_error";
+};
+type ApiErrorCode = (typeof API_ERROR_CODES)[keyof typeof API_ERROR_CODES];
+/** A single message in a chat conversation. */
+interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+/** Input for `agents.chat` and `agents.chatStream`. */
+interface ChatInput {
+    agentId: string;
+    messages: ChatMessage[];
+    /** Optional internal user id; defaults to the key's workspace when omitted. */
+    userId?: string;
+    /** Optional OpenRouter response-format hint (e.g. `{ type: "json_object" }`). */
+    response_format?: Record<string, unknown>;
+}
+/** Result of a non-streaming chat call. */
+interface ChatResult {
+    content: string;
+    toolCalls: number;
+    iterations: number;
+    /** Human-readable duration string, e.g. "2.91s". */
+    duration: string;
+}
+/**
+ * A single event yielded by `agents.chatStream`.
+ * - `delta`: an incremental piece of the streamed response (text and/or reasoning).
+ * - `done`: emitted once at the end with the fully accumulated text.
+ */
+type ChatStreamEvent = {
+    type: "delta";
+    content?: string;
+    reasoning?: string;
+} | {
+    type: "done";
+    content: string;
+    reasoning?: string;
+};
+/** Options accepted by streaming methods. */
+interface StreamOptions {
+    /** Abort the in-flight request/stream at any time. */
+    signal?: AbortSignal;
+}
+/** A conversation-history page (newest first). */
+interface MessageItem {
+    id: string;
+    role: string;
+    content: string | null;
+    reasoning?: string;
+    toolCalls: unknown[];
+    status: string;
+    timestamp: string | Date;
+}
+interface HistoryPage {
+    agentId: string;
+    limit: number;
+    /** Cursor for the next page (pass as `before`); null when exhausted. */
+    nextBefore: string | null;
+    items: MessageItem[];
+}
+/** Query params for `agents.history`. */
+interface HistoryParams {
+    /** Page size, 1..100 (default 20 server-side). */
+    limit?: number;
+    /** Cursor = id of the last item on the previous page. */
+    before?: string;
+    /** Optional internal user id filter. */
+    userId?: string;
+}
+/** Agent summary as returned by `agents.list`. */
+interface AgentSummary {
+    id: string;
+    name: string;
+    domain: string;
+    description: string;
+    icon: string;
+    tags: string[];
+    capabilityCount: number;
+}
+interface AgentListResult {
+    agents: AgentSummary[];
+}
+/** A schema-driven capability parameter (rendered as a form field in the UI). */
+type CapParamKind = "text" | "textarea" | "number" | "select" | "boolean" | "json";
+interface CapabilityParam {
+    key: string;
+    label: string;
+    kind: CapParamKind;
+    placeholder?: string;
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    required?: boolean;
+    hint?: string;
+    rows?: number;
+    [key: string]: unknown;
+}
+/** A pre-filled example input set (suggestion chip). */
+interface CapabilityTemplate {
+    label: string;
+    values: Record<string, unknown>;
+}
+/** A client-safe capability descriptor (the server-side `run` is stripped). */
+interface CapabilityInfo {
+    id: string;
+    name: string;
+    description: string;
+    category: string;
+    icon?: string;
+    badge?: string;
+    params: CapabilityParam[];
+    templates?: CapabilityTemplate[];
+    metrics?: string[];
+    tableKey?: string;
+    outputHint?: string;
+    [key: string]: unknown;
+}
+/** Agent detail + its capabilities, as returned by `agents.get`. */
+interface AgentDetail {
+    agent: {
+        id: string;
+        name: string;
+        domain: string;
+        description: string;
+        icon: string;
+        tags: string[];
+    };
+    capabilities: CapabilityInfo[];
+}
+/** Result of `agents.capabilities`. */
+interface CapabilitiesResult {
+    agentId: string;
+    capabilities: CapabilityInfo[];
+}
+/** Input for `agents.runCapability`. */
+interface RunCapabilityInput {
+    capId: string;
+    /** Capability-specific parameters (see the capability's `params`). */
+    params?: Record<string, unknown>;
+}
+/**
+ * The result of running a capability. A discriminated union matching the
+ * backend — a feature can return text, structured JSON, HTML, or a file URL.
+ */
+type CapabilityResult = {
+    type: "text";
+    content: string;
+} | {
+    type: "json";
+    data: unknown;
+} | {
+    type: "html";
+    html: string;
+} | {
+    type: "file";
+    url: string;
+    filename: string;
+    mime: string;
+};
+/** Result envelope for `agents.runCapability`. */
+interface RunCapabilityResult {
+    result: CapabilityResult;
+}
+/** The workspace object as returned by the public API (redacted). */
+interface Workspace {
+    _id: string;
+    name: string;
+    plan?: string;
+    createdAt?: string | Date;
+    updatedAt?: string | Date;
+}
+/** Input for `workflows.run`. */
+interface WorkflowRunInput {
+    /** Optional workflow input payload. */
+    input?: Record<string, unknown>;
+}
+/** Returned immediately when a workflow run is started (HTTP 202). */
+interface WorkflowRunStart {
+    runId: string;
+    status: "running";
+}
+type WorkflowRunStatus = "queued" | "running" | "completed" | "failed" | "cancelled" | (string & {});
+/** A workflow run snapshot, as returned by `workflows.getRun`. */
+interface WorkflowRun {
+    runId: string;
+    status: WorkflowRunStatus;
+    output: unknown | null;
+    error?: string;
+    durationMs?: number;
+    startedAt: string | Date;
+    finishedAt: string | Date | null;
+}
+type TaskPriority = "low" | "medium" | "high" | "urgent";
+/** Input for `tasks.create`. */
+interface TaskCreateInput {
+    agentId: string;
+    title: string;
+    description?: string;
+    /** Arbitrary payload handed to the agent. */
+    input?: unknown;
+    priority?: TaskPriority;
+}
+/** Returned when a task is created (HTTP 201). */
+interface TaskCreated {
+    taskId: string;
+    status: TaskStatus;
+}
+type TaskStatus = "queued" | "running" | "completed" | "failed" | "cancelled" | "retrying" | (string & {});
+/** A task snapshot, as returned by `tasks.get`. */
+interface Task {
+    taskId: string;
+    status: TaskStatus;
+    title: string;
+    progress?: unknown;
+    result?: unknown;
+    output?: unknown;
+    error?: string;
+    createdAt: string | Date;
+    completedAt: string | Date | null;
+}
+/** Options for polling / waiting on a task. */
+interface WaitOptions {
+    /** Base delay between polls in ms (default 2000). Grows with backoff up to `maxIntervalMs`. */
+    intervalMs?: number;
+    /** Upper bound for the backoff delay in ms (default 15000). */
+    maxIntervalMs?: number;
+    /** Stop waiting after this many ms and throw a timeout error. Omit to wait until terminal or abort. */
+    timeoutMs?: number;
+    /** Abort polling at any time. */
+    signal?: AbortSignal;
+    /** Called after each poll with the latest task snapshot. */
+    onTick?: (task: Task) => void;
+}
+
+declare function isTerminalTaskStatus(status: string): boolean;
+/**
+ * A handle to a background task created via `tasks.create`.
+ *
+ * NOTE on execution: creating a task only enqueues it. It may stay in the
+ * `queued` state until an existing worker/execution mechanism processes it —
+ * this SDK does not trigger execution. `wait()` simply polls until the task
+ * reaches a terminal status (or you time out / abort).
+ */
+declare class TaskHandle {
+    private readonly transport;
+    readonly taskId: string;
+    constructor(transport: Transport, taskId: string);
+    /** Fetch the current task snapshot (single request). */
+    get(signal?: AbortSignal): Promise<Task>;
+    /** Alias of `get()` — perform one poll and return the latest snapshot. */
+    poll(signal?: AbortSignal): Promise<Task>;
+    /**
+     * Poll until the task reaches a terminal status.
+     *
+     * - Uses exponential-ish backoff from `intervalMs` up to `maxIntervalMs`.
+     * - Throws a QLError with code "timeout" if `timeoutMs` elapses first.
+     * - Throws a QLError with code "aborted" if `signal` aborts.
+     */
+    wait(opts?: WaitOptions): Promise<Task>;
+}
+
+declare const DEFAULT_BASE_URL = "https://app.quantonlabs.com";
+interface QLClientOptions {
+    /** Your Quanton Labs API key (Bearer). Never logged or exposed. */
+    apiKey: string;
+    /** API base URL. Defaults to `QL_BASE_URL` if set, else https://app.quantonlabs.com. */
+    baseUrl?: string;
+    /** Override the global fetch (for tests, proxies, or custom runtimes). */
+    fetch?: typeof fetch;
+}
+/** Workspace namespace. */
+declare class WorkspaceApi {
+    private readonly t;
+    constructor(t: Transport);
+    /** GET /api/v1/workspace */
+    get(): Promise<Workspace>;
+}
+/** Agents namespace. */
+declare class AgentsApi {
+    private readonly t;
+    constructor(t: Transport);
+    /** GET /api/v1/agents — list the global agent registry. */
+    list(): Promise<AgentListResult>;
+    /** GET /api/v1/agents/:agentId — agent detail + capabilities. */
+    get(agentId: string): Promise<AgentDetail>;
+    /** GET /api/v1/agents/:agentId/capabilities */
+    capabilities(agentId: string): Promise<CapabilitiesResult>;
+    /** POST /api/v1/agents/:agentId/capabilities/run — run a feature. */
+    runCapability(agentId: string, input: RunCapabilityInput): Promise<RunCapabilityResult>;
+    /** POST /api/v1/agents/chat — non-streaming chat. */
+    chat(input: ChatInput): Promise<ChatResult>;
+    /**
+     * POST /api/v1/agents/chat/stream — streaming chat as an async iterable.
+     *
+     * Yields incremental `delta` events (text and/or reasoning) followed by a
+     * single `done` event with the fully accumulated text. Stop early by passing
+     * an `AbortSignal` (see StreamOptions) or breaking out of the loop.
+     */
+    chatStream(input: ChatInput, opts?: StreamOptions): AsyncIterable<ChatStreamEvent>;
+    /** GET /api/v1/agents/:agentId/messages — paginated history (newest first). */
+    history(agentId: string, params?: HistoryParams): Promise<HistoryPage>;
+    private chatStreamImpl;
+}
+/** Workflows namespace. */
+declare class WorkflowsApi {
+    private readonly t;
+    constructor(t: Transport);
+    /** POST /api/v1/workflows/:id/run — start a run (returns immediately, HTTP 202). */
+    run(workflowId: string, input?: WorkflowRunInput): Promise<WorkflowRunStart>;
+    /** GET /api/v1/workflow-runs/:runId — poll a run. */
+    getRun(runId: string): Promise<WorkflowRun>;
+}
+/** Tasks namespace. */
+declare class TasksApi {
+    private readonly t;
+    constructor(t: Transport);
+    /** POST /api/v1/tasks — create (enqueue) a background task. Does NOT trigger execution. */
+    create(input: TaskCreateInput): Promise<TaskCreated>;
+    /** GET /api/v1/tasks/:taskId — fetch the current snapshot. */
+    get(taskId: string, signal?: AbortSignal): Promise<Task>;
+    /** Get a handle for polling / waiting on a task (poll(), wait()). */
+    handle(taskId: string): TaskHandle;
+}
+/**
+ * The public client. Example:
+ *   const ql = new QLClient({ apiKey: process.env.QL_API_KEY });
+ *   const agents = await ql.agents.list();
+ */
+declare class QLClient {
+    readonly workspace: WorkspaceApi;
+    readonly agents: AgentsApi;
+    readonly workflows: WorkflowsApi;
+    readonly tasks: TasksApi;
+    private readonly transport;
+    private readonly base;
+    constructor(opts: QLClientOptions);
+    /** The normalized base URL in use (not secret). */
+    get baseUrl(): string;
+}
+
+interface QLErrorContext {
+    method?: string;
+    url?: string;
+}
+/**
+ * Error thrown by the SDK for any failed API interaction.
+ *
+ * - `status`: HTTP status code (when the failure came from an HTTP response).
+ * - `code`:   stable API error code when provided by the backend, otherwise a
+ *             synthesized one derived from the status, or a synthetic transport
+ *             code such as "aborted" / "timeout" / "network".
+ * - `message`: human-readable description. The API key is never included.
+ */
+declare class QLError extends Error {
+    readonly status?: number;
+    readonly code: string;
+    readonly method?: string;
+    readonly url?: string;
+    /** The raw parsed error body (if any), for advanced inspection. */
+    readonly details?: unknown;
+    constructor(message: string, opts?: {
+        status?: number;
+        code: string;
+        context?: QLErrorContext;
+        details?: unknown;
+    });
+    /** True for 401/403 or unauthorized/forbidden codes. */
+    get isAuthError(): boolean;
+    /** True when the request was aborted by the caller. */
+    get isAborted(): boolean;
+    /** True when a wait() call exceeded its timeout. */
+    get isTimeout(): boolean;
+    /** True for transient network failures (no HTTP response received). */
+    get isNetworkError(): boolean;
+}
+
+export { API_ERROR_CODES, type AgentDetail, type AgentListResult, type AgentSummary, AgentsApi, type ApiErrorCode, type CapParamKind, type CapabilitiesResult, type CapabilityInfo, type CapabilityParam, type CapabilityResult, type CapabilityTemplate, type ChatInput, type ChatMessage, type ChatResult, type ChatStreamEvent, DEFAULT_BASE_URL, type HistoryPage, type HistoryParams, type MessageItem, QLClient, type QLClientOptions, QLError, type QLErrorContext, type RunCapabilityInput, type RunCapabilityResult, type StreamOptions, type Task, type TaskCreateInput, type TaskCreated, TaskHandle, type TaskPriority, type TaskStatus, TasksApi, type WaitOptions, type WorkflowRun, type WorkflowRunInput, type WorkflowRunStart, type WorkflowRunStatus, WorkflowsApi, type Workspace, WorkspaceApi, isTerminalTaskStatus };