cp dines

Author: dines-rl

README.md

@@ -51,7 +51,7 @@ await devbox.shutdown();
 
 ## Core Concepts
 
-### RunloopSDK
+### [RunloopSDK](https://runloopai.github.io/api-client-ts/stable/classes/RunloopSDK.html)
 
 The main SDK class that provides access to all Runloop functionality:
 
@@ -68,26 +68,11 @@ const sdk = new RunloopSDK({
 
 The SDK provides object-oriented interfaces for all major Runloop resources:
 
-- **`sdk.devbox`** - Devbox management (create, list, execute commands, file operations)
-- **`sdk.blueprint`** - Blueprint management (create, list, build blueprints)
-- **`sdk.snapshot`** - Snapshot management (list disk snapshots)
-- **`sdk.storageObject`** - Storage object management (upload, download, list objects)
-- **`sdk.api`** - Direct access to the legacy REST API client
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+- **[`sdk.devbox`](https://runloopai.github.io/api-client-ts/stable/classes/RunloopSDK.Devbox.html)** - Devbox management (create, list, execute commands, file operations)
+- **[`sdk.blueprint`](https://runloopai.github.io/api-client-ts/stable/classes/RunloopSDK.Blueprint.html)** - Blueprint management (create, list, build blueprints)
+- **[`sdk.snapshot`](https://runloopai.github.io/api-client-ts/stable/classes/RunloopSDK.Snapshot.html)** - Snapshot management (list disk snapshots)
+- **[`sdk.storageObject`](https://runloopai.github.io/api-client-ts/stable/classes/RunloopSDK.StorageObject.html)** - Storage object management (upload, download, list objects)
+- **[`sdk.api`](https://runloopai.github.io/api-client-ts/stable/classes/Runloop.html)** - Direct access to the legacy REST API client
 
 ## Installation
 

src/sdk/blueprint.ts

@@ -11,12 +11,43 @@ import { Devbox } from './devbox';
 
 /**
  * Object-oriented interface for working with Blueprints.
+ *
+ * ## Overview
+ *
+ * The `Blueprint` class provides a high-level, object-oriented API for managing blueprints.
+ * 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.
+ *
+ * ## Quickstart
+ *
+ * ### Basic Creation
+ * ```typescript
+ * import { RunloopSDK } from '@runloop/api-client-ts';
+ *
+ * const runloop = new RunloopSDK();
+ * const blueprint = await runloop.blueprint.create({
+ *   name: 'my-blueprint',
+ *   dockerfile: 'FROM ubuntu:22.04
+ *                RUN apt-get update',
+ * });
+ * console.log(`Created blueprint: ${blueprint.id}`);
+ *
+ * // Create a devbox from the blueprint
+ * const devbox = await blueprint.createDevbox({ name: 'my-devbox' });
  * ```
+ *
  */
 export class Blueprint {
   private client: Runloop;
   private _id: string;
 
+  /**
+   * Creates a new Blueprint instance.
+   *
+   * @private
+   * @param {Runloop} client - The Runloop client instance
+   * @param {string} id - The blueprint ID
+   */
   private constructor(client: Runloop, id: string) {
     this.client = client;
     this._id = id;

src/sdk/devbox.ts

@@ -51,6 +51,12 @@ export class DevboxNetOps {
 
   /**
    * Create an SSH key for remote access to the devbox.
+   *
+   * @example
+   * ```typescript
+   * const sshKey = await devbox.net.createSSHKey();
+   * ```
+   *
    * @param {Core.RequestOptions} [options] - Request options
    * @returns {Promise<unknown>} SSH key creation result
    */
@@ -60,6 +66,12 @@ export class DevboxNetOps {
 
   /**
    * Create a tunnel to a port on the devbox.
+   *
+   * @example
+   * ```typescript
+   * const tunnel = await devbox.net.createTunnel({ port: 8080 });
+   * ```
+   *
    * @param {DevboxCreateTunnelParams} params - Tunnel creation parameters
    * @param {Core.RequestOptions} [options] - Request options
    * @returns {Promise<unknown>} Tunnel creation result
@@ -70,6 +82,12 @@ export class DevboxNetOps {
 
   /**
    * Remove a tunnel from the devbox.
+   *
+   * @example
+   * ```typescript
+   * await devbox.net.removeTunnel({ port: 8080 });
+   * ```
+   *
    * @param {DevboxRemoveTunnelParams} params - Tunnel removal parameters
    * @param {Core.RequestOptions} [options] - Request options
    * @returns {Promise<unknown>} Tunnel removal result
@@ -258,6 +276,13 @@ export class DevboxFileOps {
   /**
    * Download file contents (supports binary files).
    *
+   * @example
+   * ```typescript
+   * const response = await devbox.file.download({ path: '/app/data.bin' });
+   * const blob = await response.blob();
+   * // Process binary data...
+   * ```
+   *
    * @param {DevboxDownloadFileParams} params - Parameters containing the file path
    * @param {Core.RequestOptions} [options] - Request options
    * @returns {Promise<Response>} Response with file contents
@@ -269,6 +294,15 @@ export class DevboxFileOps {
   /**
    * Upload a file to the devbox.
    *
+   * @example
+   * ```typescript
+   * const file = new File(['content'], 'data.txt');
+   * await devbox.file.upload({
+   *   path: '/app/data.txt',
+   *   file: file,
+   * });
+   * ```
+   *
    * @param {DevboxUploadFileParams} params - Parameters containing the file path and file to upload
    * @param {Core.RequestOptions} [options] - Request options
    * @returns {Promise<unknown>} Upload result
@@ -284,11 +318,13 @@ export class DevboxFileOps {
  * ## Overview
  *
  * The `Devbox` class provides a high-level, object-oriented API for managing devboxes.
- * It wraps the low-level API client and provides convenient methods for common operations.
+ * Devboxes are containers that run your code in a consistent environment. They have the the following operations:
+ * - {@link DevboxNetOps net} - Network operations
+ * - {@link DevboxCmdOps cmd} - Command execution operations
+ * - {@link DevboxFileOps file} - File operations
  *
- * ## Creating Devboxes
+ * ## Quickstart
  *
- * ### Basic Creation
  * ```typescript
  * import { RunloopSDK } from '@runloop/api-client-ts';
  *
@@ -334,7 +370,9 @@ export class Devbox {
    * ```typescript
    * const runloop = new RunloopSDK();
    * const devbox = await runloop.devbox.create({ name: 'my-devbox' });
-   * console.log(`Devbox ${devbox.id} is ready!`);
+   *
+   * devbox.cmd.exec({ command: 'echo "Hello, World!"' });
+   * ...
    * ```
    *
    * @param {Runloop} client - The Runloop client instance
@@ -354,6 +392,15 @@ export class Devbox {
   /**
    * Create a new Devbox from a Blueprint and wait for it to reach the running state.
    *
+   * @example
+   * ```typescript
+   * const devbox = await Devbox.createFromBlueprintId(
+   *   runloop,
+   *   blueprint.id,
+   *   { name: 'my-devbox' }
+   * );
+   * ```
+   *
    * @param {Runloop} client - The Runloop client instance
    * @param {string} blueprintId - The blueprint ID to create from
    * @param {Omit<DevboxCreateParams, 'blueprint_id' | 'snapshot_id' | 'blueprint_name'>} [params] - Additional devbox creation parameters
@@ -400,6 +447,15 @@ export class Devbox {
   /**
    * Create a new Devbox from a Snapshot and wait for it to reach the running state.
    *
+   * @example
+   * ```typescript
+   * const devbox = await Devbox.createFromSnapshot(
+   *   runloop,
+   *   snapshot.id,
+   *   { name: 'restored-devbox' }
+   * );
+   * ```
+   *
    * @param {Runloop} client - The Runloop client instance
    * @param {string} snapshotId - The snapshot ID to create from
    * @param {Omit<DevboxCreateParams, 'snapshot_id' | 'blueprint_id' | 'blueprint_name'>} [params] - Additional devbox creation parameters
@@ -424,6 +480,12 @@ export class Devbox {
    * Create a Devbox instance by ID without retrieving from API.
    * Use getInfo() to fetch the actual data when needed.
    *
+   * @example
+   * ```typescript
+   * const devbox = Devbox.fromId(runloop, 'devbox-123');
+   * const info = await devbox.getInfo();
+   * ```
+   *
    * @param {Runloop} client - The Runloop client instance
    * @param {string} id - The devbox ID
    * @returns {Devbox} A {@link Devbox} instance
@@ -434,6 +496,7 @@ export class Devbox {
 
   /**
    * Get the devbox ID.
+   * @returns {string} The devbox ID
    */
   get id(): string {
     return this._id;
@@ -443,6 +506,13 @@ export class Devbox {
    * Start streaming logs with callbacks.
    * Returns a promise that resolves when all streams complete.
    * Uses SSE streams from the old SDK with auto-reconnect.
+   *
+   * @private
+   * @param {string} executionId - The execution ID to stream logs for
+   * @param {(line: string) => void} [stdout] - Callback for stdout log lines
+   * @param {(line: string) => void} [stderr] - Callback for stderr log lines
+   * @param {(line: string) => void} [output] - Callback for all log lines (both stdout and stderr)
+   * @returns {Promise<void>} Promise that resolves when all streams complete
    */
   private startStreamingWithCallbacks(
     executionId: string,
@@ -492,6 +562,14 @@ export class Devbox {
 
   /**
    * Get the complete devbox data from the API.
+   *
+   * @example
+   * ```typescript
+   * const devbox = Devbox.fromId(runloop, 'devbox-123');
+   * const info = await devbox.getInfo();
+   * console.log(`Devbox name: ${info.name}, status: ${info.status}`);
+   * ```
+   *
    * @param {Core.RequestOptions} [options] - Request options
    * @returns {Promise<DevboxView>} The devbox data
    */
@@ -503,6 +581,13 @@ export class Devbox {
    * Wait for the devbox to reach the running state.
    * Uses optimized server-side polling for better performance.
    *
+   * @example
+   * ```typescript
+   * const devbox = Devbox.fromId(runloop, 'devbox-123');
+   * await devbox.awaitRunning();
+   * console.log('Devbox is now running');
+   * ```
+   *
    * @param {Core.RequestOptions & { polling?: Partial<PollingOptions<DevboxView>> }} [options] - Request options with optional polling configuration
    * @returns {Promise<DevboxView>} The devbox data when running state is reached
    */
@@ -516,6 +601,13 @@ export class Devbox {
    * Wait for the devbox to reach the suspended state.
    * Uses optimized server-side polling for better performance.
    *
+   * @example
+   * ```typescript
+   * await devbox.suspend();
+   * await devbox.awaitSuspended();
+   * console.log('Devbox is now suspended');
+   * ```
+   *
    * @param {Core.RequestOptions & { polling?: Partial<PollingOptions<DevboxView>> }} [options] - Request options with optional polling configuration
    * @returns {Promise<DevboxView>} The devbox data when suspended state is reached
    */
@@ -570,6 +662,12 @@ export class Devbox {
 
   /**
    * Shutdown the devbox.
+   *
+   * @example
+   * ```typescript
+   * await devbox.shutdown();
+   * ```
+   *
    * @param {Core.RequestOptions} [options] - Request options
    * @returns {Promise<unknown>} Shutdown result
    */
@@ -579,6 +677,13 @@ export class Devbox {
 
   /**
    * Suspend the devbox and create a disk snapshot.
+   *
+   * @example
+   * ```typescript
+   * await devbox.suspend();
+   * await devbox.awaitSuspended();
+   * ```
+   *
    * @param {Core.RequestOptions} [options] - Request options
    * @returns {Promise<unknown>} Suspend result
    */
@@ -588,6 +693,13 @@ export class Devbox {
 
   /**
    * Resume a suspended devbox.
+   *
+   * @example
+   * ```typescript
+   * await devbox.resume();
+   * await devbox.awaitRunning();
+   * ```
+   *
    * @param {Core.RequestOptions} [options] - Request options
    * @returns {Promise<unknown>} Resume result
    */
@@ -597,6 +709,13 @@ export class Devbox {
 
   /**
    * Send a keep-alive signal to prevent idle shutdown.
+   *
+   * @example
+   * ```typescript
+   * // Send keep-alive periodically
+   * setInterval(() => devbox.keepAlive(), 60000);
+   * ```
+   *
    * @param {Core.RequestOptions} [options] - Request options
    * @returns {Promise<unknown>} Keep-alive result
    */
@@ -605,13 +724,41 @@ export class Devbox {
   }
 }
 
+/**
+ * Namespace for Devbox-related types and classes.
+ * Provides convenient access to operation classes and types.
+ */
 export declare namespace Devbox {
+  /**
+   * Network operations class for devboxes.
+   * @see {@link DevboxNetOps}
+   */
   export {
     DevboxNetOps as NetOps,
+    /**
+     * Command execution operations class for devboxes.
+     * @see {@link DevboxCmdOps}
+     */
     DevboxCmdOps as CmdOps,
+    /**
+     * File operations class for devboxes.
+     * @see {@link DevboxFileOps}
+     */
     DevboxFileOps as FileOps,
+    /**
+     * Execution class for tracking async command execution.
+     * @see {@link Execution}
+     */
     Execution as Execution,
+    /**
+     * ExecutionResult class for accessing command execution results.
+     * @see {@link ExecutionResult}
+     */
     ExecutionResult as ExecutionResult,
+    /**
+     * Streaming callbacks interface for real-time log processing.
+     * @see {@link ExecuteStreamingCallbacks}
+     */
     type ExecuteStreamingCallbacks as ExecuteStreamingCallbacks,
   };
 }