@miosa/sdk 1.2.3 → 1.2.5

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();
-  }
 }

package/src/resources/webhooks.ts

@@ -66,6 +66,11 @@ export interface WebhookUpdateParams {
   [key: string]: unknown;
 }
 
+export interface WebhookSignatureVerifyOptions {
+  /** Maximum age for the webhook timestamp in seconds. Defaults to 300. */
+  toleranceSeconds?: number;
+}
+
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
 function unwrap<T>(payload: unknown): T {
@@ -101,63 +106,73 @@ function idempotencyKey(key?: string): string {
   return key ?? randomUUID();
 }
 
-function bodyBuffer(body: Buffer | Uint8Array | string): Buffer {
-  if (Buffer.isBuffer(body)) return body;
-  if (typeof body === "string") return Buffer.from(body, "utf8");
-  return Buffer.from(body);
+function parseSignatureHeader(header: string): {
+  timestamp: number;
+  signatures: string[];
+} | null {
+  const parts = header.split(",").map((part) => part.trim());
+  let timestamp: number | null = null;
+  const signatures: string[] = [];
+
+  for (const part of parts) {
+    const [key, value] = part.split("=", 2);
+    if (!key || !value) continue;
+    if (key === "t") {
+      const parsed = Number(value);
+      if (Number.isFinite(parsed)) timestamp = parsed;
+    } else if (key === "v1") {
+      signatures.push(value);
+    }
+  }
+
+  if (timestamp == null || signatures.length === 0) return null;
+  return { timestamp, signatures };
 }
 
 /**
- * Verify the `Miosa-Signature` webhook header.
+ * Verify a MIOSA webhook signature header.
  *
- * Header format: `t=<unix_seconds>,v1=<hex_hmac>`.
- * Signed payload: `<timestamp>.<raw_body>`.
+ * Header format: `t=<unix_seconds>,v1=<hex_hmac_sha256>`.
  */
 export function verifySignature(
-  body: Buffer | Uint8Array | string,
+  body: string | Buffer | Uint8Array,
   header: string,
   secret: string,
-  toleranceSec = 300,
+  options: WebhookSignatureVerifyOptions = {},
 ): boolean {
-  const parts = Object.fromEntries(
-    header
-      .split(",")
-      .map((chunk) => chunk.split("=", 2))
-      .filter(([key, value]) => key && value),
-  );
-
-  const timestamp = parts.t;
-  const received = parts.v1;
-  if (!timestamp || !received || !secret) return false;
-
-  const unixSeconds = Number(timestamp);
-  if (!Number.isFinite(unixSeconds)) return false;
+  const parsed = parseSignatureHeader(header);
+  if (!parsed) return false;
 
-  const ageSec = Math.abs(Date.now() / 1000 - unixSeconds);
-  if (ageSec > toleranceSec) {
-    throw new Error("webhook timestamp too old");
+  const toleranceSeconds = options.toleranceSeconds ?? 300;
+  const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - parsed.timestamp);
+  if (ageSeconds > toleranceSeconds) {
+    throw new Error("Webhook signature timestamp is too old");
   }
 
-  const rawBody = bodyBuffer(body);
-  const signed = Buffer.concat([Buffer.from(`${timestamp}.`), rawBody]);
-  const expected = createHmac("sha256", secret).update(signed).digest("hex");
-
-  try {
-    return timingSafeEqual(
-      Buffer.from(expected, "utf8"),
-      Buffer.from(received, "utf8"),
-    );
-  } catch {
-    return false;
-  }
+  const bodyBuffer = Buffer.isBuffer(body) ? body : Buffer.from(body);
+  const signedPayload = Buffer.concat([
+    Buffer.from(`${parsed.timestamp}.`),
+    bodyBuffer,
+  ]);
+  const expected = createHmac("sha256", secret)
+    .update(signedPayload)
+    .digest("hex");
+  const expectedBuffer = Buffer.from(expected, "hex");
+
+  return parsed.signatures.some((signature) => {
+    const actualBuffer = Buffer.from(signature, "hex");
+    if (actualBuffer.length !== expectedBuffer.length) return false;
+    return timingSafeEqual(actualBuffer, expectedBuffer);
+  });
 }
 
 // ── Main resource ─────────────────────────────────────────────────────────────
 
 export class Webhooks {
-  constructor(private readonly http: HttpClient) {}
-
   static verifySignature = verifySignature;
+  static verify_signature = verifySignature;
+
+  constructor(private readonly http: HttpClient) {}
 
   async list(params: WebhookListParams = {}): Promise<WebhookData[]> {
     const query = stripUndefined({ ...params }) as Record<

package/src/types.ts

@@ -78,9 +78,9 @@ export interface ComputerData {
   id: ComputerId;
   name: string;
   /**
-   * URL-safe identifier used in preview URLs: `https://{port}-{slug}.sandbox.{preview_domain}`.
-   * Falls back to the computer id when no slug is assigned. The domain is the
-   * tenant's white-label `preview_domain` (server-provided) — never hardcode it.
+   * URL-safe identifier used in preview URLs:
+   * `https://{port}-{slug}.sandbox.{preview_domain}`.
+   * Falls back to the computer id when no slug is assigned.
    */
   slug: string;
   status: ComputerStatus;
@@ -91,9 +91,9 @@ export interface ComputerData {
   metadata: Record<string, string>;
   /** Controls who can access the HTTP preview URL. Defaults to `"public"`. */
   visibility: ComputerVisibility;
-  /** Public ingress root, e.g. `https://<slug>.sandbox.<preview_domain>` (server-provided). */
+  /** Public ingress root, e.g. `https://<slug>.sandbox.<preview_domain>`. */
   sandbox_url?: string;
-  /** Tenant's white-label preview/base domain (e.g. `cliniciq.com`). Use to build preview URLs. */
+  /** Tenant's white-label preview/base domain, e.g. `cliniciq.com`. */
   preview_domain?: string;
   /** KasmVNC URL for desktop templates. */
   desktop_url?: string;