colacloud-cli 0.1.0__py3-none-any.whl

colacloud_cli/__init__.py

@@ -0,0 +1,3 @@
+"""COLA Cloud CLI - Command-line interface for the COLA Cloud API."""
+
+__version__ = "0.1.0"

colacloud_cli/api.py

@@ -0,0 +1,337 @@
+"""COLA Cloud API client wrapper."""
+
+from typing import Any, Optional
+
+import httpx
+
+from colacloud_cli import __version__
+from colacloud_cli.config import get_config
+
+
+class APIError(Exception):
+    """Exception raised for API errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        error_code: Optional[str] = None,
+        details: Optional[dict] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code
+        self.details = details or {}
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.status_code:
+            parts.insert(0, f"[{self.status_code}]")
+        if self.error_code:
+            parts.insert(0, f"({self.error_code})")
+        return " ".join(parts)
+
+
+class AuthenticationError(APIError):
+    """Exception raised for authentication errors."""
+
+    pass
+
+
+class RateLimitError(APIError):
+    """Exception raised when rate limit is exceeded."""
+
+    def __init__(
+        self,
+        message: str,
+        retry_after: Optional[int] = None,
+        **kwargs,
+    ):
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class ColaCloudClient:
+    """HTTP client for the COLA Cloud API."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+    ):
+        """Initialize the API client.
+
+        Args:
+            api_key: API key for authentication. If not provided,
+                    will be read from config.
+            base_url: API base URL. If not provided, will use default.
+            timeout: Request timeout in seconds.
+        """
+        config = get_config()
+        self.api_key = api_key or config.get_api_key()
+        self.base_url = (base_url or config.get_api_base_url()).rstrip("/")
+        self.timeout = timeout
+
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=self._get_headers(),
+        )
+
+    def _get_headers(self) -> dict[str, str]:
+        """Get request headers including authentication."""
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": f"colacloud-cli/{__version__}",
+        }
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+        return headers
+
+    def _handle_response(self, response: httpx.Response) -> dict[str, Any]:
+        """Handle API response and raise appropriate exceptions.
+
+        Args:
+            response: HTTP response object.
+
+        Returns:
+            Parsed JSON response data.
+
+        Raises:
+            AuthenticationError: If authentication fails.
+            RateLimitError: If rate limit is exceeded.
+            APIError: For other API errors.
+        """
+        # Try to parse JSON response
+        try:
+            data = response.json()
+        except (ValueError, httpx.DecodingError):
+            data = {}
+
+        # Handle successful responses
+        if response.is_success:
+            return data
+
+        # Extract error information
+        error_info = data.get("error", {})
+        error_code = error_info.get("code", "unknown_error")
+        error_message = error_info.get("message", response.reason_phrase or "Unknown error")
+        error_details = error_info.get("details", {})
+
+        # Handle specific error types
+        if response.status_code == 401:
+            raise AuthenticationError(
+                error_message,
+                status_code=response.status_code,
+                error_code=error_code,
+                details=error_details,
+            )
+
+        if response.status_code == 429:
+            retry_after = None
+            if "Retry-After" in response.headers:
+                try:
+                    retry_after = int(response.headers["Retry-After"])
+                except ValueError:
+                    pass
+
+            raise RateLimitError(
+                error_message,
+                status_code=response.status_code,
+                error_code=error_code,
+                details=error_details,
+                retry_after=retry_after,
+            )
+
+        raise APIError(
+            error_message,
+            status_code=response.status_code,
+            error_code=error_code,
+            details=error_details,
+        )
+
+    def _require_api_key(self) -> None:
+        """Ensure API key is configured.
+
+        Raises:
+            AuthenticationError: If API key is not configured.
+        """
+        if not self.api_key:
+            raise AuthenticationError(
+                "API key not configured. Run 'cola config set-key' to set your API key, "
+                "or set the COLACLOUD_API_KEY environment variable."
+            )
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> "ColaCloudClient":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    # COLA endpoints
+
+    def list_colas(
+        self,
+        query: Optional[str] = None,
+        product_type: Optional[str] = None,
+        origin: Optional[str] = None,
+        brand_name: Optional[str] = None,
+        approval_date_from: Optional[str] = None,
+        approval_date_to: Optional[str] = None,
+        abv_min: Optional[float] = None,
+        abv_max: Optional[float] = None,
+        page: int = 1,
+        per_page: int = 20,
+    ) -> dict[str, Any]:
+        """Search and filter COLAs.
+
+        Args:
+            query: Full-text search query.
+            product_type: Filter by product type (malt beverage, wine, distilled spirits).
+            origin: Filter by country/state.
+            brand_name: Filter by brand name (partial match).
+            approval_date_from: Filter by minimum approval date (YYYY-MM-DD).
+            approval_date_to: Filter by maximum approval date (YYYY-MM-DD).
+            abv_min: Filter by minimum ABV.
+            abv_max: Filter by maximum ABV.
+            page: Page number.
+            per_page: Results per page (max 100).
+
+        Returns:
+            API response with data and pagination info.
+        """
+        self._require_api_key()
+
+        params = {"page": page, "per_page": per_page}
+
+        if query:
+            params["q"] = query
+        if product_type:
+            params["product_type"] = product_type
+        if origin:
+            params["origin"] = origin
+        if brand_name:
+            params["brand_name"] = brand_name
+        if approval_date_from:
+            params["approval_date_from"] = approval_date_from
+        if approval_date_to:
+            params["approval_date_to"] = approval_date_to
+        if abv_min is not None:
+            params["abv_min"] = abv_min
+        if abv_max is not None:
+            params["abv_max"] = abv_max
+
+        response = self._client.get("/colas", params=params)
+        return self._handle_response(response)
+
+    def get_cola(self, ttb_id: str) -> dict[str, Any]:
+        """Get a single COLA by TTB ID.
+
+        Args:
+            ttb_id: The TTB ID of the COLA.
+
+        Returns:
+            API response with COLA details.
+        """
+        self._require_api_key()
+
+        response = self._client.get(f"/colas/{ttb_id}")
+        return self._handle_response(response)
+
+    # Permittee endpoints
+
+    def list_permittees(
+        self,
+        query: Optional[str] = None,
+        state: Optional[str] = None,
+        is_active: Optional[bool] = None,
+        page: int = 1,
+        per_page: int = 20,
+    ) -> dict[str, Any]:
+        """Search permittees.
+
+        Args:
+            query: Search by company name (partial match).
+            state: Filter by state.
+            is_active: Filter by active status.
+            page: Page number.
+            per_page: Results per page (max 100).
+
+        Returns:
+            API response with data and pagination info.
+        """
+        self._require_api_key()
+
+        params = {"page": page, "per_page": per_page}
+
+        if query:
+            params["q"] = query
+        if state:
+            params["state"] = state.upper()
+        if is_active is not None:
+            params["is_active"] = "true" if is_active else "false"
+
+        response = self._client.get("/permittees", params=params)
+        return self._handle_response(response)
+
+    def get_permittee(self, permit_number: str) -> dict[str, Any]:
+        """Get a single permittee by permit number.
+
+        Args:
+            permit_number: The permit number.
+
+        Returns:
+            API response with permittee details.
+        """
+        self._require_api_key()
+
+        response = self._client.get(f"/permittees/{permit_number}")
+        return self._handle_response(response)
+
+    # Barcode endpoint
+
+    def lookup_barcode(self, barcode_value: str) -> dict[str, Any]:
+        """Look up COLAs by barcode.
+
+        Args:
+            barcode_value: The barcode value (UPC, EAN, etc.).
+
+        Returns:
+            API response with barcode info and associated COLAs.
+        """
+        self._require_api_key()
+
+        response = self._client.get(f"/barcode/{barcode_value}")
+        return self._handle_response(response)
+
+    # Usage endpoint
+
+    def get_usage(self) -> dict[str, Any]:
+        """Get current API usage statistics.
+
+        Returns:
+            API response with usage data.
+        """
+        self._require_api_key()
+
+        response = self._client.get("/usage")
+        return self._handle_response(response)
+
+
+# Convenience function to get a client instance
+def get_client(**kwargs) -> ColaCloudClient:
+    """Get a ColaCloudClient instance.
+
+    Args:
+        **kwargs: Arguments to pass to ColaCloudClient constructor.
+
+    Returns:
+        ColaCloudClient instance.
+    """
+    return ColaCloudClient(**kwargs)

colacloud_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules."""

colacloud_cli/commands/barcode.py

@@ -0,0 +1,48 @@
+"""Barcode lookup command for COLA Cloud CLI."""
+
+import json
+
+import click
+
+from colacloud_cli.api import APIError, get_client
+from colacloud_cli.commands.utils import console, handle_api_error
+from colacloud_cli.formatters import format_barcode_result
+
+
+@click.command(name="barcode")
+@click.argument("value")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+def barcode_command(value: str, as_json: bool):
+    """Look up COLAs by barcode (UPC, EAN, etc.).
+
+    VALUE is the barcode number from the product label.
+
+    This command searches the COLA database for products that have been
+    registered with the specified barcode.
+
+    Examples:
+
+    \b
+        # Look up a UPC barcode
+        cola barcode 012345678901
+
+    \b
+        # Look up an EAN barcode
+        cola barcode 5000281025155
+
+    \b
+        # Output as JSON
+        cola barcode 012345678901 --json
+    """
+    try:
+        with get_client() as client:
+            result = client.lookup_barcode(value)
+
+        if as_json:
+            click.echo(json.dumps(result, indent=2))
+        else:
+            data = result.get("data", {})
+            format_barcode_result(data, console)
+
+    except APIError as e:
+        handle_api_error(e)

colacloud_cli/commands/colas.py

@@ -0,0 +1,179 @@
+"""COLA commands for COLA Cloud CLI."""
+
+import json
+
+import click
+
+from colacloud_cli.api import APIError, get_client
+from colacloud_cli.commands.utils import console, handle_api_error
+from colacloud_cli.formatters import (
+    format_cola_detail,
+    format_cola_table,
+    format_pagination,
+)
+
+
+@click.group(name="colas")
+def colas_group():
+    """Search and retrieve COLA records."""
+    pass
+
+
+@colas_group.command(name="list")
+@click.option("-q", "--query", help="Full-text search query.")
+@click.option(
+    "--product-type",
+    type=click.Choice(["malt beverage", "wine", "distilled spirits"], case_sensitive=False),
+    help="Filter by product type.",
+)
+@click.option("--origin", help="Filter by origin (country/state).")
+@click.option("--brand", "brand_name", help="Filter by brand name (partial match).")
+@click.option("--date-from", "approval_date_from", help="Filter by minimum approval date (YYYY-MM-DD).")
+@click.option("--date-to", "approval_date_to", help="Filter by maximum approval date (YYYY-MM-DD).")
+@click.option("--abv-min", type=float, help="Filter by minimum ABV.")
+@click.option("--abv-max", type=float, help="Filter by maximum ABV.")
+@click.option("--limit", "per_page", default=20, type=int, help="Results per page (max 100).")
+@click.option("--page", default=1, type=int, help="Page number.")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+def list_colas(
+    query: str | None,
+    product_type: str | None,
+    origin: str | None,
+    brand_name: str | None,
+    approval_date_from: str | None,
+    approval_date_to: str | None,
+    abv_min: float | None,
+    abv_max: float | None,
+    per_page: int,
+    page: int,
+    as_json: bool,
+):
+    """List and search COLA records.
+
+    Examples:
+
+    \b
+        # Search for bourbon
+        cola colas list -q "bourbon"
+
+    \b
+        # List wines from California
+        cola colas list --product-type wine --origin california
+
+    \b
+        # Find high-ABV spirits
+        cola colas list --product-type "distilled spirits" --abv-min 50
+
+    \b
+        # Search by brand
+        cola colas list --brand "buffalo trace"
+    """
+    try:
+        with get_client() as client:
+            result = client.list_colas(
+                query=query,
+                product_type=product_type,
+                origin=origin,
+                brand_name=brand_name,
+                approval_date_from=approval_date_from,
+                approval_date_to=approval_date_to,
+                abv_min=abv_min,
+                abv_max=abv_max,
+                page=page,
+                per_page=min(per_page, 100),
+            )
+
+        if as_json:
+            click.echo(json.dumps(result, indent=2))
+        else:
+            colas = result.get("data", [])
+            pagination = result.get("pagination", {})
+
+            if not colas:
+                console.print("[yellow]No COLAs found matching your criteria.[/]")
+                return
+
+            table = format_cola_table(colas, console)
+            console.print(table)
+            format_pagination(pagination, console)
+
+    except APIError as e:
+        handle_api_error(e)
+
+
+@colas_group.command(name="get")
+@click.argument("ttb_id")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+def get_cola(ttb_id: str, as_json: bool):
+    """Get detailed information about a specific COLA.
+
+    TTB_ID is the unique identifier for the COLA (e.g., 24001234).
+
+    Examples:
+
+    \b
+        # Get COLA details
+        cola colas get 24001234
+
+    \b
+        # Output as JSON
+        cola colas get 24001234 --json
+    """
+    try:
+        with get_client() as client:
+            result = client.get_cola(ttb_id)
+
+        if as_json:
+            click.echo(json.dumps(result, indent=2))
+        else:
+            cola = result.get("data", {})
+            format_cola_detail(cola, console)
+
+    except APIError as e:
+        handle_api_error(e)
+
+
+@colas_group.command(name="search")
+@click.argument("query")
+@click.option("--limit", "per_page", default=20, type=int, help="Results per page (max 100).")
+@click.option("--page", default=1, type=int, help="Page number.")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+def search_colas(query: str, per_page: int, page: int, as_json: bool):
+    """Quick search for COLAs.
+
+    This is a shortcut for 'cola colas list -q <query>'.
+
+    Examples:
+
+    \b
+        # Search for whiskey
+        cola colas search "whiskey"
+
+    \b
+        # Search for a specific brand
+        cola colas search "buffalo trace"
+    """
+    try:
+        with get_client() as client:
+            result = client.list_colas(
+                query=query,
+                page=page,
+                per_page=min(per_page, 100),
+            )
+
+        if as_json:
+            click.echo(json.dumps(result, indent=2))
+        else:
+            colas = result.get("data", [])
+            pagination = result.get("pagination", {})
+
+            if not colas:
+                console.print(f"[yellow]No COLAs found for '{query}'.[/]")
+                return
+
+            table = format_cola_table(colas, console)
+            console.print(table)
+            format_pagination(pagination, console)
+
+    except APIError as e:
+        handle_api_error(e)

colacloud_cli/commands/config.py

@@ -0,0 +1,80 @@
+"""Configuration commands for COLA Cloud CLI."""
+
+import json
+
+import click
+from rich.console import Console
+
+from colacloud_cli.config import get_config
+from colacloud_cli.formatters import format_config
+
+console = Console()
+
+
+@click.group(name="config")
+def config_group():
+    """Manage CLI configuration."""
+    pass
+
+
+@config_group.command(name="set-key")
+@click.option(
+    "--key",
+    "-k",
+    help="API key to set. If not provided, will prompt for input.",
+)
+def set_key(key: str | None):
+    """Set your COLA Cloud API key.
+
+    The API key will be saved to ~/.colacloud/config.json with restricted
+    permissions (readable only by you).
+
+    You can also set the COLACLOUD_API_KEY environment variable instead.
+    """
+    config = get_config()
+
+    if key is None:
+        # Prompt for API key with hidden input
+        key = click.prompt(
+            "Enter your API key",
+            hide_input=True,
+            confirmation_prompt=True,
+        )
+
+    if not key or not key.strip():
+        console.print("[red]Error:[/] API key cannot be empty.")
+        raise SystemExit(1)
+
+    key = key.strip()
+    config.set_api_key(key)
+
+    console.print("[green]Success![/] API key saved to ~/.colacloud/config.json")
+    console.print("[dim]The config file has been set to mode 600 (owner read/write only).[/]")
+
+
+@config_group.command(name="show")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+def show(as_json: bool):
+    """Show current configuration.
+
+    API key will be partially masked for security.
+    """
+    config = get_config()
+    config_data = config.to_dict()
+
+    if as_json:
+        click.echo(json.dumps(config_data, indent=2))
+    else:
+        format_config(config_data, console)
+
+
+@config_group.command(name="clear")
+@click.confirmation_option(prompt="Are you sure you want to clear your configuration?")
+def clear():
+    """Clear all saved configuration.
+
+    This will remove your saved API key and any other settings.
+    """
+    config = get_config()
+    config.clear()
+    console.print("[green]Configuration cleared.[/]")