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

teams_phone/infrastructure/output_formatter.py

@@ -0,0 +1,234 @@
+"""Output formatter for Teams Phone CLI.
+
+This module provides rich terminal output formatting including tables,
+JSON output mode, progress bars, and styled messages with remediation guidance.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any
+
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TaskProgressColumn,
+    TextColumn,
+)
+from rich.table import Table
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+def _can_encode_unicode() -> bool:
+    """Check if stdout can encode Unicode characters.
+
+    Tests by attempting to encode a Unicode checkmark. On Windows with
+    legacy console (cp1252), this will fail.
+
+    Returns:
+        True if Unicode is supported, False if ASCII-only mode is needed.
+    """
+    try:
+        # Test with checkmark - if this fails, we need ASCII mode
+        encoding = getattr(sys.stdout, "encoding", None) or "utf-8"
+        "✓".encode(encoding)
+        return True
+    except (UnicodeEncodeError, LookupError):
+        return False
+
+
+# ASCII-safe placeholder for "no value" display
+# Em-dash (—) works in most encodings but we provide a fallback
+PLACEHOLDER_UNICODE = "—"
+PLACEHOLDER_ASCII = "-"
+
+
+class OutputFormatter:
+    """Format and display output for the CLI.
+
+    Provides methods for displaying data as tables, JSON, or styled messages.
+    Supports color control via constructor flag and NO_COLOR environment variable.
+
+    Attributes:
+        console: Rich Console instance for output.
+        json_mode: Whether to output JSON instead of Rich formatting.
+        no_color: Whether color output is disabled.
+    """
+
+    def __init__(
+        self,
+        console: Console | None = None,
+        *,
+        json_mode: bool = False,
+        no_color: bool = False,
+    ) -> None:
+        """Initialize the OutputFormatter.
+
+        Args:
+            console: Optional Rich Console instance. If not provided, creates one.
+            json_mode: If True, output JSON to stdout instead of Rich formatting.
+            no_color: If True, disable color output. Also respects NO_COLOR env var.
+        """
+        self.json_mode = json_mode
+        # Respect both the flag and the NO_COLOR environment variable
+        self.no_color = no_color or os.environ.get("NO_COLOR") is not None
+        # Detect Unicode support for Windows compatibility
+        self._use_ascii = not _can_encode_unicode()
+
+        if console is not None:
+            self.console = console
+        else:
+            self.console = Console(
+                force_terminal=not json_mode,
+                no_color=self.no_color,
+            )
+
+    def table(
+        self,
+        data: list[dict[str, Any]],
+        columns: list[str],
+        *,
+        title: str | None = None,
+    ) -> None:
+        """Display data as a formatted table.
+
+        Args:
+            data: List of dictionaries containing row data.
+            columns: List of column names to display.
+            title: Optional title for the table.
+        """
+        if self.json_mode:
+            self.json(data)
+            return
+
+        table = Table(title=title)
+
+        for column in columns:
+            table.add_column(column, style="cyan")
+
+        for row in data:
+            table.add_row(*[str(row.get(col, "")) for col in columns])
+
+        self.console.print(table)
+
+    def json(self, data: Any) -> None:
+        """Output data as JSON to stdout.
+
+        Args:
+            data: Data to serialize as JSON.
+        """
+        # Use plain print to stdout for JSON mode (no Rich formatting)
+        print(json.dumps(data, indent=2, default=str), file=sys.stdout)
+
+    def success(self, message: str) -> None:
+        """Display a success message in green.
+
+        Args:
+            message: The success message to display.
+        """
+        if self.json_mode:
+            return
+        # Use ASCII-safe marker on Windows legacy console
+        marker = "OK:" if self._use_ascii else "✓"
+        self.console.print(f"[green]{marker}[/green] {message}")
+
+    def error(self, message: str, *, remediation: str | None = None) -> None:
+        """Display an error message in red with optional remediation guidance.
+
+        Args:
+            message: The error message to display.
+            remediation: Optional guidance on how to fix the issue.
+        """
+        if self.json_mode:
+            return
+
+        self.console.print(f"[red]Error:[/red] {message}")
+
+        if remediation:
+            self.console.print()
+            self.console.print("[yellow]To fix:[/yellow]")
+            self.console.print(f"  {remediation}")
+
+    def warning(self, message: str) -> None:
+        """Display a warning message in yellow.
+
+        Args:
+            message: The warning message to display.
+        """
+        if self.json_mode:
+            return
+        self.console.print(f"[yellow]Warning:[/yellow] {message}")
+
+    def info(self, message: str) -> None:
+        """Display an informational message.
+
+        Args:
+            message: The info message to display.
+        """
+        if self.json_mode:
+            return
+        self.console.print(message)
+
+    def get_spinner_name(self) -> str:
+        """Get the appropriate spinner name based on Unicode support.
+
+        Returns:
+            'line' for ASCII-only mode (Windows legacy console),
+            'dots' for Unicode-capable terminals.
+        """
+        return "line" if self._use_ascii else "dots"
+
+    @property
+    def placeholder(self) -> str:
+        """Get the appropriate placeholder for 'no value' display.
+
+        Returns:
+            '-' for ASCII-only mode, '—' (em-dash) for Unicode terminals.
+        """
+        return PLACEHOLDER_ASCII if self._use_ascii else PLACEHOLDER_UNICODE
+
+    @contextmanager
+    def progress(
+        self,
+        total: int,
+        description: str = "Processing",
+    ) -> Iterator[Progress]:
+        """Return a Progress context manager for displaying progress bars.
+
+        Args:
+            total: Total number of items to process.
+            description: Description text for the progress bar.
+
+        Yields:
+            Progress instance for tracking progress.
+        """
+        if self.json_mode:
+            # Return a minimal progress that does nothing in JSON mode
+            progress = Progress(
+                console=Console(force_terminal=False, quiet=True),
+                disable=True,
+            )
+            with progress:
+                progress.add_task(description, total=total)
+                yield progress
+        else:
+            # Use ASCII-safe spinner on Windows legacy console
+            spinner_name = self.get_spinner_name()
+            progress = Progress(
+                SpinnerColumn(spinner_name=spinner_name),
+                TextColumn("[progress.description]{task.description}"),
+                BarColumn(),
+                TaskProgressColumn(),
+                console=self.console,
+            )
+            with progress:
+                progress.add_task(description, total=total)
+                yield progress

teams_phone/models/__init__.py

@@ -0,0 +1,76 @@
+"""Pydantic models for API responses and domain objects."""
+
+from teams_phone.models.api_responses import (
+    GraphErrorDetail,
+    GraphErrorResponse,
+    GraphListResponse,
+)
+from teams_phone.models.auth import (
+    AuthStatus,
+    AuthStatusType,
+    CachedToken,
+    ConnectionTestResult,
+)
+from teams_phone.models.cache import CacheMetadata
+from teams_phone.models.config import CacheSettings, Config, NetworkSettings
+from teams_phone.models.location import EmergencyLocation
+from teams_phone.models.number import (
+    ActivationState,
+    AssignmentCategory,
+    AssignmentStatus,
+    AsyncOperation,
+    NumberAssignment,
+    NumberType,
+    OperationNumber,
+    OperationStatus,
+)
+from teams_phone.models.policy import Policy
+from teams_phone.models.tenant import AuthMethod, TenantProfile
+from teams_phone.models.user import (
+    AccountType,
+    EffectivePolicyAssignment,
+    PolicyAssignmentDetail,
+    TelephoneNumber,
+    UserConfiguration,
+)
+
+
+__all__ = [
+    # API response models
+    "GraphErrorDetail",
+    "GraphErrorResponse",
+    "GraphListResponse",
+    # Auth models
+    "AuthStatus",
+    "AuthStatusType",
+    "CachedToken",
+    "ConnectionTestResult",
+    # Cache models
+    "CacheMetadata",
+    # Config models
+    "CacheSettings",
+    "Config",
+    "NetworkSettings",
+    # Number models
+    "ActivationState",
+    "AssignmentCategory",
+    "AssignmentStatus",
+    "AsyncOperation",
+    "NumberAssignment",
+    "NumberType",
+    "OperationNumber",
+    "OperationStatus",
+    # Location models
+    "EmergencyLocation",
+    # Policy models
+    "Policy",
+    # Tenant models
+    "AuthMethod",
+    "TenantProfile",
+    # User models
+    "AccountType",
+    "EffectivePolicyAssignment",
+    "PolicyAssignmentDetail",
+    "TelephoneNumber",
+    "UserConfiguration",
+]

teams_phone/models/api_responses.py

@@ -0,0 +1,69 @@
+"""Generic Graph API response models for pagination and error handling."""
+
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+T = TypeVar("T")
+
+
+class GraphErrorDetail(BaseModel):
+    """Nested error details from Graph API error responses.
+
+    Graph API errors can contain nested details for complex error scenarios.
+    The details field is self-referential to support arbitrary nesting depth.
+
+    Attributes:
+        code: Error code string (e.g., "BadRequest", "ResourceNotFound").
+        message: Human-readable error message.
+        target: The target of the error, typically the field or parameter that caused it.
+        details: Nested error details for additional context.
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    code: str
+    message: str
+    target: str | None = None
+    details: list["GraphErrorDetail"] | None = None
+
+
+class GraphErrorResponse(BaseModel):
+    """Graph API error response wrapper.
+
+    Standard error response format returned by Microsoft Graph API
+    when a request fails. Contains a single error object with details.
+
+    Attributes:
+        error: The error detail object containing code, message, and optional nested details.
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    error: GraphErrorDetail
+
+
+class GraphListResponse(BaseModel, Generic[T]):
+    """Generic wrapper for paginated Graph API list responses.
+
+    Microsoft Graph API returns list results in a consistent format with
+    OData annotations for context, count, and pagination. This generic
+    model can wrap any item type T for type-safe parsing.
+
+    Type Parameters:
+        T: The type of items in the value list (e.g., UserConfiguration).
+
+    Attributes:
+        odata_context: OData context URL describing the response metadata.
+        odata_count: Total count of items when requested with $count=true.
+        odata_next_link: URL to fetch the next page of results.
+        value: List of items of type T.
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    odata_context: str | None = Field(alias="@odata.context", default=None)
+    odata_count: int | None = Field(alias="@odata.count", default=None)
+    odata_next_link: str | None = Field(alias="@odata.nextLink", default=None)
+    value: list[T]

teams_phone/models/auth.py

@@ -0,0 +1,100 @@
+"""Authentication models for token caching and status tracking."""
+
+from datetime import datetime, timezone
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict
+
+
+class AuthStatusType(str, Enum):
+    """Authentication status states.
+
+    Attributes:
+        AUTHENTICATED: Successfully authenticated with valid token.
+        UNAUTHENTICATED: No valid authentication (requires login).
+        EXPIRED: Token has expired (requires refresh or re-authentication).
+    """
+
+    AUTHENTICATED = "authenticated"
+    UNAUTHENTICATED = "unauthenticated"
+    EXPIRED = "expired"
+
+
+class CachedToken(BaseModel):
+    """Cached authentication token for a tenant.
+
+    Stores the access token and expiration timestamp for token caching.
+    MSAL handles refresh tokens internally, so only access token is stored.
+
+    Attributes:
+        access_token: The OAuth 2.0 access token string.
+        expires_at: UTC datetime when the token expires.
+        tenant_id: The tenant ID this token is associated with.
+        scopes: List of scopes granted to this token.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    access_token: str
+    expires_at: datetime
+    tenant_id: str
+    scopes: list[str]
+
+    def is_expired(self) -> bool:
+        """Check if the token has expired.
+
+        Returns:
+            True if current time is past expiration, False otherwise.
+        """
+        now = datetime.now(timezone.utc)
+        expires = self.expires_at
+        # Handle both naive and aware datetimes for comparison
+        if expires.tzinfo is None:
+            expires = expires.replace(tzinfo=timezone.utc)
+        return now >= expires
+
+
+class AuthStatus(BaseModel):
+    """Current authentication status for a tenant.
+
+    Tracks the authentication state and provides context about
+    the current session.
+
+    Attributes:
+        status: Current authentication state.
+        tenant_name: Profile name of the authenticated tenant.
+        tenant_id: Tenant ID if authenticated.
+        expires_at: Token expiration time if authenticated.
+        error_message: Error details if authentication failed.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    status: AuthStatusType
+    tenant_name: str | None = None
+    tenant_id: str | None = None
+    expires_at: datetime | None = None
+    error_message: str | None = None
+
+
+class ConnectionTestResult(BaseModel):
+    """Result of a tenant connection test.
+
+    Contains the outcome of testing connectivity to Microsoft Graph API
+    for a given tenant, including latency measurement and permission info.
+
+    Attributes:
+        success: Whether the connection test succeeded.
+        tenant_name: Name of the tenant that was tested.
+        latency_ms: Round-trip latency in milliseconds (None if failed before API call).
+        permissions: List of application permissions (scopes) available.
+        error_message: Error details if the test failed.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    success: bool
+    tenant_name: str
+    latency_ms: int | None = None
+    permissions: list[str] = []
+    error_message: str | None = None

teams_phone/models/cache.py

@@ -0,0 +1,25 @@
+"""Cache-related models for metadata and staleness tracking."""
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class CacheMetadata(BaseModel):
+    """Metadata about CSV cache files.
+
+    Tracks when the cache was last updated and how much data it contains.
+    Used to determine if the cache is stale and needs refreshing.
+
+    Attributes:
+        last_updated: UTC datetime when the oldest cache file was modified.
+            None if no cache files exist.
+        locations_count: Number of location records in the cache.
+        policies_count: Number of policy records in the cache.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    last_updated: datetime | None
+    locations_count: int
+    policies_count: int

teams_phone/models/config.py

@@ -0,0 +1,66 @@
+"""Configuration models for CLI settings and defaults."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from teams_phone.constants import (
+    CSV_STALE_DAYS,
+    DEFAULT_CACHE_PATH,
+    DEFAULT_CONFIG_PATH,
+    DEFAULT_TIMEOUT,
+    DEFAULT_TOKEN_PATH,
+    MAX_RETRIES,
+)
+from teams_phone.models.tenant import TenantProfile
+
+
+class CacheSettings(BaseModel):
+    """Cache configuration settings.
+
+    Attributes:
+        cache_path: Directory path for cached data files.
+        stale_days: Number of days before cache is considered stale.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    cache_path: str = DEFAULT_CACHE_PATH
+    stale_days: int = CSV_STALE_DAYS
+
+
+class NetworkSettings(BaseModel):
+    """Network and HTTP client settings.
+
+    Attributes:
+        timeout: HTTP request timeout in seconds.
+        max_retries: Maximum retry attempts for transient failures.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    timeout: int = DEFAULT_TIMEOUT
+    max_retries: int = MAX_RETRIES
+
+
+class Config(BaseModel):
+    """Main configuration model for Teams Phone CLI.
+
+    Root configuration containing all settings, defaults, and tenant profiles.
+    Loaded from config.toml at startup.
+
+    Attributes:
+        config_path: Path to the configuration file.
+        token_path: Directory path for authentication token storage.
+        default_tenant: Name of the default tenant profile to use.
+        cache: Cache-related settings.
+        network: Network and HTTP client settings.
+        tenants: Dictionary of tenant profiles keyed by name.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    config_path: str = DEFAULT_CONFIG_PATH
+    token_path: str = DEFAULT_TOKEN_PATH
+    default_tenant: str | None = None
+    cache: CacheSettings = Field(default_factory=CacheSettings)
+    network: NetworkSettings = Field(default_factory=NetworkSettings)
+    tenants: dict[str, TenantProfile] = Field(default_factory=dict)

teams_phone/models/location.py

@@ -0,0 +1,36 @@
+"""Emergency location model for CSV cache data."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class EmergencyLocation(BaseModel):
+    """Emergency location from CSV cache.
+
+    Represents an emergency calling location exported via PowerShell.
+    Used for validation and display since Graph API doesn't expose location endpoints.
+
+    Attributes:
+        location_id: Unique identifier for the location (GUID).
+        civic_address_id: Associated civic address ID (GUID).
+        description: Location description/name.
+        company_name: Company name at this location.
+        address: Street address.
+        city: City name.
+        state_or_province: State or province.
+        postal_code: Postal/ZIP code.
+        country_or_region: Country or region code.
+        is_default: Whether this is the default location for the civic address.
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    location_id: str = Field(alias="locationId")
+    civic_address_id: str = Field(alias="civicAddressId")
+    description: str = Field(alias="description")
+    company_name: str | None = Field(alias="companyName", default=None)
+    address: str | None = Field(alias="address", default=None)
+    city: str | None = Field(alias="city", default=None)
+    state_or_province: str | None = Field(alias="stateOrProvince", default=None)
+    postal_code: str | None = Field(alias="postalCode", default=None)
+    country_or_region: str | None = Field(alias="countryOrRegion", default=None)
+    is_default: bool = Field(alias="isDefault")