`crate-activity`

crate-activity is a Rust-based tool for analyzing the usage metrics of your published crates on crates.io. It provides insights such as total downloads, average daily downloads, peak daily downloads, and download trends over time. Additionally, it highlights the most downloaded crates over recent intervals and enables caching for efficient data retrieval.

Features

Comprehensive Usage Analysis:
- Aggregates and summarizes crate downloads by day.
- Calculates total downloads, average daily downloads, and peak daily downloads.
- Identifies trends in download activity: Increasing, Decreasing, or Stable.
Multi-Day Activity Summary:
- Reports download statistics for individual crates.
- Highlights top crates for the last 1-day and 3-day intervals.
- Provides overall statistics such as median daily downloads and per-crate averages.
Efficient Data Handling:
- Fetches data from the crates.io API.
- Supports caching of API responses to reduce redundant requests.
Customizable Configuration:
- Reads the list of crates and user agent settings from a configuration directory (~/.published-crates by default).
- Automatically creates necessary configuration files if they don't exist.

Installation

Add crate-activity to your Rust project using Cargo:

cargo install crate-activity

Alternatively, clone the repository and run it directly:

git clone https://github.com/your-username/crate-activity.git
cd crate-activity
cargo build --release
./target/release/crate-activity

Usage

Run crate-activity to analyze your crate usage data:

crate-activity

By default, the tool looks for a configuration directory at ~/.published-crates. It expects the following files:

crate_list.txt: A list of crate names to analyze, one per line.
user_agent.txt: A custom user agent string for API requests.

If these files are missing, the tool will generate defaults.

Output Example

Crate Activity Summary:
  Date Interval (Last 1 Day):  2024-12-08
  Date Interval (Last 3 Days): 2024-12-06

  Total Downloads:                   15,000
  Average Daily Downloads:           5,000.00
  Average Daily Downloads per Crate: 2,500.00
  Median Daily Downloads:            3,000
  Crates Analyzed:                   6

Top Crates (Last 1 Day):
  serde                          3,500 downloads
  tokio                          3,000 downloads

Top Crates (Last 3 Days):
  serde                          8,500 downloads
  tokio                          6,000 downloads

Configuration

Directory Structure

The configuration directory is located at ~/.published-crates by default. It should have the following structure:

.published-crates/
├── cache/
├── crate_list.txt
└── user_agent.txt

Default Configuration

If the directory or files do not exist, they will be created with default values:

crate_list.txt:
```
serde
tokio
```

user_agent.txt:

crate-activity-bot/1.0 (contact@example.com)

Cache

Cached responses are stored in the cache/ subdirectory and named using the pattern <crate_name>_<date>.json. This allows reusing data from the same day without re-fetching it from the API.

Development

Clone the repository and explore the code:

git clone https://github.com/your-username/crate-activity.git
cd crate-activity

The main entry point is src/main.rs. Core functionality is modularized for ease of maintenance and extension.

Testing

Run the tests to ensure functionality:

cargo test

Contributing

Contributions are welcome! If you encounter bugs or have feature suggestions, feel free to open an issue or submit a pull request.

License

crate-activity is licensed under the MIT License.

Acknowledgments

Built with Rust.
Inspired by the need to efficiently monitor crate usage on crates.io.

Start monitoring your crate usage today with crate-activity! 🚀

crate-activity 0.1.0

crate-activity