# Budgero Python SDK

Official Python SDK for [Budgero](https://budgero.io) - Privacy-First Zero Based Budget Manager.

## Installation

```bash
pip install budgero
```

## Quick Start

```python
from budgero import BudgeroClient

# Initialize the client with your API key and encryption key
client = BudgeroClient(
    api_key="your-api-key",
    encryption_key="your-encryption-key",
)

# Add a transaction
result = client.add_transaction(
    account_id=1,
    category_id=5,
    budget_id=1,
    date="2024-11-27",
    outflow=50.00,
    memo="Weekly groceries",
    payee="Whole Foods",
)

print(f"Transaction queued: {result.queue_id}")
```

## Getting Your Credentials

1. Open the Budgero app
2. Go to **Settings > Integrations > Push API**
3. Generate a new API key
4. Copy both the API key and encryption key

## Features

- **End-to-end encryption**: All transaction data is encrypted client-side before being sent to the server
- **Type-safe**: Full type hints for IDE autocompletion and type checking
- **Simple API**: Easy-to-use methods for common operations
- **Self-hosted support**: Works with self-hosted Budgero instances

## Usage Examples

### Record an Expense

```python
client.add_transaction(
    account_id=1,
    category_id=5,  # Groceries
    budget_id=1,
    date="2024-11-27",
    outflow=50.00,
    memo="Weekly groceries",
    payee="Whole Foods",
)
```

### Record Income

```python
from datetime import date

client.add_transaction(
    account_id=1,
    category_id=10,  # Income category
    budget_id=1,
    date=date.today(),
    inflow=3000.00,
    memo="Monthly salary",
    payee="Acme Corp",
)
```

### Using Context Manager

```python
from budgero import BudgeroClient

with BudgeroClient(api_key="...", encryption_key="...") as client:
    client.add_transaction(
        account_id=1,
        category_id=5,
        budget_id=1,
        date="2024-11-27",
        outflow=25.00,
        memo="Coffee",
    )
# Client is automatically closed
```

### Check Queue Status

```python
# Get pending items
queue = client.get_queue()
for item in queue:
    print(f"{item.id}: {item.status}")

# Get statistics
stats = client.get_queue_stats()
print(f"Pending: {stats['pending']}")
```

### Self-Hosted Instance

```python
client = BudgeroClient(
    api_key="your-api-key",
    encryption_key="your-encryption-key",
    base_url="https://budgero.mycompany.com",
)
```

## API Reference

### BudgeroClient

#### `__init__(api_key, encryption_key, *, base_url, timeout)`

Initialize the client.

- `api_key`: Your Budgero Push API key
- `encryption_key`: Your encryption key (hex or base64 format)
- `base_url`: API base URL (default: `https://app.budgero.io`)
- `timeout`: Request timeout in seconds (default: 30)

#### `add_transaction(...)`

Add a new transaction to your budget.

- `account_id`: ID of the account
- `category_id`: ID of the category (None for transfers)
- `budget_id`: ID of the budget
- `date`: Transaction date (string or date object)
- `inflow`: Amount flowing in (default: 0)
- `outflow`: Amount flowing out (default: 0)
- `memo`: Description (default: "")
- `payee`: Payee name (optional)
- `transfer_id`: Transfer ID for linked transfers (optional)

#### `get_queue()`

Get pending items in the push queue.

#### `get_queue_stats()`

Get statistics about the push queue.

#### `clear_queue()`

Clear all items from the push queue.

#### `health_check()`

Check if the API is healthy.

#### `close()`

Close the client and release resources.

## Data Models

### TransactionInput

```python
from budgero import TransactionInput

tx = TransactionInput(
    account_id=1,
    category_id=5,
    budget_id=1,
    date="2024-11-27",
    inflow=0.0,
    outflow=50.00,
    memo="Groceries",
    payee="Store",
)
```

## Error Handling

```python
from budgero import BudgeroClient, AuthenticationError, APIError, ValidationError

try:
    client.add_transaction(...)
except AuthenticationError:
    print("Invalid API key")
except ValidationError as e:
    print(f"Invalid input: {e}")
except APIError as e:
    print(f"API error: {e} (HTTP {e.status_code})")
```

## Requirements

- Python 3.9+
- httpx
- pycryptodome

## License

MIT
