@miosa/sdk 0.3.0

package/src/resources/computer.ts

@@ -0,0 +1,530 @@
+import { HttpClient } from "../http.js";
+import type { ComputerData, ComputerId } from "../types.js";
+import { Checkpoints } from "./checkpoints.js";
+import { ComputerAutoStop } from "./computer-auto-stop.js";
+import { ComputerEnv } from "./computer-env.js";
+import { ComputerLogs } from "./computer-logs.js";
+import { ComputerOsa } from "./computer-osa.js";
+import { ComputerPorts } from "./computer-ports.js";
+import { ComputerTerminal } from "./computer-terminal.js";
+import { ComputerVolumes } from "./computer-volumes.js";
+import { CustomDomains } from "./custom_domains.js";
+import { Desktop } from "./desktop.js";
+import { Events } from "./events.js";
+import { Exec } from "./exec.js";
+import { Files } from "./files.js";
+import { NetworkPolicy } from "./network_policy.js";
+
+/**
+ * Per-computer inbox config (GET/PATCH /computers/:id/inbox).
+ * Defined inline because it has no separate file (small surface).
+ */
+export class ComputerInbox {
+  constructor(
+    private readonly http: HttpClient,
+    private readonly computerId: string,
+  ) {}
+
+  async get(): Promise<Record<string, unknown>> {
+    const raw = await this.http.get<unknown>(
+      `/computers/${this.computerId}/inbox`,
+    );
+    return unwrapData(raw);
+  }
+
+  async update(
+    fields: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
+    const body = Object.fromEntries(
+      Object.entries(fields).filter(([, v]) => v !== undefined),
+    );
+    const raw = await this.http.patch<unknown>(
+      `/computers/${this.computerId}/inbox`,
+      body,
+    );
+    return unwrapData(raw);
+  }
+}
+
+function unwrapData(data: unknown): Record<string, unknown> {
+  if (data && typeof data === "object") {
+    const d = data as Record<string, unknown>;
+    if ("data" in d && Object.keys(d).length <= 2) {
+      return d.data as Record<string, unknown>;
+    }
+  }
+  return (data ?? {}) as Record<string, unknown>;
+}
+
+/**
+ * A Computer instance bound to a specific computer ID.
+ *
+ * Returned by `miosa.computers.create()`, `miosa.computers.get()`, and
+ * `miosa.computers.list()`. Exposes all per-computer actions as methods and
+ * sub-resources as properties.
+ */
+export class Computer {
+  /** Raw data from the API. Refresh with `await computer.reload()`. */
+  data: ComputerData;
+
+  /** Desktop control — screenshot, click, type, drag, etc. */
+  readonly desktop: Desktop;
+
+  /** Execute shell and Python commands. */
+  readonly exec: Exec;
+
+  /** File operations — upload, download, list, delete. */
+  readonly files: Files;
+
+  /** Firecracker checkpoint (snapshot) management. */
+  readonly checkpoints: Checkpoints;
+
+  /** Egress network policy — allow/deny rules applied at the host TAP level. */
+  readonly networkPolicy: NetworkPolicy;
+
+  /** Real-time event subscription (window, clipboard, file, process, idle). */
+  readonly events: Events;
+
+  /** Custom domain management — map your own FQDNs to this sandbox. */
+  readonly domains: CustomDomains;
+
+  /** PTY session management — create/resize. */
+  readonly terminal: ComputerTerminal;
+
+  /** In-VM OSA agent dispatch — submitTask, cancelTask, status, configure. */
+  readonly osa: ComputerOsa;
+
+  /** Idle auto-stop config — get/update. */
+  readonly autoStop: ComputerAutoStop;
+
+  /** Per-computer inbox config — get/update. */
+  readonly inbox: ComputerInbox;
+
+  /** Encrypted env var CRUD — list, set, update, delete, bulkSet. */
+  readonly env: ComputerEnv;
+
+  /** VM log read + SSE stream. */
+  readonly logs: ComputerLogs;
+
+  /** Per-port visibility control — list, get, create, update, delete. */
+  readonly ports: ComputerPorts;
+
+  /** Volume attachment — list, attach, detach. */
+  readonly volumes: ComputerVolumes;
+
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient, data: ComputerData) {
+    this.http = http;
+    this.data = data;
+
+    const id = data.id as string;
+    this.desktop = new Desktop(http, id);
+    this.exec = new Exec(http, id);
+    this.files = new Files(http, id);
+    this.checkpoints = new Checkpoints(http, id);
+    this.networkPolicy = new NetworkPolicy(http, id);
+    this.events = new Events(http.baseUrl, http.apiKey, id);
+    this.domains = new CustomDomains(http, id);
+    this.terminal = new ComputerTerminal(http, id);
+    this.osa = new ComputerOsa(http, id);
+    this.autoStop = new ComputerAutoStop(http, id);
+    this.inbox = new ComputerInbox(http, id);
+    this.env = new ComputerEnv(http, id);
+    this.logs = new ComputerLogs(http, id);
+    this.ports = new ComputerPorts(http, id);
+    this.volumes = new ComputerVolumes(http, id);
+  }
+
+  get id(): ComputerId {
+    return this.data.id;
+  }
+
+  get name(): string {
+    return this.data.name;
+  }
+
+  get status(): ComputerData["status"] {
+    return this.data.status;
+  }
+
+  /** URL-safe slug; falls back to the raw id when unset. */
+  get slug(): string {
+    return this.data.slug || (this.data.id as string);
+  }
+
+  /**
+   * Public HTTPS URL that forwards to a given port inside the VM.
+   *
+   * Example — expose a dev server running on port 3000:
+   * ```ts
+   * await computer.exec.bash("npm run dev &");
+   * const url = computer.previewUrl(3000);
+   * // => https://3000-<slug>.sandbox.miosa.ai
+   * ```
+   *
+   * 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.
+   */
+  previewUrl(port: number, path: string = "/"): string {
+    const p = path.startsWith("/") ? path : `/${path}`;
+    return `https://${port}-${this.slug}.sandbox.miosa.ai${p}`;
+  }
+
+  /** Root preview URL — serves whatever is on the default app port. */
+  get publicUrl(): string {
+    return `https://${this.slug}.sandbox.miosa.ai`;
+  }
+
+  // ─── Lifecycle ─────────────────────────────────────────────────────────────
+
+  /** Start the computer. */
+  async start(): Promise<Computer> {
+    const updated = await this.http.post<ComputerData>(
+      `/computers/${this.id}/start`,
+    );
+    this.data = updated;
+    return this;
+  }
+
+  /** Stop the computer. */
+  async stop(): Promise<Computer> {
+    const updated = await this.http.post<ComputerData>(
+      `/computers/${this.id}/stop`,
+    );
+    this.data = updated;
+    return this;
+  }
+
+  /** Restart the computer. */
+  async restart(): Promise<Computer> {
+    const updated = await this.http.post<ComputerData>(
+      `/computers/${this.id}/restart`,
+    );
+    this.data = updated;
+    return this;
+  }
+
+  /** Permanently destroy the computer. After this call the instance is invalid. */
+  async destroy(): Promise<void> {
+    return this.http.delete<void>(`/computers/${this.id}`);
+  }
+
+  /** Reload metadata from the API and update `this.data`. */
+  async reload(): Promise<Computer> {
+    this.data = await this.http.get<ComputerData>(`/computers/${this.id}`);
+    return this;
+  }
+
+  // ─── Desktop shortcuts ─────────────────────────────────────────────────────
+
+  /**
+   * Capture a desktop screenshot as PNG bytes.
+   * Shortcut for `computer.desktop.screenshot()`.
+   */
+  async screenshot(): Promise<Uint8Array> {
+    return this.desktop.screenshot();
+  }
+
+  /**
+   * Capture a desktop screenshot encoded as a base64 string.
+   * Convenience for AI agents that pass screenshots to LLMs.
+   */
+  async screenshotBase64(): Promise<string> {
+    const bytes = await this.desktop.screenshot();
+    // Browser-safe base64 — Buffer isn't always available.
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]!);
+    }
+    return typeof btoa === "function"
+      ? btoa(binary)
+      : Buffer.from(bytes).toString("base64");
+  }
+
+  /**
+   * Click at the given coordinates (default left button).
+   * Shortcut for `computer.desktop.click(x, y)`.
+   */
+  async click(x: number, y: number): Promise<void> {
+    await this.desktop.click(x, y);
+  }
+
+  /** Explicit left-button click. Alias for `click(x, y)`. */
+  async leftClick(x: number, y: number): Promise<void> {
+    await this.desktop.click(x, y, "left");
+  }
+
+  /** Right-button click. */
+  async rightClick(x: number, y: number): Promise<void> {
+    await this.desktop.click(x, y, "right");
+  }
+
+  /** Double-click at the given coordinates. */
+  async doubleClick(x: number, y: number): Promise<void> {
+    await this.desktop.doubleClick(x, y);
+  }
+
+  /**
+   * Type text into the focused element.
+   * Shortcut for `computer.desktop.type(text)`.
+   */
+  async type(text: string): Promise<void> {
+    await this.desktop.type(text);
+  }
+
+  /**
+   * Send a key or key combo.
+   * Shortcut for `computer.desktop.key(key)`.
+   */
+  async key(key: string): Promise<void> {
+    await this.desktop.key(key);
+  }
+
+  /**
+   * Scroll in a direction.
+   * Shortcut for `computer.desktop.scroll(direction, clicks)`.
+   */
+  async scroll(
+    direction: Parameters<Desktop["scroll"]>[0],
+    clicks = 3,
+  ): Promise<void> {
+    await this.desktop.scroll(direction, clicks);
+  }
+
+  /**
+   * Click and drag between two points.
+   * Shortcut for `computer.desktop.drag(fromX, fromY, toX, toY)`.
+   */
+  async drag(
+    fromX: number,
+    fromY: number,
+    toX: number,
+    toY: number,
+  ): Promise<void> {
+    await this.desktop.drag(fromX, fromY, toX, toY);
+  }
+
+  /**
+   * Wait for N seconds inside the desktop environment.
+   * Shortcut for `computer.desktop.wait(seconds)`.
+   */
+  async wait(seconds: number): Promise<void> {
+    await this.desktop.wait(seconds);
+  }
+
+  // ─── Exec shortcuts ────────────────────────────────────────────────────────
+
+  /**
+   * Run a shell command.
+   * Shortcut for `computer.exec.bash(command)`.
+   */
+  async bash(command: string, timeout?: number) {
+    return this.exec.bash(command, timeout);
+  }
+
+  /**
+   * Run Python code.
+   * Shortcut for `computer.exec.python(code)`.
+   */
+  async python(code: string, timeout?: number) {
+    return this.exec.python(code, timeout);
+  }
+
+  // ─── Window / cursor / app shortcuts ───────────────────────────────────────
+
+  /** List open windows on the desktop. */
+  async windows(): Promise<Awaited<ReturnType<Desktop["windows"]>>> {
+    return this.desktop.windows();
+  }
+
+  /** Get the current cursor position. */
+  async cursor(): Promise<Awaited<ReturnType<Desktop["cursor"]>>> {
+    return this.desktop.cursor();
+  }
+
+  /** Focus a specific window by ID. */
+  async focusWindow(windowId: string): Promise<void> {
+    await this.desktop.focusWindow(windowId);
+  }
+
+  /** Launch an installed app inside the VM. */
+  async launch(appName: string): Promise<void> {
+    await this.desktop.launch(appName);
+  }
+
+  // ─── Scoped filesystem helper ──────────────────────────────────────────────
+
+  /**
+   * Return a `ScopedFs` bound to `workingDir`.  All path arguments to
+   * `readFile`, `writeFile`, and `readdir` are resolved relative to that
+   * directory — no need to repeat the prefix on every call.
+   *
+   * ```ts
+   * const fs = computer.fs("/workspace");
+   * await fs.writeFile("main.py", "print(1)");
+   * const src = await fs.readFile("main.py");
+   * const entries = await fs.readdir(".");
+   * ```
+   */
+  fs(workingDir: string): ScopedFs {
+    return new ScopedFs(this.files, workingDir);
+  }
+
+  // ─── Direct methods ────────────────────────────────────────────────────────
+
+  /** Get VNC credentials for this computer. */
+  async vncCredentials(): Promise<Record<string, unknown>> {
+    return unwrapData(
+      await this.http.get<unknown>(`/computers/${this.id}/vnc-credentials`),
+    );
+  }
+
+  /** List installed apps inside the VM. */
+  async apps(): Promise<Record<string, unknown>> {
+    return unwrapData(
+      await this.http.get<unknown>(`/computers/${this.id}/apps`),
+    );
+  }
+
+  /** Get URL map for this computer (VNC, preview, etc.). */
+  async urls(): Promise<Record<string, unknown>> {
+    return unwrapData(
+      await this.http.get<unknown>(`/computers/${this.id}/urls`),
+    );
+  }
+
+  /** Mint a short-lived stream token for this computer. */
+  async streamToken(): Promise<Record<string, unknown>> {
+    return unwrapData(
+      await this.http.post<unknown>(`/computers/${this.id}/stream-token`),
+    );
+  }
+
+  /** Clone this computer into a new one. */
+  async clone(opts: Record<string, unknown> = {}): Promise<Computer> {
+    const body = Object.fromEntries(
+      Object.entries(opts).filter(([, v]) => v !== undefined),
+    );
+    const raw = await this.http.post<unknown>(
+      `/computers/${this.id}/clone`,
+      body,
+    );
+    const data = unwrapData(raw) as unknown as ComputerData;
+    return new Computer(this.http, data);
+  }
+
+  /** Resize the computer (change CPU/memory/disk). */
+  async resize(size: string): Promise<Computer> {
+    const updated = await this.http.post<ComputerData>(
+      `/computers/${this.id}/resize`,
+      { size },
+    );
+    this.data = updated;
+    return this;
+  }
+
+  /** Move the computer to a different region or host. */
+  async move(opts: Record<string, unknown>): Promise<Computer> {
+    const body = Object.fromEntries(
+      Object.entries(opts).filter(([, v]) => v !== undefined),
+    );
+    const updated = await this.http.post<ComputerData>(
+      `/computers/${this.id}/move`,
+      body,
+    );
+    this.data = updated;
+    return this;
+  }
+
+  /** Capture a region of the desktop as PNG bytes. */
+  async screenshotRegion(
+    x: number,
+    y: number,
+    width: number,
+    height: number,
+  ): Promise<Uint8Array> {
+    return this.http.request<Uint8Array>(
+      `/computers/${this.id}/screenshot-region`,
+      {
+        method: "POST",
+        body: { x, y, width, height },
+        binary: true,
+      },
+    );
+  }
+
+  /** Get time-series metrics (window: "1h" | "24h" | "7d"). */
+  async metrics(window = "1h"): Promise<Record<string, unknown>> {
+    return unwrapData(
+      await this.http.get<unknown>(`/computers/${this.id}/metrics`, {
+        window,
+      }),
+    );
+  }
+
+  // ─── Serialisation ─────────────────────────────────────────────────────────
+
+  toJSON(): ComputerData {
+    return this.data;
+  }
+
+  toString(): string {
+    return `Computer(${this.id}, ${this.status})`;
+  }
+}
+
+/**
+ * A thin filesystem wrapper that prepends a fixed working directory to all
+ * path arguments, mirroring the Node.js `fs/promises` surface.
+ *
+ * Obtain via `computer.fs("/workspace")`.
+ */
+export class ScopedFs {
+  private readonly files: Files;
+  private readonly workingDir: string;
+
+  constructor(files: Files, workingDir: string) {
+    this.files = files;
+    // Normalise: strip trailing slash unless it's the root.
+    this.workingDir =
+      workingDir !== "/" ? workingDir.replace(/\/$/, "") : workingDir;
+  }
+
+  /** Resolve a relative or absolute path against `workingDir`. */
+  private resolve(path: string): string {
+    if (path.startsWith("/")) return path;
+    const joined = `${this.workingDir}/${path}`;
+    // Collapse double slashes and simple `.` segments.
+    return joined.replace(/\/\.\//g, "/").replace(/\/+/g, "/");
+  }
+
+  /** Write a UTF-8 string to a file (relative or absolute path). */
+  async writeFile(path: string, content: string): Promise<void> {
+    return this.files.writeFile(this.resolve(path), content);
+  }
+
+  /** Read a file and return its UTF-8 contents (relative or absolute path). */
+  async readFile(path: string): Promise<string> {
+    return this.files.readFile(this.resolve(path));
+  }
+
+  /** List a directory (relative or absolute path). */
+  async readdir(path: string): Promise<import("../types.js").DirEntry[]> {
+    return this.files.readdir(this.resolve(path));
+  }
+
+  /** Stat a path (relative or absolute). */
+  async stat(path: string): Promise<import("../types.js").FileStat> {
+    return this.files.stat(this.resolve(path));
+  }
+
+  /** Create a directory (relative or absolute). */
+  async mkdir(
+    path: string,
+    options?: import("../types.js").MkdirParams,
+  ): Promise<void> {
+    return this.files.mkdir(this.resolve(path), options);
+  }
+}

package/src/resources/computers.ts

@@ -0,0 +1,75 @@
+import { HttpClient } from "../http.js";
+import type {
+  ComputerCreateParams,
+  ComputerData,
+  ComputerId,
+  ComputerListParams,
+  ComputerUpdateParams,
+} from "../types.js";
+import { Computer } from "./computer.js";
+
+export class Computers {
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
+
+  /**
+   * Create a new computer. The computer starts in `creating` state — call
+   * `computer.start()` once it reaches `stopped` to boot it.
+   */
+  async create(params: ComputerCreateParams): Promise<Computer> {
+    const data = await this.http.post<ComputerData>("/computers", {
+      template_type: "miosa-desktop",
+      size: "small",
+      ...params,
+    });
+    return new Computer(this.http, data);
+  }
+
+  /**
+   * List all computers for the authenticated tenant.
+   */
+  async list(params?: ComputerListParams): Promise<Computer[]> {
+    const query: Record<string, string | number | boolean | undefined> = {
+      page: params?.page,
+      per_page: params?.per_page,
+      status: params?.status,
+    };
+    const response = await this.http.get<{ data: ComputerData[] }>(
+      "/computers",
+      query,
+    );
+    return response.data.map((d) => new Computer(this.http, d));
+  }
+
+  /**
+   * Fetch a single computer by ID.
+   */
+  async get(id: ComputerId | string): Promise<Computer> {
+    const data = await this.http.get<ComputerData>(`/computers/${id}`);
+    return new Computer(this.http, data);
+  }
+
+  /**
+   * Update computer metadata or name.
+   */
+  async update(
+    id: ComputerId | string,
+    params: ComputerUpdateParams,
+  ): Promise<Computer> {
+    const data = await this.http.patch<ComputerData>(
+      `/computers/${id}`,
+      params,
+    );
+    return new Computer(this.http, data);
+  }
+
+  /**
+   * Permanently delete a computer.
+   */
+  async delete(id: ComputerId | string): Promise<void> {
+    return this.http.delete<void>(`/computers/${id}`);
+  }
+}

package/src/resources/credits.ts

@@ -0,0 +1,43 @@
+import { HttpClient } from "../http.js";
+import type {
+  CreditBalance,
+  CreditTransactionListResponse,
+  CreditUsage,
+} from "../types.js";
+
+export interface CreditTransactionListParams {
+  page?: number;
+  per_page?: number;
+}
+
+export class Credits {
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
+
+  /** Get the current credit balance for the authenticated tenant. */
+  async balance(): Promise<CreditBalance> {
+    return this.http.get<CreditBalance>("/credits/balance");
+  }
+
+  /** List credit transactions (purchases, deductions). */
+  async transactions(
+    params?: CreditTransactionListParams,
+  ): Promise<CreditTransactionListResponse> {
+    const query: Record<string, number | undefined> = {
+      page: params?.page,
+      per_page: params?.per_page,
+    };
+    return this.http.get<CreditTransactionListResponse>(
+      "/credits/transactions",
+      query,
+    );
+  }
+
+  /** Get aggregated credit usage for the current billing period. */
+  async usage(): Promise<CreditUsage> {
+    return this.http.get<CreditUsage>("/credits/usage");
+  }
+}