slab-cli 0.1.0__py3-none-any.whl

slab_cli/prompts.py

@@ -0,0 +1,549 @@
+"""Interactive prompts built on InquirerPy — arrow-key selects, fuzzy search, confirmations.
+
+Each function returns the user's choice. Functions suffixed with `_optional` allow skipping
+(empty input = None). Functions without that suffix loop until valid input is provided."""
+
+from __future__ import annotations
+
+from collections import Counter
+from datetime import date
+from decimal import Decimal, InvalidOperation
+
+from InquirerPy import inquirer
+from InquirerPy.base.control import Choice
+
+from slab_schemas.cards import CardOut, SetOut, SetSearchResult
+from slab_schemas.collection import (
+    BreakOut,
+    BreakSearchResult,
+    CardCopyCostOut,
+    CardCopyOut,
+    LotOut,
+    LotSearchResult,
+)
+from slab_schemas.enums import GRADE_ORDINAL, AcquisitionType, BreakType, Grade
+
+from .theme import console as _console
+
+
+# ---------------------------------------------------------------------------
+# Label builders (for select menus)
+# ---------------------------------------------------------------------------
+
+def _slot(c: CardOut) -> str:
+    """The card's line: its subset, plus the parallel finish when it has one. 'Base' shows only
+    when the subset is literally Base — a no-finish INSERT shows its insert name, not 'Base'
+    (id_finish NULL means 'base printing of this line', not 'the base set')."""
+    return (c.subset or "?") + (f" · {c.finish}" if c.finish else "")
+
+
+def _card_label(c: CardOut) -> str:
+    subjects = ", ".join(s.name for s in c.subjects)
+    pr = f" /{c.print_run}" if c.print_run else ""
+    attrs = f" [{', '.join(a.name for a in c.attributes)}]" if c.attributes else ""
+    return f"{c.card_number}  {subjects} — {c.set_name} — {_slot(c)}{pr}{attrs}"
+
+
+def _set_label(s: SetOut) -> str:
+    return f"{s.brand} {s.name} ({s.season or '—'})  [{s.card_count or 0} cards]"
+
+
+def _break_label(b: BreakOut) -> str:
+    # Lead with the open date so identical products are distinguishable; short uuid guarantees it.
+    when = b.break_date.isoformat() if b.break_date else "—"
+    src = f" · {b.source}" if b.source else ""
+    cpc = f" @ ${b.cost_per_card:.2f}/card" if b.cost_per_card else ""
+    return (f"{when} · {b.set_name} · {b.break_type} · ${b.total_cost:.2f}{src} · "
+            f"{b.copy_count} cards{cpc}  [{b.uuid[:8]}]")
+
+
+def _lot_label(lot: LotOut) -> str:
+    # Lead with the purchase date so identical-value lots are distinguishable; short uuid guarantees it.
+    when = lot.lot_date.isoformat() if lot.lot_date else "—"
+    src = f" · {lot.source}" if lot.source else ""
+    cpc = f" @ ${lot.cost_per_card:.2f}/card" if lot.cost_per_card else ""
+    return (f"{when} · ${lot.total_cost:.2f}{src} · {lot.copy_count} cards{cpc}  [{lot.uuid[:8]}]")
+
+
+def _copy_label(cp: CardCopyOut) -> str:
+    card = cp.card
+    if card:
+        subjects = ", ".join(s.name for s in card.subjects)
+        grade = f" {cp.grading_company} {cp.grade}" if cp.grading_company else ""
+        serial = f" #{cp.serial_number}" if cp.serial_number else ""
+        basis = f" [${cp.cost_basis:.2f}]" if cp.cost_basis is not None else ""
+        return f"{card.card_number}  {subjects} — {card.set_name} — {_slot(card)}{grade}{serial}{basis}"
+    return f"Copy {cp.uuid[:8]}"
+
+
+# ---------------------------------------------------------------------------
+# Select prompts (arrow-key navigation)
+# ---------------------------------------------------------------------------
+
+def select_subject(cards: list[CardOut]) -> str | None:
+    """Subject-first step 1: from a card search, pick the player. Auto-selects when only one
+    player matches; otherwise type-to-filter among the distinct players (with card counts)."""
+    counts: Counter[str] = Counter()
+    for c in cards:
+        for s in c.subjects:
+            counts[s.name] += 1
+    if not counts:
+        return None
+    if len(counts) == 1:
+        return next(iter(counts))
+    choices = [Choice(value=name, name=f"{name}  ({n})") for name, n in sorted(counts.items())]
+    return inquirer.fuzzy(
+        message=f"Which player? ({len(counts)} found — type to filter):",
+        choices=choices,
+        max_height="70%",
+    ).execute()
+
+
+def select_printing_for_slot(printings: list[CardOut]) -> CardOut | None:
+    """Break-fill step: given the full rainbow of one checklist slot (base first, then every
+    parallel — the output of `get_parallels`), pick the exact printing you pulled. Defaults to
+    the base printing, so the common case is a single Enter; pick a parallel only when you pulled
+    one. Auto-selects when the slot has no parallels."""
+    if not printings:
+        return None
+    if len(printings) == 1:
+        return printings[0]
+
+    def label(c: CardOut) -> str:
+        pr = f" /{c.print_run}" if c.print_run else ""
+        attrs = f" [{', '.join(a.name for a in c.attributes)}]" if c.attributes else ""
+        name = "Base" if not c.finish else c.finish
+        return f"{name}{pr}{attrs}"
+
+    # Base first (id_finish NULL → no finish) is already the server order; make it the default.
+    choices = [Choice(value=c, name=label(c)) for c in printings]
+    return inquirer.select(
+        message="Which printing did you pull?",
+        choices=choices,
+        default=choices[0].value,
+        max_height="70%",
+    ).execute()
+
+
+def walk_prompt(card: CardOut, position: tuple[int, int]) -> tuple[str, str | None]:
+    """One step of the checklist walk. Prints the slot, then reads a single compact control:
+    Enter = skip to next, y = add this one, a card number = jump to it, q = quit.
+    Returns one of ("skip", None), ("add", None), ("quit", None), ("jump", <typed value>)."""
+    idx, total = position
+    subjects = ", ".join(s.name for s in card.subjects) or "—"
+    slot = (card.subset or "?") + (f" · {card.finish}" if card.finish else "")
+    owned = f"  [green]● owned x{card.owned_quantity}[/green]" if card.owned_quantity else ""
+    _console.print(f"\n[dim]{idx}/{total}[/dim]  [bold]#{card.card_number}[/bold]  {subjects} · {slot}{owned}")
+    val = inquirer.text(message="[y]es · [Enter] skip · #=jump · [q]uit:", default="").execute()
+    v = (val or "").strip()
+    if not v:
+        return ("skip", None)
+    low = v.lower()
+    if low in ("y", "yes"):
+        return ("add", None)
+    if low in ("q", "quit"):
+        return ("quit", None)
+    return ("jump", v)
+
+
+def select_printing(cards: list[CardOut], subject: str, show_set: bool = False) -> CardOut | None:
+    """Subject-first step 2: pick the exact card for the chosen player — any printing (base,
+    parallel, insert, auto). Auto-selects when there's only one. `show_set` prepends the set name
+    to each row — used when the list spans multiple sets (e.g. the player wasn't narrowed to one
+    set), so you can tell a 2023-24 Young Guns from a 2024-25 one at a glance."""
+    if not cards:
+        return None
+    if len(cards) == 1:
+        return cards[0]
+
+    def label(c: CardOut) -> str:
+        pr = f" /{c.print_run}" if c.print_run else ""
+        upd = f" ({c.season} update)" if c.release_set_slug else ""
+        attrs = f" [{', '.join(a.name for a in c.attributes)}]" if c.attributes else ""
+        others = [s.name for s in c.subjects if s.name != subject]
+        co = f" + {', '.join(others)}" if others else ""
+        setp = f"{c.set_name} — " if show_set else ""
+        return f"{setp}#{c.card_number}{co} — {_slot(c)}{pr}{upd}{attrs}"
+
+    choices = [Choice(value=c, name=label(c)) for c in cards]
+    return inquirer.fuzzy(
+        message=f"Which card? — {subject} ({len(cards)} printings — type to filter):",
+        choices=choices,
+        max_height="70%",
+    ).execute()
+
+
+def select_set(sets: list[SetOut], initial: str | None = None) -> SetOut | None:
+    """Pick one set from the catalog — fuzzy type-to-filter, pre-seeded with the user's query so
+    the closest names surface immediately (backspace to widen). Auto-selects a lone match;
+    Ctrl-C backs out."""
+    if not sets:
+        return None
+    if len(sets) == 1:
+        return sets[0]
+    ranked = sorted(sets, key=lambda s: (-(s.year or 0), s.name or ""))  # newest first
+    choices = [Choice(value=s, name=_set_label(s)) for s in ranked]
+    return inquirer.fuzzy(
+        message=f"Which set? ({len(sets)} in catalog — type to filter):",
+        choices=choices,
+        default=initial or "",
+        max_height="70%",
+    ).execute()
+
+
+def select_set_filter(cards: list[CardOut]) -> str | None:
+    """Price step 2: narrow the player's cards to one set, or keep all. Returns a set slug, or
+    "" for all sets. Auto-returns "" when every card is from the same set (nothing to choose)."""
+    sets: dict[str, tuple[str, int]] = {}
+    for c in cards:
+        if not c.set_slug:
+            continue
+        name, n = sets.get(c.set_slug, (c.set_name or c.set_slug, 0))
+        sets[c.set_slug] = (name, n + 1)
+    if len(sets) <= 1:
+        return ""
+    ranked = sorted(sets.items(), key=lambda kv: (-kv[1][1], kv[1][0]))
+    choices = [Choice(value="", name=f"★ All sets  ({len(cards)} cards)")]
+    choices += [Choice(value=slug, name=f"{name}  ({n})") for slug, (name, n) in ranked]
+    return inquirer.fuzzy(
+        message=f"Which set? ({len(sets)} found — type to filter):",
+        choices=choices,
+        max_height="70%",
+    ).execute()
+
+
+def select_priced_card(cards: list[CardOut], subject: str, show_set: bool) -> CardOut | None:
+    """Price step 3: the card list — each row shows its FMV (● = you own it) so values are visible
+    before drilling in. Selecting a row returns its card for the full market view. Auto-selects a
+    lone card. `show_set` includes the set name (used when viewing across all sets)."""
+    if not cards:
+        return None
+    if len(cards) == 1:
+        return cards[0]
+
+    def label(c: CardOut) -> str:
+        pr = f" /{c.print_run}" if c.print_run else ""
+        attrs = f" [{', '.join(a.name for a in c.attributes)}]" if c.attributes else ""
+        others = [s.name for s in c.subjects if s.name != subject]
+        co = f" + {', '.join(others)}" if others else ""
+        setp = f" — {c.set_name}" if show_set else ""
+        # FMV column: value + low-confidence marker + grade bucket when not RAW.
+        if c.market is not None:
+            conf = "*" if c.market.low_confidence else ""
+            gk = "" if c.market.grade_key == "RAW" else f" {c.market.grade_key}"
+            fmv = f"${c.market.fair_market_value:,.2f}{conf}{gk}"
+        else:
+            fmv = "no comps"
+        own = f"  ● x{c.owned_quantity}" if c.owned_quantity else ""
+        return f"#{c.card_number}{co}{setp} — {_slot(c)}{pr}{attrs}   {fmv}{own}"
+
+    choices = [Choice(value=c, name=label(c)) for c in cards]
+    return inquirer.fuzzy(
+        message=f"{subject} — {len(cards)} cards (● = owned; select for full market):",
+        choices=choices,
+        max_height="70%",
+    ).execute()
+
+
+def select_search_set(result: SetSearchResult) -> SetOut | None:
+    """Pick one set from a bounded search result (arrow-key select). Distinct from `select_set`,
+    which fuzzy-filters the whole catalog list — this one is for an already-narrowed search."""
+    if not result.items:
+        return None
+    choices = [Choice(value=s, name=_set_label(s)) for s in result.items]
+    return inquirer.select(
+        message=f"Select a set ({result.total} found):",
+        choices=choices,
+        max_height="70%",
+    ).execute()
+
+
+def select_owned_set(sets: list[tuple[str, str, int]], total: int) -> str:
+    """Pick a set to export from the sets the collector actually owns cards in. Fuzzy — arrow keys
+    plus type-to-filter, so you never have to know the exact set name. `sets` = [(slug, name, count)]
+    sorted by the caller. Returns a set slug, or "" for the whole collection."""
+    choices = [Choice(value="", name=f"★ Whole collection  ({total} cards)")]
+    choices += [Choice(value=slug, name=f"{name}  ({count})") for slug, name, count in sets]
+    return inquirer.fuzzy(
+        message="Export which set?",
+        choices=choices,
+        max_height="70%",
+    ).execute()
+
+
+def select_copy(items: list[CardCopyOut], message: str = "Select a copy:") -> CardCopyOut | None:
+    """Arrow-key select from collection results."""
+    if not items:
+        return None
+    choices = [Choice(value=cp, name=_copy_label(cp)) for cp in items]
+    return inquirer.select(
+        message=message,
+        choices=choices,
+        max_height="70%",
+    ).execute()
+
+
+def select_break(result: BreakSearchResult, allow_new: bool = True) -> BreakOut | str | None:
+    """Select a break. Returns a BreakOut, the string "new" if user wants to create, or None."""
+    choices = [Choice(value=b, name=_break_label(b)) for b in result.items]
+    if allow_new:
+        choices.append(Choice(value="new", name="+ Create a new break"))
+    choices.append(Choice(value=None, name="Skip (no break)"))
+    return inquirer.select(
+        message="Select a break:",
+        choices=choices,
+        max_height="70%",
+    ).execute()
+
+
+def select_lot(result: LotSearchResult, allow_new: bool = True) -> LotOut | str | None:
+    """Select a purchase lot. Returns a LotOut, the string "new" to create one, or None to skip."""
+    choices = [Choice(value=lot, name=_lot_label(lot)) for lot in result.items]
+    if allow_new:
+        choices.append(Choice(value="new", name="+ Create a new purchase"))
+    choices.append(Choice(value=None, name="Skip (no purchase lot)"))
+    return inquirer.select(
+        message="Select a purchase:",
+        choices=choices,
+        max_height="70%",
+    ).execute()
+
+
+# Sentinel VALUE for "enter a new source". A string compared by ==, deliberately NOT `object()`
+# checked by `is`: InquirerPy deep-copies choice values internally, so an object() sentinel comes
+# back as a different instance, fails the identity check, and leaks raw into the payload (real
+# crash: BreakCreate(source=<object object>) pydantic ValidationError).
+_NEW_SOURCE = "__slab_new_source__"
+
+
+def select_source(known: list[str]) -> str | None:
+    """Pick a previously-used source with arrow keys, or enter a new one. Empty/skip = None.
+
+    With no prior sources it degrades to a plain text prompt, so the first break behaves as before."""
+    if not known:
+        return ask_text_optional("Source (e.g. eBay, LCS — enter to skip):")
+    choices = [Choice(value=s, name=s) for s in known]
+    choices.append(Choice(value=_NEW_SOURCE, name="+ Enter a new source"))
+    choices.append(Choice(value=None, name="Skip (no source)"))
+    picked = inquirer.select(
+        message="Source (↑↓ to reuse, or add new):",
+        choices=choices,
+        max_height="70%",
+    ).execute()
+    if picked == _NEW_SOURCE:
+        return ask_text_optional("New source (enter to skip):")
+    return picked
+
+
+# Human-friendly blurbs for the enum members. The VALUE SET always comes from the schema enum (so a
+# new member reaches the CLI automatically); these only supply nicer labels, with a title-cased
+# fallback for any member not listed here.
+_ACQUISITION_LABELS: dict[AcquisitionType, str] = {
+    AcquisitionType.purchase: "Purchase — bought the card",
+    AcquisitionType.pack_pull: "Pack pull — from a break",
+    AcquisitionType.trade: "Trade",
+    AcquisitionType.gift: "Gift",
+    AcquisitionType.other: "Other",
+}
+
+_BREAK_TYPE_LABELS: dict[BreakType, str] = {
+    BreakType.pack: "Pack",
+    BreakType.box: "Box",
+    BreakType.case: "Case",
+    BreakType.other: "Other",
+}
+
+# The 1-10 rung display names. Ordering and ordinals come from GRADE_ORDINAL, not from here.
+_GRADE_LABELS: dict[Grade, str] = {
+    Grade.gem_mint: "Gem Mint",
+    Grade.mint: "Mint",
+    Grade.near_mint_mint: "Near Mint-Mint",
+    Grade.near_mint: "Near Mint",
+    Grade.excellent_mint: "Excellent-Mint",
+    Grade.excellent: "Excellent",
+    Grade.very_good_excellent: "Very Good-Excellent",
+    Grade.very_good: "Very Good",
+    Grade.good: "Good",
+    Grade.poor: "Poor",
+}
+
+
+def _enum_label(member, labels: dict) -> str:
+    """A member's display label, falling back to a title-cased name so a newly-added enum member is
+    still selectable (never silently dropped from the menu)."""
+    return labels.get(member) or member.value.replace("_", " ").title()
+
+
+def select_acquisition_type() -> str:
+    choices = [Choice(value=t.value, name=_enum_label(t, _ACQUISITION_LABELS)) for t in AcquisitionType]
+    return inquirer.select(message="How did you acquire this card?", choices=choices).execute()
+
+
+def select_break_type() -> str:
+    choices = [Choice(value=t.value, name=_enum_label(t, _BREAK_TYPE_LABELS)) for t in BreakType]
+    return inquirer.select(message="What did you open?", choices=choices).execute()
+
+
+def select_grade(message: str = "Your grade assessment:") -> str | None:
+    """Self-assessed condition on the shared 1-10 rung scale. Returns the Grade enum value
+    (e.g. "NM-MT") or None if skipped. Rungs and their 1-10 positions come from the schema's
+    Grade + GRADE_ORDINAL, so a new rung reaches the CLI automatically; listed best-first."""
+    rungs = sorted(Grade, key=lambda g: GRADE_ORDINAL.get(g, 0), reverse=True)
+    choices = []
+    for g in rungs:
+        ordinal = GRADE_ORDINAL.get(g)
+        label = _enum_label(g, _GRADE_LABELS)
+        name = f"{label} ({ordinal})" if ordinal is not None else label
+        choices.append(Choice(value=g.value, name=name))
+    choices.append(Choice(value=None, name="Skip / unsure"))
+    return inquirer.select(message=message, choices=choices, max_height="70%").execute()
+
+
+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"),
+    ]
+    return inquirer.select(message="Grading company:", choices=choices).execute()
+
+
+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"),
+    ]
+    return inquirer.select(message="Match mode:", choices=choices).execute()
+
+
+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"),
+    ]
+    return inquirer.select(message="Visibility:", choices=choices).execute()
+
+
+def select_custom_set_type() -> str:
+    choices = [
+        Choice(value="curated", name="Curated — hand-pick specific cards"),
+        Choice(value="dynamic", name="Dynamic — defined by a search filter (auto-updates)"),
+    ]
+    return inquirer.select(message="Set type:", choices=choices).execute()
+
+
+def select_cost_category() -> str:
+    choices = [
+        Choice(value="grading", name="Grading fee"),
+        Choice(value="shipping", name="Shipping"),
+        Choice(value="insurance", name="Insurance"),
+        Choice(value="authentication", name="Authentication"),
+        Choice(value="other", name="Other"),
+    ]
+    return inquirer.select(message="Cost type:", choices=choices).execute()
+
+
+def select_cost_action() -> str | None:
+    """On a copy that already has costs: add a new one, edit one, or delete one. None = cancel."""
+    choices = [
+        Choice(value="add", name="Add a new cost"),
+        Choice(value="edit", name="Edit an existing cost"),
+        Choice(value="delete", name="Delete a cost"),
+        Choice(value=None, name="Cancel"),
+    ]
+    return inquirer.select(message="What would you like to do?", choices=choices).execute()
+
+
+def select_cost_entry(costs: list[CardCopyCostOut], message: str = "Select a cost:") -> CardCopyCostOut | None:
+    """Pick one entry from a copy's cost ledger."""
+    if not costs:
+        return None
+    choices = []
+    for c in costs:
+        extra = f" · {c.vendor}" if c.vendor else ""
+        when = f" · {c.incurred_date}" if c.incurred_date else ""
+        choices.append(Choice(value=c, name=f"{c.cost_category}  ${c.amount:.2f}{extra}{when}"))
+    return inquirer.select(message=message, choices=choices, max_height="70%").execute()
+
+
+# ---------------------------------------------------------------------------
+# Text prompts — required (loops until non-empty)
+# ---------------------------------------------------------------------------
+
+def ask_text(message: str) -> str:
+    """Prompt for text input. Loops until the user provides a non-empty value."""
+    while True:
+        val = inquirer.text(message=message).execute()
+        if val and val.strip():
+            return val.strip()
+        _console.print("[yellow]  This field is required.[/yellow]")
+
+
+def ask_decimal(message: str) -> Decimal:
+    """Prompt for a decimal. Loops until valid."""
+    while True:
+        val = inquirer.text(message=message).execute()
+        if not val or not val.strip():
+            _console.print("[yellow]  This field is required.[/yellow]")
+            continue
+        try:
+            return Decimal(val.strip())
+        except InvalidOperation:
+            _console.print("[yellow]  Enter a valid number (e.g. 25.00).[/yellow]")
+
+
+# ---------------------------------------------------------------------------
+# Text prompts — optional (empty = None)
+# ---------------------------------------------------------------------------
+
+def ask_text_optional(message: str) -> str | None:
+    """Prompt for text input. Empty = None (skip)."""
+    val = inquirer.text(message=message, default="").execute()
+    return val.strip() or None
+
+
+def ask_decimal_optional(message: str) -> Decimal | None:
+    """Prompt for a decimal. Empty = None (skip). Invalid input retries."""
+    while True:
+        val = inquirer.text(message=message, default="").execute()
+        if not val or not val.strip():
+            return None
+        try:
+            return Decimal(val.strip())
+        except InvalidOperation:
+            _console.print("[yellow]  Enter a valid number or leave empty to skip.[/yellow]")
+
+
+def ask_int_optional(message: str) -> int | None:
+    """Prompt for an integer. Empty = None (skip). Invalid input retries."""
+    while True:
+        val = inquirer.text(message=message, default="").execute()
+        if not val or not val.strip():
+            return None
+        try:
+            return int(val.strip())
+        except ValueError:
+            _console.print("[yellow]  Enter a whole number or leave empty to skip.[/yellow]")
+
+
+def ask_date(message: str) -> date:
+    """Prompt for a date (YYYY-MM-DD). Empty input defaults to today. Loops until valid."""
+    today = date.today()
+    while True:
+        val = inquirer.text(message=f"{message} (YYYY-MM-DD, enter for {today})", default="").execute()
+        if not val or not val.strip():
+            return today
+        try:
+            return date.fromisoformat(val.strip())
+        except ValueError:
+            _console.print("[yellow]  Enter a date as YYYY-MM-DD, or leave empty for today.[/yellow]")
+
+
+# ---------------------------------------------------------------------------
+# Confirm
+# ---------------------------------------------------------------------------
+
+def confirm(message: str, default: bool = True) -> bool:
+    return inquirer.confirm(message=message, default=default).execute()

slab_cli/sources.py

@@ -0,0 +1,17 @@
+"""Acquisition sources — the collector's growing list of where cards and breaks came from.
+
+One home for "where did this come from?": the reuse-or-type flow the break and copy-add flows share,
+so the source UX is identical everywhere. The distinct-source list is computed server-side
+(``GET /collectors/{id}/sources``, union of break + copy sources); the generic picker UI lives in
+``prompts.select_source`` with its ``select_*`` siblings. This module composes the two."""
+
+from __future__ import annotations
+
+from .client import SlabClient
+from .prompts import select_source
+
+
+def pick_source(client: SlabClient, collector: str) -> str | None:
+    """Fetch the collector's prior sources, then let them reuse one (arrow keys) or enter a new one.
+    None = skipped. The single entry point both the break and copy-add flows call."""
+    return select_source(client.get_sources(collector))