Metadata-Version: 2.4
Name: mgz-pkmn
Version: 1.7.0
Summary: CLI and web app to look up Pokemon cards across open data sources, fetch images and prices, and emit an .xlsx, PDF binder, set-completion checklist, and JSON report for card-show prep.
Project-URL: Homepage, https://mgz-pkmn.com
Project-URL: Repository, https://github.com/mgzwarrior/mgz-pkmn
Project-URL: Issues, https://github.com/mgzwarrior/mgz-pkmn/issues
Project-URL: Documentation, https://github.com/mgzwarrior/mgz-pkmn/tree/main/docs
Author-email: Matt Grant <mattgrant33@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: card-collection,cli,pokemon,pricing,spreadsheet,tcg,trading-cards
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: openpyxl>=3.1
Requires-Dist: pillow>=10.0
Requires-Dist: reportlab>=4.5.1
Requires-Dist: requests>=2.34.2
Provides-Extra: api
Requires-Dist: alembic>=1.13; extra == 'api'
Requires-Dist: authlib>=1.3; extra == 'api'
Requires-Dist: fastapi>=0.136.1; extra == 'api'
Requires-Dist: httpx>=0.28.1; extra == 'api'
Requires-Dist: itsdangerous>=2.2; extra == 'api'
Requires-Dist: python-multipart>=0.0.20; extra == 'api'
Requires-Dist: sqlalchemy>=2.0; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.47.0; extra == 'api'
Description-Content-Type: text/markdown

<h1>
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mgzwarrior/mgz-pkmn/main/assets/logo-dark.svg">
    <img src="https://raw.githubusercontent.com/mgzwarrior/mgz-pkmn/main/assets/logo.svg" alt="mgz-pkmn" height="64">
  </picture>
</h1>

[![CI](https://github.com/mgzwarrior/mgz-pkmn/actions/workflows/ci.yml/badge.svg)](https://github.com/mgzwarrior/mgz-pkmn/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/mgzwarrior/mgz-pkmn/branch/main/graph/badge.svg)](https://codecov.io/gh/mgzwarrior/mgz-pkmn)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)

🌐 **Project site:** <https://mgz-pkmn.com> · 🚀 **Live demo:** <https://mgz-pkmn.onrender.com>

A toolkit for prepping Pokemon card binders for a card show: take a list
of cards, look each one up across **three open data sources**, download
images, and write an `.xlsx` with embedded thumbnails, current market
price, and 80 / 85 / 90 / 95 % negotiation comps. Optional PDF binder,
condensed binder, set-completion checklist, and JSON report alongside.

Two ways to drive it:

- **CLI** — `./pkmn lookup cards.txt` produces xlsx + (optional) PDF +
  JSON; `./pkmn set-cards` emits printable set ID cutouts.
- **Web UI** — FastAPI backend in [api/](api/) and a React + Vite
  frontend in [web/](web/) put the same pipeline behind a live
  in-browser interface with streaming results and one-click export.

The tool tries sources in this order:

1. **[pokemontcg.io]** — primary. Best coverage of English /
   international English releases, with TCGPlayer (USD) + Cardmarket
   (EUR) prices.
2. **[TCGdex]** — multilingual fallback (`en`, `ja`, `ko`, `zh-tw`,
   `zh-cn`, `de`, `fr`, `es`, `it`, `pt`, …). Has Cardmarket prices
   for many cards.
3. **[PriceCharting]** — opt-in via an explicit URL on the line. Ideal
   for region-exclusive products neither aggregator indexes (Chinese
   Gem Pack, etc.). Returns USD loose / new / graded prices.

[pokemontcg.io]: https://pokemontcg.io
[TCGdex]: https://tcgdex.dev
[PriceCharting]: https://www.pricecharting.com

## Install

Requires Python 3.11+ and [`uv`](https://docs.astral.sh/uv/).

```bash
brew install uv                                   # macOS
curl -LsSf https://astral.sh/uv/install.sh | sh   # any platform

make install-cli          # CLI only — fastest
# or
make install              # CLI + API + web + pre-commit hook
```

Run `make help` for the full target list.

## Quickstart

```bash
./pkmn lookup input/ --no-images \
  -o output/cards.xlsx \
  --pdf output/binder.pdf \
  --condensed-pdf output/binder-condensed.pdf \
  --checklist output/checklist.pdf \
  --report-json output/summary.json

./pkmn set-cards -o output/set-cards.pdf   # printable set ID cutouts (no input needed)
```

The bundled [`input/`](input/) directory ships four small example lists
that exercise every input syntax and lookup mode the tool supports —
including [`example-url-overrides.txt`](input/example-url-overrides.txt),
which walks through the "paste a PriceCharting URL once and forget it"
workflow. The tracked files in [`output/`](output/) were generated by
exactly the command above. See the [CLI reference](docs/cli.md#worked-examples)
for the full breakdown.

### API key (optional but recommended)

The pokemontcg.io API works without a key (~1000 requests/day, 30/min)
but a free key raises that to 20k/day. Grab one at
<https://dev.pokemontcg.io>, then set it as an env var:

```bash
export POKEMONTCG_IO_API_KEY=your-key-here          # current shell
echo 'export POKEMONTCG_IO_API_KEY=your-key-here' >> ~/.zshrc   # persistent
```

Prefer the env var over `--api-key` — flags get saved to shell history.

## Environment variables

Every variable the tool reads, in one place:

| Variable | Purpose |
|---|---|
| `POKEMONTCG_IO_API_KEY` | Raises pokemontcg.io rate limits from 1k/day to 20k/day. Free key at <https://dev.pokemontcg.io>. |
| `MGZ_PKMN_NO_CACHE` | Disables the disk cache for the current process. The CLI's `--no-cache` flag sets this internally. |
| `MGZ_PKMN_CACHE_WARN_BYTES` | Threshold for the cache-size soft-warn at startup (default 50 MB, `0` disables). |
| `XDG_CACHE_HOME` | Overrides the cache root (`$XDG_CACHE_HOME/mgz-pkmn`). Standard XDG semantics. |

See [docs/cache.md → Environment variables](docs/cache.md#environment-variables) for the full behavior of the cache-related vars.

## Web UI

```bash
make install         # one-time setup
make dev-api         # Terminal 1 — API on :8000
make dev-web         # Terminal 2 — Vite dev server on :5173
```

Open <http://localhost:5173>. The Vite dev server proxies `/api/*` to
the FastAPI server. Swagger UI lives at <http://localhost:8000/docs>.

Prefer not to install anything? The same UI is hosted at
<https://mgz-pkmn.onrender.com>.

Every matched result — both in the results table and the card detail
view — carries a "Buy" affordance that links out to eBay and TCGPlayer
searches for that exact printing, opening in a new tab. Both are
affiliate-tagged (eBay via its Partner Network, TCGPlayer via an Impact
tracking redirect) and fall back to plain searches when no code is
configured, so they always work.

The hosted demo can sign users in with GitHub, Google, Discord, or an
email magic link when auth is enabled. See
[Deployment](docs/deployment.md#environment-variables) for the provider
credentials, callback URLs, and production session settings. Anonymous
hosted-demo lookups run against the warmed cache only; sign in to let a
cache miss query the live upstream API.

For deeper docs (endpoint reference, troubleshooting, architecture),
see [api/README.md](api/README.md) and [web/README.md](web/README.md).

## License

Released under the [MIT License](LICENSE).

## Documentation

Reference docs live under [`docs/`](docs/) and are mirrored to the
[GitHub Wiki](https://github.com/mgzwarrior/mgz-pkmn/wiki) on every
push to `main`.

| Topic | Page |
|---|---|
| Every flag and `pkmn` invocation pattern | [CLI reference](docs/cli.md) |
| Single-card + bulk `top:N` / `All …` syntax | [Input format](docs/input-format.md) |
| pokemontcg.io / TCGdex / PriceCharting layering | [Sources & coverage](docs/sources.md) |
| Non-English / regional handling | [Languages](docs/languages.md) |
| Spreadsheet + JSON report shape | [Outputs](docs/outputs.md) |
| Standard 3×3 + condensed 6×4 layouts | [PDF binder](docs/binder-pdf.md) |
| Front-of-binder set checklist | [Checklist PDF](docs/checklist.md) |
| Disk cache + URL overrides | [Cache](docs/cache.md) |
| Render / Docker / production recipe | [Deployment](docs/deployment.md) |
| Marketing site (Astro + Tailwind, Cloudflare Pages) | [site/README.md](site/README.md) |
| Design system, tokens, and styleguide | [Design system](design/DESIGN_SYSTEM.md) · hosted at <https://styleguide.mgz-pkmn.com> |
| Project layout, dev workflow, CI, release | [Contributing](docs/contributing.md) |

## AI-assisted development

mgz-pkmn uses a lightweight multi-agent workflow inspired by
[@bobbylough](https://github.com/bobbylough)'s
[ai-pit-crew](https://github.com/bobbylough/ai-pit-crew) project. GitHub
itself is the active-work board — issues, milestones, branches, PRs, and
`agent:*` labels carry every piece of state. [docs/roadmap.md](docs/roadmap.md)
is the planning navigator.

Agents should start with [AGENTS.md](AGENTS.md), follow the shared loop in
[.agent-workflow.md](.agent-workflow.md), and expect cross-agent review before
human approval.

## Community

Questions, ideas, or want to share what you built? Open a thread in [GitHub Discussions](https://github.com/mgzwarrior/mgz-pkmn/discussions).

## Support the project

mgz-pkmn is free and MIT-licensed. If it's saved you time at a card show and you'd like to chip in, the [Buy Me a Coffee page](https://www.buymeacoffee.com/mgz.pkmn) takes one-off "buy me a pizza 🍕" tips and runs three recurring membership tiers:

|   | Tier | What you get |
|---|---|---|
| <img src="https://raw.githubusercontent.com/mgzwarrior/mgz-pkmn/main/assets/bmc/tier-common.png" alt="Common tier badge" width="160" /> | **Common**<br>$3 / month | Supporters listing, ~24h early peek at release notes, personal thank-you |
| <img src="https://raw.githubusercontent.com/mgzwarrior/mgz-pkmn/main/assets/bmc/tier-uncommon.png" alt="Uncommon tier badge" width="160" /> | **Uncommon**<br>$8 / month | Everything in Common, plus members-only Discussions, one monthly roadmap vote, name in the README Supporters section |
| <img src="https://raw.githubusercontent.com/mgzwarrior/mgz-pkmn/main/assets/bmc/tier-holo-rare.png" alt="Holo Rare tier badge" width="160" /> | **Holo Rare**<br>$20 / month | Everything in Uncommon, plus your logo on the marketing-site supporters strip, priority bug triage (best-effort), early-access booth in the virtual card-show pilot |

<a href="https://www.buymeacoffee.com/mgz.pkmn"><img src="https://img.buymeacoffee.com/button-api/?text=Buy%20me%20some%20pizza&amp;emoji=%F0%9F%8D%95&amp;slug=mgz.pkmn&amp;button_colour=6bac55&amp;font_colour=000000&amp;font_family=Lato&amp;outline_colour=000000&amp;coffee_colour=FFDD00" alt="Buy me a pizza on Buy Me a Coffee" /></a>
