chore: renaming of classes to bring consistency, adding fallback with validations for options params

Author: rmad17

examples/AnonymousSessions.md

@@ -122,14 +122,14 @@ All anonymous session errors subclass `AnonymousApiError`, carrying a `.code` yo
 
 ```python
 from auth0_server_python.error import (
-    AnonymousFeatureNotEnabledError,   # tenant flag is off
-    AnonymousClientNotEnabledError,    # client not enabled for anonymous sessions
-    AnonymousClientNotSupportedError,  # e.g. a DPoP-mandated client — see Known Limitations
-    AnonymousResourceServerError,      # audience not a valid/enabled resource server
-    AnonymousScopeError,               # scope not granted to anonymous callers
-    AnonymousSessionCreateError,       # base class for create/re-mint failures
-    AnonymousTokenError,               # get_token() failure with no active session
-    AnonymousSessionIntrospectError,
+    AnonymousFeatureNotEnabledError,
+    AnonymousClientNotEnabledError,
+    AnonymousClientNotSupportedError,
+    AnonymousResourceServerError,
+    AnonymousScopeError,
+    AnonymousCreateError,
+    AnonymousTokenError,
+    AnonymousIntrospectError,
     AnonymousLogoutError,
 )
 

src/auth0_server_python/auth_server/anonymous_client.py

@@ -5,7 +5,7 @@
 
 import json
 import time
-from typing import Any, Optional
+from typing import Any, Optional, Union
 
 import httpx
 from pydantic import ValidationError
@@ -16,18 +16,19 @@
     AnonymousSessionContext,
     AnonymousSessionIntrospection,
     AnonymousTokenResponse,
+    CreateAnonymousSessionOptions,
 )
 from auth0_server_python.encryption.encrypt import decrypt, encrypt
 from auth0_server_python.error import (
     AnonymousApiError,
     AnonymousClientNotEnabledError,
     AnonymousClientNotSupportedError,
+    AnonymousCreateError,
     AnonymousFeatureNotEnabledError,
+    AnonymousIntrospectError,
     AnonymousLogoutError,
     AnonymousResourceServerError,
     AnonymousScopeError,
-    AnonymousSessionCreateError,
-    AnonymousSessionIntrospectError,
     AnonymousTokenError,
     ConfigurationError,
     DomainResolverError,
@@ -211,13 +212,13 @@ def _map_anonymous_error(
             return AnonymousScopeError(description, error_data)
 
         if operation == "create":
-            return AnonymousSessionCreateError(description, cause=error_data)
+            return AnonymousCreateError(description, cause=error_data)
         if operation == "token":
             return AnonymousTokenError(description, error_data)
         if operation == "logout":
             return AnonymousLogoutError(description, error_data)
         if operation == "introspect":
-            return AnonymousSessionIntrospectError(description, error_data)
+            return AnonymousIntrospectError(description, error_data)
         return AnonymousApiError(code or "anonymous_error", description, error_data)
 
     # ============================================================================
@@ -232,25 +233,25 @@ def _validate_metadata(metadata: Optional[dict[str, Any]]) -> None:
             metadata: The metadata dict to validate, or None.
 
         Raises:
-            AnonymousSessionCreateError: metadata is not a dict, contains a
+            AnonymousCreateError: metadata is not a dict, contains a
                 disallowed key, a non-string value, or exceeds 1KB.
         """
         if metadata is None:
             return
         if not isinstance(metadata, dict):
-            raise AnonymousSessionCreateError("metadata must be a JSON object", code="invalid_metadata")
+            raise AnonymousCreateError("metadata must be a JSON object", code="invalid_metadata")
         for key, value in metadata.items():
             if key in _DANGEROUS_METADATA_KEYS:
-                raise AnonymousSessionCreateError(
+                raise AnonymousCreateError(
                     f"metadata key '{key}' is not allowed", code="invalid_metadata"
                 )
             if not isinstance(value, str):
-                raise AnonymousSessionCreateError(
+                raise AnonymousCreateError(
                     f"metadata value for key '{key}' must be a string", code="invalid_metadata"
                 )
         size = len(json.dumps(metadata).encode("utf-8"))
         if size > _METADATA_MAX_BYTES:
-            raise AnonymousSessionCreateError(
+            raise AnonymousCreateError(
                 "metadata exceeds the 1KB size limit", code="metadata_too_large"
             )
 
@@ -325,7 +326,7 @@ async def _create_session_at(
             The newly created AnonymousSession, with is_new=True.
 
         Raises:
-            AnonymousSessionCreateError: The request failed, or the response
+            AnonymousCreateError: The request failed, or the response
                 was invalid or missing required fields.
         """
         base_url = f"https://{domain}"
@@ -343,7 +344,7 @@ async def _create_session_at(
             try:
                 response = await client.post(f"{base_url}/anonymous/token", json=body)
             except httpx.HTTPError as e:
-                raise AnonymousSessionCreateError(
+                raise AnonymousCreateError(
                     "Failed to reach the anonymous token endpoint"
                 ) from e
 
@@ -352,18 +353,18 @@ async def _create_session_at(
                 mapped = self._map_anonymous_error(response.status_code, error_data, "create")
                 if isinstance(mapped, _AnonymousSessionExpired):
                     # Internal-only type must never escape.
-                    raise AnonymousSessionCreateError(str(mapped))
+                    raise AnonymousCreateError(str(mapped))
                 raise mapped
 
             try:
                 token_response = AnonymousTokenResponse.model_validate(response.json())
             except (json.JSONDecodeError, ValueError, ValidationError) as e:
-                raise AnonymousSessionCreateError(
+                raise AnonymousCreateError(
                     "Failed to parse anonymous token response"
                 ) from e
 
         if not token_response.session_token:
-            raise AnonymousSessionCreateError("Anonymous token response missing required fields")
+            raise AnonymousCreateError("Anonymous token response missing required fields")
 
         now = int(time.time())
         context = AnonymousSessionContext(
@@ -527,6 +528,7 @@ async def get_session_token_for_injection(
 
     async def create_session(
         self,
+        options: Optional[Union[CreateAnonymousSessionOptions, dict[str, Any]]] = None,
         *,
         audience: Optional[str] = None,
         scope: Optional[str] = None,
@@ -536,22 +538,37 @@ async def create_session(
         """Mint a fresh anon@<uuid> identity.
 
         Args:
-            audience: Audience for the session. Falls back to the client's
-                configured default when omitted.
-            scope: Scope for the session. Falls back to the client's
-                configured default when omitted.
+            options: Optional bundle of audience/scope/metadata, accepted as a
+                CreateAnonymousSessionOptions or a plain dict. Explicit keyword
+                arguments below always win over the same field on options.
+            audience: Audience for the session. Falls back to options.audience,
+                then to the client's configured default, when omitted.
+            scope: Scope for the session. Falls back to options.scope, then to
+                the client's configured default, when omitted.
             metadata: Metadata to attach at creation, up to 1KB. Cannot be
-                changed after creation.
+                changed after creation. Falls back to options.metadata.
             store_options: Options passed to the anonymous store.
 
         Returns:
             The newly created AnonymousSession.
 
         Raises:
             ConfigurationError: No anonymous_store configured.
-            AnonymousSessionCreateError: Local validation or server rejection.
+            AnonymousCreateError: Invalid options, local validation
+                failure, or server rejection.
         """
         self._require_store()
+        if options is not None:
+            if isinstance(options, dict):
+                try:
+                    options = CreateAnonymousSessionOptions(**options)
+                except ValidationError as e:
+                    raise AnonymousCreateError(
+                        "Invalid create_session options", code="invalid_options"
+                    ) from e
+            audience = audience if audience is not None else options.audience
+            scope = scope if scope is not None else options.scope
+            metadata = metadata if metadata is not None else options.metadata
         self._validate_metadata(metadata)
         audience = audience or self._default_audience
         scope = scope or self._default_scope
@@ -645,18 +662,18 @@ async def introspect(
 
         Raises:
             ConfigurationError: No anonymous_store configured.
-            AnonymousSessionIntrospectError: No active session, or a request
+            AnonymousIntrospectError: No active session, or a request
                 failure.
         """
         self._require_store()
         stored = await self._anonymous_store.get(ANON_IDENTIFIER, options=store_options)
         if not stored:
-            raise AnonymousSessionIntrospectError("No active anonymous session to introspect.")
+            raise AnonymousIntrospectError("No active anonymous session to introspect.")
 
         try:
             context = self._decrypt_context(stored)
         except _AnonymousSessionExpired as e:
-            raise AnonymousSessionIntrospectError(
+            raise AnonymousIntrospectError(
                 "Stored anonymous session is invalid or corrupted."
             ) from e
 
@@ -670,21 +687,21 @@ async def introspect(
                     auth=BearerAuth(context.access_token),
                 )
             except httpx.HTTPError as e:
-                raise AnonymousSessionIntrospectError(
+                raise AnonymousIntrospectError(
                     "Failed to reach the anonymous userinfo endpoint"
                 ) from e
 
             if response.status_code != 200:
                 error_data = self._parse_anonymous_error_body(response)
                 mapped = self._map_anonymous_error(response.status_code, error_data, "introspect")
                 if isinstance(mapped, _AnonymousSessionExpired):
-                    raise AnonymousSessionIntrospectError(str(mapped))
+                    raise AnonymousIntrospectError(str(mapped))
                 raise mapped
 
             try:
                 return AnonymousSessionIntrospection.model_validate(response.json())
             except (json.JSONDecodeError, ValueError, ValidationError) as e:
-                raise AnonymousSessionIntrospectError(
+                raise AnonymousIntrospectError(
                     "Failed to parse anonymous introspection response"
                 ) from e
 

src/auth0_server_python/auth_types/__init__.py

@@ -222,6 +222,16 @@ class LogoutOptions(BaseModel):
     return_to: Optional[str] = None
 
 
+class CreateAnonymousSessionOptions(BaseModel):
+    """Options bundle for create_session(): audience, scope, and metadata."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    audience: Optional[str] = None
+    scope: Optional[str] = None
+    metadata: Optional[dict[str, Any]] = None
+
+
 class AuthorizationParameters(BaseModel):
     """
     Parameters used in authorization requests.

src/auth0_server_python/error/__init__.py

@@ -382,10 +382,10 @@ def __init__(
         self.cause = cause
 
 
-class AnonymousSessionCreateError(AnonymousApiError):
+class AnonymousCreateError(AnonymousApiError):
     """Error thrown when creating or re-minting an anonymous session fails."""
 
-    def __init__(self, message: str, code: str = "anonymous_session_create_error", cause: Optional[dict] = None):
+    def __init__(self, message: str, code: str = "anonymous_create_error", cause: Optional[dict] = None):
         super().__init__(code, message, cause)
 
 
@@ -403,7 +403,7 @@ def __init__(self, message: str, cause: Optional[dict] = None):
         super().__init__("anonymous_token_error", message, cause)
 
 
-class AnonymousSessionIntrospectError(AnonymousApiError):
+class AnonymousIntrospectError(AnonymousApiError):
     """
     Error thrown when introspect() fails.
 
@@ -412,38 +412,38 @@ class AnonymousSessionIntrospectError(AnonymousApiError):
     """
 
     def __init__(self, message: str, cause: Optional[dict] = None):
-        super().__init__("anonymous_session_introspect_error", message, cause)
+        super().__init__("anonymous_introspect_error", message, cause)
 
 
-class AnonymousFeatureNotEnabledError(AnonymousSessionCreateError):
+class AnonymousFeatureNotEnabledError(AnonymousCreateError):
     """Error thrown when the tenant has not enabled the anonymous sessions add-on."""
 
     def __init__(self, message: str, cause: Optional[dict] = None):
         super().__init__(message, "anonymous_feature_not_enabled_error", cause)
 
 
-class AnonymousClientNotEnabledError(AnonymousSessionCreateError):
+class AnonymousClientNotEnabledError(AnonymousCreateError):
     """Error thrown when the client is not enabled for anonymous sessions."""
 
     def __init__(self, message: str, cause: Optional[dict] = None):
         super().__init__(message, "anonymous_client_not_enabled_error", cause)
 
 
-class AnonymousClientNotSupportedError(AnonymousSessionCreateError):
+class AnonymousClientNotSupportedError(AnonymousCreateError):
     """Error thrown when the client type does not support anonymous sessions (e.g. DPoP-mandated)."""
 
     def __init__(self, message: str, cause: Optional[dict] = None):
         super().__init__(message, "anonymous_client_not_supported_error", cause)
 
 
-class AnonymousResourceServerError(AnonymousSessionCreateError):
+class AnonymousResourceServerError(AnonymousCreateError):
     """Error thrown when the requested audience is not a valid resource server."""
 
     def __init__(self, message: str, cause: Optional[dict] = None):
         super().__init__(message, "anonymous_resource_server_error", cause)
 
 
-class AnonymousScopeError(AnonymousSessionCreateError):
+class AnonymousScopeError(AnonymousCreateError):
     """Error thrown when the requested scope is not granted to anonymous callers."""
 
     def __init__(self, message: str, cause: Optional[dict] = None):