docs
    site-kit: Booking
    v8.13.4.md

    Sync (Booking): @sonordev/site-kit/sync

    Embeddable booking/scheduling widget, like Calendly, built into Sonor. Appointments, consultations, classes.

    Usage

    'use client'
    import { BookingWidget } from '@sonordev/site-kit/sync'
    
    export default function BookPage() {
      return (
        <BookingWidget
          onBookingComplete={(result) => {
            console.log('Booked:', result.booking.confirmationCode)
          }}
        />
      )
    }

    Props

    interface BookingWidgetProps {
      orgSlug?: string                    // Organization slug (for public mode)
      apiKey?: string                     // API key (auto-resolved from env)
      apiUrl?: string                     // Default: https://api.sonor.io
      bookingTypeSlug?: string            // Show specific type only
      timezone?: string                   // Guest timezone (auto-detected)
      className?: string
      daysToShow?: number                 // Days of availability to display. Default 60
      onBookingComplete?: (result: BookingResult) => void
      onError?: (error: Error) => void
      hideTypeSelector?: boolean          // Hide type selector for single-type embed
      autoSelectFirstDay?: boolean        // Open on the first day with open times. Default true
      source?: BookingSource              // Where the booking came from. Default 'main-site'
      defaultGuest?: {                    // Prefill the guest form
        name?: string
        email?: string
        phone?: string
      }
    
      styles?: {                          // Custom theme
        primaryColor?: string             // Buttons, selected day and time. Default #0069ff
        borderRadius?: string             // Default 8px
        fontFamily?: string
        backgroundColor?: string          // Widget background. Default #ffffff
        surfaceColor?: string             // Skeletons and hover fills. Default #f3f4f6
        elevatedColor?: string            // Cards and inputs. Default #f9fafb
        textPrimary?: string
        textSecondary?: string
        textTertiary?: string
        borderColor?: string              // Default #e5e7eb
        inputBorderColor?: string         // Defaults to borderColor
      }
    }

    autoSelectFirstDay checks up to 14 days, starting from the earliest day the booking type's minimum notice allows, and opens on the first one with open times. Guests land on times they can pick instead of an empty day. Set it to false to start with no day selected.

    Prefill the guest

    Pass defaultGuest when you already know who's booking, such as a signed-in member or someone arriving from an email link:

    <BookingWidget
      bookingTypeSlug="consultation"
      defaultGuest={{ name: member.name, email: member.email, phone: member.phone }}
    />

    Only empty fields are filled, and values are trimmed. The guest can change any of them, and anything they've typed is never overwritten. If the details arrive after the first render, the fields that are still empty fill in then. A guest who clears a field isn't refilled by the same values rendering again. Phone is still required to book, so pass it when you have it.

    Booking source

    source is recorded on the booking so you can tell where it came from: 'main-site' (the default), 'audit-page', 'portal', 'proposal' or 'email-cta'. The list is also exported as BOOKING_SOURCES. Agent bookings are a separate flow and aren't a widget source.

    Campaign tags

    When the visitor allows analytics, createBooking adds the booking page's campaign tags to the booking: utm_source, utm_medium, utm_campaign, utm_term and utm_content (as utmSource through utmContent) and the gclid and fbclid click IDs. They're read from the URL the booking records as sourceUrl, so a widget on a landing page tags its bookings with no setup. Values are cut at 200 characters, empty ones are left out, and a value you pass to createBooking yourself always wins. While analytics is denied or withdrawn, or on a site the visitor's choices weren't issued for, nothing is read from the page, and the sourceUrl the booking records is cut to the origin and path, so no tag or click ID travels in the URL either. A form submission follows the same rule. The booking still goes through, untagged.

    await createBooking({ ...booking, source: 'main-site', gclid: myStoredGclid })

    Layout

    The calendar and the time list sit side by side once the widget itself is 560px wide, and stack below that. The widget decides from its own width, not the window's, so one in a narrow column of a wide page stacks. The widget fills the width of its parent. In a parent that sizes itself to its content (an inline-block, a flex item with no width of its own) it is 340px wide; give that parent a width to change it. Browsers without container queries use the window width instead.

    UI Flow

    1. Type selector: choose a booking type, unless a specific bookingTypeSlug is provided.
    2. Meeting format: when the booking type enables meeting options, choose virtual, office, or a visit to the guest's location. Travel meetings validate the address before showing availability.
    3. Calendar and times: choose an available time and reserve it while completing contact details.
    4. Guest info: name, email, phone, optional company, and notes. Every booking requires a phone number. The widget trims the company name and leaves it out of the booking request if the field is blank.
    5. Result: a confirmed booking shows calendar links when Sonor sends the guest's invitation. When the host's Google Calendar sends it, the widget says who the invite is coming from instead (see Calendar invitations). Meetings that require review show a pending request without calendar links.

    Changing a meeting format restores the selected format, address, and access notes. Guests can return to the service selector when it's available. Contact details survive changes to the format or reserved time.

    After Sonor confirms a time is held, the widget shows the hold status next to Change meeting format when that control is available. On narrow screens the row can wrap. Booking types without a format control show the status on its own.

    If booking types fail to load, Retry loading booking options rereads the available types. It does not place a hold or submit a booking.

    Expired meeting details and time reservations show a recovery action. Guests can recheck their meeting details or choose another time without re-entering their contact information. An active hold remains usable if its prepared meeting token expires, until the hold's own deadline.

    Navigation is disabled while a reservation or booking request is running. Stale responses cannot reopen a previous step, and holds created after the widget is removed are released.

    Accessibility

    Screen readers and AI agent browsers (which act on elements by their accessible names) can book without guessing:

    • Days are buttons named with the full date, year included: "Wednesday, October 7, 2026". The picked day is pressed (aria-pressed="true"), and days that can't be booked are disabled.
    • Times are buttons named with the time and the date, "10:30 AM, Wednesday, October 7, 2026", in the booking's time zone. They still show just the time. The picked time is pressed.
    • Confirm, the button that reserves the picked time, is named "Confirm 10:30 AM, Wednesday, October 7, 2026".

    Every name contains what its button shows (a time's and Confirm's start with it), so voice control can still target a button by its visible text (WCAG 2.5.3). None of this changes what the widget sends.

    API Functions

    import {
      fetchBookingTypes, fetchBookingTypeDetails,
      fetchAvailability, fetchAvailableDates,
      createSlotHold, releaseSlotHold, createBooking,
      prepareMeeting,
      detectTimezone, formatTime, formatDate, formatDuration,
      BOOKING_SOURCES,
    } from '@sonordev/site-kit/sync'
    import type { BookingSource, BookingAttribution } from '@sonordev/site-kit/sync'

    Types

    interface BookingType {
      slug: string; name: string; description?: string;
      duration_minutes: number; color?: string;
      location_type: 'virtual' | 'phone' | 'in_person' | 'custom';
      price_cents?: number; currency?: string; is_active: boolean;
    }
    
    interface BookingResult {
      success: boolean
      booking: {
        id: string; confirmationCode: string; scheduledAt: string;
        durationMinutes: number; hostName?: string; timezone: string;
      }
      cancelUrl: string; rescheduleUrl: string;
      invitation?: 'google' | 'sonor'   // who sends the guest's calendar invite
      calendarLinks: { google: string; outlook: string; ics: string }
    }

    Calendar invitations

    Each booking gives the guest one calendar invitation, and invitation says who sends it:

    • 'google': the host has Google Calendar connected, so Google invites the guest to the host's event. Sonor's emails don't attach a second invite, and the success screen says who the invite is coming from instead of showing calendar links. The Google and Outlook links build a separate event with no tie to that invitation, so a guest who clicked one would have two entries for the same meeting.
    • 'sonor': there's no Google event for the booking, usually because the host hasn't connected a calendar. Sonor's confirmation email carries the invite, and the success screen shows the calendar links.

    APIs older than the field don't send it; treat a missing invitation like 'sonor'. calendarLinks is still sent for every booking so older widgets keep working. If you build your own success screen with createBooking, check invitation before you render calendarLinks.

    createBooking attaches the browser's existing analytics visitorId and analyticsSessionId automatically, including for custom booking screens. Sonor links that journey to the contact resolved from the accepted booking. These IDs are separate from sessionId, which owns a slot hold; don't replace a hold's session with the analytics session. With analytics disabled, no tracking IDs or visits are invented. Custom callers can pass their existing analytics IDs explicitly. The contact identity is resolved by Sonor, never supplied by the browser.

    Features

    • Automatic timezone detection
    • Slot hold with expiry (prevents double-booking)
    • Business hours support
    • Multiple hosts per booking type
    • Custom meeting URL / location

    Booking regression checks

    Run pnpm exec vitest run src/sync/booking-flow.test.ts for expiry and server-error recovery checks. Start pnpm exec vite --host 127.0.0.1 --port 5189, then run node test/meeting-flow/run.mjs and node test/meeting-flow/regression.mjs for the real widget flows. The browser harness intercepts requests to a reserved test domain, so it creates no live bookings.