Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
Nick:
Nicolasbb1df562cd83
diff --git a/apps/js-sdk/firecrawl/src/v2/client.ts b/apps/js-sdk/firecrawl/src/v2/client.tsindex 3cdbda053..31d5a182c 100644--- a/apps/js-sdk/firecrawl/src/v2/client.ts+++ b/apps/js-sdk/firecrawl/src/v2/client.ts@@ -20,6 +20,12 @@ import {} from "./methods/batch";import { startExtract, getExtractStatus, extract as extractWaiter } from "./methods/extract";import { startAgent, getAgentStatus, cancelAgent, agent as agentWaiter } from "./methods/agent";+import {+ browser as browserMethod,+ browserExecute,+ deleteBrowser,+ listBrowsers,+} from "./methods/browser";import { getConcurrency, getCreditUsage, getQueueStatus, getTokenUsage, getCreditUsageHistorical, getTokenUsageHistorical } from "./methods/usage";import type {Document,@@ -40,6 +46,10 @@ import type {CrawlOptions,BatchScrapeOptions,PaginationConfig,+ BrowserCreateResponse,+ BrowserExecuteResponse,+ BrowserDeleteResponse,+ BrowserListResponse,} from "./types";import { Watcher } from "./watcher";import type { WatcherOptions } from "./watcher";@@ -298,6 +308,47 @@ export class FirecrawlClient {return cancelAgent(this.http, jobId);}+ // Browser+ /**+ * Create a new browser session.+ * @param args Session options (ttlTotal, ttlWithoutActivity, streamWebView).+ * @returns Session id and CDP URL.+ */+ async browser(+ args: Parameters<typeof browserMethod>[1] = {}+ ): Promise<BrowserCreateResponse> {+ return browserMethod(this.http, args);+ }+ /**+ * Execute code in a browser session.+ * @param sessionId Browser session id.+ * @param args Code and language to execute.+ * @returns Execution result.+ */+ async browserExecute(+ sessionId: string,+ args: Parameters<typeof browserExecute>[2]+ ): Promise<BrowserExecuteResponse> {+ return browserExecute(this.http, sessionId, args);+ }+ /**+ * Delete a browser session.+ * @param sessionId Browser session id.+ */+ async deleteBrowser(sessionId: string): Promise<BrowserDeleteResponse> {+ return deleteBrowser(this.http, sessionId);+ }+ /**+ * List browser sessions.+ * @param args Optional filter (status: "active" | "destroyed").+ * @returns List of browser sessions.+ */+ async listBrowsers(+ args: Parameters<typeof listBrowsers>[1] = {}+ ): Promise<BrowserListResponse> {+ return listBrowsers(this.http, args);+ }+// Usage/** Current concurrency usage. */async getConcurrency() {diff --git a/apps/js-sdk/firecrawl/src/v2/methods/browser.ts b/apps/js-sdk/firecrawl/src/v2/methods/browser.tsnew file mode 100644index 000000000..f952311bc--- /dev/null+++ b/apps/js-sdk/firecrawl/src/v2/methods/browser.ts@@ -0,0 +1,92 @@+import type {+ BrowserCreateResponse,+ BrowserExecuteResponse,+ BrowserDeleteResponse,+ BrowserListResponse,+} from "../types";+import { HttpClient } from "../utils/httpClient";+import { normalizeAxiosError, throwForBadResponse } from "../utils/errorHandler";++export async function browser(+ http: HttpClient,+ args: {+ ttlTotal?: number;+ ttlWithoutActivity?: number;+ streamWebView?: boolean;+ } = {}+): Promise<BrowserCreateResponse> {+ const body: Record<string, unknown> = {};+ if (args.ttlTotal != null) body.ttlTotal = args.ttlTotal;+ if (args.ttlWithoutActivity != null) body.ttlWithoutActivity = args.ttlWithoutActivity;+ if (args.streamWebView != null) body.streamWebView = args.streamWebView;++ try {+ const res = await http.post<BrowserCreateResponse>("/v2/browser", body);+ if (res.status !== 200) throwForBadResponse(res, "create browser session");+ return res.data;+ } catch (err: any) {+ if (err?.isAxiosError) return normalizeAxiosError(err, "create browser session");+ throw err;+ }+}++export async function browserExecute(+ http: HttpClient,+ sessionId: string,+ args: {+ code: string;+ language?: "python" | "js";+ }+): Promise<BrowserExecuteResponse> {+ const body: Record<string, unknown> = {+ code: args.code,+ language: args.language ?? "python",+ };++ try {+ const res = await http.post<BrowserExecuteResponse>(+ `/v2/browser/${sessionId}/execute`,+ body+ );+ if (res.status !== 200) throwForBadResponse(res, "execute browser code");+ return res.data;+ } catch (err: any) {+ if (err?.isAxiosError) return normalizeAxiosError(err, "execute browser code");+ throw err;+ }+}++export async function deleteBrowser(+ http: HttpClient,+ sessionId: string+): Promise<BrowserDeleteResponse> {+ try {+ const res = await http.delete<BrowserDeleteResponse>(+ `/v2/browser/${sessionId}`+ );+ if (res.status !== 200) throwForBadResponse(res, "delete browser session");+ return res.data;+ } catch (err: any) {+ if (err?.isAxiosError) return normalizeAxiosError(err, "delete browser session");+ throw err;+ }+}++export async function listBrowsers(+ http: HttpClient,+ args: {+ status?: "active" | "destroyed";+ } = {}+): Promise<BrowserListResponse> {+ let endpoint = "/v2/browser";+ if (args.status) endpoint += `?status=${args.status}`;++ try {+ const res = await http.get<BrowserListResponse>(endpoint);+ if (res.status !== 200) throwForBadResponse(res, "list browser sessions");+ return res.data;+ } catch (err: any) {+ if (err?.isAxiosError) return normalizeAxiosError(err, "list browser sessions");+ throw err;+ }+}diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.tsindex df9c79de8..fb8ccd833 100644--- a/apps/js-sdk/firecrawl/src/v2/types.ts+++ b/apps/js-sdk/firecrawl/src/v2/types.ts@@ -683,3 +683,37 @@ export interface QueueStatusResponse {maxConcurrency: number;mostRecentSuccess: string | null;}++// Browser types+export interface BrowserCreateResponse {+ success: boolean;+ id?: string;+ cdpUrl?: string;+ error?: string;+}++export interface BrowserExecuteResponse {+ success: boolean;+ result?: string;+ error?: string;+}++export interface BrowserDeleteResponse {+ success: boolean;+ error?: string;+}++export interface BrowserSession {+ id: string;+ status: string;+ cdpUrl: string;+ streamWebView: boolean;+ createdAt: string;+ lastActivity: string;+}++export interface BrowserListResponse {+ success: boolean;+ sessions?: BrowserSession[];+ error?: string;+}diff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.pyindex f461a8122..ada0efe08 100644--- a/apps/python-sdk/firecrawl/v2/client.py+++ b/apps/python-sdk/firecrawl/v2/client.py@@ -51,6 +51,7 @@ from .methods import batch as batch_methodsfrom .methods import usage as usage_methodsfrom .methods import extract as extract_modulefrom .methods import agent as agent_module+from .methods import browser as browser_modulefrom .watcher import Watcherclass FirecrawlClient:@@ -949,6 +950,84 @@ class FirecrawlClient:"""Get metrics about the team's scrape queue."""return usage_methods.get_queue_status(self.http_client)+ # Browser+ def browser(+ self,+ *,+ ttl_total: Optional[int] = None,+ ttl_without_activity: Optional[int] = None,+ stream_web_view: Optional[bool] = None,+ ):+ """Create a new browser session.++ Args:+ ttl_total: Total time-to-live in seconds (30-3600, default 300)+ ttl_without_activity: TTL without activity in seconds (10-3600)+ stream_web_view: Whether to enable webview streaming++ Returns:+ BrowserCreateResponse with session id and CDP URL+ """+ return browser_module.browser(+ self.http_client,+ ttl_total=ttl_total,+ ttl_without_activity=ttl_without_activity,+ stream_web_view=stream_web_view,+ )++ def browser_execute(+ self,+ session_id: str,+ code: str,+ *,+ language: Literal["python", "js"] = "python",+ ):+ """Execute code in a browser session.++ Args:+ session_id: Browser session ID+ code: Code to execute+ language: Programming language ("python" or "js")++ Returns:+ BrowserExecuteResponse with execution result+ """+ return browser_module.browser_execute(+ self.http_client,+ session_id,+ code,+ language=language,+ )++ def delete_browser(self, session_id: str):+ """Delete a browser session.++ Args:+ session_id: Browser session ID++ Returns:+ BrowserDeleteResponse+ """+ return browser_module.delete_browser(self.http_client, session_id)++ def list_browsers(+ self,+ *,+ status: Optional[Literal["active", "destroyed"]] = None,+ ):+ """List browser sessions.++ Args:+ status: Filter by session status ("active" or "destroyed")++ Returns:+ BrowserListResponse with list of sessions+ """+ return browser_module.list_browsers(+ self.http_client,+ status=status,+ )+def watcher(self,job_id: str,diff --git a/apps/python-sdk/firecrawl/v2/client_async.py b/apps/python-sdk/firecrawl/v2/client_async.pyindex 5bd482977..7ad422ed8 100644--- a/apps/python-sdk/firecrawl/v2/client_async.py+++ b/apps/python-sdk/firecrawl/v2/client_async.py@@ -46,6 +46,7 @@ from .methods.aio import map as async_map # type: ignore[attr-defined]from .methods.aio import usage as async_usage # type: ignore[attr-defined]from .methods.aio import extract as async_extract # type: ignore[attr-defined]from .methods.aio import agent as async_agent # type: ignore[attr-defined]+from .methods.aio import browser as async_browser # type: ignore[attr-defined]from .watcher_async import AsyncWatcher@@ -420,6 +421,86 @@ class AsyncFirecrawlClient:"""return await async_agent.cancel_agent(self.async_http_client, job_id)+ # Browser+ async def browser(+ self,+ *,+ ttl_total: Optional[int] = None,+ ttl_without_activity: Optional[int] = None,+ stream_web_view: Optional[bool] = None,+ ):+ """Create a new browser session.++ Args:+ ttl_total: Total time-to-live in seconds (30-3600, default 300)+ ttl_without_activity: TTL without activity in seconds (10-3600)+ stream_web_view: Whether to enable webview streaming++ Returns:+ BrowserCreateResponse with session id and CDP URL+ """+ return await async_browser.browser(+ self.async_http_client,+ ttl_total=ttl_total,+ ttl_without_activity=ttl_without_activity,+ stream_web_view=stream_web_view,+ )++ async def browser_execute(+ self,+ session_id: str,+ code: str,+ *,+ language: Literal["python", "js"] = "python",+ ):+ """Execute code in a browser session.++ Args:+ session_id: Browser session ID+ code: Code to execute+ language: Programming language ("python" or "js")++ Returns:+ BrowserExecuteResponse with execution result+ """+ return await async_browser.browser_execute(+ self.async_http_client,+ session_id,+ code,+ language=language,+ )++ async def delete_browser(self, session_id: str):+ """Delete a browser session.++ Args:+ session_id: Browser session ID++ Returns:+ BrowserDeleteResponse+ """+ return await async_browser.delete_browser(+ self.async_http_client, session_id+ )++ async def list_browsers(+ self,+ *,+ status: Optional[Literal["active", "destroyed"]] = None,+ ):+ """List browser sessions.++ Args:+ status: Filter by session status ("active" or "destroyed")++ Returns:+ BrowserListResponse with list of sessions+ """+ return await async_browser.list_browsers(+ self.async_http_client,+ status=status,+ )+# Usage endpointsasync def get_concurrency(self):from .methods.aio import usage as async_usage # type: ignore[attr-defined]diff --git a/apps/python-sdk/firecrawl/v2/methods/aio/browser.py b/apps/python-sdk/firecrawl/v2/methods/aio/browser.pynew file mode 100644index 000000000..26a468087--- /dev/null+++ b/apps/python-sdk/firecrawl/v2/methods/aio/browser.py@@ -0,0 +1,139 @@+"""+Async browser session methods for Firecrawl v2 API.++Provides async create, execute, delete, and list operations for browser sessions.+"""++from typing import Any, Dict, List, Literal, Optional++from ...types import (+ BrowserCreateResponse,+ BrowserExecuteResponse,+ BrowserDeleteResponse,+ BrowserListResponse,+)+from ...utils.http_client_async import AsyncHttpClient+++def _normalize_browser_create_response(payload: Dict[str, Any]) -> Dict[str, Any]:+ out = dict(payload)+ if "cdpUrl" in out and "cdp_url" not in out:+ out["cdp_url"] = out["cdpUrl"]+ return out+++def _normalize_browser_list_response(payload: Dict[str, Any]) -> Dict[str, Any]:+ out = dict(payload)+ if "sessions" in out and isinstance(out["sessions"], list):+ normalized_sessions = []+ for s in out["sessions"]:+ ns = dict(s)+ if "cdpUrl" in ns and "cdp_url" not in ns:+ ns["cdp_url"] = ns["cdpUrl"]+ if "streamWebView" in ns and "stream_web_view" not in ns:+ ns["stream_web_view"] = ns["streamWebView"]+ if "createdAt" in ns and "created_at" not in ns:+ ns["created_at"] = ns["createdAt"]+ if "lastActivity" in ns and "last_activity" not in ns:+ ns["last_activity"] = ns["lastActivity"]+ normalized_sessions.append(ns)+ out["sessions"] = normalized_sessions+ return out+++async def browser(+ client: AsyncHttpClient,+ *,+ ttl_total: Optional[int] = None,+ ttl_without_activity: Optional[int] = None,+ stream_web_view: Optional[bool] = None,+) -> BrowserCreateResponse:+ """Create a new browser session.++ Args:+ client: Async HTTP client instance+ ttl_total: Total time-to-live in seconds (30-3600, default 300)+ ttl_without_activity: TTL without activity in seconds (10-3600)+ stream_web_view: Whether to enable webview streaming++ Returns:+ BrowserCreateResponse with session id and CDP URL+ """+ body: Dict[str, Any] = {}+ if ttl_total is not None:+ body["ttlTotal"] = ttl_total+ if ttl_without_activity is not None:+ body["ttlWithoutActivity"] = ttl_without_activity+ if stream_web_view is not None:+ body["streamWebView"] = stream_web_view++ resp = await client.post("/v2/browser", body)+ payload = _normalize_browser_create_response(resp.json())+ return BrowserCreateResponse(**payload)+++async def browser_execute(+ client: AsyncHttpClient,+ session_id: str,+ code: str,+ *,+ language: Literal["python", "js"] = "python",+) -> BrowserExecuteResponse:+ """Execute code in a browser session.++ Args:+ client: Async HTTP client instance+ session_id: Browser session ID+ code: Code to execute+ language: Programming language ("python" or "js")++ Returns:+ BrowserExecuteResponse with execution result+ """+ body: Dict[str, Any] = {+ "code": code,+ "language": language,+ }++ resp = await client.post(f"/v2/browser/{session_id}/execute", body)+ return BrowserExecuteResponse(**resp.json())+++async def delete_browser(+ client: AsyncHttpClient,+ session_id: str,+) -> BrowserDeleteResponse:+ """Delete a browser session.++ Args:+ client: Async HTTP client instance+ session_id: Browser session ID++ Returns:+ BrowserDeleteResponse+ """+ resp = await client.delete(f"/v2/browser/{session_id}")+ return BrowserDeleteResponse(**resp.json())+++async def list_browsers(+ client: AsyncHttpClient,+ *,+ status: Optional[Literal["active", "destroyed"]] = None,+) -> BrowserListResponse:+ """List browser sessions.++ Args:+ client: Async HTTP client instance+ status: Filter by session status ("active" or "destroyed")++ Returns:+ BrowserListResponse with list of sessions+ """+ endpoint = "/v2/browser"+ if status is not None:+ endpoint = f"{endpoint}?status={status}"++ resp = await client.get(endpoint)+ payload = _normalize_browser_list_response(resp.json())+ return BrowserListResponse(**payload)diff --git a/apps/python-sdk/firecrawl/v2/methods/browser.py b/apps/python-sdk/firecrawl/v2/methods/browser.pynew file mode 100644index 000000000..f76b85f81--- /dev/null+++ b/apps/python-sdk/firecrawl/v2/methods/browser.py@@ -0,0 +1,148 @@+"""+Browser session methods for Firecrawl v2 API.++Provides create, execute, delete, and list operations for browser sessions.+"""++from typing import Any, Dict, List, Literal, Optional++from ..types import (+ BrowserCreateResponse,+ BrowserExecuteResponse,+ BrowserDeleteResponse,+ BrowserListResponse,+)+from ..utils.http_client import HttpClient+from ..utils.error_handler import handle_response_error+++def _normalize_browser_create_response(payload: Dict[str, Any]) -> Dict[str, Any]:+ out = dict(payload)+ if "cdpUrl" in out and "cdp_url" not in out:+ out["cdp_url"] = out["cdpUrl"]+ return out+++def _normalize_browser_list_response(payload: Dict[str, Any]) -> Dict[str, Any]:+ out = dict(payload)+ if "sessions" in out and isinstance(out["sessions"], list):+ normalized_sessions = []+ for s in out["sessions"]:+ ns = dict(s)+ if "cdpUrl" in ns and "cdp_url" not in ns:+ ns["cdp_url"] = ns["cdpUrl"]+ if "streamWebView" in ns and "stream_web_view" not in ns:+ ns["stream_web_view"] = ns["streamWebView"]+ if "createdAt" in ns and "created_at" not in ns:+ ns["created_at"] = ns["createdAt"]+ if "lastActivity" in ns and "last_activity" not in ns:+ ns["last_activity"] = ns["lastActivity"]+ normalized_sessions.append(ns)+ out["sessions"] = normalized_sessions+ return out+++def browser(+ client: HttpClient,+ *,+ ttl_total: Optional[int] = None,+ ttl_without_activity: Optional[int] = None,+ stream_web_view: Optional[bool] = None,+) -> BrowserCreateResponse:+ """Create a new browser session.++ Args:+ client: HTTP client instance+ ttl_total: Total time-to-live in seconds (30-3600, default 300)+ ttl_without_activity: TTL without activity in seconds (10-3600)+ stream_web_view: Whether to enable webview streaming++ Returns:+ BrowserCreateResponse with session id and CDP URL+ """+ body: Dict[str, Any] = {}+ if ttl_total is not None:+ body["ttlTotal"] = ttl_total+ if ttl_without_activity is not None:+ body["ttlWithoutActivity"] = ttl_without_activity+ if stream_web_view is not None:+ body["streamWebView"] = stream_web_view++ resp = client.post("/v2/browser", body)+ if not resp.ok:+ handle_response_error(resp, "create browser session")+ payload = _normalize_browser_create_response(resp.json())+ return BrowserCreateResponse(**payload)+++def browser_execute(+ client: HttpClient,+ session_id: str,+ code: str,+ *,+ language: Literal["python", "js"] = "python",+) -> BrowserExecuteResponse:+ """Execute code in a browser session.++ Args:+ client: HTTP client instance+ session_id: Browser session ID+ code: Code to execute+ language: Programming language ("python" or "js")++ Returns:+ BrowserExecuteResponse with execution result+ """+ body: Dict[str, Any] = {+ "code": code,+ "language": language,+ }++ resp = client.post(f"/v2/browser/{session_id}/execute", body)+ if not resp.ok:+ handle_response_error(resp, "execute browser code")+ return BrowserExecuteResponse(**resp.json())+++def delete_browser(+ client: HttpClient,+ session_id: str,+) -> BrowserDeleteResponse:+ """Delete a browser session.++ Args:+ client: HTTP client instance+ session_id: Browser session ID++ Returns:+ BrowserDeleteResponse+ """+ resp = client.delete(f"/v2/browser/{session_id}")+ if not resp.ok:+ handle_response_error(resp, "delete browser session")+ return BrowserDeleteResponse(**resp.json())+++def list_browsers(+ client: HttpClient,+ *,+ status: Optional[Literal["active", "destroyed"]] = None,+) -> BrowserListResponse:+ """List browser sessions.++ Args:+ client: HTTP client instance+ status: Filter by session status ("active" or "destroyed")++ Returns:+ BrowserListResponse with list of sessions+ """+ endpoint = "/v2/browser"+ if status is not None:+ endpoint = f"{endpoint}?status={status}"++ resp = client.get(endpoint)+ if not resp.ok:+ handle_response_error(resp, "list browser sessions")+ payload = _normalize_browser_list_response(resp.json())+ return BrowserListResponse(**payload)diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.pyindex 7dd452f7c..fcf34ab66 100644--- a/apps/python-sdk/firecrawl/v2/types.py+++ b/apps/python-sdk/firecrawl/v2/types.py@@ -809,6 +809,51 @@ class AgentResponse(BaseModel):expires_at: Optional[datetime] = Nonecredits_used: Optional[int] = None++# Browser types+class BrowserCreateResponse(BaseModel):+ """Response from creating a browser session."""++ success: bool+ id: Optional[str] = None+ cdp_url: Optional[str] = None+ error: Optional[str] = None+++class BrowserExecuteResponse(BaseModel):+ """Response from executing code in a browser session."""++ success: bool+ result: Optional[str] = None+ error: Optional[str] = None+++class BrowserDeleteResponse(BaseModel):+ """Response from deleting a browser session."""++ success: bool+ error: Optional[str] = None+++class BrowserSession(BaseModel):+ """Information about a browser session."""++ id: str+ status: str+ cdp_url: str+ stream_web_view: bool+ created_at: str+ last_activity: str+++class BrowserListResponse(BaseModel):+ """Response from listing browser sessions."""++ success: bool+ sessions: Optional[List["BrowserSession"]] = None+ error: Optional[str] = None++# Usage/limits typesclass ConcurrencyCheck(BaseModel):"""Current concurrency and limits for the team/API key."""