documenting

Author: christianalfoni

src/PreviewTokens.ts

@@ -35,21 +35,16 @@ export class PreviewTokens extends Disposable {
 
   /**
    * Get a signed preview URL for a port using a preview token.
-   *
-   * @param port - The port to get a signed preview URL for
-   * @param token - The preview token to sign the URL with
-   * @returns The signed preview URL, or undefined if the port is not open
    */
-  getSignedPreviewUrl(token: PreviewToken, port: number): string {
+  getSignedPreviewUrl(
+    token: { sandboxId: string; token: string },
+    port: number
+  ): string {
     return `https://${token.sandboxId}-${port}.csb.app?preview_token=${token.token}`;
   }
 
   /**
-   * Generate a new preview token that can be used to access private sandbox previews.
-   *
-   * @param opts - Options
-   * @param opts.expiresAt - Optional expiration date for the preview token
-   * @returns A preview token that can be used with Ports.getSignedPreviewUrl
+   * Generate a new preview token that can be used to access private sandbox previews. By default the token never expires.
    */
   async create(
     sandboxId: string,
@@ -87,8 +82,6 @@ export class PreviewTokens extends Disposable {
 
   /**
    * List all active preview tokens for this sandbox.
-   *
-   * @returns A list of preview tokens
    */
   async list(sandboxId: string): Promise<PreviewTokenInfo[]> {
     const response = handleResponse(
@@ -115,8 +108,6 @@ export class PreviewTokens extends Disposable {
 
   /**
    * Revoke a single preview token for this sandbox.
-   *
-   * @param tokenId - The ID of the token to revoke
    */
   async revoke(sandboxId: string, tokenId: string): Promise<void> {
     handleResponse(
@@ -153,10 +144,6 @@ export class PreviewTokens extends Disposable {
 
   /**
    * Update a preview token's expiration date.
-   *
-   * @param tokenId - The ID of the token to update
-   * @param expiresAt - The new expiration date for the token (null for no expiration)
-   * @returns The updated preview token info
    */
   async update(
     sandboxId: string,

src/SandboxClient.ts renamed to src/Sandboxes.ts

@@ -56,7 +56,10 @@ export async function startVm(
   return getStartResponse(response);
 }
 
-export class SandboxClient {
+/**
+ * This class provides methods for creating and managing sandboxes.
+ */
+export class Sandboxes {
   get defaultTemplateId() {
     return getDefaultTemplateId(this.apiClient);
   }
@@ -139,7 +142,13 @@ export class SandboxClient {
   }
 
   /**
+   * Resume a sandbox.
    *
+   * - Hibernated with snapshot: It wakes up and continues within 2-3 seconds
+   * - Hibernated with expired snapshot: It will start from scratch (CLEAN bootup)
+   * - Shutdown: It will start from scratch (CLEAN bootup)
+   *
+   * Note! On CLEAN bootups the setup will run again. When hibernated a new snapshot will be created.
    */
   async resume(sandboxId: string) {
     const startResponse = await startVm(this.apiClient, sandboxId);
@@ -148,8 +157,6 @@ export class SandboxClient {
 
   /**
    * Shuts down a sandbox. Files will be saved, and the sandbox will be stopped.
-   *
-   * @param sandboxId The ID of the sandbox to shutdown
    */
   async shutdown(sandboxId: string): Promise<void> {
     const response = await vmShutdown({
@@ -166,7 +173,7 @@ export class SandboxClient {
    * Restart the sandbox. This will shutdown the sandbox, and then start it again. Files in
    * the project directory (`/project/sandbox`) will be preserved.
    *
-   * Will resolve once the sandbox is rebooted.
+   * Will resolve once the sandbox is restarted with its setup running.
    */
   public async restart(sandboxId: string, opts?: StartSandboxOpts) {
     await this.shutdown(sandboxId);
@@ -177,9 +184,7 @@ export class SandboxClient {
 
   /**
    * Hibernates a sandbox. Files will be saved, and the sandbox will be put to sleep. Next time
-   * you start the sandbox it will be resumed from the last state it was in.
-   *
-   * @param sandboxId The ID of the sandbox to hibernate
+   * you resume the sandbox it will continue from the last state it was in.
    */
   async hibernate(sandboxId: string): Promise<void> {
     const response = await vmHibernate({
@@ -193,16 +198,7 @@ export class SandboxClient {
   }
 
   /**
-   * Creates a sandbox by forking a template. You can pass in any template or sandbox id (from
-   * any sandbox/template created on codesandbox.io, even your own templates) or don't pass
-   * in anything and we'll use the default universal template.
-   *
-   * This function will also start & connect to the VM of the created sandbox with a global session, and return a {@link Sandbox}
-   * that allows you to control the VM. Pass "autoConnect: false" to only return the session data.
-   *
-   * @param opts Additional options for creating the sandbox
-   *
-   * @returns A promise that resolves to a {@link Sandbox}, which you can use to control the VM
+   * Create a sandbox from a template or git repository. By default we will create a sandbox from the default template.
    */
   async create(
     opts: CreateSandboxOpts & StartSandboxOpts = { source: "template" }

src/browser.ts

@@ -7,39 +7,7 @@ export * from "./sessions/WebSocketSession";
 export { createPreview, Preview } from "./previews";
 
 /**
- * With this function you can connect to a sandbox from the browser.
- *
- * ## Why does this exist?
- *
- * The CodeSandbox API is a REST API that you can use to control sandboxes. However, it
- * requires your CodeSandbox API token to be sent with every request. This makes it
- * unsafe to use from the browser, where you don't want to expose your API token.
- *
- * With this helper function, you can generate a sandbox on the server, and then share a single-use
- * token that can be used to create a connection to that sandbox from the browser.
- *
- * ## Example
- *
- * To use this function, you first need to start a sandbox on the server:
- *
- * ```ts
- * import { CodeSandbox } from "@codesandbox/sdk";
- *
- * const client = new CodeSandbox(apiToken);
- *
- * const startData = await client.sandbox.start("my-sandbox-id");
- * ```
- *
- * Then you can start a sandbox using this start data in the browser:
- *
- * ```ts
- * import { connectToSandbox } from "@codesandbox/sdk/browser";
- *
- * // Get the start data from the server
- * const startData = ...;
- *
- * const sandbox = await connectToSandbox(startData);
- * ```
+ * Connect to a Sandbox from the browser and automatically reconnect. `getSession` requires and endpoint that resumes the Sandbox. `onFocusChange` can be used to notify when a reconnect should happen.
  */
 export async function connectToSandbox(options: {
   id: string;

src/index.ts

@@ -1,7 +1,7 @@
-import { SandboxClient } from "./SandboxClient";
+import { Sandboxes } from "./Sandboxes";
 import { ClientOpts } from "./types";
 
-export { SandboxClient };
+export { Sandboxes as SandboxClient };
 
 export { VMTier } from "./VMTier";
 
@@ -24,11 +24,11 @@ function ensure<T>(value: T | undefined, message: string): T {
 }
 
 export class CodeSandbox {
-  public readonly sandboxes: SandboxClient;
+  public readonly sandboxes: Sandboxes;
   /**
    * @deprecated Use `sandboxes` instead
    */
-  public readonly sandbox: SandboxClient;
+  public readonly sandbox: Sandboxes;
 
   /**
    * Provider for generating preview tokens. These tokens can be used to generate signed
@@ -67,7 +67,7 @@ export class CodeSandbox {
       })
     );
 
-    this.sandboxes = new SandboxClient(apiClient);
+    this.sandboxes = new Sandboxes(apiClient);
     this.sandbox = this.sandboxes;
     this.previewTokens = new PreviewTokens(apiClient);
   }

src/previews/index.ts

@@ -8,6 +8,9 @@ import {
 
 export { Preview, InjectFunction };
 
+/**
+ * Create a preview that you can interact with. By default you can interact with navigation, but you can also inject your own code and do custom message passing. Append the `iframe` to your DOM to display the preview.
+ */
 export function createPreview<
   MessageToPreview extends Message = BaseMessageToPreview,
   MessageFromPreview extends Message = BaseMessageFromPreview

src/sandbox.ts

@@ -20,15 +20,31 @@ import { handleResponse } from "./utils/api";
 import { VMTier } from "./VMTier";
 import { WebSocketSession } from "./sessions/WebSocketSession";
 import { RestSession } from "./sessions/RestSession";
-import { SandboxClient, startVm } from "./SandboxClient";
+import { Sandboxes, startVm } from "./Sandboxes";
 
 export class Sandbox {
+  /**
+   * How the Sandbox booted up:
+   * - RUNNING: Already running
+   * - RESUME: Resumes from hibernation
+   * - CLEAN: Clean bootup, no hibernation snapshot or shutdown
+   * - FORK: When the sandbox was created from a template
+   */
   get bootupType() {
     return this.pitcherManagerResponse.bootupType;
   }
+
+  /**
+   * The cluster the Sandbox is running on.
+   */
   get cluster() {
     return this.pitcherManagerResponse.cluster;
   }
+
+  /**
+   * Whether the Sandbox Agent version is up to date. Use "restart" to
+   * update the agent.
+   */
   get isUpToDate() {
     return (
       this.pitcherManagerResponse.latestPitcherVersion ===
@@ -53,9 +69,6 @@ export class Sandbox {
    * Updates the specs that this sandbox runs on. It will dynamically scale the sandbox to the
    * new specs without a reboot. Be careful when scaling specs down, if the VM is using more memory
    * than it can scale down to, it can become very slow.
-   *
-   * @param id The ID of the sandbox to update
-   * @param tier The new VM tier
    */
   async updateTier(sandboxId: string, tier: VMTier): Promise<void> {
     const response = await vmUpdateSpecs({
@@ -69,6 +82,10 @@ export class Sandbox {
     handleResponse(response, `Failed to update sandbox tier ${sandboxId}`);
   }
 
+  /**
+   * Updates the hibernation timeout for this sandbox. This is the amount of seconds the sandbox
+   * will be kept alive without activity before it is automatically hibernated. Activity can be sessions or interactions with any endpoints exposed by the Sandbox.
+   */
   async updateHibernationTimeout(
     sandboxId: string,
     timeoutSeconds: number
@@ -122,6 +139,9 @@ export class Sandbox {
     return session;
   }
 
+  /**
+   * Connects to the Sandbox using a WebSocket connection, allowing you to interact with it. You can pass a custom session to connect to a specific user workspace, controlling permissions, git credentials and environment variables.
+   */
   async connect(
     customSession?: SessionCreateOptions
   ): Promise<WebSocketSession> {
@@ -189,6 +209,9 @@ export class Sandbox {
     return new WebSocketSession(pitcherClient, () => customSession?.env ?? {});
   }
 
+  /**
+   * Returns a REST API client connected to this Sandbox, allowing you to interact with it. You can pass a custom session to connect to a specific user workspace, controlling permissions, git credentials and environment variables.
+   */
   async createRestSession(customSession?: SessionCreateOptions) {
     const session = customSession
       ? await this.createSession(customSession)
@@ -197,6 +220,9 @@ export class Sandbox {
     return new RestSession(session);
   }
 
+  /**
+   * Returns a browser session connected to this Sandbox, allowing you to interact with it. You can pass a custom session to connect to a specific user workspace, controlling permissions, git credentials and environment variables.
+   */
   async createBrowserSession(
     customSession?: SessionCreateOptions
   ): Promise<SandboxBrowserSession> {