From ccae8ff23fd9d237560931379becfe30e22399cd Mon Sep 17 00:00:00 2001 From: James Chainey Date: Tue, 16 Dec 2025 12:04:43 -0800 Subject: [PATCH 1/2] added types to typedocs so that you can find the raw API types. Also made some changes to fix some rendering issues (eg. added @remarks). --- src/resources/agents.ts | 7 ++ src/resources/blueprints.ts | 7 ++ src/resources/devboxes/devboxes.ts | 22 +++++++ src/resources/objects.ts | 7 ++ src/resources/shared.ts | 24 +++++++ src/sdk.ts | 24 +++++++ src/sdk/agent.ts | 3 + src/sdk/blueprint.ts | 2 + src/sdk/devbox.ts | 14 ++++ src/sdk/execution-result.ts | 3 + src/sdk/execution.ts | 3 + src/sdk/snapshot.ts | 3 + src/sdk/storage-object.ts | 3 + src/types.ts | 101 +++++++++++++++++++++++++++++ tsconfig.typedoc.json | 2 +- typedoc.json | 22 ++++++- 16 files changed, 245 insertions(+), 2 deletions(-) create mode 100644 src/types.ts diff --git a/src/resources/agents.ts b/src/resources/agents.ts index c895ff513..0f7931a70 100644 --- a/src/resources/agents.ts +++ b/src/resources/agents.ts @@ -90,6 +90,8 @@ export interface AgentListView { /** * An Agent represents a registered AI agent entity. + * + * @category Agent Types */ export interface AgentView { /** @@ -123,6 +125,11 @@ export interface AgentView { source?: Shared.AgentSource | null; } +/** + * Parameters for creating a new Agent. + * + * @category Agent Types + */ export interface AgentCreateParams { /** * The name of the Agent. diff --git a/src/resources/blueprints.ts b/src/resources/blueprints.ts index 7d46dd8fa..37eb2717c 100644 --- a/src/resources/blueprints.ts +++ b/src/resources/blueprints.ts @@ -457,6 +457,8 @@ export interface BlueprintPreviewView { * Blueprints are ways to create customized starting points for Devboxes. They * allow you to define custom starting points for Devboxes such that environment * set up can be cached to improve Devbox boot times. + * + * @category Blueprint Types */ export interface BlueprintView { /** @@ -595,6 +597,11 @@ export interface InspectionSource { export type BlueprintDeleteResponse = unknown; +/** + * Parameters for creating a new Blueprint. + * + * @category Blueprint Types + */ export interface BlueprintCreateParams { /** * Name of the Blueprint. diff --git a/src/resources/devboxes/devboxes.ts b/src/resources/devboxes/devboxes.ts index a7b2baf41..ee58a3669 100644 --- a/src/resources/devboxes/devboxes.ts +++ b/src/resources/devboxes/devboxes.ts @@ -533,6 +533,11 @@ export class DevboxViewsDevboxesCursorIDPage extends DevboxesCursorIDPage {} +/** + * Details of an asynchronous command execution on a Devbox. + * + * @category Devbox Types + */ export interface DevboxAsyncExecutionDetailView { /** * Devbox id where command was executed. @@ -673,6 +678,11 @@ export interface DevboxSnapshotListView { total_count: number; } +/** + * View of a Devbox disk snapshot. + * + * @category Snapshot Types + */ export interface DevboxSnapshotView { /** * The unique identifier of the snapshot. @@ -731,6 +741,8 @@ export interface DevboxTunnelView { * A Devbox represents a virtual development environment. It is an isolated sandbox * that can be given to agents and used to run arbitrary code such as AI generated * code. + * + * @category Devbox Types */ export interface DevboxView { /** @@ -886,6 +898,11 @@ export type DevboxRemoveTunnelResponse = unknown; export type DevboxUploadFileResponse = unknown; +/** + * Parameters for creating a new Devbox. + * + * @category Devbox Types + */ export interface DevboxCreateParams { /** * Blueprint ID to use for the Devbox. If none set, the Devbox will be created with @@ -1005,6 +1022,11 @@ export interface DevboxDownloadFileParams { path: string; } +/** + * Parameters for executing a command on a Devbox. + * + * @category Devbox Types + */ export interface DevboxExecuteParams { /** * Body param: The command to execute via the Devbox shell. By default, commands diff --git a/src/resources/objects.ts b/src/resources/objects.ts index db536b314..63bbcfd37 100644 --- a/src/resources/objects.ts +++ b/src/resources/objects.ts @@ -171,6 +171,8 @@ export interface ObjectListView { /** * An Object represents a stored data entity with metadata. + * + * @category Storage Object Types */ export interface ObjectView { /** @@ -214,6 +216,11 @@ export interface ObjectView { upload_url?: string | null; } +/** + * Parameters for creating a new Storage Object. + * + * @category Storage Object Types + */ export interface ObjectCreateParams { /** * The content type of the Object. diff --git a/src/resources/shared.ts b/src/resources/shared.ts index cfb476bc1..7abc600f8 100644 --- a/src/resources/shared.ts +++ b/src/resources/shared.ts @@ -1,5 +1,10 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. +/** + * Configuration for automatic Devbox behavior after idle time. + * + * @category Shared Types + */ export interface AfterIdle { /** * After idle_time_seconds, on_idle action will be taken. @@ -14,6 +19,8 @@ export interface AfterIdle { /** * Agent source configuration. + * + * @category Shared Types */ export interface AgentSource { /** @@ -119,6 +126,11 @@ export namespace AgentSource { } } +/** + * Parameters for mounting code from a Git repository. + * + * @category Shared Types + */ export interface CodeMountParameters { /** * The name of the repo to mount. By default, code will be mounted at @@ -146,6 +158,8 @@ export interface CodeMountParameters { * LaunchParameters enable you to customize the resources available to your Devbox * as well as the environment set up that should be completed before the Devbox is * marked as 'running'. + * + * @category Shared Types */ export interface LaunchParameters { /** @@ -238,6 +252,11 @@ export namespace LaunchParameters { } } +/** + * Mount configuration for attaching files, agents, or code to a Devbox. + * + * @category Shared Types + */ export type Mount = Mount.ObjectMount | Mount.AgentMount | Mount.CodeMount | Mount.FileMount; export namespace Mount { @@ -322,6 +341,11 @@ export namespace Mount { } } +/** + * Configuration profile for scenario/benchmark runs. + * + * @category Shared Types + */ export interface RunProfile { /** * Mapping of Environment Variable to Value. May be shown in devbox logging. diff --git a/src/sdk.ts b/src/sdk.ts index c1bf964e9..8bf069e59 100644 --- a/src/sdk.ts +++ b/src/sdk.ts @@ -29,6 +29,8 @@ import * as Shared from './resources/shared'; * The key is the path on the devbox where the object will be mounted, * and the value is the StorageObject instance. * + * @category SDK Types + * * @example * ```typescript * { '/home/user/config.txt': storageObject } @@ -39,12 +41,16 @@ export type InlineObjectMount = { [path: string]: StorageObject }; /** * Union type representing all valid mount inputs for the SDK. * Accepts both the standard API mount format and the convenient InlineObjectMount format. + * + * @category SDK Types */ export type MountInstance = Shared.Mount | InlineObjectMount; /** * Extended DevboxCreateParams that accepts the convenient SDK mount syntax. * Use this type when creating devboxes through the SDK's DevboxOps.create() method. + * + * @category SDK Types */ export interface SDKDevboxCreateParams extends Omit { /** @@ -167,6 +173,8 @@ type ContentType = ObjectCreateParams['content_type']; * Runloop SDK - The recommended way to interact with Runloop. * Provides both low-level API access and high-level object-oriented interfaces. * + * @category SDK Client + * * @example * ```typescript * const runloop = new RunloopSDK(); // export RUNLOOP_API_KEY will automatically be used. @@ -175,6 +183,7 @@ type ContentType = ObjectCreateParams['content_type']; * console.log(result.exitCode); * ``` * + * @remarks * ## Operations * - `devbox` - {@link DevboxOps} * - `blueprint` - {@link BlueprintOps} @@ -268,6 +277,9 @@ export class RunloopSDK { /** * Devbox SDK interface for managing devboxes. * + * @category Devbox + * + * @remarks * ## Overview * * The `DevboxOps` class provides a high-level abstraction for managing devboxes, @@ -417,6 +429,9 @@ export class DevboxOps { /** * Blueprint SDK interface for managing blueprints. * + * @category Blueprint + * + * @remarks * ## Overview * * The `BlueprintOps` class provides a high-level abstraction for managing blueprints, @@ -510,6 +525,9 @@ export class BlueprintOps { /** * Snapshot SDK interface for managing disk snapshots. * + * @category Snapshot + * + * @remarks * ## Overview * * The `SnapshotOps` class provides a high-level abstraction for managing disk snapshots, @@ -558,6 +576,9 @@ export class SnapshotOps { /** * Storage object management interface * + * @category Storage Object + * + * @remarks * ## Overview * * The `StorageObjectOps` class provides a high-level abstraction for managing storage objects, @@ -773,6 +794,9 @@ export class StorageObjectOps { /** * Agent SDK interface for managing agents. * + * @category Agent + * + * @remarks * ## Overview * * The `AgentOps` class provides a high-level abstraction for managing AI agent entities. diff --git a/src/sdk/agent.ts b/src/sdk/agent.ts index da01baa48..cdf530371 100644 --- a/src/sdk/agent.ts +++ b/src/sdk/agent.ts @@ -5,6 +5,9 @@ import type { AgentCreateParams, AgentListParams, AgentView } from '../resources /** * Object-oriented interface for working with Agents. * + * @category Agent + * + * @remarks * ## Overview * * The `Agent` class provides a high-level API for managing AI agent entities. diff --git a/src/sdk/blueprint.ts b/src/sdk/blueprint.ts index 1f66dc7f9..361aab0f1 100644 --- a/src/sdk/blueprint.ts +++ b/src/sdk/blueprint.ts @@ -59,6 +59,8 @@ export type CreateParams = Omit & { /** * Object-oriented interface for working with Blueprints. + * + * @category Blueprint */ export class Blueprint { private client: Runloop; diff --git a/src/sdk/devbox.ts b/src/sdk/devbox.ts index 43e2f4944..826073594 100644 --- a/src/sdk/devbox.ts +++ b/src/sdk/devbox.ts @@ -28,6 +28,8 @@ export { ExecutionResult } from './execution-result'; /** * Streaming callbacks for real-time log processing. + * + * @category Execution Types */ export interface ExecuteStreamingCallbacks { /** Callback invoked for each stdout log line */ @@ -41,6 +43,8 @@ export interface ExecuteStreamingCallbacks { /** * Network operations for a devbox. * Provides methods for managing SSH keys and network tunnels. + * + * @category Devbox */ export class DevboxNetOps { /** @@ -130,6 +134,8 @@ export class DevboxNetOps { /** * Command execution operations for a devbox. * Provides methods for executing commands synchronously and asynchronously. + * + * @category Devbox */ export class DevboxCmdOps { /** @@ -262,6 +268,9 @@ export class DevboxCmdOps { * Named shell operations for a devbox. * Provides methods for executing commands in a persistent, stateful shell session. * + * @category Devbox + * + * @remarks * Use {@link Devbox.shell} to create a named shell instance. If you use the same shell name, * it will re-attach to the existing named shell, preserving its state (environment variables, * current working directory, etc.). @@ -383,6 +392,8 @@ export class DevboxNamedShell { /** * File operations for a devbox. * Provides methods for reading, writing, uploading, and downloading files. + * + * @category Devbox */ export class DevboxFileOps { /** @@ -471,6 +482,9 @@ export class DevboxFileOps { /** * Object-oriented interface for working with Devboxes. * + * @category Devbox + * + * @remarks * ## Overview * * The `Devbox` class provides a high-level, object-oriented API for managing devboxes. diff --git a/src/sdk/execution-result.ts b/src/sdk/execution-result.ts index 87d119195..9e9dd03d0 100644 --- a/src/sdk/execution-result.ts +++ b/src/sdk/execution-result.ts @@ -4,6 +4,9 @@ import type { DevboxAsyncExecutionDetailView } from '../resources/devboxes/devbo /** * Execution Result object for a completed command execution. * + * @category Execution Types + * + * @remarks * ## Overview * * The `ExecutionResult` class provides access to the results of a completed command execution. diff --git a/src/sdk/execution.ts b/src/sdk/execution.ts index 12b4e46f1..032c526e4 100644 --- a/src/sdk/execution.ts +++ b/src/sdk/execution.ts @@ -7,6 +7,9 @@ import { ExecutionResult } from './execution-result'; /** * Execution object for tracking async command execution with streaming support. * + * @category Execution Types + * + * @remarks * ## Overview * * The `Execution` class represents an asynchronous command execution on a devbox. diff --git a/src/sdk/snapshot.ts b/src/sdk/snapshot.ts index c93c11177..adbbd9053 100644 --- a/src/sdk/snapshot.ts +++ b/src/sdk/snapshot.ts @@ -15,6 +15,9 @@ import { Devbox } from './devbox'; /** * Object-oriented interface for working with Disk Snapshots. * + * @category Snapshot + * + * @remarks * ## Overview * * The `Snapshot` class provides a high-level API for managing disk snapshots of devboxes. diff --git a/src/sdk/storage-object.ts b/src/sdk/storage-object.ts index 8809af4c3..f1bd084a3 100644 --- a/src/sdk/storage-object.ts +++ b/src/sdk/storage-object.ts @@ -59,6 +59,9 @@ function assertNodeEnvironment(): void { /** * Object-oriented interface for working with Storage Objects. * + * @category Storage Object + * + * @remarks * ## Overview * * The `StorageObject` class provides a high-level API for managing storage objects, diff --git a/src/types.ts b/src/types.ts new file mode 100644 index 000000000..c4f12af36 --- /dev/null +++ b/src/types.ts @@ -0,0 +1,101 @@ +/** + * @module Types + * This module provides centralized access to all Runloop SDK types. + * Types are organized by category for easy discovery. + * + * @example + * ```typescript + * import type { DevboxCreateParams, DevboxView, Mount, LaunchParameters } from '@runloop/api-client/types'; + * ``` + */ + +// ============================================================================= +// Devbox Types +// ============================================================================= + +export type * from './resources/devboxes/devboxes'; + +// ============================================================================= +// Snapshot Types (Disk Snapshots) +// ============================================================================= + +export type * from './resources/devboxes/disk-snapshots'; + +// ============================================================================= +// Execution Types +// ============================================================================= + +export type * from './resources/devboxes/executions'; + +// ============================================================================= +// Browser Types +// ============================================================================= + +export type * from './resources/devboxes/browsers'; + +// ============================================================================= +// Computer Types +// ============================================================================= + +export type * from './resources/devboxes/computers'; + +// ============================================================================= +// Log Types +// ============================================================================= + +export type * from './resources/devboxes/logs'; + +// ============================================================================= +// Blueprint Types +// ============================================================================= + +export type * from './resources/blueprints'; + +// ============================================================================= +// Agent Types +// ============================================================================= + +export type * from './resources/agents'; + +// ============================================================================= +// Storage Object Types +// ============================================================================= + +export type * from './resources/objects'; + +// ============================================================================= +// Shared Types +// ============================================================================= + +export type * from './resources/shared'; + +// ============================================================================= +// Repository Types +// ============================================================================= + +export type * from './resources/repositories'; + +// ============================================================================= +// Secret Types +// ============================================================================= + +export type * from './resources/secrets'; + +// ============================================================================= +// Scenario Types +// ============================================================================= + +export type * from './resources/scenarios/scenarios'; + +// ============================================================================= +// Benchmark Types +// ============================================================================= + +export type * from './resources/benchmarks/benchmarks'; + +// ============================================================================= +// SDK Types +// ============================================================================= + +export type * from './sdk/devbox'; +export type * from './sdk'; diff --git a/tsconfig.typedoc.json b/tsconfig.typedoc.json index 323d84853..825f901ee 100644 --- a/tsconfig.typedoc.json +++ b/tsconfig.typedoc.json @@ -1,5 +1,5 @@ { "extends": "./tsconfig.json", "exclude": ["**/*.test.ts", "**/tests/**", "**/node_modules/**", "src/_shims/**/*-deno.ts"], - "include": ["src/sdk.ts", "src/sdk/**/*.ts", "src/core.ts", "src/resources/**/*.ts", "src/lib/**/*.ts"] + "include": ["src/sdk.ts", "src/types.ts", "src/sdk/**/*.ts", "src/core.ts", "src/resources/**/*.ts", "src/lib/**/*.ts"] } diff --git a/typedoc.json b/typedoc.json index 5b811ebb5..75c1d9b7c 100644 --- a/typedoc.json +++ b/typedoc.json @@ -1,6 +1,6 @@ { "$schema": "https://typedoc.org/schema.json", - "entryPoints": ["src/sdk.ts"], + "entryPoints": ["src/sdk.ts", "src/types.ts"], "entryPointStrategy": "expand", "out": "docs/", "tsconfig": "tsconfig.typedoc.json", @@ -31,6 +31,26 @@ "Function", "Variable" ], + "categoryOrder": [ + "SDK Client", + "Devbox", + "Blueprint", + "Snapshot", + "Storage Object", + "Agent", + "Devbox Types", + "Blueprint Types", + "Snapshot Types", + "Storage Object Types", + "Agent Types", + "Execution Types", + "Shared Types", + "Browser Types", + "Computer Types", + "Log Types", + "SDK Types", + "*" + ], "visibilityFilters": { "protected": false, "private": false, From 535c13f9ad4ce6cb613833ea0fe81d9658e7fc1b Mon Sep 17 00:00:00 2001 From: James Chainey Date: Tue, 16 Dec 2025 12:41:12 -0800 Subject: [PATCH 2/2] exclude types during normal build --- tsconfig.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tsconfig.json b/tsconfig.json index 032ca6504..27f21bac6 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,6 +1,6 @@ { "include": ["src", "tests", "examples"], - "exclude": ["src/_shims/**/*-deno.ts", "tests/smoketests/build-package.test.ts"], + "exclude": ["src/_shims/**/*-deno.ts", "tests/smoketests/build-package.test.ts", "src/types.ts"], "compilerOptions": { "target": "es2020", "lib": ["es2020"],