import { z } from 'zod'; import { BaseConnector, html as htmlUtil, type ConnectorMeta, type CrawlContext, type RawRecordInput, type RawRecordLike } from '@rareindex/connectors'; import { type NormalizedRecord } from '@rareindex/shared'; import { attrs, catalogItem, makeTitle, num, priceObservation, withRetries } from '../_lib/shared.js'; import { dayOf, isoDay } from '../_lib/tcg-shared.js'; /** * MTGGoldfish — set pages embed a JSON card list with current paper/online prices; the public * price-history component returns a daily paper price series (2010 →) per printing. */ const BASE = 'https://www.mtggoldfish.com'; const PARSER_VERSION = '1.0.0'; const HEADERS = { 'user-agent': 'RareIndexBot/0.1 (+https://www.rareindex.io/about/data)', accept: 'text/html,application/xhtml+xml' }; const CardSchema = z.object({ name: z.string(), // "Black Lotus [LEA]" — MTGGoldfish card id set: z.string(), display_name: z.string(), rarity: z.string().nullable().optional(), foil: z.boolean().optional(), card_num: z.union([z.number(), z.string()]).nullable().optional(), finish: z.string().nullable().optional(), card_uuid: z.string().nullable().optional(), paper: z.number().nullable(), online: z.number().nullable(), link: z.string().nullable(), image: z.string().nullable(), }); type Card = z.infer; const SetPayloadSchema = z.object({ kind: z.literal('card'), setName: z.string().nullable(), setSlug: z.string(), card: CardSchema }); const HistoryPayloadSchema = z.object({ kind: z.literal('history'), setName: z.string().nullable(), card: CardSchema, series: z.array(z.tuple([z.string(), z.number()])) }); /** Parse the escaped JSON card list embedded in a set page. */ export function parseSetPage(html: string): { setName: string | null; cards: Card[] } { const idx = html.indexOf('"cards":['); if (idx < 0) return { setName: titleOf(html), cards: [] }; const start = html.lastIndexOf('="', idx) + 2; const end = html.indexOf('"', start); const raw = html.slice(start, end); const decoded = raw.replace(/"/g, '"').replace(/'/g, "'").replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>'); let json: { cards?: Array> }; try { json = JSON.parse(decoded) as { cards?: Array> }; } catch { return { setName: titleOf(html), cards: [] }; } const cards: Card[] = []; for (const c of json.cards ?? []) { const prices = (c.prices ?? {}) as Record; const images = (c.source_image_variants ?? {}) as Record; const links = (c.links ?? {}) as Record; const parsed = CardSchema.safeParse({ name: c.name, set: c.set, display_name: c.display_name, rarity: c.rarity, foil: c.foil, card_num: c.card_num, finish: c.finish, card_uuid: c.card_uuid, paper: num(prices.paper?.current_price), online: num(prices.online?.current_price), link: links.default ?? null, image: images['672x938'] ?? images['265x370'] ?? null, }); if (parsed.success) cards.push(parsed.data); } return { setName: titleOf(html), cards }; } function titleOf(html: string): string | null { const m = html.match(/([^<]+)<\/title>/); if (!m) return null; return m[1]!.replace(/\s*[|·-]\s*MTGGoldfish.*$/i, '').replace(/\s*Price(s| Guide).*$/i, '').replace(/\s*Set Information.*$/i, '').replace(/\s*\([A-Z0-9]{2,6}\)\s*$/, '').trim() || null; } /** "d += '2010-11-02, 3102.99\n'" lines → [[date, price], …] */ export function parseHistory(js: string): Array<[string, number]> { const out: Array<[string, number]> = []; for (const m of js.matchAll(/(\d{4}-\d{2}-\d{2}),\s*([0-9.]+)/g)) { const price = Number(m[2]); if (Number.isFinite(price) && price > 0) out.push([m[1]!, price]); } return out; } export class MtgGoldfishConnector extends BaseConnector { readonly version = '1.0.0'; readonly parserVersion = PARSER_VERSION; protected override minIntervalMs = 1500; override readonly urlPatterns = [/mtggoldfish\.com\/price\/[^/]+\/\d+\//i, /mtggoldfish\.com\/sets\/[^/?#]+/i]; private async page(ctx: CrawlContext, url: string) { await this.throttle(); return withRetries(() => ctx.fetch(url, { engines: ['api', 'firecrawl'], headers: HEADERS, responseType: 'text', minQuality: 0.3 }), (r) => r.success && Boolean(r.html || r.markdown), 3, 2500); } private async discoverSets(ctx: CrawlContext): Promise<string[]> { const seeds = (ctx.options.seeds?.length ? ctx.options.seeds : (this.meta.config.seeds as string[] | undefined)) ?? []; if (seeds.length) return seeds; const res = await this.page(ctx, `${BASE}/sets`); const text = res.html ?? ''; const slugs = [...new Set([...text.matchAll(/href="\/sets\/([^"#?]+)"/g)].map((m) => m[1]!))]; return slugs; } async *crawl(ctx: CrawlContext): AsyncIterable<RawRecordInput> { const sets = await this.discoverSets(ctx); const maxSets = ctx.options.mode === 'backfill' ? Infinity : Number(this.meta.config.maxSetsPerRun ?? 60); const hist = (this.meta.config.history ?? {}) as { enabled?: boolean; minPrice?: number; maxPerRun?: number; days?: number }; let setIdx = Number(ctx.options.cursor?.setIdx ?? 0); if (setIdx >= sets.length) setIdx = 0; let done = 0; let count = 0; let historyFetched = 0; for (; setIdx < sets.length && done < maxSets; setIdx++, done++) { const slug = sets[setIdx]!; const res = await this.page(ctx, `${BASE}/sets/${slug}`); if (!res.success || !res.html) { ctx.anomaly('page_fetch_failed', `${slug}: ${res.error ?? res.httpStatus}`); continue; } const { setName, cards } = parseSetPage(res.html); if (!cards.length) ctx.anomaly('empty_page', `set ${slug}`); for (const card of cards) { if (this.reached(ctx, count)) return; count++; const url = card.link ? `${BASE}${card.link}` : `${BASE}/sets/${slug}`; yield { url, externalId: card.card_uuid ?? card.name, kind: 'catalog_item', engine: res.engine, httpStatus: res.httpStatus, payload: { kind: 'card', setName, setSlug: slug, card }, fetchedAt: res.fetchedAt }; if (hist.enabled !== false && card.paper !== null && card.paper >= Number(hist.minPrice ?? 100) && historyFetched < Number(hist.maxPerRun ?? 150) && !card.foil) { historyFetched++; const q = new URLSearchParams({ card_id: card.name, selector: '#tab-paper', type: 'paper', price_type: '' }); // The component is an XHR endpoint: needs the XHR headers and must never fall back to Firecrawl (406 otherwise). await this.throttle(); const h = await ctx.fetch(`${BASE}/price_history_component?${q.toString()}`, { engines: ['api'], headers: { ...HEADERS, accept: 'text/javascript, application/javascript, */*;q=0.1', 'x-requested-with': 'XMLHttpRequest' }, responseType: 'text', minQuality: 0.3 }); if (h.success && h.html) { const cutoff = Date.now() - Number(hist.days ?? 1095) * 86_400_000; const series = parseHistory(h.html).filter(([d]) => new Date(`${d}T00:00:00Z`).getTime() >= cutoff); if (series.length) yield { url, externalId: `${card.card_uuid ?? card.name}:history`, kind: 'price_observation', engine: h.engine, httpStatus: h.httpStatus, payload: { kind: 'history', setName, card, series }, fetchedAt: h.fetchedAt }; } else ctx.anomaly('page_fetch_failed', `history ${card.name}: ${h.error ?? h.httpStatus}`); } } await ctx.setCursor({ setIdx: setIdx + 1, updatedAt: new Date().toISOString() }); } if (setIdx >= sets.length) await ctx.setCursor({ setIdx: 0, updatedAt: new Date().toISOString() }); } async lookup(url: string, ctx: CrawlContext): Promise<RawRecordInput[]> { const m = url.match(/mtggoldfish\.com\/price\/([^/]+)\/(\d+)\//i); if (!m) return []; // Card pages do not embed the JSON list; resolve through the set page. const res = await this.page(ctx, `${BASE}/sets/${m[1]}`); if (!res.success || !res.html) return []; const { setName, cards } = parseSetPage(res.html); const card = cards.find((c) => String(c.card_num) === m[2] && !c.foil) ?? cards.find((c) => String(c.card_num) === m[2]); if (!card) return []; return [{ url, externalId: card.card_uuid ?? card.name, kind: 'catalog_item', engine: res.engine, httpStatus: res.httpStatus, payload: { kind: 'card', setName, setSlug: m[1]!, card }, fetchedAt: res.fetchedAt }]; } private attrsFor(card: Card, setName: string | null) { const variant = card.foil || /foil/i.test(card.finish ?? '') ? (/etched/i.test(card.finish ?? '') ? 'Etched Foil' : 'Foil') : null; return { variant, a: attrs({ categorySlug: 'magic_the_gathering', franchise: 'Magic: The Gathering', brand: 'Wizards of the Coast', set: setName ?? card.set, setCode: card.set.toUpperCase(), name: card.display_name, number: card.card_num !== null && card.card_num !== undefined ? String(card.card_num) : null, year: null, variant, language: 'English', rarity: card.rarity ?? null, identifiers: { mtggoldfish_card_id: card.name, ...(card.card_uuid ? { mtggoldfish_uuid: card.card_uuid } : {}) }, metadata: { finish: card.finish ?? null, online_price: card.online }, }), }; } async normalize(raw: RawRecordLike): Promise<NormalizedRecord[]> { const payload = raw.payload as { kind?: string }; if (payload.kind === 'history') { const { card, setName, series } = HistoryPayloadSchema.parse(raw.payload); const { a, variant } = this.attrsFor(card, setName); const rawTitle = makeTitle({ name: card.display_name, set: setName ?? card.set, number: card.card_num !== null && card.card_num !== undefined ? String(card.card_num) : null, variant }); const out: NormalizedRecord[] = []; const seen = new Set<string>(); for (const [date, price] of series) { if (seen.has(date)) continue; seen.add(date); const day = isoDay(date); if (!day) continue; out.push(priceObservation({ kind: 'price_observation', connectorId: this.meta.id, sourceId: this.meta.sourceId, sourceUrl: raw.url, externalId: `${card.card_uuid ?? card.name}:paper:${date}`, rawTitle, imageUrls: card.image ? [card.image] : [], attributes: a, observedAt: raw.fetchedAt, confidence: 0.7, parserVersion: PARSER_VERSION, priceKind: 'market', price, currency: 'USD', observationDate: day, sampleSize: null })); } return out; } const { card, setName } = SetPayloadSchema.parse(raw.payload); const { a, variant } = this.attrsFor(card, setName); const number = card.card_num !== null && card.card_num !== undefined ? String(card.card_num) : null; const rawTitle = makeTitle({ name: card.display_name, set: setName ?? card.set, number, variant }); const images = card.image ? [card.image] : []; const out: NormalizedRecord[] = [ catalogItem({ kind: 'catalog_item', connectorId: this.meta.id, sourceId: this.meta.sourceId, sourceUrl: raw.url, externalId: card.card_uuid ?? card.name, rawTitle, imageUrls: images, attributes: a, observedAt: raw.fetchedAt, confidence: 0.85, parserVersion: PARSER_VERSION, releaseDate: null }), ]; if (card.paper) { out.push(priceObservation({ kind: 'price_observation', connectorId: this.meta.id, sourceId: this.meta.sourceId, sourceUrl: raw.url, externalId: `${card.card_uuid ?? card.name}:paper:current`, rawTitle, imageUrls: images, attributes: a, observedAt: raw.fetchedAt, confidence: 0.75, parserVersion: PARSER_VERSION, priceKind: 'market', price: card.paper, currency: 'USD', observationDate: dayOf(raw.fetchedAt), sampleSize: null })); } return out; } } export default (meta: ConnectorMeta) => new MtgGoldfishConnector(meta); export { htmlUtil as _html };