@miosa/sdk 1.2.0 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miosa/sdk",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "TypeScript SDK for the MIOSA API — cloud VM desktop infrastructure for AI agents",
   "license": "MIT",
   "author": "MIOSA <hello@miosa.ai>",

package/src/index.ts

@@ -122,6 +122,7 @@ export type {
   DeploymentData,
   DeploymentId,
   DeploymentListParams,
+  DeploymentProduct,
   DeploymentReleaseData,
   DeploymentReleaseId,
   DeploymentServiceData,
@@ -134,6 +135,7 @@ export type {
   DeploymentVersionId,
   DeploymentVersionKind,
   DeploymentVersionState,
+  DockerDeployCreateParams,
   ExternalAttribution,
   PublishFromSandboxParams,
   PublishParams,
@@ -216,7 +218,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 +287,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/computer.ts

@@ -176,21 +176,26 @@ export class Computer {
    * ```ts
    * await computer.exec.bash("npm run dev &");
    * const url = computer.previewUrl(3000);
-   * // => https://3000-<slug>.sandbox.miosa.ai
+   * // => https://3000-<slug>.sandbox.<tenant-domain>
    * ```
    *
    * Works for any TCP HTTP listener. Public (no auth required); anyone with
    * the URL can see it. Served over the ingress proxy so it inherits the
-   * wildcard TLS cert — no per-sandbox certs to manage.
+   * tenant's white-label preview domain — no per-sandbox certs to manage.
    */
   previewUrl(port: number, path: string = "/"): string {
     const p = path.startsWith("/") ? path : `/${path}`;
-    return `https://${port}-${this.slug}.sandbox.miosa.ai${p}`;
+    return `https://${port}-${this.slug}.sandbox.${this.previewDomain}${p}`;
   }
 
   /** Root preview URL — serves whatever is on the default app port. */
   get publicUrl(): string {
-    return `https://${this.slug}.sandbox.miosa.ai`;
+    return `https://${this.slug}.sandbox.${this.previewDomain}`;
+  }
+
+  /** Tenant's preview/base domain, white-label aware. */
+  get previewDomain(): string {
+    return this.data.preview_domain || "miosa.app";
   }
 
   // ─── Lifecycle ─────────────────────────────────────────────────────────────

package/src/resources/deployments.test.ts

@@ -0,0 +1,55 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { HttpClient } from "../http.js";
+import { Deployments } from "./deployments.js";
+
+const mockRequest = vi.fn();
+
+function makeHttp(): HttpClient {
+  const http = {} as HttpClient;
+  http.request = mockRequest;
+  return http;
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+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");
+  });
+});

package/src/resources/deployments.ts

@@ -50,6 +50,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 +109,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;
@@ -119,7 +123,7 @@ export interface DeploymentData {
 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 +285,8 @@ export interface DeploymentCreateParams extends ExternalAttribution {
   idempotencyKey?: string;
 }
 
+export interface DockerDeployCreateParams extends DeploymentCreateParams {}
+
 export interface DeploymentUpdateParams {
   name?: string;
   branch?: string;
@@ -421,6 +427,15 @@ function stripUndefined(
   );
 }
 
+function dockerDeployMetadata(
+  metadata: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  return {
+    ...(metadata ?? {}),
+    deployment_product: "docker_deploy",
+  };
+}
+
 // ── Sub-resources ──────────────────────────────────────────────────────────
 
 export class DeploymentVersions {
@@ -627,6 +642,20 @@ 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),
+    });
+  }
+
   async update(
     deploymentId: string,
     params: DeploymentUpdateParams,

package/src/resources/sandboxes.test.ts

@@ -393,10 +393,10 @@ describe("Sandbox handle", () => {
   it("pause/resume/deploy use native sandbox lifecycle endpoints", async () => {
     mockPost
       .mockResolvedValueOnce({ data: sandboxData({ state: "paused" }) })
-      .mockResolvedValueOnce({ data: sandboxData({ state: "running" }) })
-      .mockResolvedValueOnce({
+      .mockResolvedValueOnce({ data: sandboxData({ state: "running" }) });
+    mockRequest.mockResolvedValueOnce({
         data: { deployment_id: "dep_1", url: "https://app.miosa.app" },
-      });
+    });
 
     const sandbox = new Sandbox(makeHttp(), sandboxData());
     await sandbox.pause();
@@ -413,14 +413,43 @@ describe("Sandbox handle", () => {
       "/sandboxes/sbx_123/resume",
       {},
     );
-    expect(mockPost).toHaveBeenNthCalledWith(3, "/sandboxes/sbx_123/deploy", {
-      name: "site",
-      path: "/workspace/dist",
-      custom_domain: "example.com",
+    expect(mockRequest).toHaveBeenCalledWith("/sandboxes/sbx_123/deploy", {
+      method: "POST",
+      body: {
+        name: "site",
+        output_path: "/workspace/dist",
+        custom_domain: "example.com",
+      },
     });
     expect(deployment.deployment_id).toBe("dep_1");
   });
 
+  it("deployDocker marks sandbox deployment for Docker Deploy", async () => {
+    mockRequest.mockResolvedValueOnce({
+      data: {
+        deployment_id: "dep_2",
+        deployment_product: "docker_deploy",
+        data: { deployment: { docker_deploy_host_id: "ddh_123" } },
+      },
+    });
+
+    const sandbox = new Sandbox(makeHttp(), sandboxData());
+    const deployment = await sandbox.deployDocker({
+      name: "docker-site",
+      port: 3000,
+    });
+
+    expect(mockRequest).toHaveBeenCalledWith("/sandboxes/sbx_123/deploy", {
+      method: "POST",
+      body: {
+        name: "docker-site",
+        port: 3000,
+        deployment_type: "docker_deploy",
+      },
+    });
+    expect(deployment.deployment_product).toBe("docker_deploy");
+  });
+
   it("throws before operations when not running", async () => {
     const sandbox = new Sandbox(
       makeHttp(),

package/src/resources/sandboxes.ts

@@ -318,6 +318,21 @@ export interface SandboxDeployParams {
   sourceSnapshotPath?: string;
   source_snapshot_path?: string;
   entrypoint?: string;
+  buildCommand?: string;
+  build_command?: string;
+  runCommand?: string;
+  run_command?: string;
+  startCommand?: string;
+  start_command?: string;
+  port?: number;
+  healthCheckPath?: string;
+  health_check_path?: string;
+  deploymentType?: "miosa_deploy" | "docker_deploy" | "docker-deploy" | string;
+  deployment_type?: "miosa_deploy" | "docker_deploy" | "docker-deploy" | string;
+  type?: "static" | "dynamic" | "server" | string;
+  mode?: "static" | "dynamic" | "server" | string;
+  database?: boolean | Record<string, unknown>;
+  resources?: Record<string, unknown>;
   domain?: string;
   customDomain?: string;
   custom_domain?: string;
@@ -1092,6 +1107,16 @@ export class Sandbox {
         source_snapshot_path:
           params.sourceSnapshotPath ?? params.source_snapshot_path,
         entrypoint: params.entrypoint,
+        build_command: params.buildCommand ?? params.build_command,
+        run_command: params.runCommand ?? params.run_command,
+        start_command: params.startCommand ?? params.start_command,
+        port: params.port,
+        health_check_path: params.healthCheckPath ?? params.health_check_path,
+        deployment_type: params.deploymentType ?? params.deployment_type,
+        type: params.type,
+        mode: params.mode,
+        database: params.database,
+        resources: params.resources,
         domain: params.domain,
         custom_domain: params.customDomain ?? params.custom_domain,
       }),
@@ -1108,6 +1133,12 @@ export class Sandbox {
     );
   }
 
+  async deployDocker(
+    params: SandboxDeployParams = {},
+  ): Promise<Record<string, unknown>> {
+    return this.deploy({ ...params, deploymentType: "docker_deploy" });
+  }
+
   /** Check readiness of the sandbox (GET /sandboxes/:id/readiness). */
   async readiness(): Promise<Record<string, unknown>> {
     return unwrap(

package/src/resources/tenant.ts

@@ -9,11 +9,38 @@ 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;
+  deployment_domain?: string | null;
+  fallback_miosa_domain?: string | null;
+  status?: string;
+  [key: string]: unknown;
+}
+
+export interface TenantBrandingUpdateParams {
+  logo_url?: string | null;
+  primary_color?: string | null;
+  wordmark?: string | null;
+  favicon_url?: string | null;
+  [key: string]: unknown;
+}
+
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
 function unwrap<T>(payload: unknown): T {

package/src/resources/webhooks.ts

@@ -2,7 +2,7 @@
  * Webhooks resource — tenant outgoing event delivery.
  */
 
-import { randomUUID } from "node:crypto";
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 
 import type { HttpClient } from "../http.js";
 
@@ -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,9 +106,72 @@ function idempotencyKey(key?: string): string {
   return key ?? randomUUID();
 }
 
+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 a MIOSA webhook signature header.
+ *
+ * Header format: `t=<unix_seconds>,v1=<hex_hmac_sha256>`.
+ */
+export function verifySignature(
+  body: string | Buffer | Uint8Array,
+  header: string,
+  secret: string,
+  options: WebhookSignatureVerifyOptions = {},
+): boolean {
+  const parsed = parseSignatureHeader(header);
+  if (!parsed) return false;
+
+  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 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 {
+  static verifySignature = verifySignature;
+  static verify_signature = verifySignature;
+
   constructor(private readonly http: HttpClient) {}
 
   async list(params: WebhookListParams = {}): Promise<WebhookData[]> {

package/src/types.ts

@@ -78,8 +78,9 @@ export interface ComputerData {
   id: ComputerId;
   name: string;
   /**
-   * URL-safe identifier used in preview URLs: `https://{port}-{slug}.sandbox.miosa.ai`.
-   * Falls back to the computer id when no slug is assigned.
+   * 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.
    */
   slug: string;
   status: ComputerStatus;
@@ -90,8 +91,10 @@ 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.miosa.ai`. */
+  /** Public ingress root, e.g. `https://<slug>.sandbox.<preview_domain>` (server-provided). */
   sandbox_url?: string;
+  /** Tenant's white-label preview/base domain (e.g. `cliniciq.com`). Use to build preview URLs. */
+  preview_domain?: string;
   /** KasmVNC URL for desktop templates. */
   desktop_url?: string;
   created_at: string;

package/src/resources/phase1.test.ts

@@ -1,187 +0,0 @@
-import * as crypto from "node:crypto";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import type { HttpClient } from "../http.js";
-import { Sandbox } from "./sandboxes.js";
-import { Tenant } from "./tenant.js";
-import { verifySignature, Webhooks } from "./webhooks.js";
-
-const mockGet = vi.fn();
-const mockPost = vi.fn();
-const mockPut = vi.fn();
-const mockPatch = vi.fn();
-const mockDelete = vi.fn();
-const mockRequest = vi.fn();
-
-function makeHttp(): HttpClient {
-  return {
-    get: mockGet,
-    post: mockPost,
-    put: mockPut,
-    patch: mockPatch,
-    delete: mockDelete,
-    request: mockRequest,
-  } as unknown as HttpClient;
-}
-
-function sandboxData(overrides: Record<string, unknown> = {}) {
-  return {
-    id: "sbx_123",
-    state: "running",
-    ready: true,
-    template_id: "miosa-sandbox",
-    ...overrides,
-  };
-}
-
-beforeEach(() => {
-  vi.resetAllMocks();
-});
-
-// ── tenant.preview_domain ────────────────────────────────────────────────────
-
-describe("tenant.preview_domain", () => {
-  it("get calls GET /tenant/preview-domain", async () => {
-    mockGet.mockResolvedValue({
-      domain: "preview.acme.com",
-      verified_at: null,
-    });
-    const tenant = new Tenant(makeHttp());
-    const result = await tenant.preview_domain.get();
-    expect(mockGet).toHaveBeenCalledWith("/tenant/preview-domain");
-    expect(result.domain).toBe("preview.acme.com");
-  });
-
-  it("set calls PUT /tenant/preview-domain", async () => {
-    mockPut.mockResolvedValue({ domain: "preview.acme.com" });
-    const tenant = new Tenant(makeHttp());
-    await tenant.preview_domain.set("preview.acme.com");
-    expect(mockPut).toHaveBeenCalledWith("/tenant/preview-domain", {
-      domain: "preview.acme.com",
-    });
-  });
-
-  it("verify calls POST /tenant/preview-domain/verify", async () => {
-    mockPost.mockResolvedValue({
-      verified: true,
-      target: "proxy.miosa.app",
-      records: [],
-    });
-    const tenant = new Tenant(makeHttp());
-    const result = await tenant.preview_domain.verify();
-    expect(mockPost).toHaveBeenCalledWith("/tenant/preview-domain/verify", {});
-    expect(result.verified).toBe(true);
-  });
-
-  it("delete calls DELETE /tenant/preview-domain", async () => {
-    mockDelete.mockResolvedValue(undefined);
-    const tenant = new Tenant(makeHttp());
-    await tenant.preview_domain.delete();
-    expect(mockDelete).toHaveBeenCalledWith("/tenant/preview-domain");
-  });
-});
-
-// ── tenant.branding ──────────────────────────────────────────────────────────
-
-describe("tenant.branding", () => {
-  it("get calls GET /tenant/branding", async () => {
-    mockGet.mockResolvedValue({ product_name: "Acme AI" });
-    const tenant = new Tenant(makeHttp());
-    const result = await tenant.branding.get();
-    expect(result.product_name).toBe("Acme AI");
-  });
-
-  it("set calls PUT /tenant/branding", async () => {
-    const branding = { product_name: "Acme", primary_color: "#ff0000" };
-    mockPut.mockResolvedValue(branding);
-    const tenant = new Tenant(makeHttp());
-    await tenant.branding.set(branding);
-    expect(mockPut).toHaveBeenCalledWith("/tenant/branding", branding);
-  });
-});
-
-// ── sandbox.update ───────────────────────────────────────────────────────────
-
-describe("sandbox.update", () => {
-  it("calls PATCH /sandboxes/{id} with body", async () => {
-    const updated = sandboxData({ name: "renamed" });
-    mockPatch.mockResolvedValue({ data: updated });
-    const sbx = new Sandbox(makeHttp(), sandboxData());
-    await sbx.update({ name: "renamed", slug: "my-slug" });
-    expect(mockPatch).toHaveBeenCalledWith("/sandboxes/sbx_123", {
-      name: "renamed",
-      slug: "my-slug",
-    });
-  });
-
-  it("only sends defined fields", async () => {
-    mockPatch.mockResolvedValue({ data: sandboxData() });
-    const sbx = new Sandbox(makeHttp(), sandboxData());
-    await sbx.update({ always_on: true });
-    expect(mockPatch).toHaveBeenCalledWith("/sandboxes/sbx_123", {
-      always_on: true,
-    });
-  });
-});
-
-// ── sandbox.previewToken ─────────────────────────────────────────────────────
-
-describe("sandbox.previewToken", () => {
-  it("calls POST /sandboxes/{id}/preview-token", async () => {
-    const tokenResp = {
-      token: "tok_xyz",
-      url: "https://preview.miosa.app?t=tok_xyz",
-      expires_at: "2026-05-26T01:00:00Z",
-      scope: "read",
-    };
-    mockPost.mockResolvedValue(tokenResp);
-    const sbx = new Sandbox(makeHttp(), sandboxData());
-    const result = await sbx.previewToken(3600, "read");
-    expect(mockPost).toHaveBeenCalledWith("/sandboxes/sbx_123/preview-token", {
-      expires_in: 3600,
-      scope: "read",
-    });
-    expect(result.token).toBe("tok_xyz");
-  });
-});
-
-// ── verifySignature ──────────────────────────────────────────────────────────
-
-function makeHeader(payload: Buffer, secret: string, ts?: number): string {
-  const t = ts ?? Math.floor(Date.now() / 1000);
-  const signed = Buffer.concat([Buffer.from(`${t}.`), payload]);
-  const sig = crypto.createHmac("sha256", secret).update(signed).digest("hex");
-  return `t=${t},v1=${sig}`;
-}
-
-describe("verifySignature", () => {
-  it("returns true for a valid signature", () => {
-    const payload = Buffer.from('{"event":"sandbox.created"}');
-    const header = makeHeader(payload, "secret123");
-    expect(verifySignature(payload, header, "secret123")).toBe(true);
-  });
-
-  it("returns false for wrong secret", () => {
-    const payload = Buffer.from('{"event":"sandbox.created"}');
-    const header = makeHeader(payload, "secret123");
-    expect(verifySignature(payload, header, "wrongsecret")).toBe(false);
-  });
-
-  it("throws for old timestamp", () => {
-    const payload = Buffer.from("body");
-    const old = Math.floor(Date.now() / 1000) - 400;
-    const header = makeHeader(payload, "s3cr3t", old);
-    expect(() => verifySignature(payload, header, "s3cr3t")).toThrow("too old");
-  });
-
-  it("returns false for malformed header", () => {
-    expect(verifySignature(Buffer.from("body"), "malformed", "secret")).toBe(
-      false,
-    );
-  });
-
-  it("Webhooks.verifySignature delegates to module function", () => {
-    const payload = Buffer.from("body");
-    const header = makeHeader(payload, "secret");
-    expect(Webhooks.verifySignature(payload, header, "secret")).toBe(true);
-  });
-});