@banata-boxes/sdk 0.2.1 → 0.2.3

package/src/index.ts

@@ -1,9 +1,9 @@
 // sdk/src/index.ts
-// Customer-facing TypeScript SDK for Browser-as-a-Service
+// Customer-facing TypeScript SDK for Banata sandboxes
 //
 // M7 FIX: Added retry with exponential backoff on transient errors (5xx, network).
 
-export interface BrowserConfig {
+interface BrowserConfig {
   /** Session weight: light (512MB, default), medium (1GB), heavy (2GB — Pro+) */
   weight?: 'light' | 'medium' | 'heavy';
   /** Isolation mode: shared (default) or dedicated (Pro+) */
@@ -43,7 +43,7 @@ export interface BrowserConfig {
   timeout?: number;
 }
 
-export interface BrowserSession {
+interface BrowserSession {
   id: string;
   status: 'queued' | 'assigning' | 'ready' | 'active' | 'ending' | 'ended' | 'failed';
   waitTimedOut?: boolean;
@@ -64,6 +64,11 @@ export interface BrowserSession {
 export interface UsageInfo {
   totalSessions: number;
   totalBrowserHours: number;
+  totalSandboxSessions?: number;
+  totalSandboxHours?: number;
+  sandboxSizeBreakdown?: {
+    standard: number;
+  };
   weightBreakdown: {
     light: number;
     medium: number;
@@ -78,6 +83,8 @@ export interface BillingInfo {
   currentPeriod: {
     totalSessions: number;
     totalBrowserHours: number;
+    totalSandboxSessions?: number;
+    totalSandboxHours?: number;
     weightBreakdown: {
       light: number;
       medium: number;
@@ -86,7 +93,7 @@ export interface BillingInfo {
   };
 }
 
-export interface LaunchedBrowserSession {
+interface LaunchedBrowserSession {
   cdpUrl: string;
   sessionId: string;
   previewViewerUrl: string | null;
@@ -263,6 +270,15 @@ export class BanataError extends Error {
 /** @deprecated Use BanataError instead */
 export const BrowserServiceError = BanataError;
 
+const BROWSER_SESSIONS_UNSUPPORTED_MESSAGE =
+  "Browser-only sessions are not currently supported. Use BanataSandbox with browser capabilities instead.";
+
+function throwBrowserSessionsUnsupported(): never {
+  throw new BanataError(BROWSER_SESSIONS_UNSUPPORTED_MESSAGE, 501, {
+    code: "NOT_SUPPORTED",
+  });
+}
+
 /** Check if an HTTP status is retryable (5xx or 429) */
 function isRetryableStatus(status: number): boolean {
   return status >= 500 || status === 429;
@@ -284,10 +300,8 @@ function derivePreviewConnection(
     const parsed = new URL(rawUrl);
     const token = parsed.searchParams.get("token");
     const sessionId = parsed.searchParams.get("session");
+    const key = parsed.searchParams.get("key");
     const machine = parsed.searchParams.get("machine");
-    if (!token || !sessionId) {
-      return null;
-    }
 
     const httpProtocol =
       parsed.protocol === "https:" || parsed.protocol === "wss:"
@@ -299,6 +313,27 @@ function derivePreviewConnection(
         : parsed.protocol === "http:"
           ? "ws:"
           : parsed.protocol;
+    const isDirectPreviewUrl =
+      parsed.pathname.endsWith("/ws") && parsed.pathname.includes("/preview/");
+
+    if (isDirectPreviewUrl && key) {
+      const basePath = parsed.pathname.slice(0, -3);
+      const search = new URLSearchParams({ key }).toString();
+      return {
+        rawUrl,
+        token: key,
+        sessionId: sessionId ?? "preview",
+        startUrl: `${httpProtocol}//${parsed.host}${basePath}/start?${search}`,
+        navigateUrl: `${httpProtocol}//${parsed.host}${basePath}/navigate?${search}`,
+        resizeUrl: `${httpProtocol}//${parsed.host}${basePath}/resize?${search}`,
+        wsUrl: `${wsProtocol}//${parsed.host}${parsed.pathname}?${search}`,
+      };
+    }
+
+    if (!token || !sessionId) {
+      return null;
+    }
+
     const searchParams = new URLSearchParams({
       token,
       session: sessionId,
@@ -307,8 +342,6 @@ function derivePreviewConnection(
       searchParams.set("machine", machine);
     }
     const search = searchParams.toString();
-    const isDirectPreviewUrl =
-      parsed.pathname.endsWith("/ws") && parsed.pathname.includes("/preview/");
 
     if (isDirectPreviewUrl) {
       const basePath = parsed.pathname.slice(0, -3);
@@ -337,25 +370,6 @@ function derivePreviewConnection(
   }
 }
 
-function withMachineQuery(
-  rawUrl: string | null | undefined,
-  machineId: string | null | undefined,
-): string | null | undefined {
-  if (!rawUrl || !machineId) {
-    return rawUrl;
-  }
-
-  try {
-    const parsed = new URL(rawUrl);
-    if (!parsed.searchParams.get("machine")) {
-      parsed.searchParams.set("machine", machineId);
-    }
-    return parsed.toString();
-  } catch {
-    return rawUrl;
-  }
-}
-
 function deriveOpenCodeConnection(
   rawUrl: string | null | undefined,
 ): OpenCodeConnectionInfo | null {
@@ -391,6 +405,25 @@ function deriveOpenCodeConnection(
   }
 }
 
+function withMachineQuery(
+  rawUrl: string | null | undefined,
+  machineId: string | null | undefined,
+): string | null | undefined {
+  if (!rawUrl || !machineId) {
+    return rawUrl;
+  }
+
+  try {
+    const parsed = new URL(rawUrl);
+    if (!parsed.searchParams.get("machine")) {
+      parsed.searchParams.set("machine", machineId);
+    }
+    return parsed.toString();
+  } catch {
+    return rawUrl;
+  }
+}
+
 async function parseJsonResponse(response: Response): Promise<unknown> {
   const text = await response.text();
   if (!text) {
@@ -508,8 +541,7 @@ function isSandboxSessionOperationallyReady(
     return false;
   }
 
-  const browserMode = session.capabilities?.browser?.mode ?? "none";
-  if (browserMode !== "none") {
+  if (session.capabilities?.browser) {
     if (!session.pairedBrowser?.cdpUrl) {
       return false;
     }
@@ -528,7 +560,7 @@ function isSandboxSessionOperationallyReady(
   return true;
 }
 
-export class BrowserCloud {
+class BrowserCloud {
   private apiKey: string;
   private baseUrl: string;
   private appUrl: string;
@@ -634,56 +666,37 @@ export class BrowserCloud {
 
   /** Create a new browser session */
   async createBrowser(config: BrowserConfig = {}): Promise<BrowserSession> {
-    const { timeout, waitTimeoutMs, ...rest } = config;
-    const requestBody: Record<string, unknown> = { ...rest };
-    if (waitTimeoutMs !== undefined) {
-      requestBody.waitTimeoutMs = waitTimeoutMs;
-    }
-    return this.request<BrowserSession>('/v1/browsers', {
-      method: 'POST',
-      body: JSON.stringify(requestBody),
-    });
+    void config;
+    throwBrowserSessionsUnsupported();
   }
 
   /** Get session status */
   async getBrowser(sessionId: string): Promise<BrowserSession> {
-    return this.request<BrowserSession>(
-      `/v1/browsers?id=${encodeURIComponent(sessionId)}`
-    );
+    void sessionId;
+    throwBrowserSessionsUnsupported();
   }
 
   /** End a session */
   async closeBrowser(sessionId: string): Promise<void> {
-    await this.request(`/v1/browsers?id=${encodeURIComponent(sessionId)}`, {
-      method: 'DELETE',
-    });
+    void sessionId;
+    throwBrowserSessionsUnsupported();
   }
 
   /** Derive the preview websocket/start endpoints for a live browser session. */
   async getPreviewConnection(sessionId: string): Promise<PreviewConnectionInfo | null> {
-    const session = await this.getBrowser(sessionId);
-    return derivePreviewConnection(
-      session.previewUrl ?? withMachineQuery(session.cdpUrl, session.machineId),
-    );
+    void sessionId;
+    throwBrowserSessionsUnsupported();
   }
 
   async getPreviewViewerUrl(sessionId: string): Promise<string | null> {
-    const session = await this.getBrowser(sessionId);
-    return buildPreviewViewerUrl(
-      session.previewUrl ?? withMachineQuery(session.cdpUrl, session.machineId),
-      this.appUrl,
-    );
+    void sessionId;
+    throwBrowserSessionsUnsupported();
   }
 
   /** Start the remote browser preview backend for a live browser session. */
   async startPreview(sessionId: string): Promise<PreviewCommandResponse> {
-    const connection = await this.getPreviewConnection(sessionId);
-    if (!connection) {
-      throw new BanataError("Browser preview is not available for this session", 409);
-    }
-    return requestPreviewEndpoint<PreviewCommandResponse>(connection.startUrl, {
-      method: "POST",
-    });
+    void sessionId;
+    throwBrowserSessionsUnsupported();
   }
 
   /** Navigate the live browser preview session. */
@@ -691,15 +704,9 @@ export class BrowserCloud {
     sessionId: string,
     url: string,
   ): Promise<PreviewCommandResponse> {
-    const connection = await this.getPreviewConnection(sessionId);
-    if (!connection) {
-      throw new BanataError("Browser preview is not available for this session", 409);
-    }
-    return requestPreviewEndpoint<PreviewCommandResponse>(connection.navigateUrl, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ url }),
-    });
+    void sessionId;
+    void url;
+    throwBrowserSessionsUnsupported();
   }
 
   /** Resize the live browser preview session if the preview backend supports it. */
@@ -707,15 +714,9 @@ export class BrowserCloud {
     sessionId: string,
     size: { width?: number; height?: number },
   ): Promise<PreviewCommandResponse> {
-    const connection = await this.getPreviewConnection(sessionId);
-    if (!connection) {
-      throw new BanataError("Browser preview is not available for this session", 409);
-    }
-    return requestPreviewEndpoint<PreviewCommandResponse>(connection.resizeUrl, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(size),
-    });
+    void sessionId;
+    void size;
+    throwBrowserSessionsUnsupported();
   }
 
   /** Wait until session is ready and return CDP URL */
@@ -723,28 +724,9 @@ export class BrowserCloud {
     sessionId: string,
     timeoutMs: number = 30_000
   ): Promise<string> {
-    const start = Date.now();
-
-    while (Date.now() - start < timeoutMs) {
-      const session = await this.getBrowser(sessionId);
-
-      if (isBrowserSessionOperationallyReady(session)) {
-        return session.cdpUrl;
-      }
-      if (session.status === 'failed') {
-        throw new BanataError('Session failed to start', 500);
-      }
-      if (session.status === 'ended' || session.status === 'ending') {
-        throw new BanataError('Session ended before becoming ready', 410);
-      }
-
-      await sleep(500);
-    }
-
-    throw new BanataError(
-      `Session ${sessionId} not ready within ${timeoutMs}ms`,
-      408
-    );
+    void sessionId;
+    void timeoutMs;
+    throwBrowserSessionsUnsupported();
   }
 
   /**
@@ -763,10 +745,12 @@ export class BrowserCloud {
   async launch(
     config: BrowserConfig = {}
   ): Promise<LaunchedBrowserSession> {
+    void config;
+    throwBrowserSessionsUnsupported();
     const session = await this.createBrowser(config);
     let cdpUrl: string;
     if (isBrowserSessionOperationallyReady(session)) {
-      cdpUrl = session.cdpUrl;
+      cdpUrl = session.cdpUrl!;
     } else {
       try {
         cdpUrl = await this.waitForReady(
@@ -864,19 +848,11 @@ export class BrowserCloud {
 // ── Sandbox types ──
 
 export interface SandboxConfig {
-  /** Sandbox runtime: bun, python, or base shell */
-  runtime?: 'bun' | 'python' | 'base';
-  /** Sandbox compute shape. */
-  size?: 'standard';
   /** Environment variables to inject into the sandbox */
   env?: Record<string, string>;
-  /** Whether sandbox is ephemeral (destroyed on kill). Default: true */
-  ephemeral?: boolean;
-  /** Max session duration in ms */
-  maxDurationMs?: number;
   /** Preferred region for sandbox placement */
   region?: string;
-  /** Optional powerhouse capabilities to prelaunch inside the sandbox */
+  /** Supported capabilities to prelaunch inside the sandbox */
   capabilities?: SandboxCapabilities;
   /** Ask the API to wait briefly for the sandbox to become ready before returning */
   waitUntilReady?: boolean;
@@ -890,14 +866,14 @@ export interface SandboxCapabilities {
   opencode?: {
     enabled: boolean;
     defaultAgent?: "build" | "plan";
-    allowPromptApi?: boolean;
   };
   browser?: {
-    mode?: "none" | "paired-banata-browser" | "local-chromium";
+    /** Save a low-resolution MP4 recording as an artifact. Team plan only. */
     recording?: boolean;
-    persistentProfile?: boolean;
-    streamPreview?: boolean;
-    humanInLoop?: boolean;
+    /** Route outbound traffic through your own proxy. Team plan only. */
+    byoProxyUrl?: string;
+    /** True when a BYO proxy is configured for this sandbox. */
+    byoProxyConfigured?: boolean;
     viewport?: {
       width?: number;
       height?: number;
@@ -907,18 +883,10 @@ export interface SandboxCapabilities {
     libreofficeHeadless?: boolean;
   };
   storage?: {
-    workspace?: "ephemeral" | "checkpointed";
     artifactPrefix?: string;
   };
 }
 
-export interface SandboxCredentialDescriptor {
-  name: string;
-  kind: string;
-  target: string;
-  lastInjectedAt?: number;
-}
-
 export interface SandboxArtifactItem {
   key: string;
   path: string;
@@ -941,8 +909,6 @@ export interface SandboxPairedBrowser {
   sessionId?: string;
   cdpUrl?: string;
   previewUrl?: string;
-  recording?: boolean;
-  persistentProfile?: boolean;
   controlMode?: "ai" | "human" | "shared";
   controller?: string;
   handoffRequestedAt?: number;
@@ -1028,7 +994,6 @@ export interface SandboxSession {
   terminalUrl: string | null;
   previewBaseUrl?: string | null;
   capabilities?: SandboxCapabilities | null;
-  credentialDescriptors?: SandboxCredentialDescriptor[] | null;
   pairedBrowser?: SandboxPairedBrowser | null;
   opencode?: SandboxOpencodeState | null;
   browserPreview?: SandboxBrowserPreviewState | null;
@@ -1062,9 +1027,18 @@ export interface SandboxOpencodePromptResponse {
 
 export interface SandboxCheckpointResponse {
   ok: boolean;
+  status?: number;
+  checkpointId?: string | null;
   artifacts?: SandboxArtifacts;
 }
 
+export interface SandboxCheckpointInfo {
+  id: string;
+  createTimeMs: number;
+  comment?: string;
+  history?: string[];
+}
+
 export interface SandboxArtifactDownload {
   id: string;
   key: string;
@@ -1072,6 +1046,15 @@ export interface SandboxArtifactDownload {
   expiresInSeconds: number;
 }
 
+export interface SandboxDocumentConversionResult {
+  ok: boolean;
+  inputPath: string;
+  outputPath: string;
+  format: string;
+  artifact: SandboxArtifactItem | null;
+  artifacts: SandboxArtifacts | null;
+}
+
 export interface SandboxBrowserControlResponse {
   ok: boolean;
   preview: SandboxBrowserPreviewState;
@@ -1156,6 +1139,14 @@ export interface LaunchedSandbox {
     sessionId?: string;
   }) => AsyncGenerator<SandboxOpencodeStreamEvent, void, void>;
   checkpoint: () => Promise<SandboxCheckpointResponse>;
+  listCheckpoints: () => Promise<SandboxCheckpointInfo[]>;
+  restoreCheckpoint: (checkpointId: string) => Promise<{ ok: boolean; status: number; checkpointId: string }>;
+  getArtifacts: () => Promise<{ id: string; artifacts: SandboxArtifacts | null }>;
+  getArtifactDownloadUrl: (key: string, expiresInSeconds?: number) => Promise<SandboxArtifactDownload>;
+  convertDocument: (
+    inputPath: string,
+    options?: { format?: string; outputDir?: string },
+  ) => Promise<SandboxDocumentConversionResult>;
   getRuntime: () => Promise<SandboxRuntimeState>;
   getPreview: () => Promise<SandboxBrowserPreviewInfo>;
   getPreviewConnection: () => Promise<PreviewConnectionInfo | null>;
@@ -1347,10 +1338,111 @@ export class BanataSandbox {
 
   // ── Sandbox lifecycle ──
 
+  async getUsage(): Promise<UsageInfo> {
+    return this.request<UsageInfo>('/v1/usage');
+  }
+
+  async getBilling(): Promise<BillingInfo> {
+    return this.request<BillingInfo>('/v1/billing');
+  }
+
+  async createCheckout(params: {
+    plan: 'builder' | 'pro' | 'scale';
+    successUrl?: string;
+  }): Promise<{ checkoutUrl: string; checkoutId: string }> {
+    return this.request<{ checkoutUrl: string; checkoutId: string }>('/v1/billing/checkout', {
+      method: 'POST',
+      body: JSON.stringify(params),
+    });
+  }
+
+  async listWebhooks(): Promise<WebhookEndpoint[]> {
+    const response = await this.request<{ data: WebhookEndpoint[] }>('/v1/webhooks');
+    return response.data;
+  }
+
+  async createWebhook(params: {
+    url: string;
+    description?: string;
+    eventTypes?: WebhookEventType[];
+    signingSecret?: string;
+  }): Promise<WebhookEndpoint & { signingSecret: string }> {
+    return this.request<WebhookEndpoint & { signingSecret: string }>('/v1/webhooks', {
+      method: 'POST',
+      body: JSON.stringify(params),
+    });
+  }
+
+  async deleteWebhook(id: string): Promise<void> {
+    await this.request(`/v1/webhooks?id=${encodeURIComponent(id)}`, {
+      method: 'DELETE',
+    });
+  }
+
+  async listWebhookDeliveries(limit = 50): Promise<WebhookDelivery[]> {
+    const response = await this.request<{ data: WebhookDelivery[] }>(
+      `/v1/webhooks/deliveries?limit=${encodeURIComponent(String(limit))}`
+    );
+    return response.data;
+  }
+
+  async testWebhook(id: string): Promise<{ eventId: string }> {
+    return this.request<{ eventId: string }>('/v1/webhooks/test', {
+      method: 'POST',
+      body: JSON.stringify({ id }),
+    });
+  }
+
   /** Create a new sandbox session */
   async create(config: SandboxConfig = {}): Promise<SandboxSession> {
-    const { timeout, waitTimeoutMs, ...rest } = config;
+    const { timeout, waitTimeoutMs, capabilities, ...rest } = config;
     const requestBody: Record<string, unknown> = { ...rest };
+    if (capabilities) {
+      requestBody.capabilities = {
+        ...(capabilities.opencode
+          ? {
+              opencode: {
+                enabled: capabilities.opencode.enabled,
+                ...(capabilities.opencode.defaultAgent
+                  ? { defaultAgent: capabilities.opencode.defaultAgent }
+                  : {}),
+              },
+            }
+          : {}),
+        ...(capabilities.browser?.viewport
+          || capabilities.browser?.recording !== undefined
+          || capabilities.browser?.byoProxyUrl
+          ? {
+              browser: {
+                ...(capabilities.browser?.viewport
+                  ? { viewport: capabilities.browser.viewport }
+                  : {}),
+                ...(capabilities.browser?.recording !== undefined
+                  ? { recording: capabilities.browser.recording }
+                  : {}),
+                ...(capabilities.browser?.byoProxyUrl
+                  ? { byoProxyUrl: capabilities.browser.byoProxyUrl }
+                  : {}),
+              },
+            }
+          : {}),
+        ...(capabilities.documents
+          ? {
+              documents: {
+                libreofficeHeadless:
+                  capabilities.documents.libreofficeHeadless ?? true,
+              },
+            }
+          : {}),
+        ...(capabilities.storage?.artifactPrefix
+          ? {
+              storage: {
+                artifactPrefix: capabilities.storage.artifactPrefix,
+              },
+            }
+          : {}),
+      };
+    }
     if (waitTimeoutMs !== undefined) {
       requestBody.waitTimeoutMs = waitTimeoutMs;
     }
@@ -1451,7 +1543,11 @@ export class BanataSandbox {
     /** Read a file from the sandbox */
     read: async (id: string, path: string): Promise<string> => {
       const result = await this.request<{ content: string }>(
-        `/v1/sandboxes/fs/read?id=${encodeURIComponent(id)}&path=${encodeURIComponent(path)}`
+        '/v1/sandboxes/fs/read',
+        {
+          method: 'POST',
+          body: JSON.stringify({ id, path }),
+        },
       );
       return result.content;
     },
@@ -1466,9 +1562,10 @@ export class BanataSandbox {
 
     /** List files in a directory in the sandbox */
     list: async (id: string, path?: string): Promise<FsEntry[]> => {
-      return this.request<FsEntry[]>(
-        `/v1/sandboxes/fs/list?id=${encodeURIComponent(id)}&path=${encodeURIComponent(path ?? '/workspace')}`
-      );
+      return this.request<FsEntry[]>('/v1/sandboxes/fs/list', {
+        method: 'POST',
+        body: JSON.stringify({ id, path: path ?? '/workspace' }),
+      });
     },
   };
 
@@ -1527,7 +1624,9 @@ export class BanataSandbox {
   async getOpencodeConnection(id: string): Promise<OpenCodeConnectionInfo | null> {
     const preview = await this.getPreview(id);
     return deriveOpenCodeConnection(
-      preview.browserPreviewUrl ??
+      preview.browserPreview?.websocketUrl ??
+        preview.runtime?.websocketUrl ??
+        preview.browserPreviewUrl ??
         preview.browserPreview?.publicUrl ??
         preview.pairedBrowser?.previewUrl ??
         null,
@@ -1744,6 +1843,24 @@ export class BanataSandbox {
     });
   }
 
+  async listCheckpoints(id: string): Promise<SandboxCheckpointInfo[]> {
+    const response = await this.request<{
+      id: string;
+      checkpoints: SandboxCheckpointInfo[];
+      currentCheckpointId?: string | null;
+    }>(
+      `/v1/sandboxes/checkpoints?id=${encodeURIComponent(id)}`
+    );
+    return response.checkpoints;
+  }
+
+  async restoreCheckpoint(id: string, checkpointId: string): Promise<{ ok: boolean; status: number; checkpointId: string }> {
+    return this.request<{ ok: boolean; status: number; checkpointId: string }>('/v1/sandboxes/checkpoints/restore', {
+      method: 'POST',
+      body: JSON.stringify({ id, checkpointId }),
+    });
+  }
+
   async getArtifacts(id: string): Promise<{ id: string; artifacts: SandboxArtifacts | null }> {
     return this.request(
       `/v1/sandboxes/artifacts?id=${encodeURIComponent(id)}`
@@ -1760,29 +1877,64 @@ export class BanataSandbox {
     );
   }
 
+  async convertDocument(
+    id: string,
+    inputPath: string,
+    options: {
+      format?: string;
+      outputDir?: string;
+    } = {},
+  ): Promise<SandboxDocumentConversionResult> {
+    return this.request<SandboxDocumentConversionResult>('/v1/sandboxes/documents/convert', {
+      method: 'POST',
+      body: JSON.stringify({
+        id,
+        inputPath,
+        format: options.format,
+        outputDir: options.outputDir,
+      }),
+    });
+  }
+
   async getPreview(id: string): Promise<SandboxBrowserPreviewInfo> {
     const preview = await this.request<SandboxBrowserPreviewInfo>(
       `/v1/sandboxes/browser-preview?id=${encodeURIComponent(id)}`
     );
     return {
       ...preview,
-      browserPreviewViewerUrl: buildPreviewViewerUrl(
-        preview.browserPreviewUrl,
-        this.appUrl,
-      ),
+      browserPreviewViewerUrl:
+        preview.browserPreviewViewerUrl ??
+        preview.browserPreview?.publicUrl ??
+        preview.pairedBrowser?.previewUrl ??
+        buildPreviewViewerUrl(
+          preview.browserPreview?.websocketUrl ??
+            preview.runtime?.websocketUrl ??
+            preview.browserPreviewUrl,
+          this.appUrl,
+        ),
     };
   }
 
   async getPreviewConnection(id: string): Promise<PreviewConnectionInfo | null> {
     const preview = await this.getPreview(id);
-    return derivePreviewConnection(preview.browserPreviewUrl);
+    return derivePreviewConnection(
+      preview.browserPreview?.websocketUrl ??
+        preview.runtime?.websocketUrl ??
+        preview.browserPreviewUrl,
+    );
   }
 
   async getPreviewViewerUrl(id: string): Promise<string | null> {
     const preview = await this.getPreview(id);
     return (
       preview.browserPreviewViewerUrl ??
-      buildPreviewViewerUrl(preview.browserPreviewUrl, this.appUrl)
+      preview.browserPreview?.publicUrl ??
+      buildPreviewViewerUrl(
+        preview.browserPreview?.websocketUrl ??
+          preview.runtime?.websocketUrl ??
+          preview.browserPreviewUrl,
+        this.appUrl,
+      )
     );
   }
 
@@ -1911,7 +2063,7 @@ export class BanataSandbox {
    * Usage:
    * ```ts
    * const sandbox = new BanataSandbox({ apiKey: '...' });
-   * const session = await sandbox.launch({ runtime: 'bun', size: 'standard' });
+   * const session = await sandbox.launch();
    *
    * const result = await session.exec('echo', ['Hello!']);
    * console.log(result.stdout);
@@ -1974,6 +2126,16 @@ export class BanataSandbox {
       streamOpencodeEvents: (options) =>
         this.streamOpencodeEvents(sessionId, options),
       checkpoint: () => this.checkpoint(sessionId),
+      listCheckpoints: () => this.listCheckpoints(sessionId),
+      restoreCheckpoint: (checkpointId: string) =>
+        this.restoreCheckpoint(sessionId, checkpointId),
+      getArtifacts: () => this.getArtifacts(sessionId),
+      getArtifactDownloadUrl: (key: string, expiresInSeconds?: number) =>
+        this.getArtifactDownloadUrl(sessionId, key, expiresInSeconds),
+      convertDocument: (
+        inputPath: string,
+        options?: { format?: string; outputDir?: string },
+      ) => this.convertDocument(sessionId, inputPath, options),
       getRuntime: () => this.getRuntime(sessionId),
       getPreview: () => this.getPreview(sessionId),
       getPreviewConnection: () => this.getPreviewConnection(sessionId),
@@ -2004,4 +2166,4 @@ export class BanataSandbox {
 }
 
 // Default export for convenience
-export default BrowserCloud;
+export default BanataSandbox;