screenshotfreeapi 1.0.0

Official Rust client for ScreenshotFreeAPI — Screenshot-as-a-Service
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
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

use std::sync::Arc;

use crate::error::Result;
use crate::http::HttpClient;
use crate::resources::{
    auth::AuthResource,
    billing::BillingResource,
    integrations::IntegrationsResource,
    jobs::JobsResource,
    monitors::MonitorsResource,
    screenshots::{wait_for_job, ScreenshotsResource, WaitOptions},
    workspaces::WorkspacesResource,
};
use crate::types::{HealthResponse, JobResult, WebScreenshotOptions};

/// The main entry point for the ScreenshotFreeAPI Rust client.
///
/// Construct with [`ScreenshotFreeAPIClient::new`] and access endpoints through the
/// resource fields:
///
/// ```rust,no_run
/// use screenshotfreeapi::ScreenshotFreeAPIClient;
///
/// #[tokio::main]
/// async fn main() -> screenshotfreeapi::Result<()> {
///     let client = ScreenshotFreeAPIClient::new("sfa_your_api_key");
///
///     // Quick one-liner capture
///     let result = client.capture("https://stripe.com").await?;
///     println!("{}", result.screenshots[0].url);
///     Ok(())
/// }
/// ```
///
/// # Resources
///
/// | Field | Endpoints |
/// |---|---|
/// | `auth` | `/auth/register`, `/auth/token`, `/auth/refresh` |
/// | `screenshots` | `/screenshots/web`, `/screenshots/mobile`, `/screenshots/html` |
/// | `jobs` | `/jobs/:id/status`, `/jobs/:id/result` |
/// | `billing` | `/billing/*` |
/// | `workspaces` | `/workspaces/*` |
/// | `monitors` | `/monitors/app/*` |
/// | `integrations` | `/integrations/zapier/*` |
#[derive(Clone)]
pub struct ScreenshotFreeAPIClient {
    http: Arc<HttpClient>,

    /// Auth endpoints — register, token, refresh.
    pub auth: AuthResource,

    /// Screenshot capture endpoints.
    pub screenshots: ScreenshotsResource,

    /// Job status polling and result fetching.
    pub jobs: JobsResource,

    /// Billing plans, usage, upgrades, and cancellation.
    pub billing: BillingResource,

    /// Team workspace management.
    pub workspaces: WorkspacesResource,

    /// Scheduled app monitors.
    pub monitors: MonitorsResource,

    /// Zapier REST Hook integrations.
    pub integrations: IntegrationsResource,
}

impl ScreenshotFreeAPIClient {
    /// Create a client using the production base URL (`https://api.screenshotfreeapi.com`).
    ///
    /// ```rust
    /// use screenshotfreeapi::ScreenshotFreeAPIClient;
    /// let client = ScreenshotFreeAPIClient::new("sfa_your_api_key");
    /// ```
    pub fn new(api_key: impl Into<String>) -> Self {
        Self::with_base_url(api_key, "https://api.screenshotfreeapi.com")
    }

    /// Create a client with a custom base URL.  Useful for testing against a
    /// local development server or a staging environment.
    ///
    /// ```rust
    /// use screenshotfreeapi::ScreenshotFreeAPIClient;
    /// let client = ScreenshotFreeAPIClient::with_base_url("sfa_test_key", "http://localhost:3000");
    /// ```
    pub fn with_base_url(
        api_key: impl Into<String>,
        base_url: impl Into<String>,
    ) -> Self {
        let http = Arc::new(HttpClient::new(api_key.into(), base_url.into()));

        Self {
            auth: AuthResource { http: Arc::clone(&http) },
            screenshots: ScreenshotsResource { http: Arc::clone(&http) },
            jobs: JobsResource { http: Arc::clone(&http) },
            billing: BillingResource { http: Arc::clone(&http) },
            workspaces: WorkspacesResource { http: Arc::clone(&http) },
            monitors: MonitorsResource { http: Arc::clone(&http) },
            integrations: IntegrationsResource { http: Arc::clone(&http) },
            http,
        }
    }

    // -----------------------------------------------------------------------
    // Convenience
    // -----------------------------------------------------------------------

    /// One-liner: enqueue a web screenshot for `url` and wait for it to finish.
    ///
    /// Uses [`WaitOptions::default`] (2-second polling interval, 120-second timeout).
    ///
    /// ```rust,no_run
    /// use screenshotfreeapi::ScreenshotFreeAPIClient;
    ///
    /// #[tokio::main]
    /// async fn main() -> screenshotfreeapi::Result<()> {
    ///     let client = ScreenshotFreeAPIClient::new("sfa_your_api_key");
    ///     let result = client.capture("https://github.com").await?;
    ///     println!("Screenshot URL: {}", result.screenshots[0].url);
    ///     Ok(())
    /// }
    /// ```
    pub async fn capture(&self, url: &str) -> Result<JobResult> {
        let enq = self
            .screenshots
            .capture_web(WebScreenshotOptions {
                url: url.to_string(),
                ..Default::default()
            })
            .await?;
        wait_for_job(&self.http, &enq.job_id, WaitOptions::default()).await
    }

    /// Check the API health.
    ///
    /// Corresponds to `GET /health`. Does not require authentication.
    pub async fn health(&self) -> Result<HealthResponse> {
        self.http.get("/health", None).await
    }
}