Metadata-Version: 2.4
Name: plexus-sdk
Version: 0.1.6
Summary: Python SDK for the Plexus school-administration platform — typed Convex client + API-token auth.
Requires-Python: >=3.12
Requires-Dist: convex-rpc==0.1.3
Description-Content-Type: text/markdown

# plexus-sdk

Typed Python SDK for the **Plexus** school-administration platform. It speaks to
the platform's self-hosted Convex backend over the standard HTTP RPC plane
(`/api/query|mutation|action`) and authenticates with an **API token** you mint in
the app.

It is intentionally dependency-light (`httpx` + `pydantic` only) so you can drop it
into scripts, data pipelines, or your own tools. The `plexus-cli` command-line tool
is a thin layer on top of this SDK.

## Install

```bash
uv pip install plexus-sdk \
  --extra-index-url https://gitea.i.ivo-zilkenat.de/api/packages/ivo.zilkenat/pypi/simple/
```

## Get a token

In the Plexus app: **Settings → API-Token → create**. Copy the `plx_…` value (it is
shown only once). The token maps to **your user**, so it carries your permissions
across every tenant you can reach (a platform-admin token reaches all of them).

## Use

```python
from plexus_sdk import PlexusClient

client = PlexusClient(
    convex_url="https://db.edos.schule",          # /api/query|mutation|action
    site_url="https://actions.db.edos.schule",     # /cli/token (auth exchange)
    token="plx_…",
)

# Who am I? (identity + permissions)
me = client.query("permissions:currentUserAccess", {})

# Search persons in a tenant
people = client.query("parties:listForMain", {"client": "<tenant-slug>", "q": "Müller"})
```

`PlexusClient` exchanges the opaque token for a short-lived JWT on first use,
caches it in memory, and refreshes automatically on expiry. Convex errors are
raised as `PlexusError` (never swallowed).

### From environment variables

```python
import os
from plexus_sdk import Config, PlexusClient

os.environ.update(
    PLEXUS_CONVEX_URL="https://db.edos.schule",
    PLEXUS_SITE_URL="https://actions.db.edos.schule",
    PLEXUS_TOKEN="plx_…",
)
client = PlexusClient.from_config(Config.from_env())
```

## Typed models

`plexus_sdk.models` contains generated Pydantic models for the platform's **public**
functions' arguments and return shapes. They are generated from the Convex
function-spec (`scripts/regen-models.sh`) and curated to the public surface — do
not hand-edit `models.py`.

## Notes

- The backend uses `edos*` identifiers internally (issuer, deployment) for
  historical reasons; you only ever need the two URLs above and your token.
- Subscriptions/real-time are not supported by this SDK (HTTP RPC only).
