dominus-sdk-python 2.1.7__tar.gz → 2.2.0__tar.gz

{dominus_sdk_python-2.1.7 → dominus_sdk_python-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 2.1.7
+Version: 2.2.0
 Summary: Python SDK for the Dominus Orchestrator Platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License: Proprietary
@@ -29,31 +29,31 @@ Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
 
-# CB Dominus SDK
+# CB Dominus SDK for Python
 
-**Python SDK for the Dominus Orchestrator Platform**
+**Async Python SDK for the Dominus Orchestrator Platform**
 
 A unified, async-first Python SDK providing seamless access to all Dominus backend services including secrets management, database operations, caching, file storage, authentication, schema management, and structured logging.
 
 ## Features
 
 - **Namespace-based API** - Intuitive access via `dominus.db`, `dominus.redis`, `dominus.files`, etc.
-- **Async/Await** - Built for modern async Python applications
+- **Async/Await** - Built for modern async Python applications (asyncio)
 - **Automatic JWT Management** - Token minting, caching, and refresh handled transparently
 - **Resilience Built-in** - Circuit breaker, exponential backoff, and retry logic
-- **Typed Errors** - Specific error classes for different failure modes
+- **Cold Start Handling** - Special retry logic for orchestrator cold starts
+- **Typed Errors** - 9 specific error classes for different failure modes
 - **Secure by Default** - Client-side password hashing, encrypted cache, audit trail support
 
 ## Quick Start
 
 ```python
 from dominus import dominus
+import os
 
 # Set your token (or use DOMINUS_TOKEN environment variable)
-import os
 os.environ["DOMINUS_TOKEN"] = "your-psk-token"
 
-# Start using the SDK
 async def main():
     # Secrets
     db_url = await dominus.get("DATABASE_URL")
@@ -81,18 +81,32 @@ git clone https://github.com/carebridgesystems/cb-dominus-sdk.git
 pip install httpx bcrypt cryptography
 ```
 
+Or install via pip (when published):
+
+```bash
+pip install dominus-sdk-python
+```
+
+## Requirements
+
+- Python 3.9+
+- `httpx` - Async HTTP client
+- `bcrypt` - Password hashing
+- `cryptography` - Cache encryption
+
 ## Namespaces
 
 | Namespace | Service | Purpose |
 |-----------|---------|---------|
 | `dominus.secrets` | Warden | Secrets management |
 | `dominus.db` | Scribe | Database CRUD operations |
-| `dominus.redis` | Whisperer | Redis caching |
-| `dominus.files` | Archivist | Object storage (B2) |
-| `dominus.auth` | Guardian | Authentication & authorization |
+| `dominus.secure` | Scribe | Secure table access with audit logging |
+| `dominus.redis` | Whisperer | Redis caching & distributed locks |
+| `dominus.files` | Archivist | Object storage (Backblaze B2) |
+| `dominus.auth` | Guardian | Users, roles, scopes, tenants, pages, navigation |
 | `dominus.ddl` | Smith | Schema DDL & migrations |
-| `dominus.logs` | Herald | Structured logging |
-| `dominus.portal` | Portal | User auth & sessions |
+| `dominus.logs` | Herald | Structured logging (BetterStack) |
+| `dominus.portal` | Portal | User auth, sessions, profiles, navigation |
 | `dominus.courier` | Courier | Email delivery (Postmark) |
 | `dominus.open` | Scribe | Direct database access |
 | `dominus.health` | Health | Service health checks |
@@ -114,6 +128,10 @@ await dominus.secrets.delete("OLD_KEY")
 ### Database Operations
 
 ```python
+# List tables
+tables = await dominus.db.tables()
+tenant_tables = await dominus.db.tables(schema="tenant_acme")
+
 # Query with filters and pagination
 users = await dominus.db.query(
     "users",
@@ -133,6 +151,15 @@ user = await dominus.db.insert("users", {
 # Update
 await dominus.db.update("users", {"status": "inactive"}, filters={"id": user_id})
 
+# Delete
+await dominus.db.delete("users", filters={"id": user_id})
+
+# Bulk insert
+await dominus.db.bulk_insert("events", [
+    {"type": "login", "user_id": "123"},
+    {"type": "login", "user_id": "456"}
+])
+
 # Secure table access (requires audit reason)
 patients = await dominus.db.query(
     "patients",
@@ -145,9 +172,10 @@ patients = await dominus.db.query(
 ### Redis Caching
 
 ```python
-# Key-value operations
+# Key-value operations (TTL: min 60s, max 24h)
 await dominus.redis.set("user:123", {"name": "John"}, ttl=3600)
 value = await dominus.redis.get("user:123")
+await dominus.redis.delete("user:123")
 
 # Distributed locks
 if await dominus.redis.setnx("lock:job", "worker-1", ttl=60):
@@ -162,6 +190,7 @@ await dominus.redis.incr("page:views", delta=1)
 
 # Hash operations
 await dominus.redis.hset("user:123", "email", "john@example.com", ttl=3600)
+email = await dominus.redis.hget("user:123", "email")
 ```
 
 ### File Storage
@@ -181,6 +210,9 @@ url = download["download_url"]
 
 # List files
 files = await dominus.files.list(category="reports", prefix="2025/")
+
+# Delete file
+await dominus.files.delete(file_id=result["id"])
 ```
 
 ### Structured Logging
@@ -190,38 +222,67 @@ files = await dominus.files.list(category="reports", prefix="2025/")
 await dominus.logs.info("User logged in", {"user_id": "123"})
 await dominus.logs.error("Payment failed", {"order_id": "456"})
 
+# All log levels
+await dominus.logs.debug("Debug message", {"data": "..."})
+await dominus.logs.notice("Important notice", {})
+await dominus.logs.warn("Warning message", {})
+await dominus.logs.critical("Critical error", {})
+
+# With category
+await dominus.logs.info("Cache hit", {"key": "user:123"}, category="cache")
+
 # With exception context
 try:
     risky_operation()
 except Exception as e:
-    await dominus.logs.error("Operation failed", exception=e)
+    await dominus.logs.error("Operation failed", {}, exception=e)
+
+# Batch logging
+await dominus.logs.batch([
+    {"level": "info", "message": "Step 1 complete", "data": {}},
+    {"level": "info", "message": "Step 2 complete", "data": {}}
+])
 
 # Query logs
 errors = await dominus.logs.query(level="error", limit=100)
 ```
 
-### Authentication
+### Authentication & Authorization (Guardian)
 
 ```python
 # User management
-user = await dominus.auth.add_user(
+users = await dominus.auth.list_users()
+user = await dominus.auth.get_user(user_id="uuid")
+
+new_user = await dominus.auth.add_user(
     username="john",
     password="secure-password",
     email="john@example.com"
 )
 
+await dominus.auth.update_user("uuid", status="active")
+await dominus.auth.delete_user("uuid")
+
 # Role management
+roles = await dominus.auth.list_roles()
 role = await dominus.auth.add_role(
     name="Editor",
     scope_slugs=["read", "write", "publish"]
 )
 
+# Scope management
+scopes = await dominus.auth.list_scopes()
+
+# Tenant management
+tenants = await dominus.auth.list_tenants()
+categories = await dominus.auth.list_tenant_categories()
+
 # JWT operations
 jwt = await dominus.auth.mint_jwt(user_id=user["id"], expires_in=900)
 claims = await dominus.auth.validate_jwt(token)
 ```
 
-### Schema Management
+### Schema Management (DDL)
 
 ```python
 # Create table
@@ -232,29 +293,60 @@ await dominus.ddl.add_table("orders", [
     {"name": "created_at", "type": "TIMESTAMPTZ", "default": "NOW()"}
 ])
 
-# Provision tenant schema
+# Add column
+await dominus.ddl.add_column("orders", "status", "VARCHAR(50)", default="'pending'")
+
+# Provision tenant schema from category template
 await dominus.ddl.provision_tenant("customer_acme", category_slug="healthcare")
 ```
 
 ### User Authentication (Portal)
 
 ```python
-# User login
+# User login (tenant_id is optional)
 session = await dominus.portal.login(
     username="john@example.com",
     password="secret123",
-    tenant_id="tenant-uuid"
+    tenant_id="tenant-uuid"  # optional
 )
 
+# Client login with PSK (for service-to-service)
+client_session = await dominus.portal.login_client(psk="psk-token")
+
 # Get current user
 me = await dominus.portal.me()
 
-# Get navigation (access-filtered)
+# Get navigation (access-filtered for current user)
 nav = await dominus.portal.get_navigation()
 
+# Check page access
+has_access = await dominus.portal.check_page_access("/dashboard/admin/users")
+
+# Switch tenant
+await dominus.portal.switch_tenant("other-tenant-uuid")
+
 # Profile & preferences
+profile = await dominus.portal.get_profile()
+await dominus.portal.update_profile(display_name="John Doe")
+
+prefs = await dominus.portal.get_preferences()
 await dominus.portal.update_preferences(theme="dark", timezone="America/New_York")
 
+# Password management
+await dominus.portal.change_password("old-password", "new-password")
+await dominus.portal.request_password_reset("john@example.com")
+await dominus.portal.confirm_password_reset("reset-token", "new-password")
+
+# Session management
+sessions = await dominus.portal.list_sessions()
+await dominus.portal.revoke_session("session-id")
+await dominus.portal.revoke_all_sessions()
+
+# Registration & email verification
+await dominus.portal.register("newuser", "new@example.com", "password", "tenant-id")
+await dominus.portal.verify_email("verification-token")
+await dominus.portal.resend_verification("new@example.com")
+
 # Logout
 await dominus.portal.logout()
 ```
@@ -271,6 +363,14 @@ result = await dominus.courier.send(
 )
 
 # Convenience methods
+await dominus.courier.send_welcome(
+    to="user@example.com",
+    from_email="noreply@myapp.com",
+    name="John",
+    action_url="https://myapp.com/start",
+    product_name="My App"
+)
+
 await dominus.courier.send_password_reset(
     to="user@example.com",
     from_email="noreply@myapp.com",
@@ -278,6 +378,30 @@ await dominus.courier.send_password_reset(
     reset_url="https://myapp.com/reset?token=abc",
     product_name="My App"
 )
+
+await dominus.courier.send_email_verification(
+    to="user@example.com",
+    from_email="noreply@myapp.com",
+    name="John",
+    verify_url="https://myapp.com/verify?token=xyz",
+    product_name="My App"
+)
+
+await dominus.courier.send_invitation(
+    to="invited@example.com",
+    from_email="noreply@myapp.com",
+    name="Invited User",
+    invite_url="https://myapp.com/invite?token=abc",
+    inviter_name="John",
+    product_name="My App"
+)
+```
+
+### Health Checks
+
+```python
+# Basic health check
+status = await dominus.health.check()
 ```
 
 ## Error Handling
@@ -290,7 +414,11 @@ from dominus import (
     AuthorizationError,
     NotFoundError,
     ValidationError,
+    ConflictError,
+    ServiceError,
     SecureTableError,
+    ConnectionError,
+    TimeoutError,
 )
 
 try:
@@ -299,6 +427,14 @@ except NotFoundError as e:
     print(f"User not found: {e.message}")
 except SecureTableError as e:
     print("Secure table requires 'reason' and 'actor' parameters")
+except AuthenticationError as e:
+    print("Invalid or expired token")
+except AuthorizationError as e:
+    print("Insufficient permissions")
+except ValidationError as e:
+    print(f"Invalid request: {e.message}")
+except TimeoutError as e:
+    print("Request timed out")
 except DominusError as e:
     print(f"Error {e.status_code}: {e.message}")
     if e.details:
@@ -326,13 +462,17 @@ except DominusError as e:
 ```bash
 # Required: PSK token for authentication
 export DOMINUS_TOKEN="your-psk-token"
+
+# Optional: Project configuration
+export CB_PROJECT_SLUG="my-project"
+export CB_ENVIRONMENT="production"
 ```
 
 ### Token Resolution
 
 The SDK resolves the authentication token in this order:
 1. `DOMINUS_TOKEN` environment variable
-2. Hardcoded fallback in `dominus/start.py`
+2. Hardcoded fallback in `dominus/start.py` (development only)
 
 ## Architecture
 
@@ -356,16 +496,53 @@ The SDK resolves the authentication token in this order:
 │  ┌─────────┬─────────┬────────┐ │
 │  │ Warden  │Guardian │Archivist│ │
 │  │ Scribe  │ Smith   │Whisperer│ │
-│  │ Herald  │ Portal  │ Courier│ │
+│  │ Herald  │ Portal  │ Courier │ │
 │  └─────────┴─────────┴────────┘ │
 └─────────────────────────────────┘
 ```
 
-## Dependencies
+## FastAPI Integration
 
-- `httpx` - Async HTTP client
-- `bcrypt` - Password hashing
-- `cryptography` - Cache encryption
+```python
+from fastapi import FastAPI, HTTPException
+from dominus import dominus, NotFoundError
+
+app = FastAPI()
+
+@app.get("/users")
+async def list_users():
+    try:
+        users = await dominus.db.query("users", filters={"status": "active"}, limit=50)
+        return users
+    except NotFoundError:
+        raise HTTPException(status_code=404, detail="Not found")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app.get("/users/{user_id}")
+async def get_user(user_id: str):
+    try:
+        user = await dominus.auth.get_user(user_id)
+        return user
+    except NotFoundError:
+        raise HTTPException(status_code=404, detail="User not found")
+```
+
+## Pagination Pattern
+
+```python
+async def get_all_users(page_size: int = 100):
+    offset = 0
+    all_users = []
+    while True:
+        result = await dominus.db.query("users", limit=page_size, offset=offset)
+        rows = result.get("rows", [])
+        all_users.extend(rows)
+        if len(rows) < page_size:
+            break
+        offset += page_size
+    return all_users
+```
 
 ## Documentation
 
@@ -374,7 +551,17 @@ The SDK resolves the authentication token in this order:
 
 ## Version
 
-**v2.0.0** - Namespace-based API with unified orchestrator backend
+**v2.1.6** - Latest release with navigation routes and page scope methods
+
+### Changelog
+
+- **v2.1.6** - Fix navigation routes and add page scope methods
+- **v2.1.5** - Add PSK-only client login
+- **v2.1.4** - Make `tenant_id` optional in login methods
+- **v2.1.2** - Remove `/verify` endpoint call, keep health warmup
+- **v2.1.1** - Fix hardcoded orchestrator base URL
+- **v2.1.0** - Fix SDK routes and remove hardcoded token support
+- **v2.0.0** - Complete namespace-based API rewrite
 
 ## License