vortex-python-sdk 0.0.6__tar.gz → 0.1.0__tar.gz

{vortex_python_sdk-0.0.6 → vortex_python_sdk-0.1.0}/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **JWT Payload Simplification**: Updated JWT structure to use simplified fields (backward compatible)
+  - **NEW (Preferred)**: Use `User` object with `id`, `email`, and `admin_scopes` for cleaner, more maintainable code
+  - `id` (string): User's ID in your system
+  - `email` (string): User's email address - replaces the `identifiers` array
+  - `admin_scopes` (list): List of admin scopes (e.g., `['autojoin']` for autojoin admin privileges)
+  - **DEPRECATED (Still Supported)**: `identifiers`, `groups`, and `role` fields maintained for backward compatibility
+  - Supports additional properties via Pydantic's `extra="allow"` configuration
+  - All existing integrations will continue to work without changes
+
+### Migration Guide (Optional - Backward Compatible)
+
+The old format still works, but we recommend migrating to the simpler structure:
+
+**New simplified format (recommended):**
+
+```python
+user = {
+    "id": "user-123",
+    "email": "user@example.com",
+    "admin_scopes": ["autojoin"]  # optional: grants autojoin admin privileges
+}
+jwt = vortex.generate_jwt(user=user)
+```
+
+**Old format (still supported):**
+
+```python
+jwt = vortex.generate_jwt({
+    "user_id": "user-123",
+    "identifiers": [{"type": "email", "value": "user@example.com"}],
+    "groups": [{"type": "team", "id": "team-1", "name": "Engineering"}],
+    "role": "admin"
+})
+```
+
 ## [0.0.5] - 2025-11-06
 
 ### Fixed

{vortex_python_sdk-0.0.6/src/vortex_python_sdk.egg-info → vortex_python_sdk-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex-python-sdk
-Version: 0.0.6
+Version: 0.1.0
 Summary: Vortex Python SDK for invitation management and JWT generation
 Author-email: TeamVortexSoftware <support@vortexsoftware.com>
 License-Expression: MIT
@@ -66,34 +66,32 @@ vortex = Vortex(api_key="your-vortex-api-key", base_url="https://custom-api.exam
 
 ```python
 # Generate JWT for a user
-jwt = vortex.generate_jwt({
-    "user_id": "user-123",
-    "identifiers": [
-        {"type": "email", "value": "user@example.com"}
-    ],
-    "groups": [
-        {"type": "team", "id": "team-1", "name": "Engineering"}
-    ],
-    "role": "admin"
-})
+user = {
+    "id": "user-123",
+    "email": "user@example.com",
+    "admin_scopes": ["autojoin"]  # Optional - included as adminScopes array in JWT
+}
 
+jwt = vortex.generate_jwt(user=user)
 print(f"JWT: {jwt}")
 
+# With additional properties
+jwt = vortex.generate_jwt(
+    user=user,
+    role="admin",
+    department="Engineering"
+)
+
 # Or using type-safe models
-from vortex_sdk import JwtPayload, IdentifierInput, GroupInput
+from vortex_sdk import User
 
-jwt = vortex.generate_jwt(
-    JwtPayload(
-        user_id="user-123",
-        identifiers=[
-            IdentifierInput(type="email", value="user@example.com")
-        ],
-        groups=[
-            GroupInput(type="team", id="team-1", name="Engineering")
-        ],
-        role="admin"
-    )
+user = User(
+    id="user-123",
+    email="user@example.com",
+    admin_scopes=["autojoin"]
 )
+
+jwt = vortex.generate_jwt(user=user)
 ```
 
 ### Invitation Management

{vortex_python_sdk-0.0.6 → vortex_python_sdk-0.1.0}/README.md

@@ -28,34 +28,32 @@ vortex = Vortex(api_key="your-vortex-api-key", base_url="https://custom-api.exam
 
 ```python
 # Generate JWT for a user
-jwt = vortex.generate_jwt({
-    "user_id": "user-123",
-    "identifiers": [
-        {"type": "email", "value": "user@example.com"}
-    ],
-    "groups": [
-        {"type": "team", "id": "team-1", "name": "Engineering"}
-    ],
-    "role": "admin"
-})
+user = {
+    "id": "user-123",
+    "email": "user@example.com",
+    "admin_scopes": ["autojoin"]  # Optional - included as adminScopes array in JWT
+}
 
+jwt = vortex.generate_jwt(user=user)
 print(f"JWT: {jwt}")
 
+# With additional properties
+jwt = vortex.generate_jwt(
+    user=user,
+    role="admin",
+    department="Engineering"
+)
+
 # Or using type-safe models
-from vortex_sdk import JwtPayload, IdentifierInput, GroupInput
+from vortex_sdk import User
 
-jwt = vortex.generate_jwt(
-    JwtPayload(
-        user_id="user-123",
-        identifiers=[
-            IdentifierInput(type="email", value="user@example.com")
-        ],
-        groups=[
-            GroupInput(type="team", id="team-1", name="Engineering")
-        ],
-        role="admin"
-    )
+user = User(
+    id="user-123",
+    email="user@example.com",
+    admin_scopes=["autojoin"]
 )
+
+jwt = vortex.generate_jwt(user=user)
 ```
 
 ### Invitation Management
@@ -209,4 +207,4 @@ mypy src/
 
 ## License
 
-MIT
+MIT

{vortex_python_sdk-0.0.6 → vortex_python_sdk-0.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vortex-python-sdk"
-version = "0.0.6"
+version = "0.1.0"
 description = "Vortex Python SDK for invitation management and JWT generation"
 authors = [{name = "TeamVortexSoftware", email = "support@vortexsoftware.com"}]
 readme = "README.md"
@@ -81,7 +81,7 @@ warn_no_return = true
 warn_unreachable = true
 
 [tool.ruff]
-target-version = "py38"
+target-version = "py39"
 line-length = 88
 
 [tool.ruff.lint]

{vortex_python_sdk-0.0.6 → vortex_python_sdk-0.1.0/src/vortex_python_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex-python-sdk
-Version: 0.0.6
+Version: 0.1.0
 Summary: Vortex Python SDK for invitation management and JWT generation
 Author-email: TeamVortexSoftware <support@vortexsoftware.com>
 License-Expression: MIT
@@ -66,34 +66,32 @@ vortex = Vortex(api_key="your-vortex-api-key", base_url="https://custom-api.exam
 
 ```python
 # Generate JWT for a user
-jwt = vortex.generate_jwt({
-    "user_id": "user-123",
-    "identifiers": [
-        {"type": "email", "value": "user@example.com"}
-    ],
-    "groups": [
-        {"type": "team", "id": "team-1", "name": "Engineering"}
-    ],
-    "role": "admin"
-})
+user = {
+    "id": "user-123",
+    "email": "user@example.com",
+    "admin_scopes": ["autojoin"]  # Optional - included as adminScopes array in JWT
+}
 
+jwt = vortex.generate_jwt(user=user)
 print(f"JWT: {jwt}")
 
+# With additional properties
+jwt = vortex.generate_jwt(
+    user=user,
+    role="admin",
+    department="Engineering"
+)
+
 # Or using type-safe models
-from vortex_sdk import JwtPayload, IdentifierInput, GroupInput
+from vortex_sdk import User
 
-jwt = vortex.generate_jwt(
-    JwtPayload(
-        user_id="user-123",
-        identifiers=[
-            IdentifierInput(type="email", value="user@example.com")
-        ],
-        groups=[
-            GroupInput(type="team", id="team-1", name="Engineering")
-        ],
-        role="admin"
-    )
+user = User(
+    id="user-123",
+    email="user@example.com",
+    admin_scopes=["autojoin"]
 )
+
+jwt = vortex.generate_jwt(user=user)
 ```
 
 ### Invitation Management

{vortex_python_sdk-0.0.6 → vortex_python_sdk-0.1.0}/src/vortex_sdk/types.py

@@ -52,20 +52,77 @@ class InvitationGroup(BaseModel):
         }
 
 
+class User(BaseModel):
+    """
+    User data for JWT generation
+
+    Required fields:
+    - id: User's ID in their system
+    - email: User's email address
+
+    Optional fields:
+    - admin_scopes: List of admin scopes (e.g., ['autojoin'])
+
+    Additional fields are allowed via extra parameter
+    """
+    id: str
+    email: str
+    admin_scopes: Optional[List[str]] = None
+
+    class Config:
+        extra = "allow"  # Allow additional fields
+
+
 class AuthenticatedUser(BaseModel):
+    """
+    User data for JWT generation (simplified structure)
+
+    Note: identifiers, groups, and role are maintained for backward compatibility
+    but are deprecated in favor of the User object with admin_scopes.
+    """
     user_id: str
-    identifiers: List[IdentifierInput]
+    user_email: Optional[str] = None
+    admin_scopes: Optional[List[str]] = None
+
+    # Deprecated fields (maintained for backward compatibility)
+    identifiers: Optional[List[IdentifierInput]] = None
     groups: Optional[List[GroupInput]] = None
     role: Optional[str] = None
 
 
 class JwtPayload(BaseModel):
+    """
+    JWT payload structure (simplified)
+
+    Required fields:
+    - user_id: User's ID in their system
+    - user_email: User's email address (preferred)
+
+    Optional fields:
+    - admin_scopes: List of admin scopes (e.g., ['autojoin'] for autojoin admin privileges)
+    - attributes: Additional custom attributes
+
+    Deprecated fields (maintained for backward compatibility):
+    - identifiers: Use user_email instead
+    - groups: No longer required
+    - role: No longer required
+
+    Additional fields are allowed via [key: string]: any pattern
+    """
     user_id: str
-    identifiers: List[IdentifierInput]
+    user_email: Optional[str] = None
+    admin_scopes: Optional[List[str]] = None
+
+    # Deprecated fields (maintained for backward compatibility)
+    identifiers: Optional[List[IdentifierInput]] = None
     groups: Optional[List[GroupInput]] = None
     role: Optional[str] = None
+
     attributes: Optional[Dict[str, Any]] = None
 
+    class Config:
+        extra = "allow"  # Allow additional fields [key: string]: any
+
 
 class InvitationTarget(BaseModel):
     type: Literal["email", "sms"]
@@ -116,12 +173,14 @@ class InvitationResult(BaseModel):
         "unfurled",
         "accepted_elsewhere",
     ]
-    target: List[InvitationTarget]
+    target: List[InvitationTarget] = Field(default_factory=list)
     views: int
     widget_configuration_id: str = Field(alias="widgetConfigurationId")
     project_id: str = Field(alias="projectId")
     groups: List[Optional[InvitationGroup]] = Field(default_factory=list)
     accepts: List[InvitationAcceptance] = Field(default_factory=list)
+    expired: bool
+    expires: Optional[str] = None
 
     class Config:
         populate_by_name = True

{vortex_python_sdk-0.0.6 → vortex_python_sdk-0.1.0}/src/vortex_sdk/vortex.py

@@ -11,7 +11,7 @@ import httpx
 from .types import (
     Invitation,
     InvitationTarget,
-    JwtPayload,
+    User,
     VortexApiError,
 )
 
@@ -39,21 +39,30 @@ class Vortex:
         self._client = httpx.AsyncClient()
         self._sync_client = httpx.Client()
 
-    def generate_jwt(self, payload: Union[JwtPayload, Dict]) -> str:
+    def generate_jwt(self, user: Union[User, Dict], **extra: Any) -> str:
         """
-        Generate a JWT token for the given payload matching Node.js SDK implementation
+        Generate a JWT token for a user
 
         Args:
-            payload: JWT payload containing user_id, identifiers, groups, and role
+            user: User object or dict with 'id', 'email', and optional 'admin_scopes'
+            **extra: Additional properties to include in JWT payload
 
         Returns:
             JWT token string
 
         Raises:
-            ValueError: If API key format is invalid
+            ValueError: If API key format is invalid or required fields are missing
+
+        Example:
+            user = {'id': 'user-123', 'email': 'user@example.com', 'admin_scopes': ['autojoin']}
+            jwt = vortex.generate_jwt(user=user)
+
+            # With additional properties
+            jwt = vortex.generate_jwt(user=user, role='admin', department='Engineering')
         """
-        if isinstance(payload, dict):
-            payload = JwtPayload(**payload)
+        # Convert dict to User if needed
+        if isinstance(user, dict):
+            user = User(**user)
 
         # Parse API key (format: VRTX.base64url(uuid).key)
         parts = self.api_key.split(".")
@@ -94,30 +103,24 @@ class Vortex:
             "kid": kid,
         }
 
-        # Serialize identifiers
-        identifiers_list = [
-            {"type": id.type, "value": id.value} for id in payload.identifiers
-        ]
-
-        # Serialize groups
-        groups_list = None
-        if payload.groups is not None:
-            groups_list = [
-                group.model_dump(by_alias=True, exclude_none=True)
-                for group in payload.groups
-            ]
-
+        # Build JWT payload
         jwt_payload: Dict[str, Any] = {
-            "userId": payload.user_id,
-            "groups": groups_list,
-            "role": payload.role,
+            "userId": user.id,
+            "userEmail": user.email,
             "expires": expires,
-            "identifiers": identifiers_list,
         }
 
-        # Add attributes if provided
-        if hasattr(payload, "attributes") and payload.attributes:
-            jwt_payload["attributes"] = payload.attributes
+        # Add adminScopes if present
+        if user.admin_scopes:
+            jwt_payload["adminScopes"] = user.admin_scopes
+
+        # Add any additional properties from user.model_extra
+        if hasattr(user, "model_extra") and user.model_extra:
+            jwt_payload.update(user.model_extra)
+
+        # Add any additional properties from **extra
+        if extra:
+            jwt_payload.update(extra)
 
         # Step 3: Base64URL encode (without padding)
         header_json = json.dumps(header, separators=(",", ":"))
@@ -184,6 +187,10 @@ class Vortex:
 
                 raise VortexApiError(error_message, response.status_code)
 
+            # Handle empty responses (e.g., DELETE requests may return 204 or empty 200)
+            if response.status_code == 204 or not response.content:
+                return {}  # type: ignore[return-value]
+
             return response.json()  # type: ignore[no-any-return]
 
         except httpx.RequestError as e:
@@ -237,6 +244,10 @@ class Vortex:
 
                 raise VortexApiError(error_message, response.status_code)
 
+            # Handle empty responses (e.g., DELETE requests may return 204 or empty 200)
+            if response.status_code == 204 or not response.content:
+                return {}  # type: ignore[return-value]
+
             return response.json()  # type: ignore[no-any-return]
 
         except httpx.RequestError as e:
@@ -260,7 +271,7 @@ class Vortex:
         params = {"targetType": target_type, "targetValue": target_value}
 
         response = await self._vortex_api_request(
-            "GET", "/invitations/by-target", params=params
+            "GET", "/invitations", params=params
         )
         return [Invitation(**inv) for inv in response.get("invitations", [])]
 
@@ -282,7 +293,7 @@ class Vortex:
         params = {"targetType": target_type, "targetValue": target_value}
 
         response = self._vortex_api_request_sync(
-            "GET", "/invitations/by-target", params=params
+            "GET", "/invitations", params=params
         )
         return [Invitation(**inv) for inv in response.get("invitations", [])]