atlas-backend 0.1.0__tar.gz

atlas_backend-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+build/
+dist/

atlas_backend-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: atlas-backend
+Version: 0.1.0
+Summary: Official Python backend SDK for Atlas — a typed client over the sk_ Backend API (BAPI).
+Author: Atlas
+License: MIT
+Keywords: atlas,auth,authentication,backend,bapi,sdk
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.23
+Provides-Extra: dev
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# atlas-backend
+
+The official **Python backend SDK** for Atlas — a typed client over the `sk_`
+Backend API (BAPI). It is the Python peer of the TypeScript `@atlas/backend`
+SDK and mirrors it namespace-for-namespace.
+
+- Typed (`py.typed`), one namespace per BAPI area.
+- Sync `AtlasClient` **and** async `AsyncAtlasClient`, built on `httpx`.
+- The `{ errors: [{ code, message, param }] }` envelope surfaces as `AtlasError`.
+- Cursor pagination helper, `Idempotency-Key` on creates.
+
+## Install
+
+```bash
+pip install atlas-backend
+```
+
+## Quick start
+
+```python
+from atlas_backend import AtlasClient, AtlasError, paginate
+
+atlas = AtlasClient("sk_live_...", base_url="https://api.atlasauth.net")
+
+# Create a user (idempotency key optional, forwarded as Idempotency-Key).
+user = atlas.users.create(
+    {"email_address": "ada@example.com", "first_name": "Ada"},
+    idempotency_key="signup-ada-001",
+)
+print(user["id"])
+
+# List organizations (a single cursor page).
+page = atlas.organizations.list(limit=20)
+print(page["data"], page["has_more"], page["next_cursor"])
+
+# Auto-iterate every page.
+for org in paginate(atlas.organizations.list):
+    print(org["name"])
+
+# Errors carry the HTTP status and the stable BAPI error code.
+try:
+    atlas.users.get("user_does_not_exist")
+except AtlasError as err:
+    print(err.status)          # e.g. 404
+    print(err.code)            # e.g. "NOT_FOUND"
+    print(err.errors[0].get("param"))
+    if err.has_code("NOT_FOUND"):
+        ...
+```
+
+### Context manager
+
+```python
+with AtlasClient("sk_live_...") as atlas:
+    atlas.users.list(limit=10)
+# underlying httpx.Client is closed on exit
+```
+
+## Async
+
+```python
+import asyncio
+from atlas_backend import AsyncAtlasClient, acollect
+
+async def main() -> None:
+    async with AsyncAtlasClient("sk_live_...") as atlas:
+        user = await atlas.users.create({"email_address": "grace@example.com"})
+        orgs = await acollect(atlas.organizations.list)
+        print(user["id"], len(orgs))
+
+asyncio.run(main())
+```
+
+## Configuration
+
+| Argument      | Default                   | Notes                                            |
+| ------------- | ------------------------- | ------------------------------------------------ |
+| `secret_key`  | —                         | `sk_...`; sent as `Authorization: Bearer <key>`. |
+| `base_url`    | `https://api.atlasauth.net`   | The instance's BAPI origin (`BAPI_ORIGIN`).      |
+| `timeout`     | `30.0`                    | Per-request timeout, seconds.                    |
+| `http_client` | a new `httpx.Client`      | Pass your own for pooling / proxies / retries.   |
+
+## Namespaces
+
+`users`, `sessions`, `organizations` (+ `memberships`, `invitations`,
+`domains`, `group_roles`), `roles`, `permissions`, `oauth_clients` (+ `grants`),
+`resource_servers`, `sso_connections`, `scim_tokens`, `domains`, `waitlist`,
+`allowlist`, `blocklist`, `attack_protection`, `actor_tokens`, `invitations`,
+`webhooks` (+ `endpoints`), `sign_in_tokens`, `audit_logs`, `jwt_templates`.
+
+## Pagination
+
+`paginate(list_fn, **params)` and `collect(list_fn, **params)` walk every
+cursor page of any `list` that returns `{ data, has_more, next_cursor }`. Async
+peers: `aiterate` / `acollect`.
+
+## Errors
+
+Every non-2xx raises `AtlasError`, carrying:
+
+- `status` — the HTTP status code.
+- `errors` — the full `[{ code, message, param?, meta? }]` envelope.
+- `code` — the first error's stable code (what you branch on).
+- `has_code(code)` — True if any error in the envelope has that code.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+mypy .
+pytest
+```

atlas_backend-0.1.0/README.md

@@ -0,0 +1,113 @@
+# atlas-backend
+
+The official **Python backend SDK** for Atlas — a typed client over the `sk_`
+Backend API (BAPI). It is the Python peer of the TypeScript `@atlas/backend`
+SDK and mirrors it namespace-for-namespace.
+
+- Typed (`py.typed`), one namespace per BAPI area.
+- Sync `AtlasClient` **and** async `AsyncAtlasClient`, built on `httpx`.
+- The `{ errors: [{ code, message, param }] }` envelope surfaces as `AtlasError`.
+- Cursor pagination helper, `Idempotency-Key` on creates.
+
+## Install
+
+```bash
+pip install atlas-backend
+```
+
+## Quick start
+
+```python
+from atlas_backend import AtlasClient, AtlasError, paginate
+
+atlas = AtlasClient("sk_live_...", base_url="https://api.atlasauth.net")
+
+# Create a user (idempotency key optional, forwarded as Idempotency-Key).
+user = atlas.users.create(
+    {"email_address": "ada@example.com", "first_name": "Ada"},
+    idempotency_key="signup-ada-001",
+)
+print(user["id"])
+
+# List organizations (a single cursor page).
+page = atlas.organizations.list(limit=20)
+print(page["data"], page["has_more"], page["next_cursor"])
+
+# Auto-iterate every page.
+for org in paginate(atlas.organizations.list):
+    print(org["name"])
+
+# Errors carry the HTTP status and the stable BAPI error code.
+try:
+    atlas.users.get("user_does_not_exist")
+except AtlasError as err:
+    print(err.status)          # e.g. 404
+    print(err.code)            # e.g. "NOT_FOUND"
+    print(err.errors[0].get("param"))
+    if err.has_code("NOT_FOUND"):
+        ...
+```
+
+### Context manager
+
+```python
+with AtlasClient("sk_live_...") as atlas:
+    atlas.users.list(limit=10)
+# underlying httpx.Client is closed on exit
+```
+
+## Async
+
+```python
+import asyncio
+from atlas_backend import AsyncAtlasClient, acollect
+
+async def main() -> None:
+    async with AsyncAtlasClient("sk_live_...") as atlas:
+        user = await atlas.users.create({"email_address": "grace@example.com"})
+        orgs = await acollect(atlas.organizations.list)
+        print(user["id"], len(orgs))
+
+asyncio.run(main())
+```
+
+## Configuration
+
+| Argument      | Default                   | Notes                                            |
+| ------------- | ------------------------- | ------------------------------------------------ |
+| `secret_key`  | —                         | `sk_...`; sent as `Authorization: Bearer <key>`. |
+| `base_url`    | `https://api.atlasauth.net`   | The instance's BAPI origin (`BAPI_ORIGIN`).      |
+| `timeout`     | `30.0`                    | Per-request timeout, seconds.                    |
+| `http_client` | a new `httpx.Client`      | Pass your own for pooling / proxies / retries.   |
+
+## Namespaces
+
+`users`, `sessions`, `organizations` (+ `memberships`, `invitations`,
+`domains`, `group_roles`), `roles`, `permissions`, `oauth_clients` (+ `grants`),
+`resource_servers`, `sso_connections`, `scim_tokens`, `domains`, `waitlist`,
+`allowlist`, `blocklist`, `attack_protection`, `actor_tokens`, `invitations`,
+`webhooks` (+ `endpoints`), `sign_in_tokens`, `audit_logs`, `jwt_templates`.
+
+## Pagination
+
+`paginate(list_fn, **params)` and `collect(list_fn, **params)` walk every
+cursor page of any `list` that returns `{ data, has_more, next_cursor }`. Async
+peers: `aiterate` / `acollect`.
+
+## Errors
+
+Every non-2xx raises `AtlasError`, carrying:
+
+- `status` — the HTTP status code.
+- `errors` — the full `[{ code, message, param?, meta? }]` envelope.
+- `code` — the first error's stable code (what you branch on).
+- `has_code(code)` — True if any error in the envelope has that code.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+mypy .
+pytest
+```

atlas_backend-0.1.0/atlas_backend/__init__.py

@@ -0,0 +1,55 @@
+"""atlas-backend — the official Python backend SDK for Atlas.
+
+A typed client over the ``sk_`` Backend API (BAPI), the Python peer of the
+TypeScript ``@atlas/backend`` SDK.
+
+    from atlas_backend import AtlasClient, AtlasError
+
+    atlas = AtlasClient("sk_live_...")
+    user = atlas.users.create({"email_address": "ada@example.com"})
+    for org in paginate(atlas.organizations.list):
+        print(org["name"])
+"""
+
+from __future__ import annotations
+
+from ._client import AsyncAtlasClient, AtlasClient
+from ._errors import AtlasError, ErrorItem
+from ._handshake import (
+    HandshakeParams,
+    HandshakeSession,
+    PKCEPair,
+    aredeem_handshake,
+    create_pkce_pair,
+    read_handshake_params,
+    redeem_handshake,
+)
+from ._pagination import acollect, aiterate, collect, paginate
+from ._transport import DEFAULT_BASE_URL
+from ._types import CursorPage, DeletedObject, ListPage, Metadata
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AtlasClient",
+    "AsyncAtlasClient",
+    "AtlasError",
+    "ErrorItem",
+    "DEFAULT_BASE_URL",
+    "paginate",
+    "collect",
+    "aiterate",
+    "acollect",
+    "CursorPage",
+    "ListPage",
+    "DeletedObject",
+    "Metadata",
+    "HandshakeSession",
+    "HandshakeParams",
+    "PKCEPair",
+    "create_pkce_pair",
+    "redeem_handshake",
+    "aredeem_handshake",
+    "read_handshake_params",
+    "__version__",
+]

atlas_backend-0.1.0/atlas_backend/_client.py

@@ -0,0 +1,139 @@
+"""The typed management clients for the Atlas Backend API.
+
+:class:`AtlasClient` is the secret-key surface — the Python peer of the official
+TypeScript SDK's ``createAtlasClient``. Each namespace is one attribute handing
+the shared, config-bound transport to a resource class, so this file reads as a
+table of contents for the whole surface. :class:`AsyncAtlasClient` is the same
+surface over ``asyncio``.
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+
+import httpx
+
+from . import aresources as ar
+from . import resources as r
+from ._transport import DEFAULT_BASE_URL, _AsyncTransport, _SyncTransport
+
+
+class AtlasClient:
+    """Synchronous Backend API client.
+
+    Args:
+        secret_key: The instance secret key (``sk_...``). Sent as
+            ``Authorization: Bearer <key>`` on every request; never logged,
+            never placed in a URL.
+        base_url: Base URL of the instance's Backend API. Defaults to
+            ``https://api.atlasauth.net``. Trailing slashes are tolerated.
+        timeout: Per-request timeout in seconds.
+        http_client: An optional pre-configured :class:`httpx.Client` (for
+            connection pooling, proxies, retries). One is created if omitted.
+    """
+
+    def __init__(
+        self,
+        secret_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        if not secret_key:
+            raise ValueError("AtlasClient requires a secret_key.")
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout)
+        transport = _SyncTransport(secret_key, base_url, self._http)
+
+        self.users = r.Users(transport)
+        self.sessions = r.Sessions(transport)
+        self.organizations = r.Organizations(transport)
+        self.roles = r.Roles(transport)
+        self.permissions = r.Permissions(transport)
+        self.oauth_clients = r.OAuthClients(transport)
+        self.resource_servers = r.ResourceServers(transport)
+        self.sso_connections = r.SsoConnections(transport)
+        self.scim_tokens = r.ScimTokens(transport)
+        self.domains = r.Domains(transport)
+        self.waitlist = r.Waitlist(transport)
+        self.allowlist = r._Restriction(transport, "/v1/allowlist_identifiers")
+        self.blocklist = r._Restriction(transport, "/v1/blocklist_identifiers")
+        self.attack_protection = r.AttackProtection(transport)
+        self.actor_tokens = r.ActorTokens(transport)
+        self.invitations = r.Invitations(transport)
+        self.webhooks = r.Webhooks(transport)
+        self.sign_in_tokens = r.SignInTokens(transport)
+        self.audit_logs = r.AuditLogs(transport)
+        self.jwt_templates = r.JwtTemplates(transport)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client, if this client created it."""
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> AtlasClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncAtlasClient:
+    """Asynchronous Backend API client — the ``asyncio`` peer of :class:`AtlasClient`."""
+
+    def __init__(
+        self,
+        secret_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        if not secret_key:
+            raise ValueError("AsyncAtlasClient requires a secret_key.")
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+        transport = _AsyncTransport(secret_key, base_url, self._http)
+
+        self.users = ar.AsyncUsers(transport)
+        self.sessions = ar.AsyncSessions(transport)
+        self.organizations = ar.AsyncOrganizations(transport)
+        self.roles = ar.AsyncRoles(transport)
+        self.permissions = ar.AsyncPermissions(transport)
+        self.oauth_clients = ar.AsyncOAuthClients(transport)
+        self.resource_servers = ar.AsyncResourceServers(transport)
+        self.sso_connections = ar.AsyncSsoConnections(transport)
+        self.scim_tokens = ar.AsyncScimTokens(transport)
+        self.domains = ar.AsyncDomains(transport)
+        self.waitlist = ar.AsyncWaitlist(transport)
+        self.allowlist = ar._AsyncRestriction(transport, "/v1/allowlist_identifiers")
+        self.blocklist = ar._AsyncRestriction(transport, "/v1/blocklist_identifiers")
+        self.attack_protection = ar.AsyncAttackProtection(transport)
+        self.actor_tokens = ar.AsyncActorTokens(transport)
+        self.invitations = ar.AsyncInvitations(transport)
+        self.webhooks = ar.AsyncWebhooks(transport)
+        self.sign_in_tokens = ar.AsyncSignInTokens(transport)
+        self.audit_logs = ar.AsyncAuditLogs(transport)
+        self.jwt_templates = ar.AsyncJwtTemplates(transport)
+
+    async def aclose(self) -> None:
+        """Close the underlying async HTTP client, if this client created it."""
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncAtlasClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()

atlas_backend-0.1.0/atlas_backend/_errors.py

@@ -0,0 +1,62 @@
+"""The single error type every Backend API call raises on a non-2xx.
+
+Atlas answers a failed BAPI call with the §9.1 envelope::
+
+    { "errors": [ { "code", "message", "param?", "meta?" } ] }
+
+``code`` is the stable, machine-readable part of that contract — integrators
+branch on it (``LAST_ADMIN``, ``NOT_FOUND``, ``SCOPE_MISSING``, ...) — so it is
+surfaced first-class here rather than buried in a parsed body. The raw
+``errors`` list and the HTTP ``status`` are both kept so a caller can inspect
+``param``/``meta`` (e.g. a rate limit's ``retry_after``) when they need to.
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+
+class ErrorItem(TypedDict, total=False):
+    """One entry of the BAPI error envelope."""
+
+    code: str
+    message: str
+    param: str
+    meta: dict[str, Any]
+
+
+class AtlasError(Exception):
+    """Raised on any non-2xx response from the Backend API.
+
+    Carries the HTTP ``status`` and the full parsed ``errors`` envelope. Branch
+    on :attr:`code` (the first error's stable code) or use :meth:`has_code`.
+    """
+
+    status: int
+    errors: list[ErrorItem]
+
+    def __init__(
+        self,
+        status: int,
+        errors: list[ErrorItem],
+        message: str | None = None,
+    ) -> None:
+        first_message = errors[0].get("message") if errors else None
+        super().__init__(
+            message
+            or first_message
+            or f"Atlas API request failed with status {status}"
+        )
+        self.status = status
+        self.errors = errors
+
+    @property
+    def code(self) -> str | None:
+        """The first error's stable code, the field callers branch on most."""
+        if not self.errors:
+            return None
+        return self.errors[0].get("code")
+
+    def has_code(self, code: str) -> bool:
+        """True when any error in the envelope carries the given stable code."""
+        return any(e.get("code") == code for e in self.errors)