For agents

import { chromium, type Browser, type Page } from "patchright";

const API = "https://api.driver.dev";

export interface CreateOptions {
  type?: "hosted" | "hosted_stealth" | "hosted_privacy";
  country?: string;            // "US", "GB", "DE", … (see Countries)
  timezone?: string;           // IANA name from the country's list
  language?: string;           // BCP-47 tag from the country's list
  duration?: number;           // seconds, 60–3600, default 3600
  url?: string;                // opened right after launch
  profile?: { name: string; persist?: boolean };
  proxyUrl?: string;           // socks5://user:pass@host:port
  windowSize?: string;         // "1920x1040"
  displaySize?: string;        // "1920x1080"
  captchaSolver?: boolean;
  adblock?: boolean;
  extensionIds?: string[];
  nodeId?: string;
  browserCheck?: boolean;
  note?: string;               // up to 256 characters
}

export interface Session {
  sessionId: string;
  status: "starting" | "active" | "completed" | "error";
  cdpUrl: string | null;
  servedBy: string;
  createdAt: string;
  stoppedAt: string | null;
  note: string | null;
  bandwidthBytes?: number | null; // on GET: null while running, the metered total afterwards
}

/** Every non-2xx answer: `status` is the HTTP status, `code` the machine-readable code when there is one. */
export class DriverError extends Error {
  constructor(public status: number, message: string, public code?: string, public retryAfter?: number) {
    super(`Driver ${status}: ${message}`);
  }
}

const headers = () => ({
  Authorization: `Bearer ${process.env.DRIVER_API_KEY}`,
  "Content-Type": "application/json",
});

async function call<T>(method: string, path: string, body?: unknown): Promise<T> {
  const res = await fetch(`${API}${path}`, { method, headers: headers(), body: body ? JSON.stringify(body) : undefined });
  if (!res.ok) {
    const err = (await res.json().catch(() => ({}))) as { error?: string; code?: string };
    const retryAfter = Number(res.headers.get("retry-after")) || undefined;
    throw new DriverError(res.status, err.error ?? res.statusText, err.code, retryAfter);
  }
  return res.json() as Promise<T>;
}

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

/**
 * The error policy from the Errors page: 402 and 403 are reported at once; 503 backs off from Retry-After
 * with jitter and a cap; 504 and 500 are retried once; 429 backs off a few times.
 */
export async function createSession(opts: CreateOptions = {}): Promise<Session> {
  let attempt = 0;
  for (;;) {
    try {
      return await call<Session>("POST", "/v1/browser/session", opts);
    } catch (e) {
      if (!(e instanceof DriverError)) throw e;
      attempt++;
      if (e.status === 503 && attempt <= 5) { await sleep((e.retryAfter ?? 2) * 1000 * attempt + Math.random() * 1000); continue; }
      if ((e.status === 504 || e.status === 500) && attempt <= 1) continue;
      if (e.status === 429 && attempt <= 3) { await sleep(2000 * attempt + Math.random() * 1000); continue; }
      throw e; // 400, 401, 402, 403, or out of attempts: a person has to act
    }
  }
}

export const getSession = (id: string) => call<Session>("GET", `/v1/browser/session?sessionId=${encodeURIComponent(id)}`);

export const listSessions = (status?: Session["status"], page = 1, pageSize = 20) =>
  call<{ sessions: Array<Session & { type: string | null; country: string | null }>; total: number; totalPages: number; page: number; pageSize: number }>(
    "GET", `/v1/browser/sessions?page=${page}&pageSize=${pageSize}${status ? `&status=${status}` : ""}`);

/**
 * Idempotent. In a finally, a failed stop must not replace the error you are already handling, so this
 * logs instead of throwing; the session ends on its own at `duration` anyway.
 */
export async function stopSession(id: string): Promise<void> {
  try {
    const r = await call<{ success: boolean }>("DELETE", `/v1/browser/session?sessionId=${encodeURIComponent(id)}`);
    if (!r.success) console.error(`Driver: stop of ${id} did not succeed`);
  } catch (e) {
    console.error(`Driver: stop of ${id} failed: ${(e as Error).message}`);
  }
}

/**
 * Browser pools (see Browser pools in the docs): a warm browser in under a second. The returned session is an
 * ordinary session; release it (or stop it) in a finally. A 409 means nothing became ready within waitMs.
 */
export interface PoolLease {
  poolId: string;
  leaseId: string;
  acquiredAt: string;
  expiresAt: string;   // the session is stopped at this time unless released earlier
  session: Session & { cdpUrl: string };
}
export const acquireFromPool = (poolId: string, waitMs = 10_000) =>
  call<PoolLease>("POST", `/v1/browser/pools/${encodeURIComponent(poolId)}/acquire`, { waitMs });
export async function releaseLease(poolId: string, leaseId: string): Promise<void> {
  try {
    await call("POST", `/v1/browser/pools/${encodeURIComponent(poolId)}/release`, { leaseId });
  } catch (e) {
    console.error(`Driver: release of ${leaseId} failed: ${(e as Error).message}`);
  }
}

/** Create normally returns an active session; this covers the rare `starting` answer. */
export async function waitForActive(s: Session, timeoutMs = 60_000): Promise<Session & { cdpUrl: string }> {
  const deadline = Date.now() + timeoutMs;
  while (!(s.status === "active" && s.cdpUrl)) {
    if (s.status === "completed" || s.status === "error") throw new DriverError(500, `session ended: ${s.status}`);
    if (Date.now() > deadline) throw new DriverError(504, "timed out waiting for the browser");
    await sleep(1000);
    s = await getSession(s.sessionId);
  }
  return s as Session & { cdpUrl: string };
}

/**
 * Runs `fn` against a fresh Driver session, always stops it afterwards, and verifies the stop the way the
 * checklist asks (`status: "completed"`). `fn` receives the session too, for logging the id and building the
 * live view URL: `https://viewer.driver.dev?ws=${session.cdpUrl}`.
 */
export async function withBrowser<T>(
  opts: CreateOptions,
  fn: (page: Page, browser: Browser, session: Session & { cdpUrl: string }) => Promise<T>,
): Promise<T> {
  const session = await createSession(opts);
  try {
    const active = await waitForActive(session);
    const browser = await chromium.connectOverCDP(active.cdpUrl);
    try {
      const context = browser.contexts()[0] ?? (await browser.newContext());
      const page = context.pages()[0] ?? (await context.newPage());
      return await fn(page, browser, active);
    } finally {
      await browser.close(); // your connection only
    }
  } finally {
    await stopSession(session.sessionId);
    const after = await getSession(session.sessionId).catch(() => null);
    if (after?.status !== "completed") console.error(`Driver: session ${session.sessionId} is ${after?.status ?? "unknown"} after stop`);
    else console.log(`Driver: session ${session.sessionId} completed, ${after.bandwidthBytes ?? 0} bytes`);
  }
}

import os
import random
import time
from contextlib import contextmanager

import requests
from patchright.sync_api import sync_playwright

API = "https://api.driver.dev"


class DriverError(RuntimeError):
    """Every non-2xx answer: .status is the HTTP status, .code the machine-readable code when there is one."""

    def __init__(self, status, message, code=None, retry_after=None):
        super().__init__(f"Driver {status}: {message}")
        self.status, self.code, self.retry_after = status, code, retry_after


def _headers():
    return {"Authorization": f"Bearer {os.environ['DRIVER_API_KEY']}"}


def _call(method, path, **kwargs):
    r = requests.request(method, f"{API}{path}", headers=_headers(), timeout=200, **kwargs)
    if not r.ok:
        body = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
        raise DriverError(r.status_code, body.get("error", r.reason), body.get("code"), r.headers.get("Retry-After"))
    return r.json()


def create_session(**opts):
    """opts: type, country, timezone, language, duration, url, profile={"name": …, "persist": True},
    proxyUrl, windowSize, displaySize, captchaSolver, adblock, extensionIds, nodeId, browserCheck, note.
    Applies the error policy from the Errors page: 402/403 raise at once; 503 backs off with a cap;
    504/500 retry once; 429 backs off a few times."""
    attempt = 0
    while True:
        try:
            return _call("POST", "/v1/browser/session", json=opts)
        except DriverError as e:
            attempt += 1
            if e.status == 503 and attempt <= 5:
                time.sleep(float(e.retry_after or 2) * attempt + random.random())
            elif e.status in (504, 500) and attempt <= 1:
                pass
            elif e.status == 429 and attempt <= 3:
                time.sleep(2 * attempt + random.random())
            else:
                raise  # 400, 401, 402, 403, or out of attempts: a person has to act


def get_session(session_id):
    return _call("GET", "/v1/browser/session", params={"sessionId": session_id})


def list_sessions(status=None, page=1, page_size=20):
    params = {"page": page, "pageSize": page_size}
    if status:
        params["status"] = status
    return _call("GET", "/v1/browser/sessions", params=params)


def stop_session(session_id):
    """Idempotent. In a finally, a failed stop must not replace the error you are handling, so this logs."""
    try:
        _call("DELETE", "/v1/browser/session", params={"sessionId": session_id})
    except DriverError as e:
        print(f"Driver: stop of {session_id} failed: {e}")


def acquire_from_pool(pool_id, wait_ms=10000):
    """Browser pools: a warm browser in under a second. Returns {poolId, leaseId, acquiredAt, expiresAt, session};
    the session is an ordinary session. A 409 means nothing became ready within wait_ms."""
    return _call("POST", f"/v1/browser/pools/{pool_id}/acquire", json={"waitMs": wait_ms})


def release_lease(pool_id, lease_id):
    """Ends the leased session. Idempotent; logs instead of raising, for use in a finally."""
    try:
        _call("POST", f"/v1/browser/pools/{pool_id}/release", json={"leaseId": lease_id})
    except DriverError as e:
        print(f"Driver: release of {lease_id} failed: {e}")


def wait_for_active(session, timeout=60):
    """Create normally returns an active session; this covers the rare 'starting' answer."""
    deadline = time.time() + timeout
    while not (session["status"] == "active" and session.get("cdpUrl")):
        if session["status"] in ("completed", "error"):
            raise DriverError(500, f"session ended: {session['status']}")
        if time.time() > deadline:
            raise DriverError(504, "timed out waiting for the browser")
        time.sleep(1)
        session = get_session(session["sessionId"])
    return session


@contextmanager
def browser_page(**opts):
    """with browser_page(country="US") as page: ...  — always stops the session and verifies the stop.
    The session dict is on page.driver_session (id, cdpUrl for the live view: https://viewer.driver.dev?ws=<cdpUrl>)."""
    session = create_session(**opts)
    try:
        session = wait_for_active(session)
        with sync_playwright() as p:
            browser = p.chromium.connect_over_cdp(session["cdpUrl"])
            context = browser.contexts[0] if browser.contexts else browser.new_context()
            page = context.pages[0] if context.pages else context.new_page()
            page.driver_session = session
            try:
                yield page
            finally:
                browser.close()  # your connection only
    finally:
        stop_session(session["sessionId"])
        after = get_session(session["sessionId"])
        if after.get("status") != "completed":
            print(f"Driver: session {session['sessionId']} is {after.get('status')} after stop")