@miosa/sdk 1.2.2 → 1.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miosa/sdk",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "TypeScript SDK for the MIOSA API — cloud VM desktop infrastructure for AI agents",
   "license": "MIT",
   "author": "MIOSA <hello@miosa.ai>",

package/src/client.ts

@@ -15,6 +15,7 @@ import { CronJobs } from "./resources/cron-jobs.js";
 import { Dashboard } from "./resources/dashboard.js";
 import { Databases } from "./resources/databases.js";
 import { Deployments } from "./resources/deployments.js";
+import { DockerDeploy } from "./resources/docker-deploy.js";
 import { EgressAudit } from "./resources/egressAudit.js";
 import { EgressNetwork } from "./resources/egressNetwork.js";
 import { EgressSecrets } from "./resources/egressSecrets.js";
@@ -130,6 +131,9 @@ export class Miosa {
    */
   readonly deployments: Deployments;
 
+  /** Docker Deploy appliance hosts — one always-on workspace host, many apps. */
+  readonly dockerDeploy: DockerDeploy;
+
   /** Credit balance and usage. */
   readonly credits: Credits;
 
@@ -257,6 +261,7 @@ export class Miosa {
     this.computers = new Computers(this.http);
     this.sandboxes = new Sandboxes(this.http);
     this.deployments = new Deployments(this.http);
+    this.dockerDeploy = new DockerDeploy(this.http);
     this.credits = new Credits(this.http);
     this.admin = new Admin(this.http);
     this.openComputers = new OpenComputers(this.http);

package/src/index.ts

@@ -136,6 +136,10 @@ export type {
   DeploymentVersionKind,
   DeploymentVersionState,
   DockerDeployCreateParams,
+  DockerDeployDoctorCheck,
+  DockerDeployDoctorParams,
+  DockerDeployDoctorProbe,
+  DockerDeployDoctorResult,
   ExternalAttribution,
   PublishFromSandboxParams,
   PublishParams,
@@ -147,6 +151,17 @@ export type {
   RuntimeLogsResult,
   VersionListParams,
 } from "./resources/deployments.js";
+export { DockerDeploy } from "./resources/docker-deploy.js";
+export type {
+  DockerDeployApplianceStatus,
+  DockerDeployHostData,
+  DockerDeployHostEnsureParams,
+  DockerDeployHostId,
+  DockerDeployHostListParams,
+  DockerDeployHostListResponse,
+  DockerDeployHostResponse,
+  DockerDeployHostStatus,
+} from "./resources/docker-deploy.js";
 export type {
   SnapshotData,
   SnapshotStatus,

package/src/resources/deployments.test.ts

@@ -3,15 +3,18 @@ import type { HttpClient } from "../http.js";
 import { Deployments } from "./deployments.js";
 
 const mockRequest = vi.fn();
+const mockGet = vi.fn();
 
 function makeHttp(): HttpClient {
   const http = {} as HttpClient;
   http.request = mockRequest;
+  http.get = mockGet;
   return http;
 }
 
 beforeEach(() => {
   vi.clearAllMocks();
+  vi.unstubAllGlobals();
 });
 
 describe("Deployments", () => {
@@ -52,4 +55,67 @@ describe("Deployments", () => {
     expect(deployment.deployment_product).toBe("docker_deploy");
     expect(deployment.docker_deploy_host_id).toBe("ddh_123");
   });
+
+  it("doctorDockerDeploy verifies host, route metadata, and public URL", async () => {
+    mockGet.mockImplementation(async (path: string) => {
+      if (path === "/deployments/dep_123") {
+        return {
+          data: {
+            id: "dep_123",
+            tenant_id: "ten_123",
+            name: "Clinic Intake",
+            slug: "clinic-intake",
+            state: "running",
+            deployment_product: "docker_deploy",
+            docker_deploy_host_id: "ddh_123",
+            public_url: "https://clinic-intake.osa.miosa.app",
+            metadata: {
+              deployment_product: "docker_deploy",
+              runtime: { ip: "172.16.74.246", port: 23906 },
+            },
+          },
+        };
+      }
+
+      if (path === "/docker-deploy/hosts/ddh_123") {
+        return {
+          data: {
+            id: "ddh_123",
+            tenant_id: "ten_123",
+            workspace_id: "ws_123",
+            status: "active",
+            size: "medium",
+            region: "us",
+            appliance_status: "healthy",
+          },
+        };
+      }
+
+      throw new Error(`unexpected path ${path}`);
+    });
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({ ok: true, status: 200 }),
+    );
+
+    const result = await new Deployments(makeHttp()).doctorDockerDeploy(
+      "dep_123",
+      { probePath: "/health" },
+    );
+
+    expect(result.ok).toBe(true);
+    expect(mockGet).toHaveBeenCalledWith("/deployments/dep_123");
+    expect(mockGet).toHaveBeenCalledWith("/docker-deploy/hosts/ddh_123");
+    expect(fetch).toHaveBeenCalledWith(
+      "https://clinic-intake.osa.miosa.app/health",
+      expect.objectContaining({ method: "GET" }),
+    );
+    expect(result.checks.map((check) => check.name)).toEqual([
+      "deployment_product",
+      "docker_deploy_host_id",
+      "docker_deploy_host_health",
+      "runtime_route",
+      "public_url_probe",
+    ]);
+  });
 });

package/src/resources/deployments.ts

@@ -13,6 +13,7 @@
 import { randomUUID } from "node:crypto";
 
 import type { HttpClient } from "../http.js";
+import type { DockerDeployHostData } from "./docker-deploy.js";
 
 // ── Branded IDs ─────────────────────────────────────────────────────────────
 
@@ -120,6 +121,35 @@ export interface DeploymentData {
   updated_at?: string;
 }
 
+export interface DockerDeployDoctorCheck {
+  name: string;
+  ok: boolean;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export interface DockerDeployDoctorProbe {
+  url: string;
+  ok: boolean;
+  status?: number;
+  error?: string;
+}
+
+export interface DockerDeployDoctorResult {
+  ok: boolean;
+  deployment: DeploymentData;
+  host?: DockerDeployHostData;
+  checks: DockerDeployDoctorCheck[];
+  probe?: DockerDeployDoctorProbe;
+}
+
+export interface DockerDeployDoctorParams {
+  probePath?: string;
+  probe_path?: string;
+  timeoutMs?: number;
+  timeout_ms?: number;
+}
+
 export type DeploymentDatabaseRequest =
   | boolean
   | {
@@ -436,6 +466,43 @@ function dockerDeployMetadata(
   };
 }
 
+function dockerDeployProduct(deployment: DeploymentData): unknown {
+  return (
+    deployment.deployment_product ??
+    deployment.metadata?.["deployment_product"]
+  );
+}
+
+function dockerDeployHostId(deployment: DeploymentData): string | null {
+  const metadataHost = deployment.metadata?.["docker_deploy_host_id"];
+  return (
+    deployment.docker_deploy_host_id ??
+    (typeof metadataHost === "string" ? metadataHost : null)
+  );
+}
+
+function addDoctorCheck(
+  checks: DockerDeployDoctorCheck[],
+  name: string,
+  ok: boolean,
+  message: string,
+  details?: Record<string, unknown>,
+): void {
+  checks.push({ name, ok, message, ...(details ? { details } : {}) });
+}
+
+function hostHealthy(host: DockerDeployHostData | undefined): boolean {
+  return Boolean(
+    host && host.status === "active" && host.appliance_status === "healthy",
+  );
+}
+
+function probeUrl(publicUrl: string, probePath: string): string {
+  const url = new URL(publicUrl);
+  url.pathname = probePath.startsWith("/") ? probePath : `/${probePath}`;
+  return url.toString();
+}
+
 // ── Sub-resources ──────────────────────────────────────────────────────────
 
 export class DeploymentVersions {
@@ -656,6 +723,140 @@ export class Deployments {
     });
   }
 
+  /**
+   * Verify a Docker Deploy deployment before telling a user or agent it is
+   * live. Checks product markers, appliance host health, route metadata, and
+   * optionally probes the public URL.
+   */
+  async doctorDockerDeploy(
+    deploymentId: string,
+    params: DockerDeployDoctorParams = {},
+  ): Promise<DockerDeployDoctorResult> {
+    const checks: DockerDeployDoctorCheck[] = [];
+    const deployment = await this.get(deploymentId);
+    const metadata = deployment.metadata ?? {};
+    const product = dockerDeployProduct(deployment);
+    const hostId = dockerDeployHostId(deployment);
+
+    addDoctorCheck(
+      checks,
+      "deployment_product",
+      product === "docker_deploy",
+      product === "docker_deploy"
+        ? "Deployment is marked for Docker Deploy."
+        : `Expected deployment_product=docker_deploy, got ${String(product ?? "missing")}.`,
+      { deployment_product: product ?? null },
+    );
+
+    addDoctorCheck(
+      checks,
+      "docker_deploy_host_id",
+      Boolean(hostId),
+      hostId
+        ? "Deployment has a Docker Deploy host id."
+        : "Deployment has no docker_deploy_host_id.",
+      { docker_deploy_host_id: hostId },
+    );
+
+    let host: DockerDeployHostData | undefined;
+    if (hostId) {
+      try {
+        const rawHost = await this.http.get<unknown>(
+          `/docker-deploy/hosts/${hostId}`,
+        );
+        host = unwrap(rawHost) as DockerDeployHostData;
+        addDoctorCheck(
+          checks,
+          "docker_deploy_host_health",
+          hostHealthy(host),
+          hostHealthy(host)
+            ? "Docker Deploy host is active and healthy."
+            : `Docker Deploy host status=${host.status} appliance=${host.appliance_status}.`,
+          {
+            status: host.status,
+            appliance_status: host.appliance_status,
+          },
+        );
+      } catch (error) {
+        addDoctorCheck(
+          checks,
+          "docker_deploy_host_health",
+          false,
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+    }
+
+    const runtime = metadata["runtime"];
+    const hasRuntimeRoute =
+      typeof runtime === "object" &&
+      runtime !== null &&
+      typeof (runtime as Record<string, unknown>)["ip"] === "string" &&
+      typeof (runtime as Record<string, unknown>)["port"] === "number";
+    addDoctorCheck(
+      checks,
+      "runtime_route",
+      hasRuntimeRoute,
+      hasRuntimeRoute
+        ? "Deployment has appliance runtime route metadata."
+        : "Deployment is missing appliance runtime route metadata.",
+      typeof runtime === "object" && runtime !== null
+        ? (runtime as Record<string, unknown>)
+        : undefined,
+    );
+
+    let probe: DockerDeployDoctorProbe | undefined;
+    const publicUrl = deployment.public_url;
+    const path = params.probePath ?? params.probe_path ?? "/";
+    if (publicUrl && typeof fetch === "function") {
+      const url = probeUrl(publicUrl, path);
+      const controller = new AbortController();
+      const timeout = setTimeout(
+        () => controller.abort(),
+        params.timeoutMs ?? params.timeout_ms ?? 10_000,
+      );
+      try {
+        const response = await fetch(url, {
+          method: "GET",
+          signal: controller.signal,
+        });
+        probe = { url, ok: response.ok, status: response.status };
+        addDoctorCheck(
+          checks,
+          "public_url_probe",
+          response.ok,
+          response.ok
+            ? `Public URL returned HTTP ${response.status}.`
+            : `Public URL returned HTTP ${response.status}.`,
+          { url, status: response.status },
+        );
+      } catch (error) {
+        probe = {
+          url,
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
+        addDoctorCheck(
+          checks,
+          "public_url_probe",
+          false,
+          probe.error ?? "Public URL probe failed.",
+          { url },
+        );
+      } finally {
+        clearTimeout(timeout);
+      }
+    }
+
+    return {
+      ok: checks.every((check) => check.ok),
+      deployment,
+      ...(host ? { host } : {}),
+      checks,
+      ...(probe ? { probe } : {}),
+    };
+  }
+
   async update(
     deploymentId: string,
     params: DeploymentUpdateParams,

package/src/resources/docker-deploy.test.ts

@@ -0,0 +1,102 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { HttpClient } from "../http.js";
+import { DockerDeploy } from "./docker-deploy.js";
+
+const mockGet = vi.fn();
+const mockPost = vi.fn();
+
+function makeHttp(): HttpClient {
+  const http = {} as HttpClient;
+  http.get = mockGet;
+  http.post = mockPost;
+  return http;
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("DockerDeploy", () => {
+  it("lists Docker Deploy hosts by workspace", async () => {
+    mockGet.mockResolvedValue({
+      data: [
+        {
+          id: "ddh_123",
+          tenant_id: "ten_123",
+          workspace_id: "ws_123",
+          status: "bootstrapping",
+          appliance_status: "starting",
+          size: "medium",
+          region: "us",
+        },
+      ],
+    });
+
+    const hosts = await new DockerDeploy(makeHttp()).listHosts({
+      workspaceId: "ws_123",
+    });
+
+    expect(mockGet).toHaveBeenCalledWith("/docker-deploy/hosts", {
+      workspace_id: "ws_123",
+    });
+    expect(hosts[0]?.id).toBe("ddh_123");
+  });
+
+  it("ensures a workspace Docker Deploy host", async () => {
+    mockPost.mockResolvedValue({
+      host: {
+        id: "ddh_123",
+        tenant_id: "ten_123",
+        workspace_id: "ws_123",
+        status: "pending",
+        appliance_status: "not_installed",
+        size: "medium",
+        region: "us",
+      },
+      queued: true,
+    });
+
+    const result = await new DockerDeploy(makeHttp()).ensureHost({
+      workspaceId: "ws_123",
+    });
+
+    expect(mockPost).toHaveBeenCalledWith("/docker-deploy/hosts/ensure", {
+      workspace_id: "ws_123",
+    });
+    expect(result.queued).toBe(true);
+    expect(result.host.status).toBe("pending");
+  });
+
+  it("lists Docker Deploy templates", async () => {
+    mockGet.mockResolvedValue({
+      data: [
+        {
+          id: "nextjs-app",
+          name: "Next.js app",
+          description: "App router starter",
+        },
+      ],
+    });
+
+    const templates = await new DockerDeploy(makeHttp()).listTemplates();
+
+    expect(mockGet).toHaveBeenCalledWith("/docker-deploy/templates");
+    expect(templates[0]?.id).toBe("nextjs-app");
+  });
+
+  it("gets a Docker Deploy template", async () => {
+    mockGet.mockResolvedValue({
+      template: {
+        id: "compose-full-stack",
+        name: "Compose full stack",
+      },
+    });
+
+    const template = await new DockerDeploy(makeHttp()).getTemplate("compose-full-stack");
+
+    expect(mockGet).toHaveBeenCalledWith(
+      "/docker-deploy/templates/compose-full-stack",
+    );
+    expect(template.id).toBe("compose-full-stack");
+  });
+});

package/src/resources/docker-deploy.ts

@@ -0,0 +1,183 @@
+import type { HttpClient } from "../http.js";
+
+export type DockerDeployHostId = string & {
+  readonly __brand: "DockerDeployHostId";
+};
+
+export type DockerDeployHostStatus =
+  | "pending"
+  | "provisioning"
+  | "bootstrapping"
+  | "active"
+  | "degraded"
+  | "suspended"
+  | "retired"
+  | "error";
+
+export type DockerDeployApplianceStatus =
+  | "not_installed"
+  | "installing"
+  | "starting"
+  | "healthy"
+  | "unhealthy"
+  | "unknown";
+
+export interface DockerDeployHostData {
+  id: DockerDeployHostId;
+  tenant_id: string;
+  workspace_id: string;
+  external_workspace_id?: string | null;
+  computer_id?: string | null;
+  fleet_node_id?: string | null;
+  status: DockerDeployHostStatus;
+  size: string;
+  region: string;
+  portal_domain?: string | null;
+  runtime_base_url?: string | null;
+  agent_base_url?: string | null;
+  appliance_image?: string | null;
+  appliance_version?: string | null;
+  appliance_status: DockerDeployApplianceStatus;
+  agent_last_seen_at?: string | null;
+  metadata?: Record<string, unknown>;
+  created_at?: string;
+  updated_at?: string;
+}
+
+export interface DockerDeployHostListParams {
+  workspace_id?: string;
+  workspaceId?: string;
+}
+
+export interface DockerDeployHostEnsureParams {
+  workspace_id?: string;
+  workspaceId?: string;
+  external_workspace_id?: string;
+  externalWorkspaceId?: string;
+}
+
+export interface DockerDeployHostListResponse {
+  data?: DockerDeployHostData[];
+  hosts?: DockerDeployHostData[];
+}
+
+export interface DockerDeployHostResponse {
+  data?: DockerDeployHostData;
+  host?: DockerDeployHostData;
+  queued?: boolean;
+}
+
+export interface DockerDeployTemplate {
+  id: string;
+  name: string;
+  description?: string;
+  category?: string;
+  runtime?: string;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface DockerDeployTemplateListResponse {
+  data?: DockerDeployTemplate[];
+  templates?: DockerDeployTemplate[];
+}
+
+export interface DockerDeployTemplateResponse {
+  data?: DockerDeployTemplate;
+  template?: DockerDeployTemplate;
+}
+
+function workspaceId(params?: DockerDeployHostListParams): string | undefined {
+  return params?.workspace_id ?? params?.workspaceId;
+}
+
+function ensureBody(params: DockerDeployHostEnsureParams): Record<string, string> {
+  const body: Record<string, string> = {};
+  const id = params.workspace_id ?? params.workspaceId;
+  const externalId = params.external_workspace_id ?? params.externalWorkspaceId;
+  if (id) body.workspace_id = id;
+  if (externalId) body.external_workspace_id = externalId;
+  return body;
+}
+
+function unwrapHost(response: DockerDeployHostResponse): DockerDeployHostData {
+  const host = response.data ?? response.host;
+  if (!host) {
+    throw new Error("Docker Deploy host response was empty.");
+  }
+  return host;
+}
+
+function unwrapTemplates(response: DockerDeployTemplateListResponse): DockerDeployTemplate[] {
+  return response.data ?? response.templates ?? [];
+}
+
+function unwrapTemplate(response: DockerDeployTemplateResponse): DockerDeployTemplate {
+  const template = response.data ?? response.template;
+  if (!template) {
+    throw new Error("Docker Deploy template response was empty.");
+  }
+  return template;
+}
+
+export class DockerDeploy {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * List Docker Deploy appliance hosts scoped to the current tenant.
+   *
+   * Pass a workspace ID to inspect the dedicated always-on appliance machine
+   * for one white-label workspace.
+   */
+  async listHosts(
+    params: DockerDeployHostListParams = {},
+  ): Promise<DockerDeployHostData[]> {
+    const res = await this.http.get<DockerDeployHostListResponse>(
+      "/docker-deploy/hosts",
+      { workspace_id: workspaceId(params) },
+    );
+    return res.data ?? res.hosts ?? [];
+  }
+
+  /**
+   * Ensure a workspace has its dedicated Docker Deploy appliance host.
+   *
+   * The host may still be `pending`, `provisioning`, or `bootstrapping` after
+   * this call. Treat `status === "active"` and `appliance_status === "healthy"`
+   * as the ready condition before sending app/container traffic to it.
+   */
+  async ensureHost(
+    params: DockerDeployHostEnsureParams = {},
+  ): Promise<{ host: DockerDeployHostData; queued: boolean }> {
+    const res = await this.http.post<DockerDeployHostResponse>(
+      "/docker-deploy/hosts/ensure",
+      ensureBody(params),
+    );
+    return { host: unwrapHost(res), queued: res.queued ?? false };
+  }
+
+  /** Fetch one Docker Deploy host by ID. */
+  async getHost(hostId: string): Promise<DockerDeployHostData> {
+    const res = await this.http.get<DockerDeployHostResponse>(
+      `/docker-deploy/hosts/${hostId}`,
+    );
+    return unwrapHost(res);
+  }
+
+  /** List Docker Deploy starter templates. */
+  async listTemplates(): Promise<DockerDeployTemplate[]> {
+    const res = await this.http.get<DockerDeployTemplateListResponse>(
+      "/docker-deploy/templates",
+    );
+    return unwrapTemplates(res);
+  }
+
+  /** Fetch one Docker Deploy starter template by ID. */
+  async getTemplate(templateId: string): Promise<DockerDeployTemplate> {
+    const res = await this.http.get<DockerDeployTemplateResponse>(
+      `/docker-deploy/templates/${encodeURIComponent(templateId)}`,
+    );
+    return unwrapTemplate(res);
+  }
+}