@cosmoops/connect-sdk 0.17.0 → 0.19.0

package/dist/esm/client/components/booking-calendar.js

@@ -0,0 +1,167 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Button, Card, Chip, Skeleton } from "@heroui/react";
+import { CalendarDays, ChevronLeft, ChevronRight, Phone, Video } from "lucide-react";
+import { useMemo, useState } from "react";
+import { ConnectEmptyState } from "../../ui/empty-state.js";
+import { useBookableEventTypes, useBookings, } from "../use-scheduling.js";
+import { dayColumns, dayStartInstant, hourMarks, layoutBookings, zonedInstant, } from "./booking-grid.js";
+import { ConnectBookingDetail, ConnectBookingDialog } from "./booking-dialogs.js";
+/**
+ * The visible band of the day. Outside it a booking is drawn at the edge and
+ * flagged rather than hidden - see `layoutBookings`.
+ *
+ * 07:00-21:00 rather than a full day: fourteen hours is the most that stays
+ * legible on a laptop without scrolling, and a booking grid whose first screen
+ * is six empty night-time hours reads as a broken calendar.
+ */
+const DEFAULT_WINDOW = { startMinute: 7 * 60, endMinute: 21 * 60 };
+const LOCATION_ICON = {
+    phone: Phone,
+    address: CalendarDays,
+    link: Video,
+};
+/**
+ * A week of the workspace's calendar, with booking, rescheduling and
+ * cancelling.
+ *
+ * **Two views, and which one you get is a viewport decision, not a
+ * preference.** A seven-column time grid needs roughly 640px before a column
+ * is wide enough to hold a name; below that it degrades into unreadable
+ * slivers. So the grid is `sm:` and up, and the same week renders as a grouped
+ * agenda underneath - not a cut-down grid, a different and better shape for a
+ * phone. Both read the same data and open the same dialogs.
+ *
+ * Everything it does goes through the bridge as the signed-in member, so
+ * Connect checks *their* `calendar:read` / `calendar:manage` rather than the
+ * host application's key. A member who may look but not book gets the grid and
+ * a refusal on the write, which is the correct shape - see `useBookingActions`.
+ */
+export function ConnectBookingCalendar({ timeZone, hostMemberId, window: visibleWindow = DEFAULT_WINDOW, canBook = true, className, }) {
+    const zone = timeZone ?? hostTimeZone();
+    const [weekAnchor, setWeekAnchor] = useState(() => startOfWeek(new Date(), zone));
+    const [selected, setSelected] = useState(null);
+    const [booking, setBooking] = useState(null);
+    const now = new Date();
+    const columns = useMemo(() => dayColumns(weekAnchor, zone, 7, now), 
+    // `now` is deliberately not a dependency: it changes on every render, and
+    // the only thing it decides is which column is highlighted. Recomputing
+    // seven columns per keystroke elsewhere on the page to move a highlight
+    // that changes once a day is not a trade worth making.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [weekAnchor, zone]);
+    const range = useMemo(() => ({
+        from: columns[0]?.startsAt ?? weekAnchor,
+        to: new Date((columns.at(-1)?.startsAt.getTime() ?? weekAnchor.getTime()) + 24 * 60 * 60_000),
+    }), [columns, weekAnchor]);
+    const { eventTypes } = useBookableEventTypes();
+    const { bookings, isLoading, error, refetch } = useBookings({
+        from: range.from,
+        to: range.to,
+        hostMemberId,
+    });
+    const positioned = useMemo(() => layoutBookings(bookings, zone, visibleWindow), [bookings, zone, visibleWindow]);
+    const marks = useMemo(() => hourMarks(visibleWindow), [visibleWindow]);
+    const shiftWeek = (weeks) => setWeekAnchor((anchor) => new Date(anchor.getTime() + weeks * 7 * 24 * 60 * 60_000));
+    const eventTypeById = useMemo(() => new Map(eventTypes.map((eventType) => [eventType.id, eventType])), [eventTypes]);
+    return (_jsxs("div", { className: `flex flex-col gap-4 ${className ?? ""}`, children: [_jsxs("header", { className: "flex flex-wrap items-center justify-between gap-3", children: [_jsxs("div", { className: "flex items-center gap-1", children: [_jsx(Button, { isIconOnly: true, size: "sm", variant: "tertiary", "aria-label": "Previous week", onPress: () => shiftWeek(-1), children: _jsx(ChevronLeft, { className: "size-4", "aria-hidden": true }) }), _jsx(Button, { size: "sm", variant: "secondary", onPress: () => setWeekAnchor(startOfWeek(new Date(), zone)), children: "Today" }), _jsx(Button, { isIconOnly: true, size: "sm", variant: "tertiary", "aria-label": "Next week", onPress: () => shiftWeek(1), children: _jsx(ChevronRight, { className: "size-4", "aria-hidden": true }) }), _jsx("p", { className: "ml-2 text-sm font-medium", children: weekLabel(columns, zone) })] }), canBook && eventTypes.length > 0 && (_jsx(Button, { size: "sm", variant: "primary", onPress: () => setBooking({ startAt: nextHour(now) }), children: "New appointment" }))] }), error && _jsx("p", { className: "text-sm text-danger", children: error }), isLoading ? (_jsx(Skeleton, { className: "h-96 w-full rounded-lg" })) : (_jsxs(_Fragment, { children: [_jsx(Card, { className: "hidden overflow-hidden sm:block", children: _jsx(WeekGrid, { columns: columns, marks: marks, window: visibleWindow, positioned: positioned, eventTypeById: eventTypeById, zone: zone, onSelect: setSelected, onPickEmpty: canBook ? (startAt) => setBooking({ startAt }) : undefined }) }), _jsx("div", { className: "sm:hidden", children: _jsx(AgendaView, { columns: columns, bookings: bookings, eventTypeById: eventTypeById, zone: zone, onSelect: setSelected }) })] })), booking && (_jsx(ConnectBookingDialog, { isOpen: true, onOpenChange: (open) => !open && setBooking(null), eventTypes: eventTypes, initialStartAt: booking.startAt, timeZone: zone, onBooked: () => {
+                    setBooking(null);
+                    refetch();
+                } })), selected && (_jsx(ConnectBookingDetail, { booking: selected, eventType: eventTypeById.get(selected.eventTypeId) ?? null, timeZone: zone, onOpenChange: (open) => !open && setSelected(null), onChanged: () => {
+                    setSelected(null);
+                    refetch();
+                } }))] }));
+}
+function WeekGrid({ columns, marks, window: visibleWindow, positioned, eventTypeById, zone, onSelect, onPickEmpty, }) {
+    const span = visibleWindow.endMinute - visibleWindow.startMinute;
+    return (_jsxs("div", { className: "grid grid-cols-[3rem_repeat(7,minmax(0,1fr))]", children: [_jsx("div", { className: "border-b border-separator" }), columns.map((column) => (_jsx("div", { className: `border-b border-l border-separator px-2 py-2 text-center ${column.isToday ? "bg-accent/5" : ""}`, children: _jsx("p", { className: `text-xs font-medium ${column.isToday ? "text-accent" : ""}`, children: column.label }) }, column.dateKey))), _jsx("div", { className: "relative", style: { height: `${(span / 60) * 3}rem` }, children: marks.map((mark) => (_jsx("span", { className: "absolute right-1 -translate-y-1/2 text-[0.625rem] text-muted", style: { top: `${((mark.minute - visibleWindow.startMinute) / span) * 100}%` }, children: mark.label }, mark.minute))) }), columns.map((column) => (_jsxs("div", { className: `relative border-l border-separator ${column.isToday ? "bg-accent/5" : ""}`, style: { height: `${(span / 60) * 3}rem` }, children: [marks.map((mark) => (_jsx("div", { className: "absolute inset-x-0 border-t border-separator/60", style: { top: `${((mark.minute - visibleWindow.startMinute) / span) * 100}%` } }, mark.minute))), onPickEmpty &&
+                        marks.map((mark) => (_jsx("button", { type: "button", "aria-label": `Book ${column.label} at ${mark.label}`, className: "absolute inset-x-0 cursor-pointer transition-colors hover:bg-accent/10", style: {
+                                top: `${((mark.minute - visibleWindow.startMinute) / span) * 100}%`,
+                                height: `${(60 / span) * 100}%`,
+                            }, onClick: () => onPickEmpty(new Date(column.startsAt.getTime() + mark.minute * 60_000)) }, `slot-${mark.minute}`))), positioned
+                        .filter((entry) => entry.dateKey === column.dateKey)
+                        .map((entry) => {
+                        const eventType = eventTypeById.get(entry.booking.eventTypeId);
+                        return (_jsxs("button", { type: "button", onClick: () => onSelect(entry.booking), className: "absolute overflow-hidden rounded-[--radius] border border-accent/30 bg-accent/15 px-1 py-0.5 text-left transition-colors hover:bg-accent/25", style: {
+                                top: `${entry.top * 100}%`,
+                                height: `${entry.height * 100}%`,
+                                // Side-by-side within an overlap cluster, with a hairline
+                                // gap so two adjacent blocks read as two things.
+                                left: `${(entry.column / entry.columns) * 100}%`,
+                                width: `calc(${(1 / entry.columns) * 100}% - 2px)`,
+                            }, children: [_jsx("span", { className: "block truncate text-[0.625rem] font-medium text-accent", children: timeLabel(new Date(entry.booking.startAt), zone) }), _jsx("span", { className: "block truncate text-[0.625rem]", children: entry.booking.attendee.name }), eventType && (_jsx("span", { className: "block truncate text-[0.625rem] text-muted", children: eventType.name }))] }, entry.booking.id));
+                    })] }, column.dateKey)))] }));
+}
+function AgendaView({ columns, bookings, eventTypeById, zone, onSelect, }) {
+    const byDay = useMemo(() => {
+        const map = new Map();
+        for (const booking of bookings) {
+            const { dateKey } = zonedInstant(new Date(booking.startAt), zone);
+            map.set(dateKey, [...(map.get(dateKey) ?? []), booking]);
+        }
+        return map;
+    }, [bookings, zone]);
+    // Days with nothing on them are omitted rather than rendered empty: an
+    // agenda is a list of what is happening, and seven "nothing" rows is six
+    // screens of scrolling to find the one day that matters.
+    const populated = columns.filter((column) => (byDay.get(column.dateKey)?.length ?? 0) > 0);
+    if (populated.length === 0) {
+        return (_jsx(ConnectEmptyState, { variant: "dashed", icon: _jsx(CalendarDays, { "aria-hidden": true }), title: "Nothing booked this week", description: "Appointments booked here, on your public link, or by a voice agent all show up together." }));
+    }
+    return (_jsx("div", { className: "flex flex-col gap-4", children: populated.map((column) => (_jsxs("section", { className: "flex flex-col gap-2", children: [_jsx("h3", { className: `text-sm font-medium ${column.isToday ? "text-accent" : ""}`, children: column.label }), (byDay.get(column.dateKey) ?? []).map((booking) => {
+                    const eventType = eventTypeById.get(booking.eventTypeId);
+                    const Icon = eventType ? LOCATION_ICON[eventType.locationKind] : CalendarDays;
+                    return (_jsx("button", { type: "button", onClick: () => onSelect(booking), children: _jsx(Card, { className: "transition-colors hover:bg-surface", children: _jsxs(Card.Content, { className: "flex items-center gap-3 py-3 text-left", children: [_jsx(Icon, { className: "size-4 shrink-0 text-muted", "aria-hidden": true }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("p", { className: "truncate text-sm font-medium", children: booking.attendee.name }), _jsxs("p", { className: "truncate text-xs text-muted", children: [timeLabel(new Date(booking.startAt), zone), eventType ? ` · ${eventType.name}` : ""] })] }), booking.source === "agent-call" && (_jsxs(Chip, { size: "sm", variant: "secondary", children: [_jsx(Phone, { className: "size-3", "aria-hidden": true }), "Agent"] }))] }) }) }, booking.id));
+                })] }, column.dateKey))) }));
+}
+/* ------------------------------------------------------------------ helpers */
+/** The host's zone, used when the caller does not name the business's. */
+function hostTimeZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+    }
+    catch {
+        return "UTC";
+    }
+}
+/**
+ * Monday of the week `instant` falls in, in `zone`.
+ *
+ * Monday rather than Sunday: this is a *business* calendar, and a week that
+ * splits the working days across two screens is the one thing a week view must
+ * not do.
+ */
+function startOfWeek(instant, zone) {
+    const { dateKey } = zonedInstant(instant, zone);
+    const midnight = dayStartInstant(dateKey, zone);
+    // `getUTCDay` on local midnight-as-an-instant is not the local weekday, so
+    // the weekday is read back through the zone.
+    const weekday = new Intl.DateTimeFormat("en-US", { timeZone: zone, weekday: "short" }).format(midnight);
+    const offset = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"].indexOf(weekday);
+    return new Date(midnight.getTime() - (offset < 0 ? 0 : offset) * 24 * 60 * 60_000);
+}
+function weekLabel(columns, zone) {
+    const first = columns[0];
+    const last = columns.at(-1);
+    if (!first || !last)
+        return "";
+    const month = new Intl.DateTimeFormat("en-IN", { timeZone: zone, month: "long", year: "numeric" });
+    return first.monthLabel === last.monthLabel
+        ? month.format(first.startsAt)
+        : `${first.monthLabel} - ${month.format(last.startsAt)}`;
+}
+function timeLabel(instant, zone) {
+    return new Intl.DateTimeFormat("en-IN", {
+        timeZone: zone,
+        hour: "numeric",
+        minute: "2-digit",
+        hour12: true,
+    }).format(instant);
+}
+/** The next whole hour - where "New appointment" opens with no slot picked. */
+function nextHour(now) {
+    const next = new Date(now);
+    next.setMinutes(0, 0, 0);
+    return new Date(next.getTime() + 60 * 60_000);
+}
+export { timeLabel as connectBookingTimeLabel };

package/dist/esm/client/components/booking-dialogs.js

@@ -0,0 +1,120 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Button, Input, Label, Modal, TextField } from "@heroui/react";
+import { CalendarX2, Clock } from "lucide-react";
+import { useMemo, useState } from "react";
+import { useAvailableSlots, useBookingActions } from "../use-scheduling.js";
+const SEARCH_DAYS = 14;
+/**
+ * Picking a time, and then who it is for.
+ *
+ * The slot list is read fresh every time this opens and is **never cached
+ * across an open**: it is a snapshot of contention, and offering a time
+ * somebody took ninety seconds ago is how two people end up in the same slot.
+ * The server re-checks inside its transaction regardless, so a stale list
+ * costs a refusal rather than a double booking - this only makes the refusal
+ * rare enough to be surprising when it happens.
+ */
+export function ConnectBookingDialog({ isOpen, onOpenChange, eventTypes, initialStartAt, timeZone, onBooked, }) {
+    const [eventTypeId, setEventTypeId] = useState(eventTypes[0]?.id ?? "");
+    const [chosen, setChosen] = useState(null);
+    const [name, setName] = useState("");
+    const [phone, setPhone] = useState("");
+    const window = useMemo(() => ({
+        // From the start of the day that was clicked, so the times on offer are
+        // the ones near where the person was looking.
+        from: new Date(initialStartAt.getTime() - 12 * 60 * 60_000),
+        to: new Date(initialStartAt.getTime() + SEARCH_DAYS * 24 * 60 * 60_000),
+    }), [initialStartAt]);
+    const { slots, isLoading } = useAvailableSlots(eventTypeId ? { eventTypeId, from: window.from, to: window.to } : null);
+    const { createBooking, isPending, error, clearError } = useBookingActions();
+    const canSubmit = Boolean(chosen && name.trim() && phone.trim()) && !isPending;
+    return (_jsx(Modal, { isOpen: isOpen, onOpenChange: onOpenChange, children: _jsx(Modal.Backdrop, { children: _jsx(Modal.Container, { children: _jsxs(Modal.Dialog, { children: [_jsx(Modal.Header, { children: "New appointment" }), _jsxs(Modal.Body, { className: "flex flex-col gap-4", children: [eventTypes.length > 1 && (_jsx("div", { className: "flex flex-wrap gap-2", children: eventTypes.map((eventType) => (_jsx(Button, { size: "sm", variant: eventType.id === eventTypeId ? "primary" : "secondary", onPress: () => {
+                                            setEventTypeId(eventType.id);
+                                            // The old pick belongs to the old type's grid and is
+                                            // almost never a legal slot on the new one.
+                                            setChosen(null);
+                                        }, children: eventType.name }, eventType.id))) })), _jsx(SlotPicker, { slots: slots, isLoading: isLoading, chosen: chosen, onChoose: setChosen, timeZone: timeZone }), _jsxs(TextField, { isRequired: true, variant: "secondary", children: [_jsx(Label, { children: "Name" }), _jsx(Input, { value: name, onChange: (e) => setName(e.currentTarget.value), disabled: isPending })] }), _jsxs(TextField, { isRequired: true, variant: "secondary", children: [_jsx(Label, { children: "Phone" }), _jsx(Input, { type: "tel", value: phone, onChange: (e) => setPhone(e.currentTarget.value), disabled: isPending })] }), error && _jsx("p", { className: "text-sm text-danger", children: error }), _jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { variant: "secondary", onPress: () => onOpenChange(false), isDisabled: isPending, children: "Cancel" }), _jsx(Button, { variant: "primary", isDisabled: !canSubmit, onPress: async () => {
+                                                clearError();
+                                                const booked = await createBooking({
+                                                    eventTypeId,
+                                                    startAt: chosen,
+                                                    attendee: { name: name.trim(), phone: phone.trim(), email: null },
+                                                });
+                                                if (booked)
+                                                    onBooked(booked);
+                                            }, children: isPending ? "Booking…" : "Book" })] })] })] }) }) }) }));
+}
+/**
+ * One appointment, and the two things anyone opens it to do.
+ *
+ * Rescheduling re-reads the slots with `excludeBookingId` set to this booking.
+ * Without that the appointment blocks its own replacement, and moving it by
+ * half an hour - the only move most people ever make - offers nothing.
+ */
+export function ConnectBookingDetail({ booking, eventType, timeZone, onOpenChange, onChanged, }) {
+    const [isMoving, setMoving] = useState(false);
+    const [chosen, setChosen] = useState(null);
+    const { rescheduleBooking, cancelBooking, isPending, error, clearError } = useBookingActions();
+    const start = new Date(booking.startAt);
+    const window = useMemo(() => ({
+        from: new Date(start.getTime() - 12 * 60 * 60_000),
+        to: new Date(start.getTime() + SEARCH_DAYS * 24 * 60 * 60_000),
+    }), [start]);
+    const { slots, isLoading } = useAvailableSlots(isMoving ? { eventTypeId: booking.eventTypeId, ...window, excludeBookingId: booking.id } : null);
+    return (_jsx(Modal, { isOpen: true, onOpenChange: onOpenChange, children: _jsx(Modal.Backdrop, { children: _jsx(Modal.Container, { children: _jsxs(Modal.Dialog, { children: [_jsx(Modal.Header, { children: booking.attendee.name }), _jsxs(Modal.Body, { className: "flex flex-col gap-4", children: [_jsxs("div", { className: "flex flex-col gap-1", children: [_jsxs("p", { className: "flex items-center gap-2 text-sm", children: [_jsx(Clock, { className: "size-4 text-muted", "aria-hidden": true }), longLabel(start, timeZone)] }), eventType && _jsx("p", { className: "text-sm text-muted", children: eventType.name }), _jsx("p", { className: "text-sm text-muted", children: booking.attendee.phone }), booking.notes && _jsx("p", { className: "pt-1 text-sm", children: booking.notes })] }), isMoving && (_jsx(SlotPicker, { slots: slots, isLoading: isLoading, chosen: chosen, onChoose: setChosen, timeZone: timeZone })), error && _jsx("p", { className: "text-sm text-danger", children: error }), _jsx("div", { className: "flex flex-wrap justify-end gap-2", children: isMoving ? (_jsxs(_Fragment, { children: [_jsx(Button, { variant: "secondary", onPress: () => setMoving(false), isDisabled: isPending, children: "Back" }), _jsx(Button, { variant: "primary", isDisabled: !chosen || isPending, onPress: async () => {
+                                                    clearError();
+                                                    const moved = await rescheduleBooking({
+                                                        bookingId: booking.id,
+                                                        startAt: chosen,
+                                                    });
+                                                    if (moved)
+                                                        onChanged();
+                                                }, children: isPending ? "Moving…" : "Move appointment" })] })) : (_jsxs(_Fragment, { children: [_jsx(Button, { variant: "danger", isDisabled: isPending, onPress: async () => {
+                                                    clearError();
+                                                    const cancelled = await cancelBooking({ bookingId: booking.id });
+                                                    if (cancelled)
+                                                        onChanged();
+                                                }, children: isPending ? "Cancelling…" : "Cancel appointment" }), _jsx(Button, { variant: "secondary", onPress: () => setMoving(true), children: "Reschedule" })] })) })] })] }) }) }) }));
+}
+function SlotPicker({ slots, isLoading, chosen, onChoose, timeZone, }) {
+    const byDay = useMemo(() => {
+        const groups = new Map();
+        const dayFormat = new Intl.DateTimeFormat("en-IN", {
+            timeZone,
+            weekday: "short",
+            day: "numeric",
+            month: "short",
+        });
+        for (const slot of slots) {
+            const label = dayFormat.format(new Date(slot.startAt));
+            groups.set(label, [...(groups.get(label) ?? []), slot]);
+        }
+        return [...groups.entries()];
+    }, [slots, timeZone]);
+    if (isLoading)
+        return _jsx("p", { className: "text-sm text-muted", children: "Finding free times\u2026" });
+    if (byDay.length === 0) {
+        return (_jsxs("div", { className: "flex items-center gap-2 rounded-lg border border-dashed border-separator p-4", children: [_jsx(CalendarX2, { className: "size-4 text-muted", "aria-hidden": true }), _jsx("p", { className: "text-sm text-muted", children: "Nothing free in the next two weeks." })] }));
+    }
+    return (_jsx("div", { className: "flex max-h-56 flex-col gap-3 overflow-y-auto", children: byDay.map(([day, daySlots]) => (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx("p", { className: "text-xs font-medium text-muted", children: day }), _jsx("div", { className: "grid grid-cols-2 gap-1.5 sm:grid-cols-4", children: daySlots.map((slot) => (_jsx(Button, { size: "sm", className: "w-full", variant: slot.startAt === chosen ? "primary" : "secondary", onPress: () => onChoose(slot.startAt), children: shortTime(new Date(slot.startAt), timeZone) }, slot.startAt))) })] }, day))) }));
+}
+function shortTime(instant, timeZone) {
+    return new Intl.DateTimeFormat("en-IN", {
+        timeZone,
+        hour: "numeric",
+        minute: "2-digit",
+        hour12: true,
+    }).format(instant);
+}
+function longLabel(instant, timeZone) {
+    return new Intl.DateTimeFormat("en-IN", {
+        timeZone,
+        weekday: "long",
+        day: "numeric",
+        month: "long",
+        hour: "numeric",
+        minute: "2-digit",
+        hour12: true,
+    }).format(instant);
+}

package/dist/esm/client/components/booking-grid.js

@@ -0,0 +1,199 @@
+/**
+ * An instant, as the local day and minute it lands on in `timeZone`.
+ *
+ * Built from `formatToParts` rather than by adding a fixed offset. An offset
+ * is only correct until a DST boundary, and "add 5.5 hours" is wrong the
+ * moment the same code is pointed at a zone that observes one - which is
+ * exactly the kind of bug that appears twice a year and never in a test.
+ */
+export function zonedInstant(instant, timeZone) {
+    const parts = partsFormatter(timeZone).formatToParts(instant);
+    const read = (type) => parts.find((part) => part.type === type)?.value ?? "00";
+    // `hourCycle: "h23"` so midnight is 00 rather than 24 - `hour12: false`
+    // alone still yields 24 in some engines, and a 24 would push midnight onto
+    // the wrong day.
+    return {
+        dateKey: `${read("year")}-${read("month")}-${read("day")}`,
+        minutes: Number(read("hour")) * 60 + Number(read("minute")),
+    };
+}
+const formatterCache = new Map();
+function partsFormatter(timeZone) {
+    let formatter = formatterCache.get(timeZone);
+    if (!formatter) {
+        // Cached because a grid calls this once per booking per render, and
+        // constructing an `Intl.DateTimeFormat` is the expensive part by a wide
+        // margin.
+        formatter = new Intl.DateTimeFormat("en-CA", {
+            timeZone,
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            hour: "2-digit",
+            minute: "2-digit",
+            hourCycle: "h23",
+        });
+        formatterCache.set(timeZone, formatter);
+    }
+    return formatter;
+}
+/**
+ * `count` consecutive days starting at the local day `anchor` falls on.
+ *
+ * Days are stepped by adding 24 hours and re-reading the zone rather than by
+ * incrementing a date field, so a day that is 23 or 25 hours long still
+ * produces the right sequence of `dateKey`s - the midday anchor is what keeps
+ * a DST shift from landing the step on the previous or next day.
+ */
+export function dayColumns(anchor, timeZone, count, now) {
+    const todayKey = zonedInstant(now, timeZone).dateKey;
+    const columns = [];
+    for (let index = 0; index < count; index += 1) {
+        const probe = new Date(anchor.getTime() + index * 24 * 60 * 60_000);
+        const { dateKey } = zonedInstant(probe, timeZone);
+        const startsAt = dayStartInstant(dateKey, timeZone);
+        columns.push({
+            dateKey,
+            label: new Intl.DateTimeFormat("en-IN", {
+                timeZone,
+                weekday: "short",
+                day: "numeric",
+            }).format(startsAt),
+            monthLabel: new Intl.DateTimeFormat("en-IN", { timeZone, month: "short" }).format(startsAt),
+            startsAt,
+            isToday: dateKey === todayKey,
+        });
+    }
+    return columns;
+}
+/**
+ * Local midnight of `dateKey` in `timeZone`, as an instant.
+ *
+ * Solved by probing rather than by arithmetic: guess UTC midnight, read what
+ * local time that actually is, and subtract the difference. One correction is
+ * always enough because a zone's offset cannot change within the few hours the
+ * correction spans - and unlike a fixed-offset formula it is right across DST
+ * and for the half-hour zones (`Asia/Kolkata`, `Australia/Adelaide`) that a
+ * naive implementation quietly breaks on.
+ */
+export function dayStartInstant(dateKey, timeZone) {
+    const utcGuess = new Date(`${dateKey}T00:00:00.000Z`);
+    const { dateKey: landedOn, minutes } = zonedInstant(utcGuess, timeZone);
+    // Whether the guess landed on the day before, the day itself, or the day
+    // after decides which way to correct.
+    const dayDelta = compareDateKeys(landedOn, dateKey);
+    return new Date(utcGuess.getTime() - (minutes + dayDelta * 1440) * 60_000);
+}
+function compareDateKeys(a, b) {
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+/**
+ * A fifteen-minute appointment on a twelve-hour grid is two percent tall -
+ * unreadable and unclickable. Short appointments are drawn at a floor and
+ * allowed to overhang, which is what every calendar does and what makes a
+ * back-to-back pair still look like two things.
+ */
+const MIN_VISIBLE_FRACTION = 0.02;
+/**
+ * Places bookings on the grid, side by side where they collide.
+ *
+ * Overlap handling is the part worth stating. Two appointments at the same
+ * time are not an error - a workspace with two hosts has them constantly - and
+ * stacking them would hide one entirely. So overlapping bookings are grouped
+ * into *clusters* and each cluster is split into equal columns. The cluster is
+ * built transitively: A overlapping B and B overlapping C puts all three in one
+ * cluster even when A and C do not touch, because anything else lets two of
+ * them land on the same column.
+ */
+export function layoutBookings(bookings, timeZone, window) {
+    const span = window.endMinute - window.startMinute;
+    if (span <= 0)
+        return [];
+    const byDay = new Map();
+    for (const booking of bookings) {
+        const start = zonedInstant(new Date(booking.startAt), timeZone);
+        const end = zonedInstant(new Date(booking.endAt), timeZone);
+        // An appointment that crosses local midnight is clamped to the end of the
+        // day it started on. Splitting it across two columns would be more correct
+        // and is not worth the complexity for a booking grid, where the longest
+        // event type is capped at eight hours server-side.
+        const endMinutes = end.dateKey === start.dateKey ? end.minutes : 1440;
+        const entries = byDay.get(start.dateKey) ?? [];
+        entries.push({ booking, start: start.minutes, end: Math.max(endMinutes, start.minutes + 1) });
+        byDay.set(start.dateKey, entries);
+    }
+    const positioned = [];
+    for (const [dateKey, entries] of byDay) {
+        entries.sort((a, b) => a.start - b.start || a.end - b.end);
+        for (const cluster of clusterOverlapping(entries)) {
+            cluster.forEach((entry, column) => {
+                const clampedStart = Math.max(entry.start, window.startMinute);
+                const clampedEnd = Math.min(entry.end, window.endMinute);
+                positioned.push({
+                    booking: entry.booking,
+                    dateKey,
+                    top: (clampedStart - window.startMinute) / span,
+                    height: Math.max((clampedEnd - clampedStart) / span, MIN_VISIBLE_FRACTION),
+                    column,
+                    columns: cluster.length,
+                    clipped: entry.start < window.startMinute || entry.end > window.endMinute,
+                });
+            });
+        }
+    }
+    return positioned;
+}
+/**
+ * Transitive overlap grouping - see `layoutBookings`.
+ *
+ * Entries arrive sorted by start. A cluster stays open while the next entry
+ * begins before the *furthest* end seen so far, not before the previous
+ * entry's end: a long appointment that swallows several short ones has to keep
+ * the whole run together.
+ */
+function clusterOverlapping(entries) {
+    const clusters = [];
+    let current = [];
+    let clusterEnd = -Infinity;
+    for (const entry of entries) {
+        if (current.length > 0 && entry.start >= clusterEnd) {
+            clusters.push(current);
+            current = [];
+            clusterEnd = -Infinity;
+        }
+        current.push(entry);
+        clusterEnd = Math.max(clusterEnd, entry.end);
+    }
+    if (current.length > 0)
+        clusters.push(current);
+    return clusters;
+}
+/**
+ * The hour labels down the left edge, inclusive of both ends.
+ *
+ * Takes no timezone, deliberately: these label *wall-clock hours on the grid*,
+ * not instants. The grid is already drawn in the business's zone, so "10 am"
+ * means the business's ten - running the label through a zone conversion would
+ * shift it away from the row it sits on.
+ */
+export function hourMarks(window) {
+    const marks = [];
+    const formatter = new Intl.DateTimeFormat("en-IN", {
+        timeZone: "UTC",
+        hour: "numeric",
+        hour12: true,
+    });
+    const firstHour = Math.ceil(window.startMinute / 60);
+    const lastHour = Math.floor(window.endMinute / 60);
+    for (let hour = firstHour; hour <= lastHour; hour += 1) {
+        marks.push({
+            minute: hour * 60,
+            // A synthetic UTC instant formatted in UTC - the round trip exists only
+            // to borrow `Intl`'s "10 am" / "12 pm" spelling, not to convert anything.
+            label: formatter.format(new Date(Date.UTC(2000, 0, 1, hour % 24))),
+        });
+    }
+    return marks;
+}

package/dist/esm/client/index.js

@@ -113,3 +113,7 @@ export { formatPrice, monthlyOf, resolveAction, annualSaving, discountLabel, ACT
 groupPlansByTier, resolvePlanGroup, } from "./components/plan-pricing.js";
 export { ConnectWorkspaceSwitcher } from "./components/workspace-switcher.js";
 export { useConnectWorkspaces, useConnectWorkspaceMembers } from "./provider.js";
+export { ConnectBookingCalendar } from "./components/booking-calendar.js";
+export { ConnectBookingDialog, ConnectBookingDetail } from "./components/booking-dialogs.js";
+export { useBookableEventTypes, useAvailableSlots, useBookings, useBookingActions, } from "./use-scheduling.js";
+export { layoutBookings, dayColumns, zonedInstant, } from "./components/booking-grid.js";

package/dist/esm/client/use-scheduling.js

@@ -0,0 +1,107 @@
+"use client";
+import { useCallback, useMemo, useState } from "react";
+import { useConnect, useConnectResource } from "./provider.js";
+/**
+ * The bridge's scheduling surface, as hooks.
+ *
+ * Every path here is one of the six the bridge exposes, and every one of them
+ * is resolved *for the signed-in member* - Connect takes the workspace from
+ * their session and checks their own `calendar:read` / `calendar:manage`.
+ * Nothing in this file names a workspace, and nothing should: a browser that
+ * can name a tenant is a browser that can read someone else's diary.
+ */
+/** What this workspace offers as bookable. Active types only. */
+export function useBookableEventTypes() {
+    const { data, isLoading, error } = useConnectResource("/scheduling/event-types");
+    return { eventTypes: data?.eventTypes ?? [], isLoading, error };
+}
+/**
+ * Free times for one appointment type.
+ *
+ * **Deliberately re-read rather than cached across a session.** A slot list is
+ * a snapshot of contention: anyone else on that calendar - a colleague, a
+ * voice agent mid-call, someone on the public booking link - can take one
+ * between the read and the click. Showing a stale one is how two people are
+ * offered the same minute. The booking call re-checks inside a transaction
+ * anyway, so a stale list costs a refusal rather than a double booking; this
+ * just means the refusal is rare.
+ */
+export function useAvailableSlots(query) {
+    const path = query
+        ? `/scheduling/slots?${new URLSearchParams({
+            eventTypeId: query.eventTypeId,
+            from: query.from.toISOString(),
+            to: query.to.toISOString(),
+            ...(query.excludeBookingId ? { excludeBookingId: query.excludeBookingId } : {}),
+        }).toString()}`
+        : null;
+    // `useConnectResource` needs a path; an empty one never resolves, so the
+    // hook is called unconditionally (rules of hooks) and simply idles.
+    const { data, isLoading, error, refetch } = useConnectResource(path ?? "");
+    return {
+        slots: path ? (data?.slots ?? []) : [],
+        timezone: data?.timezone ?? null,
+        durationMinutes: data?.durationMinutes ?? null,
+        isLoading: path ? isLoading : false,
+        error: path ? error : null,
+        refetch,
+    };
+}
+/** One page of the diary, ascending - a forward view, not a history. */
+export function useBookings(query) {
+    const path = useMemo(() => `/scheduling/bookings?${new URLSearchParams({
+        from: query.from.toISOString(),
+        to: query.to.toISOString(),
+        order: "asc",
+        status: "confirmed",
+        limit: String(query.limit ?? 100),
+        ...(query.hostMemberId ? { hostMemberId: query.hostMemberId } : {}),
+    }).toString()}`, [query.from, query.to, query.hostMemberId, query.limit]);
+    const { data, isLoading, error, refetch } = useConnectResource(path);
+    return {
+        bookings: data?.bookings ?? [],
+        hasMore: data?.hasMore ?? false,
+        isLoading,
+        error,
+        path,
+        refetch,
+    };
+}
+/**
+ * Book, move and cancel.
+ *
+ * **None of these is optimistic**, and that is not an oversight. Whether a
+ * slot is still free is a question only the server can answer, inside the
+ * transaction that decides it - two people can be holding the same minute
+ * right now. Painting a booking as made and withdrawing it is exactly the lie
+ * the two-phase hold exists to prevent.
+ */
+export function useBookingActions() {
+    const { mutateResource } = useConnect();
+    const [isPending, setPending] = useState(false);
+    const [error, setError] = useState(null);
+    const run = useCallback(async (path, body) => {
+        setPending(true);
+        setError(null);
+        try {
+            return await mutateResource(path, body);
+        }
+        catch (cause) {
+            // The server writes these as sentences - "that time was just taken" -
+            // precisely so they can be shown rather than mapped to a code.
+            setError(cause instanceof Error ? cause.message : "Something went wrong.");
+            return null;
+        }
+        finally {
+            setPending(false);
+        }
+    }, [mutateResource]);
+    return {
+        isPending,
+        error,
+        clearError: () => setError(null),
+        createBooking: (input) => run("/scheduling/bookings", input),
+        rescheduleBooking: (input) => run("/scheduling/bookings/reschedule", input).then((result) => result?.booking ?? null),
+        cancelBooking: (input) => run("/scheduling/bookings/cancel", input),
+    };
+}

package/dist/esm/server/client.js

@@ -4,6 +4,7 @@ import { AiResource } from "./resources/ai.js";
 import { DataResource, storePassthrough } from "./resources/data.js";
 import { WorkspacesResource } from "./resources/workspaces.js";
 import { SchedulingResource } from "./resources/scheduling.js";
+import { ContactsResource } from "./resources/contacts.js";
 import { KvResource } from "./resources/kv.js";
 import { BillingResource } from "./resources/billing.js";
 import { DriveResource } from "./resources/drive.js";
@@ -79,6 +80,8 @@ export class ConnectClient {
     drive;
     /** A subscribing workspace's own calendar - what is bookable, free, and booked. */
     scheduling;
+    /** Who a workspace already knows how to reach, by phone or by id. */
+    contacts;
     /** RAG chat and structured extraction. */
     ai;
     /** Your application's own document store - see `DataResource`. */
@@ -128,6 +131,7 @@ export class ConnectClient {
         this.billing = new BillingResource(transport);
         this.drive = new DriveResource(transport);
         this.scheduling = new SchedulingResource(transport);
+        this.contacts = new ContactsResource(transport);
         this.ai = new AiResource(transport);
         this.data = new DataResource(transport);
         this.kv = new KvResource(transport);
@@ -142,4 +146,4 @@ export class ConnectClient {
     }
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export const SDK_VERSION = "0.17.0";
+export const SDK_VERSION = "0.19.0";