tktax-amazon

High-performance crate for deserializing Amazon CSV exports, unifying multi-epoch transaction data, and generating tabular outputs for taxation workflows. Provides idiomatic Rust abstractions for Amazon transactions, macros to instantiate medical/business purchases, and configurable options to merge distinct CSV epochs into consolidated records.

Overview

1. CSV Parsing (Latin: comma separata tabula):

   • parse_amazon_csv accepts in-memory byte buffers and deserializes them into strongly-typed Rust structures implementing the AmazonTxn trait.
   • Resilient to flexible CSV terminators, embedded quotes, and partial escaping sequences.

2. Transaction Fusion (Greek: συναρμολόγηση):

   • fuse_amazon_transactions_from_two_epochs merges distinct epochs (e.g., AmazonTx1 vs. AmazonTx2) into a uniform AmazonTx vector.
   • Simplifies archival or further analytic workflows.

3. Configurable CSV Aggregation:

   • maybe_fuse_amazon_csv_from_two_epochs demonstrates orchestrating both epochs’ CSV data into a single CSV output, contingent upon a user-supplied AmazonConfig.

4. Macros for Medical/Business Purchases:

   • amazon_medical! & amazon_business! reduce boilerplate when constructing domain-specific line items, integrating cost, quantity, and date fields into robust builder patterns.

5. Auxiliary Constructs:

   • AmazonItemListing and AmazonItemMap facilitate indexing or referencing items by known identifiers.
   • IndexedAmazonTx ensures each record includes a short symbolic code plus standard transaction metadata.

6. Error Handling:

   • Implements AmazonError (IoError, CsvError, and ChronoParseError) to capture explicit runtime anomalies.
   • Encourages safe error propagation without unwinding the runtime or resorting to stringly-typed errors.

Usage

Parsing and Fusing CSVs:

use tktax_amazon::{parse_amazon_csv, fuse_amazon_transactions_from_two_epochs, AmazonTx1, AmazonTx2};

fn main() -> Result<(), tktax_amazon::AmazonError> {
    // Ingest epoch1 CSV as AmazonTx1
    let epoch1_contents = std::fs::read("path/to/epoch1.csv")?;
    let epoch2_contents = std::fs::read("path/to/epoch2.csv")?;

    let epoch1_txns = parse_amazon_csv::<AmazonTx1>(&epoch1_contents)?;
    let epoch2_txns = parse_amazon_csv::<AmazonTx2>(&epoch2_contents)?;

    let consolidated = fuse_amazon_transactions_from_two_epochs(epoch1_txns, epoch2_txns);

    // Now operate on the unified `AmazonTx` vector or write it to a CSV
    tktax_amazon::write_to_csv(consolidated, "consolidated.csv")?;
    Ok(())
}

On-the-Fly Example Items:

use chrono::NaiveDate;
use tktax_amazon::amazon_medical;
use rust_decimal::Decimal;

// Construct a one-off medical purchase
let med_purchase = amazon_medical![1, "stethoscope", 79.95, NaiveDate::from_ymd(2025, 7, 15)];
println!("{:?}", med_purchase);

Configuration-Based Fusion:

let config = tktax_amazon::AmazonConfig {
    txfile: "output.csv".into(),
    epoch1file: "epoch1.csv".into(),
    epoch2file: "epoch2.csv".into(),
};

match tktax_amazon::maybe_fuse_amazon_csv_from_two_epochs(&config) {
    Ok(_) => println!("Successfully fused Amazon CSV data."),
    Err(err) => eprintln!("Encountered error: {:?}", err),
}

Features and Extensions

• Multi-Epoch Compatibility: Automatic unification of different Amazon CSV layouts.
• Macro-Based Builders: Streamlined creation of typed domain items for specialized expenses.
• Decoupled Category Logic: LineItem<TxCat> trait obtains a user-defined category enumeration for accounting segregation.
• Chrono & Decimal Integration: Leverages NaiveDate for time fields, Decimal for quantity, and custom MonetaryAmount for robust currency handling.

License

Distributed under the MIT License.