Price History Builder

Every price monitor tells you the price changed. This one remembers every price it has ever seen for a product and turns that history into analytics nobody else offers: volatility, promo cadence, price bands, a next-drop estimate, and trend.

It is stateful by design — the value it delivers builds up run over run. Run it once and you get a snapshot. Run it on a schedule for a few weeks and you get a real picture of how a product actually gets priced.

Honesty first: what this actor can and cannot know

• History only exists from the first run onward. This actor cannot see prices from before you started tracking a product. A product's first-ever run always reports isFirstRun: true with a one-point series — volatility, bands and cadence only become meaningful after several runs, and cadence needs multiple discount cycles before it means anything at all.
• The next-drop estimate is extrapolation, not a promise. It projects a window from the gaps between past discount events. A shop can change its pricing strategy at any time without warning. Every prediction row says so explicitly in its note field, and the actor refuses to predict at all until minEventsForPrediction discount events have been observed.

Two ways to feed it prices

1. Scrape URLs. Put product pages in products. The price is auto-detected from JSON-LD, microdata/OpenGraph, common price containers, or a text scan — the same selector-free detection used by Price Drop Monitor. Supply priceSelector per item to override it.
2. Supply a price list. Put {"key":"sku-123","price":19.99} objects in prices — your own feed, a spreadsheet export, a previous scrape, anything. This needs no network access at all, which is what makes the analytics testable fully offline and reusable as a pure analytics step in any pipeline that already has prices.

You can mix both in the same run; they accumulate into the same per-key series in the named state store (stateStoreName).

What gets computed, per product, every run

Field	What it means
volatility	Sample stdev and coefficient of variation (CV) of the whole series — CV is scale-free so a $50 item and a $5,000 item are comparable.
promoCadence	Detected discount events (price ≥ promoDropThresholdPercent below a rolling baseline), how often they happen, average gap in days, typical discount depth, longest gap.
priceBands	min / max / median of the series, and currentPercentile — is today's price actually good, or is it near the historical ceiling?
nextDropEstimate	A predicted window derived from the observed cadence, with a confidence (LOW/MEDIUM/HIGH) and an explicit note that it is extrapolation.
trend	RISING / FALLING / STABLE (a trendFlatBandPercent deadband absorbs noise) plus a linear-regression slope.
alert	true when priceBands.currentPercentile <= alertPercentile — today's price is at or below the historical Nth percentile.

Input

{
  "products": [
    "https://shop.example/product/123"
  ],
  "prices": [
    { "key": "own-feed-sku-9", "price": 44.5, "currency": "USD" }
  ],
  "maxHistory": 90,
  "promoDropThresholdPercent": 8,
  "alertPercentile": 25
}

Output

Per product: key, price, checkedAt, isFirstRun, historyLength, priceHistory (the capped series), volatility, priceBands, promoCadence, nextDropEstimate, trend, alert.

Who uses it

Buyers deciding whether today's price is actually a deal · dropshippers timing restocks around a competitor's known sale cadence · deal-alert sites that want a statistically grounded "buy now" signal instead of a gut call · anyone who has ever screenshotted a price history chart by hand.