teams-phone-cli 0.1.2__py3-none-any.whl

teams_phone/models/number.py

@@ -0,0 +1,184 @@
+"""Phone number assignment models for Teams Phone Graph API responses.
+
+These models represent phone number inventory and async operation data from Microsoft Graph API.
+All models use `extra="forbid"` for strict contract validation to detect API changes.
+"""
+
+from datetime import datetime
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class NumberType(str, Enum):
+    """Phone number type in Teams Phone.
+
+    Attributes:
+        DIRECT_ROUTING: Direct routing phone number.
+        CALLING_PLAN: Microsoft Calling Plan phone number.
+        OPERATOR_CONNECT: Operator Connect phone number.
+    """
+
+    DIRECT_ROUTING = "directRouting"
+    CALLING_PLAN = "callingPlan"
+    OPERATOR_CONNECT = "operatorConnect"
+
+
+class ActivationState(str, Enum):
+    """Phone number activation state.
+
+    Attributes:
+        ACTIVATED: Number is active and ready for use.
+        ASSIGNMENT_PENDING: Number assignment is in progress.
+        ASSIGNMENT_FAILED: Number assignment failed.
+        UPDATE_PENDING: Number update is in progress.
+        UPDATE_FAILED: Number update failed.
+    """
+
+    ACTIVATED = "activated"
+    ASSIGNMENT_PENDING = "assignmentPending"
+    ASSIGNMENT_FAILED = "assignmentFailed"
+    UPDATE_PENDING = "updatePending"
+    UPDATE_FAILED = "updateFailed"
+
+
+class AssignmentStatus(str, Enum):
+    """Phone number assignment status.
+
+    Attributes:
+        UNASSIGNED: Number is not assigned to any user or resource.
+        USER_ASSIGNED: Number is assigned to a user.
+        CONFERENCE_ASSIGNED: Number is assigned to a conference bridge.
+        VOICE_APPLICATION_ASSIGNED: Number is assigned to a voice application.
+    """
+
+    UNASSIGNED = "unassigned"
+    USER_ASSIGNED = "userAssigned"
+    CONFERENCE_ASSIGNED = "conferenceAssigned"
+    VOICE_APPLICATION_ASSIGNED = "voiceApplicationAssigned"
+
+
+class AssignmentCategory(str, Enum):
+    """Phone number assignment category.
+
+    Attributes:
+        PRIMARY: Primary phone number for the user.
+        PRIVATE: Private line number.
+        ALTERNATE: Alternate phone number.
+    """
+
+    PRIMARY = "primary"
+    PRIVATE = "private"
+    ALTERNATE = "alternate"
+
+
+class OperationStatus(str, Enum):
+    """Async operation status from Graph API.
+
+    Attributes:
+        NOT_STARTED: Operation has not started.
+        RUNNING: Operation is in progress.
+        SUCCEEDED: Operation completed successfully.
+        FAILED: Operation failed.
+        SKIPPED: Operation was skipped.
+        UNKNOWN_FUTURE_VALUE: Reserved for future values.
+    """
+
+    NOT_STARTED = "notStarted"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+    UNKNOWN_FUTURE_VALUE = "unknownFutureValue"
+
+
+class OperationNumber(BaseModel):
+    """Status of a phone number in an async operation.
+
+    Attributes:
+        resource_location: URL to the phone number resource.
+        status: Current status of the operation for this number.
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    resource_location: str = Field(alias="resourceLocation")
+    status: OperationStatus
+
+
+class AsyncOperation(BaseModel):
+    """Async operation polling response from Graph API.
+
+    Represents the response from polling a long-running phone number operation.
+
+    Attributes:
+        odata_context: OData context annotation from Graph API.
+        odata_type: OData type annotation from Graph API.
+        id: Unique identifier for the operation (not present in polling responses).
+        created_date_time: When the operation was created.
+        status: Overall status of the operation.
+        numbers: Status of individual phone numbers in the operation.
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    odata_context: str | None = Field(alias="@odata.context", default=None)
+    odata_type: str | None = Field(alias="@odata.type", default=None)
+    id: str | None = Field(default=None)
+    created_date_time: datetime = Field(alias="createdDateTime")
+    status: OperationStatus
+    numbers: list[OperationNumber] = Field(default=[])
+
+
+class NumberAssignment(BaseModel):
+    """Phone number assignment from Graph API.
+
+    Represents a phone number in the tenant's inventory with its assignment details.
+
+    Attributes:
+        id: Unique identifier for the number assignment.
+        telephone_number: Phone number in E.164 format.
+        operator_id: ID of the operator providing the number.
+        number_type: Type of the phone number (direct routing, calling plan, etc.).
+        activation_state: Current activation state of the number.
+        capabilities: List of capabilities (userAssignment, conferenceAssignment, etc.).
+        location_id: ID of the emergency location.
+        civic_address_id: ID of the civic address.
+        network_site_id: ID of the network site.
+        assignment_target_id: User or resource account object ID.
+        assignment_category: Category of assignment (primary, private, alternate).
+        assignment_status: Current assignment status.
+        port_in_status: Status of port-in if applicable.
+        iso_country_code: ISO country code (e.g., "US").
+        city: City associated with the number.
+        number_source: Source of the number (online, onPremises).
+        supported_customer_actions: Actions the customer can perform on this number.
+        reverse_number_lookup_options: Available reverse lookup options.
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    id: str
+    telephone_number: str = Field(alias="telephoneNumber")
+    operator_id: str | None = Field(alias="operatorId", default=None)
+    number_type: NumberType = Field(alias="numberType")
+    activation_state: ActivationState = Field(alias="activationState")
+    capabilities: list[str]
+    location_id: str | None = Field(alias="locationId", default=None)
+    civic_address_id: str | None = Field(alias="civicAddressId", default=None)
+    network_site_id: str | None = Field(alias="networkSiteId", default=None)
+    assignment_target_id: str | None = Field(alias="assignmentTargetId", default=None)
+    assignment_category: AssignmentCategory | None = Field(
+        alias="assignmentCategory", default=None
+    )
+    assignment_status: AssignmentStatus = Field(alias="assignmentStatus")
+    port_in_status: str | None = Field(alias="portInStatus", default=None)
+    iso_country_code: str | None = Field(alias="isoCountryCode", default=None)
+    city: str | None = Field(default=None)
+    number_source: str | None = Field(alias="numberSource", default=None)
+    supported_customer_actions: list[str] = Field(
+        alias="supportedCustomerActions", default=[]
+    )
+    reverse_number_lookup_options: list[str] = Field(
+        alias="reverseNumberLookupOptions", default=[]
+    )

teams_phone/models/policy.py

@@ -0,0 +1,26 @@
+"""Voice policy model for CSV cache data."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Policy(BaseModel):
+    """Voice policy from CSV cache.
+
+    Represents a Teams voice policy exported via PowerShell.
+    Used for validation and display since Graph API doesn't expose policy endpoints.
+
+    Attributes:
+        policy_type: Type of policy (e.g., "TeamsCallingPolicy", "TenantDialPlan").
+        policy_name: Human-readable policy name.
+        policy_id: Unique identifier for the policy.
+        description: Optional policy description.
+        is_global: Whether this is the global (default) policy.
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    policy_type: str = Field(alias="policyType")
+    policy_name: str = Field(alias="policyName")
+    policy_id: str = Field(alias="policyId")
+    description: str | None = Field(alias="description", default=None)
+    is_global: bool = Field(alias="isGlobal")

teams_phone/models/tenant.py

@@ -0,0 +1,45 @@
+"""Tenant profile models for multi-tenant CLI configuration."""
+
+from enum import Enum
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict
+
+
+class AuthMethod(str, Enum):
+    """Authentication methods supported for tenant profiles.
+
+    Attributes:
+        CERTIFICATE: Certificate-based authentication using X.509 certificate.
+        CLIENT_SECRET: Client secret authentication (less secure, for dev/test).
+    """
+
+    CERTIFICATE = "certificate"
+    CLIENT_SECRET = "client-secret"
+
+
+class TenantProfile(BaseModel):
+    """Configuration for a Microsoft Entra tenant.
+
+    Represents a tenant profile stored in config.toml for multi-tenant
+    CLI operations. Supports both certificate and client-secret authentication.
+
+    Attributes:
+        name: Profile name used as key in configuration (e.g., "contoso").
+        tenant_id: Microsoft Entra tenant ID (UUID).
+        client_id: App registration client ID (UUID).
+        display_name: Human-readable tenant name for display.
+        auth_method: Authentication method (certificate or client-secret).
+        cert_path: Path to certificate file (required if auth_method is certificate).
+        default_location: Default emergency location name for number assignments.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    tenant_id: UUID
+    client_id: UUID
+    display_name: str
+    auth_method: AuthMethod
+    cert_path: str | None = None
+    default_location: str | None = None

teams_phone/models/user.py

@@ -0,0 +1,117 @@
+"""User configuration models for Teams Phone Graph API responses.
+
+These models represent the Teams User Configuration data from Microsoft Graph API.
+All models use `extra="forbid"` for strict contract validation to detect API changes.
+"""
+
+from datetime import datetime
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AccountType(str, Enum):
+    """User account type in Microsoft Teams.
+
+    Attributes:
+        USER: Standard user account.
+        RESOURCE_ACCOUNT: Resource account (e.g., auto attendant, call queue).
+        GUEST: Guest user account.
+        SFB_ON_PREM_USER: Skype for Business on-premises user.
+        INELIGIBLE_USER: User not eligible for Teams Phone (e.g., no license).
+        UNKNOWN: Unknown account type.
+    """
+
+    USER = "user"
+    RESOURCE_ACCOUNT = "resourceAccount"
+    GUEST = "guest"
+    SFB_ON_PREM_USER = "sfbOnPremUser"
+    INELIGIBLE_USER = "ineligibleUser"
+    UNKNOWN = "unknown"
+
+
+class TelephoneNumber(BaseModel):
+    """A telephone number assigned to a user.
+
+    Attributes:
+        telephone_number: The phone number in E.164 format (e.g., "+13235533696").
+        assignment_category: Assignment category (e.g., "primary", "alternate").
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    telephone_number: str = Field(alias="telephoneNumber")
+    assignment_category: str = Field(alias="assignmentCategory")
+
+
+class PolicyAssignmentDetail(BaseModel):
+    """Details of a policy assignment to a user.
+
+    Attributes:
+        display_name: Human-readable policy name.
+        assignment_type: How the policy was assigned (e.g., "direct", "group").
+        policy_id: Unique identifier for the policy.
+        group_id: Group ID if assigned via group (optional).
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    display_name: str = Field(alias="displayName")
+    assignment_type: str = Field(alias="assignmentType")
+    policy_id: str = Field(alias="policyId")
+    group_id: str | None = Field(alias="groupId", default=None)
+
+
+class EffectivePolicyAssignment(BaseModel):
+    """An effective policy assignment on a user.
+
+    Represents a single policy type and its assignment details.
+
+    Attributes:
+        policy_type: Type of the policy (e.g., "TeamsCallingPolicy", "TenantDialPlan").
+        policy_assignment: Details of how the policy is assigned.
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    policy_type: str = Field(alias="policyType")
+    policy_assignment: PolicyAssignmentDetail = Field(alias="policyAssignment")
+
+
+class UserConfiguration(BaseModel):
+    """Teams user configuration from Microsoft Graph API.
+
+    Represents a user's Teams Phone configuration including phone numbers,
+    policies, and voice enablement status.
+
+    Attributes:
+        id: User's Entra object ID (GUID).
+        user_principal_name: User's UPN (email format).
+        tenant_id: Microsoft Entra tenant ID.
+        display_name: User's display name.
+        account_type: Type of user account.
+        is_enterprise_voice_enabled: Whether enterprise voice is enabled.
+        feature_types: List of enabled features (e.g., "Teams", "CallingPlan").
+        telephone_numbers: List of assigned telephone numbers.
+        effective_policy_assignments: List of effective policy assignments.
+        created_date_time: When the user configuration was created.
+        modified_date_time: When the user configuration was last modified.
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    id: str
+    user_principal_name: str = Field(alias="userPrincipalName")
+    tenant_id: str = Field(alias="tenantId")
+    display_name: str | None = Field(alias="displayName", default=None)
+    account_type: AccountType = Field(alias="accountType")
+    is_enterprise_voice_enabled: bool = Field(alias="isEnterpriseVoiceEnabled")
+    feature_types: list[str] = Field(alias="featureTypes", default=[])
+    telephone_numbers: list[TelephoneNumber] = Field(
+        alias="telephoneNumbers", default=[]
+    )
+    effective_policy_assignments: list[EffectivePolicyAssignment] = Field(
+        alias="effectivePolicyAssignments", default=[]
+    )
+    created_date_time: datetime | None = Field(alias="createdDateTime", default=None)
+    modified_date_time: datetime | None = Field(alias="modifiedDateTime", default=None)

teams_phone/services/__init__.py

@@ -0,0 +1,21 @@
+"""Service Layer - Business logic for Teams Phone operations."""
+
+from teams_phone.services.auth_service import CLIENT_SECRET_ENV_VAR, SCOPES, AuthService
+from teams_phone.services.location_service import LocationService
+from teams_phone.services.policy_service import PolicyService
+from teams_phone.services.tenant_service import TenantService
+
+
+# Note: UserService and NumberService are not exported here to avoid circular import.
+# Import directly:
+#   from teams_phone.services.user_service import UserService
+#   from teams_phone.services.number_service import NumberService
+
+__all__ = [
+    "AuthService",
+    "CLIENT_SECRET_ENV_VAR",
+    "LocationService",
+    "PolicyService",
+    "SCOPES",
+    "TenantService",
+]