esix 0.1.1

A simple wrapper of the e621 API
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

//! **You are responsible for any possible form of abuse with the e621 API.**
//!
//! Esix is an e621 API client for Rust.
//!
//! "Esix" is a mascot name of e621.
//!
//! # Example
//!
//! This example shows an example action of getting the post with the highest score that has the tag "tic_tac".
//! ```rust
//! use esix::{Esix, error::Error};
//!
//! fn main() -> Result<(), Error> {
//!     let mut client = Esix::new(
//!             "API_KEY",
//!             "USERNAME",
//!             "project_name".to_string(),
//!             "project_version".to_string()
//!     );
//!     
//!     let posts = client.list("rating:safe", 1)?;
//!     
//!     for post in posts {
//!         println!("{:?}", post);
//!     }
//!     
//!    Ok(())
//! }
//! ```

pub mod error;
pub mod post;

use crate::error::Error;
use crate::post::{Post, Posts};
use std::fmt::Display;

/// The client that will interact with the e621 API.
pub struct Esix {
    pub username: String,
    pub key: String,
    useragent: String,
}

impl Esix {
    /// The base URL of e621 and its API.
    const URL: &'static str = "https://e621.net";

    /// Creates a new instance of the Esix client.
    ///
    /// The client requires the project name and version to be passed in order to
    /// properly identify itself to the e621 API.
    ///
    /// # Arguments
    ///
    /// * `key` - The API key to use for authentication.
    /// * `username` - The username of the e621 account.
    /// * `project_name` - The name of the project using the client.
    /// * `project_version` - The version of the project using the client.
    ///
    /// # Returns
    ///
    /// A new instance of the Esix client.
    pub fn new<S: AsRef<str> + Display>(
        key: S,
        username: S,
        project_name: String,
        project_version: String,
    ) -> Self {
        let useragent = format!("{project_name}/{project_version} (by {username} on e621)");

        Esix {
            username: username.to_string(),
            key: key.as_ref().to_string(),
            useragent,
        }
    }

    /// Lists posts from e621 based on the tags provided delimited with spaces.
    ///
    /// # Arguments
    ///
    /// * `tags` - The tags to search for.
    /// * `limit` - The maximum number of posts to return.
    ///
    /// # Returns
    ///
    /// A vector of posts that match the tags provided.
    pub fn list(&mut self, tags: impl Into<String>, limit: usize) -> Result<Vec<Post>, Error> {
        let reqwest = reqwest::blocking::Client::new();

        let tags = tags.into().replace(" ", "+");

        let url = format!("{}/posts.json", Self::URL);

        let params: Vec<(&str, String)> = vec![
            ("login", self.username.clone()),
            ("api_key", self.key.clone()),
            ("tags", tags),
            ("limit", limit.to_string()),
        ];

        let response = reqwest
            .get(url)
            .query(&params)
            .header("User-Agent", self.useragent.clone())
            .send();

        match response {
            Ok(response) => match response.json::<Posts>() {
                Ok(posts) => Ok(posts.posts),
                Err(e) => Err(Error::from(&e.to_string())),
            },
            Err(e) => Err(Error::from(&e.to_string())),
        }
    }
}