██████╗ ██████╗ ██████╗     ██╗███╗   ██╗██╗   ██╗ ██████╗ ██╗ ██████╗███████╗
        ██╔══██╗██╔══██╗██╔══██╗    ██║████╗  ██║██║   ██║██╔═══██╗██║██╔════╝██╔════╝
        ██████╔╝██║  ██║██████╔╝    ██║██╔██╗ ██║██║   ██║██║   ██║██║██║     █████╗  
        ██╔══██╗██║  ██║██╔══██╗    ██║██║╚██╗██║╚██╗ ██╔╝██║   ██║██║██║     ██╔══╝  
        ██████╔╝██████╔╝██████╔╝    ██║██║ ╚████║ ╚████╔╝ ╚██████╔╝██║╚██████╗███████╗
        ╚═════╝ ╚═════╝ ╚═════╝     ╚═╝╚═╝  ╚═══╝  ╚═══╝   ╚═════╝ ╚═╝ ╚═════╝╚══════╝

            A U T O N O M O U S   I N V O I C E   &   R E C E I P T   S U I T E

🧾 BDB Invoice & Receipt Suite (Multi-Service & IMAP)

Unified, autonomous, cross-platform CLI suite to discover, batch download, and normalize invoices and receipts (Uber, AliExpress, Amazon) and directly from any IMAP E-Mail inbox (Bolt, Adobe, etc.). Generates consolidated accounting tables (Gesamtauflistung.pdf).

🌟 Key Highlights

📧 Universal IMAP E-Mail Scraper

• 🔑 Interactive Auth: Prompts for IMAP_HOST, IMAP_USER, and IMAP_PASS and securely stores them in a .env file.
• ✉️ JSON-driven Provider Configs: Easily scaffold new email scrapers (like Bolt, Lime, Freenow, Adobe) by typing their name in the CLI. The system automatically creates a .json regex config in services/email/providers/.
• ✂️ Headless Playwright PDF Rendering: Dynamically renders HTML emails into clean A4 PDFs with CSS hooks to hide footers/unnecessary clutter.

📦 Amazon Invoices

• 🚀 Native Popover Download: Uses Playwright to navigate Amazon's complex DOM, bypassing standard print dialogs to fetch original Amazon PDF invoices.
• 🔍 Regex Text Extraction: Parses order numbers, dates, and EUR amounts deterministically.

🚖 Uber Invoices

• ⚡ GraphQL Network Interception: Captures 100% of trips via https://riders.uber.com/graphql without virtual scrolling glitches.
• 📅 Chronological Year Tracking: Resolves Uber's year-omission in relative date strings ("31. Juli • 9:56").
• 📑 Automatic Re-naming: Extracts official invoice numbers from PDF text: invoices/Uber-Bv-YYYY-MM-DD-<INVOICE_NO>.pdf.

🛍️ AliExpress Invoices & Receipts

• 🌐 Alibaba MTOP Interceptor: Intercepts mtop.aliexpress.buyer.order.list endpoints for 100% accurate financial metadata.
• 🖼️ Lossless PNG-to-A4 PDF Pipeline: Automatically captures PNG receipts / Canvas renders and converts them to standardized, accounting-grade A4 PDFs.
• 📊 Consolidated Financial Table: Generates structured accounting summaries (Gesamtauflistung.pdf and Gesamtauflistung.json).

🛡️ Core Platform

• 🔑 Persistent Chrome Sessions: Stores logins safely in .auth-profile/ (no recurring 2FA or Captcha sliders on subsequent runs).
• 💻 100% Cross-Platform: Runs natively on macOS, Windows (PowerShell / CMD), and Linux.

🌐 OpenWiki Living Documentation

• 🚀 Quickstart & Onboarding: .openwiki/quickstart.md
• 🏗️ Architecture & Signal Flow: .openwiki/architecture.md
• 🏛️ Architecture Decision Records (ADRs): .openwiki/decisions.md
• 📝 Release Notes & Changelog: .openwiki/release_notes.md

🚀 Key Features

🖥️ Brand New Electron GUI (v1.4+)

• Cross-Platform: Works natively on macOS, Windows, and Linux.
• Glassmorphism UI: Built with Tailwind CSS for a stunning, responsive, and dark-mode native experience.
• Real-time Terminal: See the logs and scraper activity live inside the GUI window.
• Desktop Shortcuts: Automatically creates functional Desktop shortcuts during npm install -g.

⏰ Background Auto-Pilot (Cron)

• Set & Forget: Enable the Auto-Pilot toggle in the GUI (or CLI) to run the scraper silently in the background every 24 hours.
• Detached Daemon: Runs completely invisible.

🌐 Scalable Architecture

flowchart TD
    subgraph UI ["🖥️ Interfaces"]
        CLI["index.js (Multi-Service Inquirer CLI)"]
        AGENT["agent_skill.md (AI Agent Wrapper)"]
    end

    subgraph WebScrapers ["🌐 Web Scrapers (Playwright)"]
        UBER["🚖 Uber (GraphQL)"]
        ALI["🛍️ AliExpress (MTOP)"]
        AMZ["📦 Amazon (DOM Popover)"]
    end

    subgraph EmailScrapers ["📧 E-Mail IMAP Scrapers"]
        IMAP["ImapFlow (IMAP Auth)"]
        JSON["JSON Configs (Bolt, Lime, etc.)"]
        HTML2PDF["HTML to PDF Renderer"]
    end

    subgraph Storage ["💾 Storage & Output"]
        PROFILE[".auth-profile/"]
        ENV[".env (IMAP Credentials)"]
        INVOICES["invoices/"]
        SUMMARY["Gesamtauflistung.pdf"]
    end

    CLI --> WebScrapers
    CLI --> EmailScrapers
    WebScrapers --> PROFILE
    EmailScrapers --> ENV
    EmailScrapers --> IMAP
    IMAP --> HTML2PDF
    HTML2PDF --> INVOICES
    WebScrapers --> INVOICES
    INVOICES --> SUMMARY

🛠️ Installation & Quick Start

1. Global Installation (Recommended)

You can install the suite globally on any machine via NPM. The pre-install hook will automatically check your system dependencies (Node.js >= 18).

npm install -g invoice-scrape-agent

🎉 Magic! The installer will automatically generate executable Desktop Shortcuts for both the GUI and the CLI on Mac and Windows!

2. Running the App

Start the beautiful Electron GUI: Double-click your Desktop Shortcut, or type:

invoice-scrape-agent-gui

Start the powerful CLI: Double-click the CLI Desktop Shortcut, or type:

invoice-scrape-agent

💻 Option 3: Local Git Repository Clone

🍎 macOS / 🐧 Linux

git clone https://github.com/hybridlabor-api/invoice-scrape-agent.git
cd invoice-scrape-agent
chmod +x install.sh
./install.sh

🪟 Windows (PowerShell / CMD)

git clone https://github.com/hybridlabor-api/invoice-scrape-agent.git
cd invoice-scrape-agent
powershell -ExecutionPolicy Bypass -File .\install.ps1

🔄 How to Update / Aktualisierung

Option A: Local Repository Update

Um die neueste Version von GitHub zu laden und Abhängigkeiten zu aktualisieren:

npm run update
# oder manuell:
git pull origin main && npm install

Option B: Global NPM Package Update

npm install -g invoice-scrape-agent@latest

🎮 Interactive CLI Dashboard

Launch the interactive dashboard:

npm start

======================================================
       🧾 BDB Multi-Service Invoice & Tax Suite 🧾               
======================================================

? Welche Aktion oder welchen Dienst möchtest du wählen?
❯ 🚖 Uber Invoices 
  🛍️ AliExpress Invoices 
  📦 Amazon Invoices 
  ──────────────
  📧 E-Mail Rechnungs-Scraper (IMAP)
  ──────────────
  🌟 Gesamtabrechnung aller Dienste erstellen (Master PDF)
  🤖 Neuen Web-Scraper generieren (Dojo AI)
  📁 Rechnungsordner öffnen (invoices/)
  ──────────────
  🚪 Beenden

📄 License & Attribution

Distributed under the MIT License. Part of the BDB Developer Toolchain.