Per-Finish externalIds Array + HOLOFOIL Global-Enum Finish Mapping

Context and Problem Statement

Dragon Ball Super: Fusion World cards are sold on TCGplayer (category 80) in two treatments: a non-foil Standard and a foil Holofoil. On TCGplayer the same card has a distinct product ID per finish, and prices differ between them.

Two things had to be decided to model this correctly:

1. How to store the per-finish TCGplayer product IDs on a printing.
2. Which global CardFinish value the foil treatment maps to. Fusion World’s foil is labelled “Holofoil”, which did not exist in the platform-wide CardFinish enum — every existing game used STANDARD/FOIL (and richer foil variants for SWU). Using FOIL would be a lie (it is specifically a holofoil treatment, named so by Bandai/TCGplayer) and would collide with how other games and the finish hierarchy reason about FOIL.

Decision Drivers

• A product must be resolvable by a single indexed query on its marketplace ID, regardless of finish.
• The finish stored on a printing must match the real-world finish name so badges, filters, and i18n are correct.
• The global finish enum is shared by all games and feeds the PostgreSQL finish enums (price, inventory, list-product, journal) — any new value must be added everywhere exhaustively.
• Fusion World’s finish model is genuinely just two values (Standard / Holofoil); no complex variant parsing is needed.

Decision Outcome

1. Per-finish externalIds array. Each printing stores TCGplayer IDs as an array of { finish, id } entries, consistent with the platform-wide array format adopted for all games (see SWU: externalIds array format):

externalIds: {
  TCGplayer: [
    { finish: "Standard", id: 123456 },
    { finish: "Holofoil", id: 123457 },
  ],
}

This enables a single indexed lookup (externalIds.TCGplayer.id) and keeps Standard and Holofoil prices on the correct printing.

2. Add HOLOFOIL to the global CardFinish enum. Rather than reuse FOIL, a new HOLOFOIL value was added to the platform-wide CardFinish enum and propagated through every exhaustive consumer. Fusion World’s per-game finish enum is exactly Standard / Holofoil, and the game→global mapping is by exact string identity.

// dbs-fusion.types.ts
export enum DbsFusionFinish {
  STANDARD = "Standard",
  HOLOFOIL = "Holofoil",
}

Why HOLOFOIL and not FOIL

• Accuracy — TCGplayer’s subTypeName for these products is “Holofoil”, and Bandai prints them as holofoils. Mapping to a generic FOIL would mislabel the finish.
• No collision with foil semantics — FOIL is used by other games and participates in finish-hierarchy logic; overloading it for Fusion World would muddy badges, the FOIL_FINISHES set, and lowest-foil resolution.
• Exhaustive maps force correctness — adding a new enum value surfaces every place that must handle it (attribute value maps, finish badge set, mobile finish icon, the four PG finish enums), so nothing is silently dropped.

Consequences

Positive

• Single indexed query resolves a product by TCGplayer ID across both finishes.
• The finish name on each printing matches reality, so badges/filters/SEO are correct.
• HOLOFOIL is now a first-class global finish other games can reuse if needed.

Negative

• Adding a value to the global CardFinish enum touches every exhaustive Record<CardFinish, …> and all four PostgreSQL finish pgEnums. Because db:push derives the PG enums at runtime, a stale PG environment will reject Holofoil inserts until re-pushed (or until a committed ALTER TYPE … ADD VALUE 'Holofoil' migration lands). Masters is unaffected because it never uses Holofoil.
• A global holofoil i18n key must exist for the global finish-attribute code path; the per-game dbs-fusion attribute namespace already carries its own holofoil/foil labels.

Impacted Files