gateway/modules/datamodels/datamodelInvitation.py

# Copyright (c) 2025 Patrick Motsch
# All rights reserved.
"""
Invitation model for self-service onboarding.
Token-basierte Einladungen für neue User zu Mandanten/Features.
"""

import uuid
import secrets
from typing import Optional, List
from pydantic import BaseModel, Field
from modules.datamodels.datamodelBase import PowerOnModel
from modules.shared.attributeUtils import registerModelLabels


class Invitation(PowerOnModel):
    """
    Einladungs-Token für neue User.
    Ermöglicht Self-Service Onboarding zu Mandanten und Feature-Instanzen.
    """
    id: str = Field(
        default_factory=lambda: str(uuid.uuid4()),
        description="Unique ID of the invitation",
        json_schema_extra={"frontend_type": "text", "frontend_readonly": True, "frontend_required": False}
    )
    token: str = Field(
        default_factory=lambda: secrets.token_urlsafe(32),
        description="Secure invitation token",
        json_schema_extra={"frontend_type": "text", "frontend_readonly": True, "frontend_required": False}
    )
    
    # Ziel der Einladung
    mandateId: str = Field(
        description="FK → Mandate.id - Target mandate for the invitation",
        json_schema_extra={"frontend_type": "text", "frontend_readonly": True, "frontend_required": True}
    )
    featureInstanceId: Optional[str] = Field(
        default=None,
        description="Optional FK → FeatureInstance.id - Direct access to specific feature",
        json_schema_extra={"frontend_type": "text", "frontend_readonly": True, "frontend_required": False}
    )
    roleIds: List[str] = Field(
        default_factory=list,
        description="List of Role IDs to assign to the invited user",
        json_schema_extra={"frontend_type": "multiselect", "frontend_readonly": False, "frontend_required": True}
    )
    
    # Einladungs-Details
    targetUsername: Optional[str] = Field(
        default=None,
        description="Username of the invited user (must match on acceptance)",
        json_schema_extra={"frontend_type": "text", "frontend_readonly": False, "frontend_required": False}
    )
    email: Optional[str] = Field(
        default=None,
        description="Email address to send invitation link (optional)",
        json_schema_extra={"frontend_type": "email", "frontend_readonly": False, "frontend_required": False}
    )
    expiresAt: float = Field(
        description="When the invitation expires (UTC timestamp)",
        json_schema_extra={"frontend_type": "timestamp", "frontend_readonly": True, "frontend_required": True}
    )
    
    # Status
    usedBy: Optional[str] = Field(
        default=None,
        description="User ID of the person who used the invitation",
        json_schema_extra={"frontend_type": "text", "frontend_readonly": True, "frontend_required": False}
    )
    usedAt: Optional[float] = Field(
        default=None,
        description="When the invitation was used (UTC timestamp)",
        json_schema_extra={"frontend_type": "timestamp", "frontend_readonly": True, "frontend_required": False}
    )
    revokedAt: Optional[float] = Field(
        default=None,
        description="When the invitation was revoked (UTC timestamp)",
        json_schema_extra={"frontend_type": "timestamp", "frontend_readonly": True, "frontend_required": False}
    )
    
    # Email-Status
    emailSent: Optional[bool] = Field(
        default=False,
        description="Whether the invitation email was successfully sent",
        json_schema_extra={"frontend_type": "checkbox", "frontend_readonly": True, "frontend_required": False}
    )
    
    # Einschränkungen
    maxUses: int = Field(
        default=1,
        ge=1,
        le=100,
        description="Maximum number of times this invitation can be used",
        json_schema_extra={"frontend_type": "number", "frontend_readonly": False, "frontend_required": False}
    )
    currentUses: int = Field(
        default=0,
        ge=0,
        description="Current number of times this invitation has been used",
        json_schema_extra={"frontend_type": "number", "frontend_readonly": True, "frontend_required": False}
    )


registerModelLabels(
    "Invitation",
    {"en": "Invitation", "de": "Einladung", "fr": "Invitation"},
    {
        "id": {"en": "ID", "de": "ID", "fr": "ID"},
        "token": {"en": "Token", "de": "Token", "fr": "Jeton"},
        "mandateId": {"en": "Mandate", "de": "Mandant", "fr": "Mandat"},
        "featureInstanceId": {"en": "Feature Instance", "de": "Feature-Instanz", "fr": "Instance"},
        "roleIds": {"en": "Roles", "de": "Rollen", "fr": "Rôles"},
        "targetUsername": {"en": "Target Username", "de": "Ziel-Benutzername", "fr": "Nom d'utilisateur cible"},
        "email": {"en": "Email (optional)", "de": "E-Mail (optional)", "fr": "Email (optionnel)"},
        "expiresAt": {"en": "Expires At", "de": "Gültig bis", "fr": "Expire le"},
        "usedBy": {"en": "Used By", "de": "Verwendet von", "fr": "Utilisé par"},
        "usedAt": {"en": "Used At", "de": "Verwendet am", "fr": "Utilisé le"},
        "revokedAt": {"en": "Revoked At", "de": "Widerrufen am", "fr": "Révoqué le"},
        "emailSent": {"en": "Email Sent", "de": "E-Mail gesendet", "fr": "Email envoyé"},
        "maxUses": {"en": "Max Uses", "de": "Max. Verwendungen", "fr": "Utilisations max"},
        "currentUses": {"en": "Current Uses", "de": "Aktuelle Verwendungen", "fr": "Utilisations actuelles"},
    },
)