vortex-python-sdk 0.1.3__tar.gz → 0.3.0__tar.gz

{vortex_python_sdk-0.1.3 → vortex_python_sdk-0.3.0}/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-01-23
+
+### Added
+- **Internal Invitations**: New `'internal'` delivery type for customer-managed invitations
+  - Allows creating invitations with `delivery_types: ['internal']`
+  - No email/SMS communication triggered by Vortex
+  - Target value can be any customer-defined identifier
+  - Useful for in-app invitation flows managed by customer's application
+
+### Changed
+- Updated `delivery_types` type to include `'internal'` as a valid Literal value
+
 ## [0.1.3] - 2025-01-29
 
 ### Added

{vortex_python_sdk-0.1.3/src/vortex_python_sdk.egg-info → vortex_python_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex-python-sdk
-Version: 0.1.3
+Version: 0.3.0
 Summary: Vortex Python SDK for invitation management and JWT generation
 Author-email: TeamVortexSoftware <support@vortexsoftware.com>
 License-Expression: MIT
@@ -40,6 +40,21 @@ Dynamic: license-file
 
 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
 
 ```bash

{vortex_python_sdk-0.1.3 → vortex_python_sdk-0.3.0}/README.md

@@ -2,6 +2,21 @@
 
 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
 
 ```bash

{vortex_python_sdk-0.1.3 → vortex_python_sdk-0.3.0}/pyproject.toml

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

{vortex_python_sdk-0.1.3 → vortex_python_sdk-0.3.0/src/vortex_python_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex-python-sdk
-Version: 0.1.3
+Version: 0.3.0
 Summary: Vortex Python SDK for invitation management and JWT generation
 Author-email: TeamVortexSoftware <support@vortexsoftware.com>
 License-Expression: MIT
@@ -40,6 +40,21 @@ Dynamic: license-file
 
 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
 
 ```bash

{vortex_python_sdk-0.1.3 → vortex_python_sdk-0.3.0}/src/vortex_sdk/types.py

@@ -6,7 +6,7 @@ from pydantic import BaseModel, Field
 class IdentifierInput(BaseModel):
     """Identifier structure for JWT generation"""
 
-    type: Literal["email", "sms"]
+    type: Literal["email", "phone"]
     value: str
 
 
@@ -61,12 +61,16 @@ class User(BaseModel):
     - email: User's email address
 
     Optional fields:
+    - name: User's display name
+    - avatar_url: User's avatar URL (must be HTTPS, max 2000 chars)
     - admin_scopes: List of admin scopes (e.g., ['autojoin'])
 
     Additional fields are allowed via extra parameter
     """
     id: str
     email: str
+    name: Optional[str] = None
+    avatar_url: Optional[str] = None
     admin_scopes: Optional[List[str]] = None
 
     class Config:
@@ -125,7 +129,7 @@ class JwtPayload(BaseModel):
 
 
 class InvitationTarget(BaseModel):
-    type: Literal["email", "sms"]
+    type: Literal["email", "phone"]
     value: str
 
 
@@ -181,7 +185,7 @@ class InvitationResult(BaseModel):
     created_at: str = Field(alias="createdAt")
     deactivated: bool
     delivery_count: int = Field(alias="deliveryCount")
-    delivery_types: List[Literal["email", "sms", "share"]] = Field(
+    delivery_types: List[Literal["email", "phone", "share", "internal"]] = Field(
         alias="deliveryTypes"
     )
     foreign_creator_id: str = Field(alias="foreignCreatorId")
@@ -209,6 +213,9 @@ class InvitationResult(BaseModel):
     expires: Optional[str] = None
     metadata: Optional[Dict[str, Any]] = None
     pass_through: Optional[str] = Field(None, alias="passThrough")
+    source: Optional[str] = None
+    creator_name: Optional[str] = Field(None, alias="creatorName")
+    creator_avatar_url: Optional[str] = Field(None, alias="creatorAvatarUrl")
 
     class Config:
         populate_by_name = True
@@ -258,3 +265,69 @@ ApiResponseJson = Union[
     InvitationResult, Dict[str, List[InvitationResult]], Dict[str, Any]
 ]
 ApiRequestBody = Union[AcceptInvitationRequest, None]
+
+
+# --- Types for creating invitations via backend API ---
+
+class CreateInvitationTargetType(str):
+    """Target types for creating invitations"""
+    EMAIL = "email"
+    PHONE = "phone"
+    INTERNAL = "internal"
+
+
+class CreateInvitationTarget(BaseModel):
+    """Target for creating an invitation"""
+    type: Literal["email", "phone", "internal"]
+    value: str
+
+
+class Inviter(BaseModel):
+    """
+    Information about the user creating the invitation (the inviter).
+    This is equivalent to what would be extracted from a JWT in client-side flows.
+    """
+    user_id: str = Field(alias="userId")
+    user_email: Optional[str] = Field(None, alias="userEmail")
+    name: Optional[str] = None
+    avatar_url: Optional[str] = Field(None, alias="avatarUrl")
+
+    class Config:
+        populate_by_name = True
+
+
+class CreateInvitationGroup(BaseModel):
+    """Group information for creating invitations"""
+    type: str
+    group_id: str = Field(alias="groupId")
+    name: str
+
+    class Config:
+        populate_by_name = True
+
+
+class BackendCreateInvitationRequest(BaseModel):
+    """
+    Request body for creating an invitation via the public API (backend SDK use).
+    """
+    widget_configuration_id: str = Field(alias="widgetConfigurationId")
+    target: CreateInvitationTarget
+    inviter: Inviter
+    groups: Optional[List[CreateInvitationGroup]] = None
+    source: Optional[str] = None
+    template_variables: Optional[Dict[str, str]] = Field(None, alias="templateVariables")
+    metadata: Optional[Dict[str, Any]] = None
+
+    class Config:
+        populate_by_name = True
+
+
+class CreateInvitationResponse(BaseModel):
+    """Response from creating an invitation"""
+    id: str
+    short_link: str = Field(alias="shortLink")
+    status: str
+    created_at: str = Field(alias="createdAt")
+
+    class Config:
+        populate_by_name = True

{vortex_python_sdk-0.1.3 → vortex_python_sdk-0.3.0}/src/vortex_sdk/vortex.py

@@ -13,8 +13,13 @@ logger = logging.getLogger(__name__)
 
 from .types import (
     AcceptUser,
+    BackendCreateInvitationRequest,
+    CreateInvitationGroup,
+    CreateInvitationResponse,
+    CreateInvitationTarget,
     Invitation,
     InvitationTarget,
+    Inviter,
     User,
     VortexApiError,
 )
@@ -48,7 +53,8 @@ class Vortex:
         Generate a JWT token for a user
 
         Args:
-            user: User object or dict with 'id', 'email', and optional 'admin_scopes'
+            user: User object or dict with 'id', 'email', and optional 'name',
+                  'avatar_url', 'admin_scopes'
             **extra: Additional properties to include in JWT payload
 
         Returns:
@@ -61,7 +67,13 @@ class Vortex:
             user = {'id': 'user-123', 'email': 'user@example.com', 'admin_scopes': ['autojoin']}
             jwt = vortex.generate_jwt(user=user)
 
-            # With additional properties
+            # With additional properties including name and avatar
+            user = {
+                'id': 'user-123',
+                'email': 'user@example.com',
+                'name': 'John Doe',
+                'avatar_url': 'https://example.com/avatar.jpg'
+            }
             jwt = vortex.generate_jwt(user=user, role='admin', department='Engineering')
         """
         # Convert dict to User if needed
@@ -114,6 +126,14 @@ class Vortex:
             "expires": expires,
         }
 
+        # Add name if present (convert snake_case to camelCase for JWT)
+        if user.name:
+            jwt_payload["name"] = user.name
+
+        # Add avatarUrl if present (convert snake_case to camelCase for JWT)
+        if user.avatar_url:
+            jwt_payload["avatarUrl"] = user.avatar_url
+
         # Add adminScopes if present
         if user.admin_scopes:
             jwt_payload["adminScopes"] = user.admin_scopes
@@ -399,7 +419,7 @@ class Vortex:
             user = AcceptUser()
             if target_type == "email":
                 user.email = target_value
-            elif target_type in ("sms", "phoneNumber"):
+            elif target_type in ("phone", "phoneNumber"):
                 user.phone = target_value
             else:
                 # For other types, try to use as email
@@ -492,7 +512,7 @@ class Vortex:
             user = AcceptUser()
             if target_type == "email":
                 user.email = target_value
-            elif target_type in ("sms", "phoneNumber"):
+            elif target_type in ("phone", "phoneNumber"):
                 user.phone = target_value
             else:
                 # For other types, try to use as email
@@ -635,6 +655,132 @@ class Vortex:
         )
         return Invitation(**response)
 
+    async def create_invitation(
+        self,
+        widget_configuration_id: str,
+        target: Union[CreateInvitationTarget, Dict[str, str]],
+        inviter: Union[Inviter, Dict[str, str]],
+        groups: Optional[List[Union[CreateInvitationGroup, Dict[str, str]]]] = None,
+        source: Optional[str] = None,
+        template_variables: Optional[Dict[str, str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> CreateInvitationResponse:
+        """
+        Create an invitation from your backend.
+
+        This method allows you to create invitations programmatically using your API key,
+        without requiring a user JWT token. Useful for server-side invitation creation,
+        such as "People You May Know" flows or admin-initiated invitations.
+
+        Args:
+            widget_configuration_id: The widget configuration ID to use
+            target: The target of the invitation (who is being invited)
+                   - type: 'email', 'phone', or 'internal'
+                   - value: Email address, phone number, or internal user ID
+            inviter: Information about the user creating the invitation
+                    - user_id: Your internal user ID for the inviter (required)
+                    - user_email: Optional email of the inviter
+                    - name: Optional display name of the inviter
+            groups: Optional groups/scopes to associate with the invitation
+            source: Optional source for analytics (defaults to 'api')
+            template_variables: Optional template variables for email customization
+            metadata: Optional metadata passed through to webhooks
+
+        Returns:
+            CreateInvitationResponse with id, short_link, status, and created_at
+
+        Example:
+            # Create an email invitation
+            result = await vortex.create_invitation(
+                widget_configuration_id="widget-config-123",
+                target={"type": "email", "value": "invitee@example.com"},
+                inviter={"user_id": "user-456", "user_email": "inviter@example.com"},
+                groups=[{"type": "team", "group_id": "team-789", "name": "Engineering"}],
+            )
+
+            # Create an internal invitation (PYMK flow - no email sent)
+            result = await vortex.create_invitation(
+                widget_configuration_id="widget-config-123",
+                target={"type": "internal", "value": "internal-user-abc"},
+                inviter={"user_id": "user-456"},
+                source="pymk",
+            )
+        """
+        # Convert dicts to models if needed
+        if isinstance(target, dict):
+            target = CreateInvitationTarget(**target)
+        if isinstance(inviter, dict):
+            inviter = Inviter(**inviter)
+        if groups:
+            groups = [
+                CreateInvitationGroup(**g) if isinstance(g, dict) else g
+                for g in groups
+            ]
+
+        request = BackendCreateInvitationRequest(
+            widget_configuration_id=widget_configuration_id,
+            target=target,
+            inviter=inviter,
+            groups=groups,
+            source=source,
+            template_variables=template_variables,
+            metadata=metadata,
+        )
+
+        # Use by_alias=True to get camelCase keys for the API
+        response = await self._vortex_api_request(
+            "POST", "/invitations", data=request.model_dump(by_alias=True, exclude_none=True)
+        )
+        return CreateInvitationResponse(**response)
+
+    def create_invitation_sync(
+        self,
+        widget_configuration_id: str,
+        target: Union[CreateInvitationTarget, Dict[str, str]],
+        inviter: Union[Inviter, Dict[str, str]],
+        groups: Optional[List[Union[CreateInvitationGroup, Dict[str, str]]]] = None,
+        source: Optional[str] = None,
+        template_variables: Optional[Dict[str, str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> CreateInvitationResponse:
+        """
+        Create an invitation from your backend (synchronous version).
+
+        See create_invitation() for full documentation.
+
+        Example:
+            result = vortex.create_invitation_sync(
+                widget_configuration_id="widget-config-123",
+                target={"type": "email", "value": "invitee@example.com"},
+                inviter={"user_id": "user-456"},
+            )
+        """
+        # Convert dicts to models if needed
+        if isinstance(target, dict):
+            target = CreateInvitationTarget(**target)
+        if isinstance(inviter, dict):
+            inviter = Inviter(**inviter)
+        if groups:
+            groups = [
+                CreateInvitationGroup(**g) if isinstance(g, dict) else g
+                for g in groups
+            ]
+
+        request = BackendCreateInvitationRequest(
+            widget_configuration_id=widget_configuration_id,
+            target=target,
+            inviter=inviter,
+            groups=groups,
+            source=source,
+            template_variables=template_variables,
+            metadata=metadata,
+        )
+
+        response = self._vortex_api_request_sync(
+            "POST", "/invitations", data=request.model_dump(by_alias=True, exclude_none=True)
+        )
+        return CreateInvitationResponse(**response)
+
     async def close(self) -> None:
         """Close the HTTP client"""
         await self._client.aclose()