feat(devbox): add new tunnel APIs and deprecate old tunnel API (#7227)

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 111
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/runloop-ai%2Frunloop-c89b52af46573ea81341b7115e59ee3f995ff9fe5b48a04318176d9b30e7eb79.yml
-openapi_spec_hash: a8b42cc79a4fc993c8cc5cc13fc443a2
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/runloop-ai%2Frunloop-debd1f9a9d599b009905cbaaea3095c025fe290493c8a836f54ece22265579c1.yml
+openapi_spec_hash: ee42d2c73aaad86888360147d9ed0766
 config_hash: 22f65246be4646c23dde9f69f51252e7

src/runloop_api_client/resources/devboxes/devboxes.py

@@ -193,6 +193,7 @@ def create(
         repo_connection_id: Optional[str] | Omit = omit,
         secrets: Optional[Dict[str, str]] | Omit = omit,
         snapshot_id: Optional[str] | Omit = omit,
+        tunnel: Optional[devbox_create_params.Tunnel] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -252,6 +253,10 @@ def create(
           snapshot_id: Snapshot ID to use for the Devbox. Only one of (Snapshot ID, Blueprint ID,
               Blueprint name) should be specified.
 
+          tunnel: (Optional) Configuration for creating a V2 tunnel at Devbox launch time. When
+              specified, a tunnel will be automatically provisioned and the tunnel details
+              will be included in the Devbox response.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -280,6 +285,7 @@ def create(
                     "repo_connection_id": repo_connection_id,
                     "secrets": secrets,
                     "snapshot_id": snapshot_id,
+                    "tunnel": tunnel,
                 },
                 devbox_create_params.DevboxCreateParams,
             ),
@@ -640,6 +646,7 @@ def create_ssh_key(
             cast_to=DevboxCreateSSHKeyResponse,
         )
 
+    @typing_extensions.deprecated("deprecated")
     def create_tunnel(
         self,
         id: str,
@@ -653,8 +660,11 @@ def create_tunnel(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
         idempotency_key: str | None = None,
     ) -> DevboxTunnelView:
-        """
-        Create a live tunnel to an available port on the Devbox.
+        """[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.
 
         Args:
           port: Devbox port that tunnel will expose.
@@ -1739,6 +1749,7 @@ async def create(
         repo_connection_id: Optional[str] | Omit = omit,
         secrets: Optional[Dict[str, str]] | Omit = omit,
         snapshot_id: Optional[str] | Omit = omit,
+        tunnel: Optional[devbox_create_params.Tunnel] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -1798,6 +1809,10 @@ async def create(
           snapshot_id: Snapshot ID to use for the Devbox. Only one of (Snapshot ID, Blueprint ID,
               Blueprint name) should be specified.
 
+          tunnel: (Optional) Configuration for creating a V2 tunnel at Devbox launch time. When
+              specified, a tunnel will be automatically provisioned and the tunnel details
+              will be included in the Devbox response.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -1826,6 +1841,7 @@ async def create(
                     "repo_connection_id": repo_connection_id,
                     "secrets": secrets,
                     "snapshot_id": snapshot_id,
+                    "tunnel": tunnel,
                 },
                 devbox_create_params.DevboxCreateParams,
             ),
@@ -2183,6 +2199,7 @@ async def create_ssh_key(
             cast_to=DevboxCreateSSHKeyResponse,
         )
 
+    @typing_extensions.deprecated("deprecated")
     async def create_tunnel(
         self,
         id: str,
@@ -2196,8 +2213,11 @@ async def create_tunnel(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
         idempotency_key: str | None = None,
     ) -> DevboxTunnelView:
-        """
-        Create a live tunnel to an available port on the Devbox.
+        """[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.
 
         Args:
           port: Devbox port that tunnel will expose.
@@ -3247,8 +3267,10 @@ def __init__(self, devboxes: DevboxesResource) -> None:
         self.create_ssh_key = to_raw_response_wrapper(
             devboxes.create_ssh_key,
         )
-        self.create_tunnel = to_raw_response_wrapper(
-            devboxes.create_tunnel,
+        self.create_tunnel = (  # pyright: ignore[reportDeprecated]
+            to_raw_response_wrapper(
+                devboxes.create_tunnel,  # pyright: ignore[reportDeprecated],
+            )
         )
         self.delete_disk_snapshot = to_raw_response_wrapper(
             devboxes.delete_disk_snapshot,
@@ -3345,8 +3367,10 @@ def __init__(self, devboxes: AsyncDevboxesResource) -> None:
         self.create_ssh_key = async_to_raw_response_wrapper(
             devboxes.create_ssh_key,
         )
-        self.create_tunnel = async_to_raw_response_wrapper(
-            devboxes.create_tunnel,
+        self.create_tunnel = (  # pyright: ignore[reportDeprecated]
+            async_to_raw_response_wrapper(
+                devboxes.create_tunnel,  # pyright: ignore[reportDeprecated],
+            )
         )
         self.delete_disk_snapshot = async_to_raw_response_wrapper(
             devboxes.delete_disk_snapshot,
@@ -3443,8 +3467,10 @@ def __init__(self, devboxes: DevboxesResource) -> None:
         self.create_ssh_key = to_streamed_response_wrapper(
             devboxes.create_ssh_key,
         )
-        self.create_tunnel = to_streamed_response_wrapper(
-            devboxes.create_tunnel,
+        self.create_tunnel = (  # pyright: ignore[reportDeprecated]
+            to_streamed_response_wrapper(
+                devboxes.create_tunnel,  # pyright: ignore[reportDeprecated],
+            )
         )
         self.delete_disk_snapshot = to_streamed_response_wrapper(
             devboxes.delete_disk_snapshot,
@@ -3541,8 +3567,10 @@ def __init__(self, devboxes: AsyncDevboxesResource) -> None:
         self.create_ssh_key = async_to_streamed_response_wrapper(
             devboxes.create_ssh_key,
         )
-        self.create_tunnel = async_to_streamed_response_wrapper(
-            devboxes.create_tunnel,
+        self.create_tunnel = (  # pyright: ignore[reportDeprecated]
+            async_to_streamed_response_wrapper(
+                devboxes.create_tunnel,  # pyright: ignore[reportDeprecated],
+            )
         )
         self.delete_disk_snapshot = async_to_streamed_response_wrapper(
             devboxes.delete_disk_snapshot,

src/runloop_api_client/types/devbox_create_params.py

@@ -3,13 +3,13 @@
 from __future__ import annotations
 
 from typing import Dict, Iterable, Optional
-from typing_extensions import Required, TypedDict
+from typing_extensions import Literal, Required, TypedDict
 
 from .shared_params.mount import Mount
 from .shared_params.launch_parameters import LaunchParameters
 from .shared_params.code_mount_parameters import CodeMountParameters
 
-__all__ = ["DevboxCreateParams", "Gateways"]
+__all__ = ["DevboxCreateParams", "Gateways", "Tunnel"]
 
 # We split up the original DevboxCreateParams into two nested types to enable us to
 # omit blueprint_id, blueprint_name, and snapshot_id when we unpack the TypedDict
@@ -94,6 +94,13 @@ class DevboxCreateParams(DevboxBaseCreateParams, total=False):
     Only one of (Snapshot ID, Blueprint ID, Blueprint name) should be specified.
     """
 
+    tunnel: Optional[Tunnel]
+    """(Optional) Configuration for creating a V2 tunnel at Devbox launch time.
+
+    When specified, a tunnel will be automatically provisioned and the tunnel
+    details will be included in the Devbox response.
+    """
+
 
 class Gateways(TypedDict, total=False):
     """
@@ -105,3 +112,13 @@ class Gateways(TypedDict, total=False):
 
     secret: Required[str]
     """The secret containing the credential. Can be a secret ID or name."""
+
+
+class Tunnel(TypedDict, total=False):
+    """(Optional) Configuration for creating a V2 tunnel at Devbox launch time.
+
+    When specified, a tunnel will be automatically provisioned and the tunnel details will be included in the Devbox response.
+    """
+
+    auth_mode: Optional[Literal["open", "authenticated"]]
+    """Authentication mode for the tunnel. Defaults to 'public' if not specified."""

src/runloop_api_client/types/devbox_view.py

@@ -6,7 +6,7 @@
 from .._models import BaseModel
 from .shared.launch_parameters import LaunchParameters
 
-__all__ = ["DevboxView", "StateTransition", "GatewaySpecs"]
+__all__ = ["DevboxView", "StateTransition", "GatewaySpecs", "Tunnel"]
 
 
 class StateTransition(BaseModel):
@@ -38,6 +38,30 @@ class GatewaySpecs(BaseModel):
     """The ID of the secret containing the credential."""
 
 
+class Tunnel(BaseModel):
+    """
+    V2 tunnel information if a tunnel was created at launch time or via the createTunnel API.
+    """
+
+    auth_mode: Literal["public_", "authenticated"]
+    """The authentication mode for the tunnel."""
+
+    create_time_ms: int
+    """Creation time of the tunnel (Unix timestamp milliseconds)."""
+
+    tunnel_key: str
+    """The encrypted tunnel key used to construct the tunnel URL.
+
+    URL format: https://{port}-{tunnel_key}.tunnel.runloop.{domain}
+    """
+
+    auth_token: Optional[str] = None
+    """Bearer token for tunnel authentication.
+
+    Only present when auth_mode is 'authenticated'.
+    """
+
+
 class DevboxView(BaseModel):
     """A Devbox represents a virtual development environment.
 
@@ -112,3 +136,9 @@ class DevboxView(BaseModel):
     The Snapshot ID used in creation of the Devbox, if the devbox was created from a
     Snapshot.
     """
+
+    tunnel: Optional[Tunnel] = None
+    """
+    V2 tunnel information if a tunnel was created at launch time or via the
+    createTunnel API.
+    """