flan
70c67901b8
The compat badge was red on bookkeeping, not on compatibility: the check passed 16/16 and the run then failed trying to commit the refreshed matrix and open a PR. That step should never have existed here — GitHub is a read-only mirror of Gitea, so anything a bot pushes is clobbered by the next sync. It now publishes the matrix to the run summary and the workflow only needs contents:read, so the badge means what it says. The README had grown into an implementation document. Endpoints, markup traps, the login handshake and the drift-detection design move to docs/internals.md; what is left is installation, entities, events, the dashboard, requirements and troubleshooting.
3.4 KiB
Internals
How this integration talks to freshharvest.com. Nothing here is needed to use it — see the README for that. This is for anyone changing the code, or working out why it broke.
How it works
Fresh Harvest is not on Shopify, Farmigo, or Local Line — the page metadata
reports Vy Technology - Custom Code. It is a server-rendered jQuery site with
no JSON API and no mobile app, so this integration signs in and parses HTML.
Login is a two-step handshake:
GET /s/popup/loginreturns the form plus two hidden anti-replay fields,LoginSecurityandSubmitToken, minted per session.POST /s/submit/loginwithLoginEmail,LoginPassword, both tokens, and an emptyRedirect, yielding anfh_session_authenticatedcookie.
The tokens are bound to the cookie issued by step 1, so both requests must share a cookie jar.
A refresh is three GETs: /p/dashboard/details for the delivery day, next
arrival, both upcoming carts and their totals; /p/dashboard/manage-subscriptions
for standing orders; and /p/dashboard/pause-deliveries for vacation holds.
Three requests every six hours.
Write actions cost more, because nothing can be constructed offline — every mutating endpoint is guarded by rotating per-render tokens, so each action fetches the page that offers it, reads fresh tokens, checks they describe the intended target, and only then submits.
Markup notes
Six traps, none guessable from the outside:
- HTTP status means nothing. Every
/p/*path returns 200, including invented ones. Signed-in state is detected by the presence of a Sign Out control, not by a status code. cart-contents-skippeddoes not mean the order was skipped. It marks the locked cart — the one past its cutoff and arriving next. Treating it as "skipped" reports the wrong delivery as cancelled. The reliable signal for "can still be changed" is a non-empty.cart-customize-wrapper.- The free-delivery bar only renders on carts below the threshold. An order that already qualifies has no bar at all, so the threshold is read once from whichever cart shows it and applied to every order.
- Popups and AJAX replies are fragments, not pages. They carry no navigation, so a "am I still signed in?" check based on a Sign Out control reads every one of them as logged out. Skip could not run at all until these were fetched with that check disabled.
openPopupis written both("x","y")and("x", "y"). A regex requiring no space silently matches nothing on the pages that use the other form — which is every basket page.- A
<select>'sidis not its POST field. The subscribe form's frequency control isid='FrequencyID'butname='popup-toggle'. PostingFrequencyIDis accepted and does nothing.
Consistency guarantees
Two invariants hold against the portal's own arithmetic, and tests assert both:
next_delivery_box_price+next_delivery_add_ons==next_delivery_subtotalopen_order_free_delivery_remainingreaching0.00always coincides with a0.00delivery fee
Drift detection
freshharvest.com has no API and no stability contract — this integration reads HTML and posts to form endpoints, so a redesign can change what a value means without changing its shape. tools/compat.py records every assumption and CI asserts them against the live site daily, refreshing this table and opening an issue on drift.