Metadata-Version: 2.4
Name: beancount-gocardless
Version: 0.1.13
License-Expression: Unlicense
License-File: LICENSE
Requires-Python: <4,>=3.12
Requires-Dist: beancount
Requires-Dist: beangulp
Requires-Dist: pre-commit>=4.5.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml
Requires-Dist: requests
Requires-Dist: requests-cache
Requires-Dist: rich
Requires-Dist: textual-dev>=1.7.0
Requires-Dist: textual>=3.2.0
Provides-Extra: dev
Requires-Dist: myst-parser; extra == 'dev'
Requires-Dist: sphinx; extra == 'dev'
Requires-Dist: sphinx-rtd-theme; extra == 'dev'
Provides-Extra: lint
Requires-Dist: ruff>=0.9.8; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Description-Content-Type: text/markdown

beancount-gocardless
====================

GoCardless API client with models manually recreated from swagger spec, plus Beancount importer.

Inspired by https://github.com/tarioch/beancounttools.

Full documentation at https://beancount-gocardless.readthedocs.io/en/latest/.

**Key Features:**

- **API Client:** Models based on swagger spec. Built-in caching via `requests-cache`.
- **GoCardLess CLI**\: A command-line interface to manage authorization with the GoCardless API:

    - Listing available banks in a specified country (default: GB).
    - Creating a link to a specific bank using its ID.
    - Listing authorized accounts.
    - Deleting an existing link.
    - Uses environment variables (`GOCARDLESS_SECRET_ID`, `GOCARDLESS_SECRET_KEY`) or command-line arguments for API credentials.
- **Beancount Importer:**  A `beangulp.Importer` implementation to easily import transactions fetched from the GoCardless API directly into your Beancount ledger.

You'll need to create a GoCardLess account on https://bankaccountdata.gocardless.com/overview/ to get your credentials.

## Development

### API Coverage

The GoCardless client tries to provide complete API coverage with Pydantic models for all endpoints and data structures.
Models are manually recreated from the swagger spec, providing type-safe access to every API feature.

**Installation:**

```bash
pip install beancount-gocardless
```

**Usage**
```yaml
#### gocardless.yaml
secret_id: $GOCARDLESS_SECRET_ID
secret_key: $GOCARDLESS_SECRET_KEY

cache_options: # by default, no caching if cache_options is not provided
  cache_name: "gocardless"
  backend: "sqlite"
  expire_after: 3600
  old_data_on_error: true

accounts:
    - id: <REDACTED_UUID>
      asset_account: "Assets:Banks:Revolut:Checking"
      transaction_types: ["booked", "pending"]  # optional list, defaults to both
      preferred_balance_type: "interimAvailable"  # optional, use specific balance type
```

```python
#### my.import
#!/usr/bin/env python

import beangulp
from beancount_gocardless import GoCardLessImporter
from smart_importer import PredictPostings, PredictPayees

importers = [
    GoCardLessImporter()
]

hooks = [
    PredictPostings().hook,
    PredictPayees().hook,
]

if __name__ == "__main__":
    ingest = beangulp.Ingest(importers, hooks=hooks)
    ingest()
```

Import your data from GoCardLess's API
```bash
python my.import extract ./gocardless.yaml --existing ./ledger.bean
```
