@miosa/sdk 1.2.1 → 1.2.3

package/src/resources/phase1.test.ts

@@ -0,0 +1,187 @@
+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({
+      preview_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.preview_domain).toBe("preview.acme.com");
+  });
+
+  it("set calls PUT /tenant/preview-domain", async () => {
+    mockPut.mockResolvedValue({ preview_domain: "preview.acme.com" });
+    const tenant = new Tenant(makeHttp());
+    await tenant.preview_domain.set("preview.acme.com");
+    expect(mockPut).toHaveBeenCalledWith("/tenant/preview-domain", {
+      preview_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);
+  });
+});

package/src/resources/quotas.ts

@@ -0,0 +1,77 @@
+/**
+ * Quotas — per-external_user_id resource limits.
+ * Corresponds to: GET/PUT/DELETE /api/v1/quotas/external/{external_user_id}
+ */
+
+import type { HttpClient } from "../http.js";
+
+// ── Resource shapes ──────────────────────────────────────────────────────────
+
+export interface QuotaData {
+  external_user_id: string;
+  max_sandboxes?: number | null;
+  max_concurrent?: number | null;
+  max_storage_gb?: number | null;
+  max_credit_cents?: number | null;
+  usage?: {
+    sandbox_count?: number;
+    concurrent_count?: number;
+    storage_gb?: number;
+    credit_cents?: number;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+export interface QuotaSetParams {
+  max_sandboxes?: number;
+  max_concurrent?: number;
+  max_storage_gb?: number;
+  max_credit_cents?: number;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function unwrap<T>(payload: unknown): T {
+  if (payload && typeof payload === "object" && "data" in (payload as object)) {
+    return (payload as { data: T }).data;
+  }
+  return payload as T;
+}
+
+function stripUndefined(
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, v]) => v !== undefined),
+  );
+}
+
+// ── Main resource ─────────────────────────────────────────────────────────────
+
+export class Quotas {
+  constructor(private readonly http: HttpClient) {}
+
+  /** GET /api/v1/quotas/external/{external_user_id} — current limits + usage. */
+  async get(externalUserId: string): Promise<QuotaData> {
+    return unwrap(
+      await this.http.get<unknown>(`/quotas/external/${externalUserId}`),
+    );
+  }
+
+  /** PUT /api/v1/quotas/external/{external_user_id} — set per-user limits. */
+  async set(
+    externalUserId: string,
+    params: QuotaSetParams,
+  ): Promise<QuotaData> {
+    const body = stripUndefined(params as Record<string, unknown>);
+    return unwrap(
+      await this.http.put<unknown>(`/quotas/external/${externalUserId}`, body),
+    );
+  }
+
+  /** DELETE /api/v1/quotas/external/{external_user_id} — revert to tenant default. */
+  async delete(externalUserId: string): Promise<void> {
+    await this.http.delete<unknown>(`/quotas/external/${externalUserId}`);
+  }
+}

package/src/resources/sandbox-processes.ts

@@ -0,0 +1,112 @@
+/**
+ * SandboxProcesses — long-running process management inside a sandbox.
+ * Corresponds to: POST/GET/DELETE /api/v1/sandboxes/{id}/processes
+ */
+
+import type { HttpClient } from "../http.js";
+
+// ── Resource shapes ──────────────────────────────────────────────────────────
+
+export interface SandboxProcessData {
+  pid: number;
+  name?: string;
+  command: string;
+  status: "running" | "stopped" | "failed" | string;
+  started_at?: string;
+  exit_code?: number | null;
+  [key: string]: unknown;
+}
+
+export interface SandboxProcessStartParams {
+  command: string;
+  env?: Record<string, string>;
+  name?: string;
+}
+
+export interface SandboxProcessStreamEvent {
+  stream: "stdout" | "stderr";
+  line: string;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function unwrap<T>(payload: unknown): T {
+  if (payload && typeof payload === "object" && "data" in (payload as object)) {
+    return (payload as { data: T }).data;
+  }
+  return payload as T;
+}
+
+function listItems<T>(payload: unknown): T[] {
+  if (Array.isArray(payload)) return payload;
+  if (!payload || typeof payload !== "object") return [];
+  const p = payload as Record<string, unknown>;
+  for (const k of ["data", "processes", "items"]) {
+    if (Array.isArray(p[k])) return p[k] as T[];
+  }
+  return [];
+}
+
+function stripUndefined(
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, v]) => v !== undefined),
+  );
+}
+
+// ── Main resource ─────────────────────────────────────────────────────────────
+
+export class SandboxProcesses {
+  constructor(
+    private readonly http: HttpClient,
+    private readonly sandboxId: string,
+  ) {}
+
+  private base(): string {
+    return `/sandboxes/${this.sandboxId}/processes`;
+  }
+
+  /** POST /api/v1/sandboxes/{id}/processes — start a long-running process. */
+  async start(params: SandboxProcessStartParams): Promise<SandboxProcessData> {
+    const body = stripUndefined({
+      command: params.command,
+      env: params.env,
+      name: params.name,
+    });
+    return unwrap(await this.http.post<unknown>(this.base(), body));
+  }
+
+  /** GET /api/v1/sandboxes/{id}/processes — list all processes. */
+  async list(): Promise<SandboxProcessData[]> {
+    const data = await this.http.get<unknown>(this.base());
+    return listItems<SandboxProcessData>(data);
+  }
+
+  /** GET /api/v1/sandboxes/{id}/processes/{pid} — get a single process. */
+  async get(pid: number): Promise<SandboxProcessData> {
+    return unwrap(await this.http.get<unknown>(`${this.base()}/${pid}`));
+  }
+
+  /** DELETE /api/v1/sandboxes/{id}/processes/{pid} — SIGTERM then SIGKILL after 5s. */
+  async stop(pid: number): Promise<void> {
+    await this.http.delete<unknown>(`${this.base()}/${pid}`);
+  }
+
+  /** GET /api/v1/sandboxes/{id}/processes/{pid}/logs?tail=N — tail log text. */
+  async logs(pid: number, tail = 200): Promise<string> {
+    const data = await this.http.get<unknown>(`${this.base()}/${pid}/logs`, {
+      tail,
+    });
+    if (typeof data === "string") return data;
+    const d = data as Record<string, unknown>;
+    return String(d.logs ?? d.output ?? d.data ?? "");
+  }
+
+  /** GET /api/v1/sandboxes/{id}/processes/{pid}/stream (SSE) — live output. */
+  stream(pid: number): AsyncIterableIterator<SandboxProcessStreamEvent> {
+    return this.http.stream<SandboxProcessStreamEvent>(
+      `${this.base()}/${pid}/stream`,
+    );
+  }
+}

package/src/resources/sandbox-shares.ts

@@ -0,0 +1,83 @@
+/**
+ * SandboxShares — public read-only share URLs for a sandbox.
+ * Corresponds to: POST/GET/DELETE /api/v1/sandboxes/{id}/shares
+ */
+
+import type { HttpClient } from "../http.js";
+
+// ── Resource shapes ──────────────────────────────────────────────────────────
+
+export interface SandboxShareData {
+  share_id: string;
+  share_url: string;
+  expires_at?: string | null;
+  scope: string;
+  [key: string]: unknown;
+}
+
+export interface SandboxShareCreateParams {
+  expires_in?: number;
+  scope?: "read";
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function unwrap<T>(payload: unknown): T {
+  if (payload && typeof payload === "object" && "data" in (payload as object)) {
+    return (payload as { data: T }).data;
+  }
+  return payload as T;
+}
+
+function listItems<T>(payload: unknown): T[] {
+  if (Array.isArray(payload)) return payload;
+  if (!payload || typeof payload !== "object") return [];
+  const p = payload as Record<string, unknown>;
+  for (const k of ["data", "shares", "items"]) {
+    if (Array.isArray(p[k])) return p[k] as T[];
+  }
+  return [];
+}
+
+function stripUndefined(
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, v]) => v !== undefined),
+  );
+}
+
+// ── Main resource ─────────────────────────────────────────────────────────────
+
+export class SandboxShares {
+  constructor(
+    private readonly http: HttpClient,
+    private readonly sandboxId: string,
+  ) {}
+
+  private base(): string {
+    return `/sandboxes/${this.sandboxId}/shares`;
+  }
+
+  /** POST /api/v1/sandboxes/{id}/shares — create a public share URL. */
+  async create(
+    params: SandboxShareCreateParams = {},
+  ): Promise<SandboxShareData> {
+    const body = stripUndefined({
+      expires_in: params.expires_in,
+      scope: params.scope ?? "read",
+    });
+    return unwrap(await this.http.post<unknown>(this.base(), body));
+  }
+
+  /** GET /api/v1/sandboxes/{id}/shares — list all active shares. */
+  async list(): Promise<SandboxShareData[]> {
+    const data = await this.http.get<unknown>(this.base());
+    return listItems<SandboxShareData>(data);
+  }
+
+  /** DELETE /api/v1/sandboxes/{id}/shares/{share_id} — revoke a share. */
+  async revoke(shareId: string): Promise<void> {
+    await this.http.delete<unknown>(`${this.base()}/${shareId}`);
+  }
+}

package/src/resources/sandboxes.test.ts

@@ -424,6 +424,32 @@ describe("Sandbox handle", () => {
     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-events.ts

@@ -0,0 +1,32 @@
+/**
+ * TenantEvents — tenant-scoped SSE event stream.
+ * Corresponds to: GET /api/v1/events/stream?types=sandbox.*,webhook.delivered
+ */
+
+import type { HttpClient } from "../http.js";
+
+// ── Resource shapes ──────────────────────────────────────────────────────────
+
+export interface TenantStreamEvent {
+  type: string;
+  [key: string]: unknown;
+}
+
+// ── Main resource ─────────────────────────────────────────────────────────────
+
+export class TenantEvents {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * GET /api/v1/events/stream — tenant-scoped SSE event stream.
+   *
+   * @param types - Event type globs to filter. Accepts a comma-separated string
+   *   or an array, e.g. `["sandbox.*", "webhook.delivered"]`.
+   *   Omit to receive all event types.
+   */
+  stream(types?: string | string[]): AsyncIterableIterator<TenantStreamEvent> {
+    const typesParam = Array.isArray(types) ? types.join(",") : types;
+    const query = typesParam ? `?types=${encodeURIComponent(typesParam)}` : "";
+    return this.http.stream<TenantStreamEvent>(`/events/stream${query}`);
+  }
+}