@miosa/sdk 1.2.4 → 1.2.5

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 }),
+    ]);
+  });
+});

package/src/resources/devices.ts

@@ -0,0 +1,291 @@
+import { HttpClient } from "../http.js";
+
+export type DeviceKind =
+  | "sandbox_worker"
+  | "computer"
+  | "local_device"
+  | "docker_deploy_host";
+
+export type DeviceSource = "sandboxes" | "computers";
+
+export interface DeviceCatalogEntry {
+  kind: DeviceKind;
+  label: string;
+  purpose: string;
+  lifecycle: string;
+  persistence: string;
+  primaryCommands: string[];
+  useWhen: string[];
+  avoidWhen: string[];
+}
+
+export interface DeviceRecord {
+  id: string;
+  kind: DeviceKind;
+  source: DeviceSource;
+  name?: string;
+  state?: string;
+  ready?: boolean;
+  persistent?: boolean;
+  alwaysOn?: boolean;
+  region?: string;
+  template?: string;
+  previewUrl?: string;
+  timeoutRemainingMs?: number;
+}
+
+export interface DeviceListError {
+  source: DeviceSource;
+  message: string;
+  retryable: boolean;
+}
+
+export interface DeviceListParams {
+  kind?: "all" | "sandbox_worker" | "sandbox" | "computer";
+}
+
+export interface DeviceListResponse {
+  devices: DeviceRecord[];
+  errors: DeviceListError[];
+}
+
+const DEVICE_CATALOG: DeviceCatalogEntry[] = [
+  {
+    kind: "sandbox_worker",
+    label: "Sandbox Worker",
+    purpose:
+      "Isolated Linux workspace for agents to create files, run code, preview apps, snapshot, fork, and publish.",
+    lifecycle:
+      "Persistent by default; use stop/resume/snapshot/fork where the account backend supports saved state.",
+    persistence:
+      "Use one-hour timeouts for interactive builds and checkpoint before long pauses.",
+    primaryCommands: [
+      "miosa.sandboxes.create({ templateId: 'nextjs', timeoutSec: 3600 })",
+      "sandbox.exec.run('codex ...', { cwd: '/workspace' })",
+      "sandbox.files.write('/workspace/app/page.jsx', source)",
+      "miosa.deployments.publishFromSandbox(...)",
+    ],
+    useWhen: [
+      "Coding agents should build inside the remote filesystem.",
+      "You need command execution, file writes, package installs, previews, artifacts, or app publish.",
+      "You want virtual-device behavior without a GUI desktop.",
+    ],
+    avoidWhen: [
+      "The workflow requires full browser/desktop control.",
+      "The app is ready for production; publish it to a deployment runtime.",
+    ],
+  },
+  {
+    kind: "computer",
+    label: "Computer",
+    purpose:
+      "Durable VM/desktop device for browser automation, CUA sessions, SSH, tunnels, and persistent agent control.",
+    lifecycle:
+      "Managed as a Computer with desktop/browser and operator-style control surfaces.",
+    persistence:
+      "Use checkpoints, volumes, tunnels, and agent sessions for long-lived desktop workflows.",
+    primaryCommands: [
+      "miosa.computers.create({ name: 'browser-agent' })",
+      "computer.exec.run('npm test')",
+      "computer.desktop.open()",
+    ],
+    useWhen: [
+      "The agent needs Chromium or a full desktop.",
+      "The workflow logs into dashboards, fills forms, clicks buttons, or captures screenshots.",
+      "A human and agent share the same persistent machine state.",
+    ],
+    avoidWhen: [
+      "Simple code generation/build/test work fits a cheaper sandbox worker.",
+      "You only need durable app hosting.",
+    ],
+  },
+  {
+    kind: "local_device",
+    label: "Local Device",
+    purpose:
+      "Developer-owned machine connected through CLI/MCP for local discovery and private tooling.",
+    lifecycle: "Not hosted by MIOSA; the user owns uptime and state.",
+    persistence:
+      "State is local machine state. Do not assume cloud resume semantics.",
+    primaryCommands: ["miosa mcp install", "miosa doctor --json"],
+    useWhen: [
+      "The agent needs local repository discovery before cloud execution.",
+      "The user intentionally wants local private tools.",
+    ],
+    avoidWhen: [
+      "Customer code must stay isolated in MIOSA-hosted infrastructure.",
+      "The workflow needs reproducible shared cloud state.",
+    ],
+  },
+  {
+    kind: "docker_deploy_host",
+    label: "Docker Deploy Host",
+    purpose:
+      "Workspace appliance VM that runs Docker containers for durable apps published from sandboxes.",
+    lifecycle:
+      "Always-on deployment capacity; not an interactive coding workspace.",
+    persistence:
+      "Versioned releases and routing are durable; edits happen in sandboxes before publish.",
+    primaryCommands: [
+      "miosa sandbox publish <id> --docker-deploy",
+      "miosa deploy --docker-deploy",
+    ],
+    useWhen: [
+      "You need many small apps, APIs, funnels, or client sites in one workspace appliance.",
+      "You want stable public URLs backed by Docker containers.",
+    ],
+    avoidWhen: [
+      "Interactive agent work is still happening.",
+      "The app needs the standard MIOSA Deploy runtime.",
+    ],
+  },
+];
+
+export class Devices {
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
+
+  /**
+   * Return the static device catalog used by orchestration apps to choose the
+   * right MIOSA execution surface before creating resources.
+   */
+  catalog(): DeviceCatalogEntry[] {
+    return DEVICE_CATALOG.map((entry) => ({ ...entry }));
+  }
+
+  /**
+   * List hosted devices by normalizing existing sandboxes and computers.
+   * Partial backend failures are returned in `errors` so orchestration UIs can
+   * still show usable inventory instead of failing the whole page.
+   */
+  async list(params: DeviceListParams = {}): Promise<DeviceListResponse> {
+    const kind = normalizeKind(params.kind ?? "all");
+    const devices: DeviceRecord[] = [];
+    const errors: DeviceListError[] = [];
+
+    if (kind === "all" || kind === "sandbox_worker") {
+      try {
+        const sandboxes = await this.http.get<unknown>("/sandboxes");
+        devices.push(...unwrapList(sandboxes, ["sandboxes"]).map(normalizeSandbox));
+      } catch (err) {
+        errors.push(toListError("sandboxes", err));
+      }
+    }
+
+    if (kind === "all" || kind === "computer") {
+      try {
+        const computers = await this.http.get<unknown>("/computers");
+        devices.push(...unwrapList(computers, ["computers"]).map(normalizeComputer));
+      } catch (err) {
+        errors.push(toListError("computers", err));
+      }
+    }
+
+    return { devices, errors };
+  }
+}
+
+function normalizeKind(
+  kind: NonNullable<DeviceListParams["kind"]>,
+): "all" | "sandbox_worker" | "computer" {
+  if (kind === "all") return "all";
+  if (kind === "sandbox" || kind === "sandbox_worker") {
+    return "sandbox_worker";
+  }
+  if (kind === "computer") return "computer";
+  throw new Error(`Unsupported device kind: ${kind}`);
+}
+
+function normalizeSandbox(row: Record<string, unknown>): DeviceRecord {
+  return compactRecord({
+    id: stringField(row, "id"),
+    kind: "sandbox_worker",
+    source: "sandboxes",
+    name: optionalString(row, "name"),
+    state: optionalString(row, "state") ?? optionalString(row, "status"),
+    ready: optionalBoolean(row, "ready"),
+    persistent: optionalBoolean(row, "persistent"),
+    alwaysOn: optionalBoolean(row, "always_on"),
+    template:
+      optionalString(row, "template_id") ?? optionalString(row, "template"),
+    previewUrl: optionalString(row, "preview_url"),
+    timeoutRemainingMs: optionalNumber(row, "timeout_remaining_ms"),
+  });
+}
+
+function normalizeComputer(row: Record<string, unknown>): DeviceRecord {
+  return compactRecord({
+    id: stringField(row, "id"),
+    kind: "computer",
+    source: "computers",
+    name: optionalString(row, "name"),
+    state: optionalString(row, "status") ?? optionalString(row, "state"),
+    ready: optionalBoolean(row, "ready"),
+    region: optionalString(row, "region"),
+    template:
+      optionalString(row, "template_type") ?? optionalString(row, "template"),
+  });
+}
+
+function compactRecord(record: Record<string, unknown>): DeviceRecord {
+  return Object.fromEntries(
+    Object.entries(record).filter(([, value]) => value !== undefined),
+  ) as unknown as DeviceRecord;
+}
+
+function unwrapList(payload: unknown, keys: string[]): Record<string, unknown>[] {
+  const value = isRecord(payload) && "data" in payload ? payload.data : payload;
+  if (Array.isArray(value)) return value.filter(isRecord);
+  if (isRecord(value)) {
+    for (const key of keys) {
+      const nested = value[key];
+      if (Array.isArray(nested)) return nested.filter(isRecord);
+    }
+  }
+  return [];
+}
+
+function toListError(source: DeviceSource, err: unknown): DeviceListError {
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    source,
+    message,
+    retryable: /fetch failed|ECONNRESET|HTTP 502|other side closed|socket hang up|bad gateway/i.test(
+      message,
+    ),
+  };
+}
+
+function stringField(row: Record<string, unknown>, key: string): string {
+  const value = row[key];
+  return typeof value === "string" ? value : String(value ?? "");
+}
+
+function optionalString(
+  row: Record<string, unknown>,
+  key: string,
+): string | undefined {
+  const value = row[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function optionalBoolean(
+  row: Record<string, unknown>,
+  key: string,
+): boolean | undefined {
+  return typeof row[key] === "boolean" ? row[key] : undefined;
+}
+
+function optionalNumber(
+  row: Record<string, unknown>,
+  key: string,
+): number | undefined {
+  return typeof row[key] === "number" ? row[key] : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/resources/sandboxes.test.ts

@@ -437,6 +437,7 @@ describe("Sandbox handle", () => {
     const deployment = await sandbox.deployDocker({
       name: "docker-site",
       port: 3000,
+      dockerDeployTemplateId: "nextjs-refero-design-pack",
     });
 
     expect(mockRequest).toHaveBeenCalledWith("/sandboxes/sbx_123/deploy", {
@@ -445,6 +446,7 @@ describe("Sandbox handle", () => {
         name: "docker-site",
         port: 3000,
         deployment_type: "docker_deploy",
+        docker_deploy_template_id: "nextjs-refero-design-pack",
       },
     });
     expect(deployment.deployment_product).toBe("docker_deploy");

package/src/resources/sandboxes.ts

@@ -329,6 +329,8 @@ export interface SandboxDeployParams {
   health_check_path?: string;
   deploymentType?: "miosa_deploy" | "docker_deploy" | "docker-deploy" | string;
   deployment_type?: "miosa_deploy" | "docker_deploy" | "docker-deploy" | string;
+  dockerDeployTemplateId?: string;
+  docker_deploy_template_id?: string;
   type?: "static" | "dynamic" | "server" | string;
   mode?: "static" | "dynamic" | "server" | string;
   database?: boolean | Record<string, unknown>;
@@ -1113,6 +1115,8 @@ export class Sandbox {
         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,
         type: params.type,
         mode: params.mode,
         database: params.database,

package/src/resources/tenant.ts

@@ -9,140 +9,58 @@ import type { HttpClient } from "../http.js";
 export interface TenantPlan {
   id?: string;
   name?: string;
+  preview_domain?: string | null;
+  deployment_domain?: string | null;
+  fallback_miosa_domain?: string | null;
   limits?: Record<string, unknown>;
   usage?: Record<string, unknown>;
   [key: string]: unknown;
 }
 
+export interface BrandingData {
+  logo_url?: string | null;
+  primary_color?: string | null;
+  wordmark?: string | null;
+  favicon_url?: string | null;
+  [key: string]: unknown;
+}
+
 export interface PreviewDomainData {
   preview_domain?: string | null;
-  default_domain?: string;
+  deployment_domain?: string | null;
+  fallback_miosa_domain?: string | null;
   status?: string;
-  dns_status?: string;
-  cname_target?: string | null;
-  dns_instructions?: unknown;
   [key: string]: unknown;
 }
 
 export interface TenantBrandingUpdateParams {
-  product_name?: string;
-  logo_url?: string;
-  support_url?: string;
-  support_email?: string;
-  primary_color?: string;
-  background_color?: string;
+  logo_url?: string | null;
+  primary_color?: string | null;
+  wordmark?: string | null;
+  favicon_url?: string | null;
   [key: string]: unknown;
 }
 
-export type BrandingData = TenantBrandingUpdateParams;
-
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
 function unwrap<T>(payload: unknown): T {
   if (payload && typeof payload === "object") {
     const p = payload as Record<string, unknown>;
-    for (const k of ["data", "tenant", "branding", "items"]) {
+    for (const k of ["data", "tenant", "items"]) {
       if (k in p) return p[k] as T;
     }
   }
   return payload as T;
 }
 
-// ── Sub-resources ────────────────────────────────────────────────────────────
-
-class PreviewDomain {
-  constructor(private readonly http: HttpClient) {}
-
-  /** Get the tenant's white-label preview domain settings. */
-  async get(): Promise<PreviewDomainData> {
-    const data = await this.http.get<unknown>("/tenant/preview-domain");
-    return unwrap<PreviewDomainData>(data);
-  }
-
-  /** Set the tenant's white-label preview domain. */
-  async set(domain: string): Promise<PreviewDomainData> {
-    const data = await this.http.put<unknown>("/tenant/preview-domain", {
-      preview_domain: domain,
-    });
-    return unwrap<PreviewDomainData>(data);
-  }
-
-  /** Re-run DNS verification for the configured preview domain. */
-  async verify(): Promise<PreviewDomainData> {
-    const data = await this.http.post<unknown>(
-      "/tenant/preview-domain/verify",
-      {},
-    );
-    return unwrap<PreviewDomainData>(data);
-  }
-
-  /** Remove the tenant's custom preview domain. */
-  async delete(): Promise<void> {
-    await this.http.delete<unknown>("/tenant/preview-domain");
-  }
-}
-
-class Branding {
-  constructor(private readonly http: HttpClient) {}
-
-  /** Get tenant branding used by white-label hosted surfaces. */
-  async get(): Promise<BrandingData> {
-    const data = await this.http.get<unknown>("/tenant/branding");
-    return unwrap<BrandingData>(data);
-  }
-
-  /** Update tenant branding used by white-label hosted surfaces. */
-  async set(params: TenantBrandingUpdateParams): Promise<BrandingData> {
-    const body = Object.fromEntries(
-      Object.entries(params).filter(([, v]) => v !== undefined),
-    );
-    const data = await this.http.put<unknown>("/tenant/branding", {
-      branding: body,
-    });
-    return unwrap<BrandingData>(data);
-  }
-
-  /** Reset tenant branding to platform defaults. */
-  async delete(): Promise<void> {
-    await this.http.delete<unknown>("/tenant/branding");
-  }
-}
-
 // ── Main resource ─────────────────────────────────────────────────────────────
 
 export class Tenant {
-  private readonly http: HttpClient;
-  readonly preview_domain: PreviewDomain;
-  readonly branding: Branding;
-
-  /** camelCase alias for SDK consumers that avoid snake_case properties. */
-  readonly previewDomain: PreviewDomain;
-
-  constructor(http: HttpClient) {
-    this.http = http;
-    this.preview_domain = new PreviewDomain(http);
-    this.previewDomain = this.preview_domain;
-    this.branding = new Branding(http);
-  }
+  constructor(private readonly http: HttpClient) {}
 
   /** Get the current tenant's plan, limits, and live usage counters. */
   async current(): Promise<TenantPlan> {
     const data = await this.http.get<unknown>("/tenant/plan");
     return unwrap<TenantPlan>(data);
   }
-
-  /** Convenience alias for `tenant.branding.get()`. */
-  async getBranding(): Promise<BrandingData> {
-    return this.branding.get();
-  }
-
-  /** Convenience alias for `tenant.branding.set(...)`. */
-  async setBranding(params: TenantBrandingUpdateParams): Promise<BrandingData> {
-    return this.branding.set(params);
-  }
-
-  /** Convenience alias for `tenant.branding.delete()`. */
-  async deleteBranding(): Promise<void> {
-    await this.branding.delete();
-  }
 }