colacloud-cli 0.3.2__tar.gz → 0.3.4__tar.gz

colacloud_cli-0.3.4/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.event.pull_request.head.ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build & Validate
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      PYTHONPATH: src
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest tests
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Build package
+        run: uv build

{colacloud_cli-0.3.2 → colacloud_cli-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: colacloud-cli
-Version: 0.3.2
+Version: 0.3.4
 Summary: Command-line interface for the COLA Cloud API
 Project-URL: Homepage, https://colacloud.us
 Project-URL: Documentation, https://docs.colacloud.us/api-reference
@@ -100,8 +100,12 @@ cola colas list --date-from 2024-01-01 --date-to 2024-12-31
 # Filter by ABV
 cola colas list --product-type "distilled spirits" --abv-min 40 --abv-max 50
 
-# Search by brand name
-cola colas list --brand "maker's mark"
+# Filter by package and derived category
+cola colas list --category Beer --derived-subcategory "Beer > Ale" \
+  --container-type can --volume-unit "fluid ounces" --volume-min 12 --volume-max 16
+
+# Search generic text, including applicant/company names
+cola colas list -q "molson coors"
 
 # Pagination
 cola colas list -q "bourbon" --limit 50 --page 2
@@ -117,14 +121,24 @@ cola colas list -q "whiskey" --json | jq '.data[].brand_name'
 
 | Option | Description |
 |--------|-------------|
-| `-q, --query` | Full-text search query |
-| `--product-type` | Filter by type: `malt beverage`, `wine`, `distilled spirits` |
+| `-q, --query` | Generic text query across brand, product, permit, applicant/company, and related text |
+| `--product-type` | Filter by TTB type: `malt beverage`, `wine`, `distilled spirits`; can be used multiple times |
+| `--category` | Filter by derived category: `Beer`, `Wine`, `Liquor`; can be used multiple times |
+| `--derived-subcategory` | Filter by derived category path prefix, such as `Beer > Ale` |
 | `--origin` | Filter by country/state |
+| `--domestic-or-imported` | Filter by `domestic` or `imported` |
+| `--status` | Filter by application status |
 | `--brand` | Filter by brand name (partial match) |
+| `--permit-number` | Filter by exact permit number |
+| `--barcode` | Filter by exact main barcode value |
 | `--date-from` | Minimum approval date (YYYY-MM-DD) |
 | `--date-to` | Maximum approval date (YYYY-MM-DD) |
 | `--abv-min` | Minimum ABV percentage |
 | `--abv-max` | Maximum ABV percentage |
+| `--volume-unit` | Package volume unit; required with `--volume-min` or `--volume-max` |
+| `--volume-min` | Minimum package volume |
+| `--volume-max` | Maximum package volume |
+| `--container-type` | Derived container type; can be used multiple times |
 | `--limit` | Results per page (max 100) |
 | `--page` | Page number |
 | `--json` | Output as JSON |

{colacloud_cli-0.3.2 → colacloud_cli-0.3.4}/README.md

@@ -73,8 +73,12 @@ cola colas list --date-from 2024-01-01 --date-to 2024-12-31
 # Filter by ABV
 cola colas list --product-type "distilled spirits" --abv-min 40 --abv-max 50
 
-# Search by brand name
-cola colas list --brand "maker's mark"
+# Filter by package and derived category
+cola colas list --category Beer --derived-subcategory "Beer > Ale" \
+  --container-type can --volume-unit "fluid ounces" --volume-min 12 --volume-max 16
+
+# Search generic text, including applicant/company names
+cola colas list -q "molson coors"
 
 # Pagination
 cola colas list -q "bourbon" --limit 50 --page 2
@@ -90,14 +94,24 @@ cola colas list -q "whiskey" --json | jq '.data[].brand_name'
 
 | Option | Description |
 |--------|-------------|
-| `-q, --query` | Full-text search query |
-| `--product-type` | Filter by type: `malt beverage`, `wine`, `distilled spirits` |
+| `-q, --query` | Generic text query across brand, product, permit, applicant/company, and related text |
+| `--product-type` | Filter by TTB type: `malt beverage`, `wine`, `distilled spirits`; can be used multiple times |
+| `--category` | Filter by derived category: `Beer`, `Wine`, `Liquor`; can be used multiple times |
+| `--derived-subcategory` | Filter by derived category path prefix, such as `Beer > Ale` |
 | `--origin` | Filter by country/state |
+| `--domestic-or-imported` | Filter by `domestic` or `imported` |
+| `--status` | Filter by application status |
 | `--brand` | Filter by brand name (partial match) |
+| `--permit-number` | Filter by exact permit number |
+| `--barcode` | Filter by exact main barcode value |
 | `--date-from` | Minimum approval date (YYYY-MM-DD) |
 | `--date-to` | Maximum approval date (YYYY-MM-DD) |
 | `--abv-min` | Minimum ABV percentage |
 | `--abv-max` | Maximum ABV percentage |
+| `--volume-unit` | Package volume unit; required with `--volume-min` or `--volume-max` |
+| `--volume-min` | Minimum package volume |
+| `--volume-max` | Maximum package volume |
+| `--container-type` | Derived container type; can be used multiple times |
 | `--limit` | Results per page (max 100) |
 | `--page` | Page number |
 | `--json` | Output as JSON |

{colacloud_cli-0.3.2 → colacloud_cli-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "colacloud-cli"
-version = "0.3.2"
+version = "0.3.4"
 description = "Command-line interface for the COLA Cloud API"
 readme = "README.md"
 license = { text = "MIT" }

{colacloud_cli-0.3.2 → colacloud_cli-0.3.4}/src/colacloud_cli/api.py

@@ -181,26 +181,46 @@ class ColaCloudClient:
         self,
         query: str | None = None,
         product_type: str | None = None,
+        category: str | None = None,
+        derived_subcategory: str | None = None,
         origin: str | None = None,
+        domestic_or_imported: str | None = None,
+        status: str | None = None,
         brand_name: str | None = None,
+        permit_number: str | None = None,
+        barcode_value: str | None = None,
         approval_date_from: str | None = None,
         approval_date_to: str | None = None,
         abv_min: float | None = None,
         abv_max: float | None = None,
+        volume_unit: str | None = None,
+        volume_min: float | None = None,
+        volume_max: float | None = None,
+        container_type: str | None = 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.
+            query: Text search query, including applicant/company names.
+            product_type: Filter by one or more TTB product types.
+            category: Filter by derived top-level category.
+            derived_subcategory: Filter by derived category path prefix.
             origin: Filter by country/state.
+            domestic_or_imported: Filter by domestic/imported origin.
+            status: Filter by application status.
             brand_name: Filter by brand name (partial match).
+            permit_number: Filter by exact permit number.
+            barcode_value: Filter by exact main barcode value.
             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.
+            volume_unit: Filter by volume unit. Required with volume_min/volume_max.
+            volume_min: Filter by minimum package volume.
+            volume_max: Filter by maximum package volume.
+            container_type: Filter by one or more derived container types.
             page: Page number.
             per_page: Results per page (max 100).
 
@@ -215,10 +235,22 @@ class ColaCloudClient:
             params["q"] = query
         if product_type:
             params["product_type"] = product_type
+        if category:
+            params["category"] = category
+        if derived_subcategory:
+            params["derived_subcategory"] = derived_subcategory
         if origin:
             params["origin"] = origin
+        if domestic_or_imported:
+            params["domestic_or_imported"] = domestic_or_imported
+        if status:
+            params["status"] = status
         if brand_name:
             params["brand_name"] = brand_name
+        if permit_number:
+            params["permit_number"] = permit_number
+        if barcode_value:
+            params["barcode_value"] = barcode_value
         if approval_date_from:
             params["approval_date_from"] = approval_date_from
         if approval_date_to:
@@ -227,6 +259,14 @@ class ColaCloudClient:
             params["abv_min"] = abv_min
         if abv_max is not None:
             params["abv_max"] = abv_max
+        if volume_unit:
+            params["volume_unit"] = volume_unit
+        if volume_min is not None:
+            params["volume_min"] = volume_min
+        if volume_max is not None:
+            params["volume_max"] = volume_max
+        if container_type:
+            params["container_type"] = container_type
 
         response = self._client.get("/colas", params=params)
         return self._handle_response(response)

{colacloud_cli-0.3.2 → colacloud_cli-0.3.4}/src/colacloud_cli/commands/colas.py

@@ -13,6 +13,12 @@ from colacloud_cli.formatters import (
 )
 
 
+def _join_multi(values: tuple[str, ...]) -> str | None:
+    parts = [part.strip() for value in values for part in value.split(",")]
+    joined = ",".join(part for part in parts if part)
+    return joined or None
+
+
 @click.group(name="colas")
 def colas_group():
     """Search and retrieve COLA records."""
@@ -23,13 +29,32 @@ def colas_group():
 @click.option("-q", "--query", help="Full-text search query.")
 @click.option(
     "--product-type",
+    multiple=True,
     type=click.Choice(
         ["malt beverage", "wine", "distilled spirits"], case_sensitive=False
     ),
-    help="Filter by product type.",
+    help="Filter by TTB product type. Can be used multiple times.",
+)
+@click.option(
+    "--category",
+    multiple=True,
+    type=click.Choice(["Beer", "Wine", "Liquor"], case_sensitive=False),
+    help="Filter by derived top-level category. Can be used multiple times.",
+)
+@click.option(
+    "--derived-subcategory",
+    help='Filter by derived category path prefix, e.g. "Beer > Ale".',
 )
 @click.option("--origin", help="Filter by origin (country/state).")
+@click.option(
+    "--domestic-or-imported",
+    type=click.Choice(["domestic", "imported"], case_sensitive=False),
+    help="Filter by domestic/imported origin.",
+)
+@click.option("--status", help="Filter by application status.")
 @click.option("--brand", "brand_name", help="Filter by brand name (partial match).")
+@click.option("--permit-number", help="Filter by exact permit number.")
+@click.option("--barcode", "barcode_value", help="Filter by exact main barcode value.")
 @click.option(
     "--date-from",
     "approval_date_from",
@@ -42,6 +67,44 @@ def colas_group():
 )
 @click.option("--abv-min", type=float, help="Filter by minimum ABV.")
 @click.option("--abv-max", type=float, help="Filter by maximum ABV.")
+@click.option(
+    "--volume-unit",
+    type=click.Choice(
+        [
+            "beer barrels",
+            "fluid ounces",
+            "gallons",
+            "liters",
+            "milliliters",
+            "pints",
+            "quarts",
+        ],
+        case_sensitive=False,
+    ),
+    help="Filter by package volume unit. Required with --volume-min/--volume-max.",
+)
+@click.option("--volume-min", type=float, help="Filter by minimum package volume.")
+@click.option("--volume-max", type=float, help="Filter by maximum package volume.")
+@click.option(
+    "--container-type",
+    multiple=True,
+    type=click.Choice(
+        [
+            "bag",
+            "bottle",
+            "box",
+            "can",
+            "carton",
+            "cask",
+            "jug",
+            "keg",
+            "pod",
+            "pouch",
+        ],
+        case_sensitive=False,
+    ),
+    help="Filter by derived container type. Can be used multiple times.",
+)
 @click.option(
     "--limit", "per_page", default=20, type=int, help="Results per page (max 100)."
 )
@@ -49,13 +112,23 @@ def colas_group():
 @click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
 def list_colas(
     query: str | None,
-    product_type: str | None,
+    product_type: tuple[str, ...],
+    category: tuple[str, ...],
+    derived_subcategory: str | None,
     origin: str | None,
+    domestic_or_imported: str | None,
+    status: str | None,
     brand_name: str | None,
+    permit_number: str | None,
+    barcode_value: str | None,
     approval_date_from: str | None,
     approval_date_to: str | None,
     abv_min: float | None,
     abv_max: float | None,
+    volume_unit: str | None,
+    volume_min: float | None,
+    volume_max: float | None,
+    container_type: tuple[str, ...],
     per_page: int,
     page: int,
     as_json: bool,
@@ -69,28 +142,40 @@ def list_colas(
         cola colas list -q "bourbon"
 
     \b
-        # List wines from California
-        cola colas list --product-type wine --origin california
+        # List wine or beer from California
+        cola colas list --product-type wine --product-type "malt beverage"
+          --origin california
 
     \b
-        # Find high-ABV spirits
-        cola colas list --product-type "distilled spirits" --abv-min 50
+        # Find 12 oz canned beer
+        cola colas list --category Beer --container-type can
+          --volume-unit "fluid ounces" --volume-min 12 --volume-max 12
 
     \b
-        # Search by brand
-        cola colas list --brand "buffalo trace"
+        # Search generic text, including applicant/company names
+        cola colas list -q "molson coors"
     """
     try:
         with get_client() as client:
             result = client.list_colas(
                 query=query,
-                product_type=product_type,
+                product_type=_join_multi(product_type),
+                category=_join_multi(category),
+                derived_subcategory=derived_subcategory,
                 origin=origin,
+                domestic_or_imported=domestic_or_imported,
+                status=status,
                 brand_name=brand_name,
+                permit_number=permit_number,
+                barcode_value=barcode_value,
                 approval_date_from=approval_date_from,
                 approval_date_to=approval_date_to,
                 abv_min=abv_min,
                 abv_max=abv_max,
+                volume_unit=volume_unit,
+                volume_min=volume_min,
+                volume_max=volume_max,
+                container_type=_join_multi(container_type),
                 page=page,
                 per_page=min(per_page, 100),
             )

{colacloud_cli-0.3.2 → colacloud_cli-0.3.4}/src/colacloud_cli/formatters.py

@@ -494,6 +494,16 @@ def format_pagination(pagination: dict[str, Any], console: Console) -> None:
     pages = pagination.get("pages", 1)
     total = pagination.get("total", 0)
     per_page = pagination.get("per_page", 20)
+    has_more = pagination.get("has_more")
+
+    if total is None:
+        msg = f"Showing page {page}"
+        if has_more is True:
+            msg += " (more results available)"
+        elif has_more is False:
+            msg += " (end of results)"
+        console.print(f"\n[dim]{msg}[/]")
+        return
 
     # Calculate showing range
     start = (page - 1) * per_page + 1

{colacloud_cli-0.3.2 → colacloud_cli-0.3.4}/tests/test_api.py

@@ -86,9 +86,19 @@ class TestListColas:
 
         client.list_colas(
             query="bourbon",
-            product_type="distilled spirits",
+            product_type="distilled spirits,wine",
+            category="Liquor,Wine",
+            derived_subcategory="Liquor > Whiskey",
             origin="kentucky",
+            domestic_or_imported="domestic",
+            status="approved",
+            permit_number="KY-I-12345",
+            barcode_value="012345678905",
             abv_min=40.0,
+            volume_unit="milliliters",
+            volume_min=375,
+            volume_max=750,
+            container_type="bottle,can",
         )
 
         request = route.calls[0].request
@@ -96,6 +106,16 @@ class TestListColas:
         assert "product_type=distilled" in str(request.url)
         assert "origin=kentucky" in str(request.url)
         assert "abv_min=40" in str(request.url)
+        assert "category=Liquor%2CWine" in str(request.url)
+        assert "derived_subcategory=Liquor+%3E+Whiskey" in str(request.url)
+        assert "domestic_or_imported=domestic" in str(request.url)
+        assert "status=approved" in str(request.url)
+        assert "permit_number=KY-I-12345" in str(request.url)
+        assert "barcode_value=012345678905" in str(request.url)
+        assert "volume_unit=milliliters" in str(request.url)
+        assert "volume_min=375" in str(request.url)
+        assert "volume_max=750" in str(request.url)
+        assert "container_type=bottle%2Ccan" in str(request.url)
 
 
 class TestGetCola:

{colacloud_cli-0.3.2 → colacloud_cli-0.3.4}/tests/test_cli.py

@@ -44,7 +44,7 @@ class TestColasCommands:
     @respx.mock
     def test_colas_list(self, runner, api_key):
         """colas list returns results."""
-        respx.get("https://app.colacloud.us/api/v1/colas").mock(
+        route = respx.get("https://app.colacloud.us/api/v1/colas").mock(
             return_value=httpx.Response(
                 200,
                 json={
@@ -67,9 +67,38 @@ class TestColasCommands:
             )
         )
 
-        result = runner.invoke(cli, ["colas", "list", "-q", "test"])
+        result = runner.invoke(
+            cli,
+            [
+                "colas",
+                "list",
+                "-q",
+                "test",
+                "--product-type",
+                "wine",
+                "--product-type",
+                "malt beverage",
+                "--category",
+                "Beer",
+                "--container-type",
+                "can",
+                "--volume-unit",
+                "fluid ounces",
+                "--volume-min",
+                "12",
+                "--volume-max",
+                "16",
+            ],
+        )
         assert result.exit_code == 0
         assert "Test Brand" in result.output
+        request_url = str(route.calls[0].request.url)
+        assert "product_type=wine%2Cmalt+beverage" in request_url
+        assert "category=Beer" in request_url
+        assert "container_type=can" in request_url
+        assert "volume_unit=fluid+ounces" in request_url
+        assert "volume_min=12" in request_url
+        assert "volume_max=16" in request_url
 
     @respx.mock
     def test_colas_list_json(self, runner, api_key):

colacloud_cli-0.3.4/tests/test_formatters.py

@@ -0,0 +1,39 @@
+from rich.console import Console
+
+from colacloud_cli.formatters import format_pagination
+
+
+def _render_pagination(pagination: dict) -> str:
+    console = Console(record=True, width=100)
+    format_pagination(pagination, console)
+    return console.export_text()
+
+
+def test_format_pagination_handles_unknown_total_with_more_results():
+    output = _render_pagination(
+        {
+            "mode": "offset",
+            "page": 1,
+            "per_page": 3,
+            "total": None,
+            "pages": None,
+            "has_more": True,
+        }
+    )
+
+    assert "Showing page 1 (more results available)" in output
+
+
+def test_format_pagination_handles_unknown_total_at_end():
+    output = _render_pagination(
+        {
+            "mode": "offset",
+            "page": 2,
+            "per_page": 3,
+            "total": None,
+            "pages": None,
+            "has_more": False,
+        }
+    )
+
+    assert "Showing page 2 (end of results)" in output