receipt-report-generator 1.0.0__tar.gz

receipt_report_generator-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Barton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

receipt_report_generator-1.0.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: receipt-report-generator
+Version: 1.0.0
+Summary: Turn emailed receipts into a single expense-report PDF (cover summary + indexed appendix).
+Author: David Barton
+License: MIT License
+        
+        Copyright (c) 2026 David Barton
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/dbarton1974/receipt-report-generator
+Project-URL: Repository, https://github.com/dbarton1974/receipt-report-generator
+Project-URL: Issues, https://github.com/dbarton1974/receipt-report-generator/issues
+Keywords: imap,receipts,pdf,expense-report,email,invoice,bookkeeping
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: imap-tools>=1.7.0
+Requires-Dist: pdfplumber>=0.11.0
+Requires-Dist: reportlab>=4.1.0
+Requires-Dist: pypdf>=4.2.0
+Requires-Dist: python-dotenv>=1.0.0
+Dynamic: license-file
+
+# receipt-report-generator
+
+Turn receipts that land in your inbox into a single, tidy **expense-report PDF** — a cover
+sheet that summarises every receipt with a running total, followed by each original receipt
+as an indexed appendix. Optionally emails the finished PDF onwards and files the processed
+messages away so they are never counted twice.
+
+Originally built to collect public-transport receipts for monthly bookkeeping, it is
+**metadata-driven**: point it at any sender, any IMAP mailbox, and any currency.
+
+## What it does
+
+1. Connects to your mailbox over **IMAP**.
+2. Finds every email from a configured **sender** that has a **PDF attachment**.
+3. Reads the **amount** and **date** out of each receipt PDF.
+4. Builds one PDF:
+   - **Cover sheet** — a title, today's date, and a table of `# | Date | Description |
+     (Purpose) | Amount`, ending in a **Total**.
+   - **Appendix** — every original receipt, stamped `Appendix N` to match its table row,
+     with PDF bookmarks.
+5. **Moves** the processed emails to a folder so the next run only sees new receipts.
+6. *(Optional)* **Emails** the PDF to an archive address and saves a copy in your Sent folder.
+7. *(Optional, in CI)* **Emails you** if a scheduled run fails.
+
+Because "what's already processed" is represented by *moving the emails out of the inbox*,
+there is no database or local state to maintain — the mailbox is the single source of truth,
+which is what makes running it in the cloud trivial.
+
+## Requirements
+
+- Python 3.10+
+- An email account reachable over IMAP + SMTP (see [supported servers](#supported-mail-servers))
+
+## Installation
+
+```bash
+git clone https://github.com/<you>/receipt-report-generator.git
+cd receipt-report-generator
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env      # then edit .env
+```
+
+Or install it as a package to get the `receipt-report` command on your PATH:
+
+```bash
+pip install git+https://github.com/<you>/receipt-report-generator.git
+# then, in a directory containing your .env:
+receipt-report --dry-run
+```
+
+## Configuration
+
+All configuration is via environment variables (read from `.env` locally, or injected by
+your host in the cloud). The most important ones:
+
+| Variable | Description |
+| --- | --- |
+| `MAIL_PROVIDER` | A preset from [`providers.json`](receipt_report/providers.json) (`gmail`, `outlook`, `icloud`, …). Fills in IMAP/SMTP host, port and security. |
+| `IMAP_USER` / `IMAP_PASSWORD` | Mailbox login. Use an **app password** where the provider supports one. |
+| `RECEIPT_SENDER` | Sender address of the receipts. A substring works (e.g. `sl.se`). |
+| `PROCESSED_FOLDER` | Where processed emails are moved (default `Processed/Receipts`, created if missing). |
+| `RECIPIENT_NAME` / `REPORT_TITLE` | Name and cover title (`{name}` is substituted). |
+| `CURRENCY` | Label after each amount (default `kr`). |
+| `PURPOSE` | Optional value for a "Purpose" column; empty hides the column. |
+| `DESCRIPTION_MATCH` | Optional regex to extract a description from the receipt text. |
+| `ARCHIVE_RECIPIENT` | If set, the report is emailed here on a real run. |
+| `NOTIFY_RECIPIENT` | Where CI failure notices go (defaults to `IMAP_USER`). |
+
+To use a server not in the presets, leave `MAIL_PROVIDER` empty and set `IMAP_HOST`,
+`IMAP_PORT`, `SMTP_HOST`, `SMTP_PORT` and `SMTP_SECURITY` (`ssl` or `starttls`) directly.
+See [`.env.example`](.env.example) for the full list.
+
+## Supported mail servers
+
+Presets live in [`providers.json`](receipt_report/providers.json) and are easy to extend.
+
+| `MAIL_PROVIDER` | Service | IMAP | SMTP |
+| --- | --- | --- | --- |
+| `gmail` | Gmail / Google Workspace | imap.gmail.com:993 | smtp.gmail.com:465 (SSL) |
+| `outlook` | Outlook.com / Hotmail | outlook.office365.com:993 | smtp-mail.outlook.com:587 (STARTTLS) |
+| `office365` | Microsoft 365 (work/school) | outlook.office365.com:993 | smtp.office365.com:587 (STARTTLS) |
+| `icloud` | iCloud Mail | imap.mail.me.com:993 | smtp.mail.me.com:587 (STARTTLS) |
+| `yahoo` | Yahoo Mail | imap.mail.yahoo.com:993 | smtp.mail.yahoo.com:465 (SSL) |
+| `fastmail` | Fastmail | imap.fastmail.com:993 | smtp.fastmail.com:465 (SSL) |
+| `gmx` | GMX | imap.gmx.com:993 | mail.gmx.com:465 (SSL) |
+| `zoho` | Zoho Mail | imap.zoho.com:993 | smtp.zoho.com:465 (SSL) |
+| `opensrs` | OpenSRS / Tucows Hosted Email | imap.hostedemail.com:993 | smtp.hostedemail.com:465 (SSL) |
+
+Any IMAP/SMTP server works via explicit host settings — the presets are just conveniences.
+
+## Setting up your mail account
+
+Most providers need two things:
+
+1. **IMAP access enabled.** On by default for many; for some (Yahoo, GMX, Zoho) you toggle
+   it in settings.
+2. **An app password** if the account uses 2-factor authentication. The generator logs in
+   with a plain username + password, so create a provider-specific *app password* and use it
+   as `IMAP_PASSWORD`:
+   - **Gmail:** Google Account → Security → App passwords (requires 2-Step Verification).
+   - **iCloud:** appleid.apple.com → Sign-In and Security → App-Specific Passwords.
+   - **Yahoo / Fastmail / Zoho:** Account security → generate an app password.
+   - **OpenSRS/hosted email:** usually the normal mailbox password works.
+
+> **Microsoft note:** Outlook.com and many Microsoft 365 tenants have disabled basic
+> IMAP/SMTP auth. If password login is refused, an admin may need to allow it, or the account
+> may require OAuth (not handled by this tool).
+
+The same account is used both to **read** receipts and to **send** the report, so make sure
+SMTP submission is allowed too. The per-provider notes in `providers.json` summarise this.
+
+## Usage
+
+Dry run (build the PDF; touch nothing in the mailbox):
+
+```bash
+python -m receipt_report.main --dry-run
+```
+
+Real run (build the PDF, move processed emails, and email the report if `ARCHIVE_RECIPIENT`
+is set):
+
+```bash
+python -m receipt_report.main
+```
+
+Real run without emailing:
+
+```bash
+python -m receipt_report.main --no-email
+```
+
+Output lands in `output/expense-report_<YYYY-MM-DD>.pdf`.
+
+## Run it in the cloud (GitHub Actions)
+
+[`.github/workflows/monthly.yml`](.github/workflows/monthly.yml) runs the generator on the
+**last day of each month** — no machine of your own needs to be on.
+
+Set these in your repository (**Settings → Secrets and variables → Actions**):
+
+**Secrets** (sensitive):
+
+| Secret | Value |
+| --- | --- |
+| `IMAP_USER` | Your mailbox address |
+| `IMAP_PASSWORD` | App password / mailbox password |
+| `ARCHIVE_RECIPIENT` | *(optional)* where to email the report |
+
+**Variables** (non-sensitive):
+
+| Variable | Example |
+| --- | --- |
+| `MAIL_PROVIDER` | `gmail` |
+| `RECEIPT_SENDER` | `receipts@vendor.com` |
+| `RECIPIENT_NAME` | `Jane Doe` |
+| `CURRENCY` | `kr` |
+| `PURPOSE` | *(optional)* |
+
+Then:
+
+- **Test anytime:** Actions tab → *Monthly expense report* → **Run workflow**. A manual run
+  skips the last-day guard and runs immediately.
+- **Test the failure alert:** run the workflow with the **test_fail** input checked — it forces
+  a failure and emails `NOTIFY_RECIPIENT` (or `IMAP_USER`).
+- The generated PDF is also kept as a **run artifact** for 90 days.
+- Scheduled workflows only run on the repository's default branch.
+
+## Customising the parsing
+
+Receipt layouts vary. The parser ([`receipt_parser.py`](receipt_report/receipt_parser.py)) is
+built to be tuned:
+
+- **Amounts** are matched in both `1,234.50` and `1 234,50` styles; lines containing keywords
+  like *total*, *amount due*, *summa* are preferred, otherwise the largest amount wins.
+- **Dates** are read as ISO, `dd.mm.yyyy`, or `12 June 2026` (English + Swedish month names),
+  falling back to the email's date.
+- **Descriptions** default to the first meaningful text line; set `DESCRIPTION_MATCH` to a
+  regex to grab something specific (group 1 if present).
+
+Receipts where an amount or date can't be read are still included and listed as warnings so
+you can check them.
+
+## Security
+
+- Credentials live only in `.env` (git-ignored) or your host's secret store. Nothing sensitive
+  is committed.
+- The processed-email move happens **after** the PDF is written successfully, so an interrupted
+  run never loses receipts.
+
+## Publishing to PyPI
+
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml) publishes the package to
+PyPI whenever you create a **GitHub Release**, authenticating with a PyPI API token. One-time
+setup:
+
+1. **Create an API token.** On [pypi.org](https://pypi.org) → *Account settings → API tokens*
+   → *Add API token* (scope "Entire account" for the first upload; you can scope it to the
+   project afterwards).
+2. **Store it as a secret.** Repo → *Settings → Secrets and variables → Actions* → new secret
+   named `PYPI_API_TOKEN` with the token value. Or via CLI:
+   `gh secret set PYPI_API_TOKEN --repo <owner>/<repo>`
+3. **Release.** Bump `version` in [`pyproject.toml`](pyproject.toml), then create a GitHub
+   Release (e.g. tag `v1.0.0`). The workflow builds and uploads automatically.
+
+Prefer no stored token? PyPI also supports OIDC *trusted publishing* — remove the `password:`
+line from the workflow, add `permissions: id-token: write` to the publish job, and register a
+trusted publisher on PyPI (owner, repo, workflow `publish.yml`, no environment).
+
+## License
+
+[MIT](LICENSE)

receipt_report_generator-1.0.0/README.md

@@ -0,0 +1,213 @@
+# receipt-report-generator
+
+Turn receipts that land in your inbox into a single, tidy **expense-report PDF** — a cover
+sheet that summarises every receipt with a running total, followed by each original receipt
+as an indexed appendix. Optionally emails the finished PDF onwards and files the processed
+messages away so they are never counted twice.
+
+Originally built to collect public-transport receipts for monthly bookkeeping, it is
+**metadata-driven**: point it at any sender, any IMAP mailbox, and any currency.
+
+## What it does
+
+1. Connects to your mailbox over **IMAP**.
+2. Finds every email from a configured **sender** that has a **PDF attachment**.
+3. Reads the **amount** and **date** out of each receipt PDF.
+4. Builds one PDF:
+   - **Cover sheet** — a title, today's date, and a table of `# | Date | Description |
+     (Purpose) | Amount`, ending in a **Total**.
+   - **Appendix** — every original receipt, stamped `Appendix N` to match its table row,
+     with PDF bookmarks.
+5. **Moves** the processed emails to a folder so the next run only sees new receipts.
+6. *(Optional)* **Emails** the PDF to an archive address and saves a copy in your Sent folder.
+7. *(Optional, in CI)* **Emails you** if a scheduled run fails.
+
+Because "what's already processed" is represented by *moving the emails out of the inbox*,
+there is no database or local state to maintain — the mailbox is the single source of truth,
+which is what makes running it in the cloud trivial.
+
+## Requirements
+
+- Python 3.10+
+- An email account reachable over IMAP + SMTP (see [supported servers](#supported-mail-servers))
+
+## Installation
+
+```bash
+git clone https://github.com/<you>/receipt-report-generator.git
+cd receipt-report-generator
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env      # then edit .env
+```
+
+Or install it as a package to get the `receipt-report` command on your PATH:
+
+```bash
+pip install git+https://github.com/<you>/receipt-report-generator.git
+# then, in a directory containing your .env:
+receipt-report --dry-run
+```
+
+## Configuration
+
+All configuration is via environment variables (read from `.env` locally, or injected by
+your host in the cloud). The most important ones:
+
+| Variable | Description |
+| --- | --- |
+| `MAIL_PROVIDER` | A preset from [`providers.json`](receipt_report/providers.json) (`gmail`, `outlook`, `icloud`, …). Fills in IMAP/SMTP host, port and security. |
+| `IMAP_USER` / `IMAP_PASSWORD` | Mailbox login. Use an **app password** where the provider supports one. |
+| `RECEIPT_SENDER` | Sender address of the receipts. A substring works (e.g. `sl.se`). |
+| `PROCESSED_FOLDER` | Where processed emails are moved (default `Processed/Receipts`, created if missing). |
+| `RECIPIENT_NAME` / `REPORT_TITLE` | Name and cover title (`{name}` is substituted). |
+| `CURRENCY` | Label after each amount (default `kr`). |
+| `PURPOSE` | Optional value for a "Purpose" column; empty hides the column. |
+| `DESCRIPTION_MATCH` | Optional regex to extract a description from the receipt text. |
+| `ARCHIVE_RECIPIENT` | If set, the report is emailed here on a real run. |
+| `NOTIFY_RECIPIENT` | Where CI failure notices go (defaults to `IMAP_USER`). |
+
+To use a server not in the presets, leave `MAIL_PROVIDER` empty and set `IMAP_HOST`,
+`IMAP_PORT`, `SMTP_HOST`, `SMTP_PORT` and `SMTP_SECURITY` (`ssl` or `starttls`) directly.
+See [`.env.example`](.env.example) for the full list.
+
+## Supported mail servers
+
+Presets live in [`providers.json`](receipt_report/providers.json) and are easy to extend.
+
+| `MAIL_PROVIDER` | Service | IMAP | SMTP |
+| --- | --- | --- | --- |
+| `gmail` | Gmail / Google Workspace | imap.gmail.com:993 | smtp.gmail.com:465 (SSL) |
+| `outlook` | Outlook.com / Hotmail | outlook.office365.com:993 | smtp-mail.outlook.com:587 (STARTTLS) |
+| `office365` | Microsoft 365 (work/school) | outlook.office365.com:993 | smtp.office365.com:587 (STARTTLS) |
+| `icloud` | iCloud Mail | imap.mail.me.com:993 | smtp.mail.me.com:587 (STARTTLS) |
+| `yahoo` | Yahoo Mail | imap.mail.yahoo.com:993 | smtp.mail.yahoo.com:465 (SSL) |
+| `fastmail` | Fastmail | imap.fastmail.com:993 | smtp.fastmail.com:465 (SSL) |
+| `gmx` | GMX | imap.gmx.com:993 | mail.gmx.com:465 (SSL) |
+| `zoho` | Zoho Mail | imap.zoho.com:993 | smtp.zoho.com:465 (SSL) |
+| `opensrs` | OpenSRS / Tucows Hosted Email | imap.hostedemail.com:993 | smtp.hostedemail.com:465 (SSL) |
+
+Any IMAP/SMTP server works via explicit host settings — the presets are just conveniences.
+
+## Setting up your mail account
+
+Most providers need two things:
+
+1. **IMAP access enabled.** On by default for many; for some (Yahoo, GMX, Zoho) you toggle
+   it in settings.
+2. **An app password** if the account uses 2-factor authentication. The generator logs in
+   with a plain username + password, so create a provider-specific *app password* and use it
+   as `IMAP_PASSWORD`:
+   - **Gmail:** Google Account → Security → App passwords (requires 2-Step Verification).
+   - **iCloud:** appleid.apple.com → Sign-In and Security → App-Specific Passwords.
+   - **Yahoo / Fastmail / Zoho:** Account security → generate an app password.
+   - **OpenSRS/hosted email:** usually the normal mailbox password works.
+
+> **Microsoft note:** Outlook.com and many Microsoft 365 tenants have disabled basic
+> IMAP/SMTP auth. If password login is refused, an admin may need to allow it, or the account
+> may require OAuth (not handled by this tool).
+
+The same account is used both to **read** receipts and to **send** the report, so make sure
+SMTP submission is allowed too. The per-provider notes in `providers.json` summarise this.
+
+## Usage
+
+Dry run (build the PDF; touch nothing in the mailbox):
+
+```bash
+python -m receipt_report.main --dry-run
+```
+
+Real run (build the PDF, move processed emails, and email the report if `ARCHIVE_RECIPIENT`
+is set):
+
+```bash
+python -m receipt_report.main
+```
+
+Real run without emailing:
+
+```bash
+python -m receipt_report.main --no-email
+```
+
+Output lands in `output/expense-report_<YYYY-MM-DD>.pdf`.
+
+## Run it in the cloud (GitHub Actions)
+
+[`.github/workflows/monthly.yml`](.github/workflows/monthly.yml) runs the generator on the
+**last day of each month** — no machine of your own needs to be on.
+
+Set these in your repository (**Settings → Secrets and variables → Actions**):
+
+**Secrets** (sensitive):
+
+| Secret | Value |
+| --- | --- |
+| `IMAP_USER` | Your mailbox address |
+| `IMAP_PASSWORD` | App password / mailbox password |
+| `ARCHIVE_RECIPIENT` | *(optional)* where to email the report |
+
+**Variables** (non-sensitive):
+
+| Variable | Example |
+| --- | --- |
+| `MAIL_PROVIDER` | `gmail` |
+| `RECEIPT_SENDER` | `receipts@vendor.com` |
+| `RECIPIENT_NAME` | `Jane Doe` |
+| `CURRENCY` | `kr` |
+| `PURPOSE` | *(optional)* |
+
+Then:
+
+- **Test anytime:** Actions tab → *Monthly expense report* → **Run workflow**. A manual run
+  skips the last-day guard and runs immediately.
+- **Test the failure alert:** run the workflow with the **test_fail** input checked — it forces
+  a failure and emails `NOTIFY_RECIPIENT` (or `IMAP_USER`).
+- The generated PDF is also kept as a **run artifact** for 90 days.
+- Scheduled workflows only run on the repository's default branch.
+
+## Customising the parsing
+
+Receipt layouts vary. The parser ([`receipt_parser.py`](receipt_report/receipt_parser.py)) is
+built to be tuned:
+
+- **Amounts** are matched in both `1,234.50` and `1 234,50` styles; lines containing keywords
+  like *total*, *amount due*, *summa* are preferred, otherwise the largest amount wins.
+- **Dates** are read as ISO, `dd.mm.yyyy`, or `12 June 2026` (English + Swedish month names),
+  falling back to the email's date.
+- **Descriptions** default to the first meaningful text line; set `DESCRIPTION_MATCH` to a
+  regex to grab something specific (group 1 if present).
+
+Receipts where an amount or date can't be read are still included and listed as warnings so
+you can check them.
+
+## Security
+
+- Credentials live only in `.env` (git-ignored) or your host's secret store. Nothing sensitive
+  is committed.
+- The processed-email move happens **after** the PDF is written successfully, so an interrupted
+  run never loses receipts.
+
+## Publishing to PyPI
+
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml) publishes the package to
+PyPI whenever you create a **GitHub Release**, authenticating with a PyPI API token. One-time
+setup:
+
+1. **Create an API token.** On [pypi.org](https://pypi.org) → *Account settings → API tokens*
+   → *Add API token* (scope "Entire account" for the first upload; you can scope it to the
+   project afterwards).
+2. **Store it as a secret.** Repo → *Settings → Secrets and variables → Actions* → new secret
+   named `PYPI_API_TOKEN` with the token value. Or via CLI:
+   `gh secret set PYPI_API_TOKEN --repo <owner>/<repo>`
+3. **Release.** Bump `version` in [`pyproject.toml`](pyproject.toml), then create a GitHub
+   Release (e.g. tag `v1.0.0`). The workflow builds and uploads automatically.
+
+Prefer no stored token? PyPI also supports OIDC *trusted publishing* — remove the `password:`
+line from the workflow, add `permissions: id-token: write` to the publish job, and register a
+trusted publisher on PyPI (owner, repo, workflow `publish.yml`, no environment).
+
+## License
+
+[MIT](LICENSE)

receipt_report_generator-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "receipt-report-generator"
+version = "1.0.0"
+description = "Turn emailed receipts into a single expense-report PDF (cover summary + indexed appendix)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "David Barton" }]
+keywords = ["imap", "receipts", "pdf", "expense-report", "email", "invoice", "bookkeeping"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Environment :: Console",
+    "Topic :: Office/Business :: Financial :: Accounting",
+    "Topic :: Communications :: Email",
+]
+dependencies = [
+    "imap-tools>=1.7.0",
+    "pdfplumber>=0.11.0",
+    "reportlab>=4.1.0",
+    "pypdf>=4.2.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/dbarton1974/receipt-report-generator"
+Repository = "https://github.com/dbarton1974/receipt-report-generator"
+Issues = "https://github.com/dbarton1974/receipt-report-generator/issues"
+
+[project.scripts]
+receipt-report = "receipt_report.main:main"
+
+[tool.setuptools]
+packages = ["receipt_report"]
+
+[tool.setuptools.package-data]
+receipt_report = ["providers.json"]

receipt_report_generator-1.0.0/receipt_report/__init__.py

@@ -0,0 +1,3 @@
+"""receipt-report-generator: turn emailed receipts into a single expense-report PDF."""
+
+__version__ = "1.0.0"

receipt_report_generator-1.0.0/receipt_report/__main__.py

@@ -0,0 +1,8 @@
+"""Makes the package runnable with `python -m receipt_report`."""
+
+import sys
+
+from .main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

receipt_report_generator-1.0.0/receipt_report/config.py

@@ -0,0 +1,107 @@
+"""Configuration, loaded from environment variables (12-factor / metadata-driven).
+
+A named preset from providers.json can be selected with MAIL_PROVIDER, which fills in
+IMAP/SMTP host, port and security. Any explicit host/port/security env var overrides it.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+try:
+    from dotenv import load_dotenv
+except ImportError:  # python-dotenv is optional; in CI the vars are set directly.
+    def load_dotenv(*args, **kwargs):  # type: ignore[misc]
+        return False
+
+from .providers import get_provider
+
+
+@dataclass(frozen=True)
+class Config:
+    # IMAP
+    imap_host: str
+    imap_port: int
+    imap_user: str
+    imap_password: str
+    # SMTP
+    smtp_host: str
+    smtp_port: int
+    smtp_security: str  # "ssl" or "starttls"
+    # What to collect
+    receipt_sender: str
+    inbox_folder: str
+    processed_folder: str
+    # Report
+    output_dir: Path
+    recipient_name: str
+    report_title: str
+    purpose: str        # empty string => no "Purpose" column
+    currency: str
+    description_match: str  # optional regex to extract a description; empty => first line
+    # Delivery / alerts
+    archive_recipient: str  # empty => don't email the report
+    notify_recipient: str   # empty => defaults to imap_user
+
+
+def _require(name: str, value: str) -> str:
+    if not value:
+        raise SystemExit(
+            f"Configuration error: {name} is missing. "
+            f"Copy .env.example to .env and fill in the values."
+        )
+    return value
+
+
+def load_config() -> Config:
+    load_dotenv()
+
+    # Resolve provider preset (if any) for host/port/security defaults.
+    provider_key = os.getenv("MAIL_PROVIDER", "").strip()
+    preset = get_provider(provider_key) if provider_key else None
+    if provider_key and preset is None:
+        raise SystemExit(
+            f"Unknown MAIL_PROVIDER '{provider_key}'. See providers.json for valid keys, "
+            f"or set IMAP_HOST/SMTP_HOST explicitly instead."
+        )
+
+    def _host_default(env_name: str, preset_value: str | None) -> str:
+        return os.getenv(env_name, "").strip() or (preset_value or "")
+
+    imap_host = _host_default("IMAP_HOST", preset.imap_host if preset else None)
+    smtp_host = _host_default("SMTP_HOST", preset.smtp_host if preset else None)
+
+    imap_port = int(os.getenv("IMAP_PORT", str(preset.imap_port if preset else 993)))
+    smtp_port = int(os.getenv("SMTP_PORT", str(preset.smtp_port if preset else 465)))
+    smtp_security = (
+        os.getenv("SMTP_SECURITY", "").strip().lower()
+        or (preset.smtp_security if preset else "ssl")
+    )
+
+    recipient_name = os.getenv("RECIPIENT_NAME", "Me")
+    report_title = os.getenv("REPORT_TITLE", "Expense report for {name}").replace(
+        "{name}", recipient_name
+    )
+
+    return Config(
+        imap_host=_require("IMAP_HOST (or MAIL_PROVIDER)", imap_host),
+        imap_port=imap_port,
+        imap_user=_require("IMAP_USER", os.getenv("IMAP_USER", "").strip()),
+        imap_password=_require("IMAP_PASSWORD", os.getenv("IMAP_PASSWORD", "").strip()),
+        smtp_host=smtp_host or imap_host,
+        smtp_port=smtp_port,
+        smtp_security=smtp_security,
+        receipt_sender=_require("RECEIPT_SENDER", os.getenv("RECEIPT_SENDER", "").strip()),
+        inbox_folder=os.getenv("INBOX_FOLDER", "INBOX"),
+        processed_folder=os.getenv("PROCESSED_FOLDER", "Processed/Receipts"),
+        output_dir=Path(os.getenv("OUTPUT_DIR", "./output")).expanduser(),
+        recipient_name=recipient_name,
+        report_title=report_title,
+        purpose=os.getenv("PURPOSE", "").strip(),
+        currency=os.getenv("CURRENCY", "kr"),
+        description_match=os.getenv("DESCRIPTION_MATCH", "").strip(),
+        archive_recipient=os.getenv("ARCHIVE_RECIPIENT", "").strip(),
+        notify_recipient=os.getenv("NOTIFY_RECIPIENT", "").strip(),
+    )