statement-etl-ph 0.1.0__tar.gz

statement_etl_ph-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+.pytest_cache/
+
+# Never commit a real statement, a token or a config with passwords in it.
+*.pdf
+!tests/fixtures/synthetic_*.pdf
+token.json
+client_secret*.json
+statement-etl-ph.json
+*_moneymanager.csv
+.env

statement_etl_ph-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 statement-etl-ph contributors
+
+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.

statement_etl_ph-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: statement-etl-ph
+Version: 0.1.0
+Summary: Read GCash, GoTyme and Grab statements into checked transactions, a CSV, or a Money Manager import.
+Project-URL: Issues, https://github.com/Jomaries777/statement-etl-ph/issues
+Project-URL: Source, https://github.com/Jomaries777/statement-etl-ph
+Author: statement-etl-ph contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bank statement,budget,gcash,gotyme,grab,pdf,philippines
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.10
+Requires-Dist: pdfplumber>=0.11.4
+Provides-Extra: dev
+Requires-Dist: pikepdf>=9.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: reportlab>=4.2.0; extra == 'dev'
+Provides-Extra: gmail
+Requires-Dist: google-api-python-client>=2.140.0; extra == 'gmail'
+Requires-Dist: google-auth-httplib2>=0.2.0; extra == 'gmail'
+Requires-Dist: google-auth-oauthlib>=1.2.1; extra == 'gmail'
+Requires-Dist: google-auth>=2.34.0; extra == 'gmail'
+Description-Content-Type: text/markdown
+
+# statement-etl-ph
+
+Turn your **GCash**, **GoTyme** and **GrabPay** statements into a list of transactions you can actually use: a CSV for a spreadsheet, or a file you import straight into the **Money Manager** app.
+
+Every statement is checked before anything is written. The rows it reads must add up to the totals the bank printed, so a misread statement stops instead of quietly putting wrong numbers into your budget.
+
+> **Only trust the official source.** The package is `statement-etl-ph` on PyPI and the code lives at <https://github.com/Jomaries777/statement-etl-ph>. This tool runs on your own computer. It never sends your statements, passwords or transactions to anyone. Be suspicious of any copy, fork or "helper" site that asks for them.
+
+## Quick start: one statement, no setup
+
+You need Python 3.10 or newer.
+
+1. **Get your statement.** In the GCash app, open your transaction history and request it by email. It arrives as a password-protected PDF; the email tells you what the password is.
+2. **Install:**
+   ```bash
+   pipx install statement-etl-ph
+   ```
+   (Or `pip install statement-etl-ph` inside a virtual environment.)
+3. **Convert it:**
+   ```bash
+   statement-etl-ph statement.pdf --bank gcash --to moneymanager --password YOUR-PDF-PASSWORD
+   ```
+   It prints every row and the check, then writes `gcash_<from>_to_<to>_moneymanager.csv`. To keep the password out of your shell history, set `GCASH_PDF_PASSWORD` instead of passing `--password`.
+4. **Import that file into Money Manager.** The Category column is left blank on purpose, so you can sort rows in the app.
+
+Add `--dry-run` to see the rows without writing anything, and `--to csv` for a plain spreadsheet instead.
+
+### What the check catches
+
+GCash prints some inbound bank transfers with **no description at all**. A parser that matches a list of descriptions to a list of amounts by position shifts every later amount onto the wrong row, then drops the last one, and reports no error. This package reads the page as a grid, keeps the blank row, and then proves nothing moved: the debits and credits it read must equal the statement's printed Total Debit and Total Credit. If they don't, nothing is written (unless you pass `--force`).
+
+It also reports what the bank's own arithmetic leaves out. GCash sometimes refunds a cancelled booking without printing a row, and the running balance is the only evidence. Such refunds, and any other gap the balance proves but nothing explains, are listed in the output rather than hidden. They're never written as rows: add them yourself if you want them.
+
+## Supported banks and e-wallets
+
+| `--bank` | What it reads | Password variable |
+|---|---|---|
+| `gcash` | GCash transaction history PDF | `GCASH_PDF_PASSWORD` |
+| `gotyme` | GoTyme Bank statement of account PDF (the Everyday deposit account by default) | `GOTYME_PDF_PASSWORD` |
+| `grab` | Grab e-receipt emails; only GrabPay Wallet payments are imported, because card and GCash payments already appear on those statements | none |
+
+Want another bank? See [Adding a bank](docs/add-a-bank.md). It's one file.
+
+## Output formats
+
+**`--to moneymanager`**: Money Manager's bulk import, with these columns:
+
+| Column | Value |
+|---|---|
+| Date | the transaction date on the statement (default `2026-08-26`; change it with `--date-format`) |
+| Account | `GCash`, `GoTyme` or `GrabPay`; use `--account-name` to match an account you already have |
+| Category, Subcategory, Note | blank |
+| Amount | always positive, e.g. `1250.00` |
+| Income/Expense | `Income` for money in, `Expense` for money out |
+| Description | the merchant and the bank's reference, e.g. `Example Apps (ref 0000100000066)` |
+
+Money Manager doesn't detect duplicates, so importing the same file twice imports every row twice. Each file is named after its bank and statement period to make that easy to notice.
+
+**`--to csv`**: one row per transaction with the signed amount, debit, credit, balance, reference number and a `duplicate_key` column. Writing into a CSV that already exists only appends rows whose key isn't there yet.
+
+## Level up: fetch statements from Gmail automatically
+
+Instead of downloading each PDF, let the tool find statement emails in your Gmail, check they really came from the bank, and convert them.
+
+```bash
+pipx install "statement-etl-ph[gmail]"
+statement-etl-ph auth client_secret.json      # once
+statement-etl-ph init                          # once: a config file for your passwords
+statement-etl-ph fetch --bank gcash --to moneymanager --out ~/Statements/
+```
+
+**Only mail the bank actually sent is accepted.** A `From:` address is easy to fake, so each message must carry a passing DKIM signature from the bank's own domain (`gcash.com`, `gotyme.com.ph` or `grab.com`), as verified by Gmail. Anything else is refused and left alone.
+
+After a statement is converted, its email gets the label `statement-etl-ph/<bank>`, so the next run skips it.
+
+### Set up your own Gmail access (about 10 minutes, free)
+
+This tool has no shared Google login. You create your own, so nobody else's app ever gets access to your mail. Nothing is deployed, and no billing is needed.
+
+1. Go to [console.cloud.google.com](https://console.cloud.google.com), create a project (any name), and enable the **Gmail API** for it.
+2. Open **Google Auth Platform** and set up the consent screen. Choose **External**, and add your own Gmail address as a test user.
+3. Under **Clients**, create an OAuth client of type **Desktop app** and download its JSON file.
+4. **Publish the app:** on the **Audience** page, click **Publish app** to move it from *Testing* to *In production*. Without this, Google expires your sign-in after **7 days** and fetching stops working.
+5. Run `statement-etl-ph auth path/to/client_secret.json`. A browser opens. Google warns that it "hasn't verified this app": that's expected, because the app is yours. Continue, and allow access.
+
+The token is saved to `~/.config/statement-etl-ph/token.json`, readable only by you. Revoke it any time at [myaccount.google.com/permissions](https://myaccount.google.com/permissions).
+
+**Read-only option:** `statement-etl-ph auth client_secret.json --readonly` never changes your mailbox. Processed emails aren't labelled, so each run sees them again. For CSV output, the duplicate key stops rows being added twice; a Money Manager file is simply rewritten.
+
+### Your bank mail goes somewhere other than Gmail?
+
+Create a free Gmail account just for statements, and forward the bank emails to it. A dedicated account also means the token can only ever see bank mail.
+
+- **Forward with a rule that keeps the original email intact:** a Gmail filter's forwarding, or Outlook's **Redirect to**. "Forward"-style rules and forwarding by hand change the sender, add "FW:" and can wrap the PDF inside another message; those won't match and are rejected.
+- **In the receiving Gmail account,** add a filter for the bank senders set to **Never send it to Spam**. The tool doesn't search Spam.
+- **Known limits:**
+  - Microsoft 365 work accounts often block forwarding outside the company. Where it does forward, Safe Links and "External sender" banners break the bank's DKIM signature, so those messages are rejected.
+  - Some providers, such as Yahoo and Proton, may need a paid plan for automatic forwarding.
+  - Forwarding adds a few seconds to a minute of delay.
+
+## Run it on a schedule
+
+[docs/run-locally.md](docs/run-locally.md) has ready-to-edit schedules for macOS (`launchd`), Linux (`cron` or a systemd timer) and Windows (Task Scheduler), so `fetch` runs hourly or daily on its own.
+
+## Use it as a library
+
+```python
+from statement_etl_ph.banks import get_bank
+
+statement = get_bank("gcash").parser("statement.pdf", "password")
+result = statement.reconcile()
+assert result.ok, result.errors
+for txn in statement.transactions:
+    print(txn.value_date, txn.signed_amount, txn.merchant, txn.reference_no)
+```
+
+Amounts are `Decimal`, never floats.
+
+## Never share a real statement
+
+When reporting a problem, **never attach a real statement, a screenshot of one, or a real reference number**, and never post your PDF password. The [issue template](.github/ISSUE_TEMPLATE/parse-bug.yml) explains how to describe a layout problem using `-v` output and invented values instead.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

statement_etl_ph-0.1.0/README.md

@@ -0,0 +1,125 @@
+# statement-etl-ph
+
+Turn your **GCash**, **GoTyme** and **GrabPay** statements into a list of transactions you can actually use: a CSV for a spreadsheet, or a file you import straight into the **Money Manager** app.
+
+Every statement is checked before anything is written. The rows it reads must add up to the totals the bank printed, so a misread statement stops instead of quietly putting wrong numbers into your budget.
+
+> **Only trust the official source.** The package is `statement-etl-ph` on PyPI and the code lives at <https://github.com/Jomaries777/statement-etl-ph>. This tool runs on your own computer. It never sends your statements, passwords or transactions to anyone. Be suspicious of any copy, fork or "helper" site that asks for them.
+
+## Quick start: one statement, no setup
+
+You need Python 3.10 or newer.
+
+1. **Get your statement.** In the GCash app, open your transaction history and request it by email. It arrives as a password-protected PDF; the email tells you what the password is.
+2. **Install:**
+   ```bash
+   pipx install statement-etl-ph
+   ```
+   (Or `pip install statement-etl-ph` inside a virtual environment.)
+3. **Convert it:**
+   ```bash
+   statement-etl-ph statement.pdf --bank gcash --to moneymanager --password YOUR-PDF-PASSWORD
+   ```
+   It prints every row and the check, then writes `gcash_<from>_to_<to>_moneymanager.csv`. To keep the password out of your shell history, set `GCASH_PDF_PASSWORD` instead of passing `--password`.
+4. **Import that file into Money Manager.** The Category column is left blank on purpose, so you can sort rows in the app.
+
+Add `--dry-run` to see the rows without writing anything, and `--to csv` for a plain spreadsheet instead.
+
+### What the check catches
+
+GCash prints some inbound bank transfers with **no description at all**. A parser that matches a list of descriptions to a list of amounts by position shifts every later amount onto the wrong row, then drops the last one, and reports no error. This package reads the page as a grid, keeps the blank row, and then proves nothing moved: the debits and credits it read must equal the statement's printed Total Debit and Total Credit. If they don't, nothing is written (unless you pass `--force`).
+
+It also reports what the bank's own arithmetic leaves out. GCash sometimes refunds a cancelled booking without printing a row, and the running balance is the only evidence. Such refunds, and any other gap the balance proves but nothing explains, are listed in the output rather than hidden. They're never written as rows: add them yourself if you want them.
+
+## Supported banks and e-wallets
+
+| `--bank` | What it reads | Password variable |
+|---|---|---|
+| `gcash` | GCash transaction history PDF | `GCASH_PDF_PASSWORD` |
+| `gotyme` | GoTyme Bank statement of account PDF (the Everyday deposit account by default) | `GOTYME_PDF_PASSWORD` |
+| `grab` | Grab e-receipt emails; only GrabPay Wallet payments are imported, because card and GCash payments already appear on those statements | none |
+
+Want another bank? See [Adding a bank](docs/add-a-bank.md). It's one file.
+
+## Output formats
+
+**`--to moneymanager`**: Money Manager's bulk import, with these columns:
+
+| Column | Value |
+|---|---|
+| Date | the transaction date on the statement (default `2026-08-26`; change it with `--date-format`) |
+| Account | `GCash`, `GoTyme` or `GrabPay`; use `--account-name` to match an account you already have |
+| Category, Subcategory, Note | blank |
+| Amount | always positive, e.g. `1250.00` |
+| Income/Expense | `Income` for money in, `Expense` for money out |
+| Description | the merchant and the bank's reference, e.g. `Example Apps (ref 0000100000066)` |
+
+Money Manager doesn't detect duplicates, so importing the same file twice imports every row twice. Each file is named after its bank and statement period to make that easy to notice.
+
+**`--to csv`**: one row per transaction with the signed amount, debit, credit, balance, reference number and a `duplicate_key` column. Writing into a CSV that already exists only appends rows whose key isn't there yet.
+
+## Level up: fetch statements from Gmail automatically
+
+Instead of downloading each PDF, let the tool find statement emails in your Gmail, check they really came from the bank, and convert them.
+
+```bash
+pipx install "statement-etl-ph[gmail]"
+statement-etl-ph auth client_secret.json      # once
+statement-etl-ph init                          # once: a config file for your passwords
+statement-etl-ph fetch --bank gcash --to moneymanager --out ~/Statements/
+```
+
+**Only mail the bank actually sent is accepted.** A `From:` address is easy to fake, so each message must carry a passing DKIM signature from the bank's own domain (`gcash.com`, `gotyme.com.ph` or `grab.com`), as verified by Gmail. Anything else is refused and left alone.
+
+After a statement is converted, its email gets the label `statement-etl-ph/<bank>`, so the next run skips it.
+
+### Set up your own Gmail access (about 10 minutes, free)
+
+This tool has no shared Google login. You create your own, so nobody else's app ever gets access to your mail. Nothing is deployed, and no billing is needed.
+
+1. Go to [console.cloud.google.com](https://console.cloud.google.com), create a project (any name), and enable the **Gmail API** for it.
+2. Open **Google Auth Platform** and set up the consent screen. Choose **External**, and add your own Gmail address as a test user.
+3. Under **Clients**, create an OAuth client of type **Desktop app** and download its JSON file.
+4. **Publish the app:** on the **Audience** page, click **Publish app** to move it from *Testing* to *In production*. Without this, Google expires your sign-in after **7 days** and fetching stops working.
+5. Run `statement-etl-ph auth path/to/client_secret.json`. A browser opens. Google warns that it "hasn't verified this app": that's expected, because the app is yours. Continue, and allow access.
+
+The token is saved to `~/.config/statement-etl-ph/token.json`, readable only by you. Revoke it any time at [myaccount.google.com/permissions](https://myaccount.google.com/permissions).
+
+**Read-only option:** `statement-etl-ph auth client_secret.json --readonly` never changes your mailbox. Processed emails aren't labelled, so each run sees them again. For CSV output, the duplicate key stops rows being added twice; a Money Manager file is simply rewritten.
+
+### Your bank mail goes somewhere other than Gmail?
+
+Create a free Gmail account just for statements, and forward the bank emails to it. A dedicated account also means the token can only ever see bank mail.
+
+- **Forward with a rule that keeps the original email intact:** a Gmail filter's forwarding, or Outlook's **Redirect to**. "Forward"-style rules and forwarding by hand change the sender, add "FW:" and can wrap the PDF inside another message; those won't match and are rejected.
+- **In the receiving Gmail account,** add a filter for the bank senders set to **Never send it to Spam**. The tool doesn't search Spam.
+- **Known limits:**
+  - Microsoft 365 work accounts often block forwarding outside the company. Where it does forward, Safe Links and "External sender" banners break the bank's DKIM signature, so those messages are rejected.
+  - Some providers, such as Yahoo and Proton, may need a paid plan for automatic forwarding.
+  - Forwarding adds a few seconds to a minute of delay.
+
+## Run it on a schedule
+
+[docs/run-locally.md](docs/run-locally.md) has ready-to-edit schedules for macOS (`launchd`), Linux (`cron` or a systemd timer) and Windows (Task Scheduler), so `fetch` runs hourly or daily on its own.
+
+## Use it as a library
+
+```python
+from statement_etl_ph.banks import get_bank
+
+statement = get_bank("gcash").parser("statement.pdf", "password")
+result = statement.reconcile()
+assert result.ok, result.errors
+for txn in statement.transactions:
+    print(txn.value_date, txn.signed_amount, txn.merchant, txn.reference_no)
+```
+
+Amounts are `Decimal`, never floats.
+
+## Never share a real statement
+
+When reporting a problem, **never attach a real statement, a screenshot of one, or a real reference number**, and never post your PDF password. The [issue template](.github/ISSUE_TEMPLATE/parse-bug.yml) explains how to describe a layout problem using `-v` output and invented values instead.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

statement_etl_ph-0.1.0/docs/add-a-bank.md

@@ -0,0 +1,82 @@
+# Adding a bank
+
+A bank is one module in `src/statement_etl_ph/banks/`: a parser and a `BANK` definition. You never need, and must never share, a real statement to add one.
+
+## 1. Learn the layout without sharing it
+
+On your own machine, run an existing parser over your statement with `-v` to see how the PDF is laid out:
+
+```bash
+statement-etl-ph your-statement.pdf --bank gcash --dry-run -v
+```
+
+It fails for a new bank, but the debug lines show what pdfplumber sees. For a closer look, print the words and their positions yourself:
+
+```python
+import pdfplumber
+
+with pdfplumber.open("your-statement.pdf", password="...") as pdf:
+    for word in pdf.pages[0].extract_words():
+        print(round(word["x0"]), round(word["x1"]), round(word["top"]), word["text"])
+```
+
+Note the **positions** of the column headers and of a few amounts, never the values themselves. Those positions are all the rest of the work needs.
+
+## 2. Write the parser
+
+Most statements are a borderless table, and `pdf_geometry` already does the hard part:
+
+- `cluster_rows(words, tolerance, sort_key)` groups words into visual rows.
+- `find_money_columns(rows, headers)` finds where the money columns sit from their header row.
+- `assign_money_columns(row, columns, tolerance)` assigns each amount on a row to the nearest column by its right edge.
+
+What differs per bank is the vocabulary: the header names, how the period is printed, what the totals rows are called, and how forgiving the tolerances need to be. Pass yours in; don't change another bank's.
+
+The parser has one shape, `parse_statement(path, password) -> Statement`. Fill in the printed totals (`starting_balance`, `ending_balance`, `total_debit`, `total_credit`) whenever the statement prints them: they're what `reconcile()` checks the rows against.
+
+**Reference numbers.** If the bank prints one per row, use it. It becomes the duplicate key. If not, build a stable one from the date, description, amounts and running balance, as `banks/gotyme.py` does, so two identical payments on one day stay two rows.
+
+## 3. Declare the bank
+
+At the bottom of your module:
+
+```python
+BANK = BankDefinition(
+    name="examplebank",
+    display_name="Example Bank",
+    parser=parse_statement,
+    gmail_query='from:statements@examplebank.com.ph subject:"Statement" has:attachment',
+    dkim_domains=("examplebank.com.ph",),
+    password_env="EXAMPLEBANK_PDF_PASSWORD",
+)
+```
+
+Then add it to the tuple in `banks/__init__.py`.
+
+**`dkim_domains`:** in Gmail, open one of the bank's emails, choose **Show original**, and read the `Authentication-Results` line. Use the domain on the `dkim=pass` result that belongs to the bank (`header.i=@…` or `header.d=…`). Never add an email provider's domain such as `amazonses.com` or `sendgrid.net`: they sign mail for anyone who pays them.
+
+## 4. Build a synthetic statement
+
+Copy `tests/fixtures/make_fixture.py` into `tests/fixtures/make_<bank>_fixture.py` and change it to draw your bank's layout:
+
+- the same header words, at the same x positions you measured
+- **invented** rows: made-up merchants, made-up reference numbers, round amounts
+- a running balance and printed totals that genuinely add up
+- encrypted with a made-up password, using pikepdf
+
+Cover the cases that break parsers: a credit row, a thousands separator, a long description, a row with an empty description, and a second page if real statements have one.
+
+## 5. Test it
+
+In `tests/test_parse_<bank>.py`, at least:
+
+- every row is extracted, and every reference and description matches the generator's rows exactly
+- `reconcile().ok` is true
+- a wrong password is rejected
+- a row with an empty description keeps every later amount on its own row
+
+## 6. Before you open the pull request
+
+- [ ] No real names, account or mobile numbers, card digits, reference numbers or addresses anywhere: code, tests, comments or commit messages.
+- [ ] No real PDFs, screenshots or `Authentication-Results` headers. Invent values with the same shape.
+- [ ] `pytest` passes.

statement_etl_ph-0.1.0/docs/run-locally.md

@@ -0,0 +1,102 @@
+# Run it on your own computer
+
+Everything here runs on your machine. The only Google Cloud step is the free project that holds your Gmail OAuth client ([README](../README.md#set-up-your-own-gmail-access-about-10-minutes-free)); nothing is deployed.
+
+## 1. Install
+
+Python 3.10 or newer, on macOS, Linux or Windows.
+
+```bash
+pipx install "statement-etl-ph[gmail]"
+```
+
+Drop `[gmail]` if you'll only convert PDFs you download yourself.
+
+## 2. Sign in to Gmail once
+
+```bash
+statement-etl-ph auth path/to/client_secret.json
+```
+
+A browser opens for consent. The token is saved to `~/.config/statement-etl-ph/token.json` (`%APPDATA%\statement-etl-ph\token.json` on Windows), readable only by you. Add `--readonly` if the tool must never change your mailbox.
+
+## 3. Write your config
+
+```bash
+statement-etl-ph init
+```
+
+This writes `~/.config/statement-etl-ph/statement-etl-ph.json`, also readable only by you. Fill in:
+
+- each bank's `password` (or leave it empty and set `GCASH_PDF_PASSWORD` / `GOTYME_PDF_PASSWORD` instead)
+- `account_name`, if your Money Manager account is named differently
+- `output.to` (`moneymanager` or `csv`) and `output.dir`
+- `gmail.since`: how far back to search (`30d`, `2w`, `yesterday`, `all`)
+
+Remove the banks you don't use: `fetch` with no `--bank` reads every bank listed.
+
+## 4. Run it
+
+```bash
+# A PDF you already have
+statement-etl-ph statement.pdf --bank gcash --to moneymanager
+
+# Everything new in Gmail, for every bank in your config
+statement-etl-ph fetch
+
+# See what would happen, write nothing, label nothing
+statement-etl-ph fetch --dry-run
+
+# Show how a PDF was read, column positions included
+statement-etl-ph statement.pdf --bank gcash --dry-run -v
+```
+
+A statement whose rows don't match its printed totals is never written, and its email isn't labelled, so the next run tries it again.
+
+## 5. Run it on a schedule (optional)
+
+Each schedule runs `statement-etl-ph fetch`. Because converted emails are labelled, running often is harmless: a run with nothing new does nothing.
+
+First find the full path of the command, since schedulers don't load your shell's `PATH`:
+
+```bash
+which statement-etl-ph
+```
+
+### macOS (launchd)
+
+1. Copy [`deploy/local/com.statement-etl-ph.fetch.plist`](../deploy/local/com.statement-etl-ph.fetch.plist) to `~/Library/LaunchAgents/`.
+2. Edit the command path and the log paths in it.
+3. Load it:
+   ```bash
+   launchctl load ~/Library/LaunchAgents/com.statement-etl-ph.fetch.plist
+   ```
+
+It runs every hour while you're logged in, and once on login.
+
+### Linux (systemd timer)
+
+1. Copy [`deploy/local/statement-etl-ph.service`](../deploy/local/statement-etl-ph.service) and [`statement-etl-ph.timer`](../deploy/local/statement-etl-ph.timer) to `~/.config/systemd/user/`.
+2. Edit the command path in the `.service` file.
+3. Enable it:
+   ```bash
+   systemctl --user enable --now statement-etl-ph.timer
+   ```
+
+Or with cron (`crontab -e`), hourly:
+
+```
+0 * * * * /home/you/.local/bin/statement-etl-ph fetch >> /home/you/statement-etl-ph.log 2>&1
+```
+
+### Windows (Task Scheduler)
+
+In PowerShell, using the path from `where.exe statement-etl-ph`:
+
+```powershell
+schtasks /Create /SC HOURLY /TN "statement-etl-ph fetch" /TR "C:\Users\you\.local\bin\statement-etl-ph.exe fetch"
+```
+
+## What a local run can't do
+
+An import happens when the command runs, not the moment the email arrives. Reacting instantly needs a public address for Gmail's notifications to reach, which a laptop doesn't have.

statement_etl_ph-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "statement-etl-ph"
+version = "0.1.0"
+description = "Read GCash, GoTyme and Grab statements into checked transactions, a CSV, or a Money Manager import."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "statement-etl-ph contributors" }]
+keywords = ["gcash", "gotyme", "grab", "philippines", "bank statement", "pdf", "budget"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Office/Business :: Financial :: Accounting",
+]
+# Parsing a statement you already have needs nothing else.
+dependencies = ["pdfplumber>=0.11.4"]
+
+[project.optional-dependencies]
+gmail = [
+    "google-api-python-client>=2.140.0",
+    "google-auth>=2.34.0",
+    "google-auth-oauthlib>=1.2.1",
+    "google-auth-httplib2>=0.2.0",
+]
+dev = ["pytest>=8.3.0", "reportlab>=4.2.0", "pikepdf>=9.0.0"]
+
+[project.scripts]
+statement-etl-ph = "statement_etl_ph.cli:main"
+
+[project.urls]
+Issues = "https://github.com/Jomaries777/statement-etl-ph/issues"
+Source = "https://github.com/Jomaries777/statement-etl-ph"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/statement_etl_ph"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "tests/", "README.md", "LICENSE", "docs/"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

statement_etl_ph-0.1.0/src/statement_etl_ph/__init__.py

@@ -0,0 +1,11 @@
+"""Read Philippine bank and e-wallet statements into plain transactions.
+
+    from statement_etl_ph.banks import get_bank
+
+    statement = get_bank("gcash").parser("statement.pdf", "password")
+    assert statement.reconcile().ok
+    for txn in statement.transactions:
+        print(txn.value_date, txn.signed_amount, txn.merchant)
+"""
+
+__version__ = "0.1.0"

statement_etl_ph-0.1.0/src/statement_etl_ph/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

statement_etl_ph-0.1.0/src/statement_etl_ph/banks/__init__.py

@@ -0,0 +1,35 @@
+"""The banks and e-wallets this package can read, one module each.
+
+The registry is a fixed list on purpose. Nothing is discovered from other
+installed packages: a statement is financial data, and which code reads it
+should be decided here, not by whatever else happens to be installed.
+"""
+
+from __future__ import annotations
+
+from .base import BankDefinition
+from .gcash import BANK as GCASH
+from .gotyme import BANK as GOTYME
+from .grab import BANK as GRAB
+
+__all__ = ["BankDefinition", "available", "get_bank", "register"]
+
+_REGISTRY: dict[str, BankDefinition] = {bank.name: bank for bank in (GCASH, GOTYME, GRAB)}
+
+
+def register(bank: BankDefinition) -> None:
+    """Add a bank from your own code, e.g. while developing a new parser."""
+    _REGISTRY[bank.name] = bank
+
+
+def available() -> list[str]:
+    return sorted(_REGISTRY)
+
+
+def get_bank(name: str) -> BankDefinition:
+    try:
+        return _REGISTRY[name.lower()]
+    except KeyError:
+        raise KeyError(
+            f"no bank called {name!r}. Available: {', '.join(available())}"
+        ) from None

statement_etl_ph-0.1.0/src/statement_etl_ph/banks/base.py

@@ -0,0 +1,50 @@
+"""What a bank is to this package: how to find its mail and how to read it."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+from ..models import Statement
+
+# (path, password) -> Statement. A provider whose statement is the email body
+# rather than a PDF keeps the same shape and ignores the password.
+Parser = Callable[..., Statement]
+
+
+@dataclass(frozen=True)
+class BankDefinition:
+    """Everything that differs between banks, in one place.
+
+    Adding a bank means writing one module in this package that defines a
+    parser and a ``BANK`` of this type, then listing it in ``banks/__init__``.
+    """
+
+    name: str
+    # How the provider is named to a person: the Account column of a Money
+    # Manager import, a memo, a report.
+    display_name: str
+    parser: Parser
+    # Gmail search for the statement email. The processed label and date
+    # window are added at fetch time, not written here.
+    gmail_query: str
+    # The domains the provider DKIM-signs its mail with. A message no one of
+    # them signed is refused, whatever its From header says.
+    dkim_domains: tuple[str, ...]
+    # The environment variable holding the PDF password. Empty for a provider
+    # whose statement is not encrypted.
+    password_env: str = ""
+    # "pdf" for an attachment; "email_body" when the email *is* the receipt.
+    content: str = "pdf"
+    # Filename fragments that pick the right PDF when a message carries
+    # several, tried in order. A pattern that matches nothing fails the
+    # message rather than falling back to the first PDF.
+    attachment_patterns: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def reads_body(self) -> bool:
+        return self.content == "email_body"
+
+    @property
+    def processed_label(self) -> str:
+        return f"statement-etl-ph/{self.name}"