Skip to main content

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;