Skip to content

Booking calendar import ​

On Lovely Home+ and Multi Home, an owner can paste the calendar export link of an Airbnb listing (or any booking site that exports iCal) and the hub keeps a stay for each booking (#1097). With a turnover cleaner chosen, each booking also gets a cleaner visit on its checkout day.

Where it lives ​

Settings → Guest mode & stays → Import from Airbnb and other booking sites, below the scheduled stays list. Each imported calendar shows its name, where the link points (host and the last few characters, never the whole link), when it last synced, how many bookings are still to come, and anything to act on. The owner can pick the turnover cleaner, Sync now, or Stop importing. A home can import up to 5 calendars.

If the owner leaves the name blank, Airbnb, Vrbo and Booking.com links are named after the site ("Airbnb"), which keeps stay labels short (Airbnb HMABCDEF12). A link from anywhere else (an iCloud or Google calendar, a channel manager) takes the calendar's own name (X-WR-CALNAME) on its first good sync, and the host until then. Clearing the name later does the same.

On Airbnb the link is under Calendar → Availability → Connect calendars → Export calendar. Vrbo and other sites have a similar "export calendar" link.

What a sync does ​

The hub Worker's hourly cron (0 * * * *, the same run that applies the stay schedule to Cloudflare Access) syncs every calendar first, then applies the schedule, so a new or moved booking reaches Access in the same run. Adding a calendar, changing it, and Sync now also sync straight away.

For each calendar the Worker fetches the link (15-second timeout, at most 2 MB, must contain BEGIN:VCALENDAR) and reads its events with ical.js (worker/src/lib/stayCalendarFeeds.js):

In the feedOn the hub
A booking (Airbnb SUMMARY:Reserved) that hasn't endedA guest stay. Start is DTSTART, end is DTEND (the checkout day: the guest leaves that morning, so the next guest can arrive the same afternoon). Label is the calendar name plus the Airbnb code from the description, e.g. Airbnb HMABCDEF12. No emails.
A booking whose dates changedThe stay's dates move; its access lead and grace days are kept.
A booking that's gone, before it startsThe stay is cancelled (source_removed = 1). If the booking comes back, so does the stay.
A booking that's gone after it startedKept, and reported on the calendar ("A booking that has already started left the calendar"). A feed glitch must never lock out a guest who is there. The owner can cancel or end it by hand.
Blocked dates (Not available, Blocked, Closed) or STATUS:CANCELLEDIgnored.
A booking that overlaps a stay the owner added by handSkipped and reported with the clashing stay's name. Manual stays are never changed by a sync. Changeovers (one stay ending the day the next starts) are fine (#1140).

A failed fetch (link gone, site down, not a calendar) changes nothing and is shown on the calendar, so an outage never cancels a stay.

Booking.com exports every unavailable date as CLOSED - Not available, bookings included, so its feed can't tell bookings from blocks and nothing is imported from it.

Who owns what on an imported stay ​

  • The calendar owns the dates. Edit greys out the dates and the hub refuses a date change (IMPORTED_STAY_DATES), including from Account → Stays; Extend is hidden. Change the booking on Airbnb and the hub follows within the hour.
  • The owner owns everything else. Booking feeds carry no guest emails, so an imported stay starts with none and the card says so. The owner adds the guest's email (and name, who's staying, label) with Edit; a sync never overwrites those.
  • An owner's cancel sticks. A stay the owner cancels stays cancelled, even though the booking is still in the feed.
  • End now works as for any stay.

Without an email nobody signs in for that stay, but the stay still counts for the hub-wide schedule, exactly like a stay added by hand: during the stay's dates the hub's home access details and Alexa controls are shown on a device in guest mode (the wall tablet).

Turnover cleans ​

Each calendar can name one cleaner from People → Providers. They need an email, because that is how they get into the hub. For every booking still to come, the sync keeps a cleaner stay on its checkout day (source_uid = the booking's UID + #turnover), with the cleaner's email and the provider set. It moves with the checkout day and is cancelled with the booking. Changing or clearing the cleaner updates or cancels the cleans to come. Deleting the provider clears it from the calendar too, and the next sync cancels their cleans to come. A clean on today's date is never cancelled by a sync.

The clean is an ordinary cleaner stay, so the cleaner access and checklist work (#1182) applies to it unchanged.

Data ​

Hub D1 migration 0015_stay_calendar_feeds.sql:

  • stay_calendar_feeds: id, name, url (holds the site's private token; the API only ever returns urlHint), cleaner_provider_id, and the last sync's time, result code and summary.
  • sitter_stays gains source_feed_id, source_uid, source_ref and source_removed, with a unique index on (source_feed_id, source_uid). Stays added by hand have source_feed_id NULL. The stay API returns a source object (feedId, name, uid, ref, kind, removed) or null.

Stop importing cancels the calendar's stays that haven't started, turns any stay under way into an ordinary stay (source cleared), and deletes the calendar.

Backups: full site backups carry the calendars, URL included (like hubSecrets), as stayCalendarFeeds. A restore puts the calendars back before the stays, so imported stays keep their source and aren't imported twice. A turnover cleaner who isn't in the backup is dropped.

API ​

Owner only (requireOwnerIdentity). Everything but removing a calendar needs the calendarImport plan feature (Lovely Home+ and Multi Home); a Free hub gets 403 PLAN_FEATURE_LOCKED. The cron skips a hub whose last confirmed plan is Free. The demo hub refuses all of these.

Method and pathDoes
GET /api/house-settings/stay-calendars{ calendars }
POST /api/house-settings/stay-calendarsAdd { url, name?, cleanerProviderId? }, then sync
PUT /api/house-settings/stay-calendars/:idChange name, url or cleanerProviderId, then sync
DELETE /api/house-settings/stay-calendars/:idStop importing
POST /api/house-settings/stay-calendars/:id/syncSync now

Links must be https:// (webcal:// and http:// are upgraded), with no user name or password, not an IP address and not on lovely-hub.com or lovely-home.co.uk.

Sync result codes on a calendar: FEED_NOT_FOUND and FEED_FORBIDDEN (link no longer works), FEED_NOT_CALENDAR, FEED_PARSE and FEED_TOO_LARGE (not a calendar), FEED_UNAVAILABLE, FEED_TIMEOUT and FEED_UNREACHABLE (try again next hour). The cron logs stay_calendar_sync with the count and any failure codes.

Tests ​

worker/tests/stayCalendarFeeds.test.js runs the sync against a real SQLite database built from the hub migrations, with Airbnb-format feeds.