feat(mux): wait_for_eviction endpoint for flex eviction notifications (#10325)

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 119
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/runloop-ai/runloop-d0efdaa19d8a5685def3947450df7f9bdaf9bad3243317d514add5d22129fc5f.yml
-openapi_spec_hash: 7e484ea9f60294503bf4691fe3efef3a
-config_hash: 218b8d25038e627faab98532392ee9a0
+configured_endpoints: 120
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/runloop-ai/runloop-f18b1bba718700c841b3904207cd8ba2c066421a691845d6283bbbb361cf161d.yml
+openapi_spec_hash: 6044f4a4da13881c5f82fcc394c1f43b
+config_hash: d9a5b7a4227236a55c89de56b56f4aec

api.md

@@ -186,6 +186,7 @@ Types:
 - <code><a href="./src/resources/devboxes/devboxes.ts">DevboxReadFileContentsResponse</a></code>
 - <code><a href="./src/resources/devboxes/devboxes.ts">DevboxRemoveTunnelResponse</a></code>
 - <code><a href="./src/resources/devboxes/devboxes.ts">DevboxUploadFileResponse</a></code>
+- <code><a href="./src/resources/devboxes/devboxes.ts">DevboxWatchEvictionsResponse</a></code>
 
 Methods:
 
@@ -213,6 +214,7 @@ Methods:
 - <code title="post /v1/devboxes/{id}/suspend">client.devboxes.<a href="./src/resources/devboxes/devboxes.ts">suspend</a>(id) -> DevboxView</code>
 - <code title="post /v1/devboxes/{id}/upload_file">client.devboxes.<a href="./src/resources/devboxes/devboxes.ts">uploadFile</a>(id, { ...params }) -> unknown</code>
 - <code title="post /v1/devboxes/{devbox_id}/executions/{execution_id}/wait_for_status">client.devboxes.<a href="./src/resources/devboxes/devboxes.ts">waitForCommand</a>(devboxId, executionId, { ...params }) -> DevboxAsyncExecutionDetailView</code>
+- <code title="get /v1/devboxes/watch_evictions">client.devboxes.<a href="./src/resources/devboxes/devboxes.ts">watchEvictions</a>() -> DevboxWatchEvictionsResponse</code>
 - <code title="post /v1/devboxes/{id}/write_file_contents">client.devboxes.<a href="./src/resources/devboxes/devboxes.ts">writeFileContents</a>(id, { ...params }) -> DevboxExecutionDetailView</code>
 
 ## DiskSnapshots

src/index.ts

@@ -223,6 +223,7 @@ import {
   DevboxView,
   DevboxViewsDevboxesCursorIDPage,
   DevboxWaitForCommandParams,
+  DevboxWatchEvictionsResponse,
   DevboxWriteFileContentsParams,
   Devboxes,
   PtyTunnelView,
@@ -690,6 +691,7 @@ export declare namespace Runloop {
     type DevboxReadFileContentsResponse as DevboxReadFileContentsResponse,
     type DevboxRemoveTunnelResponse as DevboxRemoveTunnelResponse,
     type DevboxUploadFileResponse as DevboxUploadFileResponse,
+    type DevboxWatchEvictionsResponse as DevboxWatchEvictionsResponse,
     DevboxViewsDevboxesCursorIDPage as DevboxViewsDevboxesCursorIDPage,
     DevboxSnapshotViewsDiskSnapshotsCursorIDPage as DevboxSnapshotViewsDiskSnapshotsCursorIDPage,
     type DevboxCreateParams as DevboxCreateParams,

src/resources/devboxes/devboxes.ts

@@ -538,6 +538,17 @@ export class Devboxes extends APIResource {
     });
   }
 
+  /**
+   * Subscribe, via server-sent events, to pending infrastructure evictions for every
+   * Devbox in the account. On connect the stream emits one event per Devbox that
+   * currently has a pending eviction, then one event as each further eviction is
+   * scheduled. Best-effort and advisory: a Devbox stays running until its deadline,
+   * and delivery is not guaranteed.
+   */
+  watchEvictions(options?: Core.RequestOptions): Core.APIPromise<DevboxWatchEvictionsResponse> {
+    return this._client.get('/v1/devboxes/watch_evictions', options);
+  }
+
   /**
    * Write UTF-8 string contents to a file at path on the Devbox. Note for large
    * files (larger than 100MB), the upload_file endpoint must be used.
@@ -1094,6 +1105,19 @@ export type DevboxRemoveTunnelResponse = unknown;
 
 export type DevboxUploadFileResponse = unknown;
 
+export interface DevboxWatchEvictionsResponse {
+  /**
+   * The ID of the Devbox with a pending eviction.
+   */
+  devbox_id: string;
+
+  /**
+   * Unix timestamp (milliseconds) after which the Devbox will be suspended. Advisory
+   * and best-effort.
+   */
+  eviction_deadline_ms: number;
+}
+
 /**
  * Parameters for creating a new Devbox.
  *
@@ -1556,6 +1580,7 @@ export declare namespace Devboxes {
     type DevboxReadFileContentsResponse as DevboxReadFileContentsResponse,
     type DevboxRemoveTunnelResponse as DevboxRemoveTunnelResponse,
     type DevboxUploadFileResponse as DevboxUploadFileResponse,
+    type DevboxWatchEvictionsResponse as DevboxWatchEvictionsResponse,
     DevboxViewsDevboxesCursorIDPage as DevboxViewsDevboxesCursorIDPage,
     DevboxSnapshotViewsDiskSnapshotsCursorIDPage as DevboxSnapshotViewsDiskSnapshotsCursorIDPage,
     type DevboxCreateParams as DevboxCreateParams,

src/resources/devboxes/index.ts

@@ -22,6 +22,7 @@ export {
   type DevboxReadFileContentsResponse,
   type DevboxRemoveTunnelResponse,
   type DevboxUploadFileResponse,
+  type DevboxWatchEvictionsResponse,
   type DevboxCreateParams,
   type DevboxUpdateParams,
   type DevboxListParams,

src/resources/index.ts

@@ -103,6 +103,7 @@ export {
   type DevboxReadFileContentsResponse,
   type DevboxRemoveTunnelResponse,
   type DevboxUploadFileResponse,
+  type DevboxWatchEvictionsResponse,
   type DevboxCreateParams,
   type DevboxUpdateParams,
   type DevboxListParams,

tests/api-resources/devboxes/devboxes.test.ts

@@ -596,6 +596,24 @@ describe('resource devboxes', () => {
     });
   });
 
+  test('watchEvictions', async () => {
+    const responsePromise = client.devboxes.watchEvictions();
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
+  test('watchEvictions: request options instead of params are passed correctly', async () => {
+    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
+    await expect(client.devboxes.watchEvictions({ path: '/_stainless_unknown_path' })).rejects.toThrow(
+      Runloop.NotFoundError,
+    );
+  });
+
   test('writeFileContents: only required params', async () => {
     const responsePromise = client.devboxes.writeFileContents('id', {
       contents: 'contents',