Skip to content

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:

TableHolds
stay_cleansOne 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_ticksTicked items
clean_problemsProblems 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.

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 ​

RouteWhoDoes
GET /api/house-settings/cleaningOwnerTimes, checklist, upcoming and recent cleans, plan
PUT /api/house-settings/cleaningOwner{ checkoutTime, checkinTime, rooms }; rooms needs Plus
PUT /api/house-settings/cleans/:stayIdOwner, Plus{ slotStart, slotEnd, extras } for one clean
POST /api/house-settings/cleans/:stayId/send-linkOwner, PlusEmail the cleaner a new link on the next run
POST /api/house-settings/cleans/:stayId/turn-off-linkOwner, PlusThe link stops working
POST /api/clean/openThe link{ token }: the clean, with today's details only during the slot
POST /api/clean/actionThe link{ token, action: tick | untick | problem | done, itemId, kind, note }
POST /api/platform/clean-noticesPlatformEmails due now; mints the link for booked and changed
POST /api/platform/clean-notices/ackPlatformOne 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:

  1. The hub-jobs Worker runs every 15 minutes (*/15 * * * *) and calls POST /api/public/clean-run on its platform with header X-Activation-Run-Secret (the same secret as activation emails).
  2. The platform lists live Lovely Home+ and Multi Home hubs from site_billing and asks each for its due notices.
  3. 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).
  4. 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_CAP changes it; 0 stops them). The count is kept per UTC day in platform_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 reached in the platform logs, and its summary says capped: 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 ​

  1. Apply hub D1 migration 0016_cleans.sql to every hub: npm run d1:migrate:all. Until it is applied, Settings → Cleaning and the clean page fail on that hub; nothing else changes.

  2. Merge. The hub Worker, the hub Pages site and the platform deploy as usual.

  3. 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.

  4. 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.

  5. Check by hand in the sandbox:

    bash
    curl -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.