Product Recall Catalog Exposure Monitor

A private Apify Actor that retrieves user-declared official recall feeds, normalizes their fields, and compares affected brands, models, UPCs/GTINs, and manufacturing windows with a merchant catalog. Each dataset row explains exactly why a catalog item matched a recall.

This is a detection aid, not a legal determination. Review the linked official notice before delisting, notifying customers, or reporting to a regulator.

What it does

• Accepts an inline catalog or a remote JSON/CSV catalog.
• Reads 1–20 JSON/CSV recall sources with explicit, safe dot-path mappings.
• Performs deterministic exact matching after Unicode/case/punctuation normalization.
• Rejects a known manufacturing date outside the recall window.
• Writes one evidence-backed exposure per catalog-item/recall pair to the default dataset.
• Writes counts and limit status to the OUTPUT key-value-store record.

No recall agency is hard-coded. This keeps network access under the operator's control and makes the Actor usable across jurisdictions. The operator must declare the final, official HTTPS feed URL and confirm its terms.

Quick start

1. Copy examples/input.json into the Apify input editor.
2. Replace the .example.gov URL and mapping with a real official feed.
3. Run the Actor and review the Exposure alerts dataset view.
4. Treat matchLimitReached: true as incomplete output and rerun with a higher bounded limit or a narrower catalog.

For local development:

npm ci
npm run typecheck
npm test
npm run build
APIFY_LOCAL_STORAGE_DIR=./storage npm start

Input contracts

Exactly one of catalog or catalogUrl is required. Remote catalogs must be a JSON array or CSV with the columns id, name, brand, model, upc, and manufactureDate. Only id is mandatory.

demoMode: true requires an inline catalog, performs no external HTTP requests, and uses one built-in deterministic recall fixture for automated QA. With demoMode: false (the default), recallSources remains required and production behavior is unchanged.

Each recall source supplies mapping.id and mapping.title, plus any matchable fields. Mappings are property-only dot paths, for example results.items or Products.Model; array traversal projects the named property from each array object. They are not JSONPath and cannot execute filters or code. List fields may be arrays or strings separated by |, ;, comma, or newline.

JSON recall feeds may use recordsPath to select their record array. CSV feeds normally omit it. At least one identity path (brand, models, or upcs) is required. The run summary reports both total and matchable recalls and fails if a non-empty feed has no matchable records, which catches a common bad-mapping failure. See examples/input.json.

Scoring

Evidence	Score
Exact UPC/GTIN (at least 6 digits)	100
Exact normalized model	70
Exact normalized brand	25
Manufacturing date inside a supplied window	+5

The default minimum is 70. By default a model only counts when brand also matches, preventing common model-number collisions. UPC stands alone. A known catalog manufacturing date outside the notice window rejects the match. Brand-only matching can be enabled deliberately by lowering minScore; it is likely to be noisy.

Normalization never uses fuzzy or semantic inference. UPCs retain leading zeroes after non-digits are removed. Always inspect evidence and the official notice.

Bounded operation

Default / hard limits are 10,000 / 50,000 catalog rows, 5,000 / 25,000 recalls per source, 10,000 / 100,000 output matches, 5 MB / 25 MB per response, 30 / 60 seconds per request, and 4 / 10 concurrent downloads. Processing fails closed on a malformed or unavailable source; it never silently reports a partial clean bill of health.

All outbound destinations come from Actor input. They must use public HTTPS on port 443. DNS answers are checked and pinned for each connection, redirects are same-origin only, response compression is rejected, and streamed bodies are size-limited. See SECURITY_REVIEW.md.

Output and repeat runs

Dataset rows are stable in shape but are not deduplicated across separate runs. Use (catalogItemId, sourceName, recallId) as the business key in downstream systems. checkedAt is the scan timestamp. A run with no matches produces an empty dataset and an OUTPUT summary with exposureMatches: 0.

For repeat monitoring, invoke this private Actor through your own approved process. This repository intentionally contains no schedule, webhook, credentials, proxy configuration, publishing, or deployment setup.

canary_input.json is the deterministic no-network QA input. It always matches the built-in demo recall and writes one exposure without depending on an external recall service.

License and responsibility

The implementation is private/internal unless the owner chooses a license. Feed availability, accuracy, redistribution rights, and regulatory duties remain the operator's responsibility.