slab-cli 0.1.0__tar.gz

slab_cli-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.3
+Name: slab-cli
+Version: 0.1.0
+Summary: CLI for the slab trading-card API — catalog, collect, and track your cards from the terminal.
+Author: dev_jeb
+Requires-Dist: slab-schemas>=0.1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Requires-Dist: inquirerpy>=0.3
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# slab-cli
+
+A terminal client for the [slab](https://api.slab.dev-jeb.com) trading-card API — browse the
+catalog, price cards against real sales comps, and track your own collection from the command line.
+
+```bash
+pip install slab-cli
+```
+
+This installs the `slab` command.
+
+## Setup
+
+The CLI talks to the hosted slab API. You need an **API key** — mint one from the
+[slab portal](https://app.slab.dev-jeb.com) (sign in → **API Keys** → create). Then:
+
+```bash
+export SLAB_API_KEY=sk_live_...        # your key (required)
+# optional:
+export SLAB_API_URL=https://api.slab.dev-jeb.com   # default; override for a self-hosted API
+export SLAB_COLLECTOR=<collector-uuid>             # your active collector, reused across commands
+```
+
+## Quickstart
+
+```bash
+# Catalog + pricing (no collector needed)
+slab card search --subject "Connor Bedard"      # find cards
+slab card price <card-uuid>                      # fair-market value from sales comps
+slab card comps <card-uuid>                      # the underlying recent sales
+slab set "OPC Platinum"                          # a set's sealed FMV + top cards
+
+# Your collection
+slab collector create                            # one-time: create your collector profile
+slab collection add                              # add an owned copy (grade, cost, acquisition)
+slab collection cost                             # log grading/shipping costs on a copy
+slab break new                                   # record a box/case break
+slab collection dashboard                        # portfolio value, cost basis, P&L
+slab collection search                           # search + filter your copies
+```
+
+Run `slab` with no arguments for the full command list, or `slab <group>` (e.g. `slab collection`)
+to see a group's verbs.
+
+## Configuration reference
+
+| Env var         | Purpose                                    | Default                          |
+| --------------- | ------------------------------------------ | -------------------------------- |
+| `SLAB_API_KEY`  | API key for authentication (**required**)  | —                                |
+| `SLAB_API_URL`  | Base URL of the slab API                   | `https://api.slab.dev-jeb.com`   |
+| `SLAB_COLLECTOR`| Active collector UUID, reused per command  | —                                |
+
+## What it depends on
+
+Requests and responses are typed against [`slab-schemas`](https://pypi.org/project/slab-schemas/) —
+the same pydantic wire contract the API itself uses — so the CLI and API can never drift.
+
+Requires Python 3.13+.

slab_cli-0.1.0/README.md

@@ -0,0 +1,58 @@
+# slab-cli
+
+A terminal client for the [slab](https://api.slab.dev-jeb.com) trading-card API — browse the
+catalog, price cards against real sales comps, and track your own collection from the command line.
+
+```bash
+pip install slab-cli
+```
+
+This installs the `slab` command.
+
+## Setup
+
+The CLI talks to the hosted slab API. You need an **API key** — mint one from the
+[slab portal](https://app.slab.dev-jeb.com) (sign in → **API Keys** → create). Then:
+
+```bash
+export SLAB_API_KEY=sk_live_...        # your key (required)
+# optional:
+export SLAB_API_URL=https://api.slab.dev-jeb.com   # default; override for a self-hosted API
+export SLAB_COLLECTOR=<collector-uuid>             # your active collector, reused across commands
+```
+
+## Quickstart
+
+```bash
+# Catalog + pricing (no collector needed)
+slab card search --subject "Connor Bedard"      # find cards
+slab card price <card-uuid>                      # fair-market value from sales comps
+slab card comps <card-uuid>                      # the underlying recent sales
+slab set "OPC Platinum"                          # a set's sealed FMV + top cards
+
+# Your collection
+slab collector create                            # one-time: create your collector profile
+slab collection add                              # add an owned copy (grade, cost, acquisition)
+slab collection cost                             # log grading/shipping costs on a copy
+slab break new                                   # record a box/case break
+slab collection dashboard                        # portfolio value, cost basis, P&L
+slab collection search                           # search + filter your copies
+```
+
+Run `slab` with no arguments for the full command list, or `slab <group>` (e.g. `slab collection`)
+to see a group's verbs.
+
+## Configuration reference
+
+| Env var         | Purpose                                    | Default                          |
+| --------------- | ------------------------------------------ | -------------------------------- |
+| `SLAB_API_KEY`  | API key for authentication (**required**)  | —                                |
+| `SLAB_API_URL`  | Base URL of the slab API                   | `https://api.slab.dev-jeb.com`   |
+| `SLAB_COLLECTOR`| Active collector UUID, reused per command  | —                                |
+
+## What it depends on
+
+Requests and responses are typed against [`slab-schemas`](https://pypi.org/project/slab-schemas/) —
+the same pydantic wire contract the API itself uses — so the CLI and API can never drift.
+
+Requires Python 3.13+.

slab_cli-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "slab-cli"
+version = "0.1.0"
+description = "CLI for the slab trading-card API — catalog, collect, and track your cards from the terminal."
+readme = "README.md"
+authors = [{name = "dev_jeb"}]
+requires-python = ">=3.13"
+dependencies = [
+    "slab-schemas>=0.1.0",
+    "httpx>=0.27",
+    "rich>=13.0",
+    "InquirerPy>=0.3",
+]
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[build-system]
+requires = ["uv_build>=0.9.5,<0.10.0"]
+build-backend = "uv_build"
+
+[[tool.uv.index]]
+name = "slab-registry"
+url = "https://slab-package-domain-682033488592.d.codeartifact.us-east-1.amazonaws.com/pypi/slab-package-repository/simple/"
+
+[project.scripts]
+slab = "slab_cli.main:main"

slab_cli-0.1.0/src/slab_cli/banner.py

@@ -0,0 +1,92 @@
+"""The slab banner — the wordmark rendered as the thing a slab IS: a graded card in its case.
+
+A rounded foil-edged case (the same card silhouette every panel in the CLI uses), a grade label
+across the top — because obviously this CLI grades a perfect GEM MT 10 — and the SLAB wordmark
+printed in full gold foil: the letter faces run a top-to-bottom gradient between the portal's two
+foil tokens (bright gold catching the light, fading toward dark gold), and the drop-shadow strokes
+sit in dark gold so every letterform — the B's bowls especially — stays crisp instead of dissolving
+into the background. Both endpoint colors come from `theme.py`, so the banner restyles with the
+rest of the CLI."""
+
+from __future__ import annotations
+
+from rich.console import Group, RenderableType
+from rich.panel import Panel
+from rich.text import Text
+
+from .theme import CARD_BOX, FOIL, FOIL_DIM
+
+# ANSI-shadow letterform: solid blocks are the foil face, box-drawing chars the drop shadow.
+_WORDMARK = """\
+███████╗██╗      █████╗ ██████╗
+██╔════╝██║     ██╔══██╗██╔══██╗
+███████╗██║     ███████║██████╔╝
+╚════██║██║     ██╔══██║██╔══██╗
+███████║███████╗██║  ██║██████╔╝
+╚══════╝╚══════╝╚═╝  ╚═╝╚═════╝"""
+
+_SHADOW = set("╔╗╚╝═║")
+
+
+def _hex_to_rgb(hex_color: str) -> tuple[int, int, int]:
+    h = hex_color.lstrip("#")
+    return int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)
+
+
+def _lerp_hex(a: str, b: str, t: float) -> str:
+    """Blend between two theme hex colors — the in-between shades of the foil gradient."""
+    ra, ga, ba = _hex_to_rgb(a)
+    rb, gb, bb = _hex_to_rgb(b)
+    return f"#{round(ra + (rb - ra) * t):02x}{round(ga + (gb - ga) * t):02x}{round(ba + (bb - ba) * t):02x}"
+
+
+def _foil_print(art: str) -> Text:
+    """Print the letterform in foil: gradient gold faces, dark-gold shadow strokes.
+
+    The face gradient stops short of FOIL_DIM (t ≤ 0.6) so even the bottom row of the face stays
+    visibly brighter than the shadow — face and shadow must never blend or letter shapes smear."""
+    lines = art.splitlines()
+    width = max(len(line) for line in lines)
+    last = len(lines) - 1
+    t = Text()
+    for i, line in enumerate(lines):
+        face = f"bold {_lerp_hex(FOIL, FOIL_DIM, 0.6 * (i / last))}"
+        for ch in line.ljust(width):
+            t.append(ch, style=face if ch == "█" else f"{FOIL_DIM}" if ch in _SHADOW else None)
+        if i < last:
+            t.append("\n")
+    return t
+
+
+def _grade_label(width: int) -> Text:
+    """The slab's grade label: what it holds on the left, the verdict in gold on the right."""
+    left, right = "CATALOG & COLLECTION", "GEM MT 10"
+    t = Text()
+    t.append(left, style="slab.label")
+    t.append(" " * max(1, width - len(left) - len(right)))
+    t.append(right, style="slab.foil")
+    return t
+
+
+def _build() -> RenderableType:
+    width = max(len(line) for line in _WORDMARK.splitlines())
+    case = Panel(
+        Group(
+            _grade_label(width),
+            Text("─" * width, style="slab.foil_dim"),
+            _foil_print(_WORDMARK),
+        ),
+        box=CARD_BOX,
+        border_style="slab.foil_dim",
+        padding=(0, 2),
+        expand=False,
+    )
+    return Group(
+        Text(),
+        case,
+        Text("  trading card catalog & collection tracker", style="slab.dim"),
+        Text(),
+    )
+
+
+BANNER: RenderableType = _build()

slab_cli-0.1.0/src/slab_cli/client.py

@@ -0,0 +1,386 @@
+"""Typed HTTP client for the slab API. Talks to the API via httpx, returns schema DTOs.
+
+Usage:
+    client = SlabClient("https://api.slab.dev-jeb.com", api_key="sk_live_...")
+    results = client.search_cards(CardSearchQuery(subject="McDavid", rookie=True))
+"""
+
+from __future__ import annotations
+
+import httpx
+from slab_schemas.account import MeOut
+from slab_schemas.cards import (
+    CardOut,
+    CardSearchQuery,
+    CardSearchResult,
+    SetSearchQuery,
+    SetSearchResult,
+)
+from slab_schemas.community import CommunityBoard
+from slab_schemas.collection import (
+    BreakCreate,
+    BreakOut,
+    BreakSearchQuery,
+    BreakSearchResult,
+    BreakUpdate,
+    LotCreate,
+    LotOut,
+    LotSearchQuery,
+    LotSearchResult,
+    LotUpdate,
+    CardCopyCostCreate,
+    CardCopyCostOut,
+    CardCopyCostUpdate,
+    CardCopyCreate,
+    CardCopyOut,
+    CardCopyUpdate,
+    CollectionResult,
+    CollectionSearchQuery,
+    CollectorCreate,
+    CollectorOut,
+    CollectorUpdate,
+)
+from slab_schemas.custom_sets import (
+    CustomSetCardAdd,
+    CustomSetCardOut,
+    CustomSetCreate,
+    CustomSetDetail,
+    CustomSetOut,
+    CustomSetSearchQuery,
+    CustomSetSearchResult,
+    CustomSetUpdate,
+)
+from slab_schemas.dashboard import CatalogStats, DashboardStats
+from slab_schemas.pricing import CardComps, CardMarket, SetTopCards
+from slab_schemas.sealed import SealedMarket, SealedPriceHistory, SealedProductOut
+from slab_schemas.timeseries import CardPriceHistory, PortfolioHistory
+
+
+class ApiError(Exception):
+    """An error returned by the API (4xx/5xx)."""
+
+    def __init__(self, status: int, detail: str):
+        self.status = status
+        self.detail = detail
+        super().__init__(f"[{status}] {detail}")
+
+
+class ApiConnectionError(Exception):
+    """Cannot reach the API."""
+
+    def __init__(self, url: str, reason: str):
+        self.url = url
+        super().__init__(f"Cannot connect to {url}: {reason}")
+
+
+class SlabClient:
+    """Typed client for the slab API."""
+
+    def __init__(self, base_url: str, api_key: str | None = None):
+        headers = {}
+        if api_key:
+            headers["x-api-key"] = api_key
+        self._base_url = base_url
+        self._http = httpx.Client(base_url=base_url, headers=headers, timeout=30)
+
+    def _request(self, method: str, path: str, **kwargs) -> httpx.Response:
+        try:
+            resp = self._http.request(method, path, **kwargs)
+        except httpx.ConnectError:
+            raise ApiConnectionError(self._base_url, "connection refused — is the API running?")
+        except httpx.TimeoutException:
+            raise ApiConnectionError(self._base_url, "request timed out")
+        except httpx.HTTPError as e:
+            raise ApiConnectionError(self._base_url, str(e))
+
+        if resp.status_code >= 400:
+            detail = resp.text
+            try:
+                body = resp.json()
+                if isinstance(body, dict) and "detail" in body:
+                    detail = body["detail"]
+            except Exception:
+                pass
+            raise ApiError(resp.status_code, detail)
+        return resp
+
+    # --- catalog ---
+
+    def search_cards(self, query: CardSearchQuery) -> CardSearchResult:
+        resp = self._request("POST", "/cards/search", json=query.model_dump(mode="json", exclude_none=True))
+        return CardSearchResult.model_validate(resp.json())
+
+    def get_parallels(self, card_uuid: str) -> list[CardOut]:
+        resp = self._request("GET", f"/cards/{card_uuid}/parallels")
+        return [CardOut.model_validate(c) for c in resp.json()]
+
+    def get_card_market(self, card_uuid: str) -> CardMarket:
+        resp = self._request("GET", f"/cards/{card_uuid}/market")
+        return CardMarket.model_validate(resp.json())
+
+    def get_card_comps(
+        self, card_uuid: str, grade_key: str | None = None, limit: int = 50
+    ) -> CardComps:
+        params: dict[str, str] = {"limit": str(limit)}
+        if grade_key:
+            params["grade_key"] = grade_key
+        resp = self._request("GET", f"/cards/{card_uuid}/comps", params=params)
+        return CardComps.model_validate(resp.json())
+
+    def get_card_price_history(
+        self,
+        card_uuid: str,
+        grade_key: str = "RAW",
+        finish: str | None = None,
+        start: str | None = None,
+        end: str | None = None,
+        interval: str = "daily",
+    ) -> CardPriceHistory:
+        params: dict[str, str] = {"grade_key": grade_key, "interval": interval}
+        if finish:
+            params["finish"] = finish
+        if start:
+            params["start"] = start
+        if end:
+            params["end"] = end
+        resp = self._request("GET", f"/cards/{card_uuid}/price-history", params=params)
+        return CardPriceHistory.model_validate(resp.json())
+
+    def get_portfolio_history(
+        self,
+        collector_uuid: str,
+        start: str | None = None,
+        end: str | None = None,
+        interval: str = "daily",
+    ) -> PortfolioHistory:
+        params: dict[str, str] = {"interval": interval}
+        if start:
+            params["start"] = start
+        if end:
+            params["end"] = end
+        resp = self._request("GET", f"/collectors/{collector_uuid}/portfolio/history", params=params)
+        return PortfolioHistory.model_validate(resp.json())
+
+    def search_sets(self, query: SetSearchQuery) -> SetSearchResult:
+        resp = self._request("POST", "/sets/search", json=query.model_dump(mode="json", exclude_none=True))
+        return SetSearchResult.model_validate(resp.json())
+
+    # --- sealed / set market ---
+
+    def get_set_sealed(self, set_uuid: str) -> list[SealedProductOut]:
+        """The set's sealed SKUs, each with its headline (latest) market value."""
+        resp = self._request("GET", f"/sets/{set_uuid}/sealed")
+        return [SealedProductOut.model_validate(p) for p in resp.json()]
+
+    def get_set_top_cards(self, set_uuid: str, limit: int = 10) -> SetTopCards:
+        resp = self._request("GET", f"/sets/{set_uuid}/top-cards", params={"limit": str(limit)})
+        return SetTopCards.model_validate(resp.json())
+
+    def get_sealed_market(self, product_uuid: str, comps_limit: int = 25) -> SealedMarket:
+        resp = self._request(
+            "GET", f"/sealed/{product_uuid}/market", params={"comps_limit": str(comps_limit)}
+        )
+        return SealedMarket.model_validate(resp.json())
+
+    def get_sealed_price_history(
+        self,
+        product_uuid: str,
+        start: str | None = None,
+        end: str | None = None,
+        interval: str = "daily",
+    ) -> SealedPriceHistory:
+        params: dict[str, str] = {"interval": interval}
+        if start:
+            params["start"] = start
+        if end:
+            params["end"] = end
+        resp = self._request("GET", f"/sealed/{product_uuid}/price-history", params=params)
+        return SealedPriceHistory.model_validate(resp.json())
+
+    # --- account / identity ---
+
+    def get_account_context(self) -> MeOut:
+        """Resolve the account behind this API key — its collectors and default collector. Used to
+        pick a default collector when SLAB_COLLECTOR is unset."""
+        resp = self._request("GET", "/account")
+        return MeOut.model_validate(resp.json())
+
+    # --- collectors ---
+
+    def create_collector(self, name: str) -> CollectorOut:
+        resp = self._request("POST", "/collectors", json=CollectorCreate(name=name).model_dump(mode="json"))
+        return CollectorOut.model_validate(resp.json())
+
+    def rename_collector(self, collector_uuid: str, name: str) -> CollectorOut:
+        resp = self._request(
+            "PATCH", f"/collectors/{collector_uuid}", json=CollectorUpdate(name=name).model_dump(mode="json")
+        )
+        return CollectorOut.model_validate(resp.json())
+
+    # --- breaks ---
+
+    def create_break(self, collector_uuid: str, payload: BreakCreate) -> BreakOut:
+        resp = self._request(
+            "POST", f"/collectors/{collector_uuid}/breaks", json=payload.model_dump(mode="json", exclude_none=True)
+        )
+        return BreakOut.model_validate(resp.json())
+
+    def search_breaks(self, collector_uuid: str, query: BreakSearchQuery | None = None) -> BreakSearchResult:
+        body = (query or BreakSearchQuery()).model_dump(mode="json", exclude_none=True)
+        resp = self._request("POST", f"/collectors/{collector_uuid}/breaks/search", json=body)
+        return BreakSearchResult.model_validate(resp.json())
+
+    def update_break(self, collector_uuid: str, break_uuid: str, payload: BreakUpdate) -> BreakOut:
+        resp = self._request(
+            "PATCH",
+            f"/collectors/{collector_uuid}/breaks/{break_uuid}",
+            json=payload.model_dump(mode="json", exclude_unset=True),
+        )
+        return BreakOut.model_validate(resp.json())
+
+    def delete_break(self, collector_uuid: str, break_uuid: str) -> None:
+        self._request("DELETE", f"/collectors/{collector_uuid}/breaks/{break_uuid}")
+
+    # --- lots (a single multi-card purchase) ---
+
+    def create_lot(self, collector_uuid: str, payload: LotCreate) -> LotOut:
+        resp = self._request(
+            "POST", f"/collectors/{collector_uuid}/lots", json=payload.model_dump(mode="json", exclude_none=True)
+        )
+        return LotOut.model_validate(resp.json())
+
+    def search_lots(self, collector_uuid: str, query: LotSearchQuery | None = None) -> LotSearchResult:
+        body = (query or LotSearchQuery()).model_dump(mode="json", exclude_none=True)
+        resp = self._request("POST", f"/collectors/{collector_uuid}/lots/search", json=body)
+        return LotSearchResult.model_validate(resp.json())
+
+    def update_lot(self, collector_uuid: str, lot_uuid: str, payload: LotUpdate) -> LotOut:
+        resp = self._request(
+            "PATCH",
+            f"/collectors/{collector_uuid}/lots/{lot_uuid}",
+            json=payload.model_dump(mode="json", exclude_unset=True),
+        )
+        return LotOut.model_validate(resp.json())
+
+    def delete_lot(self, collector_uuid: str, lot_uuid: str) -> None:
+        self._request("DELETE", f"/collectors/{collector_uuid}/lots/{lot_uuid}")
+
+    # --- copies ---
+
+    def add_copy(self, collector_uuid: str, payload: CardCopyCreate) -> CardCopyOut:
+        resp = self._request(
+            "POST", f"/collectors/{collector_uuid}/copies", json=payload.model_dump(mode="json", exclude_none=True)
+        )
+        return CardCopyOut.model_validate(resp.json())
+
+    def update_copy(self, collector_uuid: str, copy_uuid: str, payload: CardCopyUpdate) -> CardCopyOut:
+        resp = self._request(
+            "PATCH",
+            f"/collectors/{collector_uuid}/copies/{copy_uuid}",
+            json=payload.model_dump(mode="json", exclude_unset=True),
+        )
+        return CardCopyOut.model_validate(resp.json())
+
+    def delete_copy(self, collector_uuid: str, copy_uuid: str) -> None:
+        self._request("DELETE", f"/collectors/{collector_uuid}/copies/{copy_uuid}")
+
+    # --- collection search ---
+
+    def search_collection(self, collector_uuid: str, query: CollectionSearchQuery | None = None) -> CollectionResult:
+        body = (query or CollectionSearchQuery()).model_dump(mode="json", exclude_none=True)
+        resp = self._request("POST", f"/collectors/{collector_uuid}/collection/search", json=body)
+        return CollectionResult.model_validate(resp.json())
+
+    # --- costs ---
+
+    def add_cost(self, collector_uuid: str, copy_uuid: str, payload: CardCopyCostCreate) -> CardCopyCostOut:
+        resp = self._request(
+            "POST",
+            f"/collectors/{collector_uuid}/copies/{copy_uuid}/costs",
+            json=payload.model_dump(mode="json", exclude_none=True),
+        )
+        return CardCopyCostOut.model_validate(resp.json())
+
+    def update_cost(
+        self, collector_uuid: str, copy_uuid: str, cost_uuid: str, payload: CardCopyCostUpdate
+    ) -> CardCopyCostOut:
+        resp = self._request(
+            "PATCH",
+            f"/collectors/{collector_uuid}/copies/{copy_uuid}/costs/{cost_uuid}",
+            json=payload.model_dump(mode="json", exclude_unset=True),
+        )
+        return CardCopyCostOut.model_validate(resp.json())
+
+    def delete_cost(self, collector_uuid: str, copy_uuid: str, cost_uuid: str) -> None:
+        self._request("DELETE", f"/collectors/{collector_uuid}/copies/{copy_uuid}/costs/{cost_uuid}")
+
+    # --- dashboards ---
+
+    def get_dashboard(self, collector_uuid: str) -> DashboardStats:
+        resp = self._request("GET", f"/collectors/{collector_uuid}/dashboard")
+        return DashboardStats.model_validate(resp.json())
+
+    def get_sources(self, collector_uuid: str) -> list[str]:
+        """Distinct acquisition sources this collector has used (breaks + copies)."""
+        resp = self._request("GET", f"/collectors/{collector_uuid}/sources")
+        return resp.json()
+
+    def get_catalog_stats(self) -> CatalogStats:
+        resp = self._request("GET", "/stats")
+        return CatalogStats.model_validate(resp.json())
+
+    def get_community_board(self, limit: int = 10) -> CommunityBoard:
+        resp = self._request("GET", "/community", params={"limit": limit})
+        return CommunityBoard.model_validate(resp.json())
+
+    # --- custom sets (collector-scoped) ---
+
+    def create_custom_set(self, collector_uuid: str, payload: CustomSetCreate) -> CustomSetOut:
+        resp = self._request(
+            "POST", f"/collectors/{collector_uuid}/custom-sets", json=payload.model_dump(mode="json", exclude_none=True)
+        )
+        return CustomSetOut.model_validate(resp.json())
+
+    def update_custom_set(self, collector_uuid: str, set_uuid: str, payload: CustomSetUpdate) -> CustomSetOut:
+        resp = self._request(
+            "PATCH",
+            f"/collectors/{collector_uuid}/custom-sets/{set_uuid}",
+            json=payload.model_dump(mode="json", exclude_unset=True),
+        )
+        return CustomSetOut.model_validate(resp.json())
+
+    def delete_custom_set(self, collector_uuid: str, set_uuid: str) -> None:
+        self._request("DELETE", f"/collectors/{collector_uuid}/custom-sets/{set_uuid}")
+
+    def add_set_card(self, collector_uuid: str, set_uuid: str, payload: CustomSetCardAdd) -> CustomSetCardOut:
+        resp = self._request(
+            "POST",
+            f"/collectors/{collector_uuid}/custom-sets/{set_uuid}/cards",
+            json=payload.model_dump(mode="json", exclude_none=True),
+        )
+        return CustomSetCardOut.model_validate(resp.json())
+
+    def delete_set_card(self, collector_uuid: str, set_uuid: str, entry_uuid: str) -> None:
+        self._request("DELETE", f"/collectors/{collector_uuid}/custom-sets/{set_uuid}/cards/{entry_uuid}")
+
+    def subscribe(self, collector_uuid: str, set_uuid: str) -> None:
+        self._request("POST", f"/collectors/{collector_uuid}/custom-sets/{set_uuid}/subscribe")
+
+    def unsubscribe(self, collector_uuid: str, set_uuid: str) -> None:
+        self._request("DELETE", f"/collectors/{collector_uuid}/custom-sets/{set_uuid}/subscribe")
+
+    def collector_custom_sets(self, collector_uuid: str) -> list[CustomSetOut]:
+        resp = self._request("GET", f"/collectors/{collector_uuid}/custom-sets")
+        return [CustomSetOut.model_validate(s) for s in resp.json()]
+
+    # --- custom sets (unscoped — discovery/viewing) ---
+
+    def search_custom_sets(self, query: CustomSetSearchQuery | None = None) -> CustomSetSearchResult:
+        body = (query or CustomSetSearchQuery()).model_dump(mode="json", exclude_none=True)
+        resp = self._request("POST", "/custom-sets/search", json=body)
+        return CustomSetSearchResult.model_validate(resp.json())
+
+    def get_custom_set(self, set_uuid: str, collector_uuid: str | None = None) -> CustomSetDetail:
+        params = {"collector_uuid": collector_uuid} if collector_uuid else {}
+        resp = self._request("GET", f"/custom-sets/{set_uuid}", params=params)
+        return CustomSetDetail.model_validate(resp.json())

slab_cli-0.1.0/src/slab_cli/commands/__init__.py

@@ -0,0 +1,4 @@
+"""Command implementations, split by domain.
+
+The command SURFACE (what maps to what) lives in `registry.py` — the single source of truth that
+drives both dispatch and the help screens. These modules hold the handlers it points at."""