@aerol-ai/aerolvm-sdk 0.3.1 → 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, 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";
+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

@@ -14,3 +14,15 @@ export declare function sandboxCustomDomainsPath(prefix: string, id: string): st
  * `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

@@ -24,3 +24,19 @@ export function sandboxCustomDomainsPath(prefix, id) {
 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, 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";
+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
@@ -102,6 +102,17 @@ export declare class APIClient {
     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[]>;
@@ -167,6 +178,7 @@ export declare class SandboxResource implements Sandbox {
         add(hostname: string): Promise<CustomDomain[]>;
         remove(hostname: string): Promise<void>;
         list(): Promise<CustomDomain[]>;
+        dns(): Promise<CustomDomainDNSRecords>;
     };
     createSnapshot(name: string): Promise<SandboxSnapshot>;
     start(): Promise<this>;

package/dist/internal/client.js

@@ -1,5 +1,5 @@
 import { basename } from "node:path";
-import { PATH_PREFIX as V1_PATH_PREFIX, sandboxCustomDomainPath as v1SandboxCustomDomainPath, sandboxCustomDomainsPath as v1SandboxCustomDomainsPath, } 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 = {
@@ -237,6 +237,21 @@ export class APIClient {
     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"));
     }
@@ -366,6 +381,7 @@ export class SandboxResource {
             add: (hostname) => client.addCustomDomain(id, hostname),
             remove: (hostname) => client.removeCustomDomain(id, hostname),
             list: () => client.listCustomDomains(id),
+            dns: () => client.customDomainDNS(id),
         };
     }
     async createSnapshot(name) {

package/dist/types.d.ts

@@ -241,6 +241,54 @@ export interface CustomDomain {
     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.3.1",
+  "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"
   }