vortex-python-sdk 0.4.0

Vortex Python SDK for invitation management and JWT generation

Vortex Python SDK

A Python SDK for Vortex invitation management and JWT generation.

Features

Invitation Delivery Types

Vortex supports multiple delivery methods for invitations:

• email - Email invitations sent by Vortex (includes reminders and nudges)
• phone - Phone invitations sent by the user/customer
• share - Shareable invitation links for social sharing
• internal - Internal invitations managed entirely by your application
  • No email/SMS communication triggered by Vortex
  • Target value can be any customer-defined identifier
  • Useful for in-app invitation flows where you handle the delivery
  • Example use case: In-app notifications, dashboard invites, etc.

Installation

pip install vortex-python-sdk

Note: The package will be available on PyPI once published. See PUBLISHING.md for publishing instructions.

Usage

Basic Setup

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

# Generate JWT for a user
user = {
    "id": "user-123",
    "email": "[e-mail]",
    "user_name": "Jane Doe",                                    # Optional: user's display name
    "user_avatar_url": "https://example.com/avatars/jane.jpg",  # Optional: user's avatar URL
    "admin_scopes": ["autojoin"]                                # Optional: grants autojoin admin privileges
}

jwt = vortex.generate_jwt(user=user)
print(f"JWT: {jwt}")

# Or using type-safe models
from vortex_sdk import User

user = User(
    id="user-123",
    email="[e-mail]",
    user_name="Jane Doe",                                       # Optional
    user_avatar_url="https://example.com/avatars/jane.jpg",     # Optional
    admin_scopes=["autojoin"]                              # Optional
)

jwt = vortex.generate_jwt(user=user)

Invitation Management

Get Invitations by Target

import asyncio

async def get_user_invitations():
    # Async version
    invitations = await vortex.get_invitations_by_target("email", "[e-mail]")
    for invitation in invitations:
        print(f"Invitation ID: {invitation.id}, Status: {invitation.status}")

# Sync version
invitations = vortex.get_invitations_by_target_sync("email", "[e-mail]")

Accept Invitations

async def accept_user_invitations():
    # Async version
    result = await vortex.accept_invitations(
        invitation_ids=["inv1", "inv2"],
        target={"type": "email", "value": "[e-mail]"}
    )
    print(f"Result: {result}")

# Sync version
result = vortex.accept_invitations_sync(
    invitation_ids=["inv1", "inv2"],
    target={"type": "email", "value": "[e-mail]"}
)

Get Specific Invitation

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

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

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

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

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

# Async context manager
async with Vortex(api_key="your-api-key") as vortex:
    invitations = await vortex.get_invitations_by_target("email", "[e-mail]")

# Sync context manager
with Vortex(api_key="your-api-key") as vortex:
    invitations = vortex.get_invitations_by_target_sync("email", "[e-mail]")

Error Handling

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

# Install development dependencies
pip install -e ".[dev]"

Running Tests

pytest

Code Formatting

# Format code
black src/ tests/
isort src/ tests/

# Lint code
ruff check src/ tests/
mypy src/

License

MIT