"""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.
    """
