chore: Mark legacy tunnel methods deprecated (#706)

Author: alb-rl

src/resources/devboxes/devboxes.ts

@@ -189,11 +189,13 @@ export class Devboxes extends APIResource {
   }
 
   /**
-   * [Deprecated] Use POST /v1/devboxes/{id}/enable_tunnel instead. This endpoint
-   * creates a legacy tunnel. The new enable_tunnel endpoint provides improved tunnel
-   * functionality with authentication options.
+   * @deprecated Use {@link enableTunnel} instead for V2 tunnels with better URL format.
    *
-   * @deprecated
+   * Creates a legacy tunnel to expose a specific port on the devbox.
+   * The legacy tunnel URL format is: `https://{devbox_id}-{port}.tunnel.runloop.ai`
+   *
+   * V2 tunnels (via enableTunnel) provide encrypted URL-based access with the format:
+   * `https://{port}-{tunnel_key}.tunnel.runloop.ai`
    */
   createTunnel(
     id: string,

src/sdk/devbox.ts

@@ -102,19 +102,24 @@ export class DevboxNetOps {
   }
 
   /**
-   * [Deprecated] Use enableTunnel instead. This method creates a legacy tunnel.
+   * @deprecated Use {@link enableTunnel} instead for V2 tunnels with better URL format.
    *
-   * Open a port on the devbox to be accessible from the internet.
+   * Creates a legacy tunnel to expose a specific port on the devbox.
+   * The legacy tunnel URL format is: `https://{devbox_id}-{port}.tunnel.runloop.ai`
+   *
+   * V2 tunnels (via enableTunnel) provide encrypted URL-based access with the format:
+   * `https://{port}-{tunnel_key}.tunnel.runloop.ai`
    *
    * @example
    * ```typescript
+   * // Deprecated - use enableTunnel instead
    * const tunnel = await devbox.net.createTunnel({ port: 8080 });
+   * console.log(tunnel.url); // Legacy URL format
    * ```
    *
-   * @param {DevboxCreateTunnelParams} params - Tunnel creation parameters
+   * @param {DevboxCreateTunnelParams} params - Tunnel creation parameters including port
    * @param {Core.RequestOptions} [options] - Request options
-   * @returns {Promise<DevboxTunnelView>} Tunnel creation result
-   * @deprecated Use enableTunnel instead for V2 tunnels
+   * @returns {Promise<DevboxTunnelView>} Legacy tunnel view with devbox_id, port, and url
    */
   async createTunnel(params: DevboxCreateTunnelParams, options?: Core.RequestOptions) {
     return this.client.devboxes.createTunnel(this.devboxId, params, options);

tests/objects/devbox.test.ts

@@ -331,8 +331,13 @@ describe('Devbox (New API)', () => {
         expect(result).toEqual(mockSSHKey);
       });
 
-      it('should create legacy tunnel', async () => {
-        const mockTunnel = { devbox_id: 'devbox-123', port: 8080 };
+      it('should create legacy tunnel (deprecated) and return old URL format', async () => {
+        // Legacy tunnel response includes the old URL format: https://{devbox_id}-{port}.tunnel.runloop.ai
+        const mockTunnel = {
+          devbox_id: 'devbox-123',
+          port: 8080,
+          url: 'https://devbox-123-8080.tunnel.runloop.ai',
+        };
         mockClient.devboxes.createTunnel.mockResolvedValue(mockTunnel);
 
         const result = await devbox.net.createTunnel({ port: 8080 });
@@ -343,6 +348,10 @@ describe('Devbox (New API)', () => {
           undefined,
         );
         expect(result).toEqual(mockTunnel);
+        expect(result.devbox_id).toBe('devbox-123');
+        expect(result.port).toBe(8080);
+        // Verify the legacy URL format contains devbox_id and port
+        expect(result.url).toBe('https://devbox-123-8080.tunnel.runloop.ai');
       });
 
       it('should enable V2 tunnel with params', async () => {

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

@@ -263,21 +263,31 @@ describe('smoketest: object-oriented devbox', () => {
       await devbox.shutdown();
     });
 
-    test('create and remove tunnel', async () => {
+    test('create and remove legacy tunnel (deprecated)', async () => {
       const devbox = await sdk.devbox.create({
         name: uniqueName('sdk-devbox-tunnel'),
         launch_parameters: { resource_size_request: 'X_SMALL', keep_alive_time_seconds: 60 * 5 }, // 5 minutes
       });
 
-      // Create tunnel
-      const tunnel = await devbox.net.createTunnel({ port: 8080 });
-      expect(tunnel).toBeDefined();
+      try {
+        // Create legacy tunnel using deprecated createTunnel method
+        const tunnel = await devbox.net.createTunnel({ port: 8080 });
 
-      // Remove tunnel
-      await devbox.net.removeTunnel({ port: 8080 });
+        // Verify the legacy tunnel response structure
+        expect(tunnel).toBeDefined();
+        expect(tunnel.devbox_id).toBe(devbox.id);
+        expect(tunnel.port).toBe(8080);
+        expect(tunnel.url).toBeDefined();
 
-      // Clean up
-      await devbox.shutdown();
+        // Verify the legacy tunnel URL format: https://{devbox_id}-{port}.tunnel.runloop.ai
+        const expectedUrlPattern = new RegExp(`^https://${devbox.id}-8080\\.tunnel\\.runloop\\.ai$`);
+        expect(tunnel.url).toMatch(expectedUrlPattern);
+
+        // Remove legacy tunnel
+        await devbox.net.removeTunnel({ port: 8080 });
+      } finally {
+        await devbox.shutdown();
+      }
     });
 
     test('enable V2 tunnel (open)', async () => {