API client reference

export interface Cumulus extends DomainMethods {
}

export declare class Cumulus {
    #private;
    constructor(options?: CumulusOptions);
    call<K extends OperationId>(operationId: K, input: OperationInput<K>, signal?: AbortSignal): Promise<OperationResult<K>>;
    /** runs.events as text/event-stream; resume with lastEventId (= last seen sequence). No client timeout. With
     * `onProgress`, the stream also carries live progress hints (`progress: "live"`: the run's transcript or effect ledger
     * moved), which go to the callback; only journal events are yielded. */
    events(input: OperationInput<"runs.events"> & {
        lastEventId?: string;
        onProgress?: (progress: RunProgress) => void;
    }, signal?: AbortSignal): AsyncGenerator<SemanticEvent>;
    /** Any journal operation served as text/event-stream (`stream: "sse"` in the registry: runs.events,
     * test_runs.events); resume with lastEventId (= last seen sequence). No client timeout. */
    stream<K extends StreamOperationId>(operationId: K, input: OperationInput<K> & {
        lastEventId?: string;
    }, signal?: AbortSignal, onProgress?: (progress: RunProgress) => void, onCursor?: (cursor: string) => void): AsyncGenerator<SemanticEvent>;
}

export declare function listOperations(): readonly OperationId[];

/**
 * Every failure, typed. Transport failures are classified exactly like the MCP server
 * (packages/mcp-server/src/rest.ts): a connection that was never established is `internal` with
 * `outcome: "none"`; a command whose acknowledgement is lost is `outcome_unknown` with
 * `outcome: "unknown"` and carries the `idempotencyKey` to retry with.
 */
export declare class PlatformError extends Error {
    readonly status: number | null;
    readonly idempotencyKey?: string | undefined;
    readonly code: ApiErrorCode;
    readonly retryable: boolean;
    readonly outcome: "none" | "unknown";
    readonly details: Record<string, unknown>;
    constructor(error: ApiErrorBody["error"], status: number | null, idempotencyKey?: string | undefined, options?: {
        cause?: unknown;
    });
    /** A command whose result was not confirmed: it may have taken effect; retry with the same key. */
    static unconfirmed(status: number | null, idempotencyKey?: string, cause?: unknown): PlatformError;
    /** A read that failed in transport or on the owner: nothing took effect. */
    static unavailable(status: number | null, idempotencyKey?: string, cause?: unknown): PlatformError;
    /** A 2xx whose body could not be read as JSON. */
    static invalidResponse(kind: OperationKind, status: number, idempotencyKey?: string, cause?: unknown): PlatformError;
    static fromResponse(response: Response, kind: OperationKind, idempotencyKey?: string): Promise<PlatformError>;
    static transport(error: unknown, kind: OperationKind, idempotencyKey?: string): PlatformError;
}

export type ApiErrorBody = components["schemas"]["ApiError"];

export type ApiErrorCode = ApiErrorBody["error"]["code"];

export interface CumulusOptions {
    /** Sent as `Authorization: Bearer`. Default `CUMULUS_API_KEY`. Without a key no Authorization header is sent:
     * a browser client calls a same-origin proxy that authenticates the session cookie server-side. */
    apiKey?: string;
    /** Every operation's host (D18: one public API host). Default `CUMULUS_BASE_URL` or https://api.cumuluslabs.io.
     * A relative URL (`/cp-proxy`) resolves against the page location in a browser. */
    baseUrl?: string;
    /** Per-owner hosts for a split deployment (a local stack serves Talos and the control plane apart). */
    talosUrl?: string;
    controlPlaneUrl?: string;
    fetch?: typeof fetch;
    timeoutMs?: number;
    /** Deployment paths keyed by stable contract operation ID. */
    operationPaths?: Partial<Record<OperationId, string>>;
    /** Defaults true. Disable only for deliberately partial transport fixtures. */
    validateResponses?: boolean;
}

export type DomainMethods = Methods<Domains>;

export type OperationBody<K extends OperationId> = Op<K> extends {
    requestBody: infer R;
} ? Json<R> : never;

export type OperationId = keyof operations;

export type OperationInput<K extends OperationId> = Part<"path", OperationPath<K>, false> & Part<"query", OperationQuery<K>, true> & Part<"body", OperationBody<K>, false> & {
    idempotencyKey?: string;
};

export type OperationKind = "read" | "command";

export interface OperationMeta {
    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
    path: string;
    owner: "talos" | "control-plane";
    kind: "read" | "command";
    idempotency: "required_header" | "natural" | "none";
    stream: "sse" | null;
    successStatus: number;
}

export type OperationPath<K extends OperationId> = Op<K> extends {
    parameters: {
        path: infer P;
    };
} ? P : never;

export type OperationQuery<K extends OperationId> = Op<K> extends {
    parameters: {
        query?: infer Q;
    };
} ? NonNullable<Q> : never;

export type OperationResult<K extends OperationId> = Op<K> extends {
    responses: infer R;
} ? {
    [S in keyof R]: S extends 200 | 201 | 202 ? Json<R[S]> : never;
}[keyof R] : never;

export type SemanticEvent = components["schemas"]["SemanticEvent"];

/** Operations the registry serves as text/event-stream (`Cumulus.stream`). */
export type StreamOperationId = {
    [K in OperationId]: (typeof OPERATIONS)[K]["stream"] extends "sse" ? K : never;
}[OperationId];

type Op<K extends OperationId> = operations[K];

type Json<T> = T extends {
    content: {
        "application/json": infer B;
    };
} ? B : never;

type Part<Key extends string, T, Optional extends boolean> = [
    T
] extends [
    never
] ? {
    [P in Key]?: undefined;
} : Optional extends true ? {
    [P in Key]?: T;
} : {
    [P in Key]: T;
};

type Domains = typeof DOMAINS;

/** `client.<domain>.<method>`; an operation id with more segments nests (`client.session.act_as.enter`). */
type Methods<T> = {
    readonly [K in keyof T]: T[K] extends OperationId ? (input: OperationInput<T[K]>, signal?: AbortSignal) => Promise<OperationResult<T[K]>> : Methods<T[K]>;
};