amazon-review-defect-parser

Parse raw 1-3 star Amazon customer reviews into structured, actionable defect data: root-cause categories, supporting quotes, and ready-to-use listing bullet rewrites.

{
  "totalReviewsAnalyzed": 10,
  "categories": [
    {
      "category": "Sizing/Fit",
      "count": 3,
      "percentage": 30,
      "customerQuotes": ["Runs way too small, ordered a large and it fit like a medium."]
    }
  ],
  "recommendedBulletRewrites": [
    "Includes a true-to-size fit chart — measure before you buy to skip returns."
  ]
}

Works two ways:

• Mock mode (default, no API key needed) — a deterministic, keyword-based analyzer. Good for local dev, CI, and trying the tool out.
• LLM mode (Anthropic or OpenAI) — real clustering, quote extraction, and bullet-rewrite generation, set an API key and it's used automatically.

Install

npm install -g amazon-review-defect-parser

Or use it without installing:

npx amazon-review-defect-parser examples/sample-reviews.json

CLI usage

# Mock mode — no API key required
review-defect-parser examples/sample-reviews.json

# LLM mode — auto-detects the provider from your env
export ANTHROPIC_API_KEY=sk-ant-...
review-defect-parser examples/sample-reviews.json

# Force a provider / model
review-defect-parser reviews.json --provider openai --model gpt-4o-mini

# Write to a file instead of stdout
review-defect-parser reviews.json --output report.json

Input can be:

• A .json file: an array of strings, or an array of { id?, rating?, text } objects
• A .txt file: one review per line

Library usage

import { analyzeReviews } from "amazon-review-defect-parser";

const report = await analyzeReviews([
  { text: "Runs way too small, had to return it." },
  { text: "Strap broke after two days, feels cheap." },
]);

console.log(report.categories);

Pick a provider explicitly:

import { analyzeReviews, AnthropicAnalyzer, MockAnalyzer } from "amazon-review-defect-parser";

const report = await analyzeReviews(reviews, { provider: "anthropic", model: "claude-opus-5" });

// or instantiate directly for more control
const analyzer = new AnthropicAnalyzer({ apiKey: "sk-ant-..." });
const report2 = await analyzer.analyze(reviews);

Categories

Every review is mapped to exactly one of:

• Sizing/Fit
• Material/Durability
• Instructions/Setup
• Packaging/Transit Damage
• Other

Development

npm install
npm run dev -- examples/sample-reviews.json   # run the CLI from source
npm test                                      # run the mock-mode test suite
npm run build                                 # compile to dist/

Why this exists

This is a focused, single-purpose utility, not a monitoring platform: point it at a batch of reviews and get one report back. If you want this running continuously across your whole catalog — automatic ingestion, trend tracking over time, and alerts when a new defect pattern emerges — that's what ASIN Guard does.

License

MIT