@miosa/sdk 0.3.0

package/src/resources/open-computers/jobs.ts

@@ -0,0 +1,75 @@
+import { HttpClient } from "../../http.js";
+import type {
+  HostId,
+  JobData,
+  JobEvent,
+  JobId,
+  JobListResponse,
+  JobRunParams,
+} from "./types.js";
+
+/**
+ * Jobs resource — run commands on a remote OpenComputers host and stream output.
+ *
+ * ```ts
+ * const job = await client.openComputers.jobs.run(hostId, { command: "npm test" });
+ * for await (const event of client.openComputers.jobs.stream(hostId, job.id)) {
+ *   process.stdout.write(String(event.data ?? ""));
+ *   if (event.type === "done") break;
+ * }
+ * ```
+ */
+export class Jobs {
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
+
+  private base(hostId: string): string {
+    return `/opencomputers/hosts/${hostId}`;
+  }
+
+  /**
+   * Dispatch a command to run on the remote host.
+   */
+  async run(hostId: HostId | string, params: JobRunParams): Promise<JobData> {
+    return this.http.post<JobData>(`${this.base(hostId)}/exec`, params);
+  }
+
+  /**
+   * List all jobs for a host.
+   */
+  async list(hostId: HostId | string): Promise<JobListResponse> {
+    return this.http.get<JobListResponse>(`${this.base(hostId)}/exec`);
+  }
+
+  /**
+   * Fetch the current state of a job.
+   */
+  async get(hostId: HostId | string, jobId: JobId | string): Promise<JobData> {
+    return this.http.get<JobData>(`${this.base(hostId)}/exec/${jobId}`);
+  }
+
+  /**
+   * Stream live output from a running job.
+   *
+   * Yields `JobEvent` objects with `type` of `stdout`, `stderr`, `exit`, or
+   * `done`. Break the loop when you receive `done` or `exit`.
+   */
+  stream(
+    hostId: HostId | string,
+    jobId: JobId | string,
+  ): AsyncIterableIterator<JobEvent> {
+    return this.http.stream<JobEvent>(
+      `${this.base(hostId)}/exec/${jobId}/stream`,
+    );
+  }
+
+  /**
+   * Cancel a running or queued job.
+   */
+  async cancel(hostId: HostId | string, jobId: JobId | string): Promise<void> {
+    return this.http.delete<void>(`${this.base(hostId)}/exec/${jobId}`);
+  }
+}

package/src/resources/open-computers/open_computers.test.ts

@@ -0,0 +1,288 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { HttpClient } from "../../http.js";
+import { OpenComputers } from "./index.js";
+
+// ── Shared mock setup ────────────────────────────────────────────────────────
+
+const mockGet = vi.fn();
+const mockPost = vi.fn();
+const mockPatch = vi.fn();
+const mockDelete = vi.fn();
+const mockStream = vi.fn();
+
+function makeHttp(): HttpClient {
+  const http = {} as HttpClient;
+  http.get = mockGet;
+  http.post = mockPost;
+  http.patch = mockPatch;
+  http.delete = mockDelete;
+  http.stream = mockStream;
+  http.getBinary = vi.fn();
+  http.postFormData = vi.fn();
+  return http;
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ── Hosts ────────────────────────────────────────────────────────────────────
+
+describe("OpenComputers.hosts", () => {
+  const hostData = {
+    id: "host_abc",
+    name: "my-mac",
+    region: null,
+    status: "online",
+    tenant_id: "t_1",
+    labels: {},
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+  };
+
+  it("list() calls GET /opencomputers/hosts", async () => {
+    mockGet.mockResolvedValue({
+      data: [hostData],
+      meta: { total: 1, page: 1, per_page: 20 },
+    });
+    const oc = new OpenComputers(makeHttp());
+    const result = await oc.hosts.list();
+    expect(mockGet).toHaveBeenCalledWith("/opencomputers/hosts");
+    expect(result.data).toHaveLength(1);
+  });
+
+  it("create() calls POST /opencomputers/hosts with host_key in response", async () => {
+    const created = { ...hostData, host_key: "hk_secret" };
+    mockPost.mockResolvedValue(created);
+    const oc = new OpenComputers(makeHttp());
+    const result = await oc.hosts.create({ name: "my-mac" });
+    expect(mockPost).toHaveBeenCalledWith("/opencomputers/hosts", {
+      name: "my-mac",
+    });
+    expect(result.host_key).toBe("hk_secret");
+  });
+
+  it("get() calls GET /opencomputers/hosts/:id", async () => {
+    mockGet.mockResolvedValue(hostData);
+    const oc = new OpenComputers(makeHttp());
+    await oc.hosts.get("host_abc");
+    expect(mockGet).toHaveBeenCalledWith("/opencomputers/hosts/host_abc");
+  });
+
+  it("update() calls PATCH /opencomputers/hosts/:id", async () => {
+    mockPatch.mockResolvedValue({ ...hostData, name: "renamed" });
+    const oc = new OpenComputers(makeHttp());
+    await oc.hosts.update("host_abc", { name: "renamed" });
+    expect(mockPatch).toHaveBeenCalledWith("/opencomputers/hosts/host_abc", {
+      name: "renamed",
+    });
+  });
+
+  it("revoke() calls DELETE /opencomputers/hosts/:id", async () => {
+    mockDelete.mockResolvedValue(undefined);
+    const oc = new OpenComputers(makeHttp());
+    await oc.hosts.revoke("host_abc");
+    expect(mockDelete).toHaveBeenCalledWith("/opencomputers/hosts/host_abc");
+  });
+
+  it("events() returns an AsyncIterable from stream()", () => {
+    async function* fakeStream() {
+      yield {
+        type: "host_connected",
+        host_id: "host_abc",
+        data: null,
+        timestamp: "t",
+      };
+    }
+    mockStream.mockReturnValue(fakeStream());
+    const oc = new OpenComputers(makeHttp());
+    const iter = oc.hosts.events();
+    expect(mockStream).toHaveBeenCalledWith("/opencomputers/hosts/events");
+    expect(typeof iter[Symbol.asyncIterator]).toBe("function");
+  });
+});
+
+// ── Jobs ─────────────────────────────────────────────────────────────────────
+
+describe("OpenComputers.jobs", () => {
+  const jobData = {
+    id: "job_1",
+    host_id: "host_abc",
+    status: "completed",
+    command: "npm test",
+    args: [],
+    env: [],
+    cwd: null,
+    exit_code: 0,
+    stdout: "ok",
+    stderr: "",
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+    completed_at: "2026-01-01T00:00:01Z",
+  };
+
+  it("run() calls POST /opencomputers/hosts/:id/exec", async () => {
+    mockPost.mockResolvedValue(jobData);
+    const oc = new OpenComputers(makeHttp());
+    const result = await oc.jobs.run("host_abc", { command: "npm test" });
+    expect(mockPost).toHaveBeenCalledWith(
+      "/opencomputers/hosts/host_abc/exec",
+      { command: "npm test" },
+    );
+    expect(result.id).toBe("job_1");
+  });
+
+  it("list() calls GET /opencomputers/hosts/:id/exec", async () => {
+    mockGet.mockResolvedValue({
+      data: [jobData],
+      meta: { total: 1, page: 1, per_page: 20 },
+    });
+    const oc = new OpenComputers(makeHttp());
+    await oc.jobs.list("host_abc");
+    expect(mockGet).toHaveBeenCalledWith("/opencomputers/hosts/host_abc/exec");
+  });
+
+  it("get() calls GET /opencomputers/hosts/:id/exec/:job_id", async () => {
+    mockGet.mockResolvedValue(jobData);
+    const oc = new OpenComputers(makeHttp());
+    await oc.jobs.get("host_abc", "job_1");
+    expect(mockGet).toHaveBeenCalledWith(
+      "/opencomputers/hosts/host_abc/exec/job_1",
+    );
+  });
+
+  it("stream() returns an AsyncIterable", () => {
+    async function* fakeStream() {
+      yield { type: "stdout", job_id: "job_1", data: "ok\n", timestamp: "t" };
+      yield { type: "done", job_id: "job_1", data: null, timestamp: "t" };
+    }
+    mockStream.mockReturnValue(fakeStream());
+    const oc = new OpenComputers(makeHttp());
+    const iter = oc.jobs.stream("host_abc", "job_1");
+    expect(mockStream).toHaveBeenCalledWith(
+      "/opencomputers/hosts/host_abc/exec/job_1/stream",
+    );
+    expect(typeof iter[Symbol.asyncIterator]).toBe("function");
+  });
+
+  it("cancel() calls DELETE /opencomputers/hosts/:id/exec/:job_id", async () => {
+    mockDelete.mockResolvedValue(undefined);
+    const oc = new OpenComputers(makeHttp());
+    await oc.jobs.cancel("host_abc", "job_1");
+    expect(mockDelete).toHaveBeenCalledWith(
+      "/opencomputers/hosts/host_abc/exec/job_1",
+    );
+  });
+});
+
+// ── Error paths ───────────────────────────────────────────────────────────────
+
+describe("OpenComputers error paths", () => {
+  it("propagates 401 from hosts.list()", async () => {
+    const { AuthError } = await import("../../errors.js");
+    mockGet.mockRejectedValue(new AuthError("Unauthorized", "UNAUTHORIZED"));
+    const oc = new OpenComputers(makeHttp());
+    await expect(oc.hosts.list()).rejects.toBeInstanceOf(AuthError);
+  });
+
+  it("propagates 404 from hosts.get()", async () => {
+    const { NotFoundError } = await import("../../errors.js");
+    mockGet.mockRejectedValue(new NotFoundError("Host not found", "NOT_FOUND"));
+    const oc = new OpenComputers(makeHttp());
+    await expect(oc.hosts.get("nonexistent")).rejects.toBeInstanceOf(
+      NotFoundError,
+    );
+  });
+
+  it("propagates 402 from jobs.run() when credits exhausted", async () => {
+    const { InsufficientCreditsError } = await import("../../errors.js");
+    mockPost.mockRejectedValue(
+      new InsufficientCreditsError(
+        "Insufficient credits",
+        "INSUFFICIENT_CREDITS",
+      ),
+    );
+    const oc = new OpenComputers(makeHttp());
+    await expect(
+      oc.jobs.run("host_abc", { command: "npm test" }),
+    ).rejects.toBeInstanceOf(InsufficientCreditsError);
+  });
+});
+
+// ── Tunnels ───────────────────────────────────────────────────────────────────
+
+describe("OpenComputers.tunnels", () => {
+  const tunnelData = {
+    id: "tun_1",
+    host_id: "host_abc",
+    slug: "abc123",
+    target_port: 3000,
+    auth_mode: "public",
+    public_url: "https://api.miosa.ai/t/abc123",
+    enabled: true,
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+  };
+
+  it("create() calls POST /opencomputers/hosts/:id/tunnels", async () => {
+    mockPost.mockResolvedValue(tunnelData);
+    const oc = new OpenComputers(makeHttp());
+    const result = await oc.tunnels.create("host_abc", { target_port: 3000 });
+    expect(mockPost).toHaveBeenCalledWith(
+      "/opencomputers/hosts/host_abc/tunnels",
+      { target_port: 3000 },
+    );
+    expect(result.public_url).toContain("abc123");
+  });
+
+  it("delete() calls DELETE /opencomputers/hosts/:id/tunnels/:tid", async () => {
+    mockDelete.mockResolvedValue(undefined);
+    const oc = new OpenComputers(makeHttp());
+    await oc.tunnels.delete("host_abc", "tun_1");
+    expect(mockDelete).toHaveBeenCalledWith(
+      "/opencomputers/hosts/host_abc/tunnels/tun_1",
+    );
+  });
+});
+
+// ── Agents ────────────────────────────────────────────────────────────────────
+
+describe("OpenComputers.agents", () => {
+  const sessionData = {
+    id: "sess_1",
+    host_id: "host_abc",
+    task: "run tests",
+    model_id: null,
+    status: "pending",
+    max_turns: 20,
+    turns_used: 0,
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+    completed_at: null,
+    error: null,
+  };
+
+  it("dispatch() calls POST /opencomputers/hosts/:id/agent/dispatch", async () => {
+    mockPost.mockResolvedValue(sessionData);
+    const oc = new OpenComputers(makeHttp());
+    const result = await oc.agents.dispatch("host_abc", { task: "run tests" });
+    expect(mockPost).toHaveBeenCalledWith(
+      "/opencomputers/hosts/host_abc/agent/dispatch",
+      { task: "run tests" },
+    );
+    expect(result.id).toBe("sess_1");
+  });
+
+  it("cancel() calls DELETE /opencomputers/hosts/:id/agent/sessions/:id", async () => {
+    mockDelete.mockResolvedValue(undefined);
+    const oc = new OpenComputers(makeHttp());
+    await oc.agents.cancel("host_abc", "sess_1");
+    expect(mockDelete).toHaveBeenCalledWith(
+      "/opencomputers/hosts/host_abc/agent/sessions/sess_1",
+    );
+  });
+});

package/src/resources/open-computers/secrets.ts

@@ -0,0 +1,115 @@
+import { HttpClient } from "../../http.js";
+import type {
+  HostId,
+  SecretCreateParams,
+  SecretData,
+  SecretId,
+  SecretUpdateParams,
+} from "./types.js";
+
+/**
+ * Secrets resource — manage encrypted per-host (and per-tenant) env vars.
+ *
+ * Secrets are injected into exec sessions and PTY sessions on the host.
+ * The value is encrypted at rest; `reveal()` decrypts it for one-time display.
+ *
+ * ```ts
+ * // Tenant-wide secret (shared across all hosts)
+ * await client.openComputers.secrets.createForTenant({ name: "OPENAI_KEY", value: "sk-..." });
+ *
+ * // Host-specific secret
+ * const secret = await client.openComputers.secrets.createForHost(hostId, {
+ *   name: "DB_PASSWORD", value: "hunter2",
+ * });
+ * ```
+ */
+export class Secrets {
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
+
+  // ── Tenant-scoped secrets ────────────────────────────────────────────────────
+
+  /**
+   * List all tenant-scoped secrets.
+   */
+  async listForTenant(): Promise<SecretData[]> {
+    const result = await this.http.get<{ data: SecretData[] }>(
+      "/opencomputers/secrets",
+    );
+    return result.data;
+  }
+
+  /**
+   * Create a tenant-scoped secret (available to all hosts).
+   */
+  async createForTenant(params: SecretCreateParams): Promise<SecretData> {
+    return this.http.post<SecretData>("/opencomputers/secrets", params);
+  }
+
+  // ── Host-scoped secrets ──────────────────────────────────────────────────────
+
+  /**
+   * List secrets scoped to a specific host.
+   */
+  async listForHost(hostId: HostId | string): Promise<SecretData[]> {
+    const result = await this.http.get<{ data: SecretData[] }>(
+      `/opencomputers/hosts/${hostId}/secrets`,
+    );
+    return result.data;
+  }
+
+  /**
+   * Create a secret scoped to a specific host.
+   */
+  async createForHost(
+    hostId: HostId | string,
+    params: SecretCreateParams,
+  ): Promise<SecretData> {
+    return this.http.post<SecretData>(
+      `/opencomputers/hosts/${hostId}/secrets`,
+      params,
+    );
+  }
+
+  /**
+   * Update a host-scoped secret (rotate value or update description).
+   */
+  async updateForHost(
+    hostId: HostId | string,
+    secretId: SecretId | string,
+    params: SecretUpdateParams,
+  ): Promise<SecretData> {
+    return this.http.patch<SecretData>(
+      `/opencomputers/hosts/${hostId}/secrets/${secretId}`,
+      params,
+    );
+  }
+
+  /**
+   * Delete a host-scoped secret.
+   */
+  async deleteForHost(
+    hostId: HostId | string,
+    secretId: SecretId | string,
+  ): Promise<void> {
+    return this.http.delete<void>(
+      `/opencomputers/hosts/${hostId}/secrets/${secretId}`,
+    );
+  }
+
+  /**
+   * Reveal (decrypt and return) the plaintext value of a secret.
+   * Use sparingly — each call is audit-logged.
+   */
+  async reveal(
+    hostId: HostId | string,
+    secretId: SecretId | string,
+  ): Promise<{ value: string }> {
+    return this.http.post<{ value: string }>(
+      `/opencomputers/hosts/${hostId}/secrets/${secretId}/reveal`,
+    );
+  }
+}

package/src/resources/open-computers/terminal.ts

@@ -0,0 +1,33 @@
+import { HttpClient } from "../../http.js";
+import type { HostId, WsTicket } from "./types.js";
+
+/**
+ * Terminal resource — issue WebSocket tickets for interactive PTY sessions on
+ * a remote OpenComputers host.
+ *
+ * The ticket is consumed by a WebSocket upgrade at the URL in `ws_url`. Use
+ * xterm.js or any raw WebSocket client to drive the terminal.
+ *
+ * ```ts
+ * const { ws_url } = await client.openComputers.terminal.ticket(hostId);
+ * const ws = new WebSocket(ws_url);
+ * ```
+ */
+export class Terminal {
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
+
+  /**
+   * Issue a short-lived WebSocket ticket for a terminal session.
+   *
+   * The ticket expires quickly — open the WebSocket immediately after receiving it.
+   */
+  async ticket(hostId: HostId | string): Promise<WsTicket> {
+    return this.http.post<WsTicket>(
+      `/opencomputers/hosts/${hostId}/terminal/ticket`,
+    );
+  }
+}

package/src/resources/open-computers/tunnels.ts

@@ -0,0 +1,87 @@
+import { HttpClient } from "../../http.js";
+import type {
+  HostId,
+  TunnelCreateParams,
+  TunnelData,
+  TunnelId,
+  TunnelListResponse,
+  TunnelUpdateParams,
+} from "./types.js";
+
+/**
+ * Tunnels resource — expose ports on a remote host as publicly reachable URLs.
+ *
+ * The public proxy is served at `/t/:slug/*path`. The `auth_mode` field on each
+ * tunnel controls whether the URL is open to the internet or requires
+ * tenant credentials / a password.
+ *
+ * ```ts
+ * const tunnel = await client.openComputers.tunnels.create(hostId, {
+ *   target_port: 8080,
+ *   auth_mode: "public",
+ * });
+ * console.log(tunnel.public_url); // https://api.miosa.ai/t/<slug>
+ * ```
+ */
+export class Tunnels {
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
+
+  private base(hostId: string): string {
+    return `/opencomputers/hosts/${hostId}/tunnels`;
+  }
+
+  /**
+   * List all tunnels for a host.
+   */
+  async list(hostId: HostId | string): Promise<TunnelListResponse> {
+    return this.http.get<TunnelListResponse>(this.base(hostId));
+  }
+
+  /**
+   * Create a new tunnel that forwards traffic to `target_port` on the host.
+   */
+  async create(
+    hostId: HostId | string,
+    params: TunnelCreateParams,
+  ): Promise<TunnelData> {
+    return this.http.post<TunnelData>(this.base(hostId), params);
+  }
+
+  /**
+   * Fetch a single tunnel.
+   */
+  async get(
+    hostId: HostId | string,
+    tunnelId: TunnelId | string,
+  ): Promise<TunnelData> {
+    return this.http.get<TunnelData>(`${this.base(hostId)}/${tunnelId}`);
+  }
+
+  /**
+   * Update a tunnel (target port, auth mode, or enabled state).
+   */
+  async update(
+    hostId: HostId | string,
+    tunnelId: TunnelId | string,
+    params: TunnelUpdateParams,
+  ): Promise<TunnelData> {
+    return this.http.patch<TunnelData>(
+      `${this.base(hostId)}/${tunnelId}`,
+      params,
+    );
+  }
+
+  /**
+   * Delete a tunnel. The public URL immediately becomes unreachable.
+   */
+  async delete(
+    hostId: HostId | string,
+    tunnelId: TunnelId | string,
+  ): Promise<void> {
+    return this.http.delete<void>(`${this.base(hostId)}/${tunnelId}`);
+  }
+}