Amazon MAP & Buy Box Evidence Monitor

A private Apify Actor for brand-protection teams. It checks up to 1,000 user-declared public HTTPS product pages, extracts the visible offer price and Buy Box seller, applies safely quantifiable coupons, compares the result with a supplied MAP threshold and prior seller, and produces a timestamped evidence pack.

This is an evidence triage tool—not a legal decision engine and not a bypass for site access controls. Result status is separate from the legacy MAP/change finding: EVIDENCE_FOUND (supported price and/or featured seller), INSUFFICIENT_DATA (verified normal product page with no offer signals), ACCESS_LIMITED (challenge/consent), PARSE_FAILED (unconfirmed/unsupported page or malformed supported signal), FETCH_FAILED (HTTP/network failure). Only the first two are successful investigations. Others never pass the Canary gate.

Normal-page proof requires the existing product title and a page ASIN matching the requested Amazon product path. Missing price/seller is represented by null, not a default. Without price, mapEvaluation is NOT_EVALUATED; false candidate flags are not a compliance conclusion. Generic JSON-LD merchants and other-offer sellers are not treated as the featured Buy Box seller. Observed signals retain bounded raw text, source, normalized value, URL and timestamp. Currency is the configured comparison currency, not independently inferred.

What the run produces

• OUTPUT in the default key-value store: the authoritative run record defined by tests/output-record.schema.json.
• One dataset row per target for filtering and export.
• A PNG evidence card per successfully fetched target. It is a screenshot of the normalized observation, not a claim to be a pixel-perfect screenshot of the remote page.
• Optional fetched HTML, disabled by default.
• SHA-256 of fetched response bytes for later integrity checks.

Input

See examples/input.json. Each target requires an HTTPS URL and may include asin, mapPrice, previousBuyBoxSeller, and label. Currency is run-wide. The Actor does not convert currencies.

{
  "targets": [{
    "url": "https://www.amazon.com/dp/B08N5WRWNW",
    "mapPrice": 30,
    "previousBuyBoxSeller": "Authorized Retailer"
  }],
  "currency": "USD"
}

Coupon-adjusted price is calculated only for unambiguous fixed-value or percentage coupons visible in supported markup. Eligibility, clipped-coupon state, tax, shipping, subscription discounts, and checkout-only promotions are not inferred.

Local verification

Requires Node.js 20+.

npm ci
npm run typecheck
npm test
npm run build

To run locally with Apify storage emulation:

$APIFY_INPUT_KEY=INPUT npm start

Place input through the normal Apify CLI/local-storage workflow. Local tests use synthetic credentials only; no paid proxy requests occur locally.

Limited Residential fallback

Direct HTTPS is always attempted first, at most once per target. Only a classified access-limited page or HTTP 403/429 enables official Apify RESIDENTIAL/US fallback, only inside the Apify runtime and only for amazon.com/www.amazon.com. Normal INSUFFICIENT_DATA never triggers proxy usage. At most two Residential requests (including redirect hops) use distinct SDK sessions; the first normal page ends fallback. There are no implicit retries, browser assets, CAPTCHA solving, or third-party proxies.

Each Residential CONNECT uses a validated public DNS pin while preserving the Amazon TLS hostname and Host header. Every redirect is revalidated. Encoded and decoded body limits remain enforced. SDK credentials remain in memory, verbose transport debugging is rejected, and authenticated proxy URLs are never stored or logged. Results expose only bounded attempt counts, response bytes, route and direct classification. Group access failure returns ACCESS_LIMITED with RESIDENTIAL_PROXY_UNAVAILABLE; other transport errors do not pretend to be missing offer evidence.

Residential traffic is billed by Apify. See PRICING_PROPOSAL.md; pricing is a proposal only. The private canary requires an explicit Actor/bundle-specific proxy cost approval; default platform policy still denies proxy spending.

Security boundaries

Only user-declared HTTPS port 443 targets are fetched. Every initial URL and redirect is validated; DNS answers containing private/reserved addresses are rejected; the approved public address is pinned into the TLS request to prevent DNS rebinding; certificate validation retains the original hostname. Redirects, compressed and decompressed bytes, timeout, and concurrency are bounded. See SECURITY_REVIEW.md.

Operational expectations

tests/output-record.schema.json is the structural OUTPUT contract and represents all five investigation statuses, including failed fetches with unobserved fields. tests/canary-output.schema.json is a separate, stricter one-target functional acceptance contract used by the production private lifecycle. Its legacy outputValid receipt means functional acceptance, not general OUTPUT structural validity. A structurally valid ACCESS_LIMITED, PARSE_FAILED, or FETCH_FAILED record never qualifies for READY_TO_PUBLISH.

Static HTML extraction is deliberate: it keeps network behavior auditable and blocks browser subresource sprawl. A verified normal product page with no offer signals returns INSUFFICIENT_DATA. A present but uninterpretable price signal returns PARSE_FAILED; an unverified layout cannot be labeled insufficient. A human should open the evidence card and source URL before any enforcement action.

Status

Private candidate: READY_TO_PUBLISH requires the current exact build and functional Canary evidence; source inclusion or process exit 0 alone is insufficient. Publishing itself is intentionally out of scope.