Cleans: the cleaner link and checklist
A cleaner gets a link by email for each clean. During the clean's time slot the link opens Today's clean: the checklist, the door and lockbox codes, the Wi‑Fi, the address, contacts, bins and when the next guests arrive. The cleaner ticks items, reports problems and taps Done. The owner gets a summary by email and sees the result on Account → Stays (#1182).
Plans: the checklist and the link are Lovely Home+ and Multi Home. Every plan can save checkout and check-in times, and every cleaner who signs in (Cloudflare Access) sees the next check-in time on their welcome card.
What a clean is
A clean is a stay with audience Cleaner (sitter_stays.audience = 'cleaner', from #1181) and a home provider picked as the cleaner (#1248). The clean day is the stay's start date. Nothing new has to be booked: however the stay is made (Account → Stays, hub stays, a calendar import), the clean follows it.
The hub's D1 migration 0016_cleans.sql adds:
| Table | Holds |
|---|---|
stay_cleans | One row per clean: its own slot (if changed), extras, the link's token hash, Done time, the frozen checklist once done, what was last emailed (notified_fingerprint) and when the summary was sent |
clean_ticks | Ticked items |
clean_problems | Problems reported (supplies, damage, left behind, other) with a note |
The time slot
The slot is the home's checkout time to check-in time on the clean day (Settings → Cleaning; defaults 10:00 and 15:00, Europe/London). An owner can change one clean's slot in Settings → Cleaning. The link opens only during the slot. Before it, the page says when the clean is; after it, or after Done, it says the clean is over.
The link
https://{home}.lovely-hub.com/s/clean/{token}. It sits under /s/*, which Cloudflare Access already skips for share links (share-links.md), so it needs no Terraform change. The token is 32 random bytes; only its SHA-256 hash is stored. A new token is made each time an email with a link is sent, so the old link stops working when the time changes or the owner taps Send a new link. Turn off link clears it.
The page (functions/s/clean/[token].js, functions/lib/cleanPage.js) is server-rendered with no JavaScript. Each tick, problem and Done is a form POST back to the same URL, which the Pages Function sends to the Worker over the HUB_API binding and then redirects back (303). Failed opens count towards the share-link rate limit. Strings are under hub.sharePage.clean.* and are built into the page with npm run build:share-page-strings.
Worker API
| Route | Who | Does |
|---|---|---|
GET /api/house-settings/cleaning | Owner | Times, checklist, upcoming and recent cleans, plan |
PUT /api/house-settings/cleaning | Owner | { checkoutTime, checkinTime, rooms }; rooms needs Plus |
PUT /api/house-settings/cleans/:stayId | Owner, Plus | { slotStart, slotEnd, extras } for one clean |
POST /api/house-settings/cleans/:stayId/send-link | Owner, Plus | Email the cleaner a new link on the next run |
POST /api/house-settings/cleans/:stayId/turn-off-link | Owner, Plus | The link stops working |
POST /api/clean/open | The link | { token }: the clean, with today's details only during the slot |
POST /api/clean/action | The link | { token, action: tick | untick | problem | done, itemId, kind, note } |
POST /api/platform/clean-notices | Platform | Emails due now; mints the link for booked and changed |
POST /api/platform/clean-notices/ack | Platform | One email was sent |
The platform calls use the same auth as the other platform → hub calls (platform health token and PLATFORM_SITE_ARCHIVE_SECRET).
Emails
Hubs don't send email, so the platform does, through Resend:
- The hub-jobs Worker runs every 15 minutes (
*/15 * * * *) and callsPOST /api/public/clean-runon its platform with headerX-Activation-Run-Secret(the same secret as activation emails). - The platform lists live Lovely Home+ and Multi Home hubs from
site_billingand asks each for its due notices. - The hub compares each clean's date, slot and cleaner emails with what it last sent (a fingerprint). New → booked; different → changed; stay cancelled after a booked email → cancelled. After Done or the end of the slot, if the cleaner was emailed, the owner gets a summary (ticked count, items not ticked, problems, link to Settings → Cleaning).
- The platform sends, then acks each one, so a failed send is tried again next run.
Keeping inside Resend's limit
Resend allows 100 emails a day for the whole platform, and sign-in codes must always get through. So:
- A week ahead at most. Booked and changed emails only go out for cleans in the next 7 days (
CLEAN_NOTICE_DAYS_AHEAD). A clean booked months ahead, or a whole imported Airbnb calendar (stay-calendar-import.md), is emailed a week before, a few a day, not all at once. - Daily cap. Clean emails stop at 30 a day across all hubs (Pages env
CLEAN_EMAILS_DAILY_CAPchanges it;0stops them). The count is kept per UTC day inplatform_settings(clean_emails_daily_count). The platform tells each hub how many it may still send; the hub hands over the most urgent first (cancelled, changed, booked by date, then owner summaries) and only makes links for those. The rest wait for the next run or the next day. - A run that hits the cap logs
[clean-emails] daily cap reachedin the platform logs, and its summary sayscapped: true.
Reserved test domains (example.com, .test and the like) are never mailed. In the sandbox, ACTIVATION_EMAILS_TEST_TO redirects every email to that inbox.
Rollout
Apply hub D1 migration
0016_cleans.sqlto every hub:npm run d1:migrate:all. Until it is applied, Settings → Cleaning and the clean page fail on that hub; nothing else changes.Merge. The hub Worker, the hub Pages site and the platform deploy as usual.
Platform admin Terraform apply (Mark's go; see ops-platform-apply-checklist.md). It adds the 15-minute cron to the hub-jobs Worker. Until then no clean emails are sent, though the link and checklist work if an owner shares the link by hand.
On the first run, every clean in the next 7 days on a Plus hub with a cleaner email gets a booked email, up to the daily cap.
Check by hand in the sandbox:
bashcurl -X POST https://platform-sandbox.lovely-home.co.uk/api/public/clean-run \ -H "X-Activation-Run-Secret: $ACTIVATION_RUN_SECRET"
Not in this version
- Photos (before/after, or of a problem). The page has no JavaScript and takes no uploads yet.
- The cleaner's Cloudflare Access sign-in still covers the whole clean day, not just the slot, and Done doesn't end it.