slab-cli 0.23.0__tar.gz → 0.25.0__tar.gz

{slab_cli-0.23.0 → slab_cli-0.25.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.3
 Name: slab-cli
-Version: 0.23.0
+Version: 0.25.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.36.0
+Requires-Dist: slab-schemas>=0.46.0
 Requires-Dist: httpx>=0.27
 Requires-Dist: rich>=13.0
 Requires-Dist: inquirerpy>=0.3

{slab_cli-0.23.0 → slab_cli-0.25.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "slab-cli"
-version = "0.23.0"
+version = "0.25.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"}]
@@ -12,7 +12,7 @@ dependencies = [
     # 0.34 reframes the grading desk from verdicts to break-even readings (BreakEvenRegion,
     # GradingDesk.break_even) — the desk shows data, never tells the user to grade.
     # 0.35 adds Liquidity/LiquidityLabel, which the market view's Sells column renders.
-    "slab-schemas>=0.36.0",
+    "slab-schemas>=0.46.0",  # metrics registry: served momentum/trend labels
     "httpx>=0.27",
     "rich>=13.0",
     "InquirerPy>=0.3",

{slab_cli-0.23.0 → slab_cli-0.25.0}/src/slab_cli/client.py

@@ -17,6 +17,7 @@ from slab_schemas.cards import (
     SetSearchResult,
 )
 from slab_schemas.community import CommunityBoard
+from slab_schemas.serials import CardSerials
 from slab_schemas.collection import (
     BreakCreate,
     BreakOut,
@@ -26,16 +27,17 @@ from slab_schemas.collection import (
     LotOut,
     LotSearchQuery,
     LotSearchResult,
-    LotUpdate,
     CardCopyCostCreate,
     CardCopyCostOut,
     CardCopyCostUpdate,
     CardCopyCreate,
     CardCopyOut,
     CardCopyUpdate,
+    CollectionGroupQuery,
     CollectionResult,
     CollectionSearchQuery,
     CollectorOut,
+    SetGroupResult,
 )
 from slab_schemas.custom_sets import (
     CustomSetCardAdd,
@@ -48,11 +50,12 @@ from slab_schemas.custom_sets import (
     CustomSetSearchResult,
     CustomSetUpdate,
 )
-from slab_schemas.dashboard import CatalogStats, DashboardStats
+from slab_schemas.dashboard import DashboardStats
 from slab_schemas.grading_desk import CollectionGradingDesk, GradingDesk
 from slab_schemas.pricing import CardComps, CardMarket, SetTopCards
 from slab_schemas.sealed import SealedPriceHistory, SealedProductOut
 from slab_schemas.timeseries import CardPriceHistory
+from slab_schemas.vocab import VocabOut
 
 
 class ApiError(Exception):
@@ -81,6 +84,8 @@ class SlabClient:
             headers["x-api-key"] = api_key
         self._base_url = base_url
         self._http = httpx.Client(base_url=base_url, headers=headers, timeout=30)
+        self._vocab: VocabOut | None = None
+        self._vocab_fetched = False
 
     def _request(self, method: str, path: str, **kwargs) -> httpx.Response:
         try:
@@ -151,6 +156,12 @@ class SlabClient:
         )
         return CollectionGradingDesk.model_validate(resp.json())
 
+    def get_card_serials(self, card_uuid: str) -> CardSerials:
+        """Which numbered copies of this printing have surfaced — sales with a stated serial and
+        collection copies — grouped by serial (GET /cards/{uuid}/serials)."""
+        resp = self._request("GET", f"/cards/{card_uuid}/serials")
+        return CardSerials.model_validate(resp.json())
+
     def get_card_price_history(
         self,
         card_uuid: str,
@@ -200,6 +211,29 @@ class SlabClient:
         resp = self._request("GET", f"/sealed/{product_uuid}/price-history", params=params)
         return SealedPriceHistory.model_validate(resp.json())
 
+    # --- vocabulary (public) ---
+
+    def get_vocab(self) -> VocabOut:
+        """Every enumerable value the API accepts or serves — wire enums, sort grammars, and the
+        LIVE catalog dimensions (grading companies, attributes) that grow as sets are seeded.
+        Raises like any other call; `vocab()` is the forgiving, cached form pickers use."""
+        resp = self._request("GET", "/vocab")
+        return VocabOut.model_validate(resp.json())
+
+    def vocab(self) -> VocabOut | None:
+        """The served vocabulary, fetched at most ONCE per process and None when the API can't
+        answer (offline, unauthorized, down). Same contract as the portal's `getVocab()`: a
+        picker renders the served list when it has one and its static fallback otherwise, so a
+        new grading company reaches the CLI with no release — and a dead API never blocks a
+        prompt. The miss is cached too, so one failure doesn't retry at every prompt."""
+        if not self._vocab_fetched:
+            self._vocab_fetched = True
+            try:
+                self._vocab = self.get_vocab()
+            except (ApiError, ApiConnectionError):
+                self._vocab = None
+        return self._vocab
+
     # --- account / identity ---
 
     def get_account_context(self) -> MeOut:
@@ -237,14 +271,6 @@ class SlabClient:
         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}")
 
@@ -274,6 +300,17 @@ class SlabClient:
         resp = self._request("POST", f"/collectors/{collector_uuid}/collection/search", json=body)
         return CollectionResult.model_validate(resp.json())
 
+    def collection_sets(
+        self, collector_uuid: str, query: CollectionGroupQuery | None = None
+    ) -> SetGroupResult:
+        """The collection rolled up by set — the SERVER's per-set math (copies, distinct cards,
+        total value), ranked most valuable first and paged over groups, so a set is never split
+        across a page. This is the number the portfolio view renders per set; the CLI must not
+        re-derive it from copies (cli/AGENTS.md, "Served numbers, not client math")."""
+        body = (query or CollectionGroupQuery()).model_dump(mode="json", exclude_none=True)
+        resp = self._request("POST", f"/collectors/{collector_uuid}/collection/sets", json=body)
+        return SetGroupResult.model_validate(resp.json())
+
     # --- costs ---
 
     def add_cost(self, collector_uuid: str, copy_uuid: str, payload: CardCopyCostCreate) -> CardCopyCostOut:
@@ -308,10 +345,6 @@ class SlabClient:
         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())

{slab_cli-0.23.0 → slab_cli-0.25.0}/src/slab_cli/commands/pricing.py

@@ -2,10 +2,13 @@
 
 from __future__ import annotations
 
-from slab_schemas.cards import SetSearchQuery
-from slab_schemas.collection import CollectionSearchQuery, PortfolioSummary
-
-from slab_schemas.cards import CardOut, SetOut
+from slab_schemas.cards import CardOut, SetOut, SetSearchQuery
+from slab_schemas.collection import (
+    CollectionGroupQuery,
+    CollectionSearchQuery,
+    PortfolioSummary,
+    SetGroupOut,
+)
 
 from ..context import MissingCollector, ctx
 from ..display import (
@@ -17,6 +20,7 @@ from ..display import (
     render_portfolio,
     render_price_history,
     render_sealed_price_history,
+    render_serials,
     render_set_market,
 )
 from ..paging import fetch_all_pages
@@ -71,6 +75,17 @@ def cmd_comps(args: list[str]) -> None:
     render_comps(ctx.client.get_card_comps(card.uuid))
 
 
+def cmd_serials(args: list[str]) -> None:
+    """Which numbered copies of a card have surfaced. Same player → set → card flow as `price`,
+    then one row per serial seen: how many collections hold it, how many times it has sold, and
+    its last sale. Sales and held copies are shown apart — the collector who bought #24 on eBay
+    is one transfer seen from both sides. Unnumbered printings say so and stop."""
+    card = _pick_card(args)
+    if card is None:
+        return
+    render_serials(ctx.client.get_card_serials(card.uuid))
+
+
 def _split_desk_flags(args: list[str]) -> tuple[list[str], float | None, str | None]:
     """Pull `--fee <amount>` and `--company <name>` out of a grading query. Hand-rolled (the
     shared flag grammar is search-specific); an unparseable fee errors loudly rather than
@@ -116,57 +131,34 @@ def cmd_grade_sweep(args: list[str]) -> None:
     )
 
 
-def _fetch_all_copies(page: int = 200, cap: int = 5000) -> tuple[list, PortfolioSummary | None]:
-    """Page through the whole collection for the per-set/mover/break breakdowns, and grab the
-    server's summary block (full-result aggregates, identical on every page) from the first page —
-    that's the source of truth for grand totals. `cap` is a safety bound so a runaway collection
-    can't spin forever."""
-    copies, first = fetch_all_pages(
-        lambda limit, offset: ctx.client.search_collection(
-            ctx.collector, CollectionSearchQuery(sort="-unrealized", limit=limit, offset=offset)
+# How many top movers the portfolio view lists, and the page it reads them from: the server's
+# `-unrealized` sort puts the biggest paper gains first (unpriced copies have no gain and sort
+# last), so one page is the whole answer — no need to pull every copy to find the top ten.
+_MOVERS_SHOWN = 10
+_MOVERS_PAGE = 25
+
+
+def _fetch_set_groups(page: int = 200, cap: int = 2000) -> list[SetGroupOut]:
+    """Every set the collection holds from, as the server's grouped rollup — copies, distinct
+    cards, and total value per set, most valuable first. Pages over GROUPS (a set is never split
+    across a page boundary) as headers only (`include_copies=False`); `cap` bounds the paging if a
+    collection somehow spans thousands of products."""
+    groups, _ = fetch_all_pages(
+        lambda limit, offset: ctx.client.collection_sets(
+            ctx.collector,
+            CollectionGroupQuery(
+                group_sort="-value", include_copies=False, limit=limit, offset=offset
+            ),
         ),
         page=page,
         cap=cap,
     )
-    return copies, (first.summary if first else None)
-
-
-def _aggregate_by_set(copies: list) -> list[dict]:
-    """Roll copies up per set, mirroring the server's headline math so the parts reconcile with the
-    whole: cost basis is summed per-copy, FMV is quantity-weighted, comp coverage is copy-weighted."""
-    sets: dict[str, dict] = {}
-    for cp in copies:
-        card = cp.card
-        name = (card.set_name if card else None) or "— Unknown set —"
-        s = sets.setdefault(name, {
-            "name": name, "copies": 0, "total_qty": 0, "priced_qty": 0,
-            "cost_basis": 0.0, "fmv": 0.0, "has_fmv": False,
-        })
-        qty = cp.quantity or 1
-        s["copies"] += 1
-        s["total_qty"] += qty
-        if cp.cost_basis is not None:
-            s["cost_basis"] += float(cp.cost_basis)
-        if cp.market and cp.market.fair_market_value is not None:
-            s["fmv"] += float(cp.market.fair_market_value) * qty
-            s["priced_qty"] += qty
-            s["has_fmv"] = True
-
-    for s in sets.values():
-        s["unrealized"] = (s["fmv"] - s["cost_basis"]) if s["has_fmv"] else None
-        s["comp_pct"] = (s["priced_qty"] / s["total_qty"] * 100) if s["total_qty"] else 0.0
-
-    # Most valuable first; sets with no market data sink to the bottom (sorted by cost basis).
-    return sorted(
-        sets.values(),
-        key=lambda s: (s["has_fmv"], s["fmv"] if s["has_fmv"] else s["cost_basis"]),
-        reverse=True,
-    )
+    return groups
 
 
 def _portfolio_totals(summary: PortfolioSummary) -> dict:
     """Grand totals for the valuation panel, straight from the server's summary block — the same
-    math the dashboard shows, so the two never diverge."""
+    numbers `GET .../dashboard` serves, so the two never diverge."""
     fmv = summary.portfolio_value
     return {
         "cost_basis": float(summary.total_cost_basis or 0),
@@ -181,67 +173,33 @@ def _portfolio_totals(summary: PortfolioSummary) -> dict:
     }
 
 
-def _most_valuable_break(copies: list, breaks: list) -> dict | None:
-    """The break whose pulled copies carry the most market value — did opening that box pay off?
-    FMV is summed from the copies we already priced; cost/metadata comes from the breaks list."""
-    fmv_by_break: dict[str, float] = {}
-    priced_by_break: dict[str, int] = {}
-    for cp in copies:
-        if cp.break_uuid and cp.market and cp.market.fair_market_value is not None:
-            qty = cp.quantity or 1
-            fmv_by_break[cp.break_uuid] = (
-                fmv_by_break.get(cp.break_uuid, 0.0) + float(cp.market.fair_market_value) * qty
-            )
-            priced_by_break[cp.break_uuid] = priced_by_break.get(cp.break_uuid, 0) + qty
-
-    if not fmv_by_break:
-        return None
-
-    top_uuid = max(fmv_by_break, key=fmv_by_break.get)
-    brk = next((b for b in breaks if b.uuid == top_uuid), None)
-    if brk is None:
-        return None
-
-    cost = float(brk.total_cost)
-    fmv = fmv_by_break[top_uuid]
-    return {
-        "set_name": brk.set_name or "— Unknown set —",
-        "break_type": brk.break_type,
-        "break_date": brk.break_date,
-        "cost": cost,
-        "fmv": fmv,
-        "gain": fmv - cost,
-        "copy_count": brk.copy_count,
-        "priced": priced_by_break.get(top_uuid, 0),
-    }
-
-
 def cmd_portfolio(args: list[str]) -> None:
-    """Portfolio-level financial summary — cost basis vs market value, per-set stats, top movers."""
-    copies, summary = _fetch_all_copies()
-    if not copies:
+    """Portfolio-level financial summary — cost basis vs market value, the per-set rollup, and
+    the top movers — every number as the SERVER computed it. Grand totals are the response's
+    `summary` block (the dashboard's math), the per-set table is `POST .../collection/sets`, and
+    the movers are the first page of the `-unrealized` sort. Nothing is re-derived from copies:
+    the old per-set client math paged a capped 5,000 copies and summed them, which both duplicated
+    the dashboard's definitions and went quietly wrong past the cap."""
+    page = ctx.client.search_collection(
+        ctx.collector, CollectionSearchQuery(sort="-unrealized", limit=_MOVERS_PAGE)
+    )
+    if not page.items:
         console.print("[dim]No cards in your collection yet.[/dim]")
         return
-    if summary is None:
+    if page.summary is None:
         # The API always includes the summary block; its absence is a server bug — say so
         # rather than invent numbers client-side.
         console.print("[red]Server response had no portfolio summary — can't value the collection.[/red]")
         return
 
-    by_set = _aggregate_by_set(copies)
-    totals = _portfolio_totals(summary)
-
-    # Top movers: copies with real unrealized P&L, biggest gain first (already sorted by the fetch).
+    # Top movers: copies with real unrealized P&L, biggest gain first (the server's sort).
     movers = [
-        cp for cp in copies
+        cp for cp in page.items
         if cp.market and cp.market.unrealized_gain_loss is not None
-    ][:10] or None
-
-    breaks = ctx.client.search_breaks(ctx.collector).items
-    mvb = _most_valuable_break(copies, breaks)
+    ][:_MOVERS_SHOWN] or None
 
     render_portfolio(
-        len(copies), totals, movers=movers, by_set=by_set, most_valuable_break=mvb
+        page.total, _portfolio_totals(page.summary), movers=movers, by_set=_fetch_set_groups()
     )
 
 

{slab_cli-0.23.0 → slab_cli-0.25.0}/src/slab_cli/commands/registry.py

@@ -61,6 +61,7 @@ GROUPS: list[Group] = [
         Command("price", "Market price + 7d/30d trend", pricing.cmd_price, "<query>"),
         Command("grade", "The grading math: payoffs per grade + break-even", pricing.cmd_grade, "<query> [--fee N]"),
         Command("comps", "Recent raw sales behind the price", pricing.cmd_comps, "<query>"),
+        Command("serials", "Which numbered copies have surfaced (sales + collections)", pricing.cmd_serials, "<query>"),
         Command("history", "Price history over time", pricing.cmd_history, "<query>"),
     ]),
     Group("set", "browse and price sealed products", [
@@ -79,7 +80,7 @@ GROUPS: list[Group] = [
         Command("cost", "Log a cost (grading, shipping) on a copy", collection.cmd_cost),
         Command("export", "Export a set to a printable checklist", export.cmd_export),
         Command("dashboard", "Overview: counts, value, composition", collection.cmd_dashboard),
-        Command("portfolio", "Portfolio: cost basis vs FMV + top movers", pricing.cmd_portfolio),
+        Command("portfolio", "Portfolio: cost basis vs FMV, by set, top movers", pricing.cmd_portfolio),
         Command("grade", "Grading math for every raw copy, best upside first", pricing.cmd_grade_sweep, "[--fee N]"),
     ]),
     Group("break", "case / box breaks", [

{slab_cli-0.23.0 → slab_cli-0.25.0}/src/slab_cli/display.py

@@ -6,7 +6,7 @@ from rich.console import Group
 from rich.text import Text
 
 from slab_schemas.cards import CardOut, CardSearchResult, SetOut, SetSearchResult
-from slab_schemas.collection import BreakSearchResult, CollectionResult, LotSearchResult
+from slab_schemas.collection import BreakSearchResult, CollectionResult, LotSearchResult, SetGroupOut
 from slab_schemas.community import (
     CollectedCard,
     CollectedPlayer,
@@ -22,8 +22,10 @@ from slab_schemas.dashboard import CatalogStats, DashboardStats, HighlightCard,
 from slab_schemas.grading_desk import CollectionGradingDesk, GradingDesk
 from slab_schemas.enums import BreakEvenRegion, Grade, LiquidityLabel, SealedFormat
 from slab_schemas.liquidity import Liquidity
+from slab_schemas.metrics import momentum_label, trend_label
 from slab_schemas.pricing import CardComps, CardMarket, PortfolioSummary, SetTopCards
 from slab_schemas.sealed import SealedPriceHistory, SealedProductOut
+from slab_schemas.serials import CardSerials
 from slab_schemas.timeseries import CardPriceHistory
 
 from .browse import Page, browse
@@ -504,10 +506,29 @@ def _pull_table(pulls) -> object:
     return table
 
 
+# A break's or lot's "worth today" is CLIENT math: FMV summed over the copies in the response.
+# There is no server number for it (the API prices copies, not containers), so this is the one
+# place the CLI adds market values up itself — and it says exactly what it added, from this ONE
+# string, on both report cards. It must never read as the dashboard's portfolio math: that is
+# as-of, full-collection, and served (`cli/AGENTS.md`, "Served numbers, not client math").
+PAGE_NET_SCOPE = "priced copies on this page only; unpriced count as $0"
+
+
+def _net_scope_line(result: CollectionResult, unpriced: int) -> str:
+    """The honest footnote under a break/lot money line: what the total covers and what it skips."""
+    parts = [f"Worth today = {PAGE_NET_SCOPE}"]
+    if unpriced:
+        parts.append(f"{unpriced} unpriced here, so the real total can only be higher")
+    if result.total > len(result.items):
+        parts.append(f"{len(result.items)} of {result.total} copies shown")
+    return f"  [slab.dim]{' · '.join(parts)}.[/]"
+
+
 def render_break_pulls(brk, result: CollectionResult) -> None:
     """A break's report card: what you paid vs what the pulls are worth today, then the most
     valuable pulls and the rarest (lowest print run). Every number in plain words — this view
-    answers "did the box pay for itself?" at a glance."""
+    answers "did the box pay for itself?" at a glance. "Worth today" is summed here from the
+    page's priced copies (`PAGE_NET_SCOPE`), and labeled so."""
     console.print()
     t = Text()
     t.append(brk.set_name or "Break", style="slab.value")
@@ -534,9 +555,7 @@ def render_break_pulls(brk, result: CollectionResult) -> None:
         f"\n  You paid [slab.value]{money(brk.total_cost)}[/] · your {len(result.items)} pulls are "
         f"worth [slab.foil]{money(total_fmv)}[/] today → {signed_money(net)} — {verdict}."
     )
-    if unpriced:
-        console.print(f"  [slab.dim]{unpriced} pull(s) have no market price yet and count as $0 here — "
-                      f"the real total can only be higher.[/]")
+    console.print(_net_scope_line(result, unpriced))
 
     top = sorted(priced, key=_fmv, reverse=True)[:10]
     if top:
@@ -588,7 +607,7 @@ def browse_lots(result: LotSearchResult, *, detail=None) -> None:
 def render_lot_contents(lot, result: CollectionResult) -> None:
     """A purchase's report card: what you paid vs what the cards are worth today, then the most
     valuable and rarest cards in it. Answers "did that bundle come out ahead?" at a glance — the
-    lot counterpart of `render_break_pulls`."""
+    lot counterpart of `render_break_pulls`, same `PAGE_NET_SCOPE` label on its total."""
     console.print()
     t = Text()
     t.append(f"Purchase {lot.uuid[:8]}", style="slab.value")
@@ -613,9 +632,7 @@ def render_lot_contents(lot, result: CollectionResult) -> None:
         f"\n  You paid [slab.value]{money(lot.total_cost)}[/] · its {len(result.items)} cards are "
         f"worth [slab.foil]{money(total_fmv)}[/] today → {signed_money(net)} — {verdict}."
     )
-    if unpriced:
-        console.print(f"  [slab.dim]{unpriced} card(s) have no market price yet and count as $0 here — "
-                      f"the real total can only be higher.[/]")
+    console.print(_net_scope_line(result, unpriced))
 
     top = sorted(priced, key=_fmv, reverse=True)[:10]
     if top:
@@ -865,26 +882,39 @@ def _collected_players_table(entries: list[CollectedPlayer]) -> Group | None:
     return titled("Most Collected Players", table)
 
 
-def _hot_momentum(cur: int, prev: int) -> str:
-    """The window-over-window badge in plain terms: 'new' (was silent), ×N up, ×N down, or steady."""
-    if prev == 0:
+# The hottest-players badges render the label the SERVER computed (`HotPlayer.momentum` /
+# `HotPlayer.trend`). The thresholds that turn a ratio into "up" are the API's metric
+# definitions (`slab_schemas.metrics`), not the CLI's to copy: three clients once each carried
+# their own ±2% band and disagreed. When an older server omits the fields, the fallback is the
+# registry's own functions, imported — the same rule, never a restated literal.
+# `tests/test_hot_labels.py` asserts no threshold number lives in this module.
+
+
+def _hot_momentum(e: HotPlayer) -> str:
+    """The window-over-window badge in plain terms: 'new' (was silent), ×N up, ×N down, or steady.
+    The label is served; the ×N beside it is the served counts' ratio, shown for scale."""
+    cur, prev = e.sales_30d, e.sales_prev_30d
+    label = e.momentum or momentum_label(cur, prev)
+    if label == "new":
         return "[slab.accent]new[/]"
-    ratio = cur / prev
-    if ratio >= 1.5:
-        return f"[slab.accent]↑{ratio:.1f}×[/]"
-    if ratio <= 0.67:
+    if label == "up":
+        return f"[slab.accent]↑{cur / prev:.1f}×[/]" if prev else "[slab.accent]↑[/]"
+    if label == "down":
         return f"[slab.dim]↓{prev / cur:.1f}×[/]" if cur else "[slab.dim]↓[/]"
     return "[slab.dim]steady[/]"
 
 
-def _hot_trend(pct: float | None) -> str:
-    """Price direction arrow — how to tell a breakout (selling up) from a sell-off (selling down)."""
-    if pct is None:
+def _hot_trend(e: HotPlayer) -> str:
+    """Price direction arrow — how to tell a breakout (selling up) from a sell-off (selling down).
+    The direction is served; the percent beside it is the served `price_trend_pct`."""
+    pct = e.price_trend_pct
+    label = e.trend or trend_label(pct)
+    if pct is None or label is None:
         return "[slab.dim]—[/]"
-    if pct > 2:
-        return f"[slab.gain]↗ +{pct:.0f}%[/]"
-    if pct < -2:
-        return f"[slab.loss]↘ {pct:.0f}%[/]"
+    if label == "up":
+        return f"[slab.gain]↗ {pct:+.0f}%[/]"
+    if label == "down":
+        return f"[slab.loss]↘ {pct:+.0f}%[/]"
     return f"[slab.dim]→ {pct:+.0f}%[/]"
 
 
@@ -903,10 +933,10 @@ def _hottest_players_table(entries: list[HotPlayer]) -> Group | None:
         table.add_row(
             e.name,
             str(e.sales_30d),
-            _hot_momentum(e.sales_30d, e.sales_prev_30d),
+            _hot_momentum(e),
             money(e.dollar_volume_30d),
             str(e.distinct_cards_30d),
-            _hot_trend(e.price_trend_pct),
+            _hot_trend(e),
         )
     return titled("🔥 Hottest Players", table)
 
@@ -1254,6 +1284,51 @@ def render_set_market(s: SetOut, sealed: list[SealedProductOut], top: SetTopCard
     console.print("  [slab.dim]Drill in with `slab card price` / `slab card comps`.[/]\n")
 
 
+def render_serials(s: CardSerials) -> None:
+    """Which numbered copies of a printing have surfaced — one row per serial, sales and held
+    copies kept apart (the same transfer can be seen from both sides). The meaning text comes
+    from the response's glossary, so the CLI, the site and the API say the same words."""
+    subjects = ", ".join(s.subjects) or "—"
+    console.print()
+    console.print(_card_headline(s.card_number, subjects, s.set_name, _slot(s)))
+
+    if not s.print_run:
+        console.print("\n  [slab.dim]This printing isn't serial-numbered, so there are no serials to track.[/]\n")
+        return
+
+    unseen = max(0, s.print_run - s.serials_seen)
+    pct = f" ({s.coverage_pct:.0f}%)" if s.coverage_pct is not None else ""
+    console.print(heading("Serials Seen", f"{s.serials_seen} of /{s.print_run}{pct} · {unseen} never surfaced"))
+    if not s.serials:
+        console.print("  [slab.dim]No numbered copy of this card has surfaced in a sale or a collection yet.[/]\n")
+        return
+
+    table = slab_table([
+        ("Serial", {"justify": "right", "style": "slab.foil"}),
+        ("Held", {"justify": "right"}),
+        ("Sales", {"justify": "right"}),
+        ("Last sale", {"justify": "right", "style": "slab.foil"}),
+        ("Grade", {"style": "slab.dim"}),
+        ("Last seen", {"style": "slab.dim"}),
+    ])
+    for sig in s.serials:
+        last = sig.sales[-1] if sig.sales else None
+        table.add_row(
+            f"{sig.serial_number}/{s.print_run}",
+            str(sig.held) if sig.held else "[slab.dim]—[/]",
+            str(len(sig.sales)) if sig.sales else "[slab.dim]—[/]",
+            money(last.sale_price) if last and last.sale_price is not None else "—",
+            (last.grade_key or "—") if last else "—",
+            sig.last_seen.isoformat() if sig.last_seen else "—",
+        )
+    console.print(table)
+    for key in ("serials.coverage", "serials.held"):
+        info = s.glossary.get(key)
+        if info:
+            console.print(f"  [slab.dim]{info.label}: {info.summary}[/]")
+    console.print()
+
+
 def render_comps(c: CardComps) -> None:
     """Display recent comps (raw sales) for a catalog card — the evidence behind its FMV."""
     subjects = ", ".join(c.subjects) or "—"
@@ -1442,67 +1517,41 @@ def render_collection_grading_desk(sweep: CollectionGradingDesk) -> None:
     console.print()
 
 
-def _render_portfolio_by_set(by_set: list | None) -> None:
-    """Per-set breakdown, most valuable first. Highlights the top set and shows comp coverage."""
+def _render_portfolio_by_set(by_set: list[SetGroupOut] | None) -> None:
+    """Per-set breakdown straight from the server's grouped rollup (`POST .../collection/sets`):
+    copies held, distinct cards, and what they're worth, most valuable first. Only SERVED columns —
+    there is no per-set cost basis, gain, or comps coverage here because the API computes none,
+    and a client-side version was a second, drifting definition of the dashboard's math (it
+    summed a capped page of copies and called it the set)."""
     if not by_set:
         return
 
     table = slab_table([
         ("Set", {"style": "slab.value", "no_wrap": False}),
+        ("Copies", {"justify": "right", "style": "slab.dim"}),
         ("Cards", {"justify": "right", "style": "slab.dim"}),
-        ("Cost Basis", {"justify": "right"}),
-        ("FMV", {"justify": "right"}),
-        ("Gain/Loss", {"justify": "right"}),
-        ("Comps", {"justify": "right"}),
+        ("Value", {"justify": "right"}),
     ])
 
-    for i, st in enumerate(by_set):
-        # crown the single most valuable set
-        name = f"[slab.foil]★[/] {st['name']}" if i == 0 and st["has_fmv"] else st["name"]
-        cards = f"{st['total_qty']:,}"
-        basis = money(st["cost_basis"])
-        fmv = f"[slab.foil]{money(st['fmv'])}[/]" if st["has_fmv"] else "[slab.dim]—[/]"
-        gain = signed_money(st["unrealized"])
-        comps = pct_coverage(st["comp_pct"])
+    for i, g in enumerate(by_set):
+        # crown the single most valuable set (the server ranks by value; a None value is unpriced)
+        name = f"[slab.foil]★[/] {g.name}" if i == 0 and g.total_value is not None else g.name
+        value = f"[slab.foil]{money(g.total_value)}[/]" if g.total_value is not None else "[slab.dim]—[/]"
+        table.add_row(name, f"{g.copy_count:,}", f"{g.card_count:,}", value)
 
-        table.add_row(name, cards, basis, fmv, gain, comps)
-
-    console.print(heading("By Set", "most valuable first"))
+    console.print(heading("By Set", "most valuable first · unpriced copies add nothing to Value"))
     console.print(table)
 
 
-def _render_most_valuable_break(mvb: dict | None) -> None:
-    """Highlight the single break whose pulled cards carry the most market value — did it pay off?"""
-    if not mvb:
-        return
-
-    date_str = f"  ·  {mvb['break_date']}" if mvb.get("break_date") else ""
-    title = Text()
-    title.append(mvb["set_name"], style="slab.value")
-    title.append(f"   {mvb['break_type'].replace('_', ' ')}{date_str}", style="slab.dim")
-
-    g = mvb["gain"]
-    verdict = "paid off" if g >= 0 else "underwater"
-    roi = f"  [slab.dim]({'+' if g >= 0 else '-'}{abs(g) / mvb['cost'] * 100:.0f}%)[/]" if mvb["cost"] else ""
-
-    body = kv_grid([
-        ("Cost", f"{money(mvb['cost'])}  [slab.dim]({_n(mvb['copy_count'], 'card')})[/]"),
-        ("Market Value", f"[slab.foil]{money(mvb['fmv'])}[/]  [slab.dim]({mvb['priced']} priced)[/]"),
-        ("Net vs Cost", f"{signed_money(g)}{roi}  [slab.dim]· {verdict}[/]"),
-    ])
-
-    console.print(heading("Most Valuable Break"))
-    console.print(slab_panel(Group(title, Text(""), body), foil=True))
-
-
 def render_portfolio(
-    total: int, totals: dict, movers: list | None = None, by_set: list | None = None,
-    most_valuable_break: dict | None = None,
+    total: int, totals: dict, movers: list | None = None, by_set: list[SetGroupOut] | None = None,
 ) -> None:
-    """Display portfolio-level financial summary, per-set breakdown, and optional top movers.
+    """Display portfolio-level financial summary, the per-set rollup, and optional top movers.
 
-    `totals` is the grand-total dict (cost_basis, fmv, unrealized, roi, priced_qty, total_qty)
-    built from the server's PortfolioSummary — see `_portfolio_totals`."""
+    Every number here is one the server computed: `totals` is the grand-total dict (cost_basis,
+    fmv, unrealized, roi, priced_qty, total_qty) built from the response's `PortfolioSummary`
+    (see `_portfolio_totals`), `by_set` is the served `SetGroupOut` rollup, and `movers` is the
+    first page of the server's `-unrealized` sort."""
     rows: list[tuple[str, str]] = [("Cost Basis", money(totals["cost_basis"]))]
 
     if totals["fmv"] is not None:
@@ -1529,7 +1578,6 @@ def render_portfolio(
     console.print(slab_panel(kv_grid(rows), foil=True))
 
     _render_portfolio_by_set(by_set)
-    _render_most_valuable_break(most_valuable_break)
 
     # Top movers
     if movers:

{slab_cli-0.23.0 → slab_cli-0.25.0}/src/slab_cli/prompts.py

@@ -12,6 +12,7 @@ from typing import Protocol
 
 from InquirerPy.base.control import Choice
 
+from .context import ctx
 from .nav import inquirer  # the nav proxy: every prompt gains Esc=back / Ctrl-C=quit
 
 from slab_schemas.cards import CardOut, SetOut, SetSearchResult
@@ -435,22 +436,69 @@ def select_grade(message: str = "Your grade assessment:") -> str | None:
     return inquirer.select(message=message, choices=choices, max_height="70%").execute()
 
 
+# ---------------------------------------------------------------------------
+# Served-vocab pickers
+# ---------------------------------------------------------------------------
+# These lists come from GET /vocab when the API answers and fall back to the literals below when it
+# doesn't — the portal's `getVocab()` pattern (portal/src/lib/vocab.ts). Grading companies are LIVE
+# catalog rows (a new one appears when a set is seeded), and the wire enums can grow in a schemas
+# release the installed CLI predates; either way the served list is the truth and the fallback is
+# only what this build knew. The label maps are the human wording for the values we know about; an
+# unknown served value still renders (title-cased) rather than being silently dropped.
+
+_GRADING_COMPANY_FALLBACK = ["PSA", "BGS", "SGC", "CGC"]
+_GRADING_COMPANY_LABELS = {"BGS": "BGS (Beckett)"}
+
+_MATCH_MODE_FALLBACK = ["exact", "any_printing", "exact_serial"]
+_MATCH_MODE_LABELS = {
+    "exact": "Exact — this specific printing (parallel/finish)",
+    "any_printing": "Any printing — any version of this card slot",
+    "exact_serial": "Exact serial — this card with a specific serial number",
+}
+
+_VISIBILITY_FALLBACK = ["private", "public"]
+_VISIBILITY_LABELS = {
+    "private": "Private — only you can see it",
+    "public": "Public — any collector can find and subscribe",
+}
+
+
+def vocab_values(
+    field: str, fallback: list[str], vocab=None, *, exclude: frozenset[str] = frozenset()
+) -> list[str]:
+    """The served list for one vocab field, else `fallback`. Pure: pass `vocab` (a VocabOut, or
+    None for "the API didn't answer") to test it; the pickers pass the client's cached one. A
+    served list that is empty (a catalog with no grading companies yet) also falls back, so a
+    prompt never renders with nothing to pick. `exclude` drops values this picker must not offer
+    because another flow owns them (applied to served and fallback alike)."""
+    values = getattr(vocab, field, None) if vocab is not None else None
+    chosen = list(values) if values else list(fallback)
+    return [v for v in chosen if v not in exclude]
+
+
+def _served_choices(
+    field: str, fallback: list[str], labels: dict[str, str], exclude: frozenset[str] = frozenset()
+) -> list[Choice]:
+    values = vocab_values(field, fallback, ctx.client.vocab(), exclude=exclude)
+    return [Choice(value=v, name=labels.get(v) or v.replace("_", " ").title()) for v in values]
+
+
 def select_grading_company() -> str:
-    choices = [
-        Choice(value="PSA", name="PSA"),
-        Choice(value="BGS", name="BGS (Beckett)"),
-        Choice(value="SGC", name="SGC"),
-        Choice(value="CGC", name="CGC"),
-    ]
+    choices = _served_choices("grading_companies", _GRADING_COMPANY_FALLBACK, _GRADING_COMPANY_LABELS)
     return inquirer.select(message="Grading company:", choices=choices).execute()
 
 
+# `any_card` is a PLAYER slot, not a way to match a card: both callers of select_match_mode are
+# tuning a CARD entry, and the player rung is reached through `select_entry_kind` instead. So it
+# is excluded from this picker however the list arrives — offering it here would send a card entry
+# with a subject-shaped mode.
+_CARD_ENTRY_MODE_EXCLUDE = frozenset({"any_card"})
+
+
 def select_match_mode() -> str:
-    choices = [
-        Choice(value="exact", name="Exact — this specific printing (parallel/finish)"),
-        Choice(value="any_printing", name="Any printing — any version of this card slot"),
-        Choice(value="exact_serial", name="Exact serial — this card with a specific serial number"),
-    ]
+    choices = _served_choices(
+        "match_modes", _MATCH_MODE_FALLBACK, _MATCH_MODE_LABELS, exclude=_CARD_ENTRY_MODE_EXCLUDE
+    )
     return inquirer.select(message="Match mode:", choices=choices).execute()
 
 
@@ -464,10 +512,7 @@ def select_entry_kind() -> str:
 
 
 def select_visibility() -> str:
-    choices = [
-        Choice(value="private", name="Private — only you can see it"),
-        Choice(value="public", name="Public — any collector can find and subscribe"),
-    ]
+    choices = _served_choices("visibilities", _VISIBILITY_FALLBACK, _VISIBILITY_LABELS)
     return inquirer.select(message="Visibility:", choices=choices).execute()
 
 

{slab_cli-0.23.0 → slab_cli-0.25.0}/src/slab_cli/theme.py

@@ -16,6 +16,8 @@ Building block cheat-sheet:
 
 from __future__ import annotations
 
+import math
+
 from rich import box
 from rich.console import Console, Group, RenderableType
 from rich.panel import Panel
@@ -148,9 +150,15 @@ def signed_money(v) -> str:
 
 
 def pct_coverage(pct: float) -> str:
-    """A coverage/health percentage, colored by band: green ≥75, gold ≥40, red below."""
-    color = "slab.gain" if pct >= 75 else ("slab.foil" if pct >= 40 else "slab.loss")
-    return f"[{color}]{pct:.0f}%[/]"
+    """A coverage/health percentage, colored by band: green ≥75, gold ≥40, red below.
+
+    The ratio itself is two served counts (e.g. `priced_count / card_count`), so the only thing a
+    client decides is the rounding — and it must round the way the frontend does (`Math.round`,
+    half UP: 62.5 → 63), not Python's `format(..., '.0f')` (half to EVEN: 62.5 → 62), or the two
+    clients print different percentages for the same set. `floor(x + 0.5)` is `Math.round`."""
+    shown = math.floor(pct + 0.5)
+    color = "slab.gain" if shown >= 75 else ("slab.foil" if shown >= 40 else "slab.loss")
+    return f"[{color}]{shown}%[/]"
 
 
 _SPARK_TICKS = "▁▂▃▄▅▆▇█"