Metadata-Version: 2.4
Name: zanii-connect
Version: 0.2.0
Summary: Python SDK for Zanii Connect — OAuth connections and tool execution for AI agents
Author-email: Zanii Agency <info@zanii.agency>
License: MIT
Project-URL: Homepage, https://vault.zanii.agency
Project-URL: Documentation, https://vault.zanii.agency/api/docs
Keywords: zanii,oauth,mcp,ai-agents,connectors,api-client,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Dynamic: license-file

# 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 zanii-connect
```

Requires Python 3.10+.

## 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` (each row carries `receipt_hash` + `proof_url`), `audit`, `audit_export_csv`, `health`
- **Proof-of-action**: `receipts_bundle` (offline-verifiable audit bundle), `compliance_report` (json/markdown)

## License

MIT © Zanii Agency
