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

teams_phone/infrastructure/cache_manager.py

@@ -0,0 +1,274 @@
+"""Cache manager for token storage and retrieval with JSON persistence."""
+
+import csv
+from datetime import datetime, timezone
+from pathlib import Path
+
+from pydantic import ValidationError as PydanticValidationError
+
+from teams_phone.constants import CSV_STALE_DAYS, DEFAULT_CACHE_PATH, DEFAULT_TOKEN_PATH
+from teams_phone.exceptions import ConfigurationError
+from teams_phone.models import CachedToken, CacheMetadata
+
+
+class CacheManager:
+    """Manages token caching with JSON persistence.
+
+    Provides methods to save, retrieve, and clear authentication tokens
+    for tenants. Tokens are stored as JSON files in the token directory.
+
+    Attributes:
+        cache_dir: Path to the cache directory for CSV files.
+        token_dir: Path to the token storage directory.
+    """
+
+    def __init__(
+        self,
+        cache_dir: str | None = None,
+        token_dir: str | None = None,
+    ) -> None:
+        """Initialize the CacheManager.
+
+        Args:
+            cache_dir: Path to the cache directory. Defaults to
+                ~/.teams-phone/cache if not specified.
+            token_dir: Path to the token directory. Defaults to
+                ~/.teams-phone/tokens if not specified.
+        """
+        cache_str = cache_dir if cache_dir is not None else DEFAULT_CACHE_PATH
+        self._cache_dir: Path = Path(cache_str).expanduser()
+
+        token_str = token_dir if token_dir is not None else DEFAULT_TOKEN_PATH
+        self._token_dir: Path = Path(token_str).expanduser()
+
+    @property
+    def cache_dir(self) -> Path:
+        """Path to the cache directory."""
+        return self._cache_dir
+
+    @property
+    def token_dir(self) -> Path:
+        """Path to the token directory."""
+        return self._token_dir
+
+    def ensure_token_dir(self) -> None:
+        """Create the token directory if it doesn't exist.
+
+        Creates all parent directories as needed.
+
+        Raises:
+            ConfigurationError: If directory creation fails due to permission error.
+        """
+        try:
+            self._token_dir.mkdir(parents=True, exist_ok=True)
+        except PermissionError as e:
+            raise ConfigurationError(
+                f"Cannot create token directory {self._token_dir}: {e}",
+                remediation=(
+                    f"Check that you have write permissions to {self._token_dir}.\n"
+                    "You may need to create the directory manually or run with elevated privileges."
+                ),
+            ) from e
+
+    def _get_token_path(self, tenant_name: str) -> Path:
+        """Get the file path for a tenant's token.
+
+        Args:
+            tenant_name: The tenant profile name.
+
+        Returns:
+            Path to the token JSON file.
+        """
+        return self._token_dir / f"{tenant_name}.json"
+
+    def get_token(self, tenant_name: str) -> CachedToken | None:
+        """Retrieve a cached token for a tenant.
+
+        Args:
+            tenant_name: The tenant profile name.
+
+        Returns:
+            CachedToken if found and valid, None if file doesn't exist or
+            contains invalid JSON.
+
+        Note:
+            Returns None silently for missing files or invalid JSON.
+            This enables graceful fallback to re-authentication.
+        """
+        token_path = self._get_token_path(tenant_name)
+
+        if not token_path.exists():
+            return None
+
+        try:
+            content = token_path.read_text(encoding="utf-8")
+            return CachedToken.model_validate_json(content)
+        except (PydanticValidationError, ValueError):
+            # Invalid JSON or failed validation - treat as missing
+            return None
+
+    def save_token(self, tenant_name: str, token: CachedToken) -> None:
+        """Save a token to the cache.
+
+        Creates the token directory if it doesn't exist.
+
+        Args:
+            tenant_name: The tenant profile name.
+            token: The token to cache.
+
+        Raises:
+            ConfigurationError: If the token directory cannot be created
+                due to permission issues.
+        """
+        self.ensure_token_dir()
+
+        token_path = self._get_token_path(tenant_name)
+        content = token.model_dump_json()
+        token_path.write_text(content, encoding="utf-8")
+
+    def clear_tokens(self, tenant_name: str | None = None) -> None:
+        """Clear cached tokens.
+
+        Args:
+            tenant_name: The tenant name to clear tokens for.
+                If None, clears all token files.
+
+        Note:
+            Does not raise errors for missing files or directories.
+            The token directory is preserved when clearing all tokens.
+        """
+        if tenant_name is not None:
+            # Clear specific tenant's token
+            token_path = self._get_token_path(tenant_name)
+            token_path.unlink(missing_ok=True)
+        else:
+            # Clear all token files
+            if self._token_dir.exists():
+                for token_file in self._token_dir.glob("*.json"):
+                    token_file.unlink(missing_ok=True)
+
+    def _read_csv(self, filename: str) -> list[dict[str, str]]:
+        """Read a CSV file from the cache directory.
+
+        Args:
+            filename: Name of the CSV file (e.g., "locations.csv").
+
+        Returns:
+            List of dictionaries, one per row. Empty list if file
+            doesn't exist or is malformed.
+
+        Note:
+            Uses UTF-8 with BOM support (utf-8-sig encoding) to handle
+            PowerShell exports which may include a byte order mark.
+        """
+        csv_path = self._cache_dir / filename
+
+        if not csv_path.exists():
+            return []
+
+        try:
+            with csv_path.open(encoding="utf-8-sig") as f:
+                reader = csv.DictReader(f)
+                return list(reader)
+        except csv.Error:
+            return []
+
+    def read_locations_csv(self) -> list[dict[str, str]]:
+        """Read emergency locations from the cache.
+
+        Returns:
+            List of location dictionaries with keys like locationId,
+            description, address, city, etc. Empty list if file doesn't
+            exist or is malformed.
+        """
+        return self._read_csv("locations.csv")
+
+    def read_policies_csv(self) -> list[dict[str, str]]:
+        """Read policies from the cache.
+
+        Returns:
+            List of policy dictionaries with keys like policyType,
+            policyName, policyId, description, isGlobal. Empty list if
+            file doesn't exist or is malformed.
+        """
+        return self._read_csv("policies.csv")
+
+    def get_csv_metadata(self) -> CacheMetadata | None:
+        """Get metadata about the CSV cache files.
+
+        Checks for locations.csv and policies.csv, returning metadata
+        about when they were last updated and how many records they contain.
+
+        Returns:
+            CacheMetadata with last_updated (oldest mtime of the two files),
+            locations_count, and policies_count. Returns None if neither
+            CSV file exists.
+        """
+        locations_path = self._cache_dir / "locations.csv"
+        policies_path = self._cache_dir / "policies.csv"
+
+        locations_exists = locations_path.exists()
+        policies_exists = policies_path.exists()
+
+        if not locations_exists and not policies_exists:
+            return None
+
+        # Get modification times, handling potential race conditions
+        mtimes: list[datetime] = []
+
+        if locations_exists:
+            try:
+                mtime = locations_path.stat().st_mtime
+                mtimes.append(datetime.fromtimestamp(mtime, tz=timezone.utc))
+            except FileNotFoundError:
+                pass
+
+        if policies_exists:
+            try:
+                mtime = policies_path.stat().st_mtime
+                mtimes.append(datetime.fromtimestamp(mtime, tz=timezone.utc))
+            except FileNotFoundError:
+                pass
+
+        # Use the OLDER mtime (indicates when cache was last completely updated)
+        last_updated = min(mtimes) if mtimes else None
+
+        # Get row counts using existing methods
+        locations_count = len(self.read_locations_csv())
+        policies_count = len(self.read_policies_csv())
+
+        return CacheMetadata(
+            last_updated=last_updated,
+            locations_count=locations_count,
+            policies_count=policies_count,
+        )
+
+    def get_cache_age_days(self) -> int | None:
+        """Get the age of the cache in days.
+
+        Returns:
+            Number of days since the oldest CSV file was modified,
+            or None if no cache metadata exists or last_updated is None.
+        """
+        metadata = self.get_csv_metadata()
+
+        if metadata is None or metadata.last_updated is None:
+            return None
+
+        now = datetime.now(timezone.utc)
+        delta = now - metadata.last_updated
+        return delta.days
+
+    def is_cache_stale(self) -> bool:
+        """Check if the CSV cache is stale and needs refreshing.
+
+        Returns:
+            True if no cache exists or the cache is older than CSV_STALE_DAYS
+            (30 days). False if the cache is fresh.
+        """
+        age_days = self.get_cache_age_days()
+
+        if age_days is None:
+            return True
+
+        return age_days > CSV_STALE_DAYS

teams_phone/infrastructure/config_manager.py

@@ -0,0 +1,209 @@
+"""Configuration manager for reading and writing TOML config files."""
+
+import sys
+from pathlib import Path
+
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[import-not-found,unused-ignore]
+
+import tomlkit
+from pydantic import ValidationError as PydanticValidationError
+
+from teams_phone.constants import DEFAULT_CONFIG_PATH
+from teams_phone.exceptions import ConfigurationError, NotFoundError, ValidationError
+from teams_phone.models import Config, TenantProfile
+
+
+class ConfigManager:
+    """Manages Teams Phone CLI configuration file operations.
+
+    Provides methods to load and save configuration from/to TOML files,
+    with validation through Pydantic models and format preservation
+    when writing.
+
+    Attributes:
+        config_path: Path to the configuration file.
+    """
+
+    def __init__(self, config_path: str | None = None) -> None:
+        """Initialize the ConfigManager.
+
+        Args:
+            config_path: Path to the configuration file. Defaults to
+                ~/.teams-phone/config.toml if not specified.
+        """
+        path_str = config_path if config_path is not None else DEFAULT_CONFIG_PATH
+        self.config_path: Path = Path(path_str).expanduser()
+
+    def ensure_config_dir(self) -> None:
+        """Create the configuration directory if it doesn't exist.
+
+        Creates all parent directories as needed.
+
+        Raises:
+            ConfigurationError: If directory creation fails due to permission error.
+        """
+        try:
+            self.config_path.parent.mkdir(parents=True, exist_ok=True)
+        except PermissionError as e:
+            raise ConfigurationError(
+                f"Cannot create configuration directory {self.config_path.parent}: {e}",
+                remediation=(
+                    f"Check that you have write permissions to {self.config_path.parent}.\n"
+                    "You may need to create the directory manually or run with elevated privileges."
+                ),
+            ) from e
+
+    def load_config(self) -> Config:
+        """Load and validate configuration from the TOML file.
+
+        Returns:
+            Config: Validated configuration object.
+
+        Raises:
+            ConfigurationError: If the file exists but contains invalid
+                TOML syntax or fails Pydantic validation.
+
+        Note:
+            Returns a default Config instance if the file doesn't exist.
+        """
+        if not self.config_path.exists():
+            return Config()
+
+        try:
+            content = self.config_path.read_text(encoding="utf-8")
+            data = tomllib.loads(content)
+            return Config.model_validate(data)
+        except tomllib.TOMLDecodeError as e:
+            raise ConfigurationError(
+                f"Invalid TOML syntax in {self.config_path}: {e}",
+                remediation=(
+                    f"Check {self.config_path} for syntax errors.\n"
+                    "Ensure all strings are properly quoted and "
+                    "section headers use [brackets]."
+                ),
+            ) from e
+        except PydanticValidationError as e:
+            raise ConfigurationError(
+                f"Invalid configuration in {self.config_path}: {e}",
+                remediation=(
+                    f"Review the configuration values in {self.config_path}.\n"
+                    "Ensure all required fields are present and have valid types."
+                ),
+            ) from e
+
+    def save_config(self, config: Config) -> None:
+        """Save configuration to the TOML file.
+
+        Uses tomlkit to serialize the configuration, which preserves
+        formatting when possible. Creates the configuration directory
+        if it doesn't exist.
+
+        Args:
+            config: Configuration object to save.
+
+        Note:
+            This method overwrites the existing file. To preserve
+            comments in an existing file, load it with tomlkit first,
+            update values, and write back.
+        """
+        self.ensure_config_dir()
+
+        # Serialize with mode="json" to convert UUID/Enum to strings
+        # exclude_none=True because tomlkit doesn't handle None values
+        data = config.model_dump(mode="json", exclude_none=True)
+        content = tomlkit.dumps(data)
+        self.config_path.write_text(content, encoding="utf-8")
+
+    def get_tenant(self, name: str) -> TenantProfile:
+        """Retrieve a tenant profile by name.
+
+        Args:
+            name: The tenant profile name to look up.
+
+        Returns:
+            TenantProfile: The tenant profile configuration.
+
+        Raises:
+            NotFoundError: If no tenant with the given name exists.
+        """
+        config = self.load_config()
+        if name not in config.tenants:
+            raise NotFoundError(
+                f"Tenant '{name}' not found",
+                remediation="Run 'teams-phone tenants list' to see configured tenants.",
+            )
+        return config.tenants[name]
+
+    def set_tenant(self, name: str, profile: TenantProfile) -> None:
+        """Add or update a tenant profile.
+
+        Args:
+            name: The key name for the tenant profile.
+            profile: The tenant profile configuration to save.
+
+        Raises:
+            ValidationError: If profile.name does not match the name parameter.
+        """
+        if profile.name != name:
+            raise ValidationError(
+                f"Tenant profile name '{profile.name}' does not match key '{name}'",
+                remediation="Ensure the profile name matches the key being set.",
+            )
+        config = self.load_config()
+        config.tenants[name] = profile
+        self.save_config(config)
+
+    def remove_tenant(self, name: str) -> None:
+        """Remove a tenant profile by name.
+
+        Args:
+            name: The tenant profile name to remove.
+
+        Raises:
+            NotFoundError: If no tenant with the given name exists.
+
+        Note:
+            If the removed tenant is the default tenant, the default_tenant
+            setting is cleared.
+        """
+        config = self.load_config()
+        if name not in config.tenants:
+            raise NotFoundError(
+                f"Tenant '{name}' not found",
+                remediation="Run 'teams-phone tenants list' to see configured tenants.",
+            )
+        del config.tenants[name]
+        if config.default_tenant == name:
+            config.default_tenant = None
+        self.save_config(config)
+
+    def get_default_tenant(self) -> str | None:
+        """Retrieve the default tenant name.
+
+        Returns:
+            The name of the default tenant, or None if not set.
+        """
+        config = self.load_config()
+        return config.default_tenant
+
+    def set_default_tenant(self, name: str) -> None:
+        """Set the default tenant.
+
+        Args:
+            name: The tenant name to set as default.
+
+        Raises:
+            NotFoundError: If the specified tenant doesn't exist.
+        """
+        config = self.load_config()
+        if name not in config.tenants:
+            raise NotFoundError(
+                f"Tenant '{name}' not found",
+                remediation="Run 'teams-phone tenants list' to see configured tenants.",
+            )
+        config.default_tenant = name
+        self.save_config(config)