SkinScope

CS2 skin price lookup for the YourBot.gg Discord bot platform (formerly branded MMO Maid; the platform rename shipped with SDK 0.6.0).

/skin query: ak redline

Returns a rich Discord embed with the skin's image, rarity tier, valid wears, and Steam Market + Skinport prices side by side (USD, from build-time bundled dumps) — the Skinport field shows its lowest ask, a vs Steam delta, and the live listing count. The embed title is a clickable hyperlink to the Steam Market listings page — the buy path. Interactive wear and quality buttons let users explore variants, editing the card in place.

Features

• Two price sources, side by side — Steam Market (from ByMykel/counter-strike-price-tracker) and Skinport (from its public /v1/items API), both sourced at build time. The Skinport field carries a −X.X% vs Steam delta and listing count so the card is a real cross-market comparison. Refresh with tools/build_prices.py + tools/build_skinport.py — see "Refreshing prices" below.
• Clickable embed title — links straight to the Steam Market listings page for the exact (skin, wear, quality) variant. One-click buy path.
• In-place card editing — wear/quality/alt buttons update the existing card (Discord UPDATE_MESSAGE, SDK 0.7.0+) instead of posting a new message.
• One-click onboarding — a bare /skin shows a numbered quick-start with a "Try an example" button that renders a live result in one click.
• Smart filters: category (rifle/SMG/pistol/sniper/knife/glove/agent), rarity tier (Consumer → Covert → Knife/Glove), wear (FN/MW/FT/WW/BS), StatTrak/Souvenir/Normal
• Browse mode: /skin category: knife (no query) shows top items in that category
• Admin dashboard (YourBot panel → plugin → Overview): lookup volume, bundled-data health (both sources), error-code table — no Discord commands needed
• 2155-item catalog (2092 skins + 63 agents) bundled in the plugin, no external DB needed
• Zero runtime HTTP — both price dumps and the catalog ship in the zip; no allowlist setup needed
• Sandbox-safe — fits in the platform's 64MB RAM envelope; no egress required

Why bundled-only

The v0.1.x design fetched prices live from Steam Market and DMarket. The v0.2.1 design added live SkinBaron alongside the bundled Steam dump. Both live-fetch directions failed in production for the same reason: MMO Maid's sandbox proxy egress IPs are TCP-reset by every Cloudflare-fronted skin marketplace during TLS handshake (Steam, DMarket, and SkinBaron all honour the same shared blocklist). The connection dies below the HTTP layer, so no in-plugin mitigation works.

v0.2.0 sidestepped Steam's block by baking ByMykel's CS2 price tracker data into the zip. v0.7.0 applies the same lesson to restore the comparative pricing the plugin was built around: Skinport is also Cloudflare-fronted (a live fetch would hit the same wall), but its /v1/items API is reachable from the build host, so a second bundled dump gives a genuine Steam-vs-Skinport comparison with zero runtime HTTP. See ARCHITECTURE.md and SDK-ASSUMPTIONS.md for the rationale and CHANGELOG.md v0.7.0 for how Skinport was chosen (CSGOTrader's old aggregate feed is dead; the choice was made by live-probing, not memory).

Quickstart

# Build the catalog from byMykel/CSGO-API (run when refreshing for new Valve content)
py tools/build_catalog.py

# Build the bundled price dumps (Steam from ByMykel, Skinport from its /v1/items API)
py tools/build_prices.py
py -m pip install brotli   # one-time: Skinport's API only serves Brotli (build host only)
py tools/build_skinport.py

# Run the full test suite
py -m pytest tests/ -q

# Run all 8 audit gates
py tools/run_audit.py

# Produce the shippable plugin zip
py tools/build_bundle.py
# -> dist/skinscope.zip

# Run the platform's own upload validator against the artifact
py tools/validate_artifact.py

Refreshing prices

Both bundled dumps are point-in-time. Re-run the builds when prices feel stale:

py tools/build_prices.py     # Steam: fetches latest from ByMykel → data/prices.json.gz
py tools/build_skinport.py   # Skinport: fetches /v1/items (needs brotli) → data/skinport.json.gz
py tools/build_bundle.py     # repackages dist/skinscope.zip
# upload dist/skinscope.zip on the YourBot dev portal (auto-deploy on push if wired up)

ByMykel's upstream cron runs every 4 hours and Skinport's data is roughly similar, so the freshest reasonable cadence is hourly; daily or "as-needed" is also fine. Each builder gates on coverage and exits non-zero on a broken/partial download (build_prices.py also takes --ref to pin a known-good SHA). The two dumps are independent — refresh one without the other if you like.

Deploy

No HTTP Domains allowlist setup is required — v0.2.2 has zero runtime HTTP. Drop the bundle into the YourBot plugin manager (or push to GitHub if auto-deploy is wired up) and confirm the two Safe-tier capabilities (interaction:respond, storage:kv) when prompted. Run py tools/validate_artifact.py first — it's the same validator the upload pipeline runs.

Repository layout

manifest.json         YourBot plugin manifest
dashboard_manifest.json  admin dashboard (generated by tools/build_dashboard.py)
__main__.py           platform entry point — imports plugin.py, calls plugin.run()
plugin.py             slash handlers + component dispatcher (importable for tests)
requirements.txt      empty (no pip deps — stdlib only)
lib/
  catalog.py          load + search bundled compact catalog (inverted token index)
  pricing.py          Steam + Skinport lookup via bundled price dumps; SOURCE_META feature matrix
  links.py            Steam Market deep-link URL builders (clickable embed title)
  embed.py            Discord embed + button-row builders (two side-by-side source fields)
  state.py            wear/quality enums, custom_id encode/decode (versioned)
  scoring.py          pure-Python fuzzy search scorer
  config.py           per-server currency table (USD-only surface in v0.2)
  reasons.py          negative-cache reason-code constants + user-facing hints
  logctx.py           per-request correlation id (ContextVar)
  metricq.py          request-scoped deferred-metrics queue (3s-deadline guard)
data/
  catalog.json.gz             ~190 KB compact CS2 catalog (regenerated by tools/build_catalog.py)
  prices.json.gz              ~97 KB Steam Market prices (regenerated by tools/build_prices.py)
  skinport.json.gz            ~142 KB Skinport prices (regenerated by tools/build_skinport.py)
tools/                        offline build + audit + bundle scripts (not shipped in zip)
tests/                        pytest suite (not shipped in zip)

Documentation

Plugin spec at a glance

• SDK: yourbot-sdk 0.7.1 (renamed from mmo_maid_sdk in 0.6.0)
• Capabilities: interaction:respond, storage:kv (Safe tier, no install warning)
• Python: 3.11+
• External APIs at runtime: none. Both price dumps and the catalog ship in the zip.
• Catalog source: byMykel/CSGO-API
• Steam prices source: ByMykel/counter-strike-price-tracker
• Skinport prices source: Skinport /v1/items API (build-time only; needs brotli)
• Audit gates: 8 / 8 passing (py tools/run_audit.py)

Status

v0.7.0 is the current shipping release: SDK 0.7.1 verified, in-place card editing, one-click onboarding, and a second bundled price source (Skinport) restoring the Steam-vs-market comparison the plugin was built around. v0.1.x's hardening (114 audit findings across three rounds — concurrency races, adversarial Unicode, partial upstream outages, cache-stampede thundering herds, SDK contract drift) is preserved where applicable; the pieces that became dead code after the bundled-only pivot were removed cleanly. See CHANGELOG.md for the full per-release history.

License

TBD.