@miosa/sdk 0.3.0

package/src/resources/project-integrations.ts

@@ -0,0 +1,133 @@
+/**
+ * Project integrations — third-party API key connections injected into VMs.
+ */
+
+import type { HttpClient } from "../http.js";
+
+// ── Resource shapes ──────────────────────────────────────────────────────────
+
+export interface ProjectIntegrationData {
+  id?: string;
+  project_id?: string;
+  provider?: string;
+  status?: string;
+  [key: string]: unknown;
+}
+
+export interface ProjectIntegrationCatalogEntry {
+  provider?: string;
+  name?: string;
+  description?: string;
+  schema?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+// ── Request payloads ─────────────────────────────────────────────────────────
+
+export interface ProjectIntegrationListParams {
+  project_id?: string;
+  provider?: string;
+  [key: string]: string | number | boolean | undefined;
+}
+
+export interface ProjectIntegrationCreateParams {
+  project_id?: string;
+  provider?: string;
+  credentials?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface ProjectIntegrationUpdateParams {
+  credentials?: Record<string, unknown>;
+  [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", "project_integrations", "catalog", "items"]) {
+      if (k in p) return p[k] as T;
+    }
+  }
+  return payload as T;
+}
+
+function listItems<T>(payload: unknown): T[] {
+  const result = unwrap<T[] | unknown>(payload);
+  if (Array.isArray(result)) return result;
+  return [];
+}
+
+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 ProjectIntegrations {
+  constructor(private readonly http: HttpClient) {}
+
+  /** List project integrations. */
+  async list(
+    params: ProjectIntegrationListParams = {},
+  ): Promise<ProjectIntegrationData[]> {
+    const query = stripUndefined(params as Record<string, unknown>);
+    const data = await this.http.get<unknown>("/project-integrations", query);
+    return listItems<ProjectIntegrationData>(data);
+  }
+
+  /** List supported providers and their schemas. */
+  async catalog(): Promise<ProjectIntegrationCatalogEntry[]> {
+    const data = await this.http.get<unknown>("/project-integrations/catalog");
+    return listItems<ProjectIntegrationCatalogEntry>(data);
+  }
+
+  /** Get a project integration by id. */
+  async get(integrationId: string): Promise<ProjectIntegrationData> {
+    const data = await this.http.get<unknown>(
+      `/project-integrations/${integrationId}`,
+    );
+    return unwrap<ProjectIntegrationData>(data);
+  }
+
+  /** Create a project integration. */
+  async create(
+    params: ProjectIntegrationCreateParams,
+  ): Promise<ProjectIntegrationData> {
+    const body = stripUndefObj(params as Record<string, unknown>);
+    const data = await this.http.post<unknown>("/project-integrations", body);
+    return unwrap<ProjectIntegrationData>(data);
+  }
+
+  /** Update a project integration. */
+  async update(
+    integrationId: string,
+    params: ProjectIntegrationUpdateParams,
+  ): Promise<ProjectIntegrationData> {
+    const body = stripUndefObj(params as Record<string, unknown>);
+    const data = await this.http.patch<unknown>(
+      `/project-integrations/${integrationId}`,
+      body,
+    );
+    return unwrap<ProjectIntegrationData>(data);
+  }
+
+  /** Delete a project integration. */
+  async delete(integrationId: string): Promise<void> {
+    await this.http.delete<unknown>(`/project-integrations/${integrationId}`);
+  }
+}

package/src/resources/provider-defaults.ts

@@ -0,0 +1,89 @@
+/**
+ * ProviderDefaults — admin LLM provider routing config.
+ *
+ * Routes:
+ *   GET  /admin/provider-defaults
+ *   PUT  /admin/provider-defaults
+ *   GET  /admin/tenants/:id/provider-config
+ *   PUT  /admin/tenants/:id/provider-config
+ *   DELETE /admin/tenants/:id/provider-config
+ *
+ * Requires admin credential (msk_a_* / msk_p_* or admin 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", "defaults", "provider_defaults", "config"]) {
+      if (k in d) return d[k] as Record<string, unknown>;
+    }
+  }
+  return data as Record<string, unknown>;
+}
+
+export class ProviderDefaults {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Get the current fleet-wide provider defaults. */
+  async list(): Promise<Record<string, unknown>> {
+    return unwrap(await this.http.get<unknown>("/admin/provider-defaults"));
+  }
+
+  /** Return the defaults entry for a single provider, or {} if missing. */
+  async get(provider: string): Promise<Record<string, unknown>> {
+    const data = await this.list();
+    const providers =
+      (data.providers as Record<string, unknown> | undefined) ?? data;
+    if (
+      typeof providers === "object" &&
+      providers !== null &&
+      provider in providers
+    ) {
+      return providers[provider] as Record<string, unknown>;
+    }
+    return {};
+  }
+
+  /** Replace the fleet-wide defaults (PUT /admin/provider-defaults). */
+  async update(
+    opts: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
+    const body = Object.fromEntries(
+      Object.entries(opts).filter(([, v]) => v !== undefined),
+    );
+    return unwrap(
+      await this.http.put<unknown>("/admin/provider-defaults", body),
+    );
+  }
+
+  // ── Per-tenant overrides ────────────────────────────────────────────────
+
+  async getTenant(tenantId: string): Promise<Record<string, unknown>> {
+    return unwrap(
+      await this.http.get<unknown>(
+        `/admin/tenants/${tenantId}/provider-config`,
+      ),
+    );
+  }
+
+  async setTenant(
+    tenantId: 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.put<unknown>(
+        `/admin/tenants/${tenantId}/provider-config`,
+        body,
+      ),
+    );
+  }
+
+  async resetTenant(tenantId: string): Promise<void> {
+    await this.http.delete(`/admin/tenants/${tenantId}/provider-config`);
+  }
+}

package/src/resources/regions.ts

@@ -0,0 +1,94 @@
+/**
+ * Regions — datacenter availability, sizes, pricing, templates.
+ */
+
+import type { HttpClient } from "../http.js";
+
+// ── Resource shapes ──────────────────────────────────────────────────────────
+
+export interface RegionData {
+  id?: string;
+  name?: string;
+  slug?: string;
+  available?: boolean;
+  [key: string]: unknown;
+}
+
+export interface SizeData {
+  id?: string;
+  name?: string;
+  slug?: string;
+  cpu?: number;
+  memory_mb?: number;
+  [key: string]: unknown;
+}
+
+export interface TemplateData {
+  id?: string;
+  name?: string;
+  slug?: string;
+  [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",
+      "regions",
+      "sizes",
+      "pricing",
+      "templates",
+      "items",
+    ]) {
+      if (k in p) return p[k] as T;
+    }
+  }
+  return payload as T;
+}
+
+function listItems<T>(payload: unknown): T[] {
+  const result = unwrap<T[] | unknown>(payload);
+  if (Array.isArray(result)) return result;
+  return [];
+}
+
+// ── Main resource ─────────────────────────────────────────────────────────────
+
+export class Regions {
+  constructor(private readonly http: HttpClient) {}
+
+  /** List datacenter regions. */
+  async listRegions(): Promise<RegionData[]> {
+    const data = await this.http.get<unknown>("/compute/regions");
+    return listItems<RegionData>(data);
+  }
+
+  /** List available compute sizes. */
+  async listSizes(): Promise<SizeData[]> {
+    const data = await this.http.get<unknown>("/compute/sizes");
+    return listItems<SizeData>(data);
+  }
+
+  /** Get static compute pricing data. */
+  async pricing(): Promise<unknown> {
+    const data = await this.http.get<unknown>("/compute/pricing");
+    return unwrap(data);
+  }
+
+  /** List community computer templates. */
+  async listTemplates(): Promise<TemplateData[]> {
+    const data = await this.http.get<unknown>("/compute/templates");
+    return listItems<TemplateData>(data);
+  }
+
+  /** Get a single community template by id. */
+  async getTemplate(templateId: string): Promise<TemplateData> {
+    const data = await this.http.get<unknown>(
+      `/compute/templates/${templateId}`,
+    );
+    return unwrap<TemplateData>(data);
+  }
+}

package/src/resources/sandbox-templates.ts

@@ -0,0 +1,195 @@
+/**
+ * SandboxTemplates resource — tenant sandbox template management.
+ */
+
+import { randomUUID } from "node:crypto";
+
+import type { HttpClient } from "../http.js";
+
+// ── Branded IDs ──────────────────────────────────────────────────────────────
+
+export type SandboxTemplateResourceId = string & {
+  readonly __brand: "SandboxTemplateResourceId";
+};
+export type SandboxTemplateBuildResourceId = string & {
+  readonly __brand: "SandboxTemplateBuildResourceId";
+};
+
+// ── Resource shapes ──────────────────────────────────────────────────────────
+
+export interface SandboxTemplateResourceData {
+  id: SandboxTemplateResourceId;
+  tenant_id: string;
+  name: string;
+  state?: string;
+  build_spec?: Record<string, unknown>;
+  aliases?: string[];
+  created_at?: string;
+  updated_at?: string;
+  [key: string]: unknown;
+}
+
+export interface SandboxTemplateBuildResourceData {
+  id: SandboxTemplateBuildResourceId;
+  template_id: SandboxTemplateResourceId;
+  state?: string;
+  started_at?: string | null;
+  finished_at?: string | null;
+  error?: string | null;
+  created_at?: string;
+  [key: string]: unknown;
+}
+
+// ── Request payloads ─────────────────────────────────────────────────────────
+
+export interface SandboxTemplateListParams {
+  include_aliases?: boolean;
+  includeAliases?: boolean;
+}
+
+export interface TemplateCreateParams {
+  name: string;
+  build_spec: Record<string, unknown>;
+  buildSpec?: Record<string, unknown>;
+  idempotencyKey?: string;
+  [key: string]: unknown;
+}
+
+export interface TemplateBuildCreateParams {
+  idempotencyKey?: string;
+  [key: string]: unknown;
+}
+
+// ── 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,
+  candidateKeys: string[] = ["data", "templates", "builds", "items"],
+): T[] {
+  if (Array.isArray(payload)) return payload;
+  if (!payload || typeof payload !== "object") return [];
+  const p = payload as Record<string, unknown>;
+  if (Array.isArray(p.data)) return p.data as T[];
+  for (const key of candidateKeys) {
+    if (Array.isArray(p[key])) return p[key] as T[];
+  }
+  return [];
+}
+
+function stripUndefined(
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, v]) => v !== undefined),
+  );
+}
+
+function idempotencyKey(key?: string): string {
+  return key ?? randomUUID();
+}
+
+// ── Main resource ─────────────────────────────────────────────────────────────
+
+export class SandboxTemplates {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(
+    params: SandboxTemplateListParams = {},
+  ): Promise<SandboxTemplateResourceData[]> {
+    const includeAliases =
+      params.includeAliases ?? params.include_aliases ?? false;
+    const query = includeAliases
+      ? ({ include_aliases: true } as Record<
+          string,
+          string | number | boolean | undefined
+        >)
+      : undefined;
+    const data = await this.http.get<unknown>("/sandbox-templates", query);
+    return listItems<SandboxTemplateResourceData>(data, [
+      "data",
+      "templates",
+      "items",
+    ]);
+  }
+
+  async get(templateId: string): Promise<SandboxTemplateResourceData> {
+    const data = await this.http.get<unknown>(
+      `/sandbox-templates/${templateId}`,
+    );
+    return unwrap<SandboxTemplateResourceData>(data);
+  }
+
+  async create(
+    params: TemplateCreateParams,
+  ): Promise<SandboxTemplateResourceData> {
+    const {
+      idempotencyKey: ikey,
+      buildSpec,
+      build_spec,
+      name,
+      ...rest
+    } = params;
+    const body = stripUndefined({
+      name,
+      build_spec: buildSpec ?? build_spec,
+      ...rest,
+    });
+    const data = await this.http.request<unknown>("/sandbox-templates", {
+      method: "POST",
+      body,
+      headers: { "Idempotency-Key": idempotencyKey(ikey) },
+    });
+    return unwrap<SandboxTemplateResourceData>(data);
+  }
+
+  async buildSpecSchema(): Promise<Record<string, unknown>> {
+    const data = await this.http.get<unknown>("/sandbox-templates/build-spec");
+    return (data ?? {}) as Record<string, unknown>;
+  }
+
+  async validate(
+    buildSpec: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
+    const data = await this.http.post<unknown>("/sandbox-templates/validate", {
+      build_spec: buildSpec,
+    });
+    return (data ?? {}) as Record<string, unknown>;
+  }
+
+  async listBuilds(
+    templateId: string,
+  ): Promise<SandboxTemplateBuildResourceData[]> {
+    const data = await this.http.get<unknown>(
+      `/sandbox-templates/${templateId}/builds`,
+    );
+    return listItems<SandboxTemplateBuildResourceData>(data, [
+      "data",
+      "builds",
+      "items",
+    ]);
+  }
+
+  async createBuild(
+    templateId: string,
+    params: TemplateBuildCreateParams = {},
+  ): Promise<SandboxTemplateBuildResourceData> {
+    const { idempotencyKey: ikey, ...rest } = params;
+    const body = stripUndefined(rest as Record<string, unknown>);
+    const data = await this.http.request<unknown>(
+      `/sandbox-templates/${templateId}/builds`,
+      {
+        method: "POST",
+        body,
+        headers: { "Idempotency-Key": idempotencyKey(ikey) },
+      },
+    );
+    return unwrap<SandboxTemplateBuildResourceData>(data);
+  }
+}

package/src/resources/sandboxes.live.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import { Miosa } from "../client.js";
+import type { Sandbox } from "./sandboxes.js";
+
+const liveApiKey = process.env.MIOSA_API_KEY;
+const liveBaseUrl = process.env.MIOSA_BASE_URL ?? "https://api.miosa.ai/api/v1";
+const describeLive = liveApiKey ? describe : describe.skip;
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function waitReady(sandbox: Sandbox, timeoutMs = 60_000): Promise<Sandbox> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await sandbox.refresh();
+    if (sandbox.state === "running" && sandbox.ready) return sandbox;
+    await sleep(500);
+  }
+  throw new Error(`sandbox ${sandbox.id} was not ready within ${timeoutMs}ms`);
+}
+
+describeLive("live native sandbox API", () => {
+  it(
+    "creates, execs, writes files, exposes preview, and destroys",
+    async () => {
+      const client = new Miosa({
+        apiKey: liveApiKey!,
+        baseUrl: liveBaseUrl,
+        timeout: 60_000,
+        maxRetries: 1,
+      });
+      let sandbox: Sandbox | undefined;
+      const marker = `miosa-ts-live-${Date.now()}`;
+      const port = 32_173;
+
+      try {
+        sandbox = await client.sandboxes.create({
+          name: `sdk-ts-live-${Date.now()}`,
+          templateId: "miosa-sandbox",
+          timeoutSec: 600,
+          metadata: { test: "typescript-live-e2e" },
+        });
+        await waitReady(sandbox);
+
+        const exec = await sandbox.commands.run("python3 -c 'print(21 * 2)'", {
+          timeoutSec: 30,
+        });
+        expect(exec.exitCode).toBe(0);
+        expect(exec.stdout.trim()).toBe("42");
+
+        await sandbox.files.write("/workspace/index.html", `<h1>${marker}</h1>`);
+        expect(await sandbox.files.readText("/workspace/index.html")).toContain(marker);
+        const list = await sandbox.files.list("/workspace");
+        expect(JSON.stringify(list)).toContain("index.html");
+        const stat = await sandbox.files.stat("/workspace/index.html");
+        expect(Number(stat.size ?? 0)).toBeGreaterThan(0);
+
+        await sandbox.commands.run(
+          [
+            "cd /workspace",
+            `nohup python3 -m http.server ${port} --bind 0.0.0.0 >/tmp/miosa-ts-live.log 2>&1 &`,
+          ].join(" && "),
+          { timeoutSec: 10 },
+        );
+
+        let reachable = false;
+        for (let attempt = 0; attempt < 20; attempt += 1) {
+          const probe = await sandbox.commands.run(
+            `python3 - <<'PY'\nimport urllib.request\nprint(urllib.request.urlopen('http://127.0.0.1:${port}', timeout=2).read().decode())\nPY`,
+            { timeoutSec: 5 },
+          );
+          if (probe.exitCode === 0 && probe.stdout.includes(marker)) {
+            reachable = true;
+            break;
+          }
+          await sleep(500);
+        }
+        expect(reachable).toBe(true);
+
+        const previewUrl = await sandbox.preview.expose(port);
+        expect(previewUrl).toMatch(/^https:\/\//);
+        const preview = await fetch(previewUrl);
+        expect(preview.status).toBe(200);
+        expect(await preview.text()).toContain(marker);
+      } finally {
+        if (sandbox) {
+          await sandbox.destroy().catch(() => undefined);
+        }
+      }
+    },
+    120_000,
+  );
+});