Metadata-Version: 2.4
Name: zanii-connect
Version: 0.1.0
Summary: Python SDK for Zanii Connect — OAuth connections and tool execution for AI agents
Author: Zanii Agency
License: Proprietary
Project-URL: Homepage, https://vault.zanii.agency/api/docs
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0

# zanii-connect — Python SDK

Python client for [Zanii Connect](https://vault.zanii.agency/api/docs): OAuth connections,
encrypted token vault, and audited tool execution for AI agents.

## Install

```bash
pip install ./sdk/python          # from the monorepo
```

## Quickstart

```python
from zanii_connect import ZaniiClient

# Agents/services authenticate with a scoped API key:
nc = ZaniiClient(api_key="nsk_...")

# Or as a user (JWT):
nc = ZaniiClient(email="info@zanii.agency", password="...")

print(nc.me()["organization"]["name"])

# Connect a provider (open the returned URL in a browser to complete OAuth):
url = nc.connect("gmail", redirect_url="https://vault.zanii.agency/api/v1/connect/oauth/callback")["url"]

# Discover tools and execute one:
conn = nc.connections()["connections"][0]
found = nc.execute("gmail.search", connection_id=conn["id"], parameters={"query": "invoice"})

# Actions that need human approval return an approval link instead of executing:
res = nc.execute("gmail.sendEmail", connection_id=conn["id"],
                 parameters={"to": "info@zanii.agency", "subject": "Hi", "body": "Hello"})
if res.get("requires_approval"):
    print("Ask a human to confirm:", res["approval_url"])

# Long-running work goes through the job queue:
job = nc.execute_async("browser.run", connection_id=conn["id"], parameters={...})
result = nc.wait_for_job(job["job_id"], timeout=300)
```

### Async

```python
from zanii_connect import AsyncZaniiClient

async with AsyncZaniiClient(api_key="nsk_...") as nc:
    tools = await nc.tools()
```

Same methods as the sync client; with email/password call `await nc.login(email, password)` once after construction.

## Behavior

- **Retries**: 429/502/503/504 are retried up to 3 times with exponential backoff.
- **Idempotency**: pass `idempotency_key=` to `execute()` to make retries safe for side-effecting actions.
- **Errors**: non-2xx responses raise `ZaniiError` with `.status_code` and `.detail`.
- **MCP**: AI agents that speak MCP don't need this SDK — point them at
  `POST https://vault.zanii.agency/api/v1/mcp` with an `X-API-Key` header.

## Surface

Covers the full API:

- **Account**: `signup`, `login`, `me`, `update_profile`, `change_password`, `forgot_password`, `reset_password`, email verification, MFA (`mfa_enroll`/`mfa_enable`/`mfa_disable`)
- **API keys**: `create_api_key` (plaintext returned once), `api_keys`, `delete_api_key`
- **Org & team**: `org`, `usage`, `update_org`, `export_org`, `delete_org`, `users`, `invite_user`, `update_user`, `deactivate_user`, roles (`permissions`, `roles`, `upsert_role`, `delete_role`), workspaces/projects/environments
- **Registry**: `providers`, `provider`, `provider_actions`, `actions`, `action`, `tools`, `tool`, dynamic-registry admin (`register_provider`, `register_action`, `unregister_action`)
- **Connections**: `connect`, `connections`, `connections_health`, `delete_connection`, `share_connection`
- **Execution**: `execute`, `execute_async`, `job`, `wait_for_job` · approvals (`approvals`, `approve`)
- **Browser sandbox**: `create_browser_session`, `browser_session`, `browser_run`, `browser_run_async`
- **Secrets / automation**: `secrets`, `set_secret`, `delete_secret`, triggers, webhook subscriptions
- **Observability**: `executions`, `audit`, `audit_export_csv`, `health`
