@aerol-ai/aerolvm-sdk 0.1.5 → 0.1.7

package/dist/MicroVM.d.ts

@@ -1,3 +1,4 @@
+import { type APIVersion } from "./internal/client.js";
 import { Sandbox } from "./Sandbox.js";
 import type { CreateOptions, CreateSessionOptions, ExecStreamHandle, ExecStreamOptions, HealthStatus, Lifecycle, MountSpecRedacted, ResizeOptions, Session, SessionAttachHandle, SessionAttachOptions } from "./types.js";
 type FetchLike = typeof fetch;
@@ -5,6 +6,13 @@ export interface MicroVMConfig {
     patToken?: string;
     apiUrl?: string;
     fetch?: FetchLike;
+    /**
+     * Wire version of the sandbox daemon API to call. Defaults to the SDK's
+     * pinned default ("v1" today). The SDK package version and the API wire
+     * version evolve independently — you can pin one without affecting the
+     * other.
+     */
+    apiVersion?: APIVersion;
 }
 export declare class MicroVM {
     readonly apiUrl: string;

package/dist/MicroVM.js

@@ -18,6 +18,7 @@ export class MicroVM {
             baseURL: apiUrl,
             patToken,
             fetch: config.fetch,
+            apiVersion: config.apiVersion,
         });
     }
     async create(options) {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { MicroVM } from "./MicroVM.js";
 export { Sandbox } from "./Sandbox.js";
 export type { MicroVMConfig } from "./MicroVM.js";
-export type { BinaryLike, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, HealthStatus, Lifecycle, MountSpec, MountSpecRedacted, MountType, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, UpdateLifecycleOptions, } from "./types.js";
+export type { BinaryLike, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, HealthStatus, Lifecycle, MountSpec, MountSpecRedacted, MountType, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, UpdateLifecycleOptions, } from "./types.js";

package/dist/internal/api/v1/paths.d.ts

@@ -0,0 +1 @@
+export declare const PATH_PREFIX = "/v1";

package/dist/internal/api/v1/paths.js

@@ -0,0 +1,7 @@
+// v1 path-prefix constant. The TypeScript SDK uses this to build URLs against
+// the v1 surface of the sandbox daemon. When v2 lands, a sibling
+// internal/api/v2/paths.ts will export its own PATH_PREFIX, and the client
+// constructor's apiVersion option selects which one to use.
+//
+// Keep this in sync with pkg/api/v1/dto.go::PathPrefix on the server.
+export const PATH_PREFIX = "/v1";

package/dist/internal/client.d.ts

@@ -1,15 +1,37 @@
-import type { BinaryLike, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, HealthStatus, Lifecycle, MountSpecRedacted, ResizeOptions, Sandbox, Session, SessionAttachHandle, SessionAttachOptions } from "../types.js";
+import type { BinaryLike, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, HealthStatus, Lifecycle, MountSpecRedacted, ResizeOptions, Sandbox, Session, SessionAttachHandle, SessionAttachOptions } from "../types.js";
 type FetchLike = typeof fetch;
+/**
+ * Wire version of the sandbox daemon API this client speaks. The SDK and the
+ * server version independently — bumping the SDK package does not move the
+ * wire version. Today only "v1" exists; "v2" will be added when a wire-level
+ * breaking change is needed on the server.
+ */
+export type APIVersion = "v1";
 export interface APIClientConfig {
     baseURL: string;
     patToken?: string;
     fetch?: FetchLike;
+    /**
+     * Wire version to call. Defaults to "v1". Pin this if you need a specific
+     * version — otherwise the SDK will track its own default, which may move in
+     * a future major SDK release.
+     */
+    apiVersion?: APIVersion;
 }
 export declare class APIClient {
     readonly baseURL: string;
+    readonly apiVersion: APIVersion;
     private readonly patToken;
     private readonly fetchFn;
+    private readonly versionPrefix;
     constructor(config: APIClientConfig);
+    /**
+     * Build a versioned API path. Pass the suffix beginning with "/" (e.g.
+     * "/sandboxes") and the active version's prefix is prepended. Use this for
+     * every versioned API call so v2 (when it lands) can be selected by the
+     * apiVersion option without touching call sites.
+     */
+    private versioned;
     create(options: CreateOptions): Promise<SandboxResource>;
     list(): Promise<SandboxResource[]>;
     get(id: string): Promise<SandboxResource>;
@@ -31,20 +53,20 @@ export declare class APIClient {
     attachSession(id: string, sessionID: string, options?: SessionAttachOptions): SessionAttachHandle;
     uploadFile(id: string, targetPath: string, data: BinaryLike): Promise<void>;
     downloadFile(id: string, targetPath: string): Promise<Uint8Array>;
-    exposePort(id: string, port: number): Promise<string>;
-    /**
-     * Publish a raw TCP port through caddy-l4. The returned URL is in
-     * `tcp://<host>:<port>` form and works directly with `psql`, `redis-cli`,
-     * `mysql`, `mongosh`, and any other native-protocol client.
-     */
-    exposeTCPPort(id: string, port: number): Promise<string>;
     /**
-     * Publish a TCP port behind the shared TLS-SNI multiplexer. Returns
-     * `tls://<id>-<port>.<domain>:<l4-port>`. Requires the daemon to have a
-     * domain configured AND `SB_L4_TLS_LISTEN` set.
+     * Publish a sandbox container port. The chosen wire protocol is selected by
+     * `options.protocol` (defaults to `"http"`):
+     *
+     *   - `"http"`: Caddy HTTP reverse proxy at `https://<id>-<port>.<domain>`.
+     *   - `"tcp"`:  raw caddy-l4 listener on a parent-host port — pair with
+     *               native protocol clients (psql, redis-cli, mysql, mongosh).
+     *   - `"tls"`:  caddy-l4 TLS-SNI route on the shared listener. Requires the
+     *               daemon to have a domain configured AND `SB_L4_TLS_LISTEN` set.
+     *
+     * Returns a discriminated result keyed on `protocol`. Only the `"tcp"`
+     * variant carries `host` / `hostPort` — everything else is in `url`.
      */
-    exposeTLSPort(id: string, port: number): Promise<string>;
-    private exposePortWithProtocol;
+    exposePort(id: string, port: number, options?: ExposePortOptions): Promise<ExposeResult>;
     unexposePort(id: string, port: number): Promise<void>;
     reconcile(): Promise<void>;
     health(): Promise<HealthStatus>;
@@ -94,9 +116,7 @@ export declare class SandboxResource implements Sandbox {
     attachSession(sessionID: string, options?: SessionAttachOptions): SessionAttachHandle;
     uploadFile(targetPath: string, data: BinaryLike): Promise<void>;
     downloadFile(targetPath: string): Promise<Uint8Array>;
-    exposePort(port: number): Promise<string>;
-    exposeTCPPort(port: number): Promise<string>;
-    exposeTLSPort(port: number): Promise<string>;
+    exposePort(port: number, options?: ExposePortOptions): Promise<ExposeResult>;
     unexposePort(port: number): Promise<void>;
     start(): Promise<this>;
     stop(): Promise<this>;

package/dist/internal/client.js

@@ -1,133 +1,145 @@
 import { basename } from "node:path";
+import { PATH_PREFIX as V1_PATH_PREFIX } from "./api/v1/paths.js";
+const DEFAULT_API_VERSION = "v1";
+const PATH_PREFIXES = {
+    v1: V1_PATH_PREFIX,
+};
 export class APIClient {
     baseURL;
+    apiVersion;
     patToken;
     fetchFn;
+    versionPrefix;
     constructor(config) {
         this.baseURL = config.baseURL.replace(/\/+$/, "");
         this.patToken = config.patToken ?? "";
         this.fetchFn = config.fetch ?? fetch;
+        this.apiVersion = config.apiVersion ?? DEFAULT_API_VERSION;
+        this.versionPrefix = PATH_PREFIXES[this.apiVersion];
+    }
+    /**
+     * Build a versioned API path. Pass the suffix beginning with "/" (e.g.
+     * "/sandboxes") and the active version's prefix is prepended. Use this for
+     * every versioned API call so v2 (when it lands) can be selected by the
+     * apiVersion option without touching call sites.
+     */
+    versioned(suffix) {
+        return `${this.versionPrefix}${suffix}`;
     }
     async create(options) {
-        const response = await this.doJSON("POST", "/v1/sandboxes", toApiCreateOptions(options));
+        const response = await this.doJSON("POST", this.versioned("/sandboxes"), toApiCreateOptions(options));
         return new SandboxResource(this, fromApiCreateSandboxResponse(response));
     }
     async list() {
-        const response = await this.doJSON("GET", "/v1/sandboxes");
+        const response = await this.doJSON("GET", this.versioned("/sandboxes"));
         return response.map((item) => this.wrap(item));
     }
     async get(id) {
-        const response = await this.doJSON("GET", `/v1/sandboxes/${id}`);
+        const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}`);
         return this.wrap(response);
     }
     async start(id) {
-        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/start`);
+        const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/start`);
         return this.wrap(response);
     }
     async stop(id) {
-        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/stop`);
+        const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/stop`);
         return this.wrap(response);
     }
     async destroy(id) {
-        await this.doJSON("DELETE", `/v1/sandboxes/${id}`);
+        await this.doJSON("DELETE", `${this.versionPrefix}/sandboxes/${id}`);
     }
     async resize(id, options) {
-        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/resize`, toApiResizeOptions(options));
+        const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/resize`, toApiResizeOptions(options));
         return this.wrap(response);
     }
     async updateLifecycle(id, lifecycle) {
-        const response = await this.doJSON("PUT", `/v1/sandboxes/${id}/lifecycle`, toApiLifecycle(lifecycle));
+        const response = await this.doJSON("PUT", `${this.versionPrefix}/sandboxes/${id}/lifecycle`, toApiLifecycle(lifecycle));
         return this.wrap(response);
     }
     async exec(id, request) {
-        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/toolbox/process/execute`, toApiExecRequest(request));
+        const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/toolbox/process/execute`, toApiExecRequest(request));
         return fromApiExecResult(response);
     }
     execStream(id, options) {
-        return openExecStream(this.baseURL, this.patToken, id, options);
+        return openExecStream(this.baseURL, this.versionPrefix, this.patToken, id, options);
     }
     async createSession(id, options) {
-        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/sessions`, toApiCreateSessionOptions(options));
+        const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/sessions`, toApiCreateSessionOptions(options));
         return fromApiSession(response);
     }
     async listSessions(id) {
-        const response = await this.doJSON("GET", `/v1/sandboxes/${id}/sessions`);
+        const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/sessions`);
         return response.sessions.map(fromApiSession);
     }
     async getSession(id, sessionID) {
-        const response = await this.doJSON("GET", `/v1/sandboxes/${id}/sessions/${sessionID}`);
+        const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/sessions/${sessionID}`);
         return fromApiSession(response);
     }
     async deleteSession(id, sessionID) {
-        await this.doJSON("DELETE", `/v1/sandboxes/${id}/sessions/${sessionID}`);
+        await this.doJSON("DELETE", `${this.versionPrefix}/sandboxes/${id}/sessions/${sessionID}`);
     }
     async signalSession(id, sessionID, signal) {
-        await this.doJSON("POST", `/v1/sandboxes/${id}/sessions/${sessionID}/signal`, { signal });
+        await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/sessions/${sessionID}/signal`, { signal });
     }
     async resizeSession(id, sessionID, cols, rows) {
-        await this.doJSON("POST", `/v1/sandboxes/${id}/sessions/${sessionID}/resize`, { cols, rows });
+        await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/sessions/${sessionID}/resize`, { cols, rows });
     }
     async sessionLog(id, sessionID) {
-        return this.doBytes(`/v1/sandboxes/${id}/sessions/${sessionID}/log`);
+        return this.doBytes(`${this.versionPrefix}/sandboxes/${id}/sessions/${sessionID}/log`);
     }
     async sessionRecording(id, sessionID) {
-        return this.doBytes(`/v1/sandboxes/${id}/sessions/${sessionID}/recording`);
+        return this.doBytes(`${this.versionPrefix}/sandboxes/${id}/sessions/${sessionID}/recording`);
     }
     attachSession(id, sessionID, options = {}) {
-        return openSessionAttach(this.baseURL, this.patToken, id, sessionID, options);
+        return openSessionAttach(this.baseURL, this.versionPrefix, this.patToken, id, sessionID, options);
     }
     async uploadFile(id, targetPath, data) {
         const form = new FormData();
         form.set("path", targetPath);
         form.set("file", toBlob(data), basename(targetPath));
-        const response = await this.request("POST", `/v1/sandboxes/${id}/toolbox/files/upload`, { body: form });
+        const response = await this.request("POST", `${this.versionPrefix}/sandboxes/${id}/toolbox/files/upload`, { body: form });
         if (!response.ok) {
             throw await decodeError(response);
         }
     }
     async downloadFile(id, targetPath) {
-        const response = await this.request("GET", `/v1/sandboxes/${id}/toolbox/files/download?path=${encodeURIComponent(targetPath)}`);
+        const response = await this.request("GET", `${this.versionPrefix}/sandboxes/${id}/toolbox/files/download?path=${encodeURIComponent(targetPath)}`);
         if (!response.ok) {
             throw await decodeError(response);
         }
         return new Uint8Array(await response.arrayBuffer());
     }
-    async exposePort(id, port) {
-        return this.exposePortWithProtocol(id, port);
-    }
-    /**
-     * Publish a raw TCP port through caddy-l4. The returned URL is in
-     * `tcp://<host>:<port>` form and works directly with `psql`, `redis-cli`,
-     * `mysql`, `mongosh`, and any other native-protocol client.
-     */
-    async exposeTCPPort(id, port) {
-        return this.exposePortWithProtocol(id, port, "tcp");
-    }
     /**
-     * Publish a TCP port behind the shared TLS-SNI multiplexer. Returns
-     * `tls://<id>-<port>.<domain>:<l4-port>`. Requires the daemon to have a
-     * domain configured AND `SB_L4_TLS_LISTEN` set.
+     * Publish a sandbox container port. The chosen wire protocol is selected by
+     * `options.protocol` (defaults to `"http"`):
+     *
+     *   - `"http"`: Caddy HTTP reverse proxy at `https://<id>-<port>.<domain>`.
+     *   - `"tcp"`:  raw caddy-l4 listener on a parent-host port — pair with
+     *               native protocol clients (psql, redis-cli, mysql, mongosh).
+     *   - `"tls"`:  caddy-l4 TLS-SNI route on the shared listener. Requires the
+     *               daemon to have a domain configured AND `SB_L4_TLS_LISTEN` set.
+     *
+     * Returns a discriminated result keyed on `protocol`. Only the `"tcp"`
+     * variant carries `host` / `hostPort` — everything else is in `url`.
      */
-    async exposeTLSPort(id, port) {
-        return this.exposePortWithProtocol(id, port, "tls");
-    }
-    async exposePortWithProtocol(id, port, protocol) {
-        const body = protocol ? { protocol } : undefined;
-        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/ports/${port}`, body);
-        return response.public_url;
+    async exposePort(id, port, options = {}) {
+        const body = options.protocol ? { protocol: options.protocol } : undefined;
+        const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/ports/${port}`, body);
+        return fromApiExposePortResponse(response);
     }
     async unexposePort(id, port) {
-        await this.doJSON("DELETE", `/v1/sandboxes/${id}/ports/${port}`);
+        await this.doJSON("DELETE", `${this.versionPrefix}/sandboxes/${id}/ports/${port}`);
     }
     async reconcile() {
-        await this.doJSON("POST", "/v1/admin/reconcile");
+        await this.doJSON("POST", this.versioned("/admin/reconcile"));
     }
     async health() {
         const response = await this.doJSON("GET", "/health");
         return fromApiHealthStatus(response);
     }
     async mounts(id) {
-        const response = await this.doJSON("GET", `/v1/sandboxes/${id}/mounts`);
+        const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/mounts`);
         return response.mounts.map(fromApiMountSpecRedacted);
     }
     wrap(sandbox) {
@@ -219,14 +231,8 @@ export class SandboxResource {
     async downloadFile(targetPath) {
         return this.client.downloadFile(this.id, targetPath);
     }
-    async exposePort(port) {
-        return this.client.exposePort(this.id, port);
-    }
-    async exposeTCPPort(port) {
-        return this.client.exposeTCPPort(this.id, port);
-    }
-    async exposeTLSPort(port) {
-        return this.client.exposeTLSPort(this.id, port);
+    async exposePort(port, options) {
+        return this.client.exposePort(this.id, port, options);
     }
     async unexposePort(port) {
         await this.client.unexposePort(this.id, port);
@@ -379,6 +385,21 @@ function fromApiExposedPort(port) {
         createdAt: port.created_at,
     };
 }
+function fromApiExposePortResponse(response) {
+    switch (response.protocol) {
+        case "tcp":
+            return {
+                protocol: "tcp",
+                url: response.public_url,
+                host: response.host ?? "",
+                hostPort: response.host_port ?? 0,
+            };
+        case "tls":
+            return { protocol: "tls", url: response.public_url };
+        case "http":
+            return { protocol: "http", url: response.public_url };
+    }
+}
 function fromApiExecResult(result) {
     return {
         stdout: result.stdout,
@@ -497,8 +518,14 @@ function describeWSClose(event) {
         parts.push(`wasClean=${e.wasClean}`);
     return parts.join(" ");
 }
-function openExecStream(baseURL, patToken, sandboxID, options) {
-    const wsURL = baseURL.replace(/^http/, "ws") + `/v1/sandboxes/${encodeURIComponent(sandboxID)}/toolbox/process/exec/stream`;
+function toWebSocketBinaryFrame(data) {
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    const frame = new Uint8Array(bytes.byteLength);
+    frame.set(bytes);
+    return frame;
+}
+function openExecStream(baseURL, versionPrefix, patToken, sandboxID, options) {
+    const wsURL = baseURL.replace(/^http/, "ws") + `${versionPrefix}/sandboxes/${encodeURIComponent(sandboxID)}/toolbox/process/exec/stream`;
     const WS = globalThis.WebSocket;
     if (!WS) {
         throw new Error("WebSocket is not available in this runtime — Node 22+ or a browser is required");
@@ -587,8 +614,7 @@ function openExecStream(baseURL, patToken, sandboxID, options) {
         failWith(detail !== "" ? `websocket error: ${detail}` : "websocket error");
     });
     const sendBinary = (data) => {
-        const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
-        ws.send(bytes);
+        ws.send(toWebSocketBinaryFrame(data));
     };
     return {
         write: sendBinary,
@@ -604,8 +630,8 @@ function openExecStream(baseURL, patToken, sandboxID, options) {
         done,
     };
 }
-function openSessionAttach(baseURL, patToken, sandboxID, sessionID, options) {
-    const wsURL = baseURL.replace(/^http/, "ws") + `/v1/sandboxes/${encodeURIComponent(sandboxID)}/sessions/${encodeURIComponent(sessionID)}/attach`;
+function openSessionAttach(baseURL, versionPrefix, patToken, sandboxID, sessionID, options) {
+    const wsURL = baseURL.replace(/^http/, "ws") + `${versionPrefix}/sandboxes/${encodeURIComponent(sandboxID)}/sessions/${encodeURIComponent(sessionID)}/attach`;
     const WS = globalThis.WebSocket;
     if (!WS) {
         throw new Error("WebSocket is not available in this runtime — Node 22+ or a browser is required");
@@ -687,8 +713,7 @@ function openSessionAttach(baseURL, patToken, sandboxID, sessionID, options) {
         failWith(detail !== "" ? `websocket error: ${detail}` : "websocket error");
     });
     const sendBinary = (data) => {
-        const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
-        ws.send(bytes);
+        ws.send(toWebSocketBinaryFrame(data));
     };
     return {
         write: sendBinary,

package/dist/types.d.ts

@@ -129,6 +129,35 @@ export interface ExposedPort {
     publicURL: string;
     createdAt: string;
 }
+/**
+ * Wire protocol an exposure publishes through:
+ *   - "http": Caddy HTTP reverse proxy at https://<id>-<port>.<domain>.
+ *   - "tcp":  raw caddy-l4 listener on a parent-host port.
+ *   - "tls":  caddy-l4 TLS-SNI route on the shared :443 listener.
+ */
+export type ExposeProtocol = "http" | "tcp" | "tls";
+export interface ExposePortOptions {
+    /** Defaults to "http" when omitted. */
+    protocol?: ExposeProtocol;
+}
+/**
+ * Discriminated result from `exposePort`. Branch on `protocol` to access the
+ * fields that are meaningful for the chosen wire protocol — only the raw-TCP
+ * variant carries `host` and `hostPort`, which are what native protocol
+ * clients (psql, redis-cli, mysql, mongosh, …) need to dial.
+ */
+export type ExposeResult = {
+    protocol: "http";
+    url: string;
+} | {
+    protocol: "tcp";
+    url: string;
+    host: string;
+    hostPort: number;
+} | {
+    protocol: "tls";
+    url: string;
+};
 export interface Sandbox {
     id: string;
     image: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aerol-ai/aerolvm-sdk",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -20,8 +20,8 @@
     "test": "tsc -p tsconfig.test.json --outDir dist-test && node --test dist-test/*.test.js"
   },
   "devDependencies": {
-    "@types/node": "^22.15.17",
-    "typescript": "^5.8.3",
+    "@types/node": "^25.6.2",
+    "typescript": "^6.0.3",
     "tsx": "^4.21.0"
   }
 }