CardMarket ID Matching Overhaul (~36% → ~85-91%)

Context and Problem Statement

CardMarket ID coverage for SWU products was ~36%. Three root causes were identified:

1. Name normalization broken by (V.N) suffixes — CardMarket appends version suffixes like (V.2) to card names, which broke the normalized name comparison. This affected ~60% of CardMarket singles, especially in newer sets (LOF 6.2%, SEC 2.8%).

2. Variant expansion search too restrictive — Only Hyperspace variants searched X-prefixed (Extras) expansions on TCGPowerTools. Showcase (124 products) and Prestige (534 products) were at 0% coverage because they searched the wrong expansion. Since print numbers are unique across base and extras expansions, filtering by variant type was unnecessary.

3. No fallback for products without SWU API match — Products that failed to match the SWU API had their CardMarket lookup skipped entirely, leaving them with no Cardmarket ID regardless of whether a PowerTools match existed.

Decision Drivers

• Print numbers are unique across base and X-prefixed (Extras) expansions — no need to filter by variant
• Products without SWU API enrichment still have TCGPlayer name + print number, sufficient for PowerTools matching
• Name normalization must strip CardMarket-specific suffixes like (V.N) and Token

Considered Options

1. Search all mapped expansions + add fallback — remove variant filtering, strip (V.N) suffixes, add TCGPlayer-data fallback
2. Improve variant detection — try to correctly classify Showcase/Prestige into base vs extras
3. Use CardMarket API directly — bypass TCGPowerTools entirely

Decision Outcome

Chosen option: Search all mapped expansions + add fallback, because it’s the simplest fix with the largest coverage gain.

Implementation

Logic Flow

Key Changes

1. Removed isHyperspace parameter from findPowertoolsProduct() and SwuTcgPowertoolsMatchService.findMatch() — now always searches all mapped expansions
2. Added fallback for products without SWU API match — uses TCGPlayer name/number directly
3. Name normalization improvements in tcg-powertools-match.utils.ts:
   • Strip (V.N) version suffixes from CardMarket names
   • Strip Token suffix for double-faced card mismatches
4. Expanded SWU_API_TO_TCGPT_CODE_MAP with 12 promo/OP set mappings

Impacted Files

Consequences

Positive

• CardMarket coverage: ~36% → ~85-91% across all SWU sets
• Showcase and Prestige products now have CardMarket IDs (were at 0%)
• Products without SWU API enrichment can still get CardMarket IDs via fallback
• Simpler code — no variant-based expansion filtering logic

Negative

• Searching all mapped expansions instead of filtering is slightly less efficient (more candidates to compare), but the impact is negligible given the small dataset size
• Fallback uses TCGPlayer names which may differ from CardMarket names, reducing match quality for edge cases

More Information

• PR: #2742
• Coverage report: specs/swu-cardmarket/status-report.md