shotgun-sh 0.2.8.dev2__py3-none-any.whl → 0.3.3.dev1__py3-none-any.whl

shotgun/settings.py

@@ -0,0 +1,243 @@
+"""Centralized application settings using Pydantic Settings.
+
+All environment variables use the SHOTGUN_ prefix to avoid conflicts with other tools.
+Settings are loaded with the following priority:
+1. Environment variables (highest priority)
+2. Build constants (embedded at build time)
+3. Default values (lowest priority)
+
+Example usage:
+    from shotgun.settings import settings
+
+    # Access telemetry settings
+    if settings.telemetry.sentry_dsn:
+        sentry_sdk.init(dsn=settings.telemetry.sentry_dsn)
+
+    # Access logging settings
+    logger.setLevel(settings.logging.log_level)
+
+    # Access API settings
+    response = httpx.get(settings.api.web_base_url)
+"""
+
+from typing import Any
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def _get_build_constant(name: str, default: Any = None) -> Any:
+    """Get a value from build_constants.py, falling back to default.
+
+    Args:
+        name: The constant name to retrieve (e.g., "SENTRY_DSN")
+        default: Default value if constant not found
+
+    Returns:
+        The constant value, or default if not found/import fails
+    """
+    try:
+        from shotgun import build_constants
+
+        return getattr(build_constants, name, default)
+    except ImportError:
+        return default
+
+
+class TelemetrySettings(BaseSettings):
+    """Telemetry and observability settings.
+
+    These settings control error tracking (Sentry), analytics (PostHog),
+    and observability (Logfire) integrations.
+    """
+
+    sentry_dsn: str = Field(
+        default_factory=lambda: _get_build_constant("SENTRY_DSN", ""),
+        description="Sentry DSN for error tracking",
+    )
+    posthog_api_key: str = Field(
+        default_factory=lambda: _get_build_constant("POSTHOG_API_KEY", ""),
+        description="PostHog API key for analytics",
+    )
+    posthog_project_id: str = Field(
+        default_factory=lambda: _get_build_constant("POSTHOG_PROJECT_ID", ""),
+        description="PostHog project ID",
+    )
+    logfire_enabled: bool = Field(
+        default_factory=lambda: _get_build_constant("LOGFIRE_ENABLED", False),
+        description="Enable Logfire observability (dev builds only)",
+    )
+    logfire_token: str = Field(
+        default_factory=lambda: _get_build_constant("LOGFIRE_TOKEN", ""),
+        description="Logfire authentication token",
+    )
+
+    model_config = SettingsConfigDict(
+        env_prefix="SHOTGUN_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    @field_validator("logfire_enabled", mode="before")
+    @classmethod
+    def parse_bool(cls, v: Any) -> bool:
+        """Parse boolean values from strings (matches is_truthy behavior)."""
+        if isinstance(v, bool):
+            return v
+        if isinstance(v, str):
+            return v.lower() in ("true", "1", "yes")
+        return bool(v)
+
+
+class LoggingSettings(BaseSettings):
+    """Logging configuration settings.
+
+    Controls log level, console output, and file logging behavior.
+    """
+
+    log_level: str = Field(
+        default="INFO",
+        description="Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)",
+    )
+    logging_to_console: bool = Field(
+        default=False,
+        description="Enable console logging output",
+    )
+    logging_to_file: bool = Field(
+        default=True,
+        description="Enable file logging output",
+    )
+    max_log_files: int = Field(
+        default=10,
+        description="Maximum number of log files to keep (older files are deleted)",
+        ge=1,
+    )
+
+    model_config = SettingsConfigDict(
+        env_prefix="SHOTGUN_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    @field_validator("log_level")
+    @classmethod
+    def validate_log_level(cls, v: str) -> str:
+        """Validate log level is one of the allowed values."""
+        v = v.upper()
+        valid_levels = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+        if v not in valid_levels:
+            return "INFO"  # Default to INFO if invalid
+        return v
+
+    @field_validator("logging_to_console", "logging_to_file", mode="before")
+    @classmethod
+    def parse_bool(cls, v: Any) -> bool:
+        """Parse boolean values from strings (matches is_truthy behavior)."""
+        if isinstance(v, bool):
+            return v
+        if isinstance(v, str):
+            return v.lower() in ("true", "1", "yes")
+        return bool(v)
+
+
+class ApiSettings(BaseSettings):
+    """API endpoint settings.
+
+    Configuration for Shotgun backend services.
+    """
+
+    web_base_url: str = Field(
+        default="https://api-219702594231.us-east4.run.app",
+        description="Shotgun Web API base URL (authentication/subscription)",
+    )
+    account_llm_base_url: str = Field(
+        default="https://litellm-219702594231.us-east4.run.app",
+        description="Shotgun's LiteLLM proxy base URL (AI model requests)",
+    )
+
+    model_config = SettingsConfigDict(
+        env_prefix="SHOTGUN_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+
+class DevelopmentSettings(BaseSettings):
+    """Development and testing settings.
+
+    These settings are primarily used for testing and development purposes.
+    """
+
+    home: str | None = Field(
+        default=None,
+        description="Override Shotgun home directory (for testing)",
+    )
+    pipx_simulate: bool = Field(
+        default=False,
+        description="Simulate pipx installation (for testing)",
+    )
+
+    model_config = SettingsConfigDict(
+        env_prefix="SHOTGUN_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    @field_validator("pipx_simulate", mode="before")
+    @classmethod
+    def parse_bool(cls, v: Any) -> bool:
+        """Parse boolean values from strings (matches is_truthy behavior)."""
+        if isinstance(v, bool):
+            return v
+        if isinstance(v, str):
+            return v.lower() in ("true", "1", "yes")
+        return bool(v)
+
+
+class Settings(BaseSettings):
+    """Main application settings with SHOTGUN_ prefix.
+
+    This is the main settings class that composes all other settings groups.
+    Access settings via the global `settings` singleton instance.
+
+    Example:
+        from shotgun.settings import settings
+
+        # Telemetry settings
+        settings.telemetry.sentry_dsn
+        settings.telemetry.posthog_api_key
+        settings.telemetry.logfire_enabled
+
+        # Logging settings
+        settings.logging.log_level
+        settings.logging.logging_to_console
+
+        # API settings
+        settings.api.web_base_url
+        settings.api.account_llm_base_url
+
+        # Development settings
+        settings.dev.home
+        settings.dev.pipx_simulate
+    """
+
+    telemetry: TelemetrySettings = Field(default_factory=TelemetrySettings)
+    logging: LoggingSettings = Field(default_factory=LoggingSettings)
+    api: ApiSettings = Field(default_factory=ApiSettings)
+    dev: DevelopmentSettings = Field(default_factory=DevelopmentSettings)
+
+    model_config = SettingsConfigDict(
+        env_prefix="SHOTGUN_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+
+# Global settings singleton
+# Import this in your modules: from shotgun.settings import settings
+settings = Settings()

shotgun/shotgun_web/__init__.py

@@ -1,14 +1,48 @@
-"""Shotgun Web API client for subscription and authentication."""
+"""Shotgun Web API client for subscription, authentication, and shared specs."""
 
 from .client import ShotgunWebClient, check_token_status, create_unification_token
+from .exceptions import (
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    PayloadTooLargeError,
+    RateLimitExceededError,
+    ShotgunWebError,
+    UnauthorizedError,
+)
 from .models import (
+    # Specs models
+    ErrorDetail,
+    ErrorResponse,
+    FileListResponse,
+    FileMetadata,
+    FileUploadRequest,
+    FileUploadResponse,
+    PermissionCheckResponse,
+    PublicSpecResponse,
+    SpecCreateRequest,
+    SpecCreateResponse,
+    SpecFileResponse,
+    SpecListResponse,
+    SpecResponse,
+    SpecUpdateRequest,
+    SpecVersionCreateRequest,
+    SpecVersionResponse,
+    SpecVersionState,
+    # Token models
     TokenCreateRequest,
     TokenCreateResponse,
     TokenStatus,
     TokenStatusResponse,
+    VersionCloseResponse,
+    VersionCreateResponse,
+    VersionListResponse,
+    WorkspaceRole,
 )
+from .specs_client import SpecsClient
 
 __all__ = [
+    # Existing exports
     "ShotgunWebClient",
     "create_unification_token",
     "check_token_status",
@@ -16,4 +50,36 @@ __all__ = [
     "TokenCreateResponse",
     "TokenStatus",
     "TokenStatusResponse",
+    # Specs client
+    "SpecsClient",
+    # Exceptions
+    "ShotgunWebError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ConflictError",
+    "PayloadTooLargeError",
+    "RateLimitExceededError",
+    # Specs models
+    "ErrorDetail",
+    "ErrorResponse",
+    "FileListResponse",
+    "FileMetadata",
+    "FileUploadRequest",
+    "FileUploadResponse",
+    "PermissionCheckResponse",
+    "PublicSpecResponse",
+    "SpecCreateRequest",
+    "SpecCreateResponse",
+    "SpecFileResponse",
+    "SpecListResponse",
+    "SpecResponse",
+    "SpecUpdateRequest",
+    "SpecVersionCreateRequest",
+    "SpecVersionResponse",
+    "SpecVersionState",
+    "VersionCloseResponse",
+    "VersionCreateResponse",
+    "VersionListResponse",
+    "WorkspaceRole",
 ]

shotgun/shotgun_web/client.py

@@ -5,11 +5,13 @@ import httpx
 from shotgun.logging_config import get_logger
 
 from .constants import (
+    ME_PATH,
     SHOTGUN_WEB_BASE_URL,
     UNIFICATION_TOKEN_CREATE_PATH,
     UNIFICATION_TOKEN_STATUS_PATH,
 )
 from .models import (
+    MeResponse,
     TokenCreateRequest,
     TokenCreateResponse,
     TokenStatusResponse,
@@ -66,7 +68,7 @@ class ShotgunWebClient:
             return result
 
         except httpx.HTTPError as e:
-            logger.error("Failed to create unification token: %s", e)
+            logger.error("Failed to create unification token at %s: %s", url, e)
             raise
 
     def check_token_status(self, token: str) -> TokenStatusResponse:
@@ -106,6 +108,45 @@ class ShotgunWebClient:
             logger.error("Failed to check token status: %s", e)
             raise
 
+    def get_me(self, jwt: str) -> MeResponse:
+        """Get current user info including workspace.
+
+        Args:
+            jwt: Supabase JWT for authentication
+
+        Returns:
+            User info including workspace details
+
+        Raises:
+            httpx.HTTPStatusError: If authentication fails (401) or other HTTP errors
+            httpx.HTTPError: For other request failures
+        """
+        url = f"{self.base_url}{ME_PATH}"
+
+        logger.debug("Fetching user info from /api/me")
+
+        try:
+            response = httpx.get(
+                url,
+                headers={"Authorization": f"Bearer {jwt}"},
+                timeout=self.timeout,
+            )
+            response.raise_for_status()
+
+            data = response.json()
+            result = MeResponse.model_validate(data)
+
+            logger.info("Successfully fetched user info for %s", result.email)
+            return result
+
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 401:
+                logger.error("Authentication failed for /api/me")
+            raise
+        except httpx.HTTPError as e:
+            logger.error("Failed to fetch user info: %s", e)
+            raise
+
 
 # Convenience functions for standalone use
 def create_unification_token(shotgun_instance_id: str) -> TokenCreateResponse:

shotgun/shotgun_web/constants.py

@@ -6,16 +6,62 @@ from shotgun.api_endpoints import SHOTGUN_WEB_BASE_URL
 # API endpoints
 UNIFICATION_TOKEN_CREATE_PATH = "/api/unification/token/create"  # noqa: S105
 UNIFICATION_TOKEN_STATUS_PATH = "/api/unification/token/{token}/status"  # noqa: S105
+ME_PATH = "/api/me"
 
 # Polling configuration
 DEFAULT_POLL_INTERVAL_SECONDS = 3
 DEFAULT_TOKEN_TIMEOUT_SECONDS = 1800  # 30 minutes
 
+# Workspaces API endpoint
+WORKSPACES_PATH = "/api/workspaces"
+
+# Specs API endpoints
+PERMISSIONS_PATH = "/api/workspaces/{workspace_id}/specs/permissions"
+SPECS_BASE_PATH = "/api/workspaces/{workspace_id}/specs"
+SPECS_DETAIL_PATH = "/api/workspaces/{workspace_id}/specs/{spec_id}"
+VERSIONS_PATH = "/api/workspaces/{workspace_id}/specs/{spec_id}/versions"
+VERSION_DETAIL_PATH = (
+    "/api/workspaces/{workspace_id}/specs/{spec_id}/versions/{version_id}"
+)
+VERSION_CLOSE_PATH = (
+    "/api/workspaces/{workspace_id}/specs/{spec_id}/versions/{version_id}/close"
+)
+VERSION_SET_LATEST_PATH = (
+    "/api/workspaces/{workspace_id}/specs/{spec_id}/versions/{version_id}/set-latest"
+)
+FILES_PATH = (
+    "/api/workspaces/{workspace_id}/specs/{spec_id}/versions/{version_id}/files"
+)
+FILE_DETAIL_PATH = "/api/workspaces/{workspace_id}/specs/{spec_id}/versions/{version_id}/files/{file_id}"
+PUBLIC_SPEC_PATH = "/api/public/specs/{spec_id}"
+PUBLIC_SPEC_FILES_PATH = "/api/public/specs/{spec_id}/files"
+PUBLIC_FILE_PATH = "/api/public/specs/{spec_id}/files/{file_id}"
+
+# CLI convenience endpoint (version lookup by ID only)
+VERSION_BY_ID_PATH = "/api/versions/{version_id}"
+
 # Re-export for backward compatibility
 __all__ = [
     "SHOTGUN_WEB_BASE_URL",
     "UNIFICATION_TOKEN_CREATE_PATH",
     "UNIFICATION_TOKEN_STATUS_PATH",
+    "ME_PATH",
     "DEFAULT_POLL_INTERVAL_SECONDS",
     "DEFAULT_TOKEN_TIMEOUT_SECONDS",
+    # Workspaces endpoint
+    "WORKSPACES_PATH",
+    # Specs endpoints
+    "PERMISSIONS_PATH",
+    "SPECS_BASE_PATH",
+    "SPECS_DETAIL_PATH",
+    "VERSIONS_PATH",
+    "VERSION_DETAIL_PATH",
+    "VERSION_CLOSE_PATH",
+    "VERSION_SET_LATEST_PATH",
+    "FILES_PATH",
+    "FILE_DETAIL_PATH",
+    "PUBLIC_SPEC_PATH",
+    "PUBLIC_SPEC_FILES_PATH",
+    "PUBLIC_FILE_PATH",
+    "VERSION_BY_ID_PATH",
 ]

shotgun/shotgun_web/exceptions.py

@@ -0,0 +1,29 @@
+"""Typed exceptions for Shotgun Web API operations."""
+
+
+class ShotgunWebError(Exception):
+    """Base exception for Shotgun Web API operations."""
+
+
+class UnauthorizedError(ShotgunWebError):
+    """401 - Missing or invalid authentication token."""
+
+
+class ForbiddenError(ShotgunWebError):
+    """403 - Insufficient permissions for the requested operation."""
+
+
+class NotFoundError(ShotgunWebError):
+    """404 - Resource not found."""
+
+
+class ConflictError(ShotgunWebError):
+    """409 - Name conflict or duplicate path."""
+
+
+class PayloadTooLargeError(ShotgunWebError):
+    """413 - File exceeds maximum size limit."""
+
+
+class RateLimitExceededError(ShotgunWebError):
+    """429 - Rate limit exceeded."""