feat(devbox): added suspend async and promoted suspend to automatically await the devbox running (#670)

Author: dines-rl

src/sdk/devbox.ts

@@ -885,18 +885,38 @@ export class Devbox {
   }
 
   /**
-   * Resume a suspended devbox.
+   * Resume a suspended devbox and wait for it to reach the running state.
    *
    * @example
    * ```typescript
    * await devbox.resume();
+   * // Devbox is now running
+   * ```
+   *
+   * @param {Core.RequestOptions & { polling?: Partial<PollingOptions<DevboxView>> }} [options] - Request options with optional polling configuration
+   * @returns {Promise<DevboxView>} The devbox data when running state is reached
+   */
+  async resume(
+    options?: Core.RequestOptions & { polling?: Partial<PollingOptions<DevboxView>> },
+  ): Promise<DevboxView> {
+    await this.resumeAsync(options);
+    return this.awaitRunning(options);
+  }
+
+  /**
+   * Resume a suspended devbox without waiting for it to reach the running state.
+   *
+   * @example
+   * ```typescript
+   * await devbox.resumeAsync();
+   * // Optionally wait for running state
    * await devbox.awaitRunning();
    * ```
    *
    * @param {Core.RequestOptions} [options] - Request options
    * @returns {Promise<DevboxResumeResponse>} Resume result
    */
-  async resume(options?: Core.RequestOptions) {
+  async resumeAsync(options?: Core.RequestOptions) {
     return this.client.devboxes.resume(this._id, options);
   }
 

tests/objects/devbox.test.ts

@@ -23,6 +23,8 @@ describe('Devbox (New API)', () => {
         shutdown: jest.fn(),
         suspend: jest.fn(),
         resume: jest.fn(),
+        awaitRunning: jest.fn(),
+        awaitSuspended: jest.fn(),
         keepAlive: jest.fn(),
         snapshotDisk: jest.fn(),
         snapshotDiskAsync: jest.fn(),
@@ -208,12 +210,15 @@ describe('Devbox (New API)', () => {
       });
 
       it('should resume the devbox', async () => {
+        const mockRunningData = { ...mockDevboxData, status: 'running' as const };
         mockClient.devboxes.resume.mockResolvedValue(undefined);
+        mockClient.devboxes.awaitRunning.mockResolvedValue(mockRunningData);
 
         const result = await devbox.resume();
 
         expect(mockClient.devboxes.resume).toHaveBeenCalledWith('devbox-123', undefined);
-        expect(result).toBeUndefined(); // Should return API response
+        expect(mockClient.devboxes.awaitRunning).toHaveBeenCalledWith('devbox-123', undefined);
+        expect(result).toEqual(mockRunningData); // Should return devbox data when running
       });
     });
 

tests/smoketests/object-oriented/devbox.test.ts

@@ -137,16 +137,38 @@ describe('smoketest: object-oriented devbox', () => {
       const suspendedInfo = await devbox.getInfo();
       expect(suspendedInfo.status).toBe('suspended');
 
-      // Resume the devbox
-      await devbox.resume();
-      await devbox.awaitRunning();
-      const resumedInfo = await devbox.getInfo();
+      // Resume the devbox - resume() automatically waits for running state
+      const resumedInfo = await devbox.resume();
       expect(resumedInfo.status).toBe('running');
 
       // Clean up
       await devbox.shutdown();
     });
 
+    test('resumeAsync - resume without waiting', async () => {
+      const devbox = await sdk.devbox.create({
+        name: uniqueName('sdk-devbox-resume-async'),
+        launch_parameters: { resource_size_request: 'X_SMALL', keep_alive_time_seconds: 60 * 5 }, // 5 minutes
+      });
+
+      // Suspend the devbox
+      await devbox.suspend();
+      await devbox.awaitSuspended();
+      const suspendedInfo = await devbox.getInfo();
+      expect(suspendedInfo.status).toBe('suspended');
+
+      // Resume the devbox asynchronously - doesn't wait automatically
+      const resumeResponse = await devbox.resumeAsync();
+      expect(resumeResponse).toBeDefined();
+
+      // Now wait for running state explicitly
+      const runningInfo = await devbox.awaitRunning();
+      expect(runningInfo.status).toBe('running');
+
+      // Clean up
+      await devbox.shutdown();
+    });
+
     test('keep alive', async () => {
       const devbox = await sdk.devbox.create({
         name: uniqueName('sdk-devbox-keepalive'),

tests/smoketests/object-oriented/execution.test.ts

@@ -49,6 +49,7 @@ describe('smoketest: object-oriented execution', () => {
       expect(result.exitCode).toBe(0);
       expect(result.success).toBe(true);
       expect(result.failed).toBe(false);
+      expect(result.executionId).toBeTruthy();
       expect(result.result).toBeDefined();
 
       const output = await result.stdout();