# 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:**
```rust
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:**
```rust
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:**
```rust
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.