Metadata-Version: 2.4
Name: ab-ecosystem-python
Version: 0.1.2
Summary: Python SDK for the Partner Ecosystem: JWKS-based auth verification and server-to-server actions.
Project-URL: Homepage, https://github.com/automationsbuilder/ab-ecosystem-python
Project-URL: Issues, https://github.com/automationsbuilder/ab-ecosystem-python/issues
Author: automationsbuilder
License: MIT
License-File: LICENSE
Keywords: auth,jwks,jwt,partner-ecosystem,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Requires-Dist: pyjwt[crypto]>=2.8
Description-Content-Type: text/markdown

# ab-ecosystem-python

Python SDK for the Partner Ecosystem: JWKS-based auth verification and
server-to-server actions.

## Install

```bash
pip install ab-ecosystem-python
```

## Quick start

Initialise once at start-up, then call the user methods anywhere — either via
the module-level helpers (they use the process-wide singleton) or on the client
returned by `init`.

```python
from ab_ecosystem import init, get_user_profile, get_user_subscription

init(
    api_url="https://api.example.com",
    project_id="proj_123",
    project_secret="super-secret",
)

# module-level (singleton)
profile = get_user_profile(access_token=user_jwt)

# or on the instance
client = init(api_url="...", project_id="...", project_secret="...")
subscription = client.get_user_subscription(access_token=user_jwt)
```

## Methods

| Method                      | Endpoint                                                        |
| --------------------------- | --------------------------------------------------------------- |
| `get_user_profile()`        | `GET /api/v1/projects/:project_id/me`                           |
| `get_user_wallet()`         | `GET /api/v1/projects/:project_id/me`                           |
| `get_user_credit_wallet()`  | `GET /api/v1/projects/:project_id/credit-wallets`               |
| `get_user_subscription()`   | `GET /api/v1/projects/:project_id/subscription`                 |
| `send_deduction_request()`  | `POST /api/v1/projects/:project_id/credit-wallets/:wallet_id/deduct` |
| `ping()`                    | `GET /ping`                                                     |

`:project_id` is filled from your config. Every call sends the project
credentials via HTTP Basic auth plus the `x-project-id` header.

### Per-user authentication

Each user method accepts `access_token` and `user_id`:

- `access_token` (the end-user's JWT) → forwarded as `Authorization: Bearer <token>`.
- `user_id` (when no `access_token`) → keeps the project HTTP Basic auth and adds
  a `user-id` header so the API can resolve the user.
- neither → project HTTP Basic auth only.

```python
sdk.get_user_profile(access_token=user_jwt)
sdk.get_user_profile(user_id="user_123")
```

### Deductions

```python
from ab_ecosystem import send_deduction_request, DeductionRequest

# amount is required; meta / reference / note default to {} / "" / ""
send_deduction_request(
    "wallet_1",
    DeductionRequest(amount=10, meta={"order_id": "o_1"}, reference="ref_1", note="usage"),
    user_id="user_123",
)

# a plain dict works too
send_deduction_request("wallet_1", {"amount": 5}, access_token=user_jwt)
```

## Verifying incoming tokens

The Node SDK ships an Express middleware; in Python the framework-agnostic core
is exposed instead, so you can wire it into Flask, FastAPI, Django, etc.

```python
from ab_ecosystem import verify_token, extract_bearer_token

token = extract_bearer_token(request.headers.get("authorization"))
claims = verify_token(token)          # raises jwt.PyJWTError on failure
```

## License

MIT
