feat: add support for listing sandboxes (#33)

Author: CompuIves

src/index.ts

@@ -6,9 +6,18 @@ import {
   SandboxStartData,
   CreateSandboxOpts,
   VMTier,
+  SandboxListOpts,
+  SandboxInfo,
 } from "./sandbox-client";
 
-export { SandboxClient, SandboxStartData, CreateSandboxOpts, VMTier };
+export {
+  SandboxClient,
+  SandboxStartData,
+  CreateSandboxOpts,
+  VMTier,
+  SandboxListOpts,
+  SandboxInfo,
+};
 export * from "./sandbox";
 
 export interface ClientOpts {

src/sandbox-client.ts

@@ -4,6 +4,7 @@ import type { Client } from "@hey-api/client-fetch";
 import type { VmStartResponse, tier } from "./client";
 import {
   sandboxFork,
+  sandboxList,
   vmHibernate,
   vmShutdown,
   vmStart,
@@ -16,6 +17,24 @@ import { handleResponse } from "./utils/handle-response";
 export type SandboxPrivacy = "public" | "unlisted" | "private";
 export type SandboxStartData = Required<VmStartResponse>["data"];
 
+export type SandboxInfo = {
+  id: string;
+  createdAt: Date;
+  updatedAt: Date;
+  title?: string;
+  description?: string;
+  privacy: SandboxPrivacy;
+  tags: string[];
+};
+
+export type SandboxListOpts = {
+  tags?: string[];
+  page?: number;
+  pageSize?: number;
+  orderBy?: "inserted_at" | "updated_at";
+  direction?: "asc" | "desc";
+};
+
 export const DEFAULT_SUBSCRIPTIONS = {
   client: {
     status: true,
@@ -352,6 +371,35 @@ export class SandboxClient {
     handleResponse(response, `Failed to hibernate sandbox ${id}`);
   }
 
+  /**
+   * List sandboxes from the current workspace with optional filters.
+   * Results are limited to a maximum of 50 sandboxes per request.
+   */
+  async list(opts: SandboxListOpts = {}): Promise<SandboxInfo[]> {
+    const response = await sandboxList({
+      client: this.apiClient,
+      query: {
+        tags: opts.tags?.join(","),
+        page: opts.page,
+        page_size: opts.pageSize,
+        order_by: opts.orderBy,
+        direction: opts.direction,
+      },
+    });
+
+    const info = handleResponse(response, "Failed to list sandboxes");
+
+    return info.sandboxes.map((sandbox) => ({
+      id: sandbox.id,
+      createdAt: new Date(sandbox.created_at),
+      updatedAt: new Date(sandbox.updated_at),
+      title: sandbox.title ?? undefined,
+      description: sandbox.description ?? undefined,
+      privacy: privacyFromNumber(sandbox.privacy),
+      tags: sandbox.tags,
+    }));
+  }
+
   /**
    * Updates the specs that this sandbox runs on. It will dynamically scale the sandbox to the
    * new specs without a reboot. Be careful when scaling specs down, if the VM is using more memory
@@ -467,3 +515,16 @@ function privacyToNumber(privacy: SandboxPrivacy): number {
       return 2;
   }
 }
+
+function privacyFromNumber(privacy: number): SandboxPrivacy {
+  switch (privacy) {
+    case 0:
+      return "public";
+    case 1:
+      return "unlisted";
+    case 2:
+      return "private";
+  }
+
+  throw new Error(`Invalid privacy number: ${privacy}`);
+}