The Royalty Reconciliation Tool

Build a Node.js CLI tool for reconciling music royalty data across multiple
distributors. The tool should be a structured project, not a single file.

PROJECT STRUCTURE:
royalty-tool/
  package.json
  src/
    cli.js           (entry point, argument parsing)
    parsers/
      distrokid.js   (DistroKid CSV parser)
      tunecore.js    (TuneCore CSV parser)
      cdbaby.js      (CD Baby CSV parser)
      auto-detect.js (header-pattern-based format detection)
    reconciler.js    (cross-platform matching and comparison)
    reporter.js      (HTML report generation)
    sample-data.js   (generates realistic test CSVs)
  templates/
    report.html      (Handlebars-style HTML template for the summary report)

REQUIREMENTS:

1. CLI INTERFACE (src/cli.js)
   - Usage: node src/cli.js [options] <csv-files...>
   - Accept multiple CSV file paths as arguments
   - --output or -o: output directory for the report (default: ./royalty-report)
   - --period or -p: reporting period label (e.g., "Q4 2025")
   - --generate-sample: generate sample CSV files instead of reconciling
   - Use csv-parser npm package for CSV reading

2. AUTO-DETECTION (src/parsers/auto-detect.js)
   - Read the first row (headers) of each CSV
   - DistroKid headers include: "Reporting Date", "Sale Period", "Store",
     "Quantity", "Song/Album", "Country of Sale", "Earnings (USD)"
   - TuneCore headers include: "Posted Date", "Sale/Return", "Platform",
     "Quantity", "Release Title", "Song Title", "Country", "Total Earned"
   - CD Baby headers include: "Date", "Distributor", "Subtotal (USD)",
     "Quantity", "Artist", "Title", "UPC"
   - Match header patterns (case-insensitive, partial match) to select the
     right parser
   - If no format is recognized, print an error with the detected headers so
     the user can report it

3. PARSERS (src/parsers/*.js)
   - Each parser normalizes CSV rows to a common schema:
     {
       track_title: string,       // normalized track name
       platform: string,          // "Spotify", "Apple Music", etc.
       streams: number,           // play/download count
       revenue: number,           // USD amount
       territory: string,         // country code or name
       period: string,            // YYYY-MM format
       source: string             // "distrokid", "tunecore", "cdbaby"
     }
   - Normalize track titles: trim whitespace, collapse multiple spaces,
     strip common suffixes like "(Original Mix)", "(Radio Edit)"
   - Normalize platform names: map variants to canonical names
     ("Spotify" not "spotify" or "Spotify Premium")
   - Parse revenue strings: strip currency symbols, handle commas, convert
     to float
   - Parse dates to YYYY-MM format regardless of input format

4. RECONCILER (src/reconciler.js)
   - Group normalized records by track_title + platform + period
   - For each group, compare across sources:
     - Stream count difference (absolute and percentage)
     - Revenue difference (absolute and percentage)
   - Flag discrepancies where:
     - Revenue is >10% below expected (based on known per-stream rates)
     - Stream counts differ >15% between distributors for the same platform
     - A track appears in one distributor but not another
   - Known per-stream rates (approximate, for flagging only):
     - Spotify: $0.003-0.005 per stream
     - Apple Music: $0.007-0.01 per stream
     - Amazon Music: $0.003-0.005 per stream
     - YouTube Music: $0.002-0.004 per stream
     - Tidal: $0.008-0.013 per stream
   - Calculate expected revenue from stream counts and flag if actual
     revenue falls below the low end of the range

5. REPORTER (src/reporter.js)
   - Generate an HTML report with these sections:
     a. Summary: total revenue per platform, total streams, reporting period
     b. Per-track breakdown: table with track name, platform, streams,
        revenue, revenue-per-stream for each distributor source
     c. Discrepancy table: rows where flags were triggered, with the
        discrepancy type, expected vs actual values, and severity
        (warning = 10-20% off, alert = >20% off)
     d. Missing tracks: tracks that appear in one source but not another
   - Dark theme: background #0a0a0a, cards #141414, borders #262626,
     text #e5e5e5, accent #f97316
   - Include totals row at the bottom of each table
   - Currency values formatted with $ and 2 decimal places
   - Responsive layout

6. SAMPLE DATA GENERATOR (src/sample-data.js)
   - When --generate-sample is passed, create 3 CSV files in the output
     directory:
     - sample-distrokid.csv
     - sample-tunecore.csv
     - sample-cdbaby.csv
   - Simulate ~50K monthly streams across 5 platforms for an artist with
     6 tracks
   - Introduce realistic discrepancies:
     - One track with 18% fewer streams in TuneCore than DistroKid
     - One track missing entirely from CD Baby
     - Revenue that's 12% below expected for one platform
   - Use realistic distributor header formats for each CSV

DEPENDENCIES: csv-parser, handlebars (for HTML template rendering)

royalty-tool/
  package.json
  src/
    cli.js
    parsers/
      distrokid.js
      tunecore.js
      cdbaby.js
      auto-detect.js
    reconciler.js
    reporter.js
    sample-data.js
  templates/
    report.html

Add a --history flag that accepts a directory of previous reports (saved as JSON).
When provided, include a "Trends" section in the HTML report showing:
- Revenue per track over the last 4 quarters (line chart using Chart.js)
- Stream count trends per platform
- Highlight any track with a >20% drop from the previous quarter
Save the current reconciliation as a JSON file in the history directory for
future comparisons.

Add a --tax flag that generates a tax-summary.csv alongside the HTML report.
Include columns: track_title, total_revenue_usd, platform, territory, quarter.
Group by territory for international tax reporting. Add a totals row. This is
what my accountant needs at tax time -- just the revenue numbers grouped by
country, nothing else.

Add a "Projections" section to the HTML report. Based on the current period's
stream counts and revenue, project next quarter's earnings assuming:
- Catalog streams decay at ~5% per month for tracks older than 3 months
- New releases get a 2x multiplier in their first month
- Show projected revenue per track and per platform
- Include a confidence range (optimistic/realistic/conservative)
Label this clearly as an estimate, not a guarantee.

Add a --watch flag that compares the current report to the previous one (from
the history directory). If any track's streams dropped more than 30% or revenue
dropped more than 25% compared to the previous period, print a prominent alert
in the terminal and add a red banner to the top of the HTML report. This catches
situations where a track gets removed from playlists or a distributor stops
reporting.