figure-market-core

TypeScript utilities for collectible figure marketplace analysis.

figure-market-core helps normalize marketplace data into cleaner pricing and portfolio signals. It is designed for apps that need to rank figure listings, filter variant mismatches, flag authenticity-risk wording, estimate values from comps, and summarize collection performance.

Features

• Listing relevance — rank marketplace listings against a target figure identity.
• Variant filtering — prefer exact releases over broad character matches.
• Authenticity-risk scoring — flag text patterns such as replica, bootleg, KO, or China version when they actually appear in listing evidence.
• Valuation estimates — compute low, median, high, and confidence from sold, active, and manual comps.
• Portfolio math — summarize paid cost, current estimate, and gain/loss.
• Query helpers — generate marketplace search variants from a figure identity.

What this package is

A dependency-free core logic package for Node.js and TypeScript projects.

What this package is not

This package does not include:

• marketplace API credentials
• OpenAI prompts or keys
• web scrapers
• databases or migrations
• local datasets, images, or debug logs

Provider integrations should live in a separate app or adapter package.

Install

npm install figure-market-core

For local development:

npm install
npm run build

Run the included example:

node examples/basic.mjs

Quick start

import {
  buildQueryVariants,
  estimateValuation,
  rankListings,
  scoreBootlegRisk,
  summarizePortfolio
} from "figure-market-core";

const identity = {
  canonicalFigureName: "S.H.Figuarts Son Goku & Dragon 40th Anniversary Edition",
  character: "Son Goku",
  franchise: "Dragon Ball",
  manufacturer: "Bandai Spirits",
  productLine: "S.H.Figuarts",
  variantTerms: ["40th", "anniversary", "dragon", "shenron"]
};

const listings = [
  {
    title: "S.H.Figuarts Son Goku & Dragon 40th Anniversary Edition Bandai Spirits",
    marketplace: "eBay",
    price: 118,
    sold: true,
    sourceType: "manual_sold",
    itemSpecifics: { Brand: "Bandai Spirits" }
  },
  {
    title: "S.H. Figuarts Dragon Ball Son Goku SDCC Exclusive 2019 Kid Goku",
    marketplace: "eBay",
    price: 95,
    sold: true,
    sourceType: "manual_sold",
    itemSpecifics: { Brand: "Bandai" }
  }
];

const queries = buildQueryVariants(identity);
const ranked = rankListings(identity.canonicalFigureName, listings, identity);
const risk = ranked.map((listing) => scoreBootlegRisk(listing));
const estimate = estimateValuation(ranked, { excludeHighRisk: true });
const portfolio = summarizePortfolio([
  { ...identity, paidPrice: 90, currentEstimate: estimate.median }
]);

API

Relevance

scoreListingRelevance(query, listing, identity?)
rankListings(query, listings, identity?)

Use these functions to sort listings by how well they match a target figure. The scorer considers character, franchise, manufacturer, product line, variant terms, and conflicting release terms.

Authenticity risk

scoreBootlegRisk(listing)

Returns a risk score and matched reasons based on listing title, description, condition text, and item specifics. Reasons are tied to matched evidence rather than generic warnings.

Valuation

estimateValuation(listings, options?)

Builds a price range from comparable listings. Sold and manual comps are weighted more heavily than active listings. High-risk listings can be excluded.

Portfolio

summarizePortfolio(items)

Calculates portfolio-level totals, including estimated value, paid cost, gain/loss, and coverage.

Query helpers

buildSearchQuery(identity)
buildQueryVariants(identity)
extractVariantTerms(query)

Use these helpers to generate marketplace search strings and identify release-specific terms.

Core types

Common inputs:

type FigureIdentity = {
  canonicalFigureName?: string;
  character?: string;
  franchise?: string;
  manufacturer?: string;
  productLine?: string;
  variantTerms?: string[];
};

type MarketplaceListing = {
  title: string;
  marketplace?: string;
  price?: number;
  sold?: boolean;
  sourceType?: string;
  url?: string;
  imageUrl?: string;
  condition?: string;
  description?: string;
  itemSpecifics?: Record<string, string>;
};

See src/types.ts for the full type definitions.

Development

npm run check
npm run build
npm pack

Package boundary

Keep this package focused on deterministic scoring and valuation logic. API clients, browser automation, image analysis, storage, and authentication should be implemented outside this package.

License

MIT