@miosa/sdk 1.2.2 → 1.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miosa/sdk",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "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,140 @@ 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 },
+              docker_deploy: {
+                app_id: "miosa-clinic-intake",
+                container_id: "container_123",
+                status: "running",
+                url: "http://127.0.0.1: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",
+      "docker_deploy_app",
+      "runtime_route",
+      "public_url_probe",
+    ]);
+  });
+
+  it("doctorDockerDeploy fails when route metadata does not point at the Docker container port", 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: 8080 },
+              docker_deploy: {
+                app_id: "miosa-clinic-intake",
+                container_id: "container_123",
+                status: "running",
+                url: "http://127.0.0.1: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(false);
+    expect(result.checks).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          name: "runtime_route",
+          ok: false,
+          message:
+            "Deployment route port 8080 does not match Docker container host port 23906.",
+        }),
+      ]),
+    );
+  });
 });

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,62 @@ 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 dockerDeployApp(deployment: DeploymentData): Record<string, unknown> | null {
+  const app = deployment.metadata?.["docker_deploy"];
+  if (!app || typeof app !== "object" || Array.isArray(app)) return null;
+  return app as Record<string, unknown>;
+}
+
+function dockerDeployAppPort(app: Record<string, unknown> | null): number | null {
+  const url = app?.["url"];
+  if (typeof url !== "string") return null;
+
+  try {
+    const parsed = new URL(url);
+    const port = Number.parseInt(parsed.port, 10);
+    return Number.isInteger(port) ? port : null;
+  } catch {
+    return 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 +742,174 @@ 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 app = dockerDeployApp(deployment);
+    const appPort = dockerDeployAppPort(app);
+    const appRunning = app?.["status"] === "running" && appPort !== null;
+    addDoctorCheck(
+      checks,
+      "docker_deploy_app",
+      appRunning,
+      appRunning
+        ? "Docker Deploy app metadata points at a running container."
+        : "Deployment is missing running Docker Deploy app metadata.",
+      app
+        ? {
+            app_id: app["app_id"],
+            container_id: app["container_id"],
+            status: app["status"],
+            url: app["url"],
+            expected_port: appPort,
+          }
+        : undefined,
+    );
+
+    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";
+    const runtimeRecord =
+      hasRuntimeRoute && typeof runtime === "object"
+        ? (runtime as Record<string, unknown>)
+        : undefined;
+    const routeMatchesContainerPort =
+      hasRuntimeRoute &&
+      (appPort === null || runtimeRecord?.["port"] === appPort);
+    addDoctorCheck(
+      checks,
+      "runtime_route",
+      hasRuntimeRoute && routeMatchesContainerPort,
+      hasRuntimeRoute && routeMatchesContainerPort
+        ? "Deployment route points at the Docker container host port."
+        : hasRuntimeRoute && appPort !== null
+          ? `Deployment route port ${String(runtimeRecord?.["port"])} does not match Docker container host port ${appPort}.`
+        : "Deployment is missing appliance runtime route metadata.",
+      runtimeRecord
+        ? {
+            ...runtimeRecord,
+            expected_port: appPort,
+            docker_deploy_url: app?.["url"],
+          }
+        : 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");
+  });
+});