@miosa/sdk 1.2.1 → 1.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miosa/sdk",
-  "version": "1.2.1",
+  "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

@@ -122,6 +122,7 @@ export type {
   DeploymentData,
   DeploymentId,
   DeploymentListParams,
+  DeploymentProduct,
   DeploymentReleaseData,
   DeploymentReleaseId,
   DeploymentServiceData,
@@ -134,6 +135,11 @@ export type {
   DeploymentVersionId,
   DeploymentVersionKind,
   DeploymentVersionState,
+  DockerDeployCreateParams,
+  DockerDeployDoctorCheck,
+  DockerDeployDoctorParams,
+  DockerDeployDoctorProbe,
+  DockerDeployDoctorResult,
   ExternalAttribution,
   PublishFromSandboxParams,
   PublishParams,
@@ -145,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,
@@ -216,7 +233,7 @@ export type {
   HealthCheckCreateParams,
   HealthCheckUpdateParams,
 } from "./resources/health-checks.js";
-export { Webhooks } from "./resources/webhooks.js";
+export { verifySignature, Webhooks } from "./resources/webhooks.js";
 export type {
   WebhookId,
   WebhookDeliveryId,
@@ -285,7 +302,12 @@ export type {
 
 // P2 resources
 export { Tenant } from "./resources/tenant.js";
-export type { TenantPlan } from "./resources/tenant.js";
+export type {
+  BrandingData,
+  PreviewDomainData,
+  TenantBrandingUpdateParams,
+  TenantPlan,
+} from "./resources/tenant.js";
 export { Regions } from "./resources/regions.js";
 export type {
   RegionData,

package/src/resources/admin.ts

@@ -345,4 +345,15 @@ export class Admin {
       model_id: modelId,
     });
   }
+
+  /** POST /api/v1/admin/impersonate — returns {token, expires_at}. */
+  impersonate(
+    externalUserId: string,
+    options: { ttlSec?: number } = {},
+  ): Promise<{ token: string; expires_at: string }> {
+    return this.http.post("/admin/impersonate", {
+      external_user_id: externalUserId,
+      ttl_sec: options.ttlSec ?? 3600,
+    });
+  }
 }

package/src/resources/api-keys.ts

@@ -113,6 +113,22 @@ export class ApiKeys {
     return unwrap<ApiKeyCreateResult>(data);
   }
 
+  /** POST /api/v1/api-keys/scoped — L2 delegation token bound to one external user. */
+  async createScoped(params: {
+    externalUserId: string;
+    scopes: string[];
+    expiresAt?: string;
+  }): Promise<ApiKeyCreateResult> {
+    const body = stripUndefined({
+      external_user_id: params.externalUserId,
+      scopes: params.scopes,
+      expires_at: params.expiresAt,
+    });
+    return unwrap<ApiKeyCreateResult>(
+      await this.http.post<unknown>("/api-keys/scoped", body),
+    );
+  }
+
   async delete(keyId: string): Promise<void> {
     await this.http.delete<unknown>(`/api-keys/${keyId}`);
   }

package/src/resources/custom_domains.ts

@@ -41,7 +41,7 @@ export interface CustomDomainRegisterParams {
  * // 1. Register the domain
  * const domain = await computer.domains.register("app.example.com");
  * console.log(domain.instructions);
- * // => "Add a CNAME record: app.example.com → <slug>.sandbox.<tenant-domain>"
+ * // => "Add a CNAME record: app.example.com → <slug>.sandbox.miosa.ai"
  *
  * // 2. Add the CNAME in your DNS registrar, then...
  *

package/src/resources/deployments.test.ts

@@ -0,0 +1,121 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+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", () => {
+  it("createDockerDeploy() marks the deployment for Docker Deploy", async () => {
+    mockRequest.mockResolvedValue({
+      data: {
+        id: "dep_123",
+        tenant_id: "ten_123",
+        name: "Clinic Intake",
+        slug: "clinic-intake",
+        state: "pending",
+        deployment_product: "docker_deploy",
+        docker_deploy_host_id: "ddh_123",
+        metadata: { deployment_product: "docker_deploy", client: "clinic-iq" },
+      },
+    });
+
+    const deployment = await new Deployments(makeHttp()).createDockerDeploy({
+      name: "Clinic Intake",
+      repoUrl: "https://github.com/clinic-iq/intake",
+      externalWorkspaceId: "dr-smith",
+      externalProjectId: "lead-magnet",
+      metadata: { client: "clinic-iq" },
+      idempotencyKey: "idem-123",
+    });
+
+    expect(mockRequest).toHaveBeenCalledWith("/deployments", {
+      method: "POST",
+      body: {
+        name: "Clinic Intake",
+        repo_url: "https://github.com/clinic-iq/intake",
+        metadata: { client: "clinic-iq", deployment_product: "docker_deploy" },
+        external_workspace_id: "dr-smith",
+        external_project_id: "lead-magnet",
+      },
+      headers: { "Idempotency-Key": "idem-123" },
+    });
+    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 ─────────────────────────────────────────────────────────────
 
@@ -50,6 +51,8 @@ export type DeploymentVersionState =
 
 export type DeploymentSourceType = "repo" | "sandbox" | "upload";
 
+export type DeploymentProduct = "miosa_deploy" | "docker_deploy";
+
 export type DeploymentServiceType =
   | "static_web"
   | "web"
@@ -107,6 +110,8 @@ export interface DeploymentData {
   auto_deploy?: boolean;
   custom_domain_id?: string | null;
   linked_database_id?: string | null;
+  deployment_product?: DeploymentProduct | string | null;
+  docker_deploy_host_id?: string | null;
   metadata?: Record<string, unknown>;
   external_workspace_id?: string | null;
   external_user_id?: string | null;
@@ -116,10 +121,39 @@ 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
   | {
-      engine?: "postgresql" | "mysql" | "redis";
+      engine?: "postgresql" | "mysql" | "redis" | "qdrant";
       size?: "xs" | "small" | "medium" | "large";
       storage_mb?: number;
       region?: string;
@@ -281,6 +315,8 @@ export interface DeploymentCreateParams extends ExternalAttribution {
   idempotencyKey?: string;
 }
 
+export interface DockerDeployCreateParams extends DeploymentCreateParams {}
+
 export interface DeploymentUpdateParams {
   name?: string;
   branch?: string;
@@ -421,6 +457,52 @@ function stripUndefined(
   );
 }
 
+function dockerDeployMetadata(
+  metadata: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  return {
+    ...(metadata ?? {}),
+    deployment_product: "docker_deploy",
+  };
+}
+
+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 {
@@ -627,6 +709,154 @@ export class Deployments {
     return unwrap(data) as DeploymentData;
   }
 
+  /**
+   * Create a deployment that runs on the workspace's dedicated Docker Deploy
+   * runtime. It uses the same /deployments API as MIOSA Deploy, but marks the
+   * deployment so the control plane attaches it to the workspace Docker host.
+   */
+  async createDockerDeploy(
+    params: DockerDeployCreateParams,
+  ): Promise<DeploymentData> {
+    return this.create({
+      ...params,
+      metadata: dockerDeployMetadata(params.metadata),
+    });
+  }
+
+  /**
+   * 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");
+  });
+});