@miosa/sdk 1.0.0 → 1.2.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/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/workspace-invites.ts

@@ -0,0 +1,188 @@
+/**
+ * Workspace Invites — email invite flow for workspace access.
+ *
+ * Sending an invite to an email that already belongs to a tenant member
+ * short-circuits to directly adding that user (returns `type: "added"`).
+ * Accepting a workspace invite for an unknown email auto-creates both a
+ * `tenant_members` and a `workspace_members` row atomically.
+ *
+ * Public endpoints (no auth):
+ *   GET  /workspace-invites/:token
+ *
+ * Authenticated endpoints:
+ *   POST   /workspaces/:id/invites
+ *   GET    /workspaces/:id/invites
+ *   DELETE /workspaces/:id/invites/:invite_id
+ *   POST   /workspace-invites/:token/accept
+ */
+
+import type { HttpClient } from "../http.js";
+import type {
+  WorkspaceMemberRecord,
+  WorkspaceRole,
+} from "./workspace-members.js";
+
+// ── Resource shapes ──────────────────────────────────────────────────────────
+
+export interface WorkspaceInvite {
+  id: string;
+  workspace_id: string;
+  tenant_id: string;
+  email: string;
+  role: WorkspaceRole;
+  invited_by: string | null;
+  expires_at: string;
+  accepted_at: string | null;
+  inserted_at: string;
+}
+
+export interface WorkspaceInvitePreview {
+  workspace_name: string;
+  tenant_name: string;
+  role: WorkspaceRole;
+  email: string;
+  expires_at: string;
+  expired: boolean;
+  revoked: boolean;
+  accepted: boolean;
+}
+
+// ── Request payloads ─────────────────────────────────────────────────────────
+
+export interface CreateWorkspaceInviteParams {
+  email: string;
+  role?: WorkspaceRole;
+}
+
+// ── Response shapes ───────────────────────────────────────────────────────────
+
+/** Returned when the email was unknown — an invite was created. */
+export interface WorkspaceInviteCreatedResponse {
+  data: WorkspaceInvite;
+  type: "invited";
+}
+
+/** Returned when the email already had a tenant_members row — added directly. */
+export interface WorkspaceMemberAddedResponse {
+  data: WorkspaceMemberRecord;
+  type: "added";
+}
+
+export type CreateWorkspaceInviteResponse =
+  | WorkspaceInviteCreatedResponse
+  | WorkspaceMemberAddedResponse;
+
+export interface WorkspaceInviteListResponse {
+  data: WorkspaceInvite[];
+  total: number;
+}
+
+export interface WorkspaceInviteRevokeResponse {
+  invite_id: string;
+  revoked: boolean;
+}
+
+export interface WorkspaceInvitePreviewResponse {
+  data: WorkspaceInvitePreview;
+}
+
+export interface AcceptWorkspaceInviteResponse {
+  accepted: boolean;
+  workspace_id: string;
+  tenant_id: string;
+  role: WorkspaceRole;
+}
+
+// ── Main resource ─────────────────────────────────────────────────────────────
+
+export class WorkspaceInvites {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * Create a workspace invite or add a member directly.
+   *
+   * If `email` already maps to a tenant member the user is added directly and
+   * `type === "added"` is returned with a `WorkspaceMemberRecord`. Otherwise
+   * an invite row is created and `type === "invited"` is returned.
+   *
+   * `POST /workspaces/:id/invites`
+   */
+  async create(
+    workspaceId: string,
+    params: CreateWorkspaceInviteParams,
+  ): Promise<CreateWorkspaceInviteResponse> {
+    return this.http.post<CreateWorkspaceInviteResponse>(
+      `/workspaces/${workspaceId}/invites`,
+      params,
+    );
+  }
+
+  /**
+   * List all pending (non-expired, non-accepted, non-revoked) workspace invites.
+   *
+   * `GET /workspaces/:id/invites`
+   */
+  async list(workspaceId: string): Promise<WorkspaceInvite[]> {
+    const res = await this.http.get<WorkspaceInviteListResponse>(
+      `/workspaces/${workspaceId}/invites`,
+    );
+    return res.data ?? [];
+  }
+
+  /**
+   * Revoke a pending workspace invite.
+   *
+   * Already-revoked invites are idempotent (returns `revoked: true`). An invite
+   * that was legitimately accepted throws `409 ALREADY_ACCEPTED`.
+   *
+   * `DELETE /workspaces/:id/invites/:invite_id`
+   */
+  async revoke(
+    workspaceId: string,
+    inviteId: string,
+  ): Promise<WorkspaceInviteRevokeResponse> {
+    return this.http.delete<WorkspaceInviteRevokeResponse>(
+      `/workspaces/${workspaceId}/invites/${inviteId}`,
+    );
+  }
+
+  /**
+   * Preview a workspace invite by token (no auth required).
+   *
+   * Use this to render the invite landing page before prompting the user to
+   * log in or sign up. Returns `null` when the token is unknown or revoked.
+   *
+   * `GET /workspace-invites/:token`
+   */
+  async preview(token: string): Promise<WorkspaceInvitePreview | null> {
+    try {
+      const res = await this.http.get<WorkspaceInvitePreviewResponse>(
+        `/workspace-invites/${token}`,
+      );
+      return res.data ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Accept a workspace invite on behalf of the authenticated user.
+   *
+   * The caller's JWT email must match the invite email (case-insensitive).
+   *
+   * Error codes:
+   * - `INVALID_TOKEN` (404) — token not found.
+   * - `EXPIRED` (410) — invite TTL elapsed.
+   * - `REVOKED` (409) — invite was revoked.
+   * - `ALREADY_ACCEPTED` (409) — already used.
+   * - `EMAIL_MISMATCH` (422) — JWT email differs from invite email.
+   *
+   * `POST /workspace-invites/:token/accept`
+   */
+  async accept(token: string): Promise<AcceptWorkspaceInviteResponse> {
+    return this.http.post<AcceptWorkspaceInviteResponse>(
+      `/workspace-invites/${token}/accept`,
+      {},
+    );
+  }
+}

package/src/resources/workspace-members.test.ts

@@ -0,0 +1,121 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { HttpClient } from "../http.js";
+import { WorkspaceMembers } from "./workspace-members.js";
+
+const mockGet = vi.fn();
+const mockPost = vi.fn();
+const mockPatch = vi.fn();
+const mockDelete = vi.fn();
+const mockRequest = vi.fn();
+
+function makeHttp(): HttpClient {
+  const http = {} as HttpClient;
+  http.get = mockGet;
+  http.post = mockPost;
+  http.patch = mockPatch;
+  http.delete = mockDelete;
+  http.request = mockRequest;
+  return http;
+}
+
+const MEMBER = {
+  user_id: "usr_abc",
+  email: "alice@example.com",
+  name: "Alice",
+  avatar_url: null,
+  role: "member" as const,
+  joined_at: "2026-05-01T10:00:00Z",
+  added_by: null,
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("WorkspaceMembers", () => {
+  describe("list()", () => {
+    it("calls GET /workspaces/:id/members and returns array", async () => {
+      mockGet.mockResolvedValue({ data: [MEMBER] });
+      const resource = new WorkspaceMembers(makeHttp());
+
+      const result = await resource.list("ws-uuid");
+
+      expect(mockGet).toHaveBeenCalledWith("/workspaces/ws-uuid/members");
+      expect(result).toHaveLength(1);
+      expect(result[0].user_id).toBe("usr_abc");
+      expect(result[0].email).toBe("alice@example.com");
+      expect(result[0].role).toBe("member");
+    });
+
+    it("returns empty array when data is empty", async () => {
+      mockGet.mockResolvedValue({ data: [] });
+      const resource = new WorkspaceMembers(makeHttp());
+
+      const result = await resource.list("ws-uuid");
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe("add()", () => {
+    it("calls POST /workspaces/:id/members with userId and role", async () => {
+      const record = {
+        user_id: "usr_def",
+        workspace_id: "ws-uuid",
+        role: "member",
+        joined_at: "2026-05-22T09:00:00Z",
+        added_by: "usr_abc",
+      };
+      mockPost.mockResolvedValue({ data: record });
+      const resource = new WorkspaceMembers(makeHttp());
+
+      const result = await resource.add("ws-uuid", {
+        user_id: "usr_def",
+        role: "member",
+      });
+
+      expect(mockPost).toHaveBeenCalledWith(
+        "/workspaces/ws-uuid/members",
+        expect.objectContaining({ user_id: "usr_def", role: "member" }),
+      );
+      expect(result.user_id).toBe("usr_def");
+      expect(result.role).toBe("member");
+    });
+  });
+
+  describe("updateRole()", () => {
+    it("calls PATCH /workspaces/:id/members/:userId with new role", async () => {
+      const updated = {
+        user_id: "usr_def",
+        workspace_id: "ws-uuid",
+        role: "admin",
+        joined_at: "2026-05-22T09:00:00Z",
+        added_by: "usr_abc",
+      };
+      mockPatch.mockResolvedValue({ data: updated });
+      const resource = new WorkspaceMembers(makeHttp());
+
+      const result = await resource.updateRole("ws-uuid", "usr_def", {
+        role: "admin",
+      });
+
+      expect(mockPatch).toHaveBeenCalledWith(
+        "/workspaces/ws-uuid/members/usr_def",
+        { role: "admin" },
+      );
+      expect(result.role).toBe("admin");
+    });
+  });
+
+  describe("remove()", () => {
+    it("calls DELETE /workspaces/:id/members/:userId", async () => {
+      mockDelete.mockResolvedValue({ deleted: true });
+      const resource = new WorkspaceMembers(makeHttp());
+
+      await resource.remove("ws-uuid", "usr_def");
+
+      expect(mockDelete).toHaveBeenCalledWith(
+        "/workspaces/ws-uuid/members/usr_def",
+      );
+    });
+  });
+});