@miosa/sdk 1.0.0 → 1.1.0

package/src/resources/sandboxes.ts

@@ -1,5 +1,22 @@
 import { MiosaError } from "../errors.js";
 import { HttpClient } from "../http.js";
+import { SandboxAudit } from "./egressAudit.js";
+import { SandboxNetwork } from "./egressNetwork.js";
+import { SandboxSecrets } from "./egressSecrets.js";
+
+function encodeContent(content: string | Uint8Array): string {
+  const bytes =
+    typeof content === "string" ? new TextEncoder().encode(content) : content;
+  const maybeBuffer = (
+    globalThis as {
+      Buffer?: { from(b: Uint8Array): { toString(e: string): string } };
+    }
+  ).Buffer;
+  if (maybeBuffer) return maybeBuffer.from(bytes).toString("base64");
+  let bin = "";
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]!);
+  return btoa(bin);
+}
 
 export const SANDBOX_TEMPLATE = "miosa-sandbox";
 
@@ -47,6 +64,7 @@ export interface SandboxCreateParams {
   tags?: string[];
   idempotencyKey?: string;
   idempotency_key?: string;
+  slug?: string;
   // White-label attribution. See platform/attribution docs.
   externalWorkspaceId?: string;
   external_workspace_id?: string;
@@ -231,6 +249,37 @@ export interface SandboxFileEntry {
   [key: string]: unknown;
 }
 
+export interface SandboxFileTreeNode {
+  path: string;
+  name: string;
+  type: "file" | "dir";
+  size?: number;
+  modified_at?: string;
+  children?: SandboxFileTreeNode[];
+}
+
+export interface SandboxWriteManyEntry {
+  path: string;
+  content: string | Uint8Array;
+}
+
+export interface SandboxWriteManyResult {
+  written: Array<{ path: string; size_bytes: number }>;
+  failed: Array<{ path: string; error: string }>;
+}
+
+export interface SandboxFileChange {
+  type: "created" | "modified" | "deleted";
+  path: string;
+  size_bytes?: number;
+}
+
+export interface SandboxEnvVar {
+  key: string;
+  encrypted: boolean;
+  value?: string;
+}
+
 export interface SandboxFileList {
   path?: string;
   entries: SandboxFileEntry[];
@@ -328,6 +377,7 @@ function createBody(params: SandboxCreateParams = {}): Record<string, unknown> {
     region: params.region,
     entrypoint: params.entrypoint,
     tags: params.tags,
+    slug: params.slug,
     external_workspace_id:
       params.externalWorkspaceId ?? params.external_workspace_id,
     external_user_id: params.externalUserId ?? params.external_user_id,
@@ -403,6 +453,54 @@ export class SandboxFiles {
   download(path: string): Promise<Uint8Array> {
     return this.read(path);
   }
+
+  /** GET /api/v1/sandboxes/{id}/files/tree — recursive directory tree. */
+  async tree(path = "/workspace", depth = 3): Promise<SandboxFileTreeNode> {
+    const http = (this.sandbox as unknown as { http: HttpClient }).http;
+    const response = await http.get<unknown>(
+      `/sandboxes/${this.sandbox.id}/files/tree`,
+      { path, depth },
+    );
+    if (
+      response &&
+      typeof response === "object" &&
+      "data" in (response as object)
+    ) {
+      return (response as { data: SandboxFileTreeNode }).data;
+    }
+    return response as SandboxFileTreeNode;
+  }
+
+  /** POST /api/v1/sandboxes/{id}/files/write-many — write multiple files atomically. */
+  async writeMany(
+    files: SandboxWriteManyEntry[],
+  ): Promise<SandboxWriteManyResult> {
+    const http = (this.sandbox as unknown as { http: HttpClient }).http;
+    const payload = files.map((f) => ({
+      path: f.path,
+      content_base64: encodeContent(f.content),
+    }));
+    const response = await http.post<unknown>(
+      `/sandboxes/${this.sandbox.id}/files/write-many`,
+      { files: payload },
+    );
+    if (
+      response &&
+      typeof response === "object" &&
+      "data" in (response as object)
+    ) {
+      return (response as { data: SandboxWriteManyResult }).data;
+    }
+    return response as SandboxWriteManyResult;
+  }
+
+  /** GET /api/v1/sandboxes/{id}/files/watch (SSE) — live file change events. */
+  watch(): AsyncIterableIterator<SandboxFileChange> {
+    const http = (this.sandbox as unknown as { http: HttpClient }).http;
+    return http.stream<SandboxFileChange>(
+      `/sandboxes/${this.sandbox.id}/files/watch`,
+    );
+  }
 }
 
 export class SandboxPreview {
@@ -571,16 +669,53 @@ export class SandboxPreviews {
 export class SandboxEnv {
   constructor(private readonly sandbox: Sandbox) {}
 
-  /**
-   * Read-only listing of sandbox env vars.
-   * The backend has no per-name CRUD route; use Sandbox.create(env=...) to set values.
-   */
-  async list(): Promise<Record<string, unknown>> {
-    return unwrap(
-      await (this.sandbox as unknown as { http: HttpClient }).http.get<
-        WireEnvelope<Record<string, unknown>>
-      >(`/sandboxes/${this.sandbox.id}/env`),
-    ) as Record<string, unknown>;
+  private get http(): HttpClient {
+    return (this.sandbox as unknown as { http: HttpClient }).http;
+  }
+
+  /** GET /api/v1/sandboxes/{id}/env → list of env vars. */
+  async get(): Promise<SandboxEnvVar[]> {
+    const response = await this.http.get<unknown>(
+      `/sandboxes/${this.sandbox.id}/env`,
+    );
+    if (Array.isArray(response)) return response as SandboxEnvVar[];
+    if (response && typeof response === "object") {
+      const r = response as Record<string, unknown>;
+      for (const k of ["data", "vars", "env", "items"]) {
+        if (Array.isArray(r[k])) return r[k] as SandboxEnvVar[];
+      }
+    }
+    return [];
+  }
+
+  /** @deprecated Use get() */
+  async list(): Promise<SandboxEnvVar[]> {
+    return this.get();
+  }
+
+  /** PUT /api/v1/sandboxes/{id}/env — set (replace) env vars. */
+  async set(
+    vars: Array<{ key: string; value: string; encrypted?: boolean }>,
+  ): Promise<SandboxEnvVar[]> {
+    const response = await this.http.put<unknown>(
+      `/sandboxes/${this.sandbox.id}/env`,
+      { vars },
+    );
+    if (Array.isArray(response)) return response as SandboxEnvVar[];
+    if (response && typeof response === "object") {
+      const r = response as Record<string, unknown>;
+      for (const k of ["data", "vars", "env", "items"]) {
+        if (Array.isArray(r[k])) return r[k] as SandboxEnvVar[];
+      }
+    }
+    return [];
+  }
+
+  /** DELETE /api/v1/sandboxes/{id}/env/{key} — remove a single env var. */
+  async delete(key: string): Promise<void> {
+    await this.http.delete<unknown>(
+      `/sandboxes/${this.sandbox.id}/env/${encodeURIComponent(key)}`,
+    );
   }
 }
 
@@ -616,6 +751,12 @@ export class Sandbox {
   readonly env: SandboxEnv;
   /** Tag replacement. */
   readonly tags: SandboxTags;
+  /** Encrypted secrets + OAuth credentials scoped to this sandbox. */
+  readonly secrets: SandboxSecrets;
+  /** Egress allowlist + policies scoped to this sandbox. */
+  readonly network: SandboxNetwork;
+  /** Egress audit log + live tail scoped to this sandbox. */
+  readonly audit: SandboxAudit;
 
   constructor(
     private readonly http: HttpClient,
@@ -640,6 +781,11 @@ export class Sandbox {
     this.previews = new SandboxPreviews(this);
     this.env = new SandboxEnv(this);
     this.tags = new SandboxTags(this);
+    // Egress (security) namespaces — pre-scoped to this sandbox id.
+    const sandboxId = data.id as string;
+    this.secrets = new SandboxSecrets(http, sandboxId);
+    this.network = new SandboxNetwork(http, sandboxId);
+    this.audit = new SandboxAudit(http, sandboxId);
   }
 
   get id(): SandboxId {
@@ -823,6 +969,89 @@ export class Sandbox {
     await this.http.delete(`/sandboxes/${this.id}/snapshots/${snapshotId}`);
   }
 
+  /**
+   * Fork (clone) this sandbox into a new sandbox via copy-on-write snapshot.
+   * The original sandbox continues running unchanged.
+   */
+  async fork(
+    opts: { name?: string; metadata?: Record<string, unknown> } = {},
+  ): Promise<Sandbox> {
+    this.assertRunning("fork");
+    const body: Record<string, unknown> = {};
+    if (opts.name !== undefined) body.name = opts.name;
+    if (opts.metadata !== undefined) body.metadata = opts.metadata;
+    const data = unwrap(
+      await this.http.post<WireEnvelope<SandboxData>>(
+        `/sandboxes/${this.id}/fork`,
+        body,
+      ),
+    );
+    return new Sandbox(this.http, data);
+  }
+
+  /**
+   * PATCH /api/v1/sandboxes/{id} — update mutable sandbox fields.
+   */
+  async update(params: {
+    name?: string;
+    slug?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    always_on?: boolean;
+    timeout_sec?: number;
+    idle_timeout_sec?: number;
+  }): Promise<Sandbox> {
+    const body: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== undefined) body[k] = v;
+    }
+    const data = unwrap(
+      await this.http.patch<WireEnvelope<SandboxData>>(
+        `/sandboxes/${this.id}`,
+        body,
+      ),
+    );
+    this.data = data;
+    return this;
+  }
+
+  /**
+   * POST /api/v1/sandboxes/{id}/preview-token → {token, url, expires_at, scope}
+   */
+  async previewToken(
+    expiresIn = 3600,
+    scope = "read",
+  ): Promise<{
+    token: string;
+    url: string;
+    expires_at: string;
+    scope: string;
+    [key: string]: unknown;
+  }> {
+    const raw = await this.http.post<unknown>(
+      `/sandboxes/${this.id}/preview-token`,
+      { expires_in: expiresIn, scope },
+    );
+    if (raw && typeof raw === "object" && "data" in (raw as object)) {
+      return (
+        raw as {
+          data: {
+            token: string;
+            url: string;
+            expires_at: string;
+            scope: string;
+          };
+        }
+      ).data;
+    }
+    return raw as {
+      token: string;
+      url: string;
+      expires_at: string;
+      scope: string;
+    };
+  }
+
   async pause(): Promise<Sandbox> {
     const data = unwrap(
       await this.http.post<WireEnvelope<SandboxData>>(

package/src/resources/storage.ts

@@ -49,6 +49,13 @@ export interface BucketCreateParams {
   visibility?: "private" | "public";
   quota_bytes?: number;
   public?: boolean;
+  // White-label attribution
+  externalWorkspaceId?: string;
+  external_workspace_id?: string;
+  externalUserId?: string;
+  external_user_id?: string;
+  externalProjectId?: string;
+  external_project_id?: string;
   [key: string]: unknown;
 }
 

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}`);
+  }
+}

package/src/resources/tenant.ts

@@ -1,5 +1,5 @@
 /**
- * Tenant — current tenant info and plan/usage.
+ * Tenant — current tenant info, preview domain, and branding.
  */
 
 import type { HttpClient } from "../http.js";
@@ -14,22 +14,101 @@ export interface TenantPlan {
   [key: string]: unknown;
 }
 
+export interface PreviewDomainData {
+  domain: string;
+  verified_at?: string | null;
+  cname_target?: string;
+  [key: string]: unknown;
+}
+
+export interface PreviewDomainVerifyResult {
+  verified: boolean;
+  target?: string;
+  records?: unknown[];
+  [key: string]: unknown;
+}
+
+export interface BrandingData {
+  product_name?: string;
+  logo_url?: string;
+  support_url?: string;
+  support_email?: string;
+  primary_color?: string;
+  background_color?: 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", "tenant", "items"]) {
+    for (const k of ["data", "tenant", "branding", "preview_domain", "items"]) {
       if (k in p) return p[k] as T;
     }
   }
   return payload as T;
 }
 
+// ── Sub-resources ─────────────────────────────────────────────────────────────
+
+export class PreviewDomain {
+  constructor(private readonly http: HttpClient) {}
+
+  /** GET /api/v1/tenant/preview-domain → {domain, verified_at, cname_target} */
+  async get(): Promise<PreviewDomainData> {
+    return unwrap(await this.http.get<unknown>("/tenant/preview-domain"));
+  }
+
+  /** PUT /api/v1/tenant/preview-domain — set the preview domain. */
+  async set(domain: string): Promise<PreviewDomainData> {
+    return unwrap(
+      await this.http.put<unknown>("/tenant/preview-domain", { domain }),
+    );
+  }
+
+  /** POST /api/v1/tenant/preview-domain/verify → {verified, target, records} */
+  async verify(): Promise<PreviewDomainVerifyResult> {
+    return unwrap(
+      await this.http.post<unknown>("/tenant/preview-domain/verify", {}),
+    );
+  }
+
+  /** DELETE /api/v1/tenant/preview-domain */
+  async delete(): Promise<void> {
+    await this.http.delete<unknown>("/tenant/preview-domain");
+  }
+}
+
+export class Branding {
+  constructor(private readonly http: HttpClient) {}
+
+  /** GET /api/v1/tenant/branding */
+  async get(): Promise<BrandingData> {
+    return unwrap(await this.http.get<unknown>("/tenant/branding"));
+  }
+
+  /** PUT /api/v1/tenant/branding — keys: product_name, logo_url, support_url, support_email, primary_color, background_color */
+  async set(branding: BrandingData): Promise<BrandingData> {
+    return unwrap(await this.http.put<unknown>("/tenant/branding", branding));
+  }
+
+  /** DELETE /api/v1/tenant/branding */
+  async delete(): Promise<void> {
+    await this.http.delete<unknown>("/tenant/branding");
+  }
+}
+
 // ── Main resource ─────────────────────────────────────────────────────────────
 
 export class Tenant {
-  constructor(private readonly http: HttpClient) {}
+  readonly preview_domain: PreviewDomain;
+  readonly branding: Branding;
+
+  constructor(private readonly http: HttpClient) {
+    this.preview_domain = new PreviewDomain(http);
+    this.branding = new Branding(http);
+  }
 
   /** Get the current tenant's plan, limits, and live usage counters. */
   async current(): Promise<TenantPlan> {

package/src/resources/volumes.ts

@@ -40,6 +40,13 @@ export interface VolumeCreateParams {
   sizeGb?: number;
   region?: string;
   idempotencyKey?: string;
+  // White-label attribution
+  externalWorkspaceId?: string;
+  external_workspace_id?: string;
+  externalUserId?: string;
+  external_user_id?: string;
+  externalProjectId?: string;
+  external_project_id?: string;
   [key: string]: unknown;
 }
 

package/src/resources/webhooks.ts

@@ -2,10 +2,48 @@
  * Webhooks resource — tenant outgoing event delivery.
  */
 
+import { createHmac, timingSafeEqual } from "node:crypto";
 import { randomUUID } from "node:crypto";
 
 import type { HttpClient } from "../http.js";
 
+const MAX_TIMESTAMP_AGE_MS = 5 * 60 * 1000;
+
+/**
+ * Verify an incoming ``X-Miosa-Signature`` header.
+ * Header format: ``t=<unix_ts>,v1=<hex_hmac>``
+ */
+export function verifySignature(
+  payload: string | Uint8Array,
+  signatureHeader: string,
+  secret: string,
+): boolean {
+  const parts: Record<string, string> = {};
+  for (const part of signatureHeader.split(",")) {
+    const idx = part.indexOf("=");
+    if (idx > 0) parts[part.slice(0, idx).trim()] = part.slice(idx + 1).trim();
+  }
+  const tsStr = parts["t"];
+  const sig = parts["v1"];
+  if (!tsStr || !sig) return false;
+
+  const ts = parseInt(tsStr, 10);
+  if (isNaN(ts)) return false;
+  if (Date.now() - ts * 1000 > MAX_TIMESTAMP_AGE_MS) {
+    throw new Error(`Webhook timestamp is too old: ${ts}`);
+  }
+
+  const body =
+    payload instanceof Uint8Array ? payload : Buffer.from(payload, "utf-8");
+  const signed = Buffer.concat([Buffer.from(`${tsStr}.`, "utf-8"), body]);
+  const expected = createHmac("sha256", secret).update(signed).digest("hex");
+
+  return timingSafeEqual(
+    Buffer.from(expected, "utf-8"),
+    Buffer.from(sig, "utf-8"),
+  );
+}
+
 // ── Branded IDs ──────────────────────────────────────────────────────────────
 
 export type WebhookId = string & { readonly __brand: "WebhookId" };
@@ -168,4 +206,21 @@ export class Webhooks {
       "items",
     ]);
   }
+
+  /**
+   * Verify an incoming ``X-Miosa-Signature`` header.
+   *
+   * Header format: ``t=<unix_ts>,v1=<hex_hmac>``
+   * HMAC body:     ``<t>.<raw_payload>``
+   *
+   * Throws if timestamp is older than 5 minutes.
+   * Returns true if signature matches.
+   */
+  static verifySignature(
+    payload: string | Uint8Array,
+    signatureHeader: string,
+    secret: string,
+  ): boolean {
+    return verifySignature(payload, signatureHeader, secret);
+  }
 }