Add filtering option for listing sandboxes

.gitignore

@@ -292,3 +292,6 @@ cython_debug/
 # SDK reference artifacts
 sdk_ref/
 sdkRefRoutes.json
+
+# SDK Client generated spec
+spec/openapi_generated.yml

packages/js-sdk/src/sandbox/sandboxApi.ts

@@ -11,6 +11,13 @@ export interface SandboxApiOpts
     Pick<ConnectionOpts, 'apiKey' | 'debug' | 'domain' | 'requestTimeoutMs'>
   > {}
 
+export interface SandboxListOpts extends SandboxApiOpts {
+  /**
+   * Filter the list of sandboxes by metadata, e.g. `{"key": "value"}`, if there are multiple filters they are combined with AND.
+   */
+  filters?: Record<string, string>
+}
+
 /**
  * Information about a sandbox.
  */
@@ -87,11 +94,21 @@ export class SandboxApi {
    *
    * @returns list of running sandboxes.
    */
-  static async list(opts?: SandboxApiOpts): Promise<SandboxInfo[]> {
+  static async list(
+      opts?: SandboxListOpts): Promise<SandboxInfo[]> {
     const config = new ConnectionConfig(opts)
     const client = new ApiClient(config)
 
+    let query = undefined
+    if (opts?.filters) {
+      const encodedPairs: Record<string, string> = Object.fromEntries(Object.entries(opts.filters).map(([key, value]) => [encodeURIComponent(key),encodeURIComponent(value)]))
+      query = new URLSearchParams(encodedPairs).toString()
+    }
+
     const res = await client.api.GET('/sandboxes', {
+        params: {
+          query: {query},
+        },
       signal: config.getSignal(opts?.requestTimeoutMs),
     })
 

packages/js-sdk/tests/api/list.test.ts

@@ -20,3 +20,21 @@ sandboxTest.skipIf(isDebug)('list sandboxes', async ({ sandbox }) => {
     )
   }
 })
+
+sandboxTest.skipIf(isDebug)('list sandboxes with filter', async () => {
+  const uniqueId = Date.now().toString()
+  // Create an extra sandbox with a uniqueId
+  const extraSbx = await Sandbox.create({ })
+  try {
+    const sbx = await Sandbox.create({metadata: {uniqueId: uniqueId}})
+    try {
+      const sandboxes = await Sandbox.list({filters: {uniqueId}})
+      assert.equal(sandboxes.length, 1)
+      assert.equal(sandboxes[0].sandboxId, sbx.sandboxId)
+    } finally {
+      await sbx.kill()
+    }
+  } finally {
+    await extraSbx.kill()
+  }
+})