@slicervm/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,424 @@
+import { IncomingMessage } from 'node:http';
+import { Readable } from 'node:stream';
+import { URL } from 'node:url';
+
+/**
+ * Slicer API types. Wire shapes mirror the Go SDK at github.com/slicervm/sdk
+ * (which calls these "Node" / "SlicerNode"); the TS SDK renames to "VM" for
+ * clarity, since Slicer's primary primitive is a VM.
+ */
+interface HostGroup {
+    name: string;
+    count: number;
+    ramBytes: number;
+    cpus: number;
+    arch: string;
+    gpuCount?: number;
+}
+interface VMInfo {
+    hostname: string;
+    hostGroup?: string;
+    ip: string;
+    ramBytes?: number;
+    cpus?: number;
+    createdAt: string;
+    arch?: string;
+    tags?: string[];
+    status?: string;
+    persistent?: boolean;
+}
+interface CreateVMRequest {
+    ramBytes?: number;
+    cpus?: number;
+    gpuCount?: number;
+    persistent?: boolean;
+    diskImage?: string;
+    importUser?: string;
+    sshKeys?: string[];
+    userdata?: string;
+    ip?: string;
+    tags?: string[];
+    secrets?: string[];
+}
+interface CreateVMResponse {
+    hostname: string;
+    hostGroup?: string;
+    ip: string;
+    createdAt: string;
+    arch?: string;
+}
+interface AgentHealth {
+    hostname?: string;
+    agentUptime?: number;
+    agentVersion?: string;
+    systemUptime?: number;
+    userdataRan?: boolean;
+}
+interface VMLogs {
+    hostname: string;
+    lines: number;
+    content: string;
+}
+interface DeleteResponse {
+    message?: string;
+    diskRemoved?: string;
+    error?: string;
+}
+/** Wire encoding of exec stdout/stderr. Defaults to `"text"`. */
+type ExecStdio = 'text' | 'base64';
+declare const ExecStdioText: ExecStdio;
+declare const ExecStdioBase64: ExecStdio;
+interface ExecRequest {
+    command?: string;
+    args?: string[];
+    env?: string[];
+    uid?: number;
+    gid?: number;
+    stdin?: Buffer | string;
+    shell?: string;
+    cwd?: string;
+    permissions?: string;
+    /**
+     * Wire encoding for stdout/stderr.
+     *  - `"text"` (default): frames carry UTF-8 strings. Safe for text output only —
+     *     arbitrary binary will be mangled by JSON string escaping.
+     *  - `"base64"`: frames carry base64-encoded bytes. Required for binary output
+     *     (video, compressed archives, raw protocol streams). The SDK decodes
+     *     automatically — callers get `Buffer` on `execBuffered({ stdio: 'base64' })`
+     *     and `{stdoutBytes, stderrBytes, dataBytes}` on streamed frames.
+     */
+    stdio?: ExecStdio;
+}
+interface ExecFrame {
+    timestamp?: string;
+    type?: string;
+    pid?: number;
+    encoding?: ExecStdio;
+    /** Raw wire value — string under text mode, base64 string under base64 mode. */
+    data?: string;
+    startedAt?: string;
+    endedAt?: string;
+    signal?: string;
+    stdout?: string;
+    stderr?: string;
+    /** Decoded bytes when `encoding === 'base64'`. SDK-populated convenience field. */
+    dataBytes?: Buffer;
+    stdoutBytes?: Buffer;
+    stderrBytes?: Buffer;
+    exitCode?: number;
+    error?: string;
+}
+interface ExecResult {
+    stdout: string;
+    stderr: string;
+    encoding?: ExecStdio;
+    pid?: number;
+    startedAt?: string;
+    endedAt?: string;
+    signal?: string;
+    exitCode: number;
+    error?: string;
+}
+/** Returned by `execBuffered` when `stdio === 'base64'`. stdout/stderr are decoded Buffers. */
+interface ExecResultBinary {
+    stdout: Buffer;
+    stderr: Buffer;
+    encoding: 'base64';
+    pid?: number;
+    startedAt?: string;
+    endedAt?: string;
+    signal?: string;
+    exitCode: number;
+    error?: string;
+}
+interface FSEntry {
+    name: string;
+    type: 'file' | 'directory' | 'symlink' | string;
+    size: number;
+    mtime: string;
+    mode: string;
+}
+interface FSMkdirRequest {
+    path: string;
+    recursive?: boolean;
+    mode?: string;
+}
+interface ShutdownRequest {
+    action?: 'shutdown' | 'reboot';
+}
+interface VMStat {
+    hostname: string;
+    ip: string;
+    createdAt: string;
+    snapshot?: VMSnapshot | null;
+    error?: string;
+}
+interface VMSnapshot {
+    hostname: string;
+    arch: string;
+    timestamp: string;
+    uptime: string;
+    totalCpus: number;
+    totalMemory: number;
+    memoryUsed: number;
+    memoryAvailable: number;
+    memoryUsedPercent: number;
+    loadAvg1: number;
+    loadAvg5: number;
+    loadAvg15: number;
+    diskReadTotal: number;
+    diskWriteTotal: number;
+    networkReadTotal: number;
+    networkWriteTotal: number;
+    diskIOInflight: number;
+    openConnections: number;
+    openFiles: number;
+    entropy: number;
+    diskSpaceTotal: number;
+    diskSpaceUsed: number;
+    diskSpaceFree: number;
+    diskSpaceUsedPercent: number;
+}
+interface SlicerInfo {
+    version?: string;
+    gitCommit?: string;
+    platform?: string;
+    arch?: string;
+}
+interface ListOptions {
+    tag?: string;
+    tagPrefix?: string;
+}
+interface WaitOptions {
+    timeoutMs?: number;
+    intervalMs?: number;
+}
+interface CreateVMOptions {
+    /**
+     * Server-side wait: `"agent"` waits for the in-guest agent to be ready,
+     * `"userdata"` additionally waits for userdata to run. If unset the daemon
+     * returns immediately once the VM is scheduled.
+     */
+    wait?: 'agent' | 'userdata';
+    /** Server-side wait timeout, in seconds. Forwarded as a Go duration. */
+    waitTimeoutSec?: number;
+}
+interface Secret {
+    name: string;
+    size: number;
+    permissions: string;
+    uid?: number;
+    gid?: number;
+    modifiedAt?: string;
+}
+interface CreateSecretRequest {
+    name: string;
+    data: string;
+    permissions?: string;
+    uid?: number;
+    gid?: number;
+}
+interface UpdateSecretRequest {
+    data: string;
+    permissions?: string;
+    uid?: number;
+    gid?: number;
+}
+declare class SecretExistsError extends Error {
+    constructor(name: string);
+}
+declare class SlicerAPIError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    readonly body: string;
+    constructor(method: string, path: string, status: number, body: string);
+}
+declare const MiB: (n: number) => number;
+declare const GiB: (n: number) => number;
+declare const NonRootUser = 4294967295;
+
+/**
+ * HTTP transport for the Slicer API. Supports two modes:
+ *   - Unix socket:  absolute path (`/...`), `unix://...`, `./...`, `../...`, `~/...`, or any `*.sock`.
+ *   - Network URL:  `http://host[:port]` or `https://host`.
+ *
+ * Mirrors the detection rules in the Go SDK's `normalizeUnixSocketPath`.
+ */
+
+type Transport = {
+    kind: 'socket';
+    socketPath: string;
+} | {
+    kind: 'net';
+    url: URL;
+};
+declare function resolveTransport(baseURL: string): Transport;
+interface TransportClientOptions {
+    baseURL: string;
+    token?: string;
+    userAgent?: string;
+}
+declare class TransportClient {
+    readonly transport: Transport;
+    private readonly token?;
+    private readonly userAgent;
+    constructor(opts: TransportClientOptions);
+    private agent;
+    private buildRequestOptions;
+    /** Buffered JSON request. Rejects on non-2xx via SlicerAPIError. */
+    request<T = unknown>(method: string, reqPath: string, body?: unknown): Promise<T>;
+    /** Raw-bytes request (for binary cp endpoints). */
+    requestRaw(method: string, reqPath: string, body?: Buffer, contentType?: string): Promise<Buffer>;
+    /** Streaming request producing a Node Readable of the response body. */
+    requestStreamRaw(method: string, reqPath: string, body?: Buffer | Readable, contentType?: string): Promise<IncomingMessage>;
+    /** Yields decoded JSON frames from an NDJSON response (one JSON object per line). */
+    requestNDJSON<Frame = unknown>(method: string, reqPath: string, body?: Buffer | Readable): AsyncGenerator<Frame, void, void>;
+}
+
+/**
+ * VM handle — returned from `client.vms.create()` / `client.vms.get()`.
+ * Exposes per-VM operations (exec, fs, power, lifecycle).
+ */
+
+/** Per-VM filesystem operations. */
+declare class VMFileSystem {
+    private readonly transport;
+    private readonly hostname;
+    constructor(transport: TransportClient, hostname: string);
+    readDir(path: string): Promise<FSEntry[]>;
+    stat(path: string): Promise<FSEntry | null>;
+    exists(path: string): Promise<boolean>;
+    mkdir(req: FSMkdirRequest): Promise<void>;
+    remove(path: string, recursive?: boolean): Promise<void>;
+    readFile(path: string): Promise<Buffer>;
+    writeFile(path: string, content: Buffer | string, opts?: {
+        uid?: number;
+        gid?: number;
+        permissions?: string;
+    }): Promise<void>;
+    /** Upload a tar archive, expanded into the VM at `path`. */
+    tarTo(path: string, tar: Buffer | Readable): Promise<void>;
+    /** Download `path` from the VM as a tar archive. */
+    tarFrom(path: string): Promise<Buffer>;
+}
+interface VMInit {
+    hostname: string;
+    hostGroup: string;
+    ip?: string;
+    createdAt?: string;
+    arch?: string;
+}
+declare class VM {
+    readonly hostname: string;
+    readonly hostGroup: string;
+    readonly ip?: string;
+    readonly createdAt?: string;
+    readonly arch?: string;
+    readonly fs: VMFileSystem;
+    private readonly transport;
+    constructor(transport: TransportClient, init: VMInit);
+    delete(): Promise<void>;
+    health(): Promise<AgentHealth>;
+    logs(): Promise<VMLogs>;
+    waitForAgent(opts?: WaitOptions): Promise<AgentHealth>;
+    waitForUserdata(opts?: WaitOptions): Promise<AgentHealth>;
+    shutdown(req?: ShutdownRequest): Promise<void>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    relaunch(): Promise<void>;
+    /** Mac-only on current daemons. Throws `SlicerAPIError 404` on Linux. */
+    suspend(): Promise<void>;
+    /** Mac-only on current daemons. Throws `SlicerAPIError 404` on Linux. */
+    restore(): Promise<void>;
+    /**
+     * Streaming exec — yields NDJSON frames (`started`, `stdout`, `stderr`, `exit`).
+     * When `req.stdio === 'base64'`, each frame's `data`/`stdout`/`stderr` string
+     * fields are preserved as-is (base64-encoded) and the SDK populates decoded
+     * `dataBytes`/`stdoutBytes`/`stderrBytes` Buffers alongside for convenience.
+     */
+    exec(req: ExecRequest): AsyncGenerator<ExecFrame, void, void>;
+    /**
+     * Buffered exec via `?buffered=true`. stdin is intentionally unsupported
+     * (matches Go SDK `ExecBuffered`); use `exec()` for stdin cases.
+     *
+     * When `req.stdio === 'base64'`, stdout/stderr are decoded from base64 and
+     * returned as `Buffer` — use this for binary output. Otherwise the result
+     * carries UTF-8 strings.
+     */
+    execBuffered(req: ExecRequest & {
+        stdio: 'base64';
+    }): Promise<ExecResultBinary>;
+    execBuffered(req: ExecRequest): Promise<ExecResult>;
+}
+
+/**
+ * Top-level namespaces on SlicerClient: hostGroups, vms, secrets.
+ * Keep control-plane operations here; per-VM operations live on the VM handle.
+ */
+
+declare class HostGroupsAPI {
+    private readonly transport;
+    constructor(transport: TransportClient);
+    list(): Promise<HostGroup[]>;
+    /** Convenience lookup (no single-group endpoint exists on the daemon). */
+    find(name: string): Promise<HostGroup | undefined>;
+    listVMs(name: string, opts?: ListOptions): Promise<VMInfo[]>;
+}
+declare class VMsAPI {
+    private readonly transport;
+    constructor(transport: TransportClient);
+    create(hostGroup: string, req?: CreateVMRequest, opts?: CreateVMOptions): Promise<VM>;
+    /**
+     * Build a VM handle for an existing VM given its hostgroup + hostname. No
+     * request is issued — use `health()` or `getInfo()` to verify reachability.
+     */
+    attach(hostGroup: string, hostname: string): VM;
+    /** Look up a VM by hostname across all host groups. Returns `undefined` if not found. */
+    get(hostname: string): Promise<VM | undefined>;
+    /** Return raw VM metadata across all host groups. */
+    list(opts?: ListOptions): Promise<VMInfo[]>;
+    stats(): Promise<VMStat[]>;
+    /**
+     * Raw response accessor — bypasses the VM handle. Useful when you only
+     * want the create metadata without a handle.
+     */
+    createRaw(hostGroup: string, req?: CreateVMRequest, opts?: CreateVMOptions): Promise<CreateVMResponse>;
+}
+declare class SecretsAPI {
+    private readonly transport;
+    constructor(transport: TransportClient);
+    list(): Promise<Secret[]>;
+    create(req: CreateSecretRequest): Promise<void>;
+    patch(name: string, req: UpdateSecretRequest): Promise<void>;
+    delete(name: string): Promise<void>;
+}
+
+/**
+ * SlicerClient — grouped TypeScript client for the Slicer VM API.
+ *
+ * Shape:
+ *   client.hostGroups.list() / find(name) / listVMs(name)
+ *   client.vms.create(group, req, opts) → VM / get(name) / list() / stats() / attach(group, name)
+ *   client.secrets.list / create / patch / delete
+ *   client.getInfo()
+ *
+ * Per-VM operations live on the `VM` handle returned from `client.vms.create`
+ * or `client.vms.attach`: `vm.exec`, `vm.execBuffered`, `vm.fs.*`,
+ * `vm.pause/resume/suspend/restore/shutdown/relaunch`, `vm.health/logs`,
+ * `vm.waitForAgent/waitForUserdata`, `vm.delete`.
+ */
+
+interface SlicerClientOptions extends TransportClientOptions {
+}
+declare class SlicerClient {
+    readonly transport: TransportClient;
+    readonly hostGroups: HostGroupsAPI;
+    readonly vms: VMsAPI;
+    readonly secrets: SecretsAPI;
+    constructor(opts: SlicerClientOptions);
+    static fromEnv(overrides?: Partial<SlicerClientOptions>): SlicerClient;
+    getInfo(): Promise<SlicerInfo>;
+}
+
+export { type AgentHealth, type CreateSecretRequest, type CreateVMOptions, type CreateVMRequest, type CreateVMResponse, type DeleteResponse, type ExecFrame, type ExecRequest, type ExecResult, type ExecResultBinary, type ExecStdio, ExecStdioBase64, ExecStdioText, type FSEntry, type FSMkdirRequest, GiB, type HostGroup, HostGroupsAPI, type ListOptions, MiB, NonRootUser, type Secret, SecretExistsError, SecretsAPI, type ShutdownRequest, SlicerAPIError, SlicerClient, type SlicerClientOptions, type SlicerInfo, type UpdateSecretRequest, VM, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, resolveTransport };