@banata-boxes/sdk 0.2.1 → 0.2.3

package/dist/index.js

@@ -54,12 +54,27 @@ function derivePreviewConnection(rawUrl) {
     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");
+    const httpProtocol = parsed.protocol === "https:" || parsed.protocol === "wss:" ? "https:" : "http:";
+    const wsProtocol = parsed.protocol === "https:" ? "wss:" : 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 search2 = new URLSearchParams({ key }).toString();
+      return {
+        rawUrl,
+        token: key,
+        sessionId: sessionId ?? "preview",
+        startUrl: `${httpProtocol}//${parsed.host}${basePath}/start?${search2}`,
+        navigateUrl: `${httpProtocol}//${parsed.host}${basePath}/navigate?${search2}`,
+        resizeUrl: `${httpProtocol}//${parsed.host}${basePath}/resize?${search2}`,
+        wsUrl: `${wsProtocol}//${parsed.host}${parsed.pathname}?${search2}`
+      };
+    }
     if (!token || !sessionId) {
       return null;
     }
-    const httpProtocol = parsed.protocol === "https:" || parsed.protocol === "wss:" ? "https:" : "http:";
-    const wsProtocol = parsed.protocol === "https:" ? "wss:" : parsed.protocol === "http:" ? "ws:" : parsed.protocol;
     const searchParams = new URLSearchParams({
       token,
       session: sessionId
@@ -68,7 +83,6 @@ function derivePreviewConnection(rawUrl) {
       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);
       return {
@@ -94,20 +108,6 @@ function derivePreviewConnection(rawUrl) {
     return null;
   }
 }
-function withMachineQuery(rawUrl, machineId) {
-  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) {
   if (!rawUrl) {
     return null;
@@ -200,15 +200,11 @@ function parseSseBlock(block) {
     };
   }
 }
-function isBrowserSessionOperationallyReady(session) {
-  return (session.status === "ready" || session.status === "active") && Boolean(session.cdpUrl);
-}
 function isSandboxSessionOperationallyReady(session) {
   if (session.status !== "ready" && session.status !== "active") {
     return false;
   }
-  const browserMode = session.capabilities?.browser?.mode ?? "none";
-  if (browserMode !== "none") {
+  if (session.capabilities?.browser) {
     if (!session.pairedBrowser?.cdpUrl) {
       return false;
     }
@@ -220,8 +216,7 @@ function isSandboxSessionOperationallyReady(session) {
   }
   return true;
 }
-
-class BrowserCloud {
+class BanataSandbox {
   apiKey;
   baseUrl;
   appUrl;
@@ -283,6 +278,9 @@ class BrowserCloud {
           }
           throw error;
         }
+        if (res.status === 204) {
+          return;
+        }
         return res.json();
       } catch (err) {
         if (err instanceof BanataError) {
@@ -299,108 +297,6 @@ class BrowserCloud {
     }
     throw lastError ?? new Error("Request failed");
   }
-  async createBrowser(config = {}) {
-    const { timeout, waitTimeoutMs, ...rest } = config;
-    const requestBody = { ...rest };
-    if (waitTimeoutMs !== undefined) {
-      requestBody.waitTimeoutMs = waitTimeoutMs;
-    }
-    return this.request("/v1/browsers", {
-      method: "POST",
-      body: JSON.stringify(requestBody)
-    });
-  }
-  async getBrowser(sessionId) {
-    return this.request(`/v1/browsers?id=${encodeURIComponent(sessionId)}`);
-  }
-  async closeBrowser(sessionId) {
-    await this.request(`/v1/browsers?id=${encodeURIComponent(sessionId)}`, {
-      method: "DELETE"
-    });
-  }
-  async getPreviewConnection(sessionId) {
-    const session = await this.getBrowser(sessionId);
-    return derivePreviewConnection(session.previewUrl ?? withMachineQuery(session.cdpUrl, session.machineId));
-  }
-  async getPreviewViewerUrl(sessionId) {
-    const session = await this.getBrowser(sessionId);
-    return buildPreviewViewerUrl(session.previewUrl ?? withMachineQuery(session.cdpUrl, session.machineId), this.appUrl);
-  }
-  async startPreview(sessionId) {
-    const connection = await this.getPreviewConnection(sessionId);
-    if (!connection) {
-      throw new BanataError("Browser preview is not available for this session", 409);
-    }
-    return requestPreviewEndpoint(connection.startUrl, {
-      method: "POST"
-    });
-  }
-  async navigatePreview(sessionId, url) {
-    const connection = await this.getPreviewConnection(sessionId);
-    if (!connection) {
-      throw new BanataError("Browser preview is not available for this session", 409);
-    }
-    return requestPreviewEndpoint(connection.navigateUrl, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ url })
-    });
-  }
-  async resizePreview(sessionId, size) {
-    const connection = await this.getPreviewConnection(sessionId);
-    if (!connection) {
-      throw new BanataError("Browser preview is not available for this session", 409);
-    }
-    return requestPreviewEndpoint(connection.resizeUrl, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(size)
-    });
-  }
-  async waitForReady(sessionId, timeoutMs = 30000) {
-    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);
-  }
-  async launch(config = {}) {
-    const session = await this.createBrowser(config);
-    let cdpUrl;
-    if (isBrowserSessionOperationallyReady(session)) {
-      cdpUrl = session.cdpUrl;
-    } else {
-      try {
-        cdpUrl = await this.waitForReady(session.id, config.timeout ?? 30000);
-      } catch (err) {
-        try {
-          await this.closeBrowser(session.id);
-        } catch {}
-        throw err;
-      }
-    }
-    return {
-      cdpUrl,
-      sessionId: session.id,
-      previewViewerUrl: buildPreviewViewerUrl(session.previewUrl ?? withMachineQuery(cdpUrl, session.machineId), this.appUrl),
-      close: () => this.closeBrowser(session.id),
-      getPreviewConnection: () => this.getPreviewConnection(session.id),
-      getPreviewViewerUrl: () => this.getPreviewViewerUrl(session.id),
-      startPreview: () => this.startPreview(session.id),
-      navigatePreview: (url) => this.navigatePreview(session.id, url),
-      resizePreview: (size) => this.resizePreview(session.id, size)
-    };
-  }
   async getUsage() {
     return this.request("/v1/usage");
   }
@@ -438,92 +334,36 @@ class BrowserCloud {
       body: JSON.stringify({ id })
     });
   }
-}
-
-class BanataSandbox {
-  apiKey;
-  baseUrl;
-  appUrl;
-  retryConfig;
-  constructor(config) {
-    if (!config.apiKey)
-      throw new Error("API key is required");
-    this.apiKey = config.apiKey;
-    this.baseUrl = config.baseUrl ?? "https://api.boxes.banata.dev";
-    this.appUrl = config.appUrl ?? "https://boxes.banata.dev";
-    this.retryConfig = {
-      maxRetries: config.retry?.maxRetries ?? 3,
-      baseDelayMs: config.retry?.baseDelayMs ?? 500,
-      maxDelayMs: config.retry?.maxDelayMs ?? 1e4
-    };
-  }
-  get headers() {
-    return {
-      Authorization: `Bearer ${this.apiKey}`,
-      "Content-Type": "application/json"
-    };
-  }
-  async request(path, options = {}) {
-    const { maxRetries, baseDelayMs, maxDelayMs } = this.retryConfig;
-    let lastError;
-    for (let attempt = 0;attempt <= maxRetries; attempt++) {
-      try {
-        const res = await fetch(`${this.baseUrl}${path}`, {
-          ...options,
-          headers: { ...this.headers, ...options.headers }
-        });
-        if (!res.ok) {
-          const body = await res.text();
-          let message;
-          let parsed = {};
-          try {
-            parsed = JSON.parse(body);
-            message = parsed.error ?? body;
-          } catch {
-            message = body;
+  async create(config = {}) {
+    const { timeout, waitTimeoutMs, capabilities, ...rest } = config;
+    const requestBody = { ...rest };
+    if (capabilities) {
+      requestBody.capabilities = {
+        ...capabilities.opencode ? {
+          opencode: {
+            enabled: capabilities.opencode.enabled,
+            ...capabilities.opencode.defaultAgent ? { defaultAgent: capabilities.opencode.defaultAgent } : {}
           }
-          const error = new BanataError(message, res.status, {
-            code: parsed.code,
-            requiredPlan: parsed.requiredPlan,
-            currentPlan: parsed.currentPlan
-          });
-          if (isRetryableStatus(res.status) && attempt < maxRetries) {
-            lastError = error;
-            const retryAfterHeader = res.headers.get("Retry-After");
-            let delay;
-            if (retryAfterHeader) {
-              delay = Math.min(parseInt(retryAfterHeader, 10) * 1000, maxDelayMs);
-            } else {
-              delay = Math.min(baseDelayMs * Math.pow(2, attempt), maxDelayMs);
-            }
-            delay += Math.random() * delay * 0.25;
-            await sleep(delay);
-            continue;
+        } : {},
+        ...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 } : {}
           }
-          throw error;
-        }
-        if (res.status === 204) {
-          return;
-        }
-        return res.json();
-      } catch (err) {
-        if (err instanceof BanataError) {
-          throw err;
-        }
-        lastError = err instanceof Error ? err : new Error(String(err));
-        if (attempt < maxRetries) {
-          const delay = Math.min(baseDelayMs * Math.pow(2, attempt), maxDelayMs);
-          await sleep(delay + Math.random() * delay * 0.25);
-          continue;
-        }
-        throw new BanataError(`Network error after ${maxRetries + 1} attempts: ${lastError.message}`, 0);
-      }
+        } : {},
+        ...capabilities.documents ? {
+          documents: {
+            libreofficeHeadless: capabilities.documents.libreofficeHeadless ?? true
+          }
+        } : {},
+        ...capabilities.storage?.artifactPrefix ? {
+          storage: {
+            artifactPrefix: capabilities.storage.artifactPrefix
+          }
+        } : {}
+      };
     }
-    throw lastError ?? new Error("Request failed");
-  }
-  async create(config = {}) {
-    const { timeout, waitTimeoutMs, ...rest } = config;
-    const requestBody = { ...rest };
     if (waitTimeoutMs !== undefined) {
       requestBody.waitTimeoutMs = waitTimeoutMs;
     }
@@ -587,7 +427,10 @@ class BanataSandbox {
   }
   fs = {
     read: async (id, path) => {
-      const result = await this.request(`/v1/sandboxes/fs/read?id=${encodeURIComponent(id)}&path=${encodeURIComponent(path)}`);
+      const result = await this.request("/v1/sandboxes/fs/read", {
+        method: "POST",
+        body: JSON.stringify({ id, path })
+      });
       return result.content;
     },
     write: async (id, path, content) => {
@@ -597,7 +440,10 @@ class BanataSandbox {
       });
     },
     list: async (id, path) => {
-      return this.request(`/v1/sandboxes/fs/list?id=${encodeURIComponent(id)}&path=${encodeURIComponent(path ?? "/workspace")}`);
+      return this.request("/v1/sandboxes/fs/list", {
+        method: "POST",
+        body: JSON.stringify({ id, path: path ?? "/workspace" })
+      });
     }
   };
   async terminal(id) {
@@ -637,7 +483,7 @@ class BanataSandbox {
   }
   async getOpencodeConnection(id) {
     const preview = await this.getPreview(id);
-    return deriveOpenCodeConnection(preview.browserPreviewUrl ?? preview.browserPreview?.publicUrl ?? preview.pairedBrowser?.previewUrl ?? null);
+    return deriveOpenCodeConnection(preview.browserPreview?.websocketUrl ?? preview.runtime?.websocketUrl ?? preview.browserPreviewUrl ?? preview.browserPreview?.publicUrl ?? preview.pairedBrowser?.previewUrl ?? null);
   }
   async listOpencodeMessages(id, options = {}) {
     const connection = await this.getOpencodeConnection(id);
@@ -797,26 +643,47 @@ class BanataSandbox {
       body: JSON.stringify({ id })
     });
   }
+  async listCheckpoints(id) {
+    const response = await this.request(`/v1/sandboxes/checkpoints?id=${encodeURIComponent(id)}`);
+    return response.checkpoints;
+  }
+  async restoreCheckpoint(id, checkpointId) {
+    return this.request("/v1/sandboxes/checkpoints/restore", {
+      method: "POST",
+      body: JSON.stringify({ id, checkpointId })
+    });
+  }
   async getArtifacts(id) {
     return this.request(`/v1/sandboxes/artifacts?id=${encodeURIComponent(id)}`);
   }
   async getArtifactDownloadUrl(id, key, expiresInSeconds = 3600) {
     return this.request(`/v1/sandboxes/artifacts/download?id=${encodeURIComponent(id)}&key=${encodeURIComponent(key)}&expiresIn=${encodeURIComponent(String(expiresInSeconds))}`);
   }
+  async convertDocument(id, inputPath, options = {}) {
+    return this.request("/v1/sandboxes/documents/convert", {
+      method: "POST",
+      body: JSON.stringify({
+        id,
+        inputPath,
+        format: options.format,
+        outputDir: options.outputDir
+      })
+    });
+  }
   async getPreview(id) {
     const preview = await this.request(`/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) {
     const preview = await this.getPreview(id);
-    return derivePreviewConnection(preview.browserPreviewUrl);
+    return derivePreviewConnection(preview.browserPreview?.websocketUrl ?? preview.runtime?.websocketUrl ?? preview.browserPreviewUrl);
   }
   async getPreviewViewerUrl(id) {
     const preview = await this.getPreview(id);
-    return preview.browserPreviewViewerUrl ?? buildPreviewViewerUrl(preview.browserPreviewUrl, this.appUrl);
+    return preview.browserPreviewViewerUrl ?? preview.browserPreview?.publicUrl ?? buildPreviewViewerUrl(preview.browserPreview?.websocketUrl ?? preview.runtime?.websocketUrl ?? preview.browserPreviewUrl, this.appUrl);
   }
   async startPreview(id) {
     const connection = await this.getPreviewConnection(id);
@@ -930,6 +797,11 @@ class BanataSandbox {
       listOpencodeMessages: (options) => this.listOpencodeMessages(sessionId, options),
       streamOpencodeEvents: (options) => this.streamOpencodeEvents(sessionId, options),
       checkpoint: () => this.checkpoint(sessionId),
+      listCheckpoints: () => this.listCheckpoints(sessionId),
+      restoreCheckpoint: (checkpointId) => this.restoreCheckpoint(sessionId, checkpointId),
+      getArtifacts: () => this.getArtifacts(sessionId),
+      getArtifactDownloadUrl: (key, expiresInSeconds) => this.getArtifactDownloadUrl(sessionId, key, expiresInSeconds),
+      convertDocument: (inputPath, options) => this.convertDocument(sessionId, inputPath, options),
       getRuntime: () => this.getRuntime(sessionId),
       getPreview: () => this.getPreview(sessionId),
       getPreviewConnection: () => this.getPreviewConnection(sessionId),
@@ -953,12 +825,11 @@ class BanataSandbox {
     };
   }
 }
-var src_default = BrowserCloud;
+var src_default = BanataSandbox;
 export {
   src_default as default,
   buildPreviewViewerUrl,
   BrowserServiceError,
-  BrowserCloud,
   BanataSandbox,
   BanataError
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@banata-boxes/sdk",
-  "version": "0.2.1",
-  "description": "TypeScript SDK for Banata browser sessions and code sandboxes",
+  "version": "0.2.3",
+  "description": "TypeScript SDK for Banata sandboxes, paired browser workflows, and OpenCode automation",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -34,12 +34,11 @@
   ],
   "keywords": [
     "banata",
-    "browser",
     "sandbox",
     "automation",
-    "puppeteer",
-    "cdp",
-    "headless"
+    "opencode",
+    "agent-browser",
+    "handoff"
   ],
   "license": "MIT",
   "repository": {