@miosa/sdk 0.3.0

package/src/resources/builder-sessions.ts

@@ -0,0 +1,75 @@
+/**
+ * BuilderSessions — durable, cross-device Builder UI state.
+ *
+ * Routes: /builder/sessions/*
+ * Accepts msk_* API keys or JWT.
+ * Sessions are optimal_sessions with resource_type="sandbox".
+ */
+
+import type { HttpClient } from "../http.js";
+
+function unwrap(data: unknown): Record<string, unknown> {
+  if (data && typeof data === "object") {
+    const d = data as Record<string, unknown>;
+    for (const k of ["data", "sessions", "items"]) {
+      if (k in d) return d[k] as Record<string, unknown>;
+    }
+  }
+  return data as Record<string, unknown>;
+}
+
+function unwrapList(data: unknown): Record<string, unknown>[] {
+  if (Array.isArray(data)) return data as Record<string, unknown>[];
+  if (data && typeof data === "object") {
+    const d = data as Record<string, unknown>;
+    for (const k of ["data", "sessions", "items"]) {
+      if (Array.isArray(d[k])) return d[k] as Record<string, unknown>[];
+    }
+  }
+  return [];
+}
+
+export interface BuilderSessionListParams {
+  limit?: number;
+  [key: string]: string | number | boolean | undefined;
+}
+
+export class BuilderSessions {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(
+    params: BuilderSessionListParams = {},
+  ): Promise<Record<string, unknown>[]> {
+    const query = { limit: 50, ...params } as Record<
+      string,
+      string | number | boolean | undefined
+    >;
+    return unwrapList(await this.http.get<unknown>("/builder/sessions", query));
+  }
+
+  /**
+   * Get a single session. The platform router only exposes index +
+   * title-update + delete, so this filters list() client-side.
+   */
+  async get(sessionId: string): Promise<Record<string, unknown>> {
+    const all = await this.list();
+    return (
+      all.find((s) => (s as Record<string, unknown>).id === sessionId) ?? {}
+    );
+  }
+
+  async updateTitle(
+    sessionId: string,
+    title: string,
+  ): Promise<Record<string, unknown>> {
+    return unwrap(
+      await this.http.patch<unknown>(`/builder/sessions/${sessionId}/title`, {
+        title,
+      }),
+    );
+  }
+
+  async delete(sessionId: string): Promise<void> {
+    await this.http.delete(`/builder/sessions/${sessionId}`);
+  }
+}

package/src/resources/channels.ts

@@ -0,0 +1,143 @@
+/**
+ * Channels — notification preferences + per-channel enable/disable.
+ */
+
+import type { HttpClient } from "../http.js";
+
+// ── Resource shapes ──────────────────────────────────────────────────────────
+
+export interface ChannelData {
+  id?: string;
+  type?: string;
+  name?: string;
+  enabled?: boolean;
+  config?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+// ── Request payloads ─────────────────────────────────────────────────────────
+
+export interface ChannelListParams {
+  type?: string;
+  enabled?: boolean;
+  [key: string]: string | number | boolean | undefined;
+}
+
+export interface ChannelCreateParams {
+  type: string;
+  name?: string;
+  config?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface ChannelUpdateParams {
+  name?: string;
+  config?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface NotificationPrefsUpdateParams {
+  [key: string]: unknown;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function unwrap<T>(payload: unknown): T {
+  if (payload && typeof payload === "object") {
+    const p = payload as Record<string, unknown>;
+    for (const k of ["data", "channels", "notifications", "items"]) {
+      if (k in p) return p[k] as T;
+    }
+  }
+  return payload as T;
+}
+
+function stripUndefined(
+  input: Record<string, unknown>,
+): Record<string, string | number | boolean | undefined> {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, v]) => v !== undefined),
+  ) as Record<string, string | number | boolean | undefined>;
+}
+
+function stripUndefObj(
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, v]) => v !== undefined),
+  );
+}
+
+// ── Main resource ─────────────────────────────────────────────────────────────
+
+export class Channels {
+  constructor(private readonly http: HttpClient) {}
+
+  /** List all channels for the tenant. */
+  async list(params: ChannelListParams = {}): Promise<ChannelData[]> {
+    const query = stripUndefined(params as Record<string, unknown>);
+    const data = await this.http.get<unknown>("/channels", query);
+    const result = unwrap<ChannelData[] | unknown>(data);
+    if (Array.isArray(result)) return result;
+    return [];
+  }
+
+  /** Get a single channel. */
+  async get(channelId: string): Promise<ChannelData> {
+    const data = await this.http.get<unknown>(`/channels/${channelId}`);
+    return unwrap<ChannelData>(data);
+  }
+
+  /** Create a new channel. */
+  async create(params: ChannelCreateParams): Promise<ChannelData> {
+    const body = stripUndefObj(params as Record<string, unknown>);
+    const data = await this.http.post<unknown>("/channels", body);
+    return unwrap<ChannelData>(data);
+  }
+
+  /** Update a channel. */
+  async update(
+    channelId: string,
+    params: ChannelUpdateParams,
+  ): Promise<ChannelData> {
+    const body = stripUndefObj(params as Record<string, unknown>);
+    const data = await this.http.patch<unknown>(`/channels/${channelId}`, body);
+    return unwrap<ChannelData>(data);
+  }
+
+  /** Delete a channel. */
+  async delete(channelId: string): Promise<void> {
+    await this.http.delete<unknown>(`/channels/${channelId}`);
+  }
+
+  // ── Notification preferences ───────────────────────────────────────────────
+
+  /** Get notification preferences across all channels. */
+  async listNotifications(): Promise<Record<string, unknown>> {
+    const data = await this.http.get<unknown>("/channels/notifications");
+    return unwrap<Record<string, unknown>>(data);
+  }
+
+  /** Update notification preferences. */
+  async updateNotifications(
+    params: NotificationPrefsUpdateParams,
+  ): Promise<Record<string, unknown>> {
+    const body = stripUndefObj(params as Record<string, unknown>);
+    const data = await this.http.put<unknown>("/channels/notifications", body);
+    return unwrap<Record<string, unknown>>(data);
+  }
+
+  /** Enable a channel. */
+  async enable(channelId: string): Promise<ChannelData> {
+    const data = await this.http.post<unknown>(`/channels/${channelId}/enable`);
+    return unwrap<ChannelData>(data);
+  }
+
+  /** Disable a channel. */
+  async disable(channelId: string): Promise<ChannelData> {
+    const data = await this.http.post<unknown>(
+      `/channels/${channelId}/disable`,
+    );
+    return unwrap<ChannelData>(data);
+  }
+}

package/src/resources/checkpoints.ts

@@ -0,0 +1,225 @@
+import type { HttpClient } from "../http.js";
+import type { ComputerData } from "../types.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type SnapshotStatus =
+  | "creating"
+  | "uploading"
+  | "ready"
+  | "restoring"
+  | "failed"
+  | "deleted";
+
+export interface SnapshotData {
+  id: string;
+  computer_id: string;
+  tenant_id: string;
+  comment: string | null;
+  status: SnapshotStatus;
+  state_size_bytes: number | null;
+  memory_size_bytes: number | null;
+  rootfs_size_bytes: number | null;
+  compressed_size_bytes: number | null;
+  s3_bucket: string | null;
+  s3_prefix: string | null;
+  parent_snapshot_id: string | null;
+  error: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface SnapshotCreateParams {
+  /** Optional human-readable label for this checkpoint. */
+  comment?: string;
+}
+
+export interface SnapshotRestoreResult {
+  /** The newly provisioned Computer booted from this snapshot. */
+  data: ComputerData;
+  /** The source snapshot used for the restore. */
+  snapshot: SnapshotData;
+}
+
+export interface SnapshotListResponse {
+  data: SnapshotData[];
+}
+
+export type SnapshotProgressEvent = {
+  type: "snapshot_progress";
+  snapshot_id: string;
+  status: SnapshotStatus | string;
+  step?: string;
+  progress?: number;
+  error?: string;
+};
+
+// ─── Checkpoints ─────────────────────────────────────────────────────────────
+
+/**
+ * Firecracker microVM checkpoint management for a Computer.
+ *
+ * Accessed via `computer.checkpoints`.
+ *
+ * @example
+ * ```ts
+ * const snap = await computer.checkpoints.create({ comment: "before upgrade" });
+ * // ... do risky work ...
+ * const fresh = await computer.checkpoints.restore(snap.id);
+ * ```
+ */
+export class Checkpoints {
+  private readonly http: HttpClient;
+  private readonly computerId: string;
+
+  constructor(http: HttpClient, computerId: string) {
+    this.http = http;
+    this.computerId = computerId;
+  }
+
+  private base(): string {
+    return `/computers/${this.computerId}/snapshots`;
+  }
+
+  /**
+   * Create a checkpoint of the running computer.
+   *
+   * The returned snapshot starts in `creating` status and progresses
+   * through `uploading` → `ready` asynchronously. Poll `get()` or subscribe
+   * to progress events via `onProgress` to know when it's ready.
+   *
+   * @param params - Optional `comment` label.
+   * @param onProgress - Optional callback fired for each SSE progress event.
+   *   Only called if a SSE ticket is available (the `events` endpoint requires
+   *   a prior `POST /api/v1/auth/sse-ticket` call).
+   */
+  async create(
+    params: SnapshotCreateParams = {},
+    onProgress?: (event: SnapshotProgressEvent) => void,
+  ): Promise<SnapshotData> {
+    const resp = await this.http.post<{ data: SnapshotData }>(
+      this.base(),
+      params,
+    );
+    const snap = resp.data;
+
+    if (onProgress) {
+      // Fire-and-forget progress subscription — caller decides how to await.
+      void this.subscribeProgress(snap.id, onProgress).catch(() => {
+        // Ignore SSE errors — the snapshot still proceeds on the server.
+      });
+    }
+
+    return snap;
+  }
+
+  /**
+   * List all non-deleted checkpoints for this computer.
+   */
+  async list(): Promise<SnapshotData[]> {
+    const resp = await this.http.get<SnapshotListResponse>(this.base());
+    return resp.data;
+  }
+
+  /**
+   * Fetch a single checkpoint by id.
+   */
+  async get(id: string): Promise<SnapshotData> {
+    const resp = await this.http.get<{ data: SnapshotData }>(
+      `${this.base()}/${id}`,
+    );
+    return resp.data;
+  }
+
+  /**
+   * Delete a checkpoint.
+   *
+   * Transitions the snapshot to `deleted` and schedules S3 cleanup on the
+   * server. After deletion the snapshot object is returned with
+   * `status: "deleted"`.
+   */
+  async delete(id: string): Promise<SnapshotData> {
+    const resp = await this.http.delete<{ data: SnapshotData }>(
+      `${this.base()}/${id}`,
+    );
+    return resp.data;
+  }
+
+  /**
+   * Restore a checkpoint onto a fresh Computer.
+   *
+   * The returned Computer starts in `provisioning` status. Use
+   * `computer.checkpoints.restore(id, onProgress)` to subscribe to restore
+   * progress events.
+   *
+   * @param id - Snapshot id to restore (must be in `ready` status).
+   * @param onProgress - Optional callback for SSE progress events during restore.
+   * @returns A `SnapshotRestoreResult` containing the new Computer and the
+   *   source snapshot.
+   */
+  async restore(
+    id: string,
+    onProgress?: (event: SnapshotProgressEvent) => void,
+  ): Promise<SnapshotRestoreResult> {
+    const resp = await this.http.post<SnapshotRestoreResult>(
+      `/computers/${this.computerId}/restore/${id}`,
+    );
+
+    if (onProgress) {
+      void this.subscribeProgress(id, onProgress).catch(() => {});
+    }
+
+    return resp;
+  }
+
+  /**
+   * Subscribe to Server-Sent Events for a snapshot's progress.
+   *
+   * Yields `SnapshotProgressEvent` objects until the stream closes or
+   * `status` reaches a terminal state (`ready`, `failed`, `deleted`).
+   *
+   * Requires a valid SSE ticket obtained via
+   * `POST /api/v1/auth/sse-ticket` and passed as `?ticket=<token>`.
+   *
+   * @param id - Snapshot id to watch.
+   * @param ticket - Short-lived SSE ticket from the auth endpoint.
+   */
+  async *events(
+    id: string,
+    ticket: string,
+  ): AsyncIterableIterator<SnapshotProgressEvent> {
+    const path = `${this.base()}/${id}/events?ticket=${encodeURIComponent(ticket)}`;
+
+    for await (const event of this.http.stream<SnapshotProgressEvent>(path)) {
+      yield event;
+
+      if (
+        event.status === "ready" ||
+        event.status === "failed" ||
+        event.status === "deleted"
+      ) {
+        return;
+      }
+    }
+  }
+
+  // ── Private ──────────────────────────────────────────────────────────
+
+  /**
+   * Internal: subscribe to SSE progress events and call `cb` for each.
+   *
+   * Resolves when the stream closes. Any auth/network errors are silently
+   * swallowed so the caller isn't blocked on progress-tracking failures.
+   */
+  private async subscribeProgress(
+    id: string,
+    cb: (event: SnapshotProgressEvent) => void,
+  ): Promise<void> {
+    // We don't have a ticket here (the SDK caller would need to obtain one
+    // separately). This internal helper is a no-op placeholder — the public
+    // `events()` iterator is the proper SSE interface.
+    // Left here for future wiring once ticket issuance is unified.
+    void id;
+    void cb;
+  }
+}

package/src/resources/command-center.ts

@@ -0,0 +1,73 @@
+/**
+ * CommandCenter — agent fleet, orchestrations, metrics.
+ *
+ * Routes: /command-center/*
+ * Requires JWT or msk_u_* API key.
+ */
+
+import type { HttpClient } from "../http.js";
+
+function unwrap(data: unknown): Record<string, unknown> {
+  if (data && typeof data === "object") {
+    const d = data as Record<string, unknown>;
+    for (const k of [
+      "data",
+      "agents",
+      "running",
+      "metrics",
+      "presets",
+      "tiers",
+      "items",
+    ]) {
+      if (k in d) return d[k] as Record<string, unknown>;
+    }
+  }
+  return data as Record<string, unknown>;
+}
+
+function unwrapList(data: unknown): Record<string, unknown>[] {
+  if (Array.isArray(data)) return data as Record<string, unknown>[];
+  if (data && typeof data === "object") {
+    const d = data as Record<string, unknown>;
+    for (const k of ["data", "agents", "running", "presets", "items"]) {
+      if (Array.isArray(d[k])) return d[k] as Record<string, unknown>[];
+    }
+  }
+  return [];
+}
+
+export class CommandCenter {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Top-level snapshot (GET /command-center). */
+  async overview(): Promise<Record<string, unknown>> {
+    return unwrap(await this.http.get<unknown>("/command-center"));
+  }
+
+  async agents(): Promise<Record<string, unknown>[]> {
+    return unwrapList(await this.http.get<unknown>("/command-center/agents"));
+  }
+
+  async runningAgents(): Promise<Record<string, unknown>[]> {
+    return unwrapList(
+      await this.http.get<unknown>("/command-center/agents/running"),
+    );
+  }
+
+  async metrics(): Promise<Record<string, unknown>> {
+    return unwrap(await this.http.get<unknown>("/command-center/metrics"));
+  }
+
+  async presets(): Promise<Record<string, unknown>[]> {
+    return unwrapList(await this.http.get<unknown>("/command-center/presets"));
+  }
+
+  async tiers(): Promise<Record<string, unknown>> {
+    return unwrap(await this.http.get<unknown>("/command-center/tiers"));
+  }
+
+  /** Stream live command-center events via SSE. */
+  events(): AsyncIterableIterator<Record<string, unknown>> {
+    return this.http.stream<Record<string, unknown>>("/command-center/events");
+  }
+}

package/src/resources/community.ts

@@ -0,0 +1,103 @@
+/**
+ * Community — public template + agent catalog with install + rate.
+ *
+ * Routes: /community/*
+ * Requires JWT.
+ */
+
+import type { HttpClient } from "../http.js";
+
+function unwrap(data: unknown): Record<string, unknown> {
+  if (data && typeof data === "object") {
+    const d = data as Record<string, unknown>;
+    for (const k of ["data", "templates", "agents", "items"]) {
+      if (k in d) return d[k] as Record<string, unknown>;
+    }
+  }
+  return data as Record<string, unknown>;
+}
+
+function unwrapList(data: unknown): Record<string, unknown>[] {
+  if (Array.isArray(data)) return data as Record<string, unknown>[];
+  if (data && typeof data === "object") {
+    const d = data as Record<string, unknown>;
+    for (const k of ["data", "templates", "agents", "items"]) {
+      if (Array.isArray(d[k])) return d[k] as Record<string, unknown>[];
+    }
+  }
+  return [];
+}
+
+export class Community {
+  constructor(private readonly http: HttpClient) {}
+
+  // ── Agents ────────────────────────────────────────────────────────────
+
+  async listAgents(
+    filters: Record<string, string | number | boolean | undefined> = {},
+  ): Promise<Record<string, unknown>[]> {
+    const query = Object.fromEntries(
+      Object.entries(filters).filter(([, v]) => v !== undefined),
+    ) as Record<string, string | number | boolean | undefined>;
+    return unwrapList(await this.http.get<unknown>("/community/agents", query));
+  }
+
+  async getAgent(agentId: string): Promise<Record<string, unknown>> {
+    return unwrap(await this.http.get<unknown>(`/community/agents/${agentId}`));
+  }
+
+  // ── Templates ─────────────────────────────────────────────────────────
+
+  async listTemplates(
+    filters: Record<string, string | number | boolean | undefined> = {},
+  ): Promise<Record<string, unknown>[]> {
+    const query = Object.fromEntries(
+      Object.entries(filters).filter(([, v]) => v !== undefined),
+    ) as Record<string, string | number | boolean | undefined>;
+    return unwrapList(
+      await this.http.get<unknown>("/community/templates", query),
+    );
+  }
+
+  async getTemplate(templateId: string): Promise<Record<string, unknown>> {
+    return unwrap(
+      await this.http.get<unknown>(`/community/templates/${templateId}`),
+    );
+  }
+
+  /** Install a community template into the caller's tenant. */
+  async installTemplate(
+    templateId: string,
+    opts: Record<string, unknown> = {},
+  ): Promise<Record<string, unknown>> {
+    const body = Object.fromEntries(
+      Object.entries(opts).filter(([, v]) => v !== undefined),
+    );
+    return unwrap(
+      await this.http.post<unknown>(
+        `/community/templates/${templateId}/install`,
+        body,
+      ),
+    );
+  }
+
+  /** Rate a community template (1–5). */
+  async rateTemplate(
+    templateId: string,
+    rating: number,
+    opts: Record<string, unknown> = {},
+  ): Promise<Record<string, unknown>> {
+    const body = {
+      rating,
+      ...Object.fromEntries(
+        Object.entries(opts).filter(([, v]) => v !== undefined),
+      ),
+    };
+    return unwrap(
+      await this.http.post<unknown>(
+        `/community/templates/${templateId}/rate`,
+        body,
+      ),
+    );
+  }
+}