vortex-python-sdk 0.0.1__tar.gz → 0.0.3__tar.gz

vortex_python_sdk-0.0.3/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.3] - 2025-01-31
+
+### Fixed
+- **CRITICAL FIX**: JWT generation now matches Node.js SDK implementation exactly
+  - Improved JWT signing algorithm to match Node.js SDK
+  - Added `iat` (issued at) and `expires` timestamp fields to JWT
+  - Added `attributes` field support in JwtPayload for custom user attributes
+  - Fixed base64url encoding
+- Added comprehensive tests verifying JWT output matches Node.js SDK byte-for-byte
+
+### Breaking Changes
+- JWT structure changed significantly - tokens from 0.0.2 are incompatible with 0.0.3
+- JWTs now include `iat` and `expires` fields for proper token lifecycle management
+
+## [0.0.2] - 2025-01-31
+
+### Fixed
+- **BREAKING FIX**: JWT payload format now matches TypeScript SDK
+  - `identifiers` changed from `Dict[str, str]` to `List[Dict]` with `type` and `value` fields
+  - `groups` structure now properly includes `type`, `id`/`groupId`, and `name` fields
+  - Added `IdentifierInput` type for type-safe identifier creation
+  - Updated `GroupInput` to support both `id` (legacy) and `groupId` (preferred) with proper camelCase serialization
+- Updated documentation with correct JWT generation examples
+
+### Migration Guide
+If you're upgrading from 0.0.1, update your JWT generation code:
+
+**Before (0.0.1):**
+```python
+jwt = vortex.generate_jwt({
+    "user_id": "user-123",
+    "identifiers": {"email": "user@example.com"},  # Dict
+    "groups": ["admin"],  # List of strings
+})
+```
+
+**After (0.0.2):**
+```python
+jwt = vortex.generate_jwt({
+    "user_id": "user-123",
+    "identifiers": [{"type": "email", "value": "user@example.com"}],  # List of dicts
+    "groups": [{"type": "team", "id": "team-1", "name": "Engineering"}],  # List of objects
+})
+```
+
+## [0.0.1] - 2024-10-10
+
+### Added
+- Initial release of Vortex Python SDK
+- JWT generation with HMAC-SHA256 signing
+- Complete invitation management API
+- Async and sync HTTP client methods
+- Type safety with Pydantic models
+- Context manager support for resource cleanup
+- Comprehensive error handling with VortexApiError
+- Full compatibility with Node.js SDK API
+
+### Features
+- `generate_jwt()` - Generate Vortex JWT tokens
+- `get_invitations_by_target()` - Get invitations by email/username/phone
+- `accept_invitations()` - Accept multiple invitations
+- `get_invitation()` - Get specific invitation by ID
+- `revoke_invitation()` - Revoke invitation
+- `get_invitations_by_group()` - Get invitations for a group
+- `delete_invitations_by_group()` - Delete all group invitations
+- `reinvite()` - Reinvite functionality
+- Both async and sync versions of all methods
+- Python 3.8+ support

{vortex_python_sdk-0.0.1/src/vortex_python_sdk.egg-info → vortex_python_sdk-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex-python-sdk
-Version: 0.0.1
+Version: 0.0.3
 Summary: Vortex Python SDK for invitation management and JWT generation
 Author-email: TeamVortexSoftware <support@vortexsoftware.com>
 License-Expression: MIT
@@ -55,11 +55,11 @@ pip install vortex-python-sdk
 ```python
 from vortex_sdk import Vortex
 
-# Initialize the client
-vortex = Vortex(api_key="your-api-key")
+# Initialize the client with your Vortex API key
+vortex = Vortex(api_key="your-vortex-api-key")
 
 # Or with custom base URL
-vortex = Vortex(api_key="your-api-key", base_url="https://custom-api.example.com")
+vortex = Vortex(api_key="your-vortex-api-key", base_url="https://custom-api.example.com")
 ```
 
 ### JWT Generation
@@ -67,16 +67,33 @@ vortex = Vortex(api_key="your-api-key", base_url="https://custom-api.example.com
 ```python
 # Generate JWT for a user
 jwt = vortex.generate_jwt({
-    "user_id": "user123",
-    "identifiers": {
-        "email": "user@example.com",
-        "username": "johndoe"
-    },
-    "groups": ["admin", "users"],
+    "user_id": "user-123",
+    "identifiers": [
+        {"type": "email", "value": "user@example.com"}
+    ],
+    "groups": [
+        {"type": "team", "id": "team-1", "name": "Engineering"}
+    ],
     "role": "admin"
 })
 
 print(f"JWT: {jwt}")
+
+# Or using type-safe models
+from vortex_sdk import JwtPayload, IdentifierInput, GroupInput
+
+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"
+    )
+)
 ```
 
 ### Invitation Management

{vortex_python_sdk-0.0.1 → vortex_python_sdk-0.0.3}/README.md

@@ -17,11 +17,11 @@ pip install vortex-python-sdk
 ```python
 from vortex_sdk import Vortex
 
-# Initialize the client
-vortex = Vortex(api_key="your-api-key")
+# Initialize the client with your Vortex API key
+vortex = Vortex(api_key="your-vortex-api-key")
 
 # Or with custom base URL
-vortex = Vortex(api_key="your-api-key", base_url="https://custom-api.example.com")
+vortex = Vortex(api_key="your-vortex-api-key", base_url="https://custom-api.example.com")
 ```
 
 ### JWT Generation
@@ -29,16 +29,33 @@ vortex = Vortex(api_key="your-api-key", base_url="https://custom-api.example.com
 ```python
 # Generate JWT for a user
 jwt = vortex.generate_jwt({
-    "user_id": "user123",
-    "identifiers": {
-        "email": "user@example.com",
-        "username": "johndoe"
-    },
-    "groups": ["admin", "users"],
+    "user_id": "user-123",
+    "identifiers": [
+        {"type": "email", "value": "user@example.com"}
+    ],
+    "groups": [
+        {"type": "team", "id": "team-1", "name": "Engineering"}
+    ],
     "role": "admin"
 })
 
 print(f"JWT: {jwt}")
+
+# Or using type-safe models
+from vortex_sdk import JwtPayload, IdentifierInput, GroupInput
+
+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"
+    )
+)
 ```
 
 ### Invitation Management

{vortex_python_sdk-0.0.1 → vortex_python_sdk-0.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vortex-python-sdk"
-version = "0.0.1"
+version = "0.0.3"
 description = "Vortex Python SDK for invitation management and JWT generation"
 authors = [{name = "TeamVortexSoftware", email = "support@vortexsoftware.com"}]
 readme = "README.md"

{vortex_python_sdk-0.0.1 → vortex_python_sdk-0.0.3/src/vortex_python_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex-python-sdk
-Version: 0.0.1
+Version: 0.0.3
 Summary: Vortex Python SDK for invitation management and JWT generation
 Author-email: TeamVortexSoftware <support@vortexsoftware.com>
 License-Expression: MIT
@@ -55,11 +55,11 @@ pip install vortex-python-sdk
 ```python
 from vortex_sdk import Vortex
 
-# Initialize the client
-vortex = Vortex(api_key="your-api-key")
+# Initialize the client with your Vortex API key
+vortex = Vortex(api_key="your-vortex-api-key")
 
 # Or with custom base URL
-vortex = Vortex(api_key="your-api-key", base_url="https://custom-api.example.com")
+vortex = Vortex(api_key="your-vortex-api-key", base_url="https://custom-api.example.com")
 ```
 
 ### JWT Generation
@@ -67,16 +67,33 @@ vortex = Vortex(api_key="your-api-key", base_url="https://custom-api.example.com
 ```python
 # Generate JWT for a user
 jwt = vortex.generate_jwt({
-    "user_id": "user123",
-    "identifiers": {
-        "email": "user@example.com",
-        "username": "johndoe"
-    },
-    "groups": ["admin", "users"],
+    "user_id": "user-123",
+    "identifiers": [
+        {"type": "email", "value": "user@example.com"}
+    ],
+    "groups": [
+        {"type": "team", "id": "team-1", "name": "Engineering"}
+    ],
     "role": "admin"
 })
 
 print(f"JWT: {jwt}")
+
+# Or using type-safe models
+from vortex_sdk import JwtPayload, IdentifierInput, GroupInput
+
+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"
+    )
+)
 ```
 
 ### Invitation Management

{vortex_python_sdk-0.0.1 → vortex_python_sdk-0.0.3}/src/vortex_sdk/__init__.py

@@ -8,6 +8,8 @@ from .vortex import Vortex
 from .types import (
     AuthenticatedUser,
     JwtPayload,
+    IdentifierInput,
+    GroupInput,
     InvitationTarget,
     Invitation,
     CreateInvitationRequest,
@@ -16,7 +18,7 @@ from .types import (
     VortexApiError
 )
 
-__version__ = "0.0.1"
+__version__ = "0.0.3"
 __author__ = "TeamVortexSoftware"
 __email__ = "support@vortexsoftware.com"
 
@@ -24,6 +26,8 @@ __all__ = [
     "Vortex",
     "AuthenticatedUser",
     "JwtPayload",
+    "IdentifierInput",
+    "GroupInput",
     "InvitationTarget",
     "Invitation",
     "CreateInvitationRequest",

vortex_python_sdk-0.0.3/src/vortex_sdk/types.py

@@ -0,0 +1,103 @@
+from typing import Dict, List, Optional, Union, Literal, Any
+from pydantic import BaseModel, Field
+
+
+class IdentifierInput(BaseModel):
+    """Identifier structure for JWT generation"""
+    type: Literal["email", "sms"]
+    value: str
+
+
+class GroupInput(BaseModel):
+    """Group structure for JWT generation (input)"""
+    type: str
+    id: Optional[str] = None  # Legacy field (deprecated, use groupId)
+    groupId: Optional[str] = Field(None, alias="group_id", serialization_alias="groupId")  # Preferred: Customer's group ID
+    name: str
+
+    class Config:
+        populate_by_name = True
+
+
+class InvitationGroup(BaseModel):
+    """
+    Invitation group from API responses
+    This matches the MemberGroups table structure from the API
+    """
+    id: str  # Vortex internal UUID
+    account_id: str  # Vortex account ID (camelCase in JSON: accountId)
+    group_id: str  # Customer's group ID (camelCase in JSON: groupId)
+    type: str  # Group type (e.g., "workspace", "team")
+    name: str  # Group name
+    created_at: str  # ISO 8601 timestamp (camelCase in JSON: createdAt)
+
+    class Config:
+        # Allow both snake_case (Python) and camelCase (JSON) field names
+        populate_by_name = True
+        json_schema_extra = {
+            "example": {
+                "id": "550e8400-e29b-41d4-a716-446655440000",
+                "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
+                "groupId": "workspace-123",
+                "type": "workspace",
+                "name": "My Workspace",
+                "createdAt": "2025-01-27T12:00:00.000Z"
+            }
+        }
+
+
+class AuthenticatedUser(BaseModel):
+    user_id: str
+    identifiers: List[IdentifierInput]
+    groups: Optional[List[GroupInput]] = None
+    role: Optional[str] = None
+
+
+class JwtPayload(BaseModel):
+    user_id: str
+    identifiers: List[IdentifierInput]
+    groups: Optional[List[GroupInput]] = None
+    role: Optional[str] = None
+    attributes: Optional[Dict[str, Any]] = None
+
+
+class InvitationTarget(BaseModel):
+    type: Literal["email", "username", "phoneNumber"]
+    value: str
+
+
+class Invitation(BaseModel):
+    id: str
+    target: InvitationTarget
+    groups: Optional[List[InvitationGroup]] = None  # Full group information
+    status: str
+    created_at: str
+    updated_at: Optional[str] = None
+    expires_at: Optional[str] = None
+    metadata: Optional[Dict[str, Union[str, int, bool]]] = None
+
+
+class CreateInvitationRequest(BaseModel):
+    target: InvitationTarget
+    group_type: Optional[str] = None
+    group_id: Optional[str] = None
+    expires_at: Optional[str] = None
+    metadata: Optional[Dict[str, Union[str, int, bool]]] = None
+
+
+class AcceptInvitationsRequest(BaseModel):
+    invitation_ids: List[str]
+    target: InvitationTarget
+
+
+class ApiResponse(BaseModel):
+    data: Optional[Dict] = None
+    error: Optional[str] = None
+    status_code: int = 200
+
+
+class VortexApiError(Exception):
+    def __init__(self, message: str, status_code: int = 500):
+        self.message = message
+        self.status_code = status_code
+        super().__init__(message)

{vortex_python_sdk-0.0.1 → vortex_python_sdk-0.0.3}/src/vortex_sdk/vortex.py

@@ -2,6 +2,8 @@ import json
 import hmac
 import hashlib
 import base64
+import time
+import uuid
 from typing import Dict, List, Optional, Union, Literal
 from urllib.parse import urlencode
 import httpx
@@ -32,54 +34,104 @@ class Vortex:
 
     def generate_jwt(self, payload: Union[JwtPayload, Dict]) -> str:
         """
-        Generate a JWT token for the given payload
+        Generate a JWT token for the given payload matching Node.js SDK implementation
 
         Args:
             payload: JWT payload containing user_id, identifiers, groups, and role
 
         Returns:
             JWT token string
+
+        Raises:
+            ValueError: If API key format is invalid
         """
         if isinstance(payload, dict):
             payload = JwtPayload(**payload)
 
-        # JWT Header
+        # Parse API key (format: VRTX.base64url(uuid).key)
+        parts = self.api_key.split('.')
+        if len(parts) != 3:
+            raise ValueError('Invalid API key format. Expected: VRTX.{encodedId}.{key}')
+
+        prefix, encoded_id, key = parts
+
+        if prefix != 'VRTX':
+            raise ValueError('Invalid API key prefix. Expected: VRTX')
+
+        # Decode UUID from base64url
+        # Add padding if needed
+        padding = 4 - len(encoded_id) % 4
+        if padding != 4:
+            encoded_id_padded = encoded_id + ('=' * padding)
+        else:
+            encoded_id_padded = encoded_id
+
+        try:
+            uuid_bytes = base64.urlsafe_b64decode(encoded_id_padded)
+            kid = str(uuid.UUID(bytes=uuid_bytes))
+        except Exception as e:
+            raise ValueError(f'Invalid UUID in API key: {e}')
+
+        # Generate timestamps
+        iat = int(time.time())
+        expires = iat + 3600
+
+        # Step 1: Derive signing key from API key + UUID
+        signing_key = hmac.new(
+            key.encode(),
+            kid.encode(),
+            hashlib.sha256
+        ).digest()
+
+        # Step 2: Build header + payload
         header = {
-            "alg": "HS256",
-            "typ": "JWT"
+            'iat': iat,
+            'alg': 'HS256',
+            'typ': 'JWT',
+            'kid': kid,
         }
 
-        # JWT Payload
+        # 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 = [
+                {k: v for k, v in group.model_dump(by_alias=True, exclude_none=True).items()}
+                for group in payload.groups
+            ]
+
         jwt_payload = {
-            "userId": payload.user_id,
-            "identifiers": payload.identifiers,
+            'userId': payload.user_id,
+            'groups': groups_list,
+            'role': payload.role,
+            'expires': expires,
+            'identifiers': identifiers_list,
         }
 
-        if payload.groups is not None:
-            jwt_payload["groups"] = payload.groups
-        if payload.role is not None:
-            jwt_payload["role"] = payload.role
+        # Add attributes if provided
+        if hasattr(payload, 'attributes') and payload.attributes:
+            jwt_payload['attributes'] = payload.attributes
 
-        # Encode header and payload
-        header_encoded = base64.urlsafe_b64encode(
-            json.dumps(header, separators=(',', ':')).encode()
-        ).decode().rstrip('=')
+        # Step 3: Base64URL encode (without padding)
+        header_json = json.dumps(header, separators=(',', ':'))
+        payload_json = json.dumps(jwt_payload, separators=(',', ':'))
 
-        payload_encoded = base64.urlsafe_b64encode(
-            json.dumps(jwt_payload, separators=(',', ':')).encode()
-        ).decode().rstrip('=')
+        header_b64 = base64.urlsafe_b64encode(header_json.encode()).decode().rstrip('=')
+        payload_b64 = base64.urlsafe_b64encode(payload_json.encode()).decode().rstrip('=')
 
-        # Create signature
-        message = f"{header_encoded}.{payload_encoded}"
+        # Step 4: Sign
+        to_sign = f'{header_b64}.{payload_b64}'
         signature = hmac.new(
-            self.api_key.encode(),
-            message.encode(),
+            signing_key,
+            to_sign.encode(),
             hashlib.sha256
         ).digest()
 
-        signature_encoded = base64.urlsafe_b64encode(signature).decode().rstrip('=')
+        signature_b64 = base64.urlsafe_b64encode(signature).decode().rstrip('=')
 
-        return f"{message}.{signature_encoded}"
+        return f'{to_sign}.{signature_b64}'
 
     async def _vortex_api_request(
         self,

vortex_python_sdk-0.0.1/CHANGELOG.md

@@ -1,32 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [0.0.1] - 2024-10-10
-
-### Added
-- Initial release of Vortex Python SDK
-- JWT generation with HMAC-SHA256 signing
-- Complete invitation management API
-- Async and sync HTTP client methods
-- Type safety with Pydantic models
-- Context manager support for resource cleanup
-- Comprehensive error handling with VortexApiError
-- Full compatibility with Node.js SDK API
-
-### Features
-- `generate_jwt()` - Generate Vortex JWT tokens
-- `get_invitations_by_target()` - Get invitations by email/username/phone
-- `accept_invitations()` - Accept multiple invitations
-- `get_invitation()` - Get specific invitation by ID
-- `revoke_invitation()` - Revoke invitation
-- `get_invitations_by_group()` - Get invitations for a group
-- `delete_invitations_by_group()` - Delete all group invitations
-- `reinvite()` - Reinvite functionality
-- Both async and sync versions of all methods
-- Python 3.8+ support

vortex_python_sdk-0.0.1/src/vortex_sdk/types.py

@@ -1,59 +0,0 @@
-from typing import Dict, List, Optional, Union, Literal
-from pydantic import BaseModel
-
-
-class AuthenticatedUser(BaseModel):
-    user_id: str
-    identifiers: Dict[str, str]
-    groups: Optional[List[str]] = None
-    role: Optional[str] = None
-
-
-class JwtPayload(BaseModel):
-    user_id: str
-    identifiers: Dict[str, str]
-    groups: Optional[List[str]] = None
-    role: Optional[str] = None
-
-
-class InvitationTarget(BaseModel):
-    type: Literal["email", "username", "phoneNumber"]
-    value: str
-
-
-class Invitation(BaseModel):
-    id: str
-    target: InvitationTarget
-    group_type: Optional[str] = None
-    group_id: Optional[str] = None
-    status: str
-    created_at: str
-    updated_at: Optional[str] = None
-    expires_at: Optional[str] = None
-    metadata: Optional[Dict[str, Union[str, int, bool]]] = None
-
-
-class CreateInvitationRequest(BaseModel):
-    target: InvitationTarget
-    group_type: Optional[str] = None
-    group_id: Optional[str] = None
-    expires_at: Optional[str] = None
-    metadata: Optional[Dict[str, Union[str, int, bool]]] = None
-
-
-class AcceptInvitationsRequest(BaseModel):
-    invitation_ids: List[str]
-    target: InvitationTarget
-
-
-class ApiResponse(BaseModel):
-    data: Optional[Dict] = None
-    error: Optional[str] = None
-    status_code: int = 200
-
-
-class VortexApiError(Exception):
-    def __init__(self, message: str, status_code: int = 500):
-        self.message = message
-        self.status_code = status_code
-        super().__init__(message)