epromo

ePromo.ee Grocery Shopping

CRITICAL: For product searches and browsing, ALWAYS use epromo-search.sh. NEVER open epromo.ee in the browser to search or browse products. The browser is ONLY needed for cart operations (add/view/clear) because Cloudflare blocks API PUT requests.

Build an ePromo.ee grocery cart through conversation, or help the user research and compare products.

Note: ePromo is a HoReCa/wholesale-oriented store — minimum order quantities are often 1–10 kg, and packages are larger than in regular grocery shops. Keep this in mind when suggesting products.

Architecture

ePromo.ee is behind Cloudflare WAF. This plugin uses a hybrid approach:

• Search: via epromo-search.sh (uses curl_cffi with Chrome TLS impersonation + authenticated POST to search-products)
• Cart operations (add, view, clear): via javascript_tool in a Chrome browser tab (Cloudflare blocks non-browser PUT requests)

Prerequisites

• curl_cffi Python package installed (pip3 install curl_cffi)
• For correct search results (Estonian names, stock availability): set environment variables (see Setup)
• For cart operations: an epromo.ee tab open and logged in in the Claude-in-Chrome browser
• If not logged in, navigate to https://epromo.ee/auth/login and help the user log in first

Setup (First-Time or When Credentials Expire)

The search script needs authentication for correct results. Credentials are stored in ~/.config/epromo/credentials and persist across sessions.

If credentials are already saved, skip this section.

To set up or refresh credentials:

1. Find the ePromo tab using tabs_context_mcp — must be logged in at epromo.ee
2. Extract token and address by running this via javascript_tool:

JSON.stringify({
  token: document.cookie.match(/token=([^;]+)/)?.[1] || 'not found',
  address: decodeURIComponent(document.cookie.match(/DeliveryAddress=([^;]+)/)?.[1] || 'not found')
})

3. Save credentials using epromo-setup.sh:

epromo-setup.sh <token> <address>

4. For cf_clearance (optional, needed if Cloudflare blocks requests): ask the user to copy this cookie value from browser DevTools (Application > Cookies > cf_clearance), then re-run:

epromo-setup.sh <token> <address> <cf_clearance>

Token validity: ~365 days. cf_clearance: hours to days (refresh when searches start failing).

Workflow

1. Search for products using epromo-search.sh (fast, no browser needed if env vars set)
2. Present results — show name, price, product code, stock amount, and unit; let the user confirm or refine
3. Find the ePromo tab using tabs_context_mcp — look for a tab with epromo.ee in the URL
4. Add confirmed items to cart via javascript_tool in the browser tab
5. Show cart summary so the user can review before checkout
6. When done, tell the user to open epromo.ee in their browser to complete checkout

Always confirm product choices with the user before adding to cart. If a search returns multiple close matches, ask which one they want.

Product Research / Comparison Workflow

When the user wants to browse, research, or compare products (not necessarily buy):

1. Search for the relevant categories using epromo-search.sh
2. Present results in a clear table: name, price (with VAT), unit price, stock, min order
3. If comparing across stores, present side-by-side
4. Only proceed to cart operations if the user explicitly asks to buy

Scripts

All scripts are in the scripts/ directory relative to this file.

epromo-search.sh

Search for products by keyword. Uses the search-products POST endpoint with authentication for Estonian names and correct stock levels.

epromo-search.sh <term> [count]

• term — search query (e.g. "piim", "juust", "kana filee")
• count — number of results, defaults to 6
• Reads credentials from ~/.config/epromo/credentials (run epromo-setup.sh first)

Returns JSON array with: id, name, price, unit, inStock, inStockAmount, minAmount, priceCoeff, storageType.

epromo-setup.sh

Save authentication credentials to ~/.config/epromo/credentials.

epromo-setup.sh <token> <address> [cf_clearance]

• token — JWT token from browser cookie named token
• address — delivery address ID from browser cookie named DeliveryAddress
• cf_clearance — optional, Cloudflare clearance cookie (httpOnly, must be copied from DevTools)

Browser API Reference (Cart Operations)

Cart operations must be made via mcp__claude-in-chrome__javascript_tool in an epromo.ee tab.

Add Items to Cart

const token = document.cookie.match(/token=([^;]+)/)[1];
fetch('/api/proxy/quick-search?search=' + encodeURIComponent(TERM) + '&count=1&page=1')
  .then(r => r.json())
  .then(data => {
    const product = data.products[0];
    return fetch('/api/proxy/update-b2c-cart', {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' + token },
      body: JSON.stringify({ cartItems: [{ amount: AMOUNT, product: product }] })
    });
  })
  .then(r => r.json())

• The product object from search must be passed as-is to the cart API — it needs the full object
• amount — quantity to add (respect minimumAmount from search results)
• Requires Authorization: Bearer <token> header — extract token from cookies
• Multiple items can be added at once by including multiple objects in cartItems array

Add Multiple Items at Once

const token = document.cookie.match(/token=([^;]+)/)[1];
// products = array of { product: <full product object from search>, amount: N }
fetch('/api/proxy/update-b2c-cart', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' + token },
  body: JSON.stringify({ cartItems: products })
}).then(r => r.json())

View Cart

const token = document.cookie.match(/token=([^;]+)/)[1];
fetch('/api/proxy/get-b2c-checkout-summary', {
  headers: { 'Authorization': 'Bearer ' + token }
})
  .then(r => r.json())
  .then(data => JSON.stringify(data, null, 2))

Clear / Update Cart

To update quantities or remove items, send the full desired cart state:

const token = document.cookie.match(/token=([^;]+)/)[1];
fetch('/api/proxy/update-b2c-cart', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' + token },
  body: JSON.stringify({ cartItems: [] })  // empty array clears the cart
}).then(r => r.json())

Important Notes

• Cloudflare WAF: Search works via curl_cffi (Chrome TLS impersonation). Cart PUT requests MUST go through the browser.
• Authentication: JWT token is in the token cookie (~365 days). cf_clearance expires in hours/days.
• Language: With authentication and languages: 'et' header, product names are in Estonian. Without auth, names default to English.
• Stock levels: Require addressid header for accurate availability. Without it, all products show as out of stock.
• Minimum amounts: Many products have minimumAmount > 1 — ePromo is HoReCa/wholesale, so packages are large (1–10 kg typical).
• Storage types: Products have storageType — "termo" (refrigerated), "frost" (frozen), "dry" (ambient).
• Price: Use priceWithVat for the displayed price. priceCoefficient shows the per-unit price (e.g. "0,96€/l").