authpi-admin 0.3.0__py3-none-any.whl

authpi_admin/user_agent.py

@@ -0,0 +1,21 @@
+"""Build a User-Agent header string for the Admin SDK.
+
+Format: ``authpi-admin-py/<sdk-version> Python/<python-version> (<platform>; <arch>)``
+
+Example: ``authpi-admin-py/0.2.0 Python/3.11.5 (linux; x86_64)``
+"""
+
+from __future__ import annotations
+
+import platform
+import sys
+
+_SDK_NAME = "authpi-admin-py"
+
+
+def build_user_agent(sdk_version: str) -> str:
+    """Build the User-Agent string for this SDK."""
+    py_version = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    system = platform.system().lower()  # linux, darwin, windows
+    machine = platform.machine().lower()  # x86_64, arm64, etc.
+    return f"{_SDK_NAME}/{sdk_version} Python/{py_version} ({system}; {machine})"

authpi_admin-0.3.0.dist-info/METADATA

@@ -0,0 +1,285 @@
+Metadata-Version: 2.4
+Name: authpi-admin
+Version: 0.3.0
+Summary: Official Python Admin SDK for AuthPI Core API
+Project-URL: Homepage, https://authpi.com
+Project-URL: Documentation, https://docs.authpi.com/sdk/python/admin
+Project-URL: Repository, https://github.com/arbfay/authpi
+Author-email: AuthPI <hello@authpi.com>
+License: MIT
+Keywords: admin,api,authentication,authorization,authpi,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.34.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# authpi-admin
+
+Official Python Admin SDK for the AuthPI Core API.
+
+**Requirements:** Python 3.11+, async-only (`httpx` + `asyncio`)
+
+## Installation
+
+```bash
+pip install authpi-admin
+```
+
+## Quick Start
+
+```python
+from authpi_admin import AuthPIAdmin
+
+async with AuthPIAdmin(api_key="key_xxx") as admin:
+    # List issuers
+    page = await admin.issuers.list(limit=10)
+    print(page.data)
+
+    # Scope into an issuer and manage users
+    users = await admin.issuer("iss_xxx").users.list()
+
+    # Auto-paginate
+    async for user in admin.issuer("iss_xxx").users.list_all():
+        print(user)
+
+    # Create a user
+    user = await admin.issuer("iss_xxx").users.create({
+        "email": "alice@example.com",
+        "display_name": "Alice",
+    })
+```
+
+## Authentication
+
+### API Key (default)
+
+```python
+admin = AuthPIAdmin(api_key="key_xxx")
+```
+
+### Bearer Token
+
+For server-side applications authenticating on behalf of a user session:
+
+```python
+admin = AuthPIAdmin(
+    access_token="tok_xxx",
+    account_id="acc_xxx",
+)
+```
+
+With optional token refresh callback:
+
+```python
+async def refresh():
+    new_tokens = await my_refresh_logic()
+    return {"access_token": new_tokens.access_token}
+
+admin = AuthPIAdmin(
+    access_token="tok_xxx",
+    account_id="acc_xxx",
+    on_token_expired=refresh,
+)
+```
+
+When `on_token_expired` is provided, the SDK calls it on 401 responses and retries the request with the new token. Concurrent 401s are deduplicated — only one refresh runs at a time.
+
+## Scoped Client Pattern
+
+The SDK mirrors the API's resource hierarchy. Navigate with chained accessors:
+
+```python
+# Account-level resources
+await admin.issuers.list()
+await admin.webhooks.create({"url": "https://..."})
+await admin.events.list(limit=50)
+
+# Issuer scope
+iss = admin.issuer("iss_xxx")
+await iss.users.list()
+await iss.agents.create({"name": "bot"})
+await iss.clients.list()
+await iss.organizations.list()
+
+# User scope (nested under issuer)
+usr = admin.issuer("iss_xxx").user("usr_xxx")
+await usr.get()
+await usr.sessions.list()
+await usr.tokens.list()
+await usr.trusted_devices.list()
+await usr.verifiers.list()
+
+# Webhook scope
+wh = admin.webhook("wh_xxx")
+await wh.get()
+await wh.deliveries.list()
+```
+
+## Pagination
+
+List endpoints return a `Page` with cursor-based pagination:
+
+```python
+# Manual pagination
+page = await admin.issuer("iss_xxx").users.list(limit=25)
+print(page.data)        # list[dict]
+print(page.has_more)    # bool
+print(page.next_cursor) # str | None
+
+# Fetch next page
+if page.has_more:
+    next_page = await admin.issuer("iss_xxx").users.list(
+        limit=25, cursor=page.next_cursor
+    )
+
+# Auto-pagination (yields individual items across all pages)
+async for user in admin.issuer("iss_xxx").users.list_all():
+    print(user)
+```
+
+## Retries
+
+Read-only requests (GET, HEAD, OPTIONS) are automatically retried on 429, 502, 503, and 504 responses with exponential backoff. The `Retry-After` header is respected when present.
+
+```python
+# Default: retries enabled (3 attempts, 1s base delay, exponential backoff)
+admin = AuthPIAdmin(api_key="key_xxx")
+
+# Disable retries
+admin = AuthPIAdmin(api_key="key_xxx", retries=False)
+
+# Custom retry config
+admin = AuthPIAdmin(
+    api_key="key_xxx",
+    retries={"limit": 5, "delay": 0.5, "backoff": "linear"},
+)
+```
+
+Mutations (POST, PATCH, DELETE) are never retried automatically. Use idempotency keys and handle retries explicitly for writes.
+
+## ETags & Optimistic Concurrency
+
+GET responses include an `_etag` field. Pass it back on updates to prevent overwriting concurrent changes:
+
+```python
+user = await admin.issuer("iss_xxx").user("usr_xxx").get()
+
+# Conditional update — fails with PreconditionFailedError if modified
+await admin.issuer("iss_xxx").users.update(
+    "usr_xxx",
+    {"display_name": "Bob"},
+    if_match=user.get("_etag"),
+)
+```
+
+## Error Handling
+
+The SDK maps HTTP status codes to specific error classes:
+
+```python
+from authpi_admin import (
+    NotFoundError,
+    ValidationError,
+    AuthenticationError,
+    RateLimitError,
+    PreconditionFailedError,
+)
+
+try:
+    await admin.issuer("iss_xxx").user("usr_xxx").get()
+except NotFoundError:
+    print("User not found")
+except ValidationError as err:
+    print("Validation failed:", err.fields)
+except RateLimitError as err:
+    print(f"Retry after {err.retry_after} seconds")
+except AuthenticationError:
+    print("Invalid credentials")
+```
+
+### Error Hierarchy
+
+| Error | Status | Extra Fields | Retryable |
+|-------|--------|--------------|-----------|
+| `ApiError` | — | `error`, `error_description`, `status_code`, `retryable`, `reference`, `raw_body` | — |
+| `ValidationError` | 400, 422 | `fields` | No |
+| `AuthenticationError` | 401 | — | No |
+| `ForbiddenError` | 403 | — | No |
+| `NotFoundError` | 404 | — | No |
+| `ConflictError` | 409 | — | No |
+| `PreconditionFailedError` | 412 | `current_etag` | No |
+| `RateLimitError` | 429 | `retry_after` | Yes |
+| `InternalServerError` | 500 | — | No |
+| `BadGatewayError` | 502 | — | Yes |
+| `ServiceUnavailableError` | 503 | — | Yes |
+| `GatewayTimeoutError` | 504 | — | Yes |
+| `UnexpectedError` | other | — | No |
+| `ClosedClientError` | — | — | No |
+
+## Configuration
+
+```python
+from authpi_admin import AuthPIAdmin
+
+admin = AuthPIAdmin(
+    api_key="key_xxx",                          # or access_token + account_id
+    base_url="https://api.authpi.dev",          # default
+    timeout=30.0,                               # default, in seconds
+    default_headers={"X-Custom": "value"},      # optional extra headers
+    retries=True,                               # default (or False, or dict)
+)
+```
+
+### Custom httpx Client
+
+Inject a pre-configured `httpx.AsyncClient` for advanced use cases (proxies, certificates, connection pooling):
+
+```python
+import httpx
+from authpi_admin import AuthPIAdmin
+
+async with httpx.AsyncClient(proxies="http://proxy:8080") as http:
+    admin = AuthPIAdmin(api_key="key_xxx", http_client=http)
+    await admin.issuers.list()
+```
+
+### Context Manager
+
+The SDK supports async context managers for clean resource cleanup:
+
+```python
+async with AuthPIAdmin(api_key="key_xxx") as admin:
+    await admin.issuers.list()
+# httpx client is closed automatically
+```
+
+Or close manually:
+
+```python
+admin = AuthPIAdmin(api_key="key_xxx")
+try:
+    await admin.issuers.list()
+finally:
+    await admin.close()
+```
+
+## License
+
+MIT

authpi_admin-0.3.0.dist-info/RECORD

@@ -0,0 +1,40 @@
+authpi_admin/__init__.py,sha256=2C5Bh6FDEFWpHT8WRNpS3hkrRB58qBmpiUKHvreMaIo,1376
+authpi_admin/_version.py,sha256=Ev00lZsiXxyvPxcsC6QBTyMzWYtUIP2jbCYqmf9Q2G0,154
+authpi_admin/client.py,sha256=ThHq_OFMu7-sSqqzZ0VePBjLkvT_KNF70iGIYcCxuUM,5358
+authpi_admin/errors.py,sha256=J_gW7uqGYB6B3ww-2BFI86KawyObSC6gDq-lJQ-uqmA,6139
+authpi_admin/http_client.py,sha256=ktN5tpGio1AzIoobg-v4MuBInwh4yvt_9yTZBH0XjVg,10654
+authpi_admin/pagination.py,sha256=Mmb75qEN_wZ0YzCq-oz5EG-9zf93uyR2ydRdvv-6gYE,992
+authpi_admin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+authpi_admin/user_agent.py,sha256=WgFss0m362eVHBoxW5HZVmW_C5boPTtCsf5K21M9EVE,715
+authpi_admin/generated/__init__.py,sha256=UdYsTfHZInAbqsg9dq_DfifKFoBMFvjzU40f1ohZWug,1645
+authpi_admin/generated/models.py,sha256=shYd_IuEHbLe5P-aYp7vR8olNlUK2-UiXOMCjIrnoRI,9652
+authpi_admin/generated/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+authpi_admin/generated/resources/accounts.py,sha256=3L2VK_-aL1NkxgEkARjk5T2ma_zFGdq-fHkLj18zj40,4832
+authpi_admin/generated/resources/agents.py,sha256=ftyjSduF2M6E7AUAg9lLinxqwUJNfVzVm2xtx1j2mtc,5499
+authpi_admin/generated/resources/api_keys.py,sha256=dWPWrX7Pgfi8UbbxeWeqNgkqehNsJ40KD16rV43lVdI,6532
+authpi_admin/generated/resources/approvals.py,sha256=L02ZFApbwg1jeBe-_5bDTbILbUZ4Nhv6hBq4bpZAORw,3415
+authpi_admin/generated/resources/auth_methods.py,sha256=GIQ6qCwqtbr-nMmdl1lmNCr3t2aqVFJzX9USpKYMLZU,4512
+authpi_admin/generated/resources/clients.py,sha256=hccCOBJ1IGVCIwrGDh-gI63VyPJwlBM4KwtNFQT819M,6061
+authpi_admin/generated/resources/deliveries.py,sha256=Vs-AmSKBEWgucM9sZUSeUsvneXYaU9a_6L_-iWTZ9W0,2688
+authpi_admin/generated/resources/domains.py,sha256=X-Xj0gqR31sRNccxEvWseggWeIyR3q0dqaUFan5T01M,5989
+authpi_admin/generated/resources/events.py,sha256=atUfR6br_dwIRygVDKarA28t9c11SDRyBrCCELXhKSM,3582
+authpi_admin/generated/resources/groups.py,sha256=rRzFgnkzrKN9rYqGh4ghlcwSeWiPqdyV53GO2mg87oQ,4904
+authpi_admin/generated/resources/invitations.py,sha256=_Uufa5TuSnw1xQuW5-FiOjYh-vdbEruTj33mKx4sdXQ,6353
+authpi_admin/generated/resources/issuers.py,sha256=a-dXIpvS2xHbUJxI4a1aQqyqr3qsPF_njP7AOwz6t6o,4776
+authpi_admin/generated/resources/members.py,sha256=JIoAUR6MxxqCkHCVDpyCs_qlZE6KvkgOXfVXwWtBpV4,4731
+authpi_admin/generated/resources/notes.py,sha256=76xTKxtLmbbwOtgsnJQNY1QbnveecD2ly2zBJ2kyKV0,6034
+authpi_admin/generated/resources/organizations.py,sha256=I93MJDQdOCzFaADJk7IdcxHGNr5E7SfGr7A04WUWF1s,7811
+authpi_admin/generated/resources/sessions.py,sha256=Bmx-RycxHELhulZ62ZvEYpbU5dnC43dTTl4jShqJRwY,3981
+authpi_admin/generated/resources/tokens.py,sha256=RvHcuKC7uErcDRCvkLoI9PyKY-FUTvdnM62aUyD0ccs,2918
+authpi_admin/generated/resources/trusted_devices.py,sha256=0_BGxY812JM9g0LeCHNvInrGHuGbrIHZ6X6XVm8PwnA,3099
+authpi_admin/generated/resources/users.py,sha256=tEB-z0r7_s2VCTEqaXEcxBmRZfu72jYQhgKRE8ZeSaU,6996
+authpi_admin/generated/resources/verifiers.py,sha256=zw3_8__nr-hmfaS27pH_tcPGn3TtJ-oXJCF5IqYdkkQ,3084
+authpi_admin/generated/resources/webhooks.py,sha256=BMc1OLLW1TrsGwdI8DoPvu2CybVE5uJ4WLq-3WOWnOk,5105
+authpi_admin/generated/scopes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+authpi_admin/generated/scopes/agent_scope.py,sha256=xNiZO99PsOBr5cAz3mxYXIBjdteH5GzJzHEVSTWx3PM,2543
+authpi_admin/generated/scopes/issuer_scope.py,sha256=CJN3XUqEDc5o1bQHfcr_j3qNqxekGwEOjZnGWZxGW40,5859
+authpi_admin/generated/scopes/user_scope.py,sha256=2IPkqtK0pBFyi0VR6tVEPt0oXoUtXHyv9BsSxQjwibc,3330
+authpi_admin/generated/scopes/webhook_scope.py,sha256=nQvpG-1ohDF0tsMJWzIJ6XSwu7DIk2TmoIErvqXLRT4,2576
+authpi_admin-0.3.0.dist-info/METADATA,sha256=v3_hmviJWJSYsNPNAewsO5Iabxc5N3UNBu1gOZdtwgg,7684
+authpi_admin-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+authpi_admin-0.3.0.dist-info/RECORD,,

authpi_admin-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any