suredata-client (0.3.1)
Installation
pip install --index-url About this package
Python client and CLI for extracting data from the Sure Finance API
suredata-client
Python package and CLI for extracting data from the Sure Finance API.
Install
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 |
LOG_LEVEL |
JSON log level: DEBUG, INFO, WARNING, ERROR, or CRITICAL (default: INFO) |
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
# 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 -f /data/accounts.json
# Fetch all pages as JSON with resource-specific filters
suredata-client list transactions --all -o json -f /data/transactions.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> -f /data/account.json --filter include_disabled=true
# Balance sheet
suredata-client balance-sheet -f /data/balance-sheet.json
Data commands require --out-file/-f; export also accepts --s3-uri instead. Operational
logs are emitted as newline-delimited JSON on stderr for ingestion by OpenObserve and similar
systems. Set LOG_LEVEL to control verbosity.
Docker-style usage
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
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
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.