fix: update pause() JSDoc and add regression tests for apiKey propagation

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

@@ -576,7 +576,7 @@ export class Sandbox extends SandboxApi {
    *
    * @param opts connection options.
    *
-   * @returns sandbox ID that can be used to resume the sandbox.
+   * @returns true if the sandbox was paused successfully, false if it was already paused.
    *
    * @example
    * ```ts
@@ -585,14 +585,14 @@ export class Sandbox extends SandboxApi {
    * ```
    */
   async pause(opts?: ConnectionOpts): Promise<boolean> {
-    return await SandboxApi.pause(this.sandboxId, opts)
+    return await SandboxApi.pause(this.sandboxId, { ...this.connectionConfig, ...opts })
   }
 
   /**
    * @deprecated Use {@link Sandbox.pause} instead.
    */
   async betaPause(opts?: ConnectionOpts): Promise<boolean> {
-    return await SandboxApi.betaPause(this.sandboxId, opts)
+    return await SandboxApi.betaPause(this.sandboxId, { ...this.connectionConfig, ...opts })
   }
 
   /**

packages/js-sdk/tests/sandbox/pause.test.ts

@@ -0,0 +1,75 @@
+import { assert, expect } from 'vitest'
+
+import { Sandbox } from '../../src'
+import { isDebug, sandboxTest, template } from '../setup'
+
+/**
+ * Regression test: Sandbox.connect() with explicit apiKey should allow
+ * pause() to succeed even when E2B_API_KEY is not set in the environment.
+ *
+ * See: https://github.com/e2b-dev/E2B/pull/1218
+ */
+sandboxTest.skipIf(isDebug)(
+  'pause() uses apiKey from connectionConfig when E2B_API_KEY is not set',
+  async ({ sandbox }) => {
+    // Save and clear the environment API key
+    const savedApiKey = process.env.E2B_API_KEY
+    delete process.env.E2B_API_KEY
+
+    try {
+      // Get the apiKey that was used to create this sandbox
+      const apiKey = process.env.E2B_API_KEY || savedApiKey
+      expect(apiKey).toBeDefined()
+
+      // Connect to the sandbox with an explicit apiKey (E2B_API_KEY is now unset)
+      const connected = Sandbox.connect(sandbox.sandboxId, { apiKey })
+
+      // pause() should succeed using the apiKey from connectionConfig
+      // rather than requiring E2B_API_KEY to be set
+      const paused = await connected.pause()
+      assert.isTrue(paused, 'pause() should return true when successfully pausing a running sandbox')
+
+      // Verify the sandbox is actually paused
+      assert.isFalse(await connected.isRunning(), 'sandbox should be paused after pause()')
+    } finally {
+      // Restore the environment API key
+      if (savedApiKey) {
+        process.env.E2B_API_KEY = savedApiKey
+      }
+    }
+  }
+)
+
+sandboxTest.skipIf(isDebug)(
+  'pause() returns false when sandbox is already paused',
+  async ({ sandbox }) => {
+    // Pause the sandbox first
+    const firstPause = await sandbox.pause()
+    assert.isTrue(firstPause, 'first pause() should return true')
+
+    // Try to pause again - should return false since already paused
+    const secondPause = await sandbox.pause()
+    assert.isFalse(secondPause, 'pause() should return false when sandbox is already paused')
+  }
+)
+
+sandboxTest.skipIf(isDebug)(
+  'pause() works on connected sandbox with apiKey in connectionConfig',
+  async ({ sandbox }) => {
+    const apiKey = process.env.E2B_API_KEY
+    expect(apiKey).toBeDefined()
+
+    // Connect to the sandbox using apiKey from connectionConfig
+    const connected = Sandbox.connect(sandbox.sandboxId, { apiKey })
+
+    // Ensure the sandbox is running before pausing
+    assert.isTrue(await sandbox.isRunning())
+
+    // Pause the connected sandbox
+    const paused = await connected.pause()
+    assert.isTrue(paused, 'pause() should succeed on connected sandbox')
+
+    // Verify it's paused
+    assert.isFalse(await connected.isRunning())
+  }
+)