vortex-python-sdk 0.1.3__tar.gz

vortex_python_sdk-0.1.3/CHANGELOG.md

@@ -0,0 +1,144 @@
+# 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.1.3] - 2025-01-29
+
+### Added
+- **AcceptUser Type**: New preferred format for accepting invitations with `email`, `phone`, and `name` fields
+- Enhanced `accept_invitations` and `accept_invitations_sync` methods to support both new User format and legacy target format
+
+### Changed
+- **DEPRECATED**: Legacy `InvitationTarget` format for `accept_invitations` - use `AcceptUser` instead
+- Internal API calls now always use User format for consistency
+- Added deprecation logging when legacy target format is used
+
+### Fixed
+- Maintained 100% backward compatibility - existing code using legacy target format continues to work
+
+## [0.1.2] - Previous
+
+### 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
+
+- **CRITICAL FIX**: Updated api url & auth headers
+
+## [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.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 TeamVortexSoftware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vortex_python_sdk-0.1.3/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+recursive-include src/vortex_sdk *.py
+recursive-include src/vortex_sdk py.typed
+exclude tests/
+exclude .github/
+exclude *.pyc
+exclude __pycache__/

vortex_python_sdk-0.1.3/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: vortex-python-sdk
+Version: 0.1.3
+Summary: Vortex Python SDK for invitation management and JWT generation
+Author-email: TeamVortexSoftware <support@vortexsoftware.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/teamvortexsoftware/vortex-python-sdk
+Project-URL: Repository, https://github.com/teamvortexsoftware/vortex-python-sdk.git
+Project-URL: Documentation, https://docs.vortexsoftware.com/python-sdk
+Project-URL: Changelog, https://github.com/teamvortexsoftware/vortex-python-sdk/blob/main/CHANGELOG.md
+Keywords: vortex,invitations,jwt,api,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: typing-extensions>=4.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# Vortex Python SDK
+
+A Python SDK for Vortex invitation management and JWT generation.
+
+## Installation
+
+```bash
+pip install vortex-python-sdk
+```
+
+> **Note**: The package will be available on PyPI once published. See [PUBLISHING.md](PUBLISHING.md) for publishing instructions.
+
+## Usage
+
+### Basic Setup
+
+```python
+from vortex_sdk import Vortex
+
+# 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-vortex-api-key", base_url="https://custom-api.example.com")
+```
+
+### JWT Generation
+
+```python
+# Generate JWT for a user
+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 User
+
+user = User(
+    id="user-123",
+    email="user@example.com",
+    admin_scopes=["autojoin"]
+)
+
+jwt = vortex.generate_jwt(user=user)
+```
+
+### Invitation Management
+
+#### Get Invitations by Target
+
+```python
+import asyncio
+
+async def get_user_invitations():
+    # Async version
+    invitations = await vortex.get_invitations_by_target("email", "user@example.com")
+    for invitation in invitations:
+        print(f"Invitation ID: {invitation.id}, Status: {invitation.status}")
+
+# Sync version
+invitations = vortex.get_invitations_by_target_sync("email", "user@example.com")
+```
+
+#### Accept Invitations
+
+```python
+async def accept_user_invitations():
+    # Async version
+    result = await vortex.accept_invitations(
+        invitation_ids=["inv1", "inv2"],
+        target={"type": "email", "value": "user@example.com"}
+    )
+    print(f"Result: {result}")
+
+# Sync version
+result = vortex.accept_invitations_sync(
+    invitation_ids=["inv1", "inv2"],
+    target={"type": "email", "value": "user@example.com"}
+)
+```
+
+#### Get Specific Invitation
+
+```python
+async def get_invitation():
+    # Async version
+    invitation = await vortex.get_invitation("invitation-id")
+    print(f"Invitation: {invitation.id}")
+
+# Sync version
+invitation = vortex.get_invitation_sync("invitation-id")
+```
+
+#### Revoke Invitation
+
+```python
+async def revoke_invitation():
+    # Async version
+    result = await vortex.revoke_invitation("invitation-id")
+    print(f"Revoked: {result}")
+
+# Sync version
+result = vortex.revoke_invitation_sync("invitation-id")
+```
+
+### Group Operations
+
+#### Get Invitations by Group
+
+```python
+async def get_group_invitations():
+    # Async version
+    invitations = await vortex.get_invitations_by_group("organization", "org123")
+    print(f"Found {len(invitations)} invitations")
+
+# Sync version
+invitations = vortex.get_invitations_by_group_sync("organization", "org123")
+```
+
+#### Delete Invitations by Group
+
+```python
+async def delete_group_invitations():
+    # Async version
+    result = await vortex.delete_invitations_by_group("organization", "org123")
+    print(f"Deleted: {result}")
+
+# Sync version
+result = vortex.delete_invitations_by_group_sync("organization", "org123")
+```
+
+#### Reinvite
+
+```python
+async def reinvite_user():
+    # Async version
+    invitation = await vortex.reinvite("invitation-id")
+    print(f"Reinvited: {invitation.id}")
+
+# Sync version
+invitation = vortex.reinvite_sync("invitation-id")
+```
+
+### Context Manager Usage
+
+```python
+# Async context manager
+async with Vortex(api_key="your-api-key") as vortex:
+    invitations = await vortex.get_invitations_by_target("email", "user@example.com")
+
+# Sync context manager
+with Vortex(api_key="your-api-key") as vortex:
+    invitations = vortex.get_invitations_by_target_sync("email", "user@example.com")
+```
+
+### Error Handling
+
+```python
+from vortex_sdk import VortexApiError
+
+try:
+    invitation = vortex.get_invitation_sync("invalid-id")
+except VortexApiError as e:
+    print(f"API Error: {e.message} (Status: {e.status_code})")
+except Exception as e:
+    print(f"Unexpected error: {e}")
+```
+
+## Development
+
+### Installation
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Code Formatting
+
+```bash
+# Format code
+black src/ tests/
+isort src/ tests/
+
+# Lint code
+ruff check src/ tests/
+mypy src/
+```
+
+## License
+
+MIT

vortex_python_sdk-0.1.3/README.md

@@ -0,0 +1,210 @@
+# Vortex Python SDK
+
+A Python SDK for Vortex invitation management and JWT generation.
+
+## Installation
+
+```bash
+pip install vortex-python-sdk
+```
+
+> **Note**: The package will be available on PyPI once published. See [PUBLISHING.md](PUBLISHING.md) for publishing instructions.
+
+## Usage
+
+### Basic Setup
+
+```python
+from vortex_sdk import Vortex
+
+# 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-vortex-api-key", base_url="https://custom-api.example.com")
+```
+
+### JWT Generation
+
+```python
+# Generate JWT for a user
+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 User
+
+user = User(
+    id="user-123",
+    email="user@example.com",
+    admin_scopes=["autojoin"]
+)
+
+jwt = vortex.generate_jwt(user=user)
+```
+
+### Invitation Management
+
+#### Get Invitations by Target
+
+```python
+import asyncio
+
+async def get_user_invitations():
+    # Async version
+    invitations = await vortex.get_invitations_by_target("email", "user@example.com")
+    for invitation in invitations:
+        print(f"Invitation ID: {invitation.id}, Status: {invitation.status}")
+
+# Sync version
+invitations = vortex.get_invitations_by_target_sync("email", "user@example.com")
+```
+
+#### Accept Invitations
+
+```python
+async def accept_user_invitations():
+    # Async version
+    result = await vortex.accept_invitations(
+        invitation_ids=["inv1", "inv2"],
+        target={"type": "email", "value": "user@example.com"}
+    )
+    print(f"Result: {result}")
+
+# Sync version
+result = vortex.accept_invitations_sync(
+    invitation_ids=["inv1", "inv2"],
+    target={"type": "email", "value": "user@example.com"}
+)
+```
+
+#### Get Specific Invitation
+
+```python
+async def get_invitation():
+    # Async version
+    invitation = await vortex.get_invitation("invitation-id")
+    print(f"Invitation: {invitation.id}")
+
+# Sync version
+invitation = vortex.get_invitation_sync("invitation-id")
+```
+
+#### Revoke Invitation
+
+```python
+async def revoke_invitation():
+    # Async version
+    result = await vortex.revoke_invitation("invitation-id")
+    print(f"Revoked: {result}")
+
+# Sync version
+result = vortex.revoke_invitation_sync("invitation-id")
+```
+
+### Group Operations
+
+#### Get Invitations by Group
+
+```python
+async def get_group_invitations():
+    # Async version
+    invitations = await vortex.get_invitations_by_group("organization", "org123")
+    print(f"Found {len(invitations)} invitations")
+
+# Sync version
+invitations = vortex.get_invitations_by_group_sync("organization", "org123")
+```
+
+#### Delete Invitations by Group
+
+```python
+async def delete_group_invitations():
+    # Async version
+    result = await vortex.delete_invitations_by_group("organization", "org123")
+    print(f"Deleted: {result}")
+
+# Sync version
+result = vortex.delete_invitations_by_group_sync("organization", "org123")
+```
+
+#### Reinvite
+
+```python
+async def reinvite_user():
+    # Async version
+    invitation = await vortex.reinvite("invitation-id")
+    print(f"Reinvited: {invitation.id}")
+
+# Sync version
+invitation = vortex.reinvite_sync("invitation-id")
+```
+
+### Context Manager Usage
+
+```python
+# Async context manager
+async with Vortex(api_key="your-api-key") as vortex:
+    invitations = await vortex.get_invitations_by_target("email", "user@example.com")
+
+# Sync context manager
+with Vortex(api_key="your-api-key") as vortex:
+    invitations = vortex.get_invitations_by_target_sync("email", "user@example.com")
+```
+
+### Error Handling
+
+```python
+from vortex_sdk import VortexApiError
+
+try:
+    invitation = vortex.get_invitation_sync("invalid-id")
+except VortexApiError as e:
+    print(f"API Error: {e.message} (Status: {e.status_code})")
+except Exception as e:
+    print(f"Unexpected error: {e}")
+```
+
+## Development
+
+### Installation
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Code Formatting
+
+```bash
+# Format code
+black src/ tests/
+isort src/ tests/
+
+# Lint code
+ruff check src/ tests/
+mypy src/
+```
+
+## License
+
+MIT