flarer 0.1.0

Rust client and CLI for Cloudflare's Browser Rendering REST API (content, screenshot, PDF, snapshot, markdown, scrape, JSON extraction, links, crawl).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

//! Request/response types and helpers.

use std::path::PathBuf;

use serde::{Deserialize, Serialize};
use serde_json::Value;

/// `response_format` payload accepted by Cloudflare's JSON tool.
///
/// The schema is held as a free-form [`serde_json::Value`] so it round-trips
/// with the canonical JSON Schema representation (keys like `type`,
/// `properties`, `required`, ...).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ResponseFormat {
    /// Always `"json_schema"` for Cloudflare today.
    #[serde(rename = "type")]
    pub format_type: String,
    /// The JSON Schema describing the expected response shape.
    pub schema: Value,
}

impl ResponseFormat {
    /// Convenience constructor for `{"type": "json_schema", "schema": ...}`.
    pub fn json_schema(schema: Value) -> Self {
        Self {
            format_type: "json_schema".to_string(),
            schema,
        }
    }
}

/// Optional knobs passed to [`Flarer::json`](crate::Flarer::json).
#[derive(Debug, Clone, Default)]
pub struct JsonOptions {
    /// Free-form prompt steering the LLM extractor.
    pub prompt: Option<String>,
    /// Structured output schema.
    pub response_format: Option<ResponseFormat>,
}

impl JsonOptions {
    /// New, empty options.
    pub fn new() -> Self {
        Self::default()
    }
    /// Set the prompt.
    pub fn with_prompt(mut self, prompt: impl Into<String>) -> Self {
        self.prompt = Some(prompt.into());
        self
    }
    /// Set the response format.
    pub fn with_response_format(mut self, rf: ResponseFormat) -> Self {
        self.response_format = Some(rf);
        self
    }
}

/// Decoded `snapshot` endpoint response.
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct SnapshotResult {
    /// Base64-encoded PNG screenshot.
    pub screenshot: String,
    /// Captured HTML content.
    pub content: String,
}

/// Top-level envelope returned by the Cloudflare API.
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct CfEnvelope<T> {
    /// Whether the request succeeded.
    pub success: bool,
    /// Result body when `success == true`.
    pub result: Option<T>,
    /// Errors when `success == false`.
    #[serde(default)]
    pub errors: Vec<Value>,
    /// Informational messages.
    #[serde(default)]
    pub messages: Vec<Value>,
}

/// Result of running a tool. The variant depends on the tool invoked.
#[derive(Debug, Clone)]
pub enum Output {
    /// Free-form JSON value (content, markdown, scrape, links, crawl, json).
    Json(Value),
    /// Path to a binary file written to disk (screenshot, pdf).
    File(PathBuf),
    /// Snapshot result: PNG path + captured HTML.
    Snapshot {
        /// Path to the saved PNG.
        png: PathBuf,
        /// HTML content captured by the snapshot.
        html: String,
    },
}

impl Output {
    /// Pretty-print the output for human consumption.
    pub fn display_string(&self) -> String {
        match self {
            Output::Json(v) => serde_json::to_string_pretty(v).unwrap_or_else(|_| v.to_string()),
            Output::File(p) => format!("Saved to {}", p.display()),
            Output::Snapshot { png, html } => {
                format!("Snapshot PNG: {}\n--- HTML ---\n{}", png.display(), html)
            }
        }
    }
}