🚀 Expand automatic coupon insertion to more stores

[AminDhouib]

Updated 2026-08-15. The original version of this issue (Aug 2025) told contributors to add a store by editing apps/caramel-extension/supported.json and adding stores/<name>.js. Since the WXT migration (v1.4.0, PRs #191–#199) neither exists — see the thread below for the details. This issue now describes how store support actually works and how you can help.

How store support works now

Caramel knows coupon codes for thousands of stores, but auto-applying them at checkout needs the extension to know where a store's promo field, apply button, price container, etc. live.

• The extension's apply engine (apps/caramel-extension/coupon-apply.js) is generic-first: it tries store-agnostic selectors for the coupon input, apply/remove buttons, "applied" state and error text.
• Where a store needs more, a per-store config (show-input / dismiss / coupon input / apply button / price container / success & error indicators / remove selectors) is served to the extension at runtime from the app's store_configs catalog table.
• Those configs are produced by our internal coupon pipeline, which discovers a store's selectors, verifies them against the real extension, and publishes them to the catalog. There is no in-repo file to edit for a new store, and no stores/<name>.js code path.

How you can help

1. Request a store — open a 🏪 Store Request with the store URL and anything odd about its checkout (promo field hidden behind a "Have a code?" link, iframes, blocking modals, cart-only vs checkout-only field). If you've already dug out selectors, include them — they're a useful hint even though the pipeline re-derives and re-verifies them.
2. Report a store where auto-apply misbehaves — a bug report with the store, page URL and what the extension did (or use the in-extension "report a problem" link).
3. Improve the generic engine (code PRs) — anything that lets coupon-apply.js succeed on more sites without a per-store config: broader generic input/apply/remove/applied-state selectors, collapsed promo fields, dynamic DOMs (MutationObserver), iframes. Open a PR against apps/caramel-extension with tests under apps/caramel-extension/tests; pnpm lint / prettier must be green. Keep selectors narrow to avoid false positives.
4. Docs — a CONTRIBUTING.md capturing the above (plus dev setup from docs/LOCAL-DEV.md) would be welcome.

Questions welcome here or on our Discord.

[SusieeTheLinuxUser]

Heads up for anyone picking this up: the instructions in the issue description are out of date as of the WXT migration (v1.4.0, PRs #191–#199).

supported.json and the stores/ folder for per-store custom JS don't exist in the repo anymore. Store configuration now lives in the app's own Postgres database (store_configs table — see DESIGN.md §2, "Coupons Ownership Inversion"), and the extension's coupon-apply engine (apps/caramel-extension/coupon-apply.js) runs off generic, store-agnostic selectors (GENERIC_APPLIED_SELECTORS, GENERIC_REMOVE_SELECTORS_SCOPED, etc.) with optional per-store overrides — coupon input/submit/remove selectors — that are expected to come from that DB-backed config, not from a file a contributor edits and PRs.

That means, as currently worded, this issue can't actually be completed the way it describes: there's no supported.json to edit, and the current build has no code path that reads a stores/<name>.js file at all.

Could a maintainer clarify how external contributors are meant to add store support now? A few options that would make this actionable again:

• If store configs are meant to stay internal-only (e.g. seeded via the ingest pipeline / admin tooling), it'd be worth relabeling this away from good first issue and closing or repurposing it.
• If there's an intended contributor path (e.g. a PR that adds a row to a seed/migration file, or a request-queue table), pointing to it here (or in a CONTRIBUTING doc) would let people actually act on it.

Happy to help update this issue's description or CONTRIBUTING.md once the current process is confirmed.

[AminDhouib]

Thanks @SusieeTheLinuxUser — you're right on all counts, and sorry for leaving this stale.

Since the WXT migration (v1.4.0) supported.json and stores/*.js are gone. Per-store apply configuration (show-input / dismiss / coupon input / apply button / price container / success & error indicators / remove selectors) now lives in the app's store_configs table and is served to the extension at runtime; the apply engine (apps/caramel-extension/coupon-apply.js) is generic-first and layers those DB-backed overrides on top. Those configs are produced by our internal coupon pipeline (a separate, private project) which discovers a store's selectors, verifies them against the real extension, and publishes them to the catalog — so there is intentionally no in-repo file for contributors to edit anymore, and hand-authored selectors wouldn't survive that loop unchanged anyway.

We still very much want help getting more stores auto-applying. What's useful now:

1. Request a store — open a 🏪 Store Request issue with the store URL and anything odd about its checkout (promo field hidden behind a "Have a code?" link, iframes, blocking modals, cart-only vs checkout-only field). If you've already dug out selectors, drop them in — they're a helpful hint for the pipeline even though it re-derives and re-verifies them.
2. Report a store where auto-apply misbehaves — a bug report with the store, page URL and what the extension did (or the in-extension "report a problem" link). These feed straight back into the pipeline's repair loop.
3. Improve the generic engine (code PRs) — anything that makes coupon-apply.js succeed on more sites without a per-store config: broader generic input/apply/remove/applied-state selectors, collapsed promo fields, dynamic DOMs, iframes. Normal PR against apps/caramel-extension, with tests under apps/caramel-extension/tests.
4. Docs — there's no CONTRIBUTING.md yet. If you'd like to write one that captures the above (plus the usual dev-setup pointers from docs/LOCAL-DEV.md), I'd happily review it.

I'm rewriting this issue's description to reflect the new process and dropping the good first issue label, keeping it open as the umbrella "more stores" issue. Thanks again for the careful write-up.