apify_rs/

lib.rs

//! Rust client for the [Apify](https://apify.com) platform API.
//!
//! Apify is a web scraping and automation cloud platform.  Users publish
//! **Actors** (serverless programs) to the Apify Store, run them with a JSON
//! input, and retrieve structured results from **Datasets** or **Key-Value
//! Stores**.
//!
//! This crate mirrors the [Apify REST API v2](https://docs.apify.com/api/v2).
//! It is organised around three primary resources:
//!
//! | Resource | What it represents | Typical workflow |
//! |----------|-------------------|------------------|
//! | [`actors`](resources::actors::ActorClient) | Scraping / automation programs | Pick an Actor and run it |
//! | [`tasks`](resources::tasks::TaskClient)   | Saved Actor configurations     | Create once, run many times |
//! | [`runs`](resources::runs::RunClient)      | Single executions              | Poll status, fetch output |
//!
//! # Disclaimer
//!
//! This project was written with the help of large language models (LLMs).
//! It is not well tested in production, so please review and test thoroughly
//! before using it for critical workloads.
//!
//! # Quick start
//!
//! ```ignore
//! use apify_rs::ApifyClient;
//!
//! let client = ApifyClient::new(std::env::var("APIFY_TOKEN")?);
//!
//! // Run a task asynchronously
//! let run = client.tasks().run("my-task-id", None).await?;
//! println!("Started run {}", run.id);
//!
//! // Poll until the run finishes
//! let finished = client.runs().wait_for_finish(&run.id, 5, 600).await?;
//! println!("Run finished with status {:?}", finished.status);
//! ```

pub mod client;
pub mod error;
pub mod instagram;
pub mod models;
pub mod resources;

pub use client::HttpClient;
pub use error::ApifyError;
pub use resources::{actors::ActorClient, runs::RunClient, tasks::TaskClient};

use reqwest::Method;

/// Root client for the Apify API.
///
/// Holds an authenticated [`HttpClient`] and exposes resource-specific
/// sub-clients ([`TaskClient`], [`RunClient`], [`ActorClient`]).
///
/// You normally construct this via [`ApifyClient::new`] or the
/// [`ApifyClientBuilder`] for more control.
///
/// # Example
/// ```ignore
/// let apify = ApifyClient::new("your-api-token");
/// let task = apify.tasks().get("my-task-id").await?;
/// let run = apify.runs().get("run-id").await?;
/// ```
#[derive(Debug, Clone)]
pub struct ApifyClient {
    http: client::HttpClient,
}

impl ApifyClient {
    /// Create a new client authenticated with an API token.
    ///
    /// The token is sent as a `Bearer` header on every request.
    pub fn new<T: Into<String>>(token: T) -> Self {
        Self {
            http: client::HttpClient::new(Some(token.into())),
        }
    }

    /// Create an unauthenticated client.
    ///
    /// Only a subset of endpoints (public Actors, public datasets) work
    /// without a token.  Most write operations will fail.
    pub fn new_anonymous() -> Self {
        Self {
            http: client::HttpClient::new(None),
        }
    }

    /// Override the base URL (default is `https://api.apify.com/v2`).
    ///
    /// Useful for integration tests against a mock server or enterprise
    /// deployments with a custom gateway.
    pub fn with_base_url(mut self, url: impl Into<String>) -> Self {
        self.http = self.http.with_base_url(url);
        self
    }

    /// Override the default HTTP timeout (60 s).
    pub fn with_timeout(mut self, timeout: std::time::Duration) -> Self {
        self.http = self.http.with_timeout(timeout);
        self
    }

    /// Return a [`TaskClient`] tied to this client's HTTP transport.
    pub fn tasks(&self) -> TaskClient<'_> {
        TaskClient::new(&self.http)
    }

    /// Return a [`RunClient`] tied to this client's HTTP transport.
    pub fn runs(&self) -> RunClient<'_> {
        RunClient::new(&self.http)
    }

    /// Return an [`ActorClient`] tied to this client's HTTP transport.
    pub fn actors(&self) -> ActorClient<'_> {
        ActorClient::new(&self.http)
    }

    /// Send an arbitrary authenticated request.
    ///
    /// Handy when you need an endpoint that is not yet wrapped by a
    /// resource client (e.g. webhooks, schedules, or new beta endpoints).
    pub async fn raw_request<T: serde::de::DeserializeOwned>(
        &self,
        method: Method,
        path: &str,
        body: Option<impl serde::Serialize>,
    ) -> Result<T, ApifyError> {
        self.http.request(method, path, body).await
    }
}

/// Fluent builder for [`ApifyClient`].
///
/// ```ignore
/// let client = ApifyClientBuilder::new()
///     .token("xxx")
///     .timeout(Duration::from_secs(30))
///     .build();
/// ```
pub struct ApifyClientBuilder {
    token: Option<String>,
    base_url: Option<String>,
    timeout: Option<std::time::Duration>,
}

impl ApifyClientBuilder {
    /// Start building with no configuration.
    pub fn new() -> Self {
        Self {
            token: None,
            base_url: None,
            timeout: None,
        }
    }

    /// Set the API token.
    pub fn token(mut self, token: impl Into<String>) -> Self {
        self.token = Some(token.into());
        self
    }

    /// Set a custom base URL.
    pub fn base_url(mut self, url: impl Into<String>) -> Self {
        self.base_url = Some(url.into());
        self
    }

    /// Set a request timeout.
    pub fn timeout(mut self, timeout: std::time::Duration) -> Self {
        self.timeout = Some(timeout);
        self
    }

    /// Consume the builder and return an [`ApifyClient`].
    pub fn build(self) -> ApifyClient {
        let mut client = ApifyClient::new(self.token.unwrap_or_default());
        if let Some(url) = self.base_url {
            client = client.with_base_url(url);
        }
        if let Some(timeout) = self.timeout {
            client = client.with_timeout(timeout);
        }
        client
    }
}

impl Default for ApifyClientBuilder {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_builder() {
        let _client = ApifyClientBuilder::new()
            .token("test-token")
            .timeout(std::time::Duration::from_secs(30))
            .build();
        // Just verify it builds without panic
    }

    #[test]
    fn test_new_anonymous() {
        let _client = ApifyClient::new_anonymous();
        // Just verify it builds without panic
    }
}