# moey-finance

> Parse moey! bank statement PDFs into CSV, categorize transactions, and sync them to InfluxDB and Google Sheets.

- Author: Diogo Silva
- Repository: diogosilva30/openclaw
- Version: 20260207014438
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/diogosilva30/openclaw
- Web: https://mule.run/skillshub/@@diogosilva30/openclaw~moey-finance:20260207014438

---

---
name: moey-finance
description: Parse moey! bank statement PDFs into CSV, categorize transactions, and sync them to InfluxDB and Google Sheets.
---

# moey-finance: PDF → CSV → Insights

Use this skill to ingest **moey! bank statement PDFs** and turn them into structured, queryable financial data. Trigger when the user asks to import, analyze, categorize, summarize, or sync moey bank statements.

Behavioral rule (important): treat Python as a **pure extraction helper**. All enrichment, categorization decisions, API calls, and persistence are owned by the **agent**. Work quietly and automatically. Only interrupt the user when credentials, configuration, or manual categorization is required.

---

## Required user inputs (ask only when needed)

- Path to the moey! PDF (local file)
- Google Sheets target (Spreadsheet ID or name, optional worksheet/tab)
- InfluxDB connection details (URL, org, bucket) **only if not already configured**

---

## High-level automated flow (executed by the agent)

1. **Run local PDF → CSV helper**
   - Execute the provided Python helper script against the supplied PDF.
   - Capture the resulting CSV path (`out/<pdfname>.csv`).
   - Treat the CSV as the canonical extracted source.

2. **Load and normalize CSV**
   - Expected columns:
     - `Date`
     - `Description`
     - `Amount`
   - Do not mutate original values.

3. **Generate deterministic transaction identity**
   - Compute `_id = sha256(date | description | amount)`
   - `_id` must be stable across re-runs.
   - Use `_id` consistently in all downstream systems.

4. **Categorize transactions (expenses only)**
   - Skip transactions with non-negative amounts.
   - Categorization order:
     1. Merchant memory (`merchants.md`)
     2. Keyword heuristics
     3. Brave Search lookup (merchant tokens only)
     4. Ask the user if still unknown
   - Persist new merchant → category mappings to `merchants.md`.

5. **Generate summaries**
   - Totals by category
   - Monthly totals
   - Optional rolling averages

6. **Sync to InfluxDB**
   - Write one point per transaction.
   - Measurement: `transactions`
   - Tags:
     - `_id`
     - `category`
     - `merchant`
   - Fields:
     - `amount`
   - Timestamp: parsed transaction date (UTC).
   - Skip writes if `_id` already exists in the bucket.

7. **Sync to Google Sheets (via goocli)**
   - Append one row per transaction if `_id` is not already present.
   - Recommended column layout:
     - Date
     - Description
     - Amount
     - Category
     - MerchantID (`_id`)
   - Use `gog sheets` commands.
   - Do not store raw credentials or tokens.

---

## Python helper contract (strict)

The Python helper script:

- Extracts transactions deterministically from moey! PDFs
- Emits a CSV file
- May optionally add *category hints* (non-authoritative)

The agent:

- Is the source of truth for categories
- May override Python hints
- Must not embed API keys, credentials, or side effects in Python
- Must not call InfluxDB or Google APIs from Python

---

## Categorization and privacy rules

- Never send amounts, dates, or user identifiers to external search APIs.
- Brave lookup queries must include **merchant tokens only**.
- Learned mappings must be stored locally in `merchants.md` using:
  - `merchant: <name> | category: <category> | notes: <optional>`

---

## Idempotency and safety guarantees

- All operations must be safe to re-run.
- InfluxDB writes must be guarded by `_id` existence checks.
- Google Sheets writes must skip existing `_id` rows.
- Never delete or overwrite historical data automatically.
- Fail fast and report errors only when human action is required:
  - Authentication failures
  - Permission issues
  - Unresolved merchants

---

## When to ask the user

- First-time setup of InfluxDB connection
- First-time setup of Google Sheets target
- Merchant cannot be categorized after all automated steps
- External API authentication or permission failures

---

## Skill output

After a successful run, report:

- CSV path generated
- Number of transactions processed
- Categories created or reused
- InfluxDB bucket written to
- Google Sheet updated

This skill is complete when the agent can ingest a moey! PDF end-to-end with **zero manual steps on repeat runs**.