@genspark/sb-box 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,641 @@
+declare const SDK_VERSION = "0.1.0";
+declare const DEFAULT_BASE_URL = "https://www.genspark.ai/api/sb-box/v1";
+interface HttpOptions {
+    apiKey: string;
+    baseUrl: string;
+    /** Default per-request timeout in seconds. */
+    timeout: number;
+    /** Retries after the first attempt for retryable calls (0 = no retry). */
+    retries: number;
+    userAgent: string;
+    fetch: typeof fetch;
+}
+interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    query?: Record<string, string | number | undefined>;
+    json?: unknown;
+    body?: Uint8Array | string;
+    contentType?: string;
+    headers?: Record<string, string>;
+    /** Seconds; overrides the client default. */
+    timeout?: number;
+    /** Retry on connection errors and 502/503/504 (default false). */
+    retry?: boolean;
+    /** Honour `Retry-After` on 503 until `deadlineMs`. */
+    retryOn503Until?: number;
+    /** Return the raw Response (streams, bytes). */
+    raw?: boolean;
+    /**
+     * Raw responses only: when false, the timeout covers just the headers and the
+     * caller owns the body for as long as it likes (unbounded server streams such
+     * as `connect`). Default true: the timeout bounds the whole body; past it the
+     * stream fails with `SbBoxConnectionError`.
+     */
+    bodyDeadline?: boolean;
+    signal?: AbortSignal;
+}
+declare class Http {
+    readonly opts: HttpOptions;
+    constructor(opts: HttpOptions);
+    url(path: string, query?: RequestOptions['query']): string;
+    request<T = unknown>(path: string, opts?: RequestOptions): Promise<T>;
+    raw(path: string, opts?: RequestOptions): Promise<Response>;
+    private send;
+    private parseBody;
+}
+
+type SandboxState = 'starting' | 'running' | 'freezing' | 'frozen' | 'exited' | 'failed' | 'unknown';
+type ListState = SandboxState | 'all';
+interface Regions {
+    regions: string[];
+    default: string;
+}
+interface Limits {
+    plan: string;
+    planRequired?: boolean;
+    limits: {
+        maxConcurrentSandboxes: number;
+        maxCpu: number;
+        maxMemoryMB: number;
+        maxDiskGB: number;
+        maxConcurrentBuilds: number;
+        [k: string]: unknown;
+    };
+    usage: {
+        runningSandboxes: number;
+        buildingTemplates: number;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+interface UsageTotals {
+    runSec?: number;
+    cpuCoreSec?: number;
+    memGBSec?: number;
+    diskGBSec?: number;
+    credits?: number;
+    [k: string]: unknown;
+}
+interface Usage {
+    days: number;
+    from: string;
+    to: string;
+    rateCard?: Record<string, unknown>;
+    direct?: UsageTotals;
+    daily?: Array<{
+        day: string;
+        direct?: Record<string, unknown>;
+        [k: string]: unknown;
+    }>;
+    [k: string]: unknown;
+}
+type TemplateStatus = 'building' | 'ready' | 'error';
+interface Template {
+    id: string;
+    name: string;
+    description?: string;
+    namespace: 'public' | 'private';
+    base_image?: string;
+    status: TemplateStatus;
+    buildError?: string;
+    region?: string;
+    is_owner?: boolean;
+    can_create?: boolean;
+    cogen_id?: string;
+    created_at?: string;
+    updated_at?: string;
+    cpuCount?: number;
+    memoryMB?: number;
+    diskSizeGB?: number;
+    startCmd?: string;
+    readyCmd?: string;
+    [k: string]: unknown;
+}
+interface TemplateBuildOptions {
+    name?: string;
+    image?: string;
+    dockerfile?: string;
+    cpuCount?: number;
+    memoryMB?: number;
+    diskSizeGB?: number;
+    startCmd?: string;
+    readyCmd?: string;
+    region?: string;
+    logPaths?: string[];
+    description?: string;
+}
+interface TemplateBuild {
+    templateId: string;
+    status: string;
+    region?: string;
+    owner?: string;
+    [k: string]: unknown;
+}
+type Permission = 'read' | 'write';
+interface Grant {
+    grantee_id: string;
+    permission: Permission;
+    granted_at?: string;
+    expires_at?: string | null;
+    template_id?: string;
+    sandbox_id?: string;
+    [k: string]: unknown;
+}
+interface GrantOptions {
+    perm?: Permission;
+    expiresAt?: string;
+    reason?: string;
+}
+interface NetworkOptions {
+    allowInternetAccess?: boolean;
+    allowOut?: string[];
+    denyOut?: string[];
+    allowPublicTraffic?: boolean;
+    maskRequestHost?: boolean;
+}
+interface CreateSandboxOptions {
+    /** Template name; defaults to `"base"` when neither name nor id is given. */
+    template?: string;
+    templateId?: string;
+    /** Lifetime in seconds. 0 / omitted = no deadline. */
+    timeout?: number;
+    onTimeout?: 'freeze' | 'kill';
+    metadata?: Record<string, string>;
+    envVars?: Record<string, string>;
+    network?: NetworkOptions;
+}
+interface SandboxVersion {
+    version: number;
+    frozenAt?: string;
+    label?: string;
+    [k: string]: unknown;
+}
+/** Full sandbox record as returned by create / get / freeze / resume / rollback / clone / reset. */
+interface SandboxInfo {
+    id: string;
+    templateId?: string;
+    template_id?: string;
+    state: SandboxState;
+    region?: string;
+    portUrl?: string;
+    domain?: string;
+    createdAt?: string;
+    startedAt?: string;
+    frozenAt?: string;
+    timeoutAt?: string;
+    cpuCount?: number;
+    memoryMB?: number;
+    diskSizeGB?: number;
+    idleTimeout?: number;
+    versions?: SandboxVersion[];
+    metadata?: Record<string, string>;
+    trafficAccessToken?: string;
+    is_owner?: boolean;
+    has_write?: boolean;
+    cogen_id?: string;
+    created_at?: string;
+    updated_at?: string;
+    [k: string]: unknown;
+}
+/** Compact row from `GET /sandboxes`. */
+interface SandboxSummary {
+    id: string;
+    template_id?: string;
+    state: SandboxState;
+    region?: string;
+    portUrl?: string;
+    domain?: string;
+    cogen_id?: string;
+    created_at?: string;
+    updated_at?: string;
+    [k: string]: unknown;
+}
+interface MetricPoint {
+    timestamp: string;
+    timestampUnix: number;
+    cpuCount: number;
+    cpuUsedPct: number;
+    memUsed: number;
+    memTotal: number;
+    memCache?: number;
+    diskUsed: number;
+    diskTotal: number;
+    [k: string]: unknown;
+}
+interface ExecOptions {
+    cwd?: string;
+    envVars?: Record<string, string>;
+    user?: string;
+    /** Seconds, default 60, max 600. */
+    timeout?: number;
+}
+interface CommandResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+interface ExecEvent {
+    kind: 'stdout' | 'stderr' | 'exit' | 'error';
+    /** Output chunk for stdout/stderr, error message for error. */
+    data?: string;
+    exitCode?: number;
+    execId?: string;
+    stage?: string;
+}
+interface RunCodeOptions {
+    language?: string;
+    contextId?: string;
+    envVars?: Record<string, string>;
+    /** Seconds, default 60, max 540. */
+    timeout?: number;
+    images?: 'base64' | 'omit';
+}
+interface CodeError {
+    name: string;
+    value: string;
+    traceback: string | string[];
+}
+interface CodeResult {
+    stdout: string;
+    stderr: string;
+    executionCount?: number;
+    complete?: boolean;
+    error: CodeError | null;
+    results: Array<Record<string, unknown>>;
+    [k: string]: unknown;
+}
+interface StartCommandOptions {
+    cwd?: string;
+    envVars?: Record<string, string>;
+    user?: string;
+}
+interface ProcessInfo {
+    execId: string;
+    pid: number;
+    sandboxId?: string;
+    [k: string]: unknown;
+}
+interface FileEntry {
+    name: string;
+    path: string;
+    isDir: boolean;
+    size: number;
+}
+interface PtyOptions {
+    command?: string[];
+    rows?: number;
+    cols?: number;
+    cwd?: string;
+    envVars?: Record<string, string>;
+}
+interface PtyEvent {
+    kind: 'data' | 'exit';
+    data?: string;
+    exitCode?: number;
+    reason?: string;
+}
+interface WaitOptions {
+    /** Seconds. */
+    timeout?: number;
+    /** Poll interval in seconds. */
+    interval?: number;
+}
+
+/** A background command started with `sandbox.commands.start()`. */
+declare class BackgroundCommand {
+    private readonly http;
+    readonly sandboxId: string;
+    readonly execId: string;
+    readonly pid: number;
+    constructor(http: Http, sandboxId: string, execId: string, pid: number);
+    private p;
+    input(data: string): Promise<number>;
+    close(): Promise<void>;
+    /** Block until the command exits; returns its exit code. `timeout` is seconds (default 600). */
+    wait(timeout?: number): Promise<number>;
+    kill(signal?: number): Promise<void>;
+    /** Stream the command's output. Resolves to an empty stream if the server already reaped it. */
+    connect(): AsyncGenerator<ExecEvent>;
+}
+declare class Commands {
+    private readonly http;
+    private readonly sandboxId;
+    constructor(http: Http, sandboxId: string);
+    private p;
+    start(command: string | string[], opts?: StartCommandOptions): Promise<BackgroundCommand>;
+    list(): Promise<ProcessInfo[]>;
+    kill(pid: number, signal?: number): Promise<void>;
+    sendStdin(pid: number, data: string): Promise<void>;
+}
+declare class Files {
+    private readonly http;
+    private readonly sandboxId;
+    constructor(http: Http, sandboxId: string);
+    private p;
+    /** Write bytes (or a UTF-8 string). Returns the byte count written. */
+    write(path: string, data: Uint8Array | string, opts?: {
+        user?: string;
+    }): Promise<number>;
+    read(path: string, opts?: {
+        user?: string;
+    }): Promise<Uint8Array>;
+    readText(path: string, opts?: {
+        user?: string;
+        encoding?: string;
+    }): Promise<string>;
+    list(path?: string, opts?: {
+        user?: string;
+    }): Promise<FileEntry[]>;
+}
+/** An interactive terminal opened with `sandbox.pty.open()`. */
+declare class PtySession {
+    private readonly http;
+    readonly sandboxId: string;
+    readonly execId: string;
+    readonly pid: number;
+    constructor(http: Http, sandboxId: string, execId: string, pid: number);
+    private p;
+    input(data: Uint8Array | string): Promise<void>;
+    resize(rows: number, cols: number): Promise<void>;
+    kill(): Promise<void>;
+    /** Stream terminal output (SSE). Ends with a `exit` event. */
+    connect(): AsyncGenerator<PtyEvent>;
+}
+interface PtyWsHandlers {
+    onData?: (data: string, seq?: number) => void;
+    onExit?: (exitCode: number) => void;
+    onError?: (error: string) => void;
+}
+/** A terminal over the WebSocket transport (`GET /sandboxes/{id}/ws/pty`). */
+declare class PtyWebSocket {
+    private readonly ws;
+    constructor(ws: WsLike);
+    input(data: string): void;
+    resize(rows: number, cols: number): void;
+    kill(): void;
+    close(): void;
+}
+interface WsLike {
+    send(data: string): void;
+    close(): void;
+    addEventListener(type: string, listener: (ev: {
+        data?: unknown;
+        message?: string;
+    }) => void): void;
+}
+declare class Pty {
+    private readonly http;
+    private readonly sandboxId;
+    constructor(http: Http, sandboxId: string);
+    open(opts?: PtyOptions): Promise<PtySession>;
+    /**
+     * Open a terminal over WebSocket. Uses the global `WebSocket` (Node 22+, browsers) or the
+     * optional `ws` package. Resolves once the socket is open and the start frame is sent.
+     */
+    connectWs(opts?: PtyOptions, handlers?: PtyWsHandlers): Promise<PtyWebSocket>;
+}
+/** Handle on one sandbox, bound to the client that created it. */
+declare class Sandbox {
+    private readonly http;
+    readonly commands: Commands;
+    readonly files: Files;
+    readonly pty: Pty;
+    private _info;
+    constructor(http: Http, info: SandboxInfo);
+    /** The last record seen for this sandbox (call `refresh()` to update). */
+    get info(): SandboxInfo;
+    get id(): string;
+    get state(): SandboxState;
+    get templateId(): string | undefined;
+    get region(): string | undefined;
+    get metadata(): Record<string, string>;
+    get versions(): SandboxVersion[];
+    get createdAt(): string | undefined;
+    get frozenAt(): string | undefined;
+    get timeoutAt(): string | undefined;
+    /** Token to reach a sandbox created with `allowPublicTraffic: false` (create response only). */
+    get trafficAccessToken(): string | undefined;
+    /** Public URL of a port inside the sandbox. */
+    portUrl(port: number): string;
+    private p;
+    private update;
+    refresh(): Promise<this>;
+    kill(): Promise<void>;
+    /** Freeze. The server may answer 202 (still freezing); with `wait` (default) we poll until `frozen`. */
+    freeze(opts?: {
+        wait?: boolean;
+    } & WaitOptions): Promise<this>;
+    waitForState(target: SandboxState | SandboxState[], opts?: WaitOptions): Promise<this>;
+    resume(opts?: {
+        timeout?: number;
+    }): Promise<this>;
+    rollback(opts?: {
+        version?: number;
+        timeout?: number;
+    }): Promise<this>;
+    /** Clone into a new sandbox owned by the caller. Retries on 503 + Retry-After until `timeout` (s). */
+    clone(opts?: {
+        version?: number;
+        metadata?: Record<string, string>;
+        timeout?: number;
+    }): Promise<Sandbox>;
+    /** Set the lifetime deadline in seconds from now; 0 clears it. */
+    setTimeout(seconds: number): Promise<void>;
+    reset(opts?: {
+        timeout?: number;
+    }): Promise<this>;
+    metrics(opts?: {
+        start?: number;
+        end?: number;
+    }): Promise<MetricPoint[]>;
+    grant(userId: string, opts?: GrantOptions): Promise<Grant>;
+    grants(): Promise<Grant[]>;
+    revoke(userId: string): Promise<void>;
+    /** Run a command and wait for it. A non-zero exit is returned, not thrown. */
+    exec(command: string | string[], opts?: ExecOptions): Promise<CommandResult>;
+    /** Run a command and stream its output as it is produced. */
+    execStream(command: string | string[], opts?: ExecOptions): AsyncGenerator<ExecEvent>;
+    /** Execute code in the sandbox's stateful interpreter. */
+    runCode(code: string, opts?: RunCodeOptions): Promise<CodeResult>;
+}
+
+declare class Templates {
+    private readonly http;
+    constructor(http: Http);
+    /** Start a build. Async: poll `get()` or use `waitReady()`. */
+    build(opts: TemplateBuildOptions): Promise<TemplateBuild>;
+    /** Poll until the template is `ready`; throws `TemplateBuildError` on `error`. */
+    waitReady(templateId: string, opts?: WaitOptions): Promise<Template>;
+    list(): Promise<Template[]>;
+    shared(): Promise<Template[]>;
+    get(templateId: string): Promise<Template>;
+    delete(templateId: string): Promise<void>;
+    grant(templateId: string, userId: string, opts?: GrantOptions): Promise<Grant>;
+    grants(templateId: string): Promise<Grant[]>;
+    revoke(templateId: string, userId: string): Promise<void>;
+}
+
+interface SbBoxOptions {
+    /** API key. Falls back to `SBBOX_API_KEY`, then `GSK_API_KEY`. */
+    apiKey?: string;
+    /** Falls back to `SBBOX_BASE_URL`, then the production API. */
+    baseUrl?: string;
+    /** Default request timeout in seconds (60). */
+    timeout?: number;
+    /** Retries after the first attempt for reads and idempotent lifecycle calls (3). Set 0 to disable. */
+    retries?: number;
+    /** Appended to the User-Agent, e.g. your app name. */
+    userAgentSuffix?: string;
+    /** Custom fetch (tests, proxies). */
+    fetch?: typeof fetch;
+}
+declare class Sandboxes {
+    private readonly http;
+    constructor(http: Http);
+    create(opts?: CreateSandboxOptions): Promise<Sandbox>;
+    /** Compact rows. `state` filters (one or many); omitted = every live state. */
+    list(state?: ListState | ListState[]): Promise<SandboxSummary[]>;
+    shared(): Promise<Sandbox[]>;
+    get(sandboxId: string): Promise<Sandbox>;
+    /** Alias of `get()`. */
+    connect(sandboxId: string): Promise<Sandbox>;
+    private handle;
+    kill(sandboxId: string): Promise<void>;
+    freeze(sandboxId: string, opts?: {
+        wait?: boolean;
+    } & WaitOptions): Promise<Sandbox>;
+    resume(sandboxId: string, opts?: {
+        timeout?: number;
+    }): Promise<Sandbox>;
+    rollback(sandboxId: string, opts?: {
+        version?: number;
+        timeout?: number;
+    }): Promise<Sandbox>;
+    clone(sandboxId: string, opts?: {
+        version?: number;
+        metadata?: Record<string, string>;
+        timeout?: number;
+    }): Promise<Sandbox>;
+    setTimeout(sandboxId: string, seconds: number): Promise<void>;
+    reset(sandboxId: string, opts?: {
+        timeout?: number;
+    }): Promise<Sandbox>;
+    metrics(sandboxId: string, opts?: {
+        start?: number;
+        end?: number;
+    }): Promise<MetricPoint[]>;
+    grant(sandboxId: string, userId: string, opts?: GrantOptions): Promise<Grant>;
+    grants(sandboxId: string): Promise<Grant[]>;
+    revoke(sandboxId: string, userId: string): Promise<void>;
+}
+/** Entry point: `const sbbox = new SbBox({ apiKey })`. */
+declare class SbBox {
+    readonly templates: Templates;
+    readonly sandboxes: Sandboxes;
+    readonly baseUrl: string;
+    private readonly http;
+    constructor(opts?: SbBoxOptions);
+    regions(): Promise<Regions>;
+    limits(): Promise<Limits>;
+    usage(days?: number): Promise<Usage>;
+}
+
+interface SseMessage {
+    event: string;
+    data: string;
+    id?: string;
+}
+/**
+ * Parse a `text/event-stream` body into messages. `event:` defaults to `message`,
+ * multi-line `data:` is joined with `\n`, a blank line ends the event.
+ */
+declare function parseSse(body: ReadableStream<Uint8Array>): AsyncGenerator<SseMessage>;
+
+/** Replace any API key that leaked into a string. */
+declare function redact(text: string): string;
+interface SbBoxErrorInit {
+    status: number;
+    code?: string;
+    message: string;
+    detail?: unknown;
+    retryAfter?: number;
+    requestId?: string;
+}
+/** Base class of every error raised by the SDK. */
+declare class SbBoxError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    /** Parsed response body (or the raw text when it was not JSON). */
+    readonly detail: unknown;
+    /** Seconds from a `Retry-After` header, when the server sent one. */
+    readonly retryAfter?: number;
+    readonly requestId?: string;
+    constructor(init: SbBoxErrorInit);
+    /** A named field from the error body (`plan`, `limit`, `balance`, `recovery`, …). */
+    field<T = unknown>(name: string): T | undefined;
+}
+declare class ValidationError extends SbBoxError {
+}
+declare class AuthenticationError extends SbBoxError {
+}
+declare class InsufficientCreditsError extends SbBoxError {
+    get balance(): number | undefined;
+}
+declare class ForbiddenError extends SbBoxError {
+}
+declare class PlanRequiredError extends ForbiddenError {
+    get plan(): string | undefined;
+    get upgrade(): string | undefined;
+}
+declare class NotFoundError extends SbBoxError {
+}
+declare class RegionRetiredError extends NotFoundError {
+    get region(): string | undefined;
+}
+declare class CommandTimeoutError extends SbBoxError {
+    get killed(): boolean;
+}
+declare class ConflictError extends SbBoxError {
+}
+declare class LimitError extends ConflictError {
+    get plan(): string | undefined;
+    get limit(): number | undefined;
+    get current(): number | undefined;
+    get requested(): number | undefined;
+}
+declare class InterpreterUnavailableError extends ConflictError {
+}
+declare class DiskLostError extends SbBoxError {
+}
+declare class MemoryExpiredError extends SbBoxError {
+    get recovery(): string[];
+}
+declare class ClientDisconnectedError extends SbBoxError {
+}
+declare class ServerError extends SbBoxError {
+}
+declare class InterpreterStartFailedError extends ServerError {
+}
+/** Network failure or request timeout before any HTTP status was received. */
+declare class SbBoxConnectionError extends SbBoxError {
+    constructor(message: string, cause?: unknown);
+}
+/** `templates.waitReady` saw the build end in `error`. */
+declare class TemplateBuildError extends SbBoxError {
+    readonly templateId: string;
+    readonly buildError?: string;
+    constructor(templateId: string, buildError?: string, detail?: unknown);
+}
+/** A `wait` helper ran past its deadline. */
+declare class WaitTimeoutError extends SbBoxError {
+    constructor(message: string);
+}
+/** Extract (code, message) from either `{"detail": …}` or `{"error": …}` envelopes. */
+declare function describeBody(body: unknown, fallback: string): {
+    code?: string;
+    message: string;
+};
+/** Map an HTTP failure to the SDK error class from the contract table. */
+declare function errorFromResponse(status: number, body: unknown, headers: Headers): SbBoxError;
+
+export { AuthenticationError, BackgroundCommand, ClientDisconnectedError, type CodeError, type CodeResult, type CommandResult, CommandTimeoutError, Commands, ConflictError, type CreateSandboxOptions, DEFAULT_BASE_URL, DiskLostError, type ExecEvent, type ExecOptions, type FileEntry, Files, ForbiddenError, type Grant, type GrantOptions, InsufficientCreditsError, InterpreterStartFailedError, InterpreterUnavailableError, LimitError, type Limits, type ListState, MemoryExpiredError, type MetricPoint, type NetworkOptions, NotFoundError, type Permission, PlanRequiredError, type ProcessInfo, Pty, type PtyEvent, type PtyOptions, PtySession, PtyWebSocket, type PtyWsHandlers, RegionRetiredError, type Regions, type RunCodeOptions, SDK_VERSION, Sandbox, type SandboxInfo, type SandboxState, type SandboxSummary, type SandboxVersion, Sandboxes, SbBox, SbBoxConnectionError, SbBoxError, type SbBoxErrorInit, type SbBoxOptions, ServerError, type SseMessage, type StartCommandOptions, type Template, type TemplateBuild, TemplateBuildError, type TemplateBuildOptions, type TemplateStatus, Templates, type Usage, type UsageTotals, ValidationError, type WaitOptions, WaitTimeoutError, describeBody, errorFromResponse, parseSse, redact };