Metadata-Version: 2.4
Name: suredata-client
Version: 0.1.4
Summary: Python client and CLI for extracting data from the Sure Finance API
Requires-Python: >=3.14
Requires-Dist: boto3>=1.43.27
Requires-Dist: httpx>=0.28
Requires-Dist: typer>=0.15
Provides-Extra: dev
Requires-Dist: pytest-httpx>=0.35; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Description-Content-Type: text/markdown

# suredata-client

Python package and CLI for extracting data from the [Sure Finance API](https://github.com/we-promise/sure).

## Install

```bash
uv sync --all-extras
```

## Configuration

| Variable | Description |
| -------- | ----------- |
| `SURE_BASE_URL` | API base URL (default: `https://app.sure.am`) |
| `SURE_API_KEY` | API key sent as `X-Api-Key` |
| `SURE_S3_ENDPOINT_URL` | Optional S3-compatible endpoint URL for `export --s3-uri` |
| `SURE_S3_REGION` | Optional S3 region override for `export --s3-uri` |
| `SURE_S3_PROFILE` | Optional AWS config/credentials profile for `export --s3-uri` |
| `SURE_S3_PATH_STYLE` | Optional path-style addressing toggle for S3-compatible storage |

CLI flags `--base-url` and `--api-key` override Sure API environment variables. S3 uploads use standard boto3/AWS credential resolution, plus optional `--s3-profile`, `--s3-endpoint-url`, `--s3-region`, and `--s3-path-style/--no-s3-path-style` overrides.

## CLI

```bash
# List supported resources
suredata-client resources

# List one page of accounts
export SURE_API_KEY=your-key
suredata-client list accounts --page 1 --per-page 25

# Fetch all pages as JSON with resource-specific filters
suredata-client list transactions --all -o json --filter account_id=<uuid> --filter start_date=2026-01-01

# Stream JSONL to a file (container-friendly)
suredata-client list categories --all -o jsonl -f /data/categories.jsonl

# Export typed JSON directly to AWS S3 using standard AWS credentials/profile resolution
suredata-client export accounts --s3-uri s3://my-bucket/exports/accounts.json
suredata-client export accounts --s3-profile work --s3-uri s3://my-bucket/exports/accounts.json

# Export to S3-compatible storage such as MinIO
SURE_S3_ENDPOINT_URL=https://minio.example.com \
SURE_S3_REGION=us-east-1 \
SURE_S3_PROFILE=minio \
SURE_S3_PATH_STYLE=true \
suredata-client export accounts --s3-uri s3://my-bucket/exports/accounts.json

# Show documented filters for all resources or one resource
suredata-client filters
suredata-client filters transactions
suredata-client resources --filters

# Get a single record, with detail filters when the API supports them
suredata-client get accounts <uuid> --filter include_disabled=true

# Balance sheet
suredata-client balance-sheet
```

### Docker-style usage

```bash
docker run --rm \
  -e SURE_API_KEY \
  -e SURE_BASE_URL=https://app.sure.am \
  suredata-client:latest \
  list transactions --all -o jsonl -f /out/transactions.jsonl
```

## Python API

```python
from suredata_client import SureClient, load_settings
from suredata_client.endpoints import Endpoints

settings = load_settings()  # reads SURE_* env vars
with SureClient(settings) as client:
    api = Endpoints(client)
    for account in api.iter_all("accounts"):
        print(account["name"])
```

## Development

```bash
uv sync --all-extras
ruff format .
ruff check .
uvx ty check
pytest
```

## MVP resources

`accounts`, `transactions`, `categories`, `merchants`, `tags`, `balances`, `holdings`, `trades`, `transfers`, `budgets`, `valuations`, `syncs`, `imports`, `family_exports`, plus `balance-sheet`.
