Next.js app for Vercel, meant to sit in a Zoho CRM Web Tab like the other Kleecks dashboards. It lists every won client (licence deals only) and, for each of them, checks the client's home page to see whether Kleecks is still serving it.
One row per client, built from the won licence deals (Licence > 0,
stage 8. Client Won). Clients whose licence is flagged as lost stay in the list.
| Column | Source |
|---|---|
| ▲ alert | licence flagged lost and Kleecks still detected live on the site |
| Client | Final Client when the deal is indirect, otherwise the CRM account. Green when live, red when offline, amber when the page could not be read. The name links to the last licence deal in the CRM |
| Status | live / offline / n/d — hover for the signals found, or the reason |
| Channel | Indirect when Contract & Invoicing Holder = Partner, otherwise Direct |
| Partner | the CRM account of the deal, when indirect (Jakala, Cerved, Neen, FGMC, Execus …) |
| Owner | deal owner of the last licence deal |
| Licence start / end | from the last licence deal, i.e. the most recent renewal |
| Closing date | closing date of that same deal |
| Amount | amount of the last licence deal |
| Total won | sum of every won licence deal of the client |
| Deals | how many won licence deals the client has |
| Licence lost | Licence Lost? on the last licence deal |
| Domain checked | the page that was probed. No badge means it came from the CRM; guessed and map mark the clients whose Website is still missing in Zoho |
Delivery-only deals (Delivery > 0, Licence = 0) are deliberately out of scope.
Everything is sortable (click a header), filterable (search, licence year range, channel, status, licence lost, how the domain was resolved) and exportable to Excel — the export contains exactly the rows you are looking at, in the order you sorted them, with the same colours.
The table opens filtered on the current year at both ends, since the licences that matter are the ones running now; All years clears that and every other filter.
One row per client, keyed on the CRM account id — the Final Client's id for an indirect deal. So the same client bought directly and through a partner collapses into one row, provided the Final Client lookup points at the same account. If a client shows up twice, the indirect deal's Final Client is pointing at a different account record (a brand account, say) rather than the one the direct deals use: fix the lookup in Zoho and the rows merge, taking any false ▲ with them.
The server fetches the client's home page with a desktop Chrome user agent and looks for two independent signals; either one is enough:
- Response headers —
x-optimized-by: Kleecks (https://www.kleecks.com), or thekleecks-debugheader. <body>classes — theKL-*families (KL-D-…,KL-LANG-…,KL-UA-…,KL-URL-…,KL-CMS_URL-LEVEL-…) andsp-HOME.
The class suffixes change from site to site (KL-D-1 on conte.it, KL-D-64
elsewhere), so the families are matched by prefix rather than as fixed strings.
Three states rather than two: a page that loads without any marker is offline (red), but a page we could not read at all — timeout, bot protection, no domain resolved — is n/d (amber), with the reason printed under the pill. That way a client behind a WAF is never reported as having dropped Kleecks, and the ▲ alert cannot fire on a false negative.
The limit worth knowing. The probe runs server-side from a Vercel IP, and the
bot protection in front of the luxury sites (Akamai, Cloudflare) often refuses
those: the request is answered 403 before it ever reaches Kleecks, and the row
reads n/d — blocked. The headers sent are as close to a real Chrome as a
server-side fetch can get, which helps but does not always win. Bulgari, checked
by hand from a normal connection, answers 200 with
x-optimized-by: Kleecks — so n/d — blocked says nothing about the client, only
that we could not look from there.
If a site only carries the markers on a locale path, put that full URL in the CRM
Website — https://www.bulgari.com/it-it/ — and the probe uses the path, falling
back to the root.
Results are cached server-side for LIVE_TTL_MINUTES (3 hours by default), so the
first visit pays for the probes and the ones after are instant. Re-check now
forces a fresh pass.
The answer to n/d — blocked: the same check, run from a normal connection,
posted back to the dashboard. A row reading live with a small via script
under it was answered that way, and the summary strip carries the time of the
last run.
The script only fills the gaps. Where the Vercel probe could read the page its
answer stands, because it is fresher; the local result replaces only the rows
that came back unknown. Hovering a via script row shows what Vercel had
been told — usually HTTP 403 — blocked by the site's bot protection.
Setup → Developer Space → Web Tabs → Create, type URL, address:
https://clients-live.vercel.app/?embed=1
embed=1 drops the Kleecks logo and tightens the padding: the CRM already
supplies a header, and the iframe is short enough that repeating ours costs a
third of the table. The page detects an iframe on its own too, so a Web Tab
created without the parameter still renders compact.
Two things make the embed work, and both are easy to break by accident:
frame-ancestorsinnext.config.jslists the Zoho data centres. Without it the browser refuses to render the iframe at all, with a console error and a blank tab.- The session cookie is third-party in there. Safari blocks it outright,
Chrome blocks it whenever third-party cookies are restricted, and the symptom
is a login that appears to work followed by 401s on every call. So the
embedded copy also keeps the token in
sessionStorageand sends it as theX-WCL-Sessionheader; the server accepts either. The token is only handed to the page when it declares itself embedded — elsewhere the httpOnly cookie stays the only carrier.
The password is asked once per browser session rather than once per day, since
sessionStorage dies with the tab.
A few sites answer neither probe: a WAF that wants a real browser, a domain that
resolves only from inside the client's own network. For those the licence is the
last piece of evidence available. A client that is won, not flagged lost, and
whose last licence deal runs past today is live by contract, so the row shows a
hollow green live pill with via CRM under it.
The inference is one-directional on purpose. An expired or lost licence is never
turned into offline: a site still running after a lost licence is exactly what
the ▲ alert exists for, and deducing offline would bury it. And because the
rule requires the lost flag to be clear, a via CRM row can never raise ▲.
The order is always probe first: Vercel, then the local script, then — only if both came back blind — the licence.
The CRM does have a Kleecks_Active field ("Client Active?") on the Accounts
module, and reading it through the deal's lookup was tried once. Don't: this
token's scopes cover Deals, and COQL answers a custom field on another module
with 401 INVALID_TOKEN — not a scope error — so the whole dashboard goes down
with what looks like a dead token. It would need ZohoCRM.modules.accounts.READ
on the Self Client, and it is worth nothing here: the fallback reads the licence
dates, which are on the deal. /api/setup/diagnose reports whether the current
token could read it, under accountsCustomField.
In the Excel export these rows carry CRM licence (not read) in Checked from
and their client name is italic, so a filtered sheet still shows which greens
were measured and which were deduced.
- In the Vercel dashboard: Storage → Blob → Create. Connecting it to the
project sets
BLOB_READ_WRITE_TOKENon its own. - Add
LOCAL_CHECK_TOKEN— any long random string; it is the shared secret between the script and the app, and the only thing guarding that endpoint. - Redeploy.
- On the machine that will run it, keep a copy of this folder. Nothing to
install: the script and
lib/livecheck.jsuse only Node built-ins, so Node 18 or newer is all it needs. Run it from inside that folder, since it loads the detection logic from../librelative to itself:
cd ~/Downloads/won-clients-live # wherever the folder actually is
APP_URL=https://your-deployment.vercel.app LOCAL_CHECK_TOKEN=the-same-string node scripts/local-check.cjs --verboseCannot find module '.../scripts/local-check.cjs' means the shell is somewhere
else — cd into the folder first. No sudo is needed for any of this.
--dry-run prints the outcome without posting it. The script asks the app which
clients to check, so the CRM stays the single source of truth for the targets and
the detection logic is imported from lib/livecheck.js — the two can never drift
apart.
Keep the folder: the script lives in it and loads lib/livecheck.js from it.
Deleting it after uploading to GitHub leaves nothing to run.
Use launchd, not cron. Cron skips a run whose minute passed while the Mac was
asleep or off; launchd remembers a missed StartCalendarInterval and fires it
shortly after the machine wakes, and RunAtLoad makes it run at login too. For a
laptop that is closed at night this is the difference between a daily check and
no check at all.
scripts/com.kleecks.local-check.plist is ready to fill in: replace the folder,
the URL, the token and the two log paths, then
cp scripts/com.kleecks.local-check.plist ~/Library/LaunchAgents/
plutil -lint ~/Library/LaunchAgents/com.kleecks.local-check.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.kleecks.local-check.plist
launchctl kickstart -p gui/$(id -u)/com.kleecks.local-check
tail -f /tmp/kleecks-local-check.logLoad failed: 5: Input/output error means launchd would not take the file: a
placeholder left in it, or a log path it cannot write. plutil -lint catches the
first, and the log paths must be absolute — launchd expands neither ~ nor
$HOME in StandardOutPath.
Nothing keeps the results fresh while the machine is off, so the dashboard says
how old they are: past NEXT_PUBLIC_LOCAL_STALE_DAYS days (3 by default) the
summary pill turns amber with the age, and every via script badge carries it.
An old answer is still shown — it is the best evidence available — but it stops
looking current.
If the check has to run whether or not that Mac is awake, put the folder on a machine that is always on and sits on the same kind of connection: an office Mac mini, a NAS with Node. A cloud VM does not work — it is a datacentre IP again, which is the problem this whole mechanism exists to route around.
Resolution order, first hit wins:
Website URLon a won licence dealWebsiteon the CRM account — for an indirect deal that is the Final Client's account, not the partner's: Boggi's own account, not Jakala'sconfig/domain-overrides.json— the fallback map, for clients the CRM does not cover yet- a domain guessed from the client name (legal suffixes stripped,
.comthen.it, with and withoutwww.)
The CRM is the source of truth, so a Website typed into Zoho takes effect on the next read. The map is only a safety net: it fills the gap where both CRM fields are empty, and its entries were proposed rather than verified, so fixing the CRM is always the better move.
"NOVE25 SRL": "https://www.nove25.net/"Keys are matched ignoring case, spaces and punctuation. "skip" is the one
value that wins over the CRM: it leaves a client out of the live check entirely,
for holdings and partners with no site of their own.
Filter the table by Domain from to see where each domain came from — Guessed from name is the list still needing attention, Fallback map the ones running on an unverified entry.
postcss.config.js ships on purpose, with no plugins. The repo this is deployed
from had a leftover config from an earlier scaffold that pulled in tailwindcss,
which this app neither uses nor installs, and the Vercel build failed with
Cannot find module 'tailwindcss' while compiling app/globals.css. Unzipping
these sources over the repo replaces that file. If a build ever fails that way
again, look for stale postcss.config.* or tailwind.config.* left behind by a
previous project.
The line under the title carries the version from package.json, the build time
and, on Vercel, the commit — v.0.1.4 - Beta for testing · built 22/09/2026, 14:34 · a1b2c3d. Environment variables are baked into a deployment, so a value
saved on Vercel changes nothing until a redeploy: if that timestamp is older
than the change you just made, you are looking at the previous build. Bump the
version in package.json when it helps to tell two builds apart.
- Push this folder to GitHub, connect the repo to a Vercel project in the Kleecks BI team.
- Set
APP_PASSWORD, deploy, then use the/setuppage below to produce the Zoho variables. The rest of.env.exampleis optional tuning. - Add the deployment URL as a Web Tab in Zoho CRM.
next.config.jsalready allows the Zoho domains as frame ancestors; add yours there if it differs.
The deployment carries a guided page at /setup that turns a Self Client
grant code into the permanent refresh token and then checks it against the CRM,
so none of this has to happen at a terminal. It is behind the same
APP_PASSWORD, which is therefore the one variable to set by hand first.
- Set
APP_PASSWORDin the Vercel variables and deploy, then openhttps://<your-deployment>/setup. - Pick the data centre the CRM lives in. The page then links to the right API console and shows the exact scope string to copy.
- In the console: Add Client → Self Client → Create, sign in as a user who can see every deal. Copy the Client ID and Client Secret from the Client Secret tab.
- Generate Code tab, paste the scope string the page gave you, 10 minutes, Create → pick the CRM portal → Create, copy the code.
- Paste Client ID, Client Secret and code into the page and press Get the refresh token. A Zoho error comes back translated: an expired or reused code, a client from another data centre, malformed scopes.
- The page prints the whole block of Vercel variables ready to copy, then Test the connection runs the dashboard's own queries with those credentials and reports how many won licence deals that user can actually see — a restricted profile returns fewer rows rather than an error, and this is where you catch it.
- Paste the block into Vercel (Production, Preview and Development) and redeploy.
Nothing typed on that page is stored server-side; the values are returned to the browser and forgotten. The refresh token itself never expires unless it is revoked, or unless more than 20 are issued for the same client and user, which quietly drops the oldest — so keep the one that works rather than regenerating for a retry.
The three scopes are read-only: the app never writes to the CRM.
The same thing by hand, if you prefer curl
curl -X POST "https://accounts.zoho.eu/oauth/v2/token" \
-d "grant_type=authorization_code" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "code=THE_CODE"Scope string for the Generate Code tab, on one line:
ZohoCRM.coql.READ,ZohoCRM.modules.deals.READ,ZohoCRM.users.READ
After changing ZOHO_REFRESH_TOKEN on Vercel, redeploy and give it a few
minutes: warm functions keep the old access token in memory for up to an hour and
Zoho answers INVALID_OAUTHTOKEN in the meantime.
That error comes from the refresh grant, so the problem is the saved
ZOHO_REFRESH_TOKEN, not the setup page. Press Check the saved connection
at the top of /setup: it retries the saved variables, reports what Zoho
refused, shows each value's length and prefix (never the value), and — because a
token issued in one data centre answers invalid_code in every other one —
retries the token against all the Zoho data centres and names the one that
accepts it, with the corrected variables ready to copy.
The usual causes, in order:
- The grant code was saved instead of the refresh token. They look nearly
identical, both
1000.…, but the code works once and expires in minutes. - A stray newline or space on the pasted value. The app trims the variables now, and the diagnosis flags it.
- Data centre mismatch — token from
.com,ZOHO_ACCOUNTS_HOSTon.eu. - Client ID/secret from a different Self Client than the one that issued the token. A refresh token only works with the client that created it.
- The token was revoked, or more than 20 were issued for that client and user, which drops the oldest silently.
npm install
cp .env.example .env.local # fill it in
npm run dev