@banata-boxes/sdk 0.1.0

package/src/index.ts

@@ -0,0 +1,1219 @@
+// sdk/src/index.ts
+// Customer-facing TypeScript SDK for Browser-as-a-Service
+//
+// M7 FIX: Added retry with exponential backoff on transient errors (5xx, network).
+
+export interface BrowserConfig {
+  /** Session weight: light (512MB, default), medium (1GB), heavy (2GB — Pro+) */
+  weight?: 'light' | 'medium' | 'heavy';
+  /** Isolation mode: shared (default) or dedicated (Pro+) */
+  isolation?: 'shared' | 'dedicated';
+  /** Outbound egress profile for the session */
+  egressProfile?:
+    | 'shared-dc'
+    | 'dedicated-dc'
+    | 'rotating-residential'
+    | 'static-residential'
+    | 'byo-proxy';
+  /** Enable anti-detection stealth (Builder+, default: false) */
+  stealth?: boolean;
+  /** Customer-provided proxy (BYOP) */
+  proxy?: {
+    protocol: 'http' | 'https' | 'socks5';
+    host: string;
+    port: number;
+    username?: string;
+    password?: string;
+  };
+  /** Enable MP4 session recording (Pro+, default: false) */
+  recording?: boolean;
+  /** Enable auto CAPTCHA solving (reCAPTCHA, hCaptcha, Turnstile) */
+  captcha?: boolean;
+  /** Max session duration in ms (capped by your plan limit) */
+  maxDurationMs?: number;
+  /** R2 key for a saved browser profile (cookies, localStorage) */
+  profileKey?: string;
+  /** Preferred Fly.io region code (e.g. 'iad', 'lhr') */
+  region?: string;
+  /** Ask the API to wait briefly for the session to become ready before returning */
+  waitUntilReady?: boolean;
+  /** Max time in ms for the API to wait before falling back to a queued response */
+  waitTimeoutMs?: number;
+  /** Timeout in ms to wait for session to become ready (default: 30000) */
+  timeout?: number;
+}
+
+export interface BrowserSession {
+  id: string;
+  status: 'queued' | 'assigning' | 'ready' | 'active' | 'ending' | 'ended' | 'failed';
+  waitTimedOut?: boolean;
+  cdpUrl: string | null;
+  weight: string;
+  isolation: string;
+  egressProfile: string;
+  artifacts: {
+    screenshots?: string[];
+    har?: string;
+    recording?: string;
+  } | null;
+  duration: number | null;
+}
+
+export interface UsageInfo {
+  totalSessions: number;
+  totalBrowserHours: number;
+  weightBreakdown: {
+    light: number;
+    medium: number;
+    heavy: number;
+  };
+  periodStart: number | null;
+}
+
+export interface BillingInfo {
+  plan: string;
+  polarCustomerId: string | null;
+  currentPeriod: {
+    totalSessions: number;
+    totalBrowserHours: number;
+    weightBreakdown: {
+      light: number;
+      medium: number;
+      heavy: number;
+    };
+  };
+}
+
+export type WebhookEventType =
+  | "session.created"
+  | "session.assigned"
+  | "session.ready"
+  | "session.ending"
+  | "session.ended"
+  | "session.failed"
+  | "sandbox.created"
+  | "sandbox.assigned"
+  | "sandbox.ready"
+  | "sandbox.ending"
+  | "sandbox.ended"
+  | "sandbox.failed"
+  | "sandbox.paused"
+  | "sandbox.resumed"
+  | "sandbox.opencode.updated"
+  | "sandbox.browser_preview.updated"
+  | "sandbox.handoff.requested"
+  | "sandbox.handoff.accepted"
+  | "sandbox.handoff.completed"
+  | "sandbox.artifacts.updated"
+  | "machine.created"
+  | "machine.woken"
+  | "machine.registered"
+  | "machine.suspended";
+
+export interface WebhookEndpoint {
+  id: string;
+  url: string;
+  description?: string;
+  eventTypes: WebhookEventType[];
+  enabled: boolean;
+  createdAt: number;
+  updatedAt?: number;
+  lastDeliveredAt?: number;
+  lastFailureAt?: number;
+  lastFailureMessage?: string;
+}
+
+export interface WebhookDelivery {
+  id: string;
+  webhookId: string;
+  eventId: string;
+  eventType: WebhookEventType;
+  resourceType?: string;
+  resourceId?: string;
+  targetUrl: string;
+  status: "pending" | "delivered" | "failed";
+  attemptCount: number;
+  responseStatus?: number;
+  responseBody?: string;
+  errorMessage?: string;
+  nextAttemptAt?: number;
+  lastAttemptAt: number;
+  deliveredAt?: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface RetryConfig {
+  /** Max number of retries (default: 3) */
+  maxRetries?: number;
+  /** Base delay in ms for exponential backoff (default: 500) */
+  baseDelayMs?: number;
+  /** Max delay in ms (default: 10000) */
+  maxDelayMs?: number;
+}
+
+export class BanataError extends Error {
+  /** HTTP status code (0 for network errors) */
+  status: number;
+  /** Machine-readable error code (e.g. PLAN_FEATURE_UNAVAILABLE, PLAN_LIMIT_EXCEEDED) */
+  code: string | undefined;
+  /** The plan required to use this feature, if applicable */
+  requiredPlan: string | undefined;
+  /** Your current plan, if returned by the API */
+  currentPlan: string | undefined;
+
+  constructor(
+    message: string,
+    status: number,
+    details?: { code?: string; requiredPlan?: string; currentPlan?: string },
+  ) {
+    super(message);
+    this.name = 'BanataError';
+    this.status = status;
+    this.code = details?.code;
+    this.requiredPlan = details?.requiredPlan;
+    this.currentPlan = details?.currentPlan;
+  }
+}
+
+/** @deprecated Use BanataError instead */
+export const BrowserServiceError = BanataError;
+
+/** Check if an HTTP status is retryable (5xx or 429) */
+function isRetryableStatus(status: number): boolean {
+  return status >= 500 || status === 429;
+}
+
+/** Sleep for a given number of ms */
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+export class BrowserCloud {
+  private apiKey: string;
+  private baseUrl: string;
+  private retryConfig: Required<RetryConfig>;
+
+  constructor(config: { apiKey: string; baseUrl?: string; retry?: RetryConfig }) {
+    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 ?? 10_000,
+    };
+  }
+
+  private get headers(): Record<string, string> {
+    return {
+      Authorization: `Bearer ${this.apiKey}`,
+      'Content-Type': 'application/json',
+    };
+  }
+
+  // M7: Request with exponential backoff retry on transient errors
+  private async request<T>(
+    path: string,
+    options: RequestInit = {}
+  ): Promise<T> {
+    const { maxRetries, baseDelayMs, maxDelayMs } = this.retryConfig;
+    let lastError: BanataError | Error | undefined;
+
+    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: string;
+          let parsed: Record<string, unknown> = {};
+          try {
+            parsed = JSON.parse(body);
+            message = (parsed.error as string) ?? body;
+          } catch {
+            message = body;
+          }
+
+          const error = new BanataError(message, res.status, {
+            code: parsed.code as string | undefined,
+            requiredPlan: parsed.requiredPlan as string | undefined,
+            currentPlan: parsed.currentPlan as string | undefined,
+          });
+
+          // Only retry on transient errors (5xx, 429)
+          if (isRetryableStatus(res.status) && attempt < maxRetries) {
+            lastError = error;
+            // Use Retry-After header if present (from rate limiter)
+            const retryAfterHeader = res.headers.get('Retry-After');
+            let delay: number;
+            if (retryAfterHeader) {
+              delay = Math.min(parseInt(retryAfterHeader, 10) * 1000, maxDelayMs);
+            } else {
+              delay = Math.min(baseDelayMs * Math.pow(2, attempt), maxDelayMs);
+            }
+            // Add jitter (0-25% of delay)
+            delay += Math.random() * delay * 0.25;
+            await sleep(delay);
+            continue;
+          }
+
+          throw error;
+        }
+
+        return res.json() as Promise<T>;
+      } catch (err) {
+        if (err instanceof BanataError) {
+          throw err;
+        }
+
+        // Network error — retry if attempts remain
+        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,
+        );
+      }
+    }
+
+    // Should not reach here, but TypeScript needs it
+    throw lastError ?? new Error('Request failed');
+  }
+
+  // ── Sessions ──
+
+  /** Create a new browser session */
+  async createBrowser(config: BrowserConfig = {}): Promise<BrowserSession> {
+    const { timeout, waitTimeoutMs, ...rest } = config;
+    return this.request<BrowserSession>('/v1/browsers', {
+      method: 'POST',
+      body: JSON.stringify({
+        ...rest,
+        waitTimeoutMs: waitTimeoutMs ?? timeout,
+      }),
+    });
+  }
+
+  /** Get session status */
+  async getBrowser(sessionId: string): Promise<BrowserSession> {
+    return this.request<BrowserSession>(
+      `/v1/browsers?id=${encodeURIComponent(sessionId)}`
+    );
+  }
+
+  /** End a session */
+  async closeBrowser(sessionId: string): Promise<void> {
+    await this.request(`/v1/browsers?id=${encodeURIComponent(sessionId)}`, {
+      method: 'DELETE',
+    });
+  }
+
+  /** Wait until session is ready and return CDP URL */
+  async waitForReady(
+    sessionId: string,
+    timeoutMs: number = 30_000
+  ): Promise<string> {
+    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
+    );
+  }
+
+  /**
+   * Convenience: Create a session, wait for it to be ready, and return
+   * the CDP URL + a close function.
+   *
+   * Usage with Puppeteer:
+   * ```ts
+   * const { cdpUrl, close } = await cloud.launch({ weight: 'heavy' });
+   * const browser = await puppeteer.connect({ browserWSEndpoint: cdpUrl });
+   * // ... use browser ...
+   * await browser.disconnect();
+   * await close();
+   * ```
+   */
+  async launch(
+    config: BrowserConfig = {}
+  ): Promise<{
+    cdpUrl: string;
+    sessionId: string;
+    close: () => Promise<void>;
+  }> {
+    const session = await this.createBrowser(config);
+    let cdpUrl: string;
+    try {
+      cdpUrl = await this.waitForReady(
+        session.id,
+        config.timeout ?? 30_000
+      );
+    } catch (err) {
+      // Clean up the orphaned session on timeout/failure
+      try {
+        await this.closeBrowser(session.id);
+      } catch {
+        // Best-effort cleanup — session will be cleaned by stale cron
+      }
+      throw err;
+    }
+
+    return {
+      cdpUrl,
+      sessionId: session.id,
+      close: () => this.closeBrowser(session.id),
+    };
+  }
+
+  // ── Usage & Billing ──
+
+  /** Get current period usage */
+  async getUsage(): Promise<UsageInfo> {
+    return this.request<UsageInfo>('/v1/usage');
+  }
+
+  /** Get billing info (plan, usage) */
+  async getBilling(): Promise<BillingInfo> {
+    return this.request<BillingInfo>('/v1/billing');
+  }
+
+  /** Create a checkout session for plan upgrade (returns Polar checkout URL) */
+  async createCheckout(params: {
+    plan: 'builder' | 'pro' | 'scale';
+    successUrl?: string;
+  }): Promise<{ checkoutUrl: string; checkoutId: string }> {
+    return this.request('/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('/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('/v1/webhooks/test', {
+      method: 'POST',
+      body: JSON.stringify({ id }),
+    });
+  }
+}
+
+// ── Sandbox types ──
+
+export interface SandboxConfig {
+  /** Sandbox runtime: bun, python, or base shell */
+  runtime?: 'bun' | 'python' | 'base';
+  /** Sandbox size: small (512MB), medium (1GB), large (2GB) */
+  size?: 'small' | 'medium' | 'large';
+  /** 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 */
+  capabilities?: SandboxCapabilities;
+  /** Ask the API to wait briefly for the sandbox to become ready before returning */
+  waitUntilReady?: boolean;
+  /** Max time in ms for the API to wait before falling back to a queued response */
+  waitTimeoutMs?: number;
+  /** Timeout in ms to wait for sandbox to become ready (default: 30000) */
+  timeout?: number;
+}
+
+export interface SandboxCapabilities {
+  opencode?: {
+    enabled: boolean;
+    defaultAgent?: "build" | "plan";
+    allowPromptApi?: boolean;
+  };
+  browser?: {
+    mode?: "none" | "paired-banata-browser" | "local-chromium";
+    recording?: boolean;
+    persistentProfile?: boolean;
+    streamPreview?: boolean;
+    humanInLoop?: boolean;
+  };
+  documents?: {
+    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;
+  kind: string;
+  createdAt: number;
+  contentType?: string;
+  sizeBytes?: number;
+}
+
+export interface SandboxArtifacts {
+  workspaceKey?: string;
+  checkpointKey?: string;
+  manifestKey?: string;
+  outputLogKey?: string;
+  items?: SandboxArtifactItem[];
+  updatedAt?: number;
+}
+
+export interface SandboxPairedBrowser {
+  sessionId?: string;
+  cdpUrl?: string;
+  previewUrl?: string;
+  recording?: boolean;
+  persistentProfile?: boolean;
+  controlMode?: "ai" | "human" | "shared";
+  controller?: string;
+  handoffRequestedAt?: number;
+  updatedAt?: number;
+}
+
+export interface SandboxOpencodeState {
+  status: "disabled" | "booting" | "ready" | "failed";
+  serverBaseUrl?: string;
+  sessionId?: string;
+  defaultAgent?: "build" | "plan";
+  lastPromptAt?: number;
+  lastError?: string;
+}
+
+export interface SandboxBrowserPreviewState {
+  status:
+    | "disabled"
+    | "provisioning"
+    | "ready"
+    | "active"
+    | "handoff_requested"
+    | "released"
+    | "failed";
+  publicUrl?: string;
+  websocketUrl?: string;
+  controlMode?: "ai" | "human" | "shared";
+  controller?: string;
+  leaseExpiresAt?: number;
+  updatedAt?: number;
+}
+
+export type SandboxHumanHandoffReason =
+  | "mfa"
+  | "captcha"
+  | "approval"
+  | "login_failed"
+  | "ambiguous_ui"
+  | "file_download"
+  | "custom";
+
+export type SandboxHumanHandoffStatus =
+  | "pending"
+  | "accepted"
+  | "completed"
+  | "cancelled"
+  | "expired";
+
+export interface SandboxHumanHandoffState {
+  requestId: string;
+  status: SandboxHumanHandoffStatus;
+  reason: SandboxHumanHandoffReason;
+  message: string;
+  requestedBy: "opencode" | "worker" | "sdk" | "dashboard";
+  controller?: string;
+  resumePrompt?: string;
+  note?: string;
+  requestedAt: number;
+  acceptedAt?: number;
+  completedAt?: number;
+  expiresAt?: number;
+  updatedAt: number;
+}
+
+export interface SandboxSession {
+  id: string;
+  status: 'queued' | 'assigning' | 'ready' | 'active' | 'ending' | 'ended' | 'failed' | 'pausing' | 'paused';
+  waitTimedOut?: boolean;
+  runtime: 'bun' | 'python' | 'base';
+  size: 'small' | 'medium' | 'large';
+  region?: string | null;
+  terminalUrl: string | null;
+  previewBaseUrl?: string | null;
+  capabilities?: SandboxCapabilities | null;
+  credentialDescriptors?: SandboxCredentialDescriptor[] | null;
+  pairedBrowser?: SandboxPairedBrowser | null;
+  opencode?: SandboxOpencodeState | null;
+  browserPreview?: SandboxBrowserPreviewState | null;
+  humanHandoff?: SandboxHumanHandoffState | null;
+  artifacts?: SandboxArtifacts | null;
+  createdAt: number;
+  duration: number | null;
+}
+
+export interface SandboxListResponse {
+  items: SandboxSession[];
+}
+
+export interface SandboxWorkerRuntimeState {
+  sessionId: string | null;
+  hasSession: boolean;
+  opencode: SandboxOpencodeState | null;
+  browserPreview: SandboxBrowserPreviewState | null;
+  pairedBrowser: SandboxPairedBrowser | null;
+  artifacts: SandboxArtifacts | null;
+  humanHandoff: SandboxHumanHandoffState | null;
+}
+
+export interface SandboxOpencodePromptResponse {
+  ok: boolean;
+  sessionId?: string;
+  response?: Record<string, unknown> | null;
+  error?: string;
+}
+
+export interface SandboxCheckpointResponse {
+  ok: boolean;
+  artifacts?: SandboxArtifacts;
+}
+
+export interface SandboxArtifactDownload {
+  id: string;
+  key: string;
+  url: string;
+  expiresInSeconds: number;
+}
+
+export interface SandboxBrowserControlResponse {
+  ok: boolean;
+  preview: SandboxBrowserPreviewState;
+  pairedBrowser: SandboxPairedBrowser | null;
+}
+
+export interface SandboxHumanHandoffResponse {
+  ok: boolean;
+  handoff: SandboxHumanHandoffState;
+  preview: SandboxBrowserPreviewState | null;
+  pairedBrowser?: SandboxPairedBrowser | null;
+}
+
+export interface SandboxHumanHandoffCompleteResponse {
+  ok: boolean;
+  handoff: SandboxHumanHandoffState;
+  preview: SandboxBrowserPreviewState | null;
+  pairedBrowser?: SandboxPairedBrowser | null;
+  resume?: SandboxOpencodePromptResponse;
+}
+
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  durationMs: number;
+}
+
+export interface FsEntry {
+  name: string;
+  type: 'file' | 'directory';
+  size: number;
+  mtime: number;
+}
+
+export interface LaunchedSandbox {
+  sessionId: string;
+  terminalUrl: string;
+  exec: (command: string, args?: string[]) => Promise<ExecResult>;
+  runCode: (code: string) => Promise<ExecResult>;
+  prompt: (
+    prompt: string,
+    options?: {
+      agent?: "build" | "plan";
+      sessionId?: string;
+      noReply?: boolean;
+    },
+  ) => Promise<SandboxOpencodePromptResponse>;
+  checkpoint: () => Promise<SandboxCheckpointResponse>;
+  getRuntime: () => Promise<SandboxRuntimeState>;
+  getPreview: () => Promise<SandboxBrowserPreviewInfo>;
+  getHandoff: () => Promise<SandboxHumanHandoffInfo>;
+  browserPreviewUrl: string | null;
+  setControl: (
+    mode: "ai" | "human" | "shared",
+    options?: { controller?: string; leaseMs?: number },
+  ) => Promise<SandboxBrowserControlResponse>;
+  takeControl: (
+    options?: { controller?: string; leaseMs?: number },
+  ) => Promise<SandboxBrowserControlResponse>;
+  returnControl: (
+    options?: { controller?: string; leaseMs?: number },
+  ) => Promise<SandboxBrowserControlResponse>;
+  requestHumanHandoff: (
+    options: {
+      reason: SandboxHumanHandoffReason;
+      message: string;
+      resumePrompt?: string;
+      expiresInMs?: number;
+    },
+  ) => Promise<SandboxHumanHandoffResponse>;
+  acceptHumanHandoff: (
+    options: { controller: string; leaseMs?: number },
+  ) => Promise<SandboxHumanHandoffResponse>;
+  completeHumanHandoff: (
+    options?: {
+      controller?: string;
+      note?: string;
+      returnControlTo?: "ai" | "shared";
+      runResumePrompt?: boolean;
+    },
+  ) => Promise<SandboxHumanHandoffCompleteResponse>;
+  fs: {
+    read: (path: string) => Promise<string>;
+    write: (path: string, content: string) => Promise<void>;
+    list: (path?: string) => Promise<FsEntry[]>;
+  };
+  kill: () => Promise<void>;
+}
+
+export interface SandboxRuntimeState {
+  id: string;
+  status: SandboxSession["status"];
+  capabilities: SandboxCapabilities | null;
+  pairedBrowser: SandboxPairedBrowser | null;
+  opencode: SandboxOpencodeState | null;
+  browserPreview: SandboxBrowserPreviewState | null;
+  humanHandoff: SandboxHumanHandoffState | null;
+  artifacts: SandboxArtifacts | null;
+  runtime: SandboxWorkerRuntimeState | null;
+}
+
+export interface SandboxBrowserPreviewInfo {
+  id: string;
+  browserPreviewUrl: string | null;
+  previewBaseUrl: string | null;
+  browserPreview: SandboxBrowserPreviewState | null;
+  humanHandoff: SandboxHumanHandoffState | null;
+  pairedBrowser: SandboxPairedBrowser | null;
+  runtime: {
+    preview: SandboxBrowserPreviewState | null;
+    pairedBrowser: SandboxPairedBrowser | null;
+    websocketUrl: string | null;
+    humanHandoff: SandboxHumanHandoffState | null;
+  } | null;
+}
+
+export interface SandboxHumanHandoffInfo {
+  id: string;
+  humanHandoff: SandboxHumanHandoffState | null;
+  browserPreview: SandboxBrowserPreviewState | null;
+  pairedBrowser: SandboxPairedBrowser | null;
+  runtime: {
+    handoff: SandboxHumanHandoffState | null;
+    preview: SandboxBrowserPreviewState | null;
+    pairedBrowser: SandboxPairedBrowser | null;
+  } | null;
+}
+
+export class BanataSandbox {
+  private apiKey: string;
+  private baseUrl: string;
+  private retryConfig: Required<RetryConfig>;
+
+  constructor(config: { apiKey: string; baseUrl?: string; retry?: RetryConfig }) {
+    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 ?? 10_000,
+    };
+  }
+
+  private get headers(): Record<string, string> {
+    return {
+      Authorization: `Bearer ${this.apiKey}`,
+      'Content-Type': 'application/json',
+    };
+  }
+
+  private async request<T>(
+    path: string,
+    options: RequestInit = {}
+  ): Promise<T> {
+    const { maxRetries, baseDelayMs, maxDelayMs } = this.retryConfig;
+    let lastError: BanataError | Error | undefined;
+
+    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: string;
+          let parsed: Record<string, unknown> = {};
+          try {
+            parsed = JSON.parse(body);
+            message = (parsed.error as string) ?? body;
+          } catch {
+            message = body;
+          }
+
+          const error = new BanataError(message, res.status, {
+            code: parsed.code as string | undefined,
+            requiredPlan: parsed.requiredPlan as string | undefined,
+            currentPlan: parsed.currentPlan as string | undefined,
+          });
+
+          if (isRetryableStatus(res.status) && attempt < maxRetries) {
+            lastError = error;
+            const retryAfterHeader = res.headers.get('Retry-After');
+            let delay: number;
+            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;
+        }
+
+        // Handle 204 No Content (e.g. DELETE responses)
+        if (res.status === 204) {
+          return undefined as T;
+        }
+
+        return res.json() as Promise<T>;
+      } 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');
+  }
+
+  // ── Sandbox lifecycle ──
+
+  /** Create a new sandbox session */
+  async create(config: SandboxConfig = {}): Promise<SandboxSession> {
+    const { timeout, waitTimeoutMs, ...rest } = config;
+    return this.request<SandboxSession>('/v1/sandboxes', {
+      method: 'POST',
+      body: JSON.stringify({
+        ...rest,
+        waitTimeoutMs: waitTimeoutMs ?? timeout,
+      }),
+    });
+  }
+
+  /** Get sandbox session status */
+  async get(id: string): Promise<SandboxSession> {
+    return this.request<SandboxSession>(
+      `/v1/sandboxes?id=${encodeURIComponent(id)}`
+    );
+  }
+
+  /** List sandbox sessions available to the API key's organization */
+  async list(): Promise<SandboxSession[]> {
+    const response = await this.request<SandboxListResponse>("/v1/sandboxes");
+    return response.items;
+  }
+
+  /** Kill (destroy) a sandbox session */
+  async kill(id: string): Promise<void> {
+    await this.request(`/v1/sandboxes?id=${encodeURIComponent(id)}`, {
+      method: 'DELETE',
+    });
+  }
+
+  /** Wait until sandbox is ready and return the session */
+  async waitForReady(
+    id: string,
+    timeoutMs: number = 30_000
+  ): Promise<SandboxSession> {
+    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
+    );
+  }
+
+  /** Execute a command in the sandbox */
+  async exec(
+    id: string,
+    command: string,
+    args?: string[]
+  ): Promise<ExecResult> {
+    return this.request<ExecResult>('/v1/sandboxes/exec', {
+      method: 'POST',
+      body: JSON.stringify({ id, command, args }),
+    });
+  }
+
+  /** Run code in the sandbox using its configured runtime */
+  async runCode(id: string, code: string): Promise<ExecResult> {
+    return this.request<ExecResult>('/v1/sandboxes/code', {
+      method: 'POST',
+      body: JSON.stringify({ id, code }),
+    });
+  }
+
+  /** Pause a sandbox (preserves state, stops billing) */
+  async pause(id: string): Promise<void> {
+    await this.request('/v1/sandboxes/pause', {
+      method: 'POST',
+      body: JSON.stringify({ id }),
+    });
+  }
+
+  /** Resume a paused sandbox */
+  async resume(id: string): Promise<void> {
+    await this.request('/v1/sandboxes/resume', {
+      method: 'POST',
+      body: JSON.stringify({ id }),
+    });
+  }
+
+  // ── File system operations ──
+
+  readonly fs = {
+    /** 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)}`
+      );
+      return result.content;
+    },
+
+    /** Write a file to the sandbox */
+    write: async (id: string, path: string, content: string): Promise<void> => {
+      await this.request('/v1/sandboxes/fs/write', {
+        method: 'POST',
+        body: JSON.stringify({ id, path, content }),
+      });
+    },
+
+    /** 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')}`
+      );
+    },
+  };
+
+  /** Get terminal connection info for a sandbox */
+  async terminal(id: string): Promise<{ terminalUrl: string | null; token: string | null }> {
+    return this.request<{ terminalUrl: string | null; token: string | null }>(
+      `/v1/sandboxes/terminal?id=${encodeURIComponent(id)}`
+    );
+  }
+
+  async getRuntime(id: string): Promise<SandboxRuntimeState> {
+    return this.request<SandboxRuntimeState>(
+      `/v1/sandboxes/runtime?id=${encodeURIComponent(id)}`
+    );
+  }
+
+  async prompt(
+    id: string,
+    prompt: string,
+    options: {
+      agent?: "build" | "plan";
+      sessionId?: string;
+      noReply?: boolean;
+    } = {},
+  ): Promise<SandboxOpencodePromptResponse> {
+    return this.request<SandboxOpencodePromptResponse>('/v1/sandboxes/opencode/prompt', {
+      method: 'POST',
+      body: JSON.stringify({
+        id,
+        prompt,
+        agent: options.agent,
+        sessionId: options.sessionId,
+        noReply: options.noReply,
+      }),
+    });
+  }
+
+  async checkpoint(id: string): Promise<SandboxCheckpointResponse> {
+    return this.request<SandboxCheckpointResponse>('/v1/sandboxes/checkpoint', {
+      method: 'POST',
+      body: JSON.stringify({ id }),
+    });
+  }
+
+  async getArtifacts(id: string): Promise<{ id: string; artifacts: SandboxArtifacts | null }> {
+    return this.request(
+      `/v1/sandboxes/artifacts?id=${encodeURIComponent(id)}`
+    );
+  }
+
+  async getArtifactDownloadUrl(
+    id: string,
+    key: string,
+    expiresInSeconds = 3600,
+  ): Promise<SandboxArtifactDownload> {
+    return this.request<SandboxArtifactDownload>(
+      `/v1/sandboxes/artifacts/download?id=${encodeURIComponent(id)}&key=${encodeURIComponent(key)}&expiresIn=${encodeURIComponent(String(expiresInSeconds))}`
+    );
+  }
+
+  async getPreview(id: string): Promise<SandboxBrowserPreviewInfo> {
+    return this.request<SandboxBrowserPreviewInfo>(
+      `/v1/sandboxes/browser-preview?id=${encodeURIComponent(id)}`
+    );
+  }
+
+  async getHandoff(id: string): Promise<SandboxHumanHandoffInfo> {
+    return this.request<SandboxHumanHandoffInfo>(
+      `/v1/sandboxes/handoff?id=${encodeURIComponent(id)}`
+    );
+  }
+
+  async requestHumanHandoff(
+    id: string,
+    options: {
+      reason: SandboxHumanHandoffReason;
+      message: string;
+      resumePrompt?: string;
+      expiresInMs?: number;
+    },
+  ): Promise<SandboxHumanHandoffResponse> {
+    return this.request<SandboxHumanHandoffResponse>('/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: string,
+    options: { controller: string; leaseMs?: number },
+  ): Promise<SandboxHumanHandoffResponse> {
+    return this.request<SandboxHumanHandoffResponse>('/v1/sandboxes/handoff/accept', {
+      method: 'POST',
+      body: JSON.stringify({
+        id,
+        controller: options.controller,
+        leaseMs: options.leaseMs,
+      }),
+    });
+  }
+
+  async completeHumanHandoff(
+    id: string,
+    options: {
+      controller?: string;
+      note?: string;
+      returnControlTo?: "ai" | "shared";
+      runResumePrompt?: boolean;
+    } = {},
+  ): Promise<SandboxHumanHandoffCompleteResponse> {
+    return this.request<SandboxHumanHandoffCompleteResponse>('/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: string,
+    mode: "ai" | "human" | "shared",
+    options: { controller?: string; leaseMs?: number } = {},
+  ): Promise<SandboxBrowserControlResponse> {
+    return this.request<SandboxBrowserControlResponse>('/v1/sandboxes/browser-preview/control', {
+      method: 'POST',
+      body: JSON.stringify({
+        id,
+        mode,
+        controller: options.controller,
+        leaseMs: options.leaseMs,
+      }),
+    });
+  }
+
+  /**
+   * Convenience: Create a sandbox, wait for it to be ready, and return
+   * a rich object with exec/fs/kill methods bound to this session.
+   *
+   * Usage:
+   * ```ts
+   * const sandbox = new BanataSandbox({ apiKey: '...' });
+   * const session = await sandbox.launch({ runtime: 'bun', size: 'small' });
+   *
+   * const result = await session.exec('echo', ['Hello!']);
+   * console.log(result.stdout);
+   *
+   * await session.kill();
+   * ```
+   */
+  async launch(config: SandboxConfig = {}): Promise<LaunchedSandbox> {
+    const created = await this.create(config);
+    let session: SandboxSession;
+
+    try {
+      session = await this.waitForReady(
+        created.id,
+        config.timeout ?? 30_000
+      );
+    } catch (err) {
+      // Clean up the orphaned sandbox on timeout/failure
+      try {
+        await this.kill(created.id);
+      } catch {
+        // Best-effort cleanup
+      }
+      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: string, args?: string[]) =>
+        this.exec(sessionId, command, args),
+      runCode: (code: string) =>
+        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: string) => this.fs.read(sessionId, path),
+        write: (path: string, content: string) =>
+          this.fs.write(sessionId, path, content),
+        list: (path?: string) => this.fs.list(sessionId, path),
+      },
+      kill: () => this.kill(sessionId),
+    };
+  }
+}
+
+// Default export for convenience
+export default BrowserCloud;