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

teams_phone/cli/users.py

@@ -0,0 +1,394 @@
+"""User management commands for Teams Phone CLI.
+
+This module provides CLI commands for listing, showing, and searching
+Teams users with their voice configurations.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+import typer
+
+from teams_phone.cli.context import get_context
+from teams_phone.cli.helpers import run_with_service
+from teams_phone.exceptions import TeamsPhoneError
+from teams_phone.models import AccountType, UserConfiguration
+from teams_phone.services.user_service import UserService
+
+
+users_app = typer.Typer(
+    name="users",
+    help="Manage Teams users.",
+    no_args_is_help=True,
+)
+
+
+class SearchField(str, Enum):
+    """Search field options for user search."""
+
+    NAME = "name"
+    UPN = "upn"
+    PHONE = "phone"
+
+
+def _format_phone_number(user: UserConfiguration) -> str:
+    """Format phone number for display, or return dash if none assigned."""
+    if user.telephone_numbers:
+        return user.telephone_numbers[0].telephone_number
+    return "—"
+
+
+def _format_license_status(user: UserConfiguration) -> str:
+    """Format license status for display."""
+    return "Licensed" if user.is_enterprise_voice_enabled else "Unlicensed"
+
+
+def _format_voice_enabled(user: UserConfiguration) -> str:
+    """Format voice enabled status for display."""
+    return "Yes" if user.is_enterprise_voice_enabled else "No"
+
+
+def _format_account_type(account_type: AccountType) -> str:
+    """Format account type for display."""
+    display_names = {
+        AccountType.USER: "User",
+        AccountType.RESOURCE_ACCOUNT: "Resource Account",
+        AccountType.GUEST: "Guest",
+        AccountType.SFB_ON_PREM_USER: "SfB On-Prem",
+        AccountType.UNKNOWN: "Unknown",
+    }
+    return display_names.get(account_type, account_type.value)
+
+
+def _user_to_list_dict(user: UserConfiguration) -> dict[str, Any]:
+    """Convert UserConfiguration to dict for list/search table display."""
+    return {
+        "display_name": user.display_name or "—",
+        "upn": user.user_principal_name,
+        "account_type": _format_account_type(user.account_type),
+        "phone_number": _format_phone_number(user),
+        "license_status": _format_license_status(user),
+        "voice_enabled": _format_voice_enabled(user),
+    }
+
+
+def _user_to_json_dict(user: UserConfiguration) -> dict[str, Any]:
+    """Convert UserConfiguration to dict for JSON output."""
+    return {
+        "id": user.id,
+        "display_name": user.display_name,
+        "user_principal_name": user.user_principal_name,
+        "account_type": user.account_type.value,
+        "is_enterprise_voice_enabled": user.is_enterprise_voice_enabled,
+        "telephone_numbers": [
+            {
+                "telephone_number": t.telephone_number,
+                "assignment_category": t.assignment_category,
+            }
+            for t in user.telephone_numbers
+        ],
+        "feature_types": user.feature_types,
+        "effective_policy_assignments": [
+            {
+                "policy_type": p.policy_type,
+                "policy_assignment": {
+                    "display_name": p.policy_assignment.display_name,
+                    "assignment_type": p.policy_assignment.assignment_type,
+                    "policy_id": p.policy_assignment.policy_id,
+                    "group_id": p.policy_assignment.group_id,
+                },
+            }
+            for p in user.effective_policy_assignments
+        ],
+    }
+
+
+def _get_policy_value(user: UserConfiguration, policy_type: str) -> str:
+    """Get the display name for a specific policy type, or 'Global (Default)' if not set."""
+    for assignment in user.effective_policy_assignments:
+        if assignment.policy_type == policy_type:
+            return assignment.policy_assignment.display_name or "Global (Default)"
+    return "Global (Default)"
+
+
+@users_app.command("list")
+def list_users(
+    ctx: typer.Context,
+    licensed: bool | None = typer.Option(
+        None,
+        "--licensed/--unlicensed",
+        help="Filter by license status (--licensed or --unlicensed).",
+    ),
+    assigned: bool | None = typer.Option(
+        None,
+        "--assigned/--unassigned",
+        help="Filter by phone number assignment (--assigned or --unassigned).",
+    ),
+    account_type: AccountType | None = typer.Option(
+        None,
+        "--account-type",
+        "-a",
+        help="Filter by account type (user, resourceAccount, guest).",
+    ),
+    limit: int | None = typer.Option(
+        None,
+        "--limit",
+        "-l",
+        help="Limit results to n users.",
+    ),
+    all_users: bool = typer.Option(
+        False,
+        "--all",
+        help="Fetch all users (may be slow for large tenants).",
+    ),
+) -> None:
+    """List users with voice configuration."""
+    cli_ctx = get_context(ctx)
+    formatter = cli_ctx.get_output_formatter()
+
+    # Validate mutually exclusive options
+    if limit is not None and all_users:
+        formatter.error(
+            "Cannot specify both --limit and --all",
+            remediation="Use either --limit <n> to limit results or --all to fetch all users.",
+        )
+        raise typer.Exit(5)  # ValidationError exit code
+
+    # Determine max_items: None for --all, provided limit, or default 50
+    if all_users:
+        max_items = None
+    elif limit is not None:
+        max_items = limit
+    else:
+        max_items = 50  # Default limit
+
+    try:
+        users, formatter = run_with_service(
+            ctx,
+            service_factory=UserService,
+            operation=lambda svc: svc.list_users(
+                licensed=licensed,
+                assigned=assigned,
+                account_type=account_type,
+                max_items=max_items,
+            ),
+        )
+
+        if cli_ctx.json_output:
+            formatter.json([_user_to_json_dict(u) for u in users])
+        else:
+            if not users:
+                formatter.info("No users found matching the specified criteria")
+            else:
+                formatter.table(
+                    data=[_user_to_list_dict(u) for u in users],
+                    columns=[
+                        "display_name",
+                        "upn",
+                        "account_type",
+                        "phone_number",
+                        "license_status",
+                        "voice_enabled",
+                    ],
+                    title="Users",
+                )
+    except TeamsPhoneError as e:
+        formatter.error(e.message, remediation=e.remediation)
+        raise typer.Exit(e.exit_code) from None
+
+
+@users_app.command("show")
+def show_user(
+    ctx: typer.Context,
+    user: str = typer.Argument(
+        ...,
+        help="User identifier: UPN (email), display name, or object ID.",
+    ),
+) -> None:
+    """Show detailed voice configuration for a specific user."""
+    cli_ctx = get_context(ctx)
+    formatter = cli_ctx.get_output_formatter()
+
+    try:
+        user_config, _ = run_with_service(
+            ctx,
+            service_factory=UserService,
+            operation=lambda svc: svc.resolve_user(user),
+        )
+
+        if cli_ctx.json_output:
+            formatter.json(_user_to_json_dict(user_config))
+        else:
+            # Identity section
+            formatter.table(
+                data=[
+                    {"field": "Display Name", "value": user_config.display_name or "—"},
+                    {"field": "UPN", "value": user_config.user_principal_name},
+                    {"field": "Object ID", "value": user_config.id},
+                    {
+                        "field": "Account Type",
+                        "value": _format_account_type(user_config.account_type),
+                    },
+                ],
+                columns=["field", "value"],
+                title="Identity",
+            )
+
+            # Phone Number section
+            if user_config.telephone_numbers:
+                phone_data = [
+                    {"number": num.telephone_number, "type": num.assignment_category}
+                    for num in user_config.telephone_numbers
+                ]
+            else:
+                phone_data = [{"number": "No phone number assigned", "type": "—"}]
+            formatter.table(
+                data=phone_data,
+                columns=["number", "type"],
+                title="Phone Numbers",
+            )
+
+            # Licensing section
+            licensing_data = [
+                {
+                    "field": "Enterprise Voice",
+                    "value": _format_voice_enabled(user_config),
+                },
+                {"field": "Status", "value": _format_license_status(user_config)},
+            ]
+            if user_config.feature_types:
+                licensing_data.append(
+                    {"field": "Features", "value": ", ".join(user_config.feature_types)}
+                )
+            formatter.table(
+                data=licensing_data,
+                columns=["field", "value"],
+                title="Licensing",
+            )
+
+            # Voice Policies section
+            formatter.table(
+                data=[
+                    {
+                        "policy": "Calling",
+                        "value": _get_policy_value(user_config, "TeamsCallingPolicy"),
+                    },
+                    {
+                        "policy": "Voicemail",
+                        "value": _get_policy_value(user_config, "TeamsCallParkPolicy"),
+                    },
+                    {
+                        "policy": "Emergency Calling",
+                        "value": _get_policy_value(
+                            user_config, "TeamsEmergencyCallingPolicy"
+                        ),
+                    },
+                    {
+                        "policy": "Emergency Call Routing",
+                        "value": _get_policy_value(
+                            user_config, "TeamsEmergencyCallRoutingPolicy"
+                        ),
+                    },
+                    {
+                        "policy": "Caller ID",
+                        "value": _get_policy_value(user_config, "TeamsCallerIdPolicy"),
+                    },
+                    {
+                        "policy": "Dial Plan",
+                        "value": _get_policy_value(user_config, "TenantDialPlan"),
+                    },
+                    {
+                        "policy": "Voice Routing",
+                        "value": _get_policy_value(
+                            user_config, "TeamsVoiceRoutingPolicy"
+                        ),
+                    },
+                ],
+                columns=["policy", "value"],
+                title="Voice Policies",
+            )
+
+    except TeamsPhoneError as e:
+        formatter.error(e.message, remediation=e.remediation)
+        raise typer.Exit(e.exit_code) from None
+
+
+@users_app.command("search")
+def search_users(
+    ctx: typer.Context,
+    query: str = typer.Argument(
+        ...,
+        help="Search term (partial match supported).",
+    ),
+    field: SearchField | None = typer.Option(
+        None,
+        "--field",
+        "-f",
+        help="Limit search to specific field: name, upn, phone.",
+    ),
+    limit: int = typer.Option(
+        25,
+        "--limit",
+        "-l",
+        help="Maximum results (default: 25).",
+    ),
+) -> None:
+    """Search for users by name, UPN, or phone number."""
+    cli_ctx = get_context(ctx)
+    formatter = cli_ctx.get_output_formatter()
+
+    # Modify query based on field option to force specific search behavior
+    search_query = query
+    if field == SearchField.PHONE:
+        # Ensure phone number format for search
+        if not query.startswith("+") and not query.isdigit():
+            # Try to use as-is, the service will handle it
+            search_query = query
+        elif query.isdigit():
+            search_query = f"+{query}"
+        else:
+            search_query = query
+    elif field == SearchField.UPN:
+        # UPN search expects @ - if not present, it will do display name search
+        # User should provide full UPN for exact match
+        search_query = query
+    elif field == SearchField.NAME:
+        # Name search is the default for non-phone, non-email queries
+        # Force display name search by ensuring no @ or +
+        if "@" not in query and not query.startswith("+"):
+            search_query = query
+        else:
+            # User provided email or phone format but wants name search
+            # This is an unusual case; proceed with the query as-is
+            search_query = query
+
+    try:
+        users, _ = run_with_service(
+            ctx,
+            service_factory=UserService,
+            operation=lambda svc: svc.search_users(search_query, max_results=limit),
+        )
+
+        if cli_ctx.json_output:
+            formatter.json([_user_to_json_dict(u) for u in users])
+        else:
+            if not users:
+                formatter.info(f"No users found matching '{query}'")
+            else:
+                formatter.table(
+                    data=[_user_to_list_dict(u) for u in users],
+                    columns=[
+                        "display_name",
+                        "upn",
+                        "account_type",
+                        "phone_number",
+                        "license_status",
+                        "voice_enabled",
+                    ],
+                    title=f"Search Results for '{query}'",
+                )
+    except TeamsPhoneError as e:
+        formatter.error(e.message, remediation=e.remediation)
+        raise typer.Exit(e.exit_code) from None

teams_phone/constants.py

@@ -0,0 +1,97 @@
+"""API URLs, exit codes, and default values for Teams Phone CLI."""
+
+from enum import IntEnum
+
+
+# =============================================================================
+# Microsoft Graph API URLs
+# =============================================================================
+
+GRAPH_API_BASE = "https://graph.microsoft.com/beta"
+"""Base URL for Microsoft Graph API (beta).
+
+Note: All /admin/teams/* endpoints require the beta API - no v1.0 equivalents exist.
+"""
+
+GRAPH_API_V1_BASE = "https://graph.microsoft.com/v1.0"
+"""Base URL for Microsoft Graph API (v1.0).
+
+Used for general user/organization queries where stable endpoints exist.
+"""
+
+# =============================================================================
+# Default File Paths
+# =============================================================================
+
+DEFAULT_CONFIG_PATH = "~/.teams-phone/config.toml"
+"""Default path for CLI configuration file."""
+
+DEFAULT_CACHE_PATH = "~/.teams-phone/cache"
+"""Default directory for cached data (users, numbers, policies)."""
+
+DEFAULT_TOKEN_PATH = "~/.teams-phone/tokens"
+"""Default directory for authentication token storage."""
+
+# =============================================================================
+# Cache and Timeout Settings
+# =============================================================================
+
+DEFAULT_TIMEOUT = 30
+"""Default HTTP request timeout in seconds."""
+
+MAX_RETRIES = 3
+"""Maximum number of retry attempts for transient failures (429, 5xx)."""
+
+CSV_STALE_DAYS = 30
+"""Number of days before CSV cache files (locations, policies) are considered stale."""
+
+TOKEN_EXPIRY_BUFFER_SECONDS = 300
+"""Seconds before token expiry to proactively refresh (5 minutes)."""
+
+# =============================================================================
+# Exit Codes
+# =============================================================================
+
+
+class ExitCode(IntEnum):
+    """CLI exit codes for structured error handling.
+
+    Exit codes map to specific exception types for consistent error reporting.
+    Using IntEnum allows shell-compatible integer comparison while preserving
+    semantic meaning in code.
+
+    Note: Exit code 8 (CONTRACT_ERROR) is intentionally not documented in
+    user-facing PRD/CLI spec as it indicates internal schema validation failures
+    that users cannot remediate directly.
+    """
+
+    SUCCESS = 0
+    """Operation completed successfully."""
+
+    GENERAL_ERROR = 1
+    """Unexpected error or unhandled exception."""
+
+    AUTH_ERROR = 2
+    """Authentication failure (token expired, invalid credentials)."""
+
+    AUTHZ_ERROR = 3
+    """Authorization failure (missing Graph API permissions)."""
+
+    NOT_FOUND = 4
+    """Resource not found (user, number, policy, location)."""
+
+    VALIDATION_ERROR = 5
+    """Input validation failure (invalid format, E911 violation)."""
+
+    RATE_LIMIT = 6
+    """Rate limit exceeded (Graph API throttling)."""
+
+    CONFIG_ERROR = 7
+    """Configuration error (invalid config file, missing tenant)."""
+
+    CONTRACT_ERROR = 8
+    """API contract violation (schema validation failure).
+
+    This exit code is for internal use when API responses don't match
+    expected schemas. Users should not encounter this in normal operation.
+    """

teams_phone/exceptions.py

@@ -0,0 +1,137 @@
+"""Custom exception hierarchy for Teams Phone CLI.
+
+This module defines the base exception class and specialized exceptions
+that map to CLI exit codes for structured error handling.
+"""
+
+from teams_phone.constants import ExitCode
+
+
+class TeamsPhoneError(Exception):
+    """Base exception for all Teams Phone CLI errors.
+
+    All custom exceptions inherit from this class, providing:
+    - An exit_code property for CLI exit status
+    - Optional remediation guidance for user-facing messages
+    - Consistent string formatting
+
+    Attributes:
+        message: The error description.
+        remediation: Optional guidance on how to fix the issue.
+        exit_code: CLI exit code (defaults to GENERAL_ERROR=1).
+    """
+
+    exit_code: int = ExitCode.GENERAL_ERROR
+
+    def __init__(self, message: str, *, remediation: str | None = None) -> None:
+        """Initialize the exception.
+
+        Args:
+            message: The error description.
+            remediation: Optional guidance on how to fix the issue.
+        """
+        self.message = message
+        self.remediation = remediation
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        """Format the exception for display.
+
+        If remediation is provided, it's appended to the message.
+        """
+        if self.remediation:
+            return f"{self.message}\n\nTo fix:\n{self.remediation}"
+        return self.message
+
+
+class AuthenticationError(TeamsPhoneError):
+    """Authentication failure (exit code 2).
+
+    Raised when authentication fails due to:
+    - Expired access token
+    - Invalid credentials
+    - Certificate issues
+    - Missing authentication configuration
+    """
+
+    exit_code: int = ExitCode.AUTH_ERROR
+
+
+class AuthorizationError(TeamsPhoneError):
+    """Authorization failure (exit code 3).
+
+    Raised when the authenticated principal lacks required permissions:
+    - Missing Graph API application permissions
+    - Insufficient role assignments
+    - Tenant-level restrictions
+    """
+
+    exit_code: int = ExitCode.AUTHZ_ERROR
+
+
+class NotFoundError(TeamsPhoneError):
+    """Resource not found (exit code 4).
+
+    Raised when a requested resource doesn't exist:
+    - User not found in tenant directory
+    - Phone number not in inventory
+    - Policy not configured
+    - Location not defined
+    """
+
+    exit_code: int = ExitCode.NOT_FOUND
+
+
+class ValidationError(TeamsPhoneError):
+    """Input validation failure (exit code 5).
+
+    Raised when input data fails validation:
+    - Invalid phone number format
+    - Missing required E911 location for Calling Plan numbers
+    - Invalid policy name or configuration
+    - CSV format or content errors
+    """
+
+    exit_code: int = ExitCode.VALIDATION_ERROR
+
+
+class RateLimitError(TeamsPhoneError):
+    """Rate limit exceeded (exit code 6).
+
+    Raised when Graph API returns HTTP 429 (throttled):
+    - Too many requests in a time window
+    - Tenant-level throttling limits reached
+
+    Note: The CLI will automatically retry with exponential backoff
+    before raising this exception.
+    """
+
+    exit_code: int = ExitCode.RATE_LIMIT
+
+
+class ConfigurationError(TeamsPhoneError):
+    """Configuration error (exit code 7).
+
+    Raised when configuration is invalid or missing:
+    - Config file doesn't exist or is malformed
+    - Required tenant not configured
+    - Invalid configuration values
+    """
+
+    exit_code: int = ExitCode.CONFIG_ERROR
+
+
+class ContractError(TeamsPhoneError):
+    """API contract violation (exit code 8).
+
+    Raised when API responses don't match expected schemas:
+    - Missing required fields in response
+    - Unexpected data types
+    - Schema validation failures
+
+    Note: This exception indicates an internal error that users
+    cannot remediate directly. It typically signals either an API
+    change or a bug in the CLI.
+    """
+
+    exit_code: int = ExitCode.CONTRACT_ERROR

teams_phone/infrastructure/__init__.py

@@ -0,0 +1,22 @@
+"""Infrastructure Layer - Graph API clients and authentication."""
+
+from teams_phone.infrastructure.cache_manager import CacheManager
+from teams_phone.infrastructure.config_manager import ConfigManager
+from teams_phone.infrastructure.debug_logger import DebugLogger
+from teams_phone.infrastructure.graph_client import GraphClient
+from teams_phone.infrastructure.output_formatter import (
+    PLACEHOLDER_ASCII,
+    PLACEHOLDER_UNICODE,
+    OutputFormatter,
+)
+
+
+__all__ = [
+    "CacheManager",
+    "ConfigManager",
+    "DebugLogger",
+    "GraphClient",
+    "OutputFormatter",
+    "PLACEHOLDER_ASCII",
+    "PLACEHOLDER_UNICODE",
+]