TKTAX-Donations

A focused crate for modeling charitable transactions (donationes in Latin) with comprehensive valuation features (inflatio, depreciatio) for tax or record-keeping systems. This crate is part of the broader TKTAX ecosystem, providing calculations for fair-market values, generating donation summaries, and handling advanced date-based amortization.

Features

1. Donation Builder (Praeparatio Donatio): Constructs donation records with flexible error handling and optional Amazon integration for historical unit-price lookups.
2. Depreciation & Inflation Calculation (Depreciatio & Inflatio): Applies monthly and yearly factors to original prices using robust decimal arithmetic.
3. Estimation & Reporting: Generates precise DonationValueEstimate items, supporting multiple display formats and advanced grouped reporting.
4. Multiple Donation Sources: Handles:
   • Full Amazon purchase history lookups
   • Items with uncertain origins but approximate or exact listing references
   • Configurable donation types (books, furniture, clothing, etc.)

Quick Start

Add the dependency to your Cargo.toml:

[dependencies]
tktax-donations = "0.1.0"

Then construct and estimate donations:

use tktax_donations::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Assume we have an existing `Option<AmazonItemMap>` for previous purchases
    let builder = DonationBuilder::new(
        None, // no Amazon map for this example
        &chrono::NaiveDate::from_ymd_opt(2025, 3, 15).unwrap(),
        &DonationLocation::Goodwill { name: "uptown" },
        &chrono::NaiveDate::from_ymd_opt(2005, 1, 1).unwrap(),
    );

    let example_donation = builder.create_unknown_origin_but_item_has_amazon_listing(
        DonationType::Book,
        2,
        "Textbook donation",
        AmazonItemListing::new("Example Book", monetary_amount!(14.99), ...), // details elided
    );

    // Compute estimate
    let estimate = example_donation.estimate();
    println!("Donation estimate: {}", estimate);
    Ok(())
}

Technical Overview

• Numeric Calculations: Utilizes Decimal for monetary and factor operations, preventing floating-point inaccuracies.
• Chronological Modeling: Leverages chrono::NaiveDate for date arithmetic, ensuring day-level precision without time-zone complexity.
• Typed Error Handling: DonationBuilderError and related error structures avoid stringly-typed error messages.
• DonationValueEstimate: Encapsulates item name, quantity, original price, elapsed time, inflation factor, and depreciation adjustments into a structured, auditable record.

Example Analysis

Within an application, you can group and display donation data:

use tktax_donations::*;

fn analyze() {
    let donations = // vector of `Donation`s from your domain logic
    analyze_donations(&donations);
    // prints grouped donation info with computed totals
}

License

Dual-licensed under MIT or Apache-2.0. See LICENSE for details.

Contributing

Contributions and suggestions are welcome. Please open an issue or pull request in the GitHub repository.