Specialty Coffee Roaster Price & Stock Feed

Structured, JSON-Schema-validated product data from specialty coffee roasters' public Shopify storefronts (/products.json). Built for AI agents, price-monitoring pipelines and analysts: stable IDs, one record per product + bag size, normalized weight in grams, price_per_100g, auto-detected currency, and an optional change-event mode.

Quick facts (for agents)

• Input: {"stores": ["onyxcoffeelab.com"], "mode": "snapshot" | "changes", "maxStores": 30, "stateKey": "default"} — all optional. Empty stores = bundled list of 30 verified roasters (robots.txt permits, products.json public).
• Output: default dataset (records or events) + OUTPUT key-value record with a run summary {stores_ok, failed, records, invalid_dropped, events, qa}.
• Record ID: record_id = "<domain>:<product_id>:<lowest variant_id in size group>", stable across runs.
• Freshness: live at run time (fetched_at, UTC ISO 8601). Typical run: ~3 s per store.
• Validation: every record is checked against the JSON Schema (src/schema.json, draft 2020-12); invalid records are dropped and counted.

Modes

snapshot (default)

One item per product+size. Grind-only variants are merged:

field	meaning
title, variant_title	product name, size label (e.g. 12oz, 250gms)
price / price_max	min / max price across grind options (store base currency)
price_varies_by_grind	true if grinds are priced differently
currency, currency_source	ISO 4217, detected from /meta.json → /cart.js → page
available	true if any grind is in stock
grind_options[]	{grind, variant_id, price, available}; green/unroasted excluded
weight_g, weight_source	grams from variant_title / product_title / shipping_grams (approx.)
price_per_100g	only from title-derived weights
compare_at_price, on_sale	Shopify compare-at price and derived sale flag
variant_ids[], sku, vendor, product_type, tags[], product_url, image_url, published_at, updated_at, fetched_at, source	metadata

Example:

{"record_id":"proudmarycoffee.com:10311889551576:52647587250392","title":"PANAMA | Bambito Estate | Yellow Catuai | Natural","variant_title":"250gms","price":42.0,"price_max":42.0,"currency":"USD","available":false,"weight_g":250.0,"price_per_100g":16.8,"grind_options":[{"grind":"Whole Bean","variant_id":52647587250392,"price":42.0,"available":false}]}

changes

Compares the current fetch with the baseline saved by this actor's previous run (named KV store coffee-roaster-feed-state, key baseline-<stateKey>), pushes only events, then saves the new baseline. The first run returns 0 events (qa: no_baseline_first_run). Schedule it (e.g. daily 03:15 Europe/Nicosia) for monitoring.

Event types: new_product, price_change (old, new, pct; qa_flag: large_price_change_review if |Δ| > 60%), on_sale, restock, sold_out, removed. Each has record_id, detected_at, baseline_at. QA: if a store's record count drops > 30% (or the fetch fails), removed events for that store are suppressed and reported in OUTPUT.qa.

Notes & limits

• Only public storefront data; no login, no personal data; polite rate limit (1.5 s between stores/pages).
• Non-coffee items (merch, equipment, milk, gift cards) are filtered by keywords — a few edge cases may remain.
• shipping_grams weights include packaging; price_per_100g is not computed from them.

Pricing (suggested, pay-per-event)

• result (each record or event pushed): $0.002 → $2.00 per 1,000 results.
• No start fee.
• Full 30-store snapshot ≈ 7,600 results ≈ $15; daily changes runs typically cost cents.