@banata-boxes/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,476 @@
+// src/index.ts
+class BanataError extends Error {
+  status;
+  code;
+  requiredPlan;
+  currentPlan;
+  constructor(message, status, details) {
+    super(message);
+    this.name = "BanataError";
+    this.status = status;
+    this.code = details?.code;
+    this.requiredPlan = details?.requiredPlan;
+    this.currentPlan = details?.currentPlan;
+  }
+}
+var BrowserServiceError = BanataError;
+function isRetryableStatus(status) {
+  return status >= 500 || status === 429;
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+class BrowserCloud {
+  apiKey;
+  baseUrl;
+  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.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;
+          }
+          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;
+          }
+          throw error;
+        }
+        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);
+      }
+    }
+    throw lastError ?? new Error("Request failed");
+  }
+  async createBrowser(config = {}) {
+    const { timeout, waitTimeoutMs, ...rest } = config;
+    return this.request("/v1/browsers", {
+      method: "POST",
+      body: JSON.stringify({
+        ...rest,
+        waitTimeoutMs: waitTimeoutMs ?? timeout
+      })
+    });
+  }
+  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 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) {
+        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;
+    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,
+      close: () => this.closeBrowser(session.id)
+    };
+  }
+  async getUsage() {
+    return this.request("/v1/usage");
+  }
+  async getBilling() {
+    return this.request("/v1/billing");
+  }
+  async createCheckout(params) {
+    return this.request("/v1/billing/checkout", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async listWebhooks() {
+    const response = await this.request("/v1/webhooks");
+    return response.data;
+  }
+  async createWebhook(params) {
+    return this.request("/v1/webhooks", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async deleteWebhook(id) {
+    await this.request(`/v1/webhooks?id=${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
+  }
+  async listWebhookDeliveries(limit = 50) {
+    const response = await this.request(`/v1/webhooks/deliveries?limit=${encodeURIComponent(String(limit))}`);
+    return response.data;
+  }
+  async testWebhook(id) {
+    return this.request("/v1/webhooks/test", {
+      method: "POST",
+      body: JSON.stringify({ id })
+    });
+  }
+}
+
+class BanataSandbox {
+  apiKey;
+  baseUrl;
+  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.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;
+          }
+          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;
+          }
+          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);
+      }
+    }
+    throw lastError ?? new Error("Request failed");
+  }
+  async create(config = {}) {
+    const { timeout, waitTimeoutMs, ...rest } = config;
+    return this.request("/v1/sandboxes", {
+      method: "POST",
+      body: JSON.stringify({
+        ...rest,
+        waitTimeoutMs: waitTimeoutMs ?? timeout
+      })
+    });
+  }
+  async get(id) {
+    return this.request(`/v1/sandboxes?id=${encodeURIComponent(id)}`);
+  }
+  async list() {
+    const response = await this.request("/v1/sandboxes");
+    return response.items;
+  }
+  async kill(id) {
+    await this.request(`/v1/sandboxes?id=${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
+  }
+  async waitForReady(id, timeoutMs = 30000) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      const session = await this.get(id);
+      if (session.status === "ready" || session.status === "active") {
+        return session;
+      }
+      if (session.status === "failed") {
+        throw new BanataError("Sandbox failed to start", 500);
+      }
+      if (session.status === "ended" || session.status === "ending") {
+        throw new BanataError("Sandbox ended before becoming ready", 410);
+      }
+      await sleep(500);
+    }
+    throw new BanataError(`Sandbox ${id} not ready within ${timeoutMs}ms`, 408);
+  }
+  async exec(id, command, args) {
+    return this.request("/v1/sandboxes/exec", {
+      method: "POST",
+      body: JSON.stringify({ id, command, args })
+    });
+  }
+  async runCode(id, code) {
+    return this.request("/v1/sandboxes/code", {
+      method: "POST",
+      body: JSON.stringify({ id, code })
+    });
+  }
+  async pause(id) {
+    await this.request("/v1/sandboxes/pause", {
+      method: "POST",
+      body: JSON.stringify({ id })
+    });
+  }
+  async resume(id) {
+    await this.request("/v1/sandboxes/resume", {
+      method: "POST",
+      body: JSON.stringify({ id })
+    });
+  }
+  fs = {
+    read: async (id, path) => {
+      const result = await this.request(`/v1/sandboxes/fs/read?id=${encodeURIComponent(id)}&path=${encodeURIComponent(path)}`);
+      return result.content;
+    },
+    write: async (id, path, content) => {
+      await this.request("/v1/sandboxes/fs/write", {
+        method: "POST",
+        body: JSON.stringify({ id, path, content })
+      });
+    },
+    list: async (id, path) => {
+      return this.request(`/v1/sandboxes/fs/list?id=${encodeURIComponent(id)}&path=${encodeURIComponent(path ?? "/workspace")}`);
+    }
+  };
+  async terminal(id) {
+    return this.request(`/v1/sandboxes/terminal?id=${encodeURIComponent(id)}`);
+  }
+  async getRuntime(id) {
+    return this.request(`/v1/sandboxes/runtime?id=${encodeURIComponent(id)}`);
+  }
+  async prompt(id, prompt, options = {}) {
+    return this.request("/v1/sandboxes/opencode/prompt", {
+      method: "POST",
+      body: JSON.stringify({
+        id,
+        prompt,
+        agent: options.agent,
+        sessionId: options.sessionId,
+        noReply: options.noReply
+      })
+    });
+  }
+  async checkpoint(id) {
+    return this.request("/v1/sandboxes/checkpoint", {
+      method: "POST",
+      body: JSON.stringify({ id })
+    });
+  }
+  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 getPreview(id) {
+    return this.request(`/v1/sandboxes/browser-preview?id=${encodeURIComponent(id)}`);
+  }
+  async getHandoff(id) {
+    return this.request(`/v1/sandboxes/handoff?id=${encodeURIComponent(id)}`);
+  }
+  async requestHumanHandoff(id, options) {
+    return this.request("/v1/sandboxes/handoff/request", {
+      method: "POST",
+      body: JSON.stringify({
+        id,
+        reason: options.reason,
+        message: options.message,
+        resumePrompt: options.resumePrompt,
+        expiresInMs: options.expiresInMs
+      })
+    });
+  }
+  async acceptHumanHandoff(id, options) {
+    return this.request("/v1/sandboxes/handoff/accept", {
+      method: "POST",
+      body: JSON.stringify({
+        id,
+        controller: options.controller,
+        leaseMs: options.leaseMs
+      })
+    });
+  }
+  async completeHumanHandoff(id, options = {}) {
+    return this.request("/v1/sandboxes/handoff/complete", {
+      method: "POST",
+      body: JSON.stringify({
+        id,
+        controller: options.controller,
+        note: options.note,
+        returnControlTo: options.returnControlTo,
+        runResumePrompt: options.runResumePrompt
+      })
+    });
+  }
+  async setControl(id, mode, options = {}) {
+    return this.request("/v1/sandboxes/browser-preview/control", {
+      method: "POST",
+      body: JSON.stringify({
+        id,
+        mode,
+        controller: options.controller,
+        leaseMs: options.leaseMs
+      })
+    });
+  }
+  async launch(config = {}) {
+    const created = await this.create(config);
+    let session;
+    try {
+      session = await this.waitForReady(created.id, config.timeout ?? 30000);
+    } 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;
+    return {
+      sessionId,
+      terminalUrl,
+      browserPreviewUrl,
+      exec: (command, args) => this.exec(sessionId, command, args),
+      runCode: (code) => this.runCode(sessionId, code),
+      prompt: (prompt, options) => this.prompt(sessionId, prompt, options),
+      checkpoint: () => this.checkpoint(sessionId),
+      getRuntime: () => this.getRuntime(sessionId),
+      getPreview: () => this.getPreview(sessionId),
+      getHandoff: () => this.getHandoff(sessionId),
+      setControl: (mode, options) => this.setControl(sessionId, mode, options),
+      takeControl: (options) => this.setControl(sessionId, "human", options),
+      returnControl: (options) => this.setControl(sessionId, "ai", options),
+      requestHumanHandoff: (options) => this.requestHumanHandoff(sessionId, options),
+      acceptHumanHandoff: (options) => this.acceptHumanHandoff(sessionId, options),
+      completeHumanHandoff: (options) => this.completeHumanHandoff(sessionId, options),
+      fs: {
+        read: (path) => this.fs.read(sessionId, path),
+        write: (path, content) => this.fs.write(sessionId, path, content),
+        list: (path) => this.fs.list(sessionId, path)
+      },
+      kill: () => this.kill(sessionId)
+    };
+  }
+}
+var src_default = BrowserCloud;
+export {
+  src_default as default,
+  BrowserServiceError,
+  BrowserCloud,
+  BanataSandbox,
+  BanataError
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@banata-boxes/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Banata browser sessions and code sandboxes",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./sdk": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target node && bun x tsc --emitDeclarationOnly --declaration --outDir dist",
+    "prepublishOnly": "bun run build",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "banata",
+    "browser",
+    "sandbox",
+    "automation",
+    "puppeteer",
+    "cdp",
+    "headless"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Banata-Labs/banata-sandbox.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://docs-boxes.banata.dev"
+}