@aerol-ai/aerolvm-sdk 0.2.2 → 0.3.1

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, CustomDomainStatus, 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";

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

@@ -1 +1,16 @@
 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;

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

@@ -5,3 +5,22 @@
 //
 // 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)}`;
+}

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, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, Failover, HealthStatus, 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,15 @@ 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>;
     reconcile(): Promise<void>;
     health(): Promise<HealthStatus>;
     mounts(id: string): Promise<MountSpecRedacted[]>;
@@ -146,6 +155,19 @@ 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[]>;
+    };
     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, 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,23 @@ 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));
+    }
     async reconcile() {
         await this.doJSON("POST", this.versioned("/admin/reconcile"));
     }
@@ -334,6 +351,23 @@ 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),
+        };
+    }
     async createSnapshot(name) {
         return this.client.createSnapshot(this.id, name);
     }
@@ -390,6 +424,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) {
@@ -439,6 +474,7 @@ function toApiLifecycle(lifecycle) {
         destroy_if_idle_for: lifecycle.destroyIfIdleFor,
         stop_at_age: lifecycle.stopAtAge,
         destroy_at_age: lifecycle.destroyAtAge,
+        serverless: lifecycle.serverless,
     };
 }
 function toApiFailover(failover) {
@@ -521,6 +557,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,
@@ -614,6 +659,9 @@ function fromApiLifecycle(lifecycle) {
     if (lifecycle?.destroy_at_age !== undefined) {
         result.destroyAtAge = lifecycle.destroy_at_age;
     }
+    if (lifecycle?.serverless) {
+        result.serverless = true;
+    }
     return result;
 }
 function fromApiFailover(failover) {

package/dist/types.d.ts

@@ -73,6 +73,13 @@ export interface Lifecycle {
     stopAtAge?: number;
     /** Duration in integer nanoseconds. */
     destroyAtAge?: number;
+    /**
+     * Opt the sandbox into HTTP wake-on-request: auto-stop when idle,
+     * resume on the next inbound HTTP request. Requires `stopIfIdleFor`
+     * to be set explicitly — the server rejects `serverless: true`
+     * without an idle window. TCP and TLS exposures stay always-on.
+     */
+    serverless?: boolean;
 }
 export type UpdateLifecycleOptions = Lifecycle;
 export type FailoverPolicy = "none" | "recreate";
@@ -163,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). */
@@ -212,6 +226,21 @@ 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;
+}
 /**
  * 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.2",
+  "version": "0.3.1",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",