browsr_client/

lib.rs

//! Browsr Client - HTTP client for browser automation
//!
//! This crate provides a client for interacting with Browsr servers for browser automation,
//! web scraping, and structured content extraction.
//!
//! # Quick Start
//!
//! ```rust,ignore
//! use browsr_client::{BrowsrClient, BrowsrClientConfig};
//! use browsr_types::Commands;
//!
//! // From environment variables
//! let client = BrowsrClient::from_env();
//!
//! // Navigate to a page
//! let response = client.navigate("https://example.com", None).await?;
//!
//! // Extract structured content
//! let data = client.extract_structured(
//!     "Extract the main heading and first paragraph",
//!     None,
//!     None,
//! ).await?;
//! ```
//!
//! # Configuration
//!
//! The client can be configured via environment variables or programmatically:
//!
//! - `BROWSR_BASE_URL`: Base URL (defaults to `https://api.browsr.dev`)
//! - `BROWSR_API_KEY`: Optional API key for authentication

mod config;

pub use config::{BrowsrClientConfig, DEFAULT_BASE_URL, ENV_API_KEY, ENV_BASE_URL};

// Re-export browser_step types for convenient access
pub use browsr_types::{BrowserStepInput, BrowserStepRequest, BrowserStepResult};

use browsr_types::{
    AutomateResponse, BrowserContext, Commands, ObserveResponse, ScrapeOptions, SearchOptions,
    SearchResponse,
};
use reqwest::StatusCode;
use serde::{Deserialize, Serialize, de::DeserializeOwned};
use serde_json::{Value, json};
use thiserror::Error;
use tokio::process::Command;

#[derive(Debug, Clone)]
pub enum TransportConfig {
    Http { base_url: String },
    Stdout { command: String },
}

/// Browsr HTTP client for browser automation.
///
/// # Example
///
/// ```rust,ignore
/// use browsr_client::BrowsrClient;
///
/// // From environment variables (BROWSR_BASE_URL, BROWSR_API_KEY)
/// let client = BrowsrClient::from_env();
///
/// // From explicit URL (for local development)
/// let client = BrowsrClient::new("http://localhost:8082");
///
/// // With API key authentication
/// let client = BrowsrClient::new("https://api.browsr.dev")
///     .with_api_key("your-api-key");
/// ```
#[derive(Debug, Clone)]
pub struct BrowsrClient {
    transport: BrowsrTransport,
    config: BrowsrClientConfig,
}

#[derive(Debug, Clone)]
enum BrowsrTransport {
    Http(HttpTransport),
    Stdout(StdoutTransport),
}

impl BrowsrClient {
    /// Create a new client with the specified base URL (no authentication).
    /// For local development, use this method.
    pub fn new(base_url: impl Into<String>) -> Self {
        let config = BrowsrClientConfig::new(base_url);
        Self::from_client_config(config)
    }

    /// Create a new client from environment variables.
    ///
    /// - `BROWSR_BASE_URL`: Base URL (defaults to `https://api.browsr.dev`)
    /// - `BROWSR_API_KEY`: Optional API key for authentication
    pub fn from_env() -> Self {
        let config = BrowsrClientConfig::from_env();
        Self::from_client_config(config)
    }

    /// Create a new client from explicit configuration.
    pub fn from_client_config(config: BrowsrClientConfig) -> Self {
        let http = config
            .build_http_client()
            .expect("Failed to build HTTP client");

        Self {
            transport: BrowsrTransport::Http(HttpTransport::new_with_client(
                &config.base_url,
                http,
            )),
            config,
        }
    }

    /// Set the API key for authentication.
    /// This rebuilds the HTTP client with the new authentication header.
    pub fn with_api_key(mut self, api_key: impl Into<String>) -> Self {
        self.config = self.config.with_api_key(api_key);
        let http = self
            .config
            .build_http_client()
            .expect("Failed to build HTTP client");
        self.transport =
            BrowsrTransport::Http(HttpTransport::new_with_client(&self.config.base_url, http));
        self
    }

    /// Create HTTP transport client (legacy method).
    pub fn new_http(base_url: impl Into<String>) -> Self {
        Self::new(base_url)
    }

    /// Create stdout transport client.
    pub fn new_stdout(command: impl Into<String>) -> Self {
        Self {
            transport: BrowsrTransport::Stdout(StdoutTransport::new(command)),
            config: BrowsrClientConfig::default(),
        }
    }

    /// Create client from transport config (legacy method).
    pub fn from_config(cfg: TransportConfig) -> Self {
        match cfg {
            TransportConfig::Http { base_url } => Self::new_http(base_url),
            TransportConfig::Stdout { command } => Self::new_stdout(command),
        }
    }

    /// Get the base URL.
    pub fn base_url(&self) -> &str {
        &self.config.base_url
    }

    /// Get the current configuration.
    pub fn config(&self) -> &BrowsrClientConfig {
        &self.config
    }

    /// Check if the client has authentication configured.
    pub fn has_auth(&self) -> bool {
        self.config.has_auth()
    }

    /// Check if this is a local development client.
    pub fn is_local(&self) -> bool {
        self.config.is_local()
    }

    // ============================================================
    // Session Management
    // ============================================================

    /// List all active browser sessions.
    pub async fn list_sessions(&self) -> Result<Vec<String>, ClientError> {
        match &self.transport {
            BrowsrTransport::Http(inner) => {
                let response: SessionList = inner.get("/sessions").await?;
                Ok(response.sessions)
            }
            BrowsrTransport::Stdout(inner) => inner.list_sessions().await,
        }
    }

    /// Create a new browser session.
    /// Returns the full session info including viewer_url, sse_url, and frame_url.
    pub async fn create_session(&self) -> Result<SessionCreated, ClientError> {
        match &self.transport {
            BrowsrTransport::Http(inner) => {
                inner.post("/sessions", &Value::Null).await
            }
            BrowsrTransport::Stdout(inner) => {
                let session_id = inner.create_session().await?;
                Ok(SessionCreated {
                    session_id,
                    sse_url: None,
                    frame_url: None,
                    frame_token: None,
                })
            }
        }
    }

    /// Destroy a browser session.
    pub async fn destroy_session(&self, session_id: &str) -> Result<(), ClientError> {
        match &self.transport {
            BrowsrTransport::Http(inner) => inner
                .delete(&format!("/sessions/{}", session_id))
                .await
                .map(|_: Value| ()),
            BrowsrTransport::Stdout(inner) => inner.destroy_session(session_id).await,
        }
    }

    // ============================================================
    // Command Execution
    // ============================================================

    /// Execute a list of browser commands.
    pub async fn execute_commands(
        &self,
        commands: Vec<Commands>,
        session_id: Option<String>,
        headless: Option<bool>,
        context: Option<BrowserContext>,
    ) -> Result<AutomateResponse, ClientError> {
        let payload = CommandsPayload {
            commands,
            session_id,
            headless: headless.or(self.config.headless),
            context,
        };

        match &self.transport {
            BrowsrTransport::Http(inner) => inner.post("/commands", &payload).await,
            BrowsrTransport::Stdout(inner) => inner.execute_commands(&payload).await,
        }
    }

    /// Execute a single browser command.
    pub async fn execute_command(
        &self,
        command: Commands,
        session_id: Option<String>,
        headless: Option<bool>,
    ) -> Result<AutomateResponse, ClientError> {
        self.execute_commands(vec![command], session_id, headless, None)
            .await
    }

    // ============================================================
    // Convenience Methods for Common Commands
    // ============================================================

    /// Navigate to a URL.
    pub async fn navigate(
        &self,
        url: &str,
        session_id: Option<String>,
    ) -> Result<AutomateResponse, ClientError> {
        self.execute_command(
            Commands::NavigateTo {
                url: url.to_string(),
            },
            session_id,
            None,
        )
        .await
    }

    /// Click an element by selector.
    pub async fn click(
        &self,
        selector: &str,
        session_id: Option<String>,
    ) -> Result<AutomateResponse, ClientError> {
        self.execute_command(
            Commands::Click {
                selector: selector.to_string(),
            },
            session_id,
            None,
        )
        .await
    }

    /// Type text into an element.
    pub async fn type_text(
        &self,
        selector: &str,
        text: &str,
        clear: Option<bool>,
        session_id: Option<String>,
    ) -> Result<AutomateResponse, ClientError> {
        self.execute_command(
            Commands::TypeText {
                selector: selector.to_string(),
                text: text.to_string(),
                clear,
            },
            session_id,
            None,
        )
        .await
    }

    /// Wait for an element to appear.
    pub async fn wait_for_element(
        &self,
        selector: &str,
        timeout_ms: Option<u64>,
        session_id: Option<String>,
    ) -> Result<AutomateResponse, ClientError> {
        self.execute_command(
            Commands::WaitForElement {
                selector: selector.to_string(),
                timeout_ms,
                visible_only: None,
            },
            session_id,
            None,
        )
        .await
    }

    /// Take a screenshot.
    pub async fn screenshot(
        &self,
        full_page: bool,
        session_id: Option<String>,
    ) -> Result<AutomateResponse, ClientError> {
        self.execute_command(
            Commands::Screenshot {
                full_page: Some(full_page),
                path: None,
            },
            session_id,
            None,
        )
        .await
    }

    /// Get page title.
    pub async fn get_title(
        &self,
        session_id: Option<String>,
    ) -> Result<AutomateResponse, ClientError> {
        self.execute_command(Commands::GetTitle, session_id, None)
            .await
    }

    /// Get text content of an element.
    pub async fn get_text(
        &self,
        selector: &str,
        session_id: Option<String>,
    ) -> Result<AutomateResponse, ClientError> {
        self.execute_command(
            Commands::GetText {
                selector: selector.to_string(),
            },
            session_id,
            None,
        )
        .await
    }

    /// Get HTML content of an element or page.
    pub async fn get_content(
        &self,
        selector: Option<String>,
        session_id: Option<String>,
    ) -> Result<AutomateResponse, ClientError> {
        self.execute_command(
            Commands::GetContent {
                selector,
                kind: None,
            },
            session_id,
            None,
        )
        .await
    }

    /// Evaluate JavaScript expression.
    pub async fn evaluate(
        &self,
        expression: &str,
        session_id: Option<String>,
    ) -> Result<AutomateResponse, ClientError> {
        self.execute_command(
            Commands::Evaluate {
                expression: expression.to_string(),
            },
            session_id,
            None,
        )
        .await
    }

    // ============================================================
    // Structured Extraction
    // ============================================================

    /// Extract structured content from the current page using AI.
    ///
    /// # Arguments
    /// * `query` - Natural language description of what to extract
    /// * `schema` - Optional JSON schema for the output
    /// * `max_chars` - Optional maximum characters to process
    /// * `session_id` - Optional session ID
    ///
    /// # Example
    /// ```rust,ignore
    /// let data = client.extract_structured(
    ///     "Extract all product names and prices",
    ///     None,
    ///     None,
    /// ).await?;
    /// ```
    pub async fn extract_structured(
        &self,
        query: &str,
        schema: Option<serde_json::Value>,
        max_chars: Option<usize>,
        session_id: Option<String>,
    ) -> Result<AutomateResponse, ClientError> {
        self.execute_command(
            Commands::ExtractStructuredContent {
                query: query.to_string(),
                schema,
                max_chars,
            },
            session_id,
            None,
        )
        .await
    }

    // ============================================================
    // Observation
    // ============================================================

    /// Observe the current browser state (screenshot + DOM snapshot).
    pub async fn observe(
        &self,
        session_id: Option<String>,
        headless: Option<bool>,
        opts: ObserveOptions,
    ) -> Result<ObserveResponse, ClientError> {
        let payload = ObservePayload {
            session_id,
            headless: headless.or(self.config.headless),
            use_image: opts.use_image,
            full_page: opts.full_page,
            wait_ms: opts.wait_ms,
            include_content: opts.include_content,
        };

        match &self.transport {
            BrowsrTransport::Http(inner) => {
                let envelope: ObserveEnvelope = inner.post("/observe", &payload).await?;
                Ok(envelope.observation)
            }
            BrowsrTransport::Stdout(inner) => inner.observe(&payload).await,
        }
    }

    // ============================================================
    // Scraping
    // ============================================================

    /// Scrape content from a URL or the current page.
    pub async fn scrape(&self, options: ScrapeOptions) -> Result<Value, ClientError> {
        match &self.transport {
            BrowsrTransport::Http(inner) => inner.post("/scrape", &options).await,
            BrowsrTransport::Stdout(inner) => inner.scrape(&options).await,
        }
    }

    /// Scrape a URL with default options.
    pub async fn scrape_url(&self, url: &str) -> Result<Value, ClientError> {
        let options = ScrapeOptions {
            url: url.to_string(),
            use_js: None,
            wait_for: None,
            extract_links: None,
            selector: None,
            extract_images: None,
            extract_metadata: None,
            extract_tables: None,
            extract_forms: None,
            extract_structured_data: None,
            readable_content: None,
            remove_base64_images: None,
        };
        self.scrape(options).await
    }

    // ============================================================
    // Search
    // ============================================================

    /// Perform a web search.
    pub async fn search(&self, options: SearchOptions) -> Result<SearchResponse, ClientError> {
        match &self.transport {
            BrowsrTransport::Http(inner) => inner.post("/search", &options).await,
            BrowsrTransport::Stdout(inner) => inner.search(&options).await,
        }
    }

    /// Search with a query string.
    pub async fn search_query(&self, query: &str) -> Result<SearchResponse, ClientError> {
        let options = SearchOptions {
            query: query.to_string(),
            limit: None,
        };
        self.search(options).await
    }

    // ============================================================
    // Browser Step (Agent Integration)
    // ============================================================

    /// Execute a browser step with commands and optional context.
    ///
    /// This is the primary method for agent integration, providing full control
    /// over browser automation with context for sequence persistence.
    ///
    /// # Arguments
    /// * `request` - Full browser step request with commands and context
    ///
    /// # Example
    /// ```rust,ignore
    /// use browsr_client::{BrowsrClient, BrowserStepRequest, BrowserStepInput};
    /// use browsr_types::Commands;
    ///
    /// let client = BrowsrClient::from_env();
    ///
    /// let input = BrowserStepInput::new(vec![
    ///     Commands::NavigateTo { url: "https://example.com".to_string() },
    ///     Commands::Screenshot { full_page: Some(false), path: None },
    /// ]);
    ///
    /// let request = BrowserStepRequest::new(input)
    ///     .with_session_id("my-session")
    ///     .with_thread_id("thread-123");
    ///
    /// let result = client.step(request).await?;
    /// println!("Success: {}, URL: {:?}", result.success, result.url);
    /// ```
    pub async fn step(&self, request: BrowserStepRequest) -> Result<BrowserStepResult, ClientError> {
        match &self.transport {
            BrowsrTransport::Http(inner) => inner.post("/browser_step", &request).await,
            BrowsrTransport::Stdout(inner) => inner.browser_step(&request).await,
        }
    }

    /// Execute a browser step with just commands (simple usage).
    ///
    /// Use this for quick automation tasks without context tracking.
    ///
    /// # Example
    /// ```rust,ignore
    /// use browsr_client::BrowsrClient;
    /// use browsr_types::Commands;
    ///
    /// let client = BrowsrClient::from_env();
    ///
    /// let result = client.step_commands(vec![
    ///     Commands::NavigateTo { url: "https://example.com".to_string() },
    /// ]).await?;
    /// ```
    pub async fn step_commands(
        &self,
        commands: Vec<Commands>,
    ) -> Result<BrowserStepResult, ClientError> {
        let input = BrowserStepInput::new(commands);
        let request = BrowserStepRequest::new(input);
        self.step(request).await
    }
}

// ============================================================
// Internal Types
// ============================================================

#[derive(Debug, Clone, Serialize, Deserialize)]
struct SessionList {
    sessions: Vec<String>,
}

/// Response from creating a browser session
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SessionCreated {
    pub session_id: String,
    /// SSE stream URL (backend API) for event streaming
    #[serde(default)]
    pub sse_url: Option<String>,
    /// Frame URL for embedding (frontend app with token)
    #[serde(default)]
    pub frame_url: Option<String>,
    /// Frame token for SSE authentication
    #[serde(default)]
    pub frame_token: Option<String>,
}

impl SessionCreated {
    /// Build SSE stream URL with authentication token and optional dimensions
    pub fn build_sse_url(&self, base_url: &str, width: Option<u32>, height: Option<u32>) -> String {
        let mut url = self.sse_url.clone().unwrap_or_else(|| {
            format!("{}/stream/sse?session_id={}", base_url, self.session_id)
        });

        // Add token if available
        if let Some(ref token) = self.frame_token {
            let sep = if url.contains('?') { "&" } else { "?" };
            url = format!("{}{}token={}", url, sep, token);
        }

        // Add dimensions if provided
        if let Some(w) = width {
            let sep = if url.contains('?') { "&" } else { "?" };
            url = format!("{}{}width={}", url, sep, w);
        }
        if let Some(h) = height {
            url = format!("{}&height={}", url, h);
        }

        url
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct CommandsPayload {
    commands: Vec<Commands>,
    #[serde(skip_serializing_if = "Option::is_none")]
    session_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    headless: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    context: Option<BrowserContext>,
}

/// Options for observing the browser state.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ObserveOptions {
    pub use_image: Option<bool>,
    pub full_page: Option<bool>,
    pub wait_ms: Option<u64>,
    pub include_content: Option<bool>,
}

impl Default for ObserveOptions {
    fn default() -> Self {
        Self {
            use_image: Some(true),
            full_page: None,
            wait_ms: None,
            include_content: Some(true),
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct ObservePayload {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub session_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub headless: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub use_image: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub full_page: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub wait_ms: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub include_content: Option<bool>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct ObserveEnvelope {
    pub session_id: String,
    pub observation: ObserveResponse,
}

// ============================================================
// Error Types
// ============================================================

#[derive(Debug, Error)]
pub enum ClientError {
    #[error("http request failed: {0}")]
    Http(#[from] reqwest::Error),
    #[error("stdout transport failed: {0}")]
    Stdout(String),
    #[error("invalid response: {0}")]
    InvalidResponse(String),
    #[error("serialization error: {0}")]
    Serialization(#[from] serde_json::Error),
    #[error("io error: {0}")]
    Io(#[from] std::io::Error),
}

// ============================================================
// HTTP Transport
// ============================================================

#[derive(Debug, Clone)]
struct HttpTransport {
    base_url: String,
    client: reqwest::Client,
}

impl HttpTransport {
    fn new_with_client(base_url: impl Into<String>, client: reqwest::Client) -> Self {
        Self {
            base_url: base_url.into(),
            client,
        }
    }

    fn url(&self, path: &str) -> String {
        let base = self.base_url.trim_end_matches('/');
        let suffix = path.trim_start_matches('/');
        format!("{}/{}", base, suffix)
    }

    async fn get<T: DeserializeOwned>(&self, path: &str) -> Result<T, ClientError> {
        let resp = self.client.get(self.url(path)).send().await?;
        Self::handle_response(resp).await
    }

    async fn delete<T: DeserializeOwned>(&self, path: &str) -> Result<T, ClientError> {
        let resp = self.client.delete(self.url(path)).send().await?;
        Self::handle_response(resp).await
    }

    async fn post<T: DeserializeOwned, B: Serialize + ?Sized>(
        &self,
        path: &str,
        body: &B,
    ) -> Result<T, ClientError> {
        let resp = self.client.post(self.url(path)).json(body).send().await?;
        Self::handle_response(resp).await
    }

    async fn handle_response<T: DeserializeOwned>(
        resp: reqwest::Response,
    ) -> Result<T, ClientError> {
        let status = resp.status();
        if status == StatusCode::NO_CONTENT {
            let empty: Value = Value::Null;
            let value: T = serde_json::from_value(empty).map_err(ClientError::Serialization)?;
            return Ok(value);
        }

        let text = resp.text().await?;
        if !status.is_success() {
            return Err(ClientError::InvalidResponse(format!(
                "{}: {}",
                status, text
            )));
        }

        serde_json::from_str(&text).map_err(ClientError::Serialization)
    }
}

// ============================================================
// Stdout Transport
// ============================================================

#[derive(Debug, Clone)]
struct StdoutTransport {
    command: String,
}

impl StdoutTransport {
    fn new(command: impl Into<String>) -> Self {
        Self {
            command: command.into(),
        }
    }

    async fn list_sessions(&self) -> Result<Vec<String>, ClientError> {
        let envelope: SessionList = self.request("sessions", &Value::Null).await?;
        Ok(envelope.sessions)
    }

    async fn create_session(&self) -> Result<String, ClientError> {
        let created: SessionCreated = self.request("create_session", &Value::Null).await?;
        Ok(created.session_id)
    }

    async fn destroy_session(&self, session_id: &str) -> Result<(), ClientError> {
        let payload = json!({ "session_id": session_id });
        let _: Value = self.request("destroy_session", &payload).await?;
        Ok(())
    }

    async fn execute_commands(
        &self,
        payload: &CommandsPayload,
    ) -> Result<AutomateResponse, ClientError> {
        self.request("execute", payload).await
    }

    async fn observe(&self, payload: &ObservePayload) -> Result<ObserveResponse, ClientError> {
        let envelope: ObserveEnvelope = self.request("observe", payload).await?;
        Ok(envelope.observation)
    }

    async fn scrape(&self, options: &ScrapeOptions) -> Result<Value, ClientError> {
        self.request("scrape", options).await
    }

    async fn search(&self, options: &SearchOptions) -> Result<SearchResponse, ClientError> {
        self.request("search", options).await
    }

    async fn browser_step(
        &self,
        request: &BrowserStepRequest,
    ) -> Result<BrowserStepResult, ClientError> {
        self.request("browser_step", request).await
    }

    async fn request<T: DeserializeOwned, B: Serialize>(
        &self,
        operation: &str,
        payload: &B,
    ) -> Result<T, ClientError> {
        let mut cmd = Command::new(&self.command);
        cmd.arg("client").arg(operation);

        let payload_str = serde_json::to_string(&payload).map_err(ClientError::Serialization)?;
        cmd.env("BROWSR_CLIENT_PAYLOAD", &payload_str);

        let output = cmd.output().await?;
        if !output.status.success() {
            let stderr = String::from_utf8_lossy(&output.stderr).to_string();
            return Err(ClientError::Stdout(format!(
                "browsr command failed ({}): {}",
                output.status, stderr
            )));
        }

        let stdout = String::from_utf8_lossy(&output.stdout);
        if stdout.trim().is_empty() {
            return Err(ClientError::InvalidResponse(
                "empty stdout from browsr".to_string(),
            ));
        }

        serde_json::from_str(stdout.trim()).map_err(ClientError::Serialization)
    }
}

// ============================================================
// Legacy Helper Functions
// ============================================================

/// Derive a default base URL for HTTP transport from standard env vars.
pub fn default_base_url() -> Option<String> {
    if let Ok(url) = std::env::var("BROWSR_API_URL") {
        return Some(url);
    }
    if let Ok(url) = std::env::var("BROWSR_BASE_URL") {
        return Some(url);
    }
    if let Ok(port) = std::env::var("BROWSR_PORT") {
        let host = std::env::var("BROWSR_HOST").unwrap_or_else(|_| "127.0.0.1".to_string());
        return Some(format!("http://{}:{}", host, port));
    }
    // Return cloud default
    Some(DEFAULT_BASE_URL.to_string())
}

pub fn default_transport() -> TransportConfig {
    TransportConfig::Http {
        base_url: default_base_url().unwrap_or_else(|| DEFAULT_BASE_URL.to_string()),
    }
}