WIP docs: added base api types to the type reference (#689)

* Restructure type references to be clearer

* title underline formatting

* Rename SDK's RequestOptions to BaseRequestOptions (avoid conflict with API's RequestOptions)

* base api types in the type reference

Author: sid-rl

docs/sdk/async/devbox.rst

@@ -6,3 +6,6 @@ The ``AsyncDevbox`` class provides asynchronous methods for managing and interac
 .. automodule:: runloop_api_client.sdk.async_devbox
    :members:
 
+.. automodule:: runloop_api_client.sdk.protocols
+   :members: AsyncCommandInterface, AsyncFileInterface, AsyncNetworkInterface
+   :undoc-members:

docs/sdk/sync/devbox.rst

@@ -6,3 +6,6 @@ The ``Devbox`` class provides synchronous methods for managing and interacting w
 .. automodule:: runloop_api_client.sdk.devbox
    :members:
 
+.. automodule:: runloop_api_client.sdk.protocols
+   :members: CommandInterface, FileInterface, NetworkInterface
+   :undoc-members:

docs/sdk/types.rst

@@ -1,27 +1,21 @@
 Type Reference
 ==============
 
-This page documents all TypeDict parameter types used throughout the SDK.
+The Runloop Python SDK uses TypeDict objects for configuration parameters to the various API calls. This page documents the TypeDict objects used throughout the SDK.
 
-Core Request Options
+Blueprint Parameters
 --------------------
 
-These TypeDicts define options for streaming, timeouts, polling, and other request configuration.
-
-.. autotypeddict:: runloop_api_client.sdk._types.ExecuteStreamingCallbacks
-
-.. autotypeddict:: runloop_api_client.sdk._types.RequestOptions
-
-.. autotypeddict:: runloop_api_client.sdk._types.LongRequestOptions
+These TypeDicts define parameters for blueprint creation and listing.
 
-.. autotypeddict:: runloop_api_client.sdk._types.PollingRequestOptions
+.. autotypeddict:: runloop_api_client.sdk._types.SDKBlueprintCreateParams
 
-.. autotypeddict:: runloop_api_client.sdk._types.LongPollingRequestOptions
+.. autotypeddict:: runloop_api_client.sdk._types.SDKBlueprintListParams
 
 Devbox Parameters
 -----------------
 
-These TypeDicts define parameters for devbox creation, execution, file operations, network tunnels, and snapshots.
+These TypeDicts define parameters for devbox creation, listing, and operations.
 
 Creation Parameters
 ~~~~~~~~~~~~~~~~~~~
@@ -30,18 +24,18 @@ Creation Parameters
 
 .. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxCreateFromImageParams
 
-Execution Parameters
-~~~~~~~~~~~~~~~~~~~~
-
-.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxExecuteParams
-
-.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxExecuteAsyncParams
-
 Listing Parameters
 ~~~~~~~~~~~~~~~~~~
 
 .. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxListParams
 
+Command Execution Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxExecuteParams
+
+.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxExecuteAsyncParams
+
 File Operation Parameters
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -54,14 +48,16 @@ File Operation Parameters
 .. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxUploadFileParams
 
 Network Tunnel Parameters
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxCreateTunnelParams
 
 .. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxRemoveTunnelParams
 
 Snapshot Parameters
-~~~~~~~~~~~~~~~~~~~
+-------------------
+
+These TypeDicts define parameters for snapshot creation, listing, and updating.
 
 .. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxSnapshotDiskParams
 
@@ -71,15 +67,6 @@ Snapshot Parameters
 
 .. autotypeddict:: runloop_api_client.sdk._types.SDKDiskSnapshotUpdateParams
 
-Blueprint Parameters
---------------------
-
-These TypeDicts define parameters for blueprint creation and listing.
-
-.. autotypeddict:: runloop_api_client.sdk._types.SDKBlueprintCreateParams
-
-.. autotypeddict:: runloop_api_client.sdk._types.SDKBlueprintListParams
-
 Storage Object Parameters
 -------------------------
 
@@ -90,3 +77,33 @@ These TypeDicts define parameters for storage object creation, listing, and down
 .. autotypeddict:: runloop_api_client.sdk._types.SDKObjectListParams
 
 .. autotypeddict:: runloop_api_client.sdk._types.SDKObjectDownloadParams
+
+Core Request Options
+--------------------
+
+These TypeDicts define options for timeouts, idempotency, polling, and other low-level request configuration. All other TypeDicts in the SDK extend from one of these core types.
+
+.. autotypeddict:: runloop_api_client.sdk._types.BaseRequestOptions
+
+.. autotypeddict:: runloop_api_client.sdk._types.LongRequestOptions
+
+.. autoclass:: runloop_api_client.sdk._types.PollingConfig
+   :members:
+   :undoc-members:
+
+.. autotypeddict:: runloop_api_client.sdk._types.PollingRequestOptions
+
+.. autotypeddict:: runloop_api_client.sdk._types.LongPollingRequestOptions
+
+Base API Type Reference
+-----------------------
+
+.. automodule:: runloop_api_client.types.shared_params
+   :members:
+   :undoc-members:
+   :imported-members:
+
+.. automodule:: runloop_api_client.types
+   :members:
+   :undoc-members:
+   :imported-members:

src/runloop_api_client/sdk/_types.py

@@ -36,7 +36,7 @@ class ExecuteStreamingCallbacks(TypedDict, total=False):
     """Callback invoked for all log lines (both stdout and stderr)"""
 
 
-class RequestOptions(TypedDict, total=False):
+class BaseRequestOptions(TypedDict, total=False):
     extra_headers: Optional[Headers]
     """Send extra headers"""
 
@@ -50,12 +50,12 @@ class RequestOptions(TypedDict, total=False):
     """Override the client-level default timeout for this request, in seconds"""
 
 
-class LongRequestOptions(RequestOptions, total=False):
+class LongRequestOptions(BaseRequestOptions, total=False):
     idempotency_key: Optional[str]
     """Specify a custom idempotency key for this request"""
 
 
-class PollingRequestOptions(RequestOptions, total=False):
+class PollingRequestOptions(BaseRequestOptions, total=False):
     polling_config: Optional[PollingConfig]
     """Configuration for polling behavior"""
 
@@ -80,7 +80,7 @@ class SDKDevboxExecuteAsyncParams(DevboxExecuteAsyncParams, ExecuteStreamingCall
     pass
 
 
-class SDKDevboxListParams(DevboxListParams, RequestOptions):
+class SDKDevboxListParams(DevboxListParams, BaseRequestOptions):
     pass
 
 
@@ -116,7 +116,7 @@ class SDKDevboxSnapshotDiskParams(DevboxSnapshotDiskParams, LongPollingRequestOp
     pass
 
 
-class SDKDiskSnapshotListParams(DiskSnapshotListParams, RequestOptions):
+class SDKDiskSnapshotListParams(DiskSnapshotListParams, BaseRequestOptions):
     pass
 
 
@@ -128,17 +128,17 @@ class SDKBlueprintCreateParams(BlueprintCreateParams, LongPollingRequestOptions)
     pass
 
 
-class SDKBlueprintListParams(BlueprintListParams, RequestOptions):
+class SDKBlueprintListParams(BlueprintListParams, BaseRequestOptions):
     pass
 
 
-class SDKObjectListParams(ObjectListParams, RequestOptions):
+class SDKObjectListParams(ObjectListParams, BaseRequestOptions):
     pass
 
 
 class SDKObjectCreateParams(ObjectCreateParams, LongRequestOptions):
     pass
 
 
-class SDKObjectDownloadParams(ObjectDownloadParams, RequestOptions):
+class SDKObjectDownloadParams(ObjectDownloadParams, BaseRequestOptions):
     pass

src/runloop_api_client/sdk/async_blueprint.py

@@ -5,7 +5,7 @@
 from typing_extensions import Unpack, override
 
 from ..types import BlueprintView
-from ._types import RequestOptions, LongRequestOptions, SDKDevboxCreateFromImageParams
+from ._types import BaseRequestOptions, LongRequestOptions, SDKDevboxCreateFromImageParams
 from .._client import AsyncRunloop
 from .async_devbox import AsyncDevbox
 from ..types.blueprint_build_logs_list_view import BlueprintBuildLogsListView
@@ -44,7 +44,7 @@ def id(self) -> str:
 
     async def get_info(
         self,
-        **options: Unpack[RequestOptions],
+        **options: Unpack[BaseRequestOptions],
     ) -> BlueprintView:
         """Retrieve the latest blueprint details.
 
@@ -59,7 +59,7 @@ async def get_info(
 
     async def logs(
         self,
-        **options: Unpack[RequestOptions],
+        **options: Unpack[BaseRequestOptions],
     ) -> BlueprintBuildLogsListView:
         """Retrieve build logs for the blueprint.
 

src/runloop_api_client/sdk/async_devbox.py

@@ -15,7 +15,7 @@
 )
 from ._types import (
     LogCallback,
-    RequestOptions,
+    BaseRequestOptions,
     LongRequestOptions,
     PollingRequestOptions,
     SDKDevboxExecuteParams,
@@ -104,7 +104,7 @@ def id(self) -> str:
 
     async def get_info(
         self,
-        **options: Unpack[RequestOptions],
+        **options: Unpack[BaseRequestOptions],
     ) -> DevboxView:
         """Retrieve current devbox status and metadata.
 

src/runloop_api_client/sdk/async_execution.py

@@ -7,7 +7,7 @@
 from typing import Optional, Awaitable, cast
 from typing_extensions import Unpack, override
 
-from ._types import RequestOptions, LongRequestOptions
+from ._types import BaseRequestOptions, LongRequestOptions
 from .._client import AsyncRunloop
 from .async_execution_result import AsyncExecutionResult
 from ..types.devbox_async_execution_detail_view import DevboxAsyncExecutionDetailView
@@ -119,7 +119,7 @@ async def result(self, **options: Unpack[LongRequestOptions]) -> AsyncExecutionR
         final = cast(DevboxAsyncExecutionDetailView, command_result)
         return AsyncExecutionResult(self._client, self._devbox_id, final)
 
-    async def get_state(self, **options: Unpack[RequestOptions]) -> DevboxAsyncExecutionDetailView:
+    async def get_state(self, **options: Unpack[BaseRequestOptions]) -> DevboxAsyncExecutionDetailView:
         """Fetch the latest execution state.
 
         :param options: Optional request configuration

src/runloop_api_client/sdk/async_snapshot.py

@@ -5,7 +5,7 @@
 from typing_extensions import Unpack, override
 
 from ._types import (
-    RequestOptions,
+    BaseRequestOptions,
     LongRequestOptions,
     PollingRequestOptions,
     SDKDiskSnapshotUpdateParams,
@@ -50,7 +50,7 @@ def id(self) -> str:
 
     async def get_info(
         self,
-        **options: Unpack[RequestOptions],
+        **options: Unpack[BaseRequestOptions],
     ) -> DevboxSnapshotAsyncStatusView:
         """Retrieve the latest snapshot status.
 

src/runloop_api_client/sdk/async_storage_object.py

@@ -5,7 +5,7 @@
 from typing import Iterable
 from typing_extensions import Unpack, override
 
-from ._types import RequestOptions, LongRequestOptions, SDKObjectDownloadParams
+from ._types import BaseRequestOptions, LongRequestOptions, SDKObjectDownloadParams
 from .._client import AsyncRunloop
 from ..types.object_view import ObjectView
 from ..types.object_download_url_view import ObjectDownloadURLView
@@ -52,7 +52,7 @@ def upload_url(self) -> str | None:
 
     async def refresh(
         self,
-        **options: Unpack[RequestOptions],
+        **options: Unpack[BaseRequestOptions],
     ) -> ObjectView:
         """Fetch the latest metadata for the object.
 

src/runloop_api_client/sdk/blueprint.py

@@ -5,7 +5,7 @@
 from typing_extensions import Unpack, override
 
 from ..types import BlueprintView
-from ._types import RequestOptions, LongRequestOptions, SDKDevboxCreateFromImageParams
+from ._types import BaseRequestOptions, LongRequestOptions, SDKDevboxCreateFromImageParams
 from .devbox import Devbox
 from .._client import Runloop
 from ..types.blueprint_build_logs_list_view import BlueprintBuildLogsListView
@@ -44,7 +44,7 @@ def id(self) -> str:
 
     def get_info(
         self,
-        **options: Unpack[RequestOptions],
+        **options: Unpack[BaseRequestOptions],
     ) -> BlueprintView:
         """Retrieve the latest blueprint details.
 
@@ -59,7 +59,7 @@ def get_info(
 
     def logs(
         self,
-        **options: Unpack[RequestOptions],
+        **options: Unpack[BaseRequestOptions],
     ) -> BlueprintBuildLogsListView:
         """Retrieve build logs for the blueprint.