Fordeal

The website's category and search grid for an agent: products with the product price of their shown offer (`lowest_goods`, in the `deliver_to_country` currency; its shipping `lowest_shipping` and the total `lowest_total` beside it, with capture time and `price_status` verified | estimate | incomplete), number of shops, best shop and trust label. Give `query` (free text, every word must match; 8 to 14 digits are an EAN, matched exactly) and/or `category` (a slug from GET /api/v1/deals/categories, e.g. letni-pneumatiky, mobilni-telefony), or neither to browse the whole catalogue (the website's /produkty page), or `slugs` (product slugs) to compare named products side by side; then any filters: price_min/price_max, brand, shops, shop_country (e.g. DE for offers from Germany), in_stock, on_sale, free_shipping, min_shop_rating, min_product_rating, attr (key:value pairs); sort price (lowest product price first, the default), price_desc, total (lowest total with shipping, opt-in; or include_shipping=true), total_desc, discount, shops, popular, rating, score, name. Answers at most `limit` products (default 20) from `offset`; `total_matches` counts every match, and `facets: true` adds the brands, shops, price range and attribute values with counts over the whole filtered list. With `query`, `query_match` says how the list answers it (all = every word found; partial = some words were dropped or matched only by typo tolerance; fallback = no product has the words, the list is the closest category's; none = nothing matches) and every product carries `match` (exact | close = another variant | partial = the name lacks some query words, `match_note` names them | fallback = not a match); never present a partial or fallback product as the asked-for item. Next: find_best_price with a product name for the full card with every offer, or price_history with `slug`.

The /kontakt form without the website: `name`, `email` (where the answer goes), `topic` general | support | cooperation | privacy and `message` (10 to 4 000 characters). The message goes as one notice to hello@fordeal.ai with the sender as Reply-To; a person answers by e-mail. The sender gets no automatic e-mail (the answer here is the confirmation of receipt, with `id`). The same message twice on one day answers the same id with `duplicate: true`. A shop that wants to be compared uses register_shop; a partner, the media or a creator may use send_cooperation_inquiry for a structured request. Public, no key; five messages a minute per caller.

The cooperation forms (docs/texty/formulare.md 2–4) without the website. `kind` partner (an affiliate network, a feed provider or a technical integration: organization, website, markets as ISO codes, cooperation_type affiliate | feed | integration | other, message = the offer and its terms), media (name, organization = the newsroom, message = the topic or the information needed, optional deadline YYYY-MM-DD and links) or creator (name or channel, website = the main channel, topic = the content's topic and audience, message = the idea, optional links: other channels, media kit). A shop that wants to be compared uses register_shop instead. A person reads every message; the sender gets a confirmation of receipt (not an approval) and the operator one notice. The same message twice within a day answers the first id with duplicate true. Public, no key; five messages a minute per caller. 503 not_available until migration 0065 is applied.

Creates (or resets) the signed-in person's watch of one product (one per product). Fordeal mails the person when the recommended total for `deliver_to_country` (goods + shipping, same meaning as on the website) falls under `target_total`, never twice for one price and at most once a day. Without `target_total` the target is today's total: the mail comes when the price really drops (by the currency's step, e.g. 50 CZK). Today's total is stored as saved_total. Needs the person's access token. Answers the watch as list_my_price_watches shows it.

`shared: true` makes a read-only link (a new random token; an older link stops working); `shared: false` removes the link. The link shows the plans at today's prices and the name, never the owner.

Signs the person out: scope global (default) revokes every session of the account on every device, local only the session of this token. The access token is refused from then on; the person needs a new e-mail sign-in link. Saved favourites, lists and watches stay.

The products the home page's first row shows, found by the data and not by a list of model names: new products people look for, up to 12, each a summary like search_products (total price with shipping at a rated shop, shops, in stock, capture time) plus `trending` with `score`, `parts` (the points of generation, newness, interest, gsc, growth, keyword, seed) and `raw` (model number and its place among the line's generations, days since the family entered the catalogue, decayed interest, Search Console weight, shops that started to list it, variants). A product qualifies when its model number is the newest or the one before in its line (iPhone 18 against iPhone 17), or its model family entered the catalogue in the last 75 days, and someone searched for it, clicked to a shop, found it on Google or a shop started to list it; the score adds model generation 40, newness 10, searches (halved every 7 days over 28 days) and human clicks 25 × log2(1 + n), Search Console 15 × log2(1 + n), new shops 12 × log2(1 + n). Colours and capacities are one card (the cheapest variant); at most 4 cards per category, 3 per brand and 3 per shop. Only products with two or more shops, a rated shop with known shipping and a price in stock; a shop on the ČOI/SOI risk list is never shown. Recomputed by the worker each night; `generated_at` says when, null before the first run. Next: get_product with a product slug for the full comparison.

Changes one of the signed-in person's lists: `name` renames it; `shared: true` makes a read-only link (a new random token, an older link stops working), `shared: false` removes the link. The link shows the list's name and products at today's prices, never the owner, the notes or the saved prices. Another id answers not_found.

Changes only the fields sent: name (at most 40 characters, empty string clears it), locale (language tag of our e-mails, e.g. cs), country (one of the markets of get_my_profile, null clears it), watch_emails (false pauses every active price watch of the account and remembers which; true resumes exactly those, never a watch the person paused themselves). Needs the person's access token. Answers the profile with `changed` (and watches_paused / watches_resumed).

Changes one of the signed-in person's watches: `paused: true` stops the mails until `paused: false`; `target_total` sets a new limit (null = any real drop under the saved total). Only the token's own watches; another id answers not_found.

After register_shop: publish <meta name="fordeal-verification" content="TOKEN"> on the shop's home page, or the token as the whole content of https://DOMAIN/fordeal-verification.txt, then call this with the domain and the token from `verification.ownership`. One request to each address with Fordeal's identified bot (www. and the bare host). The answer: ok with the method (meta | file, or already), or `error.code` not_found (no request with this domain and token) | not_verified (neither place carries the token; a CDN cache may take minutes). Proving the domain marks the request as confirmed, like the e-mail link; the operator still decides. Public.

A household gives its e-mail and the last day of its fixed electricity or gas price (fixation_end YYYY-MM-DD, today to 5 years ahead); optionally the distributor area, today's supplier (supplier_id from energy_suppliers) or product (current_offer_id from compare_energy products) and the consumption. Double opt-in: the e-mail first gets a confirmation link and nothing else is sent before the person clicks it (an agent cannot confirm for the person). A confirmed watch gets one e-mail 45 days before the end with the offers cheaper for its need (from the official price lists; an estimate). Every mail has a cancel link. Unconfirmed watches are deleted after 7 days, every watch 30 days after its end date. No account, no contract, no commission. At most 5 watches per e-mail. Ask the person for consent before passing their e-mail.

No account (UX-72): the person gives an e-mail and Fordeal mails them when the recommended total for `deliver_to_country` (goods + shipping, the product page's meaning) falls under `target_total` (default: today's total, i.e. any real drop by the currency's step), never twice for one price and at most once a day. Double opt-in: the address first gets only a confirmation link; nothing else is sent before the person clicks it (an agent cannot confirm for the person). Every alert has pause and cancel links that work without signing in (GET/POST /api/v1/price-watches/link). Unconfirmed watches are deleted after 7 days, confirmed ones 365 days after the confirmation. One watch per address and product, at most 20 per address; the answer is the same whether the address is known or not. Ask the person for consent before passing their e-mail. A signed-in person can use set_price_watch instead (no confirmation needed).