SWU Importer Technical Overview

Star Wars: Unlimited is a trading card game by Fantasy Flight Games launched in March 2024. It features Standard, Hyperspace, Showcase, and Prestige card variants with Carbonite Edition premium products.

The importer (StarWarsUnlimitedImporter) uses a TCGCSV-first architecture — every product on TCGPlayer is the source of truth for what exists in our system. The SWU API enriches products with attributes, translations, and art fallback. It extends BaseImporter and follows the standard import lifecycle.

Useful Resources

Data Sources

Product Model

Variants

SWU cards come in different art/frame treatments, modeled as the StarWarsUnlimitedVariant enum:

Finishes

Each variant can exist in one or more physical finishes, modeled as the StarWarsUnlimitedFinish enum:

TCGPlayer Suffix Mapping

The importer parses TCGCSV product names to determine variant and finish:

SWU API Variant Type Mapping

When enriching from the SWU API, the variantTypes relation maps to our model:

Import Flow

Step-by-step

1. Load data sources — TCGCSV products (all groups for category 79), SWU API cards (paginated, cached), TCGPowertools data
2. Build expansions — TCGCSV groups are the primary source. SWU API set codes enrich with short codes (e.g. “sor” for Spark of Rebellion). Groups with no API match become promo expansions.
3. Build SWU API index — Index all API cards by accent-normalized name for O(1) enrichment lookups
4. Iterate TCGCSV products — For each product:
   • Skip if non-card (no extNumber — sealed products, CSV artifacts)
   • Parse product name to extract base name and TCGPlayer suffix
   • Resolve variant and finish from the suffix via TCG_PLAYER_SUFFIX_MAP
   • Find matching SWU API card by normalized name for enrichment (attributes, translations, art fallback)
   • Find Cardmarket ID via TCGPowertools (if API match found)
   • Use TCGPlayer 1000x1000 image as primary, SWU API art crop as fallback
   • Create CardData with guaranteed TCGPlayer ID
5. Generate diff — Compare against existing DB state
6. Apply diff — Upsert approved changes

Expansion Mapping

The tcgGroupSlugToExpansionCode map tracks the relationship between TCGCSV group slugs and expansion codes. For main sets with an API match, the SWU API code is used. For promo-only groups, the slugified group name becomes the code.

Name Normalization

Card names are normalized for matching using normalizeCardName():

• Lowercase
• Trim whitespace
• Strip diacritics (NFD decomposition + remove combining marks)

This handles cases like Chirrut Îmwe (SWU API) matching Chirrut Imwe (TCGCSV).

Code Locations