{"_id":"@ari.dev/figure-market-core","name":"@ari.dev/figure-market-core","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.1":{"name":"@ari.dev/figure-market-core","version":"0.1.1","description":"Core figure marketplace utilities for relevance scoring, authenticity risk, and portfolio valuation.","type":"module","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc -p tsconfig.json","clean":"rm -rf dist","prepack":"npm run clean && npm run build","check":"tsc -p tsconfig.json --noEmit"},"keywords":["anime-figures","collectibles","valuation","marketplace","portfolio","authenticity"],"license":"MIT","devDependencies":{"typescript":"^5.5.0"},"engines":{"node":">=18"},"_id":"@ari.dev/figure-market-core@0.1.1","_nodeVersion":"26.1.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-zpsJRujnAfnEYVocVep+A393YiCw+rWjTITXGlKB/BhIwUZum2jwQ3QNIzIrQwSE1XiBs/IeSXFYhqKKIv3oWw==","shasum":"e28baf26a62579e544fba33f39e5133e473eb421","tarball":"https://registry.npmjs.org/@ari.dev/figure-market-core/-/figure-market-core-0.1.1.tgz","fileCount":31,"unpackedSize":58962,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFx3/+K9Iq41FBohIGnaru30F9yF2q8Z6bx9bSSJtOoaAiEA6NXPd4qjghbEd6xnW2aVIs7pxApzvDZ98aPJIX/Xiys="}]},"_npmUser":{"name":"ari.dev","email":"tarihant2001@gmail.com"},"directories":{},"maintainers":[{"name":"ari.dev","email":"tarihant2001@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/figure-market-core_0.1.1_1781672171339_0.35105440701653023"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-17T04:56:11.124Z","0.1.1":"2026-06-17T04:56:11.497Z","modified":"2026-06-17T04:56:11.761Z"},"maintainers":[{"name":"ari.dev","email":"tarihant2001@gmail.com"}],"description":"Core figure marketplace utilities for relevance scoring, authenticity risk, and portfolio valuation.","keywords":["anime-figures","collectibles","valuation","marketplace","portfolio","authenticity"],"license":"MIT","readme":"# figure-market-core\n\nTypeScript utilities for collectible figure marketplace analysis.\n\n`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.\n\n## Features\n\n- **Listing relevance** — rank marketplace listings against a target figure identity.\n- **Variant filtering** — prefer exact releases over broad character matches.\n- **Authenticity-risk scoring** — flag text patterns such as replica, bootleg, KO, or China version when they actually appear in listing evidence.\n- **Valuation estimates** — compute low, median, high, and confidence from sold, active, and manual comps.\n- **Portfolio math** — summarize paid cost, current estimate, and gain/loss.\n- **Query helpers** — generate marketplace search variants from a figure identity.\n\n## What this package is\n\nA dependency-free core logic package for Node.js and TypeScript projects.\n\n## What this package is not\n\nThis package does not include:\n\n- marketplace API credentials\n- OpenAI prompts or keys\n- web scrapers\n- databases or migrations\n- local datasets, images, or debug logs\n\nProvider integrations should live in a separate app or adapter package.\n\n## Install\n\n```bash\nnpm install figure-market-core\n```\n\nFor local development:\n\n```bash\nnpm install\nnpm run build\n```\n\nRun the included example:\n\n```bash\nnode examples/basic.mjs\n```\n\n## Quick start\n\n```ts\nimport {\n  buildQueryVariants,\n  estimateValuation,\n  rankListings,\n  scoreBootlegRisk,\n  summarizePortfolio\n} from \"figure-market-core\";\n\nconst identity = {\n  canonicalFigureName: \"S.H.Figuarts Son Goku & Dragon 40th Anniversary Edition\",\n  character: \"Son Goku\",\n  franchise: \"Dragon Ball\",\n  manufacturer: \"Bandai Spirits\",\n  productLine: \"S.H.Figuarts\",\n  variantTerms: [\"40th\", \"anniversary\", \"dragon\", \"shenron\"]\n};\n\nconst listings = [\n  {\n    title: \"S.H.Figuarts Son Goku & Dragon 40th Anniversary Edition Bandai Spirits\",\n    marketplace: \"eBay\",\n    price: 118,\n    sold: true,\n    sourceType: \"manual_sold\",\n    itemSpecifics: { Brand: \"Bandai Spirits\" }\n  },\n  {\n    title: \"S.H. Figuarts Dragon Ball Son Goku SDCC Exclusive 2019 Kid Goku\",\n    marketplace: \"eBay\",\n    price: 95,\n    sold: true,\n    sourceType: \"manual_sold\",\n    itemSpecifics: { Brand: \"Bandai\" }\n  }\n];\n\nconst queries = buildQueryVariants(identity);\nconst ranked = rankListings(identity.canonicalFigureName, listings, identity);\nconst risk = ranked.map((listing) => scoreBootlegRisk(listing));\nconst estimate = estimateValuation(ranked, { excludeHighRisk: true });\nconst portfolio = summarizePortfolio([\n  { ...identity, paidPrice: 90, currentEstimate: estimate.median }\n]);\n```\n\n## API\n\n### Relevance\n\n```ts\nscoreListingRelevance(query, listing, identity?)\nrankListings(query, listings, identity?)\n```\n\nUse 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.\n\n### Authenticity risk\n\n```ts\nscoreBootlegRisk(listing)\n```\n\nReturns 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.\n\n### Valuation\n\n```ts\nestimateValuation(listings, options?)\n```\n\nBuilds a price range from comparable listings. Sold and manual comps are weighted more heavily than active listings. High-risk listings can be excluded.\n\n### Portfolio\n\n```ts\nsummarizePortfolio(items)\n```\n\nCalculates portfolio-level totals, including estimated value, paid cost, gain/loss, and coverage.\n\n### Query helpers\n\n```ts\nbuildSearchQuery(identity)\nbuildQueryVariants(identity)\nextractVariantTerms(query)\n```\n\nUse these helpers to generate marketplace search strings and identify release-specific terms.\n\n## Core types\n\nCommon inputs:\n\n```ts\ntype FigureIdentity = {\n  canonicalFigureName?: string;\n  character?: string;\n  franchise?: string;\n  manufacturer?: string;\n  productLine?: string;\n  variantTerms?: string[];\n};\n\ntype MarketplaceListing = {\n  title: string;\n  marketplace?: string;\n  price?: number;\n  sold?: boolean;\n  sourceType?: string;\n  url?: string;\n  imageUrl?: string;\n  condition?: string;\n  description?: string;\n  itemSpecifics?: Record<string, string>;\n};\n```\n\nSee `src/types.ts` for the full type definitions.\n\n## Development\n\n```bash\nnpm run check\nnpm run build\nnpm pack\n```\n\n## Package boundary\n\nKeep this package focused on deterministic scoring and valuation logic. API clients, browser automation, image analysis, storage, and authentication should be implemented outside this package.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-fe41ec5e0003fb7491ffe612fef85697"}