Metadata-Version: 2.4
Name: finos-automation-sdk
Version: 0.1.1
Summary: FinOS automation client SDK — Clerk M2M token minting, Ledger/Platform API clients, and Sentry telemetry for automation scripts (Spec 035 / FINOS-214)
Author: FinOS
Keywords: automation,clerk,finos,sdk,windmill
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.13
Requires-Dist: attrs>=23.0.0
Requires-Dist: clerk-backend-api>=3.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyjwt[crypto]>=2.13.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: structlog>=26.1.0
Provides-Extra: telemetry
Requires-Dist: sentry-sdk>=2.61.1; extra == 'telemetry'
Description-Content-Type: text/markdown

# finos-automation-sdk

The FinOS automation client SDK (import name **`finos.automation`**). Automation
scripts import it to follow the FinOS automation calling contract without
re-implementing it: it calls only the public Ledger and Platform API endpoints
over HTTPS with a Clerk-signed bearer token, and grants no capability the API
would not already grant that token.

It is **standalone** — it depends only on PyPI packages, so it installs anywhere
(e.g. on a Windmill worker) without the FinOS monorepo:

```bash
pip install finos-automation-sdk            # API calling + token minting
pip install "finos-automation-sdk[telemetry]"   # + Sentry telemetry

# Pre-release dry runs are published to TestPyPI:
pip install -i https://test.pypi.org/simple/ finos-automation-sdk
```

## Three independent capabilities

```python
# API calling (any automation) — built from a JWT the caller already has.
from finos.automation import FinOSAPIClient
async with FinOSAPIClient(received_jwt) as api:
    ledgers = await api.ledger.ledgers.list_ledgers()
    me = await api.platform.users.read_own_profile()

# Token generation (dispatcher only) — Clerk M2M, hidden behind TokenMinter.
from finos.automation import TokenMinter
minter = TokenMinter()                       # CLERK_MACHINE_SECRET_KEY from env
obo = await minter.mint_for_user("user_123") # signed on_behalf_of claim

# Telemetry (every client) — optional Sentry extra, safe no-op without a DSN.
from finos.automation import init_telemetry, TelemetryContext
init_telemetry(context=TelemetryContext("import-csv", run_id, "manual"))
```

Plus `verify_user_token` (JWKS verification of a received token) and a typed error
taxonomy in `finos.automation.errors`.

Operations under `api.ledger` / `api.platform` are **reflected** from the
OpenAPI-generated clients by tag (`api.<service>.<tag>.<operation>(...)`), so no
operation is hand-written and none needs re-writing when the clients are
regenerated.

## Configuration

Every constructor argument is optional and falls back to an environment variable
when `None`. The one value with no env fallback is the API client's JWT — it is
always passed by the caller.

| Env var | Used by |
|---|---|
| `CLERK_MACHINE_SECRET_KEY` | `TokenMinter` |
| `LEDGER_API_URL` / `PLATFORM_API_URL` | `FinOSAPIClient` base URLs |
| `SENTRY_DSN` / `SENTRY_ENVIRONMENT` | `init_telemetry` (optional) |

## License

MIT
