Shopify App Merchant Pain & Switching Intelligence

This JavaScript ESM Actor collects a bounded public Shopify App Store review sample and emits exactly one evidence-backed merchant-intelligence report per canonical app slug.

Scope

• Reviews are mapped through the vendored packages/feedback-analysis-core public exports.
• validateNormalizedFeedback enforces the canonical product, source, rating, text, reply, and provenance contract.
• Shopify taxonomy covers positive/negative themes, bugs, pricing, support, onboarding, integrations, performance, feature requests, switching directions, competitors, and non-actionable text.
• Switching requires lexical direction evidence. Reasons and named alternatives are retained only when explicit lexical evidence is present. Comparison-language competitor names do not create a switching signal.
• Shared clustering and aggregation rank recurring findings, cap evidence, and normalize confidence. Evidence retains feedback IDs, bounded excerpts, and provenance.
• src/output/build-report.js adds ratings, sentiment/theme summaries, pain categories, switching and competitor evidence, developer reply health, representative excerpts, confidence, data quality, and a deterministic summary.
• src/runtime/run-app.js isolates apps and source/analysis failures, retaining usable partial reports and never pushing raw reviews.

The default run uses no login, API key, proxy, browser, or external LLM. External LLMs, embeddings, automatic competitor discovery, causal churn claims, reviewer profiling, raw review output, and private sources are intentionally excluded.

Input and output

The canonical runnable input is sample-input.json. The input defaults to the public judgeme app with a 20-review, one-page bound for Store smoke testing; values are bounded by .actor/input_schema.json. The report-shaped output and dataset identity contract are .actor/output_schema.json and .actor/dataset_schema.json. Dataset identity is appSlug; one record is emitted per unique slug.

Local verification

node --test test/shopify-contract-adapter.test.mjs
node --test test/shopify-analysis.test.mjs
node --test test/shopify-aggregation.test.mjs
node --test test/input-normalization.test.mjs test/shopify-parser.test.mjs test/shopify-source-client.test.mjs
node --test test/report-builder.test.mjs test/run-app.test.mjs test/fixture-end-to-end.test.mjs
npm test
npm run lint
npm run format:check
apify validate-schema

Benchmark bounds and synchronization notes are in benchmarks/phase-2-analysis.md. Source selectors remain fixture-backed; a public Cloud smoke is required to validate live Shopify accessibility and markup compatibility.