Update documentation

Signed-off-by: trivernis <trivernis@protonmail.com>

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "hydrus-api"
-version = "0.2.0"
+version = "0.3.0"
 authors = ["trivernis <trivernis@protonmail.com>"]
 edition = "2018"
 license = "Apache-2.0"

README.md

@@ -1,9 +1,51 @@
-# Hydrus Rust API
+<h1 align="center">
+Hydrus Rust API
+</h1>
+<p align="center">
+    <a href="https://crates.io/crates/hydrus-api">
+        <img src="https://img.shields.io/crates/v/hydrus-api?style=for-the-badge">
+    </a>
+    <a href="https://docs.rs/hydrus-api">
+        <img src="https://img.shields.io/docsrs/hydrus-api?style=for-the-badge">
+    </a>
+</p>
+
 
 This is a WIP Rust Wrapper for the Hydrus Client API. 
 The official API documentation can be found [here](https://hydrusnetwork.github.io/hydrus/help/client_api.html).
 
-## Example
+## Example with Wrapper
+
+```rust
+use std::env;
+use hydrus_api::api_core::searching_and_fetching_files::FileSearchLocation;
+use hydrus_api::wrapper::tag::Tag;
+use hydrus_api::wrapper::service::ServiceName;
+use hydrus_api::wrapper::hydrus_file::FileStatus;
+use hydrus_api::wrapper::page::PageIdentifier;
+
+#[tokio::main]
+async fn main() {
+    let hydrus_url = env::var("HYDRUS_URL").unwrap();
+    let access_key = env::var("HYDRUS_ACCESS_KEY").unwrap();
+    
+    let hydrus = Hydrus::new(Client::new(hydrus_url, access_key));
+    let files = hydrus.search(FileSearchLocation::Archive,vec![Tag::from("character:megumin")]).await.unwrap();
+
+    for mut file in files {
+        file.add_tags(ServiceName::my_tags(), vec![Tag::from("ark mage")]).await.unwrap();
+    }
+
+    let url = hydrus.import()
+        .url("https://www.pixiv.net/member_illust.php?illust_id=83406361&mode=medium")
+        .page(PageIdentifier::name("My Import Page"))
+        .add_additional_tag(ServiceName::my_tags(), Tag::from("character:megumin"))
+        .show_page(true)
+        .run().await.unwrap();
+}
+```
+
+## Example with Client
 
 ```rust
 use hydrus_api::Client;
@@ -15,7 +57,7 @@ async fn main() {
     Client::new(
         env::var("HYDRUS_URL").unwrap(),
         env::var("HYDRUS_ACCESS_KEY").unwrap(),
-    ).unwrap();
+    );
     // let's first import a file
     let hash = client.add_file("/path/to/my/file").await.unwrap().hash;
     

src/api_core/access_management.rs

@@ -1,5 +1,5 @@
-use crate::endpoints::common::BasicServiceInfo;
+use crate::api_core::common::BasicServiceInfo;
-use crate::endpoints::Endpoint;
+use crate::api_core::Endpoint;
 use std::collections::HashMap;
 
 pub static SERVICE_TYPE_LOCAL_TAGS: &str = "local_tags";

src/api_core/adding_files.rs

@@ -1,5 +1,5 @@
-use crate::endpoints::common::BasicHashList;
+use crate::api_core::common::BasicHashList;
-use crate::endpoints::Endpoint;
+use crate::api_core::Endpoint;
 
 pub static STATUS_IMPORT_SUCCESS: u8 = 1;
 pub static STATUS_IMPORT_ALREADY_EXISTS: u8 = 2;

src/api_core/adding_tags.rs

@@ -1,4 +1,4 @@
-use crate::endpoints::Endpoint;
+use crate::api_core::Endpoint;
 use std::collections::HashMap;
 
 #[derive(Debug, Clone, Deserialize)]

src/api_core/adding_urls.rs

@@ -1,4 +1,4 @@
-use crate::endpoints::Endpoint;
+use crate::api_core::Endpoint;
 use serde::Serialize;
 use std::collections::HashMap;
 
@@ -72,7 +72,7 @@ pub struct AddUrlRequest {
 ///
 /// Example:
 /// ```
-/// use hydrus_api::endpoints::adding_urls::AddUrlRequestBuilder;
+/// use hydrus_api::api_core::adding_urls::AddUrlRequestBuilder;
 ///
 /// let request = AddUrlRequestBuilder::default()
 ///     .url("https://www.pixiv.net/member_illust.php?illust_id=83406361&mode=medium")

src/api_core/client.rs

@@ -1,22 +1,22 @@
-use crate::endpoints::access_management::{
+use crate::api_core::access_management::{
     ApiVersion, ApiVersionResponse, GetServices, GetServicesResponse, SessionKey,
     SessionKeyResponse, VerifyAccessKey, VerifyAccessKeyResponse,
 };
-use crate::endpoints::adding_files::{
+use crate::api_core::adding_files::{
     AddFile, AddFileRequest, AddFileResponse, ArchiveFiles, ArchiveFilesRequest, DeleteFiles,
     DeleteFilesRequest, UnarchiveFiles, UnarchiveFilesRequest, UndeleteFiles, UndeleteFilesRequest,
 };
-use crate::endpoints::adding_tags::{AddTags, AddTagsRequest, CleanTags, CleanTagsResponse};
+use crate::api_core::adding_tags::{AddTags, AddTagsRequest, CleanTags, CleanTagsResponse};
-use crate::endpoints::adding_urls::{
+use crate::api_core::adding_urls::{
     AddUrl, AddUrlRequest, AddUrlResponse, AssociateUrl, AssociateUrlRequest, GetUrlFiles,
     GetUrlFilesResponse, GetUrlInfo, GetUrlInfoResponse,
 };
-use crate::endpoints::common::{FileIdentifier, FileMetadataInfo, FileRecord};
+use crate::api_core::common::{FileIdentifier, FileMetadataInfo, FileRecord};
-use crate::endpoints::searching_and_fetching_files::{
+use crate::api_core::searching_and_fetching_files::{
     FileMetadata, FileMetadataResponse, FileSearchLocation, GetFile, SearchFiles,
     SearchFilesResponse,
 };
-use crate::endpoints::Endpoint;
+use crate::api_core::Endpoint;
 use crate::error::{Error, Result};
 use crate::utils::{number_list_to_json_array, string_list_to_json_array};
 use reqwest::Response;
@@ -26,6 +26,8 @@ use serde::Serialize;
 static ACCESS_KEY_HEADER: &str = "Hydrus-Client-API-Access-Key";
 
 #[derive(Clone)]
+/// A low level Client for the hydrus API. It provides basic abstraction
+/// over the REST api.
 pub struct Client {
     inner: reqwest::Client,
     base_url: String,
@@ -34,12 +36,12 @@ pub struct Client {
 
 impl Client {
     /// Creates a new client to start requests against the hydrus api.
-    pub fn new<S: AsRef<str>>(url: S, access_key: S) -> Result<Self> {
+    pub fn new<S: AsRef<str>>(url: S, access_key: S) -> Self {
-        Ok(Self {
+        Self {
             inner: reqwest::Client::new(),
             access_key: access_key.as_ref().to_string(),
             base_url: url.as_ref().to_string(),
-        })
+        }
     }
 
     /// Starts a get request to the path

src/api_core/mod.rs

@@ -5,6 +5,7 @@ pub mod access_management;
 pub mod adding_files;
 pub mod adding_tags;
 pub mod adding_urls;
+pub mod client;
 pub mod common;
 pub mod searching_and_fetching_files;
 

src/api_core/searching_and_fetching_files.rs

@@ -1,5 +1,5 @@
-use crate::endpoints::common::FileMetadataInfo;
+use crate::api_core::common::FileMetadataInfo;
-use crate::endpoints::Endpoint;
+use crate::api_core::Endpoint;
 
 #[derive(Debug, Clone, Deserialize)]
 pub struct SearchFilesResponse {

src/error.rs

@@ -1,4 +1,4 @@
-use crate::endpoints::common::FileIdentifier;
+use crate::api_core::common::FileIdentifier;
 use std::error::Error as StdError;
 use std::fmt;
 

src/lib.rs

@@ -3,10 +3,41 @@
 //! token that can be retrieved in the hydrus client from the *review services* dialog.
 //! Different actions require different permissions, you can read about it in the [official docs](https://hydrusnetwork.github.io/hydrus/help/client_api.html).
 //!
-//! ## Usage Example
+//! ## Hydrus Usage Example
+//!
+//! ```
+//! # use hydrus_api::{Hydrus, Client};
+//! use std::env;
+//! use hydrus_api::api_core::searching_and_fetching_files::FileSearchLocation;
+//! use hydrus_api::wrapper::tag::Tag;
+//! use hydrus_api::wrapper::service::ServiceName;
+//! use hydrus_api::wrapper::hydrus_file::FileStatus;
+//! use hydrus_api::wrapper::page::PageIdentifier;
+//!
+//! # #[tokio::test]
+//! # async fn doctest() {
+//! let hydrus_url = env::var("HYDRUS_URL").unwrap();
+//! let access_key = env::var("HYDRUS_ACCESS_KEY").unwrap();
+//! let hydrus = Hydrus::new(Client::new(hydrus_url, access_key));
+//! let files = hydrus.search(FileSearchLocation::Archive,vec![Tag::from("character:megumin")]).await.unwrap();
+//!
+//! for mut file in files {
+//!     file.add_tags(ServiceName::my_tags(), vec![Tag::from("ark mage")]).await.unwrap();
+//! }
+//!
+//! let url = hydrus.import()
+//!     .url("https://www.pixiv.net/member_illust.php?illust_id=83406361&mode=medium")
+//!     .page(PageIdentifier::name("My Import Page"))
+//!     .add_additional_tag(ServiceName::my_tags(), Tag::from("character:megumin"))
+//!     .show_page(true)
+//!     .run().await.unwrap();
+//! # }
+//! ```
+//!
+//! ## Client Usage Example
 //! ```
 //! use hydrus_api::Client;
-//! use hydrus_api::endpoints::adding_tags::{AddTagsRequestBuilder, TagAction};
+//! use hydrus_api::api_core::adding_tags::{AddTagsRequestBuilder, TagAction};
 //! use std::env;
 //! # #[tokio::test]
 //! # async fn doctest() {
@@ -14,7 +45,7 @@
 //! Client::new(
 //!     env::var("HYDRUS_URL").unwrap(),
 //!     env::var("HYDRUS_ACCESS_KEY").unwrap(),
-//! ).unwrap();
+//! );
 //! // let's first import a file
 //! let hash = client.add_file("/path/to/my/file").await.unwrap().hash;
 //!
@@ -34,12 +65,10 @@
 #[macro_use]
 extern crate serde;
 
-pub mod client;
+pub use api_core::client::Client;
-pub mod endpoints;
+pub use wrapper::hydrus::Hydrus;
+
+pub mod api_core;
 pub mod error;
-mod models;
 pub(crate) mod utils;
-
+pub mod wrapper;
-pub use client::Client;
-pub use models::hydrus::Hydrus;
-pub use models::*;

src/utils.rs

@@ -1,4 +1,4 @@
-use crate::models::tag::Tag;
+use crate::wrapper::tag::Tag;
 
 pub fn string_list_to_json_array(l: Vec<String>) -> String {
     format!("[\"{}\"]", l.join("\",\""))

src/wrapper/builders/import_builder.rs

@@ -1,12 +1,12 @@
-use crate::endpoints::adding_files::{STATUS_IMPORT_FAILED, STATUS_IMPORT_VETOED};
+use crate::api_core::adding_files::{STATUS_IMPORT_FAILED, STATUS_IMPORT_VETOED};
-use crate::endpoints::adding_urls::AddUrlRequestBuilder;
+use crate::api_core::adding_urls::AddUrlRequestBuilder;
 use crate::error::{Error, Result};
-use crate::hydrus_file::HydrusFile;
-use crate::models::url::Url;
-use crate::page::PageIdentifier;
-use crate::service::ServiceName;
-use crate::tag::Tag;
 use crate::utils::tag_list_to_string_list;
+use crate::wrapper::hydrus_file::HydrusFile;
+use crate::wrapper::page::PageIdentifier;
+use crate::wrapper::service::ServiceName;
+use crate::wrapper::tag::Tag;
+use crate::wrapper::url::Url;
 use crate::Client;
 use std::collections::HashMap;
 use std::io::Read;

src/wrapper/builders/tagging_builder.rs

@@ -1,7 +1,7 @@
-use crate::endpoints::adding_tags::{AddTagsRequestBuilder, TagAction};
+use crate::api_core::adding_tags::{AddTagsRequestBuilder, TagAction};
 use crate::error::Result;
-use crate::models::tag::Tag;
+use crate::wrapper::service::ServiceName;
-use crate::service::ServiceName;
+use crate::wrapper::tag::Tag;
 use crate::Client;
 use std::collections::HashMap;
 

src/wrapper/hydrus.rs

@@ -1,16 +1,18 @@
-use crate::builders::import_builder::ImportBuilder;
+use crate::api_core::common::FileIdentifier;
-use crate::builders::tagging_builder::TaggingBuilder;
+use crate::api_core::searching_and_fetching_files::FileSearchLocation;
-use crate::endpoints::common::FileIdentifier;
-use crate::endpoints::searching_and_fetching_files::FileSearchLocation;
 use crate::error::Result;
-use crate::hydrus_file::HydrusFile;
-use crate::models::url::Url;
-use crate::models::version::Version;
-use crate::service::Services;
-use crate::tag::Tag;
 use crate::utils::tag_list_to_string_list;
+use crate::wrapper::builders::import_builder::ImportBuilder;
+use crate::wrapper::builders::tagging_builder::TaggingBuilder;
+use crate::wrapper::hydrus_file::HydrusFile;
+use crate::wrapper::service::Services;
+use crate::wrapper::tag::Tag;
+use crate::wrapper::url::Url;
+use crate::wrapper::version::Version;
 use crate::Client;
 
+/// A high level wrapper for the hydrus API for easier management of files, tags
+/// urls etc.
 pub struct Hydrus {
     client: Client,
 }

src/wrapper/hydrus_file.rs

@@ -1,9 +1,9 @@
-use crate::endpoints::adding_tags::{AddTagsRequestBuilder, TagAction};
+use crate::api_core::adding_tags::{AddTagsRequestBuilder, TagAction};
-use crate::endpoints::common::{FileIdentifier, FileMetadataInfo, FileRecord};
+use crate::api_core::common::{FileIdentifier, FileMetadataInfo, FileRecord};
 use crate::error::{Error, Result};
-use crate::service::ServiceName;
-use crate::tag::Tag;
 use crate::utils::tag_list_to_string_list;
+use crate::wrapper::service::ServiceName;
+use crate::wrapper::tag::Tag;
 use crate::Client;
 use mime::Mime;
 use std::collections::HashMap;

src/wrapper/service.rs

@@ -1,5 +1,5 @@
-use crate::endpoints::access_management::GetServicesResponse;
+use crate::api_core::access_management::GetServicesResponse;
-use crate::endpoints::access_management::{
+use crate::api_core::access_management::{
     SERVICE_TYPE_ALL_KNOWN_FILES, SERVICE_TYPE_ALL_KNOWN_TAGS, SERVICE_TYPE_ALL_LOCAL_FILES,
     SERVICE_TYPE_FILE_REPOSITORIES, SERVICE_TYPE_LOCAL_FILES, SERVICE_TYPE_LOCAL_TAGS,
     SERVICE_TYPE_TAG_REPOSITORIES, SERVICE_TYPE_TRASH,

src/wrapper/url.rs

@@ -1,9 +1,9 @@
-use crate::builders::import_builder::UrlImportBuilder;
+use crate::api_core::adding_urls::{
-use crate::endpoints::adding_urls::{
     URL_TYPE_FILE, URL_TYPE_GALLERY, URL_TYPE_POST, URL_TYPE_WATCHABLE,
 };
 use crate::error::Result;
-use crate::hydrus_file::HydrusFile;
+use crate::wrapper::builders::import_builder::UrlImportBuilder;
+use crate::wrapper::hydrus_file::HydrusFile;
 use crate::Client;
 
 #[derive(Clone, Debug, PartialOrd, PartialEq)]

tests/client/test_adding_tags.rs

@@ -1,5 +1,5 @@
 use super::super::common;
-use hydrus_api::endpoints::adding_tags::{AddTagsRequestBuilder, TagAction};
+use hydrus_api::api_core::adding_tags::{AddTagsRequestBuilder, TagAction};
 
 #[tokio::test]
 async fn it_cleans_tags() {

tests/client/test_adding_urls.rs

@@ -1,5 +1,5 @@
 use super::super::common;
-use hydrus_api::endpoints::adding_urls::{AddUrlRequestBuilder, URL_TYPE_POST};
+use hydrus_api::api_core::adding_urls::{AddUrlRequestBuilder, URL_TYPE_POST};
 
 #[tokio::test]
 async fn it_returns_files_for_an_url() {

tests/client/test_searching_and_fetching_files.rs

@@ -1,6 +1,6 @@
 use super::super::common;
-use hydrus_api::endpoints::common::FileIdentifier;
+use hydrus_api::api_core::common::FileIdentifier;
-use hydrus_api::endpoints::searching_and_fetching_files::FileSearchLocation;
+use hydrus_api::api_core::searching_and_fetching_files::FileSearchLocation;
 
 #[tokio::test]
 async fn is_searches_files() {

tests/common.rs

@@ -1,4 +1,4 @@
-use hydrus_api::client::Client;
+use hydrus_api::api_core::client::Client;
 use hydrus_api::Hydrus;
 use log::LevelFilter;
 use std::env;
@@ -21,7 +21,6 @@ pub fn get_client() -> Client {
         env::var("HYDRUS_URL").unwrap(),
         env::var("HYDRUS_ACCESS_KEY").unwrap(),
     )
-    .unwrap()
 }
 
 pub fn get_hydrus() -> Hydrus {

tests/wrapper/test_files.rs

@@ -1,8 +1,8 @@
 use super::super::common;
-use hydrus_api::endpoints::adding_tags::TagAction;
+use hydrus_api::api_core::adding_tags::TagAction;
-use hydrus_api::endpoints::common::FileIdentifier;
+use hydrus_api::api_core::common::FileIdentifier;
-use hydrus_api::hydrus_file::HydrusFile;
+use hydrus_api::wrapper::hydrus_file::HydrusFile;
-use hydrus_api::service::ServiceName;
+use hydrus_api::wrapper::service::ServiceName;
 
 async fn get_file() -> HydrusFile {
     let hydrus = common::get_hydrus();

tests/wrapper/test_hydrus.rs

@@ -1,8 +1,8 @@
 use super::super::common;
-use hydrus_api::endpoints::adding_tags::TagAction;
+use hydrus_api::api_core::adding_tags::TagAction;
-use hydrus_api::endpoints::searching_and_fetching_files::FileSearchLocation;
+use hydrus_api::api_core::searching_and_fetching_files::FileSearchLocation;
-use hydrus_api::service::{ServiceName, ServiceType};
+use hydrus_api::wrapper::service::{ServiceName, ServiceType};
-use hydrus_api::url::UrlType;
+use hydrus_api::wrapper::url::UrlType;
 
 #[tokio::test]
 async fn it_retrieves_version_info() {

tests/wrapper/test_import.rs

@@ -1,9 +1,9 @@
 use super::super::common;
-use hydrus_api::builders::import_builder::FileImport;
+use hydrus_api::wrapper::builders::import_builder::FileImport;
-use hydrus_api::page::PageIdentifier;
+use hydrus_api::wrapper::page::PageIdentifier;
-use hydrus_api::service::ServiceName;
+use hydrus_api::wrapper::service::ServiceName;
-use hydrus_api::tag::Tag;
+use hydrus_api::wrapper::tag::Tag;
-use hydrus_api::url::UrlType;
+use hydrus_api::wrapper::url::UrlType;
 
 #[tokio::test]
 async fn it_imports_file_paths() {

tests/wrapper/test_url.rs

@@ -1,8 +1,8 @@
 use super::super::common;
-use hydrus_api::page::PageIdentifier;
+use hydrus_api::wrapper::page::PageIdentifier;
-use hydrus_api::service::ServiceName;
+use hydrus_api::wrapper::service::ServiceName;
-use hydrus_api::tag::Tag;
+use hydrus_api::wrapper::tag::Tag;
-use hydrus_api::url::Url;
+use hydrus_api::wrapper::url::Url;
 
 async fn get_url() -> Url {
     let hydrus = common::get_hydrus();