@banata-boxes/sdk 0.1.0 → 0.1.1

package/dist/index.js

@@ -1,4 +1,30 @@
 // src/index.ts
+function buildPreviewViewerUrl(connectionUrl, appUrl = "https://boxes.banata.dev") {
+  if (!connectionUrl) {
+    return null;
+  }
+  try {
+    const parsed = new URL(connectionUrl);
+    const token = parsed.searchParams.get("token");
+    const session = parsed.searchParams.get("session");
+    const machine = parsed.searchParams.get("machine");
+    if (!token || !session) {
+      return null;
+    }
+    const backendProtocol = parsed.protocol === "wss:" ? "https:" : parsed.protocol === "ws:" ? "http:" : parsed.protocol;
+    const viewerUrl = new URL("/preview", appUrl);
+    viewerUrl.searchParams.set("backend", `${backendProtocol}//${parsed.host}`);
+    viewerUrl.searchParams.set("token", token);
+    viewerUrl.searchParams.set("session", session);
+    if (machine) {
+      viewerUrl.searchParams.set("machine", machine);
+    }
+    return viewerUrl.toString();
+  } catch {
+    return null;
+  }
+}
+
 class BanataError extends Error {
   status;
   code;
@@ -20,16 +46,170 @@ function isRetryableStatus(status) {
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
+function derivePreviewConnection(rawUrl) {
+  if (!rawUrl) {
+    return null;
+  }
+  try {
+    const parsed = new URL(rawUrl);
+    const token = parsed.searchParams.get("token");
+    const sessionId = parsed.searchParams.get("session");
+    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 search = `token=${encodeURIComponent(token)}&session=${encodeURIComponent(sessionId)}`;
+    const isDirectPreviewUrl = parsed.pathname.endsWith("/ws") && parsed.pathname.includes("/preview/");
+    if (isDirectPreviewUrl) {
+      const basePath = parsed.pathname.slice(0, -3);
+      return {
+        rawUrl,
+        token,
+        sessionId,
+        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}`
+      };
+    }
+    return {
+      rawUrl,
+      token,
+      sessionId,
+      startUrl: `${httpProtocol}//${parsed.host}/preview/start?${search}`,
+      navigateUrl: `${httpProtocol}//${parsed.host}/preview/navigate?${search}`,
+      resizeUrl: `${httpProtocol}//${parsed.host}/preview/resize?${search}`,
+      wsUrl: `${wsProtocol}//${parsed.host}/preview/ws?${search}`
+    };
+  } catch {
+    return null;
+  }
+}
+function deriveOpenCodeConnection(rawUrl) {
+  if (!rawUrl) {
+    return null;
+  }
+  try {
+    const parsed = new URL(rawUrl);
+    const token = parsed.searchParams.get("token");
+    const sessionId = parsed.searchParams.get("session");
+    if (!token || !sessionId) {
+      return null;
+    }
+    const httpProtocol = parsed.protocol === "https:" || parsed.protocol === "wss:" ? "https:" : "http:";
+    const search = `token=${encodeURIComponent(token)}&session=${encodeURIComponent(sessionId)}`;
+    return {
+      rawUrl,
+      token,
+      sessionId,
+      stateUrl: `${httpProtocol}//${parsed.host}/opencode/state?${search}`,
+      messagesUrl: `${httpProtocol}//${parsed.host}/opencode/messages?${search}`,
+      promptUrl: `${httpProtocol}//${parsed.host}/opencode/prompt-async?${search}`,
+      eventsUrl: `${httpProtocol}//${parsed.host}/opencode/events?${search}`
+    };
+  } catch {
+    return null;
+  }
+}
+async function parseJsonResponse(response) {
+  const text = await response.text();
+  if (!text) {
+    return null;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+async function requestPreviewEndpoint(url, init) {
+  const response = await fetch(url, init);
+  const payload = await parseJsonResponse(response);
+  if (!response.ok) {
+    const message = payload && typeof payload === "object" && !Array.isArray(payload) && typeof payload.error === "string" ? String(payload.error) : typeof payload === "string" ? payload : `Preview request failed (${response.status})`;
+    throw new BanataError(message, response.status);
+  }
+  return payload;
+}
+function shouldFallbackFromDirectConnection(error) {
+  if (error instanceof BanataError) {
+    return error.status === 0 || error.status >= 500;
+  }
+  if (error instanceof Error) {
+    const maybeCause = error.cause;
+    const code = maybeCause?.code;
+    return code === "ECONNRESET" || code === "ECONNREFUSED" || code === "ENOTFOUND" || code === "ETIMEDOUT" || code === "UND_ERR_CONNECT_TIMEOUT" || error.name === "TypeError";
+  }
+  return false;
+}
+function parseSseBlock(block) {
+  const trimmed = block.trim();
+  if (!trimmed) {
+    return null;
+  }
+  let eventType = "message";
+  const dataLines = [];
+  for (const line of trimmed.split(/\r?\n/)) {
+    if (line.startsWith("event:")) {
+      eventType = line.slice("event:".length).trim() || "message";
+      continue;
+    }
+    if (line.startsWith("data:")) {
+      dataLines.push(line.slice("data:".length).trimStart());
+    }
+  }
+  const rawData = dataLines.join(`
+`);
+  if (!rawData) {
+    return { type: eventType, data: null, raw: trimmed };
+  }
+  try {
+    return {
+      type: eventType,
+      data: JSON.parse(rawData),
+      raw: trimmed
+    };
+  } catch {
+    return {
+      type: eventType,
+      data: rawData,
+      raw: trimmed
+    };
+  }
+}
+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.pairedBrowser?.cdpUrl) {
+      return false;
+    }
+  }
+  if (session.capabilities?.opencode?.enabled) {
+    if (!session.opencode || session.opencode.status === "failed" || session.opencode.status === "disabled") {
+      return false;
+    }
+  }
+  return true;
+}
 
 class BrowserCloud {
   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.banata.dev";
+    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,
@@ -99,12 +279,13 @@ class BrowserCloud {
   }
   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({
-        ...rest,
-        waitTimeoutMs: waitTimeoutMs ?? timeout
-      })
+      body: JSON.stringify(requestBody)
     });
   }
   async getBrowser(sessionId) {
@@ -115,11 +296,50 @@ class BrowserCloud {
       method: "DELETE"
     });
   }
+  async getPreviewConnection(sessionId) {
+    const session = await this.getBrowser(sessionId);
+    return derivePreviewConnection(session.cdpUrl);
+  }
+  async getPreviewViewerUrl(sessionId) {
+    const session = await this.getBrowser(sessionId);
+    return buildPreviewViewerUrl(session.cdpUrl, 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 ((session.status === "ready" || session.status === "active") && session.cdpUrl) {
+      if (isBrowserSessionOperationallyReady(session)) {
         return session.cdpUrl;
       }
       if (session.status === "failed") {
@@ -135,18 +355,28 @@ class BrowserCloud {
   async launch(config = {}) {
     const session = await this.createBrowser(config);
     let cdpUrl;
-    try {
-      cdpUrl = await this.waitForReady(session.id, config.timeout ?? 30000);
-    } catch (err) {
+    if (isBrowserSessionOperationallyReady(session)) {
+      cdpUrl = session.cdpUrl;
+    } else {
       try {
-        await this.closeBrowser(session.id);
-      } catch {}
-      throw err;
+        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,
-      close: () => this.closeBrowser(session.id)
+      previewViewerUrl: buildPreviewViewerUrl(cdpUrl, 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() {
@@ -191,12 +421,14 @@ class BrowserCloud {
 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.banata.dev";
+    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,
@@ -269,12 +501,13 @@ class BanataSandbox {
   }
   async create(config = {}) {
     const { timeout, waitTimeoutMs, ...rest } = config;
+    const requestBody = { ...rest };
+    if (waitTimeoutMs !== undefined) {
+      requestBody.waitTimeoutMs = waitTimeoutMs;
+    }
     return this.request("/v1/sandboxes", {
       method: "POST",
-      body: JSON.stringify({
-        ...rest,
-        waitTimeoutMs: waitTimeoutMs ?? timeout
-      })
+      body: JSON.stringify(requestBody)
     });
   }
   async get(id) {
@@ -289,11 +522,11 @@ class BanataSandbox {
       method: "DELETE"
     });
   }
-  async waitForReady(id, timeoutMs = 30000) {
+  async waitForReady(id, timeoutMs = 120000) {
     const start = Date.now();
     while (Date.now() - start < timeoutMs) {
       const session = await this.get(id);
-      if (session.status === "ready" || session.status === "active") {
+      if (isSandboxSessionOperationallyReady(session)) {
         return session;
       }
       if (session.status === "failed") {
@@ -351,7 +584,151 @@ class BanataSandbox {
   async getRuntime(id) {
     return this.request(`/v1/sandboxes/runtime?id=${encodeURIComponent(id)}`);
   }
+  async getOpencodeState(id, options = {}) {
+    const connection = await this.getOpencodeConnection(id);
+    if (connection) {
+      try {
+        const url = new URL(connection.stateUrl);
+        if (options.ensureSession !== undefined) {
+          url.searchParams.set("ensureSession", String(options.ensureSession));
+        }
+        if (options.agent) {
+          url.searchParams.set("agent", options.agent);
+        }
+        return await requestPreviewEndpoint(url.toString(), {
+          method: "GET"
+        });
+      } catch (error) {
+        if (!shouldFallbackFromDirectConnection(error)) {
+          throw error;
+        }
+      }
+    }
+    const query = new URLSearchParams({ id });
+    if (options.ensureSession !== undefined) {
+      query.set("ensureSession", String(options.ensureSession));
+    }
+    if (options.agent) {
+      query.set("agent", options.agent);
+    }
+    return this.request(`/v1/sandboxes/opencode/state?${query.toString()}`);
+  }
+  async getOpencodeConnection(id) {
+    const preview = await this.getPreview(id);
+    return deriveOpenCodeConnection(preview.browserPreviewUrl ?? preview.browserPreview?.publicUrl ?? preview.pairedBrowser?.previewUrl ?? null);
+  }
+  async listOpencodeMessages(id, options = {}) {
+    const connection = await this.getOpencodeConnection(id);
+    if (connection) {
+      try {
+        const url = new URL(connection.messagesUrl);
+        if (options.sessionId) {
+          url.searchParams.set("opencodeSessionId", options.sessionId);
+        }
+        return await requestPreviewEndpoint(url.toString(), {
+          method: "GET"
+        });
+      } catch (error) {
+        if (!shouldFallbackFromDirectConnection(error)) {
+          throw error;
+        }
+      }
+    }
+    const query = new URLSearchParams({ id });
+    if (options.sessionId) {
+      query.set("sessionId", options.sessionId);
+    }
+    return this.request(`/v1/sandboxes/opencode/messages?${query.toString()}`);
+  }
+  async* streamOpencodeEvents(id, options = {}) {
+    const connection = await this.getOpencodeConnection(id);
+    let response;
+    if (connection) {
+      try {
+        const url = new URL(connection.eventsUrl);
+        if (options.sessionId) {
+          url.searchParams.set("opencodeSessionId", options.sessionId);
+        }
+        response = await fetch(url.toString(), {
+          method: "GET"
+        });
+      } catch (error) {
+        if (!shouldFallbackFromDirectConnection(error)) {
+          throw error;
+        }
+        const query = new URLSearchParams({ id });
+        if (options.sessionId) {
+          query.set("sessionId", options.sessionId);
+        }
+        response = await fetch(`${this.baseUrl}/v1/sandboxes/opencode/events?${query.toString()}`, {
+          method: "GET",
+          headers: this.headers
+        });
+      }
+    } else {
+      const query = new URLSearchParams({ id });
+      if (options.sessionId) {
+        query.set("sessionId", options.sessionId);
+      }
+      response = await fetch(`${this.baseUrl}/v1/sandboxes/opencode/events?${query.toString()}`, {
+        method: "GET",
+        headers: this.headers
+      });
+    }
+    if (!response.ok) {
+      const payload = await parseJsonResponse(response);
+      const message = payload && typeof payload === "object" && !Array.isArray(payload) && typeof payload.error === "string" ? String(payload.error) : typeof payload === "string" ? payload : `Failed to open OpenCode event stream (${response.status})`;
+      throw new BanataError(message, response.status);
+    }
+    if (!response.body) {
+      throw new BanataError("OpenCode event stream did not provide a response body", 502);
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder;
+    let buffered = "";
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done)
+          break;
+        buffered += decoder.decode(value, { stream: true });
+        const blocks = buffered.split(/\r?\n\r?\n/);
+        buffered = blocks.pop() ?? "";
+        for (const block of blocks) {
+          const parsed = parseSseBlock(block);
+          if (parsed) {
+            yield parsed;
+          }
+        }
+      }
+      buffered += decoder.decode();
+      const trailing = parseSseBlock(buffered);
+      if (trailing) {
+        yield trailing;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
   async prompt(id, prompt, options = {}) {
+    const connection = await this.getOpencodeConnection(id);
+    if (connection) {
+      try {
+        return await requestPreviewEndpoint(connection.promptUrl, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            prompt,
+            agent: options.agent,
+            sessionId: options.sessionId
+          })
+        });
+      } catch (error) {
+        if (!shouldFallbackFromDirectConnection(error)) {
+          throw error;
+        }
+      }
+    }
     return this.request("/v1/sandboxes/opencode/prompt", {
       method: "POST",
       body: JSON.stringify({
@@ -363,6 +740,35 @@ class BanataSandbox {
       })
     });
   }
+  async promptAsync(id, prompt, options = {}) {
+    const connection = await this.getOpencodeConnection(id);
+    if (connection) {
+      try {
+        return await requestPreviewEndpoint(connection.promptUrl, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            prompt,
+            agent: options.agent,
+            sessionId: options.sessionId
+          })
+        });
+      } catch (error) {
+        if (!shouldFallbackFromDirectConnection(error)) {
+          throw error;
+        }
+      }
+    }
+    return this.request("/v1/sandboxes/opencode/prompt-async", {
+      method: "POST",
+      body: JSON.stringify({
+        id,
+        prompt,
+        agent: options.agent,
+        sessionId: options.sessionId
+      })
+    });
+  }
   async checkpoint(id) {
     return this.request("/v1/sandboxes/checkpoint", {
       method: "POST",
@@ -376,7 +782,50 @@ class BanataSandbox {
     return this.request(`/v1/sandboxes/artifacts/download?id=${encodeURIComponent(id)}&key=${encodeURIComponent(key)}&expiresIn=${encodeURIComponent(String(expiresInSeconds))}`);
   }
   async getPreview(id) {
-    return this.request(`/v1/sandboxes/browser-preview?id=${encodeURIComponent(id)}`);
+    const preview = await this.request(`/v1/sandboxes/browser-preview?id=${encodeURIComponent(id)}`);
+    return {
+      ...preview,
+      browserPreviewViewerUrl: buildPreviewViewerUrl(preview.browserPreviewUrl, this.appUrl)
+    };
+  }
+  async getPreviewConnection(id) {
+    const preview = await this.getPreview(id);
+    return derivePreviewConnection(preview.browserPreviewUrl);
+  }
+  async getPreviewViewerUrl(id) {
+    const preview = await this.getPreview(id);
+    return preview.browserPreviewViewerUrl ?? buildPreviewViewerUrl(preview.browserPreviewUrl, this.appUrl);
+  }
+  async startPreview(id) {
+    const connection = await this.getPreviewConnection(id);
+    if (!connection) {
+      throw new BanataError("Sandbox browser preview is not available", 409);
+    }
+    return requestPreviewEndpoint(connection.startUrl, {
+      method: "POST"
+    });
+  }
+  async navigatePreview(id, url) {
+    const connection = await this.getPreviewConnection(id);
+    if (!connection) {
+      throw new BanataError("Sandbox browser preview is not available", 409);
+    }
+    return requestPreviewEndpoint(connection.navigateUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ url })
+    });
+  }
+  async resizePreview(id, size) {
+    const connection = await this.getPreviewConnection(id);
+    if (!connection) {
+      throw new BanataError("Sandbox browser preview is not available", 409);
+    }
+    return requestPreviewEndpoint(connection.resizeUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(size)
+    });
   }
   async getHandoff(id) {
     return this.request(`/v1/sandboxes/handoff?id=${encodeURIComponent(id)}`);
@@ -429,27 +878,43 @@ class BanataSandbox {
   async launch(config = {}) {
     const created = await this.create(config);
     let session;
-    try {
-      session = await this.waitForReady(created.id, config.timeout ?? 30000);
-    } catch (err) {
+    if (isSandboxSessionOperationallyReady(created)) {
+      session = created;
+    } else {
       try {
-        await this.kill(created.id);
-      } catch {}
-      throw err;
+        session = await this.waitForReady(created.id, config.timeout ?? 120000);
+      } catch (err) {
+        try {
+          await this.kill(created.id);
+        } catch {}
+        throw err;
+      }
     }
     const sessionId = session.id;
     const terminalUrl = session.terminalUrl ?? "";
     const browserPreviewUrl = session.browserPreview?.publicUrl ?? session.pairedBrowser?.previewUrl ?? null;
+    const browserPreviewViewerUrl = buildPreviewViewerUrl(browserPreviewUrl, this.appUrl);
     return {
       sessionId,
       terminalUrl,
       browserPreviewUrl,
+      browserPreviewViewerUrl,
       exec: (command, args) => this.exec(sessionId, command, args),
       runCode: (code) => this.runCode(sessionId, code),
       prompt: (prompt, options) => this.prompt(sessionId, prompt, options),
+      promptAsync: (prompt, options) => this.promptAsync(sessionId, prompt, options),
+      getOpencodeState: (options) => this.getOpencodeState(sessionId, options),
+      getOpencodeConnection: () => this.getOpencodeConnection(sessionId),
+      listOpencodeMessages: (options) => this.listOpencodeMessages(sessionId, options),
+      streamOpencodeEvents: (options) => this.streamOpencodeEvents(sessionId, options),
       checkpoint: () => this.checkpoint(sessionId),
       getRuntime: () => this.getRuntime(sessionId),
       getPreview: () => this.getPreview(sessionId),
+      getPreviewConnection: () => this.getPreviewConnection(sessionId),
+      getPreviewViewerUrl: () => this.getPreviewViewerUrl(sessionId),
+      startPreview: () => this.startPreview(sessionId),
+      navigatePreview: (url) => this.navigatePreview(sessionId, url),
+      resizePreview: (size) => this.resizePreview(sessionId, size),
       getHandoff: () => this.getHandoff(sessionId),
       setControl: (mode, options) => this.setControl(sessionId, mode, options),
       takeControl: (options) => this.setControl(sessionId, "human", options),
@@ -469,6 +934,7 @@ class BanataSandbox {
 var src_default = BrowserCloud;
 export {
   src_default as default,
+  buildPreviewViewerUrl,
   BrowserServiceError,
   BrowserCloud,
   BanataSandbox,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banata-boxes/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "TypeScript SDK for Banata browser sessions and code sandboxes",
   "type": "module",
   "main": "dist/index.js",