@miosa/sdk 1.2.3 → 1.2.5

package/src/resources/deployments.ts

@@ -13,7 +13,6 @@
 import { randomUUID } from "node:crypto";
 
 import type { HttpClient } from "../http.js";
-import type { DockerDeployHostData } from "./docker-deploy.js";
 
 // ── Branded IDs ─────────────────────────────────────────────────────────────
 
@@ -121,35 +120,6 @@ 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
   | {
@@ -311,12 +281,118 @@ export interface DeploymentCreateParams extends ExternalAttribution {
   auto_deploy?: boolean;
   autoDeploy?: boolean;
   database?: DeploymentDatabaseRequest;
+  docker_deploy_template_id?: string;
+  dockerDeployTemplateId?: string;
   metadata?: Record<string, unknown>;
   idempotencyKey?: string;
 }
 
 export interface DockerDeployCreateParams extends DeploymentCreateParams {}
 
+export interface DockerDeployHostData {
+  id: string;
+  tenant_id?: string;
+  workspace_id?: string | null;
+  computer_id?: string | null;
+  fleet_node_id?: string | null;
+  runtime_base_url?: string | null;
+  status?: string;
+  appliance_status?: string | null;
+  appliance_version?: string | null;
+  appliance_image?: string | null;
+  agent_configured?: boolean;
+  last_health_check_at?: string | null;
+  created_at?: string;
+  updated_at?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface DockerDeployHostListParams {
+  workspace_id?: string;
+  workspaceId?: string;
+}
+
+export interface DockerDeployHostEnsureParams {
+  workspace_id: string;
+  workspaceId?: string;
+  region?: string;
+  size?: string;
+  appliance_image?: string;
+  applianceImage?: string;
+  metadata?: Record<string, unknown>;
+  idempotencyKey?: string;
+}
+
+export interface DockerDeployTemplateData {
+  id: string;
+  name: string;
+  summary?: string;
+  description?: string;
+  category?: string;
+  runtime?: string;
+  framework?: string;
+  build_command?: string | null;
+  run_command?: string | null;
+  ports?: number[];
+  env?: Record<string, string>;
+  files?: Record<string, string>;
+  design_md?: string | null;
+  design_source_url?: string | null;
+  design_sources?: string[];
+  design_reference_presets?: DockerDeployDesignReferencePreset[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface DockerDeployDesignReferencePreset {
+  id: string;
+  name: string;
+  summary: string;
+  best_for?: string[];
+}
+
+export interface DockerDeployTemplateListParams {
+  category?: string;
+  runtime?: string;
+  framework?: string;
+  includePreview?: boolean;
+  include_preview?: boolean;
+}
+
+export interface DockerDeployDoctorParams {
+  /** Probe the deployment public URL after checking control-plane metadata. Default: true. */
+  probe?: boolean;
+  /** Path to request on the public URL. Default: "/". */
+  probePath?: string;
+  /** Public URL probe timeout in milliseconds. Default: 20_000. */
+  timeoutMs?: number;
+  /** Test hook or custom runtime fetch implementation. */
+  fetchImpl?: typeof fetch;
+}
+
+export interface DockerDeployDoctorCheck {
+  name: string;
+  ok: boolean;
+  message: string;
+  data?: Record<string, unknown>;
+}
+
+export interface DockerDeployDoctorProbe {
+  url: string;
+  status: number | null;
+  ok: boolean;
+  responseSnippet: string;
+  gatewayJson?: boolean;
+}
+
+export interface DockerDeployDoctorResult {
+  ok: boolean;
+  deployment: DeploymentData;
+  host?: DockerDeployHostData;
+  publicUrl?: string | null;
+  checks: DockerDeployDoctorCheck[];
+  probe?: DockerDeployDoctorProbe;
+}
+
 export interface DeploymentUpdateParams {
   name?: string;
   branch?: string;
@@ -363,6 +439,10 @@ export interface PublishParams extends ExternalAttribution {
   healthCheckPath?: string;
   /** @deprecated Reserved for dynamic runtime publish. */
   health_check_path?: string;
+  deploymentType?: DeploymentProduct | string;
+  deployment_type?: DeploymentProduct | string;
+  dockerDeployTemplateId?: string;
+  docker_deploy_template_id?: string;
   /** @deprecated Reserved for managed data-service binding. */
   dataServices?: string[];
   /** @deprecated Reserved for managed data-service binding. */
@@ -459,26 +539,49 @@ function stripUndefined(
 
 function dockerDeployMetadata(
   metadata: Record<string, unknown> | undefined,
+  templateId?: string,
 ): Record<string, unknown> {
-  return {
+  return stripUndefined({
     ...(metadata ?? {}),
     deployment_product: "docker_deploy",
-  };
+    docker_deploy_template_id: templateId,
+  });
 }
 
-function dockerDeployProduct(deployment: DeploymentData): unknown {
-  return (
-    deployment.deployment_product ??
-    deployment.metadata?.["deployment_product"]
-  );
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
-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 stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function runtimeMetadata(
+  metadata: Record<string, unknown>,
+): Record<string, unknown> | undefined {
+  const runtime = metadata.runtime;
+  return isRecord(runtime) ? runtime : undefined;
+}
+
+function publicProbeUrl(publicUrl: string, probePath: string): string {
+  const url = new URL(publicUrl);
+  const normalizedPath = probePath.startsWith("/") ? probePath : `/${probePath}`;
+  url.pathname = normalizedPath;
+  return url.toString();
+}
+
+function looksLikeMiosaGatewayJson(body: string): boolean {
+  try {
+    const parsed = JSON.parse(body) as unknown;
+    return (
+      isRecord(parsed) &&
+      parsed.ok === true &&
+      typeof parsed.run_id === "string" &&
+      Object.keys(parsed).every((key) => ["ok", "run_id"].includes(key))
+    );
+  } catch {
+    return false;
+  }
 }
 
 function addDoctorCheck(
@@ -486,21 +589,11 @@ function addDoctorCheck(
   name: string,
   ok: boolean,
   message: string,
-  details?: Record<string, unknown>,
+  data?: 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();
+  const check: DockerDeployDoctorCheck = { name, ok, message };
+  if (data !== undefined) check.data = data;
+  checks.push(check);
 }
 
 // ── Sub-resources ──────────────────────────────────────────────────────────
@@ -698,6 +791,8 @@ export class Deployments {
       run_command: params.runCommand ?? params.run_command,
       auto_deploy: params.autoDeploy ?? params.auto_deploy,
       database: params.database,
+      docker_deploy_template_id:
+        params.dockerDeployTemplateId ?? params.docker_deploy_template_id,
       metadata: params.metadata,
       ...attributionBody(params),
     });
@@ -717,16 +812,55 @@ export class Deployments {
   async createDockerDeploy(
     params: DockerDeployCreateParams,
   ): Promise<DeploymentData> {
+    const templateId =
+      params.dockerDeployTemplateId ?? params.docker_deploy_template_id;
     return this.create({
       ...params,
-      metadata: dockerDeployMetadata(params.metadata),
+      metadata: dockerDeployMetadata(params.metadata, templateId),
     });
   }
 
+  async listDockerDeployHosts(
+    params: DockerDeployHostListParams = {},
+  ): Promise<DockerDeployHostData[]> {
+    const data = await this.http.get<unknown>(
+      "/docker-deploy/hosts",
+      stripUndefined({
+        workspace_id: params.workspaceId ?? params.workspace_id,
+      }) as Record<string, string | number | boolean | undefined>,
+    );
+    return listItems<DockerDeployHostData>(data, ["hosts", "items"]);
+  }
+
+  async ensureDockerDeployHost(
+    params: DockerDeployHostEnsureParams,
+  ): Promise<DockerDeployHostData> {
+    const data = await this.http.request<unknown>("/docker-deploy/hosts/ensure", {
+      method: "POST",
+      body: stripUndefined({
+        workspace_id: params.workspaceId ?? params.workspace_id,
+        region: params.region,
+        size: params.size,
+        appliance_image: params.applianceImage ?? params.appliance_image,
+        metadata: params.metadata,
+      }),
+      headers: { "Idempotency-Key": idempotencyKey(params.idempotencyKey) },
+    });
+    return unwrap(data) as DockerDeployHostData;
+  }
+
+  async getDockerDeployHost(hostId: string): Promise<DockerDeployHostData> {
+    const data = await this.http.get<unknown>(`/docker-deploy/hosts/${hostId}`);
+    return unwrap(data) as DockerDeployHostData;
+  }
+
   /**
-   * 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.
+   * Verify a Docker Deploy deployment end-to-end.
+   *
+   * This checks the deployment product marker, Docker Deploy host linkage,
+   * appliance health, route runtime metadata, and optionally the public URL.
+   * It is intentionally agent-friendly: use this after sandbox.deployDocker()
+   * or createDockerDeploy() before telling a user the app is live.
    */
   async doctorDockerDeploy(
     deploymentId: string,
@@ -734,127 +868,176 @@ export class Deployments {
   ): Promise<DockerDeployDoctorResult> {
     const checks: DockerDeployDoctorCheck[] = [];
     const deployment = await this.get(deploymentId);
-    const metadata = deployment.metadata ?? {};
-    const product = dockerDeployProduct(deployment);
-    const hostId = dockerDeployHostId(deployment);
+    const metadata = isRecord(deployment.metadata) ? deployment.metadata : {};
+    const product =
+      stringValue(deployment.deployment_product) ??
+      stringValue(metadata.deployment_product);
+    const hostId =
+      stringValue(deployment.docker_deploy_host_id) ??
+      stringValue(metadata.docker_deploy_host_id);
 
     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 },
+        ? "Deployment is marked as Docker Deploy."
+        : `Expected deployment_product=docker_deploy, got ${product ?? "missing"}.`,
+      { product: product ?? null },
     );
 
     addDoctorCheck(
       checks,
       "docker_deploy_host_id",
-      Boolean(hostId),
+      !!hostId,
       hostId
-        ? "Deployment has a Docker Deploy host id."
+        ? "Deployment is linked to a Docker Deploy appliance host."
         : "Deployment has no docker_deploy_host_id.",
-      { docker_deploy_host_id: hostId },
+      { docker_deploy_host_id: hostId ?? null },
     );
 
     let host: DockerDeployHostData | undefined;
     if (hostId) {
       try {
-        const rawHost = await this.http.get<unknown>(
-          `/docker-deploy/hosts/${hostId}`,
-        );
-        host = unwrap(rawHost) as DockerDeployHostData;
+        host = await this.getDockerDeployHost(hostId);
+        const status = host.status ?? null;
+        const applianceStatus = host.appliance_status ?? null;
+        const badHostStates = new Set(["failed", "error", "destroyed"]);
+        const badApplianceStates = new Set(["failed", "error", "unhealthy"]);
+        const ok =
+          !badHostStates.has(String(status)) &&
+          !badApplianceStates.has(String(applianceStatus));
         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,
-          },
+          ok,
+          ok
+            ? "Docker Deploy host is not reporting a failed state."
+            : `Docker Deploy host is unhealthy: status=${status}, appliance_status=${applianceStatus}.`,
+          { status, appliance_status: applianceStatus },
         );
-      } catch (error) {
+      } catch (err) {
         addDoctorCheck(
           checks,
           "docker_deploy_host_health",
           false,
-          error instanceof Error ? error.message : String(error),
+          `Could not fetch Docker Deploy host ${hostId}: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
         );
       }
     }
 
-    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 runtime = runtimeMetadata(metadata);
+    const runtimeIp = runtime
+      ? stringValue(runtime.ip) ?? stringValue(runtime.ip_address)
+      : undefined;
+    const runtimePort = runtime?.port;
+    addDoctorCheck(
+      checks,
+      "route_runtime",
+      !!runtimeIp && runtimePort !== undefined && runtimePort !== null,
+      runtimeIp && runtimePort !== undefined && runtimePort !== null
+        ? "Deployment route metadata points at a runtime target."
+        : "Deployment metadata has no runtime ip/port target.",
+      { ip: runtimeIp ?? null, port: runtimePort ?? null },
+    );
+
+    const publicUrl =
+      stringValue(deployment.public_url) ?? stringValue(metadata.public_url);
     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,
+      "public_url",
+      !!publicUrl,
+      publicUrl
+        ? "Deployment has a public URL."
+        : "Deployment has no public URL to probe.",
+      { public_url: publicUrl ?? null },
     );
 
     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);
+    if (params.probe !== false && publicUrl) {
+      const fetchImpl = params.fetchImpl ?? fetch;
+      const url = publicProbeUrl(publicUrl, params.probePath ?? "/");
       const controller = new AbortController();
-      const timeout = setTimeout(
-        () => controller.abort(),
-        params.timeoutMs ?? params.timeout_ms ?? 10_000,
-      );
+      const timer = setTimeout(() => controller.abort(), params.timeoutMs ?? 20_000);
       try {
-        const response = await fetch(url, {
-          method: "GET",
+        const response = await fetchImpl(url, {
+          headers: { Accept: "*/*" },
           signal: controller.signal,
         });
-        probe = { url, ok: response.ok, status: response.status };
+        const text = await response.text();
+        const gatewayJson = looksLikeMiosaGatewayJson(text);
+        const ok = response.ok && !gatewayJson;
+        probe = {
+          url,
+          status: response.status,
+          ok,
+          responseSnippet: text.slice(0, 500),
+        };
+        if (gatewayJson) probe.gatewayJson = true;
         addDoctorCheck(
           checks,
           "public_url_probe",
-          response.ok,
-          response.ok
+          ok,
+          ok
             ? `Public URL returned HTTP ${response.status}.`
-            : `Public URL returned HTTP ${response.status}.`,
-          { url, status: response.status },
+            : gatewayJson
+              ? "Public URL returned MIOSA gateway JSON instead of the app."
+              : `Public URL returned HTTP ${response.status}.`,
+          { status: response.status, gateway_json: gatewayJson },
         );
-      } catch (error) {
-        probe = {
-          url,
-          ok: false,
-          error: error instanceof Error ? error.message : String(error),
-        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        probe = { url, status: null, ok: false, responseSnippet: message };
         addDoctorCheck(
           checks,
           "public_url_probe",
           false,
-          probe.error ?? "Public URL probe failed.",
-          { url },
+          `Public URL probe failed: ${message}`,
         );
       } finally {
-        clearTimeout(timeout);
+        clearTimeout(timer);
       }
     }
 
-    return {
+    const result: DockerDeployDoctorResult = {
       ok: checks.every((check) => check.ok),
       deployment,
-      ...(host ? { host } : {}),
       checks,
-      ...(probe ? { probe } : {}),
     };
+    if (host) result.host = host;
+    if (publicUrl !== undefined) result.publicUrl = publicUrl;
+    if (probe) result.probe = probe;
+    return result;
+  }
+
+  async listDockerDeployTemplates(
+    params: DockerDeployTemplateListParams = {},
+  ): Promise<DockerDeployTemplateData[]> {
+    const query: Record<string, string | number | boolean | undefined> = {
+      category: params.category,
+      runtime: params.runtime,
+      framework: params.framework,
+      include_preview: params.includePreview ?? params.include_preview,
+    };
+    const data = await this.http.get<unknown>(
+      "/docker-deploy/templates",
+      stripUndefined(query) as Record<string, string | number | boolean | undefined>,
+    );
+    const templates = unwrap<any>(data);
+    if (Array.isArray(templates)) return templates as DockerDeployTemplateData[];
+    return ((templates?.templates ?? templates?.items ?? templates?.data ?? []) ||
+      []) as DockerDeployTemplateData[];
+  }
+
+  async getDockerDeployTemplate(
+    templateId: string,
+  ): Promise<DockerDeployTemplateData> {
+    const data = await this.http.get<unknown>(
+      `/docker-deploy/templates/${templateId}`,
+    );
+    return unwrap(data) as DockerDeployTemplateData;
   }
 
   async update(
@@ -888,6 +1071,15 @@ export class Deployments {
       output_path: params.outputPath ?? params.output_path,
       entrypoint: params.entrypoint,
       promote: params.promote,
+      build_command: params.buildCommand ?? params.build_command,
+      run_command: params.runCommand ?? params.run_command,
+      port: params.port,
+      health_check_path: params.healthCheckPath ?? params.health_check_path,
+      deployment_type: params.deploymentType ?? params.deployment_type,
+      docker_deploy_template_id:
+        params.dockerDeployTemplateId ?? params.docker_deploy_template_id,
+      data_services: params.dataServices ?? params.data_services,
+      ...attributionBody(params),
     });
     const data = await this.http.request<unknown>(
       `/deployments/${deploymentId}/publish`,
@@ -918,6 +1110,15 @@ export class Deployments {
       entrypoint: params.entrypoint,
       domain: params.domain,
       custom_domain: params.customDomain ?? params.custom_domain,
+      build_command: params.buildCommand ?? params.build_command,
+      run_command: params.runCommand ?? params.run_command,
+      port: params.port,
+      health_check_path: params.healthCheckPath ?? params.health_check_path,
+      deployment_type: params.deploymentType ?? params.deployment_type,
+      docker_deploy_template_id:
+        params.dockerDeployTemplateId ?? params.docker_deploy_template_id,
+      data_services: params.dataServices ?? params.data_services,
+      ...attributionBody(params),
     });
     const data = await this.http.request<unknown>(
       `/sandboxes/${sandboxId}/deploy`,

package/src/resources/devices.test.ts

@@ -0,0 +1,92 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { HttpClient } from "../http.js";
+import { Devices } from "./devices.js";
+
+const mockGet = vi.fn();
+
+function makeHttp(): HttpClient {
+  const http = {} as HttpClient;
+  http.get = mockGet;
+  return http;
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("Devices", () => {
+  it("returns the static agent device catalog", () => {
+    const catalog = new Devices(makeHttp()).catalog();
+
+    expect(catalog.map((device) => device.kind)).toEqual(
+      expect.arrayContaining([
+        "sandbox_worker",
+        "computer",
+        "local_device",
+        "docker_deploy_host",
+      ]),
+    );
+    expect(catalog.find((device) => device.kind === "sandbox_worker")
+      ?.primaryCommands).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("sandboxes.create"),
+        expect.stringContaining("sandbox.exec"),
+      ]),
+    );
+  });
+
+  it("normalizes sandboxes and computers into one device list", async () => {
+    mockGet
+      .mockResolvedValueOnce({
+        data: [
+          {
+            id: "sbx_123",
+            name: "builder",
+            state: "running",
+            ready: true,
+            persistent: true,
+            preview_url: "https://3000-sbx_123.sandbox.miosa.app",
+          },
+        ],
+      })
+      .mockResolvedValueOnce({
+        data: [
+          {
+            id: "cmp_123",
+            name: "desktop",
+            status: "running",
+            region: "us-nyc",
+          },
+        ],
+      });
+
+    const result = await new Devices(makeHttp()).list();
+
+    expect(mockGet).toHaveBeenNthCalledWith(1, "/sandboxes");
+    expect(mockGet).toHaveBeenNthCalledWith(2, "/computers");
+    expect(result.errors).toEqual([]);
+    expect(result.devices).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ id: "sbx_123", kind: "sandbox_worker" }),
+        expect.objectContaining({ id: "cmp_123", kind: "computer" }),
+      ]),
+    );
+  });
+
+  it("returns partial device inventory when one backing endpoint fails", async () => {
+    mockGet
+      .mockResolvedValueOnce({
+        data: [{ id: "sbx_123", state: "running" }],
+      })
+      .mockRejectedValueOnce(new Error("HTTP 502"));
+
+    const result = await new Devices(makeHttp()).list();
+
+    expect(result.devices).toEqual([
+      expect.objectContaining({ id: "sbx_123", kind: "sandbox_worker" }),
+    ]);
+    expect(result.errors).toEqual([
+      expect.objectContaining({ source: "computers", retryable: true }),
+    ]);
+  });
+});