# Changelog of PricePulse AI — Cross-Marketplace Product Intelligence (`entranced_gelato/price-pulse-ai`) Actor

- **URL**: https://apify.com/entranced\_gelato/price-pulse-ai/changelog.md
- **Full Actor documentation**: https://apify.com/entranced\_gelato/price-pulse-ai.md

## Changelog

All notable changes to this Actor are documented here. The format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres
to Semantic Versioning.

### \[0.2.0] — 2026-05-22

#### Added

- **JSON-LD universal fallback parser** (`src/marketplaces/jsonld.py`). Any
  URL whose host isn't Amazon, eBay, or Walmart is routed to this parser,
  which extracts Schema.org Product nodes (and `@graph` containers) from
  embedded `<script type="application/ld+json">` blocks. Unlocks Target, Best
  Buy, Etsy, AliExpress, Shopify, WooCommerce, BigCommerce, Magento,
  Salesforce Commerce, Squarespace, Wix, and any storefront with Schema.org
  Product markup — without per-site handlers.
- **Webhook alerts** for significant price changes. Set `alert_webhook_url`
  and the actor POSTs a fire-and-forget JSON payload when
  `changes.price_change_flags[].significant == true` AND
  `abs(relative_pct) >= alert_undercut_pct`. Each successful dispatch is a
  separate `webhook_alert_dispatched` chargeable event at **$0.005**. URL
  query strings (where tokens often live) are redacted from the snapshot.
- **`reference_label` + `vs_reference` block.** Set `reference_label` to mark
  one product as the reference; every other snapshot in the run gets a
  `vs_reference: {is_reference, price_delta, price_delta_pct, is_undercut,
  is_lowest_in_run}` block. Closes the "who is undercutting me" question
  without needing client-side joins.
- **`dry_run` preview mode.** Build snapshots, set OUTPUT, but DO NOT push to
  the dataset and DO NOT charge. Lets new buyers validate the output shape
  before committing.
- **`use_apify_proxy` opt-in Residential proxy support.** When enabled, the
  actor routes fetches through Apify Residential, dramatically reducing
  Amazon's CAPTCHA hit rate. Proxy bandwidth is billed by Apify to the run's
  caller, not bundled in this Actor's price.
- **Amazon locale support** (`amazon_locale` input). Targets `us`, `uk`,
  `de`, `fr`, `jp`, `in`, `ca`, `au` for ASIN-derived URLs. User-provided
  URLs always override.
- **Amazon 2-retry exponential backoff** (`0.6s`, `1.5s`) on transient
  5xx / network errors / CAPTCHA pages. Dramatically reduces flaky-run rate.
- **Variant extraction** — `SiteMetrics.variants[]` of `{value, sku, price,
  currency, availability}` populated where the marketplace exposes it (Amazon
  swatches, eBay JSON-LD, Walmart `__NEXT_DATA__`, JSON-LD `hasVariant`).
- **Image gallery** — `core_profile.images[]` carries up to 5 deduped image
  URLs unioned across marketplaces.
- **`keyword_research` mode un-gated** with strict caps. Discovers the top-N
  products per requested marketplace for a search keyword, then snapshots
  each. Default cap 10 per marketplace; hard-capped at 50; total snapshots
  per run bounded at 25.
- 39 new tests in `test_jsonld.py`, `test_webhooks.py`, `test_reference.py`,
  and `test_v02_features.py` (165 tests total, all green).
- 5 new example input JSONs covering webhooks, keyword research, reference
  comparison, JSON-LD fallback storefronts, and dry-run previews
  (`examples/example11_*.json` through `example15_*.json`).

#### Changed

- Bumped actor version to `0.2`.
- Input schema description rewritten to highlight the new capabilities.
- `actor.json` description updated for v0.2 features.

#### Migration notes

- Existing v0.1 inputs continue to work unchanged. All new fields are
  optional with safe defaults.
- The `webhook_alert_dispatched` event needs to be configured in the Apify
  console (Publication → Monetization) before billing fires. Until then,
  webhooks dispatch successfully but no charge is recorded.
- Apify SDK upgrade to v2.5+ is required to actually fire `Actor.charge()`
  for the webhook event. On the current v1.x runtime the call no-ops
  gracefully via the `getattr(Actor, "charge", None)` wrapper — the actor
  is forward-compatible.

### \[0.1.0] — 2026-05-22

#### Added

- Initial public release of the Multi-Marketplace Product Intelligence Tracker.
- `product_list` mode covering Amazon, eBay, and Walmart with rule-based
  normalization, aggregated metrics, change detection vs. a stored baseline,
  and rule-based opportunity insights.
- Optional Anthropic Claude Haiku enrichment for the `reviews_summary` block,
  gated behind `enrichment_model = "anthropic"` + `anthropic_api_key`.
- Per-host rate limiter + robots.txt cache with fail-open semantics on network
  errors and disallow-all on 401/403 responses.
- Pay-per-Result monetization wired around the `product_intel_snapshot` event
  (one chargeable dataset record per processed product group).
- Local operational scripts: `configure_actor.py`, `kill_switch.py`,
  `verify_listing.py`, `smoke_test.py`, and `run_smoke.sh`.
- 94 unit tests covering input validation, every marketplace parser, robots,
  normalization, insights, change detection, the assembler contract, and
  end-to-end synthetic-HTML smoke flow.

#### Known limitations

- `keyword_research` mode is scaffolded in the input schema but intentionally
  returns a `failed` output in v1.0 to avoid surprise bills while the
  per-marketplace search scrapers are battle-tested. Planned for v1.1.
- Marketplace pages that rely on client-side JavaScript rendering are not
  supported in v1.0 — see the Limitations section of the README.