modrinth_wrapped/lib.rs
1//! An async rust wrapper for the public Modrinth API (v2).
2//! Does not provide any functionality for endpoints requiring Authorization.
3//!
4//! ## Features
5//! - `rate-limited`: (default) Enables per-client rate limiting.
6//! Note: uses [Tokio](https://tokio.rs) to rate limit requests. If you cannot or don't want to use Tokio, you can disable this feature and implement a custom rate limiter. See the [Modrinth API Docs](https://docs.modrinth.com/api/#ratelimits) for more information.
7//! - `tokio-io`: (default) Enables async functions for downloading version files.
8//! If you cannot or don't want to use Tokio, you can disable this feature and implement a custom downloader using `ModrinthClient.download_file_from_hash_response`.
9//! - `parse-dates`: (default) Enables parsing ISO-8601 date fields into `chrono::DateTime`.
10//! - `not-found-error`: (default) Enables treating HTTP 404 responses as a dedicated `ModrinthError::NotFound` variant
11//! - `loader-enums`: Enables the `Loader` enum, which will be used to deserialize/serialize loader fields instead of raw strings.
12//! - `donation-platform-enums`: Enables the `DonationPlatform` enum, which will be used to deserialize donation platform fields instead of raw strings.
13//!
14//! # Installation
15//! Add the following to your `Cargo.toml` file:
16//! ```toml
17//! [dependencies]
18//! modrinth-wrapped = "0.1"
19//! tokio = { version = "1.53.1", features = ["full"] } # at minimum you will need "macros" and "rt-multi-thread"
20//! ```
21//!
22//! # Examples
23//! These examples use Tokio, but you can theoretically use any async runtime you'd like.
24//!
25//! ### Fetch a single project by its ID or slug:
26//! ```rust
27//! use modrinth_wrapped::{ModrinthClient, ModrinthError};
28//!
29//! #[tokio::main]
30//! async fn main() -> Result<(), ModrinthError> {
31//! let client = ModrinthClient::new()?;
32//!
33//! let project = client.get_project("fabric-api").await?;
34//! println!("project: {:#?}", project.title);
35//!
36//! Ok(())
37//! }
38//! ```
39//!
40//! ### Search for projects:
41//! ```rust
42//! use modrinth_wrapped::{ModrinthClient, SearchQuery, ModrinthError};
43//!
44//! #[tokio::main]
45//! async fn main() -> Result<(), ModrinthError> {
46//! let client = ModrinthClient::new()?;
47//!
48//! let query = SearchQuery::new()
49//! .with_query("fabric")
50//! .with_limit(5); // default limit is 10, max is 100
51//!
52//! let results = client.search(&query).await?;
53//! for hit in results.hits {
54//! println!("hit: {}", hit.title);
55//! }
56//!
57//! Ok(())
58//! }
59//! ```
60//!
61//! ### Download a version file:
62//! For this example, the latest `1.20.1` version for `fabric-api` is being downloaded.
63//! For displaying progress as it is downloaded, see `download_file_hash_to_async_writer_with_progress`.
64//! ```ignore
65//! use modrinth_wrapped::{ModrinthClient, ModrinthError, VersionHashAlgorithm, VersionQuery};
66//!
67//! #[tokio::main]
68//! async fn main() -> Result<(), ModrinthError> {
69//! let client = ModrinthClient::new()?;
70//!
71//! let query = VersionQuery::new().with_game_versions(vec!["1.20.1"]);
72//! let versions = client.list_versions_for("fabric-api", Some(&query)).await?;
73//! let latest_file = versions
74//! .first()
75//! .and_then(|version| version.files.first())
76//! .unwrap();
77//!
78//! let mut file = tokio::fs::File::create(&latest_file.filename)
79//! .await
80//! .map_err(ModrinthError::IoError)?;
81//!
82//! let bytes_written = client
83//! .download_file_from_hash_to_async_writer(
84//! &latest_file.hashes.sha1,
85//! VersionHashAlgorithm::Sha1,
86//! None,
87//! &mut file,
88//! )
89//! .await?;
90//!
91//! println!("downloaded {bytes_written} bytes");
92//!
93//! Ok(())
94//! }
95//! ```
96
97pub mod client;
98pub mod endpoints;
99pub mod error;
100pub mod models;
101pub mod types;
102
103pub use client::ModrinthClient;
104pub use error::ModrinthError;
105#[cfg(feature = "donation-platform-enums")]
106pub use models::donation_platform::DonationPlatform;
107pub use models::environment::Environment;
108#[cfg(feature = "loader-enums")]
109pub use models::loader::Loader;
110pub use models::project::Project;
111pub use models::search_result::SearchResult;
112pub use models::version::{Dependency, DependencyType, Version, VersionStatus, VersionType};
113pub use models::version_file::{VersionFile, VersionHashAlgorithm};
114pub use types::download_progress::DownloadProgress;
115pub use types::forge_updates_type::ForgeUpdatesQueryType;
116pub use types::search_query::{Facet, FacetField, FacetOperation, SearchQuery, Sort};
117pub use types::version_hash_query::VersionHashQuery;
118pub use types::version_query::VersionQuery;