@runblackcat/sdk 0.1.0-alpha.44

package/sdk/dist/index.d.ts

@@ -0,0 +1,503 @@
+/**
+ * Server-side TypeScript client for the Blackcat gateway.
+ *
+ * The SDK intentionally contains transport primitives only.  Workload-specific
+ * workflows (a consumer's dirty-worktree sync, say) compose file and exec
+ * operations in their own repository.
+ */
+export declare const CAPABILITY_OPS: {
+    readonly EXEC: 1;
+    readonly READ: 2;
+    readonly WRITE: 4;
+    readonly SNAPSHOT: 8;
+    readonly DESTROY: 16;
+    readonly INSPECT: 32;
+    readonly SANDBOX_CREATE: 64;
+    readonly TEMPLATE_RW: 128;
+    readonly PUBLISH: 256;
+    readonly PROCESS_START: 512;
+    readonly PROCESS_INSPECT: 1024;
+    readonly PROCESS_CANCEL: 2048;
+    readonly RENEW: 4096;
+};
+export type CapabilityOps = number;
+export type FetchFunction = (input: RequestInfo | URL, init?: RequestInit & {
+    tls?: {
+        ca: string;
+    };
+    timeout?: false;
+}) => Promise<Response>;
+export interface BlackcatClientOptions {
+    baseUrl: string;
+    apiKey?: string;
+    token?: string;
+    /** Capability identity and expiry, using idiomatic TypeScript names. */
+    tokenId?: string;
+    tokenExpiresAt?: number;
+    /** Backward-compatible aliases retained for pre-publication callers. */
+    token_id?: string;
+    token_expires_at?: number;
+    /** Re-mint a capability when renewal must replace the token secret. */
+    renewCapability?: () => Promise<MintTokenResponse>;
+    /** Private gateway trust root. Bun forwards this through its fetch TLS option. */
+    caPem?: string;
+    fetch?: FetchFunction;
+}
+export interface TemplateDefaults {
+    vcpus: number;
+    memory_mib: number;
+    hibernate?: HibernateMode;
+    on_interruption?: "evacuate" | "destroy";
+}
+export type HibernateMode = "memory";
+export type TemplateEgressPolicy = {
+    mode: "deny_all";
+} | {
+    mode: "allow_public";
+} | {
+    mode: "rules";
+    rules: ReadonlyArray<{
+        protocol: "tcp" | "udp";
+        port: number;
+        target: {
+            kind: "cidr";
+            value: string;
+        } | {
+            kind: "dns_name";
+            value: string;
+        } | {
+            kind: "dns_suffix";
+            value: string;
+        };
+    }>;
+};
+export type TemplatePreparationValue = {
+    from: "literal";
+    value: string;
+} | {
+    from: "parameter";
+    name: string;
+} | {
+    from: "secret";
+    name: string;
+};
+export interface TemplateRestoreHealth {
+    command: string;
+    args: readonly string[];
+    cwd: string;
+    timeout_ms: number;
+}
+interface TemplateDockerSourceBase {
+    /** A prepared filesystem; each sandbox starts a fresh process tree. */
+    docker: {
+        image: string;
+    };
+    defaults: TemplateDefaults;
+    egress: TemplateEgressPolicy;
+    restore_health: TemplateRestoreHealth;
+}
+interface TemplatePreparation {
+    parameters: Record<string, {
+        min_length: number;
+        max_length: number;
+        charset: "printable_ascii" | "lower_hex";
+    }>;
+    prepare: {
+        command: string;
+        args: TemplatePreparationValue[];
+        cwd: string;
+        environment: Record<string, TemplatePreparationValue>;
+        timeout_ms: number;
+        output_limit_bytes: number;
+    };
+}
+export type TemplateDockerSource = TemplateDockerSourceBase & (TemplatePreparation | {
+    parameters?: never;
+    prepare?: never;
+});
+export interface TemplateSandboxSource {
+    sandbox: {
+        id: string;
+    };
+    /** The gateway derives these from the source sandbox when omitted. */
+    defaults?: TemplateDefaults;
+    /** The gateway derives this from the source template when omitted. */
+    egress?: TemplateEgressPolicy;
+}
+export type TemplateSource = TemplateDockerSource | TemplateSandboxSource;
+export type CreateTemplateInput = {
+    name: string;
+    source: TemplateDockerSource;
+} | {
+    name?: string;
+    source: TemplateSandboxSource;
+};
+export interface Template {
+    id: string;
+    name: string;
+    version: number;
+    /** The gateway stores the complete source manifest as JSON text. */
+    source: string;
+    current: boolean;
+}
+/** Public record name retained for consumers that distinguish it from creation input. */
+export type TemplateRecord = Template;
+export interface CreateTemplateBuildInput {
+    name: string;
+    content_key: string;
+    activate_on_ready: boolean;
+    source: TemplateDockerSource;
+}
+export type TemplateBuildPhase = "queued" | "building" | "validating" | "ready" | "failed";
+export interface TemplateBuildRecord {
+    id: string;
+    name: string;
+    content_key: string;
+    phase: TemplateBuildPhase;
+    attempt: number;
+    template_version_id: string | null;
+    error: string | null;
+}
+export interface PrepareSandboxResponse {
+    prepared?: boolean;
+    process: Pick<ProcessRecord, "id" | "state" | "exit_code">;
+}
+export interface CreateTemplateResponse {
+    id: string;
+    version: number;
+}
+export type CreateSandboxInput = ({
+    template: string;
+    vcpus?: never;
+    memory_mib?: never;
+} | {
+    template: string;
+    vcpus: number;
+    memory_mib: number;
+}) & {
+    /** Stable across retries of one acquisition; never reuse for another request. */
+    request_id: string;
+    ssh_public_key?: string;
+    lease: SandboxLeaseInput;
+};
+export interface SandboxLeaseInput {
+    /** Initial lease duration, between 60 seconds and 24 hours. */
+    ttl_secs: number;
+    /** Hard lifetime from acquisition, at least ttl_secs and at most 30 days. */
+    renewable_for_secs: number;
+}
+export interface WarmInventoryMember {
+    id: string;
+    tenant: string;
+    template: string;
+    memory_mib: number;
+    vcpus: number;
+    node: string | null;
+    state: "Warming" | "Warm" | "Retiring";
+    snapshot: string | null;
+    last_active: SystemTimeValue;
+}
+export interface WarmTargetResponse {
+    enabled: boolean;
+    fleet_ready_limit: number;
+}
+export interface WarmInventoryResponse extends WarmTargetResponse {
+    members: WarmInventoryMember[];
+}
+/** Response returned by POST /v1/sandboxes (the gateway has no template field). */
+export type CreateSandboxResponse = {
+    request_id: string;
+    id: string;
+    tier: "boot" | "warm_pool" | "restore";
+    expires_at: SystemTimeValue;
+    renewable_until: SystemTimeValue;
+} & ({
+    state: "placed";
+    node: string;
+} | {
+    state: "pending";
+    node: string | null;
+});
+export interface Sandbox {
+    id: string;
+    template: string;
+    state: string;
+    node?: string;
+    expires_at: SystemTimeValue;
+    renewable_until: SystemTimeValue;
+}
+export interface RenewSandboxResponse {
+    id: string;
+    expires_at: SystemTimeValue;
+    renewable_until: SystemTimeValue;
+}
+/**
+ * Tenant-scoped view returned by GET /v1/fleet. Residents and cached snapshots
+ * are already filtered by the gateway to the caller's tenant.
+ */
+export interface FleetNode {
+    id: string;
+    addr: string;
+    total_mib: number;
+    reserved_mib: number;
+    vcpus: number;
+    health: string;
+    schedulable: boolean;
+    lease_until: SystemTimeValue;
+    committed_mib: number;
+    residents: string[];
+    cached_snapshots: string[];
+    interruption: FleetInterruption | null;
+}
+export interface FleetInterruption {
+    reason: string;
+    deadline: SystemTimeValue;
+}
+export interface FleetResponse {
+    nodes: FleetNode[];
+}
+export interface ExecInput {
+    command: string;
+    args: string[];
+    cwd: string;
+    /** Positive guest execution budget; effects before timeout are not undone. */
+    timeout_ms: number;
+    /** Optional bounded stdin for the streaming EXEC endpoint. */
+    stdin?: number[];
+}
+export interface ExecResult {
+    exit_code: number | null;
+    timed_out: boolean;
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+}
+export interface ExecStreamChunk {
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+    done: boolean;
+    exit_code: number | null;
+    timed_out: boolean;
+}
+export type ProcessState = "starting" | "running" | "succeeded" | "failed" | "timed_out" | "cancelled" | "interrupted";
+export interface ProcessStartInput {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: Array<[string, string]>;
+    timeout_ms: number;
+    output_limit_bytes: number;
+    /** Optional payload delivered once and followed by EOF. Maximum 512 KiB. */
+    stdin?: Uint8Array;
+}
+export interface ProcessRecord {
+    id: string;
+    sandbox_id: string;
+    state: ProcessState;
+    exit_code: number | null;
+    stdout_bytes: number;
+    stderr_bytes: number;
+    stdout_truncated: boolean;
+    stderr_truncated: boolean;
+    failure: string | null;
+    created_at: number;
+    updated_at: number;
+    terminal_at: number | null;
+}
+export interface ProcessLogs {
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+    next_stdout_offset: number;
+    next_stderr_offset: number;
+    stdout_truncated: boolean;
+    stderr_truncated: boolean;
+    state: ProcessState;
+}
+export interface ProcessLogsResponse {
+    process: ProcessRecord;
+    logs: ProcessLogs;
+}
+export interface FileReadChunk {
+    data: Uint8Array;
+    offset: number;
+    eof: boolean;
+}
+export interface ReadFileInput {
+    path: string;
+    offset?: number;
+    /** Total bytes to read. Omit to read through EOF. */
+    length?: number;
+    /** Per-request chunk size; defaults to the gateway's maximum. */
+    chunk_size?: number;
+}
+export interface WriteFileInput {
+    path: string;
+    data: Uint8Array;
+    offset?: number;
+    truncate?: boolean;
+}
+export interface WriteFileStreamInput {
+    path: string;
+    data: AsyncIterable<Uint8Array>;
+    offset?: number;
+    truncate?: boolean;
+}
+export interface MintTokenInput {
+    sandbox?: string;
+    ops: CapabilityOps;
+    ttl_secs: number;
+}
+/** JSON representation emitted by serde for Rust's SystemTime. */
+export interface SystemTimeValue {
+    secs_since_epoch: number;
+    nanos_since_epoch: number;
+}
+export interface MintTokenResponse {
+    token: string;
+    token_id: string;
+    /** Capability timestamps are epoch milliseconds. */
+    expires_at: number;
+    renewable_until: number;
+}
+export interface RenewTokenResponse {
+    expires_at: number;
+}
+export declare class BlackcatApiError extends Error {
+    readonly status: number;
+    readonly retryAfter?: number;
+    readonly requestId?: string;
+    readonly details: unknown;
+    constructor(status: number, message: string, details: unknown, retryAfter?: number, requestId?: string);
+}
+declare const MAX_FILE_CHUNK: number;
+declare const MAX_FILE_READ_CHUNK = 1000000;
+declare const MAX_PROCESS_STDIN: number;
+declare const MAX_EXEC_STDIN: number;
+export declare function epochMillis(value: unknown, field: string): number;
+export declare function parseCreateSandboxResponse(value: unknown, requestId: string): CreateSandboxResponse;
+export declare function assertSecureBlackcatGatewayUrl(baseUrl: string): void;
+declare class GatewayClient {
+    readonly baseUrl: string;
+    readonly apiKey?: string;
+    token?: string;
+    tokenId?: string;
+    tokenExpiresAt?: number;
+    readonly renewCapability?: () => Promise<MintTokenResponse>;
+    readonly caPem?: string;
+    readonly fetcher: FetchFunction;
+    private renewalInFlight?;
+    constructor(options: BlackcatClientOptions);
+    credential(kind: "apiKey" | "token" | "either"): string;
+    json<T>(method: string, path: string, body?: unknown, kind?: "apiKey" | "token" | "either", timeout?: false, signal?: AbortSignal, extraHeaders?: HeadersInit): Promise<T>;
+    raw(method: string, path: string, body?: BodyInit, kind?: "apiKey" | "token" | "either", contentType?: string, timeout?: false, signal?: AbortSignal): Promise<Response>;
+    renewIfNeeded(signal?: AbortSignal): Promise<void>;
+    stream(method: string, path: string, body?: BodyInit, kind?: "apiKey" | "token" | "either", contentType?: string, renew?: boolean, signal?: AbortSignal): AsyncGenerator<Uint8Array>;
+}
+declare class TemplatesResource {
+    private readonly client;
+    constructor(client: GatewayClient);
+    create(input: CreateTemplateInput): Promise<CreateTemplateResponse>;
+    list(): Promise<Template[]>;
+    activate(id: string): Promise<{
+        id: string;
+        name: string;
+        version: number;
+    }>;
+    configureWarm(id: string, input: {
+        enabled: boolean;
+    }): Promise<WarmTargetResponse>;
+    inspectWarm(id: string): Promise<WarmInventoryResponse>;
+}
+declare class TemplateBuildsResource {
+    private readonly client;
+    constructor(client: GatewayClient);
+    create(input: CreateTemplateBuildInput): Promise<{
+        build: TemplateBuildRecord;
+    }>;
+    get(id: string): Promise<{
+        build: TemplateBuildRecord;
+    }>;
+    retry(id: string): Promise<{
+        build: TemplateBuildRecord;
+    }>;
+}
+declare class TokensResource {
+    private readonly client;
+    constructor(client: GatewayClient);
+    mint(input: MintTokenInput): Promise<MintTokenResponse>;
+    renew(id: string): Promise<RenewTokenResponse>;
+    revoke(id: string): Promise<void>;
+}
+declare class FleetResource {
+    private readonly client;
+    constructor(client: GatewayClient);
+    /** List the nodes and this tenant's residents/snapshots visible to INSPECT. */
+    list(): Promise<FleetResponse>;
+}
+declare class SandboxesResource {
+    private readonly client;
+    constructor(client: GatewayClient);
+    /** List all of this tenant's non-destroyed sandboxes, including hibernated ones. */
+    list(): Promise<Sandbox[]>;
+    /**
+     * Acquire once under a caller-owned request ID. Repeat the exact request to
+     * recover a lost response. A pending receipt is not an executable sandbox;
+     * no automatic retry, new ID, or replacement allocation is synthesized here.
+     */
+    create(input: CreateSandboxInput): Promise<CreateSandboxResponse>;
+    acquisition(requestId: string): Promise<CreateSandboxResponse>;
+    get(id: string): Promise<Sandbox>;
+    /** Extend the soft expiry without moving the immutable hard deadline. */
+    renew(id: string, ttl_secs: number): Promise<RenewSandboxResponse>;
+    exec(id: string, input: ExecInput): Promise<ExecResult>;
+    execStream(id: string, input: ExecInput): AsyncGenerator<ExecStreamChunk>;
+    startProcess(id: string, requestId: string, input: ProcessStartInput): Promise<ProcessRecord>;
+    getProcess(id: string, processId: string): Promise<ProcessRecord>;
+    processLogs(id: string, processId: string, input?: number | {
+        stdout_offset?: number;
+        stderr_offset?: number;
+        max_bytes?: number;
+    }): Promise<ProcessLogsResponse>;
+    cancelProcess(id: string, processId: string): Promise<ProcessRecord>;
+    prepare(id: string, input: {
+        parameters: Record<string, string>;
+        secrets: Record<string, string>;
+    }, idempotencyKey: string): Promise<PrepareSandboxResponse>;
+    logs(id: string): AsyncGenerator<Uint8Array>;
+    readFileChunk(id: string, input: {
+        path: string;
+        offset: number;
+        length: number;
+    }): Promise<FileReadChunk>;
+    readFileStream(id: string, input: ReadFileInput): AsyncGenerator<FileReadChunk>;
+    readFile(id: string, input: ReadFileInput): Promise<Uint8Array>;
+    writeFileChunk(id: string, input: {
+        path: string;
+        offset: number;
+        data: Uint8Array;
+        truncate: boolean;
+    }): Promise<void>;
+    writeFileStream(id: string, input: WriteFileStreamInput): Promise<number>;
+    writeFile(id: string, input: WriteFileInput): Promise<number>;
+    snapshot(id: string): Promise<{
+        snapshot: string;
+    }>;
+    hibernate(id: string, input?: {
+        mode: HibernateMode;
+    }): Promise<void>;
+    resume(id: string): Promise<void>;
+    destroy(id: string): Promise<void>;
+}
+export declare class BlackcatClient extends GatewayClient {
+    readonly templates: TemplatesResource;
+    readonly templateBuilds: TemplateBuildsResource;
+    readonly sandboxes: SandboxesResource;
+    readonly tokens: TokensResource;
+    readonly fleet: FleetResource;
+    constructor(options: BlackcatClientOptions);
+    /**
+     * Create a client that uses a sandbox capability for resource operations.
+     * Passing the complete mint response enables renewal during long streams.
+     */
+    withToken(token: string | MintTokenResponse, renewCapability?: () => Promise<MintTokenResponse>): BlackcatClient;
+}
+export { MAX_EXEC_STDIN, MAX_FILE_CHUNK, MAX_FILE_CHUNK as MAX_FILE_WRITE_CHUNK, MAX_FILE_READ_CHUNK, MAX_PROCESS_STDIN, };