Perishable Price Timing Engine

What it is

Given an item's observed price history, it returns buy / wait / watch with a plain-language reason and an honest confidence tier. It holds no opinions about your database, fetches nothing, and predicts no future price.

Why not just generate this

Each rule below is a bug hit with live pricing data:

• Never blend two marketplaces into one price path. Different sources price different inventory at different levels; interleaving them manufactures trends that don't exist — verified live: $112.87 alternating hourly with $101.91 reads as a steady -4% slide with zero real movement.
• Least-squares slope, not a two-endpoint delta — one noisy snapshot must not flip a verdict.
• A sustained slide outranks "it's at its low." A falling price is at its minimum by definition, so a cheapness-first rule says "buy" on exactly the days you should wait.
• Confidence is honest and separate from the verdict — three points is a guess, and the reason string says so.
• Perishability cuts both ways — "cheapest so far" with 90 days left is weak; the same price with 3 days left is a buy.

Proof

32 tests, each named after the failure it prevents: anti-contamination, slope robustness, confidence tiers, verdict precedence, perishability in both directions, and sell-side net-payout math.

Also included

`bestNetPayout()` — the sell-side mirror. Best net payout across marketplaces after fees, because a lower sticker price on a low-fee venue routinely beats a higher one.

Delivery

Source delivered as a private repository invite within 24 hours of purchase. Single-product commercial license: use and modify in any number of products; no redistribution or resale of the source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function slopePct(lows: number[]): number;
  export function pickCanonicalSeries<T extends { low: number; source?: string | null }>( rows: T[], sourcePriority: string[] = DEFAULT_SOURCE_PRIORITY, ):;
  export function confidenceFor(points: number): Confidence;
  export function timingVerdict(history: PricePoint[], opts: TimingOptions = {}): TimingVerdict;
  export function bestNetPayout(options: SellOption[], costBasis?: number): SellVerdict | null;

  export type Signal = "buy" | "wait" | "watch";
  export type Confidence = "learning" | "low" | "medium" | "high";