import { z } from 'zod'; import { BaseConnector, html as H, type ConnectorMeta, type CrawlContext, type RawRecordInput, type RawRecordLike } from '@rareindex/connectors'; import type { CurrencyCode, NormalizedRecord, NormalizedSale } from '@rareindex/shared'; import { makeSale } from '../../firecrawl/_carlib/index.js'; import { isNumisBundle, numisAttributes, numisCategory, parseCoinGrade, type NumisSlug } from '../../firecrawl/_g5-numismatics-lib/index.js'; /** * Stanley Gibbons Baldwin's (London) — stamps, coins, medals. The Next.js site exposes its page data as * JSON (/_next/data//…): the past-auctions list and, per auction, every lot with estimate, * hammer price, buyer's premium amount and status. Hammer and premium are therefore explicit. */ const SITE = 'https://sgbaldwins.com'; const PARSER_VERSION = '1.0.0'; const CHUNK = 200; const DEPARTMENTS: Record = { Stamps: 'stamps', Coins: 'coins', 'Medals & Militaria': 'medals' }; export const AuctionSchema = z.object({ uuid: z.string(), saleNumber: z.string().nullable(), title: z.string(), department: z.string().nullable(), slug: z.string(), amsDate: z.string().nullable(), dateTimeText: z.string().nullable(), status: z.string().nullable(), currencySymbol: z.string().nullable(), premiums: z.array(z.object({ percent: z.number(), amount_over: z.number().nullable().optional() })).default([]), }); export const LotSchema = z.object({ uuid: z.string(), lotNo: z.string(), title: z.string(), country: z.string().nullable(), low: z.string().nullable(), high: z.string().nullable(), startPrice: z.string().nullable(), hammerPrice: z.string().nullable(), premium: z.string().nullable(), status: z.string().nullable(), sessionDate: z.string().nullable(), categoryName: z.string().nullable(), images: z.array(z.string()).default([]), }); export const PayloadSchema = z.object({ kind: z.literal('auction_lots'), auction: AuctionSchema, url: z.string(), chunk: z.number().int(), totalLots: z.number().int(), lots: z.array(LotSchema) }); export type Payload = z.infer; export interface ListEntry { uuid: string; saleNumber: string | null; title: string; department: string | null; slug: string; amsDate: string | null; } export function buildIdFromHtml(htmlText: string): string | null { const nd = H.nextData(htmlText) as { buildId?: string } | null; return nd?.buildId ?? htmlText.match(/"buildId":"([^"]+)"/)?.[1] ?? null; } /** past-auctions.json → auctions (newest first as served). */ export function parsePastAuctions(json: unknown): ListEntry[] { const list = (json as { pageProps?: { auctionsListData?: Array> } })?.pageProps?.auctionsListData ?? []; const out: ListEntry[] = []; for (const a of list) { const uuid = typeof a.auctionId === 'string' ? a.auctionId : null; const slug = typeof a.arrowLink === 'string' ? a.arrowLink : null; if (!uuid || !slug || typeof a.title !== 'string') continue; out.push({ uuid, saleNumber: typeof a.saleNumber === 'string' ? a.saleNumber : null, title: a.title, department: typeof a.department === 'string' ? a.department : null, slug, amsDate: typeof a.amsDate === 'string' ? a.amsDate : null }); } return out; } /** auction page JSON → auction header + lots. */ export function parseAuctionJson(json: unknown, entry: ListEntry): { auction: z.infer; lots: z.infer[] } | null { const pp = (json as { pageProps?: Record })?.pageProps; if (!pp || !Array.isArray(pp.lots)) return null; const ams = (pp.amsData ?? {}) as { status?: string; premiums?: Array<{ percent: number; amount_over?: number | null }> }; const page = (pp.auctionPageData ?? {}) as { attributes?: { dateTime?: string } }; const cats = new Map(); for (const c of (pp.categories as Array<{ uuid?: string; name?: string }> | undefined) ?? []) if (c.uuid && c.name) cats.set(c.uuid, c.name); const lots: z.infer[] = []; let symbol: string | null = null; for (const raw of pp.lots as Array>) { const title = (raw.title as { en?: string } | undefined)?.en?.trim(); const uuid = typeof raw.uuid === 'string' ? raw.uuid : null; if (!uuid || !title) continue; const fin = (raw.financeItem ?? {}) as { hammer_price?: string | null; premium?: string | null }; symbol ??= (raw.auction as { currency?: { symbol?: string } } | undefined)?.currency?.symbol ?? null; const images = ((raw.images as Array<{ data?: { original?: { url?: string }; sm?: { url?: string } } }> | undefined) ?? []).map((i) => i.data?.original?.url ?? i.data?.sm?.url).filter((u): u is string => Boolean(u)).slice(0, 3); lots.push({ uuid, lotNo: String(raw.lot_no ?? ''), title, country: (typeof raw.country === 'string' ? raw.country : null) ?? (raw.dynamic_fields as { en?: { country?: string } } | undefined)?.en?.country ?? null, low: str(raw.low), high: str(raw.high), startPrice: str(raw.start_price), hammerPrice: str(fin.hammer_price ?? raw.hammer_price), premium: str(fin.premium), status: typeof raw.status === 'string' ? raw.status : null, sessionDate: typeof raw.session_date === 'string' ? raw.session_date : null, categoryName: typeof raw.category_uuid === 'string' ? (cats.get(raw.category_uuid) ?? null) : null, images, }); } return { auction: { uuid: entry.uuid, saleNumber: entry.saleNumber, title: entry.title, department: entry.department, slug: entry.slug, amsDate: entry.amsDate, dateTimeText: page.attributes?.dateTime ?? null, status: ams.status ?? null, currencySymbol: symbol, premiums: ams.premiums ?? [] }, lots, }; } function str(v: unknown): string | null { if (v === null || v === undefined || v === '') return null; return typeof v === 'number' ? String(v) : typeof v === 'string' ? v : null; } export function currencyFromSymbol(sym: string | null): CurrencyCode { if (!sym) return 'GBP'; if (sym.includes('$')) return 'USD'; if (sym.includes('€')) return 'EUR'; return 'GBP'; } interface Cursor { doneAuctions?: string[]; done?: boolean; updatedAt?: string; } export class SgBaldwinsConnector extends BaseConnector { readonly version = '1.0.0'; readonly parserVersion = PARSER_VERSION; protected override minIntervalMs = 1500; override readonly urlPatterns = [/sgbaldwins\.com\/auctions\//i]; async *crawl(ctx: CrawlContext): AsyncIterable { const auctionsPerRun = Number(this.meta.config.auctionsPerRun ?? 3); const departments = (this.meta.config.departments as string[] | undefined) ?? Object.keys(DEPARTMENTS); const cursor = { ...((ctx.options.cursor ?? {}) as Cursor) }; const done = new Set(cursor.doneAuctions ?? []); await this.throttle(); const home = await ctx.fetch(`${SITE}/`, { engines: ['api'], responseType: 'text', minQuality: 0, force: true }); const buildId = home.success && home.html ? buildIdFromHtml(home.html) : null; if (!buildId) { ctx.anomaly('selector_missing', `home: __NEXT_DATA__ buildId not found (${home.error ?? home.httpStatus})`); return; } await this.throttle(); const listUrl = `${SITE}/_next/data/${buildId}/auctions/past-auctions.json`; const list = await ctx.fetch(listUrl, { engines: ['api'], minQuality: 0 }); const auctions = list.success && list.json ? parsePastAuctions(list.json) : []; if (!auctions.length) { ctx.anomaly(list.success ? 'schema_drift' : 'page_fetch_failed', `${listUrl}: ${list.error ?? list.httpStatus ?? 'no auctionsListData'}`); return; } const wanted = auctions.filter((a) => a.department && departments.includes(a.department)); let processed = 0; let yielded = 0; for (const entry of wanted) { if (ctx.signal?.aborted || processed >= auctionsPerRun || done.has(entry.uuid) || this.reached(ctx, yielded)) { if (done.has(entry.uuid)) continue; break; } const url = `${SITE}/_next/data/${buildId}${entry.slug}.json`; await this.throttle(); const res = await ctx.fetch(url, { engines: ['api'], expect: ['title', 'price'], parse: (r) => { const p = parseAuctionJson(r.json, entry); const sold = p?.lots.find((l) => l.hammerPrice); return p ? { title: p.lots[0]?.title ?? entry.title, price: sold?.hammerPrice ?? null } : null; } }); processed++; if (!res.success || !res.json) { ctx.anomaly('page_fetch_failed', `${url}: ${res.error ?? res.httpStatus}`); continue; } const parsed = parseAuctionJson(res.json, entry); if (!parsed) { ctx.anomaly('schema_drift', `${url}: pageProps.lots missing`); continue; } if (parsed.auction.status && parsed.auction.status !== 'completed') continue; // still running for (let i = 0; i < parsed.lots.length; i += CHUNK) { const lots = parsed.lots.slice(i, i + CHUNK); if (!lots.some((l) => l.hammerPrice)) continue; yielded++; const payload: Payload = { kind: 'auction_lots', auction: parsed.auction, url: `${SITE}${entry.slug}`, chunk: i / CHUNK, totalLots: parsed.lots.length, lots }; yield { url: `${SITE}${entry.slug}`, externalId: `auction:${entry.uuid}:chunk:${i / CHUNK}`, kind: 'sale', engine: res.engine, httpStatus: res.httpStatus, payload, fetchedAt: res.fetchedAt }; } done.add(entry.uuid); if (ctx.options.mode === 'backfill') await ctx.progress({ page: wanted.indexOf(entry) + 1, totalPages: wanted.length, itemsProcessed: yielded, reachedDate: entry.amsDate ? new Date(entry.amsDate) : null }); await ctx.setCursor({ doneAuctions: [...done].slice(-400), updatedAt: new Date().toISOString() }); } if (ctx.options.mode === 'backfill' && wanted.every((a) => done.has(a.uuid))) await ctx.setCursor({ doneAuctions: [...done].slice(-400), done: true, updatedAt: new Date().toISOString() }); } async normalize(raw: RawRecordLike): Promise { const p = PayloadSchema.parse(raw.payload); const currency = currencyFromSymbol(p.auction.currencySymbol); const fallback: NumisSlug = DEPARTMENTS[p.auction.department ?? ''] ?? 'coins'; const out: NormalizedSale[] = []; for (const lot of p.lots) { const hammer = Number(lot.hammerPrice); if (!lot.hammerPrice || !Number.isFinite(hammer) || hammer <= 0 || lot.status === 'unsold') continue; const dateSrc = lot.sessionDate ?? p.auction.amsDate; if (!dateSrc) continue; const d = new Date(dateSrc); if (Number.isNaN(d.getTime())) continue; const saleDate = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate())); const hint = `${p.auction.department ?? ''} ${lot.categoryName ?? ''}`; const categorySlug = fallback === 'stamps' ? 'stamps' : numisCategory(lot.title, hint, fallback); const g = parseCoinGrade(lot.title); const premium = lot.premium ? Number(lot.premium) : null; const attributes = numisAttributes({ categorySlug, title: lot.title, section: lot.categoryName ?? p.auction.title, country: null, identifiers: { sgbaldwins_lot: lot.uuid, ...(lot.title.match(/\bSG\s?(\d+[a-z]?)\b/) && categorySlug === 'stamps' ? { sg_number: lot.title.match(/\bSG\s?(\d+[a-z]?)\b/)![1]! } : {}) }, metadata: { sale_number: p.auction.saleNumber, auction_title: p.auction.title, department: p.auction.department, category: lot.categoryName, country_label: lot.country, estimate_low: lot.low ? Number(lot.low) : null, estimate_high: lot.high ? Number(lot.high) : null, start_price: lot.startPrice ? Number(lot.startPrice) : null, hammer_price: hammer, buyer_premium_amount: premium, buyer_premium_percent: p.auction.premiums[0]?.percent ?? null, total_with_premium: premium !== null ? hammer + premium : null, }, }); if (!attributes.country && lot.country) attributes.country = countryLabel(lot.country); const sale = makeSale({ meta: this.meta, sourceUrl: `${SITE}${p.auction.slug}`, externalId: lot.uuid, rawTitle: lot.title, attributes, price: hammer, currency, saleDate, buyerPremiumIncluded: false, auctionHouse: "Stanley Gibbons Baldwin's", lotNumber: lot.lotNo || null, imageUrls: lot.images, observedAt: raw.fetchedAt, parserVersion: PARSER_VERSION, confidence: 0.9, isBundle: isNumisBundle(lot.title), conditionRaw: g.conditionRaw, location: 'GB', }); sale.grade = { grader: g.grader, grade: g.grade, qualifier: g.qualifier, certificationNumber: g.certificationNumber }; out.push(sale); } return out; } } const COUNTRY_LABELS: Record = { 'Great Britain': 'GB', 'United Kingdom': 'GB', England: 'GB', Scotland: 'GB', Ireland: 'IE', Australia: 'AU', Canada: 'CA', 'United States': 'US', USA: 'US', India: 'IN', France: 'FR', Germany: 'DE', Italy: 'IT', Spain: 'ES', 'South Africa': 'ZA', 'New Zealand': 'NZ', 'Hong Kong': 'HK', China: 'CN', Japan: 'JP', Switzerland: 'CH', Netherlands: 'NL', Belgium: 'BE', Austria: 'AT', Russia: 'RU', Malta: 'MT', Cyprus: 'CY', Gibraltar: 'GI', Ceylon: 'LK', 'Sri Lanka': 'LK', Jamaica: 'JM', Bermuda: 'BM' }; function countryLabel(label: string): string | null { return COUNTRY_LABELS[label.trim()] ?? null; } export default (meta: ConnectorMeta) => new SgBaldwinsConnector(meta);