@aerol-ai/aerolvm-sdk 0.2.3 → 0.3.2

package/dist/MicroVM.d.ts

@@ -1,7 +1,7 @@
 import { type APIVersion } from "./internal/client.js";
 import { Sandbox } from "./Sandbox.js";
 import { Image } from "./Image.js";
-import type { BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, ExecStreamHandle, ExecStreamOptions, HealthStatus, Lifecycle, ListOptions, MountSpecRedacted, RegisterSnapshotOptions, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions } from "./types.js";
+import type { BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, ExecStreamHandle, ExecStreamOptions, HealthStatus, IngressTarget, Lifecycle, ListOptions, MountSpecRedacted, RegisterSnapshotOptions, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions } from "./types.js";
 type FetchLike = typeof fetch;
 export interface MicroVMConfig {
     patToken?: string;
@@ -51,6 +51,16 @@ export declare class MicroVM {
     sessionLog(sandboxID: string, sessionID: string): Promise<Uint8Array>;
     sessionRecording(sandboxID: string, sessionID: string): Promise<Uint8Array>;
     attachSession(sandboxID: string, sessionID: string, options?: SessionAttachOptions): SessionAttachHandle;
+    /**
+     * Cluster-level DNS helpers. Exposed as a namespaced accessor (rather
+     * than a flat `ingressDNS()` method) so call sites read like
+     * `microvm.dns.target()`, mirroring the per-sandbox `sandbox.customDomains`
+     * pattern. A fresh object is returned per access so the closures always
+     * see the current client even if MicroVM is later extended.
+     */
+    get dns(): {
+        target(): Promise<IngressTarget>;
+    };
     private wrap;
 }
 export {};

package/dist/MicroVM.js

@@ -109,6 +109,19 @@ export class MicroVM {
     attachSession(sandboxID, sessionID, options = {}) {
         return this.client.attachSession(sandboxID, sessionID, options);
     }
+    /**
+     * Cluster-level DNS helpers. Exposed as a namespaced accessor (rather
+     * than a flat `ingressDNS()` method) so call sites read like
+     * `microvm.dns.target()`, mirroring the per-sandbox `sandbox.customDomains`
+     * pattern. A fresh object is returned per access so the closures always
+     * see the current client even if MicroVM is later extended.
+     */
+    get dns() {
+        const client = this.client;
+        return {
+            target: () => client.ingressDNS(),
+        };
+    }
     wrap(sandbox) {
         return new Sandbox(this.client, sandbox);
     }

package/dist/index.d.ts

@@ -2,4 +2,4 @@ export { MicroVM } from "./MicroVM.js";
 export { Sandbox } from "./Sandbox.js";
 export { Image } from "./Image.js";
 export type { MicroVMConfig } from "./MicroVM.js";
-export type { BinaryLike, BuildImageOptions, BuildImagePushOptions, BuildImageResult, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, Failover, FailoverPolicy, HealthStatus, Lifecycle, MountSpec, MountSpecRedacted, MountType, RegisterSnapshotOptions, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxSnapshot, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, UpdateLifecycleOptions, } from "./types.js";
+export type { BinaryLike, BuildImageOptions, BuildImagePushOptions, BuildImageResult, CreateOptions, CreateSessionOptions, CustomDomain, CustomDomainDNSRecords, CustomDomainStatus, DNSRecord, DNSRecordType, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, Failover, FailoverPolicy, HealthStatus, IngressTarget, IngressTargetSource, Lifecycle, MountSpec, MountSpecRedacted, MountType, RegisterSnapshotOptions, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxSnapshot, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, UpdateLifecycleOptions, } from "./types.js";

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

@@ -1 +1,28 @@
 export declare const PATH_PREFIX = "/v1";
+/**
+ * Collection URL for a sandbox's custom-domain bindings. Used for both POST
+ * (add) and GET (list). The DELETE variant lives at
+ * {@link sandboxCustomDomainPath}.
+ *
+ * `id` is interpolated verbatim — sandbox IDs are server-generated opaque
+ * tokens and already URL-safe.
+ */
+export declare function sandboxCustomDomainsPath(prefix: string, id: string): string;
+/**
+ * URL for a single custom-domain binding. The hostname is percent-encoded so
+ * IDN punycode (`xn--...`) and wildcard labels round-trip safely through
+ * `DELETE /v1/sandboxes/{id}/custom-domains/{hostname}`.
+ */
+export declare function sandboxCustomDomainPath(prefix: string, id: string, hostname: string): string;
+/**
+ * URL for the cluster's published ingress address(es), used by
+ * `microvm.dns.target()` to render the CNAME/A target a user must point
+ * custom-domain DNS at.
+ */
+export declare function ingressDNSPath(prefix: string): string;
+/**
+ * URL for the ready-to-paste DNS records of one sandbox's custom-domain
+ * bindings. Sibling of {@link sandboxCustomDomainsPath} — same `id` rules
+ * apply.
+ */
+export declare function sandboxCustomDomainDNSPath(prefix: string, id: string): string;

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

@@ -5,3 +5,38 @@
 //
 // Keep this in sync with pkg/api/v1/dto.go::PathPrefix on the server.
 export const PATH_PREFIX = "/v1";
+/**
+ * Collection URL for a sandbox's custom-domain bindings. Used for both POST
+ * (add) and GET (list). The DELETE variant lives at
+ * {@link sandboxCustomDomainPath}.
+ *
+ * `id` is interpolated verbatim — sandbox IDs are server-generated opaque
+ * tokens and already URL-safe.
+ */
+export function sandboxCustomDomainsPath(prefix, id) {
+    return `${prefix}/sandboxes/${id}/custom-domains`;
+}
+/**
+ * URL for a single custom-domain binding. The hostname is percent-encoded so
+ * IDN punycode (`xn--...`) and wildcard labels round-trip safely through
+ * `DELETE /v1/sandboxes/{id}/custom-domains/{hostname}`.
+ */
+export function sandboxCustomDomainPath(prefix, id, hostname) {
+    return `${prefix}/sandboxes/${id}/custom-domains/${encodeURIComponent(hostname)}`;
+}
+/**
+ * URL for the cluster's published ingress address(es), used by
+ * `microvm.dns.target()` to render the CNAME/A target a user must point
+ * custom-domain DNS at.
+ */
+export function ingressDNSPath(prefix) {
+    return `${prefix}/ingress/dns`;
+}
+/**
+ * URL for the ready-to-paste DNS records of one sandbox's custom-domain
+ * bindings. Sibling of {@link sandboxCustomDomainsPath} — same `id` rules
+ * apply.
+ */
+export function sandboxCustomDomainDNSPath(prefix, id) {
+    return `${prefix}/sandboxes/${id}/custom-domains/dns`;
+}

package/dist/internal/client.d.ts

@@ -1,5 +1,5 @@
 import { Image } from "../Image.js";
-import type { BinaryLike, BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, Failover, HealthStatus, Lifecycle, ListOptions, MountSpecRedacted, NetworkUsage, RegisterSnapshotOptions, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions } from "../types.js";
+import type { BinaryLike, BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, CustomDomain, CustomDomainDNSRecords, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, Failover, HealthStatus, IngressTarget, Lifecycle, ListOptions, MountSpecRedacted, NetworkUsage, RegisterSnapshotOptions, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions } from "../types.js";
 type FetchLike = typeof fetch;
 /**
  * Wire version of the v1-style sandbox endpoints (`/v1/sandboxes`, etc.) this
@@ -93,6 +93,26 @@ export declare class APIClient {
      */
     exposePort(id: string, port: number, options?: ExposePortOptions): Promise<ExposeResult>;
     unexposePort(id: string, port: number): Promise<void>;
+    /**
+     * Bind a custom hostname to a sandbox. The server lowercases the hostname
+     * and returns the post-add list of bindings (sorted by hostname). Calling
+     * with an already-registered hostname is idempotent and returns the
+     * existing list.
+     */
+    addCustomDomain(id: string, hostname: string): Promise<CustomDomain[]>;
+    listCustomDomains(id: string): Promise<CustomDomain[]>;
+    removeCustomDomain(id: string, hostname: string): Promise<void>;
+    /**
+     * Fetch the cluster's published ingress address(es) — the CNAME/A target
+     * a user must point custom-domain DNS at. Field names already match the
+     * SDK's camelCase shape on the wire, so no translation is needed.
+     */
+    ingressDNS(): Promise<IngressTarget>;
+    /**
+     * Fetch the ready-to-paste DNS records for one sandbox's custom-domain
+     * bindings, along with the {@link IngressTarget} they were composed from.
+     */
+    customDomainDNS(id: string): Promise<CustomDomainDNSRecords>;
     reconcile(): Promise<void>;
     health(): Promise<HealthStatus>;
     mounts(id: string): Promise<MountSpecRedacted[]>;
@@ -146,6 +166,20 @@ export declare class SandboxResource implements Sandbox {
     downloadFile(targetPath: string): Promise<Uint8Array>;
     exposePort(port: number, options?: ExposePortOptions): Promise<ExposeResult>;
     unexposePort(port: number): Promise<void>;
+    /**
+     * Per-sandbox custom-hostname bindings. Exposed as a namespaced accessor
+     * (rather than `addCustomDomain`/`removeCustomDomain`/`listCustomDomains`
+     * methods on the resource) so call sites read like
+     * `sandbox.customDomains.add("api.acme.com")`, mirroring the noun in the
+     * `/v1/.../custom-domains` URL space. A fresh object is returned per access
+     * so the closures always see the current `id` even after `refresh()`.
+     */
+    get customDomains(): {
+        add(hostname: string): Promise<CustomDomain[]>;
+        remove(hostname: string): Promise<void>;
+        list(): Promise<CustomDomain[]>;
+        dns(): Promise<CustomDomainDNSRecords>;
+    };
     createSnapshot(name: string): Promise<SandboxSnapshot>;
     start(): Promise<this>;
     stop(): Promise<this>;

package/dist/internal/client.js

@@ -1,5 +1,5 @@
 import { basename } from "node:path";
-import { PATH_PREFIX as V1_PATH_PREFIX } from "./api/v1/paths.js";
+import { PATH_PREFIX as V1_PATH_PREFIX, ingressDNSPath as v1IngressDNSPath, sandboxCustomDomainDNSPath as v1SandboxCustomDomainDNSPath, sandboxCustomDomainPath as v1SandboxCustomDomainPath, sandboxCustomDomainsPath as v1SandboxCustomDomainsPath, } from "./api/v1/paths.js";
 import { Image } from "../Image.js";
 const DEFAULT_API_VERSION = "v1";
 const PATH_PREFIXES = {
@@ -220,6 +220,38 @@ export class APIClient {
     async unexposePort(id, port) {
         await this.doJSON("DELETE", `${this.versionPrefix}/sandboxes/${id}/ports/${port}`);
     }
+    /**
+     * Bind a custom hostname to a sandbox. The server lowercases the hostname
+     * and returns the post-add list of bindings (sorted by hostname). Calling
+     * with an already-registered hostname is idempotent and returns the
+     * existing list.
+     */
+    async addCustomDomain(id, hostname) {
+        const response = await this.doJSON("POST", v1SandboxCustomDomainsPath(this.versionPrefix, id), { hostname });
+        return response.custom_domains.map(fromApiCustomDomain);
+    }
+    async listCustomDomains(id) {
+        const response = await this.doJSON("GET", v1SandboxCustomDomainsPath(this.versionPrefix, id));
+        return response.custom_domains.map(fromApiCustomDomain);
+    }
+    async removeCustomDomain(id, hostname) {
+        await this.doJSON("DELETE", v1SandboxCustomDomainPath(this.versionPrefix, id, hostname));
+    }
+    /**
+     * Fetch the cluster's published ingress address(es) — the CNAME/A target
+     * a user must point custom-domain DNS at. Field names already match the
+     * SDK's camelCase shape on the wire, so no translation is needed.
+     */
+    async ingressDNS() {
+        return this.doJSON("GET", v1IngressDNSPath(this.versionPrefix));
+    }
+    /**
+     * Fetch the ready-to-paste DNS records for one sandbox's custom-domain
+     * bindings, along with the {@link IngressTarget} they were composed from.
+     */
+    async customDomainDNS(id) {
+        return this.doJSON("GET", v1SandboxCustomDomainDNSPath(this.versionPrefix, id));
+    }
     async reconcile() {
         await this.doJSON("POST", this.versioned("/admin/reconcile"));
     }
@@ -334,6 +366,24 @@ export class SandboxResource {
     async unexposePort(port) {
         await this.client.unexposePort(this.id, port);
     }
+    /**
+     * Per-sandbox custom-hostname bindings. Exposed as a namespaced accessor
+     * (rather than `addCustomDomain`/`removeCustomDomain`/`listCustomDomains`
+     * methods on the resource) so call sites read like
+     * `sandbox.customDomains.add("api.acme.com")`, mirroring the noun in the
+     * `/v1/.../custom-domains` URL space. A fresh object is returned per access
+     * so the closures always see the current `id` even after `refresh()`.
+     */
+    get customDomains() {
+        const client = this.client;
+        const id = this.id;
+        return {
+            add: (hostname) => client.addCustomDomain(id, hostname),
+            remove: (hostname) => client.removeCustomDomain(id, hostname),
+            list: () => client.listCustomDomains(id),
+            dns: () => client.customDomainDNS(id),
+        };
+    }
     async createSnapshot(name) {
         return this.client.createSnapshot(this.id, name);
     }
@@ -390,6 +440,7 @@ function toApiCreateOptions(options) {
         lifecycle: options.lifecycle ? toApiLifecycle(options.lifecycle) : undefined,
         failover: options.failover ? toApiFailover(options.failover) : undefined,
         runtime: options.runtime,
+        custom_domains: options.customDomains,
     };
 }
 function toApiRegisterSnapshotOptions(options) {
@@ -522,6 +573,15 @@ function fromApiSession(session) {
         attached: session.attached,
     };
 }
+function fromApiCustomDomain(domain) {
+    return {
+        hostname: domain.hostname,
+        status: domain.status,
+        lastError: domain.last_error,
+        createdAt: domain.created_at,
+        updatedAt: domain.updated_at,
+    };
+}
 function fromApiExposedPort(port) {
     return {
         sandboxID: port.sandbox_id,

package/dist/types.d.ts

@@ -170,6 +170,13 @@ export interface CreateOptions {
      * Not compatible with runtime="gvisor".
      */
     gpus?: GPUOptions;
+    /**
+     * Custom hostnames to bind to this sandbox at create-time. Each entry is
+     * lowercased server-side and progresses through the standard custom-domain
+     * lifecycle (pending_dns → issuing → ready). Equivalent to calling
+     * `sandbox.customDomains.add(host)` for each entry after create.
+     */
+    customDomains?: string[];
 }
 export interface ResizeOptions {
     /** Number of CPU cores. Fractional values supported (e.g. 0.5). */
@@ -219,6 +226,69 @@ export interface ExposedPort {
     publicURL: string;
     createdAt: string;
 }
+/**
+ * Lifecycle states for a per-sandbox custom hostname.
+ *  - "pending_dns": hostname registered; awaiting DNS to point at the daemon.
+ *  - "issuing":     DNS resolves; Caddy is acquiring an ACME certificate.
+ *  - "ready":       certificate issued; traffic served end-to-end on the host.
+ *  - "failed":      ACME or DNS validation failed; see `lastError`.
+ */
+export type CustomDomainStatus = "pending_dns" | "issuing" | "ready" | "failed";
+export interface CustomDomain {
+    hostname: string;
+    status: CustomDomainStatus;
+    lastError?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Where the SDK derived the ingress address(es) from. Reflects how the
+ * operator deployed the cluster:
+ *   - "hostname": the cluster gossips a stable hostname (CNAME target).
+ *   - "ips":      one or more raw ingress IPs (one A/AAAA record per IP).
+ *   - "mixed":    some nodes gossip a hostname, others raw IPs — prefer
+ *                 the hostname but render both so apex domains still work.
+ *   - "unknown":  no ingress node has gossiped a public address yet; the
+ *                 target is unusable and callers should surface that, not
+ *                 guess.
+ */
+export type IngressTargetSource = "hostname" | "ips" | "mixed" | "unknown";
+/**
+ * The cluster's published ingress address(es) — the value that DNS for a
+ * custom domain must ultimately resolve to. Returned by `microvm.dns.target()`
+ * and embedded in {@link CustomDomainDNSRecords}.
+ */
+export interface IngressTarget {
+    hostname?: string;
+    ips?: string[];
+    source: IngressTargetSource;
+}
+/** DNS record types the daemon emits for custom-domain wiring. */
+export type DNSRecordType = "CNAME" | "A" | "AAAA";
+/**
+ * One ready-to-paste DNS record a user adds at their DNS provider to make a
+ * custom domain reach the cluster. `name` is the leftmost label (or "@" for
+ * apex) the way DNS UIs accept it. `notes` carries provider-specific gotchas
+ * the daemon pre-renders (e.g. Cloudflare "DNS only, gray cloud") when
+ * applicable.
+ */
+export interface DNSRecord {
+    hostname: string;
+    type: DNSRecordType;
+    name: string;
+    value: string;
+    notes?: string;
+}
+/**
+ * Response from `sandbox.customDomains.dns()`. `records` is the flat
+ * ready-to-paste list (one row per custom domain × per ingress address);
+ * `target` is the raw aggregation the records were composed from, included
+ * so callers can render their own UI without a second round trip.
+ */
+export interface CustomDomainDNSRecords {
+    records: DNSRecord[];
+    target: IngressTarget;
+}
 /**
  * Wire protocol an exposure publishes through:
  *   - "http": Caddy HTTP reverse proxy at https://<id>-<port>.<domain>.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aerol-ai/aerolvm-sdk",
-  "version": "0.2.3",
+  "version": "0.3.2",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -21,7 +21,7 @@
     "test": "tsc -p tsconfig.test.json --outDir dist-test && node --test dist-test/*.test.js dist-test/internal/*.test.js"
   },
   "devDependencies": {
-    "@types/node": "^25.8.0",
+    "@types/node": "^25.9.1",
     "typescript": "^6.0.3",
     "tsx": "^4.22.3"
   }