dominus-sdk-python-staging 2.1.7__py3-none-any.whl → 2.1.8__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,24 +1,24 @@
1
1
  """SDK Configuration"""
2
2
  from .endpoints import (
3
+ BASE_URL,
3
4
  SOVEREIGN_URL,
4
5
  ARCHITECT_URL,
5
6
  ORCHESTRATOR_URL,
6
7
  WARDEN_URL,
8
+ get_base_url,
7
9
  get_service_url,
8
10
  get_architect_url,
9
11
  get_sovereign_url,
10
- PROJECT_NUMBER,
11
- REGION,
12
12
  )
13
13
 
14
14
  __all__ = [
15
+ "BASE_URL",
15
16
  "SOVEREIGN_URL",
16
17
  "ARCHITECT_URL",
17
18
  "ORCHESTRATOR_URL",
18
19
  "WARDEN_URL",
20
+ "get_base_url",
19
21
  "get_service_url",
20
22
  "get_architect_url",
21
23
  "get_sovereign_url",
22
- "PROJECT_NUMBER",
23
- "REGION",
24
24
  ]
@@ -0,0 +1,252 @@
1
+ """
2
+ FastAPI Namespace - Decorators for route authentication.
3
+
4
+ Provides decorator-style auth for FastAPI routes:
5
+
6
+ from dominus import dominus
7
+
8
+ @router.get("/protected")
9
+ @dominus.fastapi.jwt
10
+ async def route(claims: dict):
11
+ # claims contains JWT payload
12
+ ...
13
+
14
+ @router.get("/scoped")
15
+ @dominus.fastapi.scopes(["api:read", "data:read"])
16
+ async def route(claims: dict):
17
+ # claims validated to have at least one scope
18
+ ...
19
+
20
+ @router.get("/psk-protected")
21
+ @dominus.fastapi.psk
22
+ async def route(client: dict):
23
+ # client contains {id, name, tenant_id, scopes, roles, status}
24
+ ...
25
+
26
+ Parameter naming conventions:
27
+ - @jwt and @scopes: function must have a 'claims' parameter
28
+ - @psk: function must have a 'client' parameter
29
+ """
30
+ from functools import wraps
31
+ from typing import Any, Callable, Dict, List, Optional, TYPE_CHECKING
32
+ import inspect
33
+
34
+ if TYPE_CHECKING:
35
+ from ..start import Dominus
36
+
37
+
38
+ class FastAPINamespace:
39
+ """
40
+ FastAPI authentication decorators namespace.
41
+
42
+ Usage:
43
+ from dominus import dominus
44
+
45
+ @router.get("/protected")
46
+ @dominus.fastapi.jwt
47
+ async def my_route(claims: dict):
48
+ return {"user": claims.get("sub")}
49
+ """
50
+
51
+ def __init__(self, client: "Dominus"):
52
+ self._client = client
53
+
54
+ def jwt(self, func: Callable) -> Callable:
55
+ """
56
+ Decorator: Require valid JWT in Authorization header.
57
+
58
+ Injects JWT claims into the 'claims' parameter.
59
+
60
+ Usage:
61
+ @router.get("/protected")
62
+ @dominus.fastapi.jwt
63
+ async def route(claims: dict):
64
+ return {"user": claims.get("sub")}
65
+
66
+ Raises:
67
+ HTTPException 401: Missing/invalid Authorization header or token
68
+ """
69
+ return self._create_auth_decorator(func, auth_type="jwt")
70
+
71
+ def psk(self, func: Callable) -> Callable:
72
+ """
73
+ Decorator: Require valid PSK in Authorization: Bearer header.
74
+
75
+ Injects client info into the 'client' parameter.
76
+
77
+ Usage:
78
+ @router.get("/protected")
79
+ @dominus.fastapi.psk
80
+ async def route(client: dict):
81
+ return {"client_name": client.get("name")}
82
+
83
+ Raises:
84
+ HTTPException 401: Missing/invalid Authorization header or PSK
85
+ """
86
+ return self._create_auth_decorator(func, auth_type="psk")
87
+
88
+ def scopes(self, allowed_scopes: List[str]) -> Callable:
89
+ """
90
+ Decorator factory: Require JWT with specific scopes.
91
+
92
+ Access granted if client has ANY of the allowed scopes.
93
+ Injects JWT claims into the 'claims' parameter.
94
+
95
+ Usage:
96
+ @router.get("/admin")
97
+ @dominus.fastapi.scopes(["admin:read", "admin:write"])
98
+ async def route(claims: dict):
99
+ return {"admin": True}
100
+
101
+ Args:
102
+ allowed_scopes: List of scope strings, any one grants access
103
+
104
+ Raises:
105
+ HTTPException 401: Missing/invalid Authorization header or token
106
+ HTTPException 403: Token valid but missing required scopes
107
+ """
108
+ def decorator(func: Callable) -> Callable:
109
+ return self._create_auth_decorator(func, auth_type="jwt", required_scopes=allowed_scopes)
110
+ return decorator
111
+
112
+ def _create_auth_decorator(
113
+ self,
114
+ func: Callable,
115
+ auth_type: str,
116
+ required_scopes: Optional[List[str]] = None
117
+ ) -> Callable:
118
+ """
119
+ Internal: Create an auth decorator for the given function.
120
+
121
+ Args:
122
+ func: The route function to wrap
123
+ auth_type: "jwt" or "psk"
124
+ required_scopes: Optional list of scopes to require (jwt only)
125
+ """
126
+ # Import here to avoid circular imports and make fastapi optional
127
+ from fastapi import Header, HTTPException
128
+
129
+ # Determine the parameter name to inject
130
+ param_name = "claims" if auth_type == "jwt" else "client"
131
+
132
+ # Validate the function has the required parameter
133
+ sig = inspect.signature(func)
134
+ if param_name not in sig.parameters:
135
+ raise ValueError(
136
+ f"@dominus.fastapi.{auth_type} requires a '{param_name}' parameter. "
137
+ f"Add '{param_name}: dict' to your function signature."
138
+ )
139
+
140
+ @wraps(func)
141
+ async def wrapper(*args, **kwargs):
142
+ # Get Authorization header from the request
143
+ # FastAPI injects this via the wrapper's signature
144
+ authorization = kwargs.pop("_dominus_authorization", None)
145
+
146
+ if not authorization:
147
+ raise HTTPException(
148
+ status_code=401,
149
+ detail="Missing Authorization header",
150
+ headers={"WWW-Authenticate": "Bearer"}
151
+ )
152
+
153
+ # Extract Bearer token
154
+ token = self._extract_bearer(authorization)
155
+ if not token:
156
+ raise HTTPException(
157
+ status_code=401,
158
+ detail="Invalid Authorization header format. Expected: Bearer <token>",
159
+ headers={"WWW-Authenticate": "Bearer"}
160
+ )
161
+
162
+ # Validate based on auth type
163
+ if auth_type == "jwt":
164
+ auth_data = await self._validate_jwt(token)
165
+ if not auth_data:
166
+ raise HTTPException(
167
+ status_code=401,
168
+ detail="Invalid or expired token",
169
+ headers={"WWW-Authenticate": "Bearer"}
170
+ )
171
+
172
+ # Check scopes if required
173
+ if required_scopes:
174
+ client_scopes = auth_data.get("scopes", [])
175
+ if not any(scope in client_scopes for scope in required_scopes):
176
+ raise HTTPException(
177
+ status_code=403,
178
+ detail=f"Missing required scope. Need one of: {required_scopes}"
179
+ )
180
+ else: # psk
181
+ auth_data = await self._validate_psk(token)
182
+ if not auth_data:
183
+ raise HTTPException(
184
+ status_code=401,
185
+ detail="Invalid API key",
186
+ headers={"WWW-Authenticate": "Bearer"}
187
+ )
188
+
189
+ # Inject the auth data into the function
190
+ kwargs[param_name] = auth_data
191
+
192
+ # Call the original function
193
+ return await func(*args, **kwargs)
194
+
195
+ # Modify the wrapper signature to include Authorization header
196
+ # This allows FastAPI to inject it automatically
197
+ old_sig = inspect.signature(func)
198
+ old_params = list(old_sig.parameters.values())
199
+
200
+ # Remove the claims/client param (we'll inject it manually)
201
+ new_params = [p for p in old_params if p.name != param_name]
202
+
203
+ # Add the Authorization header param
204
+ auth_param = inspect.Parameter(
205
+ "_dominus_authorization",
206
+ inspect.Parameter.KEYWORD_ONLY,
207
+ default=Header(None, alias="Authorization"),
208
+ annotation=Optional[str]
209
+ )
210
+ new_params.append(auth_param)
211
+
212
+ # Create new signature
213
+ wrapper.__signature__ = old_sig.replace(parameters=new_params)
214
+
215
+ return wrapper
216
+
217
+ def _extract_bearer(self, auth_header: str) -> Optional[str]:
218
+ """Extract token from Authorization: Bearer <token> header."""
219
+ if not auth_header or not auth_header.startswith("Bearer "):
220
+ return None
221
+ return auth_header[7:]
222
+
223
+ async def _validate_jwt(self, token: str) -> Optional[Dict[str, Any]]:
224
+ """Validate JWT and return claims."""
225
+ try:
226
+ return await self._client.validate_jwt(token)
227
+ except (ValueError, Exception):
228
+ return None
229
+
230
+ async def _validate_psk(self, psk: str) -> Optional[Dict[str, Any]]:
231
+ """
232
+ Validate PSK and return client info with scopes/roles.
233
+
234
+ Uses portal.login_client to exchange PSK for JWT, then decodes
235
+ the JWT to get the client's claims (scopes, roles, tenants, etc.).
236
+ """
237
+ try:
238
+ # Exchange PSK for JWT via portal.login_client
239
+ # This uses the SDK's project JWT + the subsidiary client's PSK
240
+ result = await self._client.portal.login_client(psk=psk)
241
+ if not result:
242
+ return None
243
+
244
+ jwt = result.get("access_token")
245
+ if not jwt:
246
+ return None
247
+
248
+ # Decode JWT to get claims (includes scopes, roles, tenants, etc.)
249
+ claims = await self._client.validate_jwt(jwt)
250
+ return claims
251
+ except Exception:
252
+ return None
dominus/start.py CHANGED
@@ -333,6 +333,10 @@ class Dominus:
333
333
  from .namespaces.portal import PortalNamespace
334
334
  self.portal = PortalNamespace(self)
335
335
 
336
+ # Initialize FastAPI namespace (decorators for route auth)
337
+ from .namespaces.fastapi import FastAPINamespace
338
+ self.fastapi = FastAPINamespace(self)
339
+
336
340
  # Cache for JWT public key
337
341
  self._public_key_cache = None
338
342
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dominus-sdk-python-staging
3
- Version: 2.1.7
3
+ Version: 2.1.8
4
4
  Summary: Python SDK for the Dominus Orchestrator Platform
5
5
  Author-email: CareBridge Systems <dev@carebridge.io>
6
6
  License: Proprietary
@@ -29,31 +29,31 @@ Provides-Extra: dev
29
29
  Requires-Dist: pytest>=7.0.0; extra == "dev"
30
30
  Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
31
31
 
32
- # CB Dominus SDK
32
+ # CB Dominus SDK for Python
33
33
 
34
- **Python SDK for the Dominus Orchestrator Platform**
34
+ **Async Python SDK for the Dominus Orchestrator Platform**
35
35
 
36
36
  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.
37
37
 
38
38
  ## Features
39
39
 
40
40
  - **Namespace-based API** - Intuitive access via `dominus.db`, `dominus.redis`, `dominus.files`, etc.
41
- - **Async/Await** - Built for modern async Python applications
41
+ - **Async/Await** - Built for modern async Python applications (asyncio)
42
42
  - **Automatic JWT Management** - Token minting, caching, and refresh handled transparently
43
43
  - **Resilience Built-in** - Circuit breaker, exponential backoff, and retry logic
44
- - **Typed Errors** - Specific error classes for different failure modes
44
+ - **Cold Start Handling** - Special retry logic for orchestrator cold starts
45
+ - **Typed Errors** - 9 specific error classes for different failure modes
45
46
  - **Secure by Default** - Client-side password hashing, encrypted cache, audit trail support
46
47
 
47
48
  ## Quick Start
48
49
 
49
50
  ```python
50
51
  from dominus import dominus
52
+ import os
51
53
 
52
54
  # Set your token (or use DOMINUS_TOKEN environment variable)
53
- import os
54
55
  os.environ["DOMINUS_TOKEN"] = "your-psk-token"
55
56
 
56
- # Start using the SDK
57
57
  async def main():
58
58
  # Secrets
59
59
  db_url = await dominus.get("DATABASE_URL")
@@ -81,18 +81,32 @@ git clone https://github.com/carebridgesystems/cb-dominus-sdk.git
81
81
  pip install httpx bcrypt cryptography
82
82
  ```
83
83
 
84
+ Or install via pip (when published):
85
+
86
+ ```bash
87
+ pip install dominus-sdk-python
88
+ ```
89
+
90
+ ## Requirements
91
+
92
+ - Python 3.9+
93
+ - `httpx` - Async HTTP client
94
+ - `bcrypt` - Password hashing
95
+ - `cryptography` - Cache encryption
96
+
84
97
  ## Namespaces
85
98
 
86
99
  | Namespace | Service | Purpose |
87
100
  |-----------|---------|---------|
88
101
  | `dominus.secrets` | Warden | Secrets management |
89
102
  | `dominus.db` | Scribe | Database CRUD operations |
90
- | `dominus.redis` | Whisperer | Redis caching |
91
- | `dominus.files` | Archivist | Object storage (B2) |
92
- | `dominus.auth` | Guardian | Authentication & authorization |
103
+ | `dominus.secure` | Scribe | Secure table access with audit logging |
104
+ | `dominus.redis` | Whisperer | Redis caching & distributed locks |
105
+ | `dominus.files` | Archivist | Object storage (Backblaze B2) |
106
+ | `dominus.auth` | Guardian | Users, roles, scopes, tenants, pages, navigation |
93
107
  | `dominus.ddl` | Smith | Schema DDL & migrations |
94
- | `dominus.logs` | Herald | Structured logging |
95
- | `dominus.portal` | Portal | User auth & sessions |
108
+ | `dominus.logs` | Herald | Structured logging (BetterStack) |
109
+ | `dominus.portal` | Portal | User auth, sessions, profiles, navigation |
96
110
  | `dominus.courier` | Courier | Email delivery (Postmark) |
97
111
  | `dominus.open` | Scribe | Direct database access |
98
112
  | `dominus.health` | Health | Service health checks |
@@ -114,6 +128,10 @@ await dominus.secrets.delete("OLD_KEY")
114
128
  ### Database Operations
115
129
 
116
130
  ```python
131
+ # List tables
132
+ tables = await dominus.db.tables()
133
+ tenant_tables = await dominus.db.tables(schema="tenant_acme")
134
+
117
135
  # Query with filters and pagination
118
136
  users = await dominus.db.query(
119
137
  "users",
@@ -133,6 +151,15 @@ user = await dominus.db.insert("users", {
133
151
  # Update
134
152
  await dominus.db.update("users", {"status": "inactive"}, filters={"id": user_id})
135
153
 
154
+ # Delete
155
+ await dominus.db.delete("users", filters={"id": user_id})
156
+
157
+ # Bulk insert
158
+ await dominus.db.bulk_insert("events", [
159
+ {"type": "login", "user_id": "123"},
160
+ {"type": "login", "user_id": "456"}
161
+ ])
162
+
136
163
  # Secure table access (requires audit reason)
137
164
  patients = await dominus.db.query(
138
165
  "patients",
@@ -145,9 +172,10 @@ patients = await dominus.db.query(
145
172
  ### Redis Caching
146
173
 
147
174
  ```python
148
- # Key-value operations
175
+ # Key-value operations (TTL: min 60s, max 24h)
149
176
  await dominus.redis.set("user:123", {"name": "John"}, ttl=3600)
150
177
  value = await dominus.redis.get("user:123")
178
+ await dominus.redis.delete("user:123")
151
179
 
152
180
  # Distributed locks
153
181
  if await dominus.redis.setnx("lock:job", "worker-1", ttl=60):
@@ -162,6 +190,7 @@ await dominus.redis.incr("page:views", delta=1)
162
190
 
163
191
  # Hash operations
164
192
  await dominus.redis.hset("user:123", "email", "john@example.com", ttl=3600)
193
+ email = await dominus.redis.hget("user:123", "email")
165
194
  ```
166
195
 
167
196
  ### File Storage
@@ -181,6 +210,9 @@ url = download["download_url"]
181
210
 
182
211
  # List files
183
212
  files = await dominus.files.list(category="reports", prefix="2025/")
213
+
214
+ # Delete file
215
+ await dominus.files.delete(file_id=result["id"])
184
216
  ```
185
217
 
186
218
  ### Structured Logging
@@ -190,38 +222,67 @@ files = await dominus.files.list(category="reports", prefix="2025/")
190
222
  await dominus.logs.info("User logged in", {"user_id": "123"})
191
223
  await dominus.logs.error("Payment failed", {"order_id": "456"})
192
224
 
225
+ # All log levels
226
+ await dominus.logs.debug("Debug message", {"data": "..."})
227
+ await dominus.logs.notice("Important notice", {})
228
+ await dominus.logs.warn("Warning message", {})
229
+ await dominus.logs.critical("Critical error", {})
230
+
231
+ # With category
232
+ await dominus.logs.info("Cache hit", {"key": "user:123"}, category="cache")
233
+
193
234
  # With exception context
194
235
  try:
195
236
  risky_operation()
196
237
  except Exception as e:
197
- await dominus.logs.error("Operation failed", exception=e)
238
+ await dominus.logs.error("Operation failed", {}, exception=e)
239
+
240
+ # Batch logging
241
+ await dominus.logs.batch([
242
+ {"level": "info", "message": "Step 1 complete", "data": {}},
243
+ {"level": "info", "message": "Step 2 complete", "data": {}}
244
+ ])
198
245
 
199
246
  # Query logs
200
247
  errors = await dominus.logs.query(level="error", limit=100)
201
248
  ```
202
249
 
203
- ### Authentication
250
+ ### Authentication & Authorization (Guardian)
204
251
 
205
252
  ```python
206
253
  # User management
207
- user = await dominus.auth.add_user(
254
+ users = await dominus.auth.list_users()
255
+ user = await dominus.auth.get_user(user_id="uuid")
256
+
257
+ new_user = await dominus.auth.add_user(
208
258
  username="john",
209
259
  password="secure-password",
210
260
  email="john@example.com"
211
261
  )
212
262
 
263
+ await dominus.auth.update_user("uuid", status="active")
264
+ await dominus.auth.delete_user("uuid")
265
+
213
266
  # Role management
267
+ roles = await dominus.auth.list_roles()
214
268
  role = await dominus.auth.add_role(
215
269
  name="Editor",
216
270
  scope_slugs=["read", "write", "publish"]
217
271
  )
218
272
 
273
+ # Scope management
274
+ scopes = await dominus.auth.list_scopes()
275
+
276
+ # Tenant management
277
+ tenants = await dominus.auth.list_tenants()
278
+ categories = await dominus.auth.list_tenant_categories()
279
+
219
280
  # JWT operations
220
281
  jwt = await dominus.auth.mint_jwt(user_id=user["id"], expires_in=900)
221
282
  claims = await dominus.auth.validate_jwt(token)
222
283
  ```
223
284
 
224
- ### Schema Management
285
+ ### Schema Management (DDL)
225
286
 
226
287
  ```python
227
288
  # Create table
@@ -232,29 +293,60 @@ await dominus.ddl.add_table("orders", [
232
293
  {"name": "created_at", "type": "TIMESTAMPTZ", "default": "NOW()"}
233
294
  ])
234
295
 
235
- # Provision tenant schema
296
+ # Add column
297
+ await dominus.ddl.add_column("orders", "status", "VARCHAR(50)", default="'pending'")
298
+
299
+ # Provision tenant schema from category template
236
300
  await dominus.ddl.provision_tenant("customer_acme", category_slug="healthcare")
237
301
  ```
238
302
 
239
303
  ### User Authentication (Portal)
240
304
 
241
305
  ```python
242
- # User login
306
+ # User login (tenant_id is optional)
243
307
  session = await dominus.portal.login(
244
308
  username="john@example.com",
245
309
  password="secret123",
246
- tenant_id="tenant-uuid"
310
+ tenant_id="tenant-uuid" # optional
247
311
  )
248
312
 
313
+ # Client login with PSK (for service-to-service)
314
+ client_session = await dominus.portal.login_client(psk="psk-token")
315
+
249
316
  # Get current user
250
317
  me = await dominus.portal.me()
251
318
 
252
- # Get navigation (access-filtered)
319
+ # Get navigation (access-filtered for current user)
253
320
  nav = await dominus.portal.get_navigation()
254
321
 
322
+ # Check page access
323
+ has_access = await dominus.portal.check_page_access("/dashboard/admin/users")
324
+
325
+ # Switch tenant
326
+ await dominus.portal.switch_tenant("other-tenant-uuid")
327
+
255
328
  # Profile & preferences
329
+ profile = await dominus.portal.get_profile()
330
+ await dominus.portal.update_profile(display_name="John Doe")
331
+
332
+ prefs = await dominus.portal.get_preferences()
256
333
  await dominus.portal.update_preferences(theme="dark", timezone="America/New_York")
257
334
 
335
+ # Password management
336
+ await dominus.portal.change_password("old-password", "new-password")
337
+ await dominus.portal.request_password_reset("john@example.com")
338
+ await dominus.portal.confirm_password_reset("reset-token", "new-password")
339
+
340
+ # Session management
341
+ sessions = await dominus.portal.list_sessions()
342
+ await dominus.portal.revoke_session("session-id")
343
+ await dominus.portal.revoke_all_sessions()
344
+
345
+ # Registration & email verification
346
+ await dominus.portal.register("newuser", "new@example.com", "password", "tenant-id")
347
+ await dominus.portal.verify_email("verification-token")
348
+ await dominus.portal.resend_verification("new@example.com")
349
+
258
350
  # Logout
259
351
  await dominus.portal.logout()
260
352
  ```
@@ -271,6 +363,14 @@ result = await dominus.courier.send(
271
363
  )
272
364
 
273
365
  # Convenience methods
366
+ await dominus.courier.send_welcome(
367
+ to="user@example.com",
368
+ from_email="noreply@myapp.com",
369
+ name="John",
370
+ action_url="https://myapp.com/start",
371
+ product_name="My App"
372
+ )
373
+
274
374
  await dominus.courier.send_password_reset(
275
375
  to="user@example.com",
276
376
  from_email="noreply@myapp.com",
@@ -278,6 +378,30 @@ await dominus.courier.send_password_reset(
278
378
  reset_url="https://myapp.com/reset?token=abc",
279
379
  product_name="My App"
280
380
  )
381
+
382
+ await dominus.courier.send_email_verification(
383
+ to="user@example.com",
384
+ from_email="noreply@myapp.com",
385
+ name="John",
386
+ verify_url="https://myapp.com/verify?token=xyz",
387
+ product_name="My App"
388
+ )
389
+
390
+ await dominus.courier.send_invitation(
391
+ to="invited@example.com",
392
+ from_email="noreply@myapp.com",
393
+ name="Invited User",
394
+ invite_url="https://myapp.com/invite?token=abc",
395
+ inviter_name="John",
396
+ product_name="My App"
397
+ )
398
+ ```
399
+
400
+ ### Health Checks
401
+
402
+ ```python
403
+ # Basic health check
404
+ status = await dominus.health.check()
281
405
  ```
282
406
 
283
407
  ## Error Handling
@@ -290,7 +414,11 @@ from dominus import (
290
414
  AuthorizationError,
291
415
  NotFoundError,
292
416
  ValidationError,
417
+ ConflictError,
418
+ ServiceError,
293
419
  SecureTableError,
420
+ ConnectionError,
421
+ TimeoutError,
294
422
  )
295
423
 
296
424
  try:
@@ -299,6 +427,14 @@ except NotFoundError as e:
299
427
  print(f"User not found: {e.message}")
300
428
  except SecureTableError as e:
301
429
  print("Secure table requires 'reason' and 'actor' parameters")
430
+ except AuthenticationError as e:
431
+ print("Invalid or expired token")
432
+ except AuthorizationError as e:
433
+ print("Insufficient permissions")
434
+ except ValidationError as e:
435
+ print(f"Invalid request: {e.message}")
436
+ except TimeoutError as e:
437
+ print("Request timed out")
302
438
  except DominusError as e:
303
439
  print(f"Error {e.status_code}: {e.message}")
304
440
  if e.details:
@@ -326,13 +462,17 @@ except DominusError as e:
326
462
  ```bash
327
463
  # Required: PSK token for authentication
328
464
  export DOMINUS_TOKEN="your-psk-token"
465
+
466
+ # Optional: Project configuration
467
+ export CB_PROJECT_SLUG="my-project"
468
+ export CB_ENVIRONMENT="production"
329
469
  ```
330
470
 
331
471
  ### Token Resolution
332
472
 
333
473
  The SDK resolves the authentication token in this order:
334
474
  1. `DOMINUS_TOKEN` environment variable
335
- 2. Hardcoded fallback in `dominus/start.py`
475
+ 2. Hardcoded fallback in `dominus/start.py` (development only)
336
476
 
337
477
  ## Architecture
338
478
 
@@ -356,16 +496,53 @@ The SDK resolves the authentication token in this order:
356
496
  │ ┌─────────┬─────────┬────────┐ │
357
497
  │ │ Warden │Guardian │Archivist│ │
358
498
  │ │ Scribe │ Smith │Whisperer│ │
359
- │ │ Herald │ Portal │ Courier│ │
499
+ │ │ Herald │ Portal │ Courier │ │
360
500
  │ └─────────┴─────────┴────────┘ │
361
501
  └─────────────────────────────────┘
362
502
  ```
363
503
 
364
- ## Dependencies
504
+ ## FastAPI Integration
365
505
 
366
- - `httpx` - Async HTTP client
367
- - `bcrypt` - Password hashing
368
- - `cryptography` - Cache encryption
506
+ ```python
507
+ from fastapi import FastAPI, HTTPException
508
+ from dominus import dominus, NotFoundError
509
+
510
+ app = FastAPI()
511
+
512
+ @app.get("/users")
513
+ async def list_users():
514
+ try:
515
+ users = await dominus.db.query("users", filters={"status": "active"}, limit=50)
516
+ return users
517
+ except NotFoundError:
518
+ raise HTTPException(status_code=404, detail="Not found")
519
+ except Exception as e:
520
+ raise HTTPException(status_code=500, detail=str(e))
521
+
522
+ @app.get("/users/{user_id}")
523
+ async def get_user(user_id: str):
524
+ try:
525
+ user = await dominus.auth.get_user(user_id)
526
+ return user
527
+ except NotFoundError:
528
+ raise HTTPException(status_code=404, detail="User not found")
529
+ ```
530
+
531
+ ## Pagination Pattern
532
+
533
+ ```python
534
+ async def get_all_users(page_size: int = 100):
535
+ offset = 0
536
+ all_users = []
537
+ while True:
538
+ result = await dominus.db.query("users", limit=page_size, offset=offset)
539
+ rows = result.get("rows", [])
540
+ all_users.extend(rows)
541
+ if len(rows) < page_size:
542
+ break
543
+ offset += page_size
544
+ return all_users
545
+ ```
369
546
 
370
547
  ## Documentation
371
548
 
@@ -374,7 +551,17 @@ The SDK resolves the authentication token in this order:
374
551
 
375
552
  ## Version
376
553
 
377
- **v2.0.0** - Namespace-based API with unified orchestrator backend
554
+ **v2.1.6** - Latest release with navigation routes and page scope methods
555
+
556
+ ### Changelog
557
+
558
+ - **v2.1.6** - Fix navigation routes and add page scope methods
559
+ - **v2.1.5** - Add PSK-only client login
560
+ - **v2.1.4** - Make `tenant_id` optional in login methods
561
+ - **v2.1.2** - Remove `/verify` endpoint call, keep health warmup
562
+ - **v2.1.1** - Fix hardcoded orchestrator base URL
563
+ - **v2.1.0** - Fix SDK routes and remove hardcoded token support
564
+ - **v2.0.0** - Complete namespace-based API rewrite
378
565
 
379
566
  ## License
380
567
 
@@ -1,7 +1,7 @@
1
1
  dominus/__init__.py,sha256=iec991dWH0_4t6k-aGikn4HFEt8Cst0Ic1GsrZWmNfw,1419
2
2
  dominus/errors.py,sha256=Sfpg_4zlraE6fprdSu7RDNmSDv0Eg5OZRcPhNUQhNGs,5761
3
- dominus/start.py,sha256=bevdXNoclOXyOmAicCbKrcsXzjTVxj4WtAr2J79LwAw,31852
4
- dominus/config/__init__.py,sha256=PyQzVeR4YqtGavXtbgh5ke2wGHvMPeJR0wKcN0nx9Tg,434
3
+ dominus/start.py,sha256=mizohr9OHyIOLJzeev0KtHT4RIHEyPLbKiWrQAVf2Gs,32023
4
+ dominus/config/__init__.py,sha256=nvLLNh4dM_MCqcfF3XFS2NnVn44q0RYHEfAPP-2G5To,434
5
5
  dominus/config/endpoints.py,sha256=CY7joW2T0Ec0HWhS6BhmGWZk7pRcaZiYAcoS_rhop4s,1067
6
6
  dominus/helpers/__init__.py,sha256=cyoBvw1QJugtGt0gYitIz1yxOaMmBa-wMXqbh-fi4PU,61
7
7
  dominus/helpers/auth.py,sha256=IVZLelikaGIAZvyc-q7EoPd8fBNVlGffGXQkTP4x5Fk,633
@@ -15,6 +15,7 @@ dominus/namespaces/auth.py,sha256=7IqQGgcmmr1tUrfaDBnEirfB057QDF8r1_NZF-_e3W8,34
15
15
  dominus/namespaces/courier.py,sha256=WAhHpswhO8S_eEzn5zgBGhDqhgGxfDR_gs4i1rnotNw,6810
16
16
  dominus/namespaces/db.py,sha256=NEx5RSHbvy17H7NEO_3NIy7Rl7foC031iRIOknDH7PA,7622
17
17
  dominus/namespaces/ddl.py,sha256=jstq5TbwKo7ecPQ-FZT8g5NNyAYjbd8ihOD0vvpDico,18301
18
+ dominus/namespaces/fastapi.py,sha256=AZOjUIJ5tznJVLkpctNa606XRTv5IEkjvrINEHgkeuE,8745
18
19
  dominus/namespaces/files.py,sha256=TSQfNx-UuGbMOsxj1oO_QuIugqrZBC1x_JNNWEO9Mhw,8365
19
20
  dominus/namespaces/health.py,sha256=xdRjwOpnG769H2kbhysATdYzQzbEmpNyt17dMMYj340,1474
20
21
  dominus/namespaces/logs.py,sha256=ieWfjW24ZjNdV86iiTvnxwiHsrOib5EsYEmwbHS-uEs,11273
@@ -25,7 +26,7 @@ dominus/namespaces/secrets.py,sha256=6xhUJVeDBb5-AiwrwjozarwAc7SoiJ-2Rq6ByBAx684
25
26
  dominus/services/__init__.py,sha256=LQl5sx6DHhX1xCN3MRoUgffxqwm3Mfm525hijyFods8,43
26
27
  dominus/services/_deprecated_architect.py,sha256=EAMhUK8C_4DLgYyKGVqcXrroEoAenWeuKWnPMowGMQk,14985
27
28
  dominus/services/_deprecated_sovereign.py,sha256=is9SQVCcmcGUEFKULqitHlk67pfpfkQE-ApU-gVjIEE,3511
28
- dominus_sdk_python_staging-2.1.7.dist-info/METADATA,sha256=TA8wbThERqDmQXJK6RF0gsIJ5qUeZBc2vpdjhJWbYi4,10765
29
- dominus_sdk_python_staging-2.1.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
30
- dominus_sdk_python_staging-2.1.7.dist-info/top_level.txt,sha256=515zxMIbX0DpheRbjvNqKIt_AFqdFjX41jtyp_SqLf4,8
31
- dominus_sdk_python_staging-2.1.7.dist-info/RECORD,,
29
+ dominus_sdk_python_staging-2.1.8.dist-info/METADATA,sha256=9DZxNNWQFLdpuDYwiZI2FyyusqdcCuwpA0fayZt8q9c,16524
30
+ dominus_sdk_python_staging-2.1.8.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
31
+ dominus_sdk_python_staging-2.1.8.dist-info/top_level.txt,sha256=515zxMIbX0DpheRbjvNqKIt_AFqdFjX41jtyp_SqLf4,8
32
+ dominus_sdk_python_staging-2.1.8.dist-info/RECORD,,