@hanzo/booker 0.1.0

package/src/client.ts

@@ -0,0 +1,218 @@
+// Data plane for the Hanzo Calendar (Cal API-v2 shapes).
+// Pure fetch layer — no React, no DOM. Runs on web and React Native.
+
+export const DEFAULT_API_URL = 'https://api.hanzo.ai/v1/calendar'
+export const CAL_API_VERSION = '2024-08-13'
+
+export interface Location {
+  type?: string
+  link?: string
+  address?: string
+}
+
+export interface Profile {
+  name?: string | null
+  username?: string | null
+  image?: string | null
+  avatarUrl?: string | null
+}
+
+export interface EventType {
+  id: number
+  slug: string
+  title: string
+  description: string
+  /** duration in minutes */
+  length: number
+  locations: Location[]
+  price: number
+  currency: string
+  profile?: Profile
+}
+
+export interface Slot {
+  /** ISO-8601 UTC instant, e.g. "2026-07-24T16:00:00Z" */
+  time: string
+}
+
+/** Slots grouped by day key "YYYY-MM-DD" (in the requested time zone). */
+export type SlotsByDay = Record<string, Slot[]>
+
+export interface Attendee {
+  name?: string
+  email?: string
+  timeZone?: string
+}
+
+export interface Booking {
+  uid: string
+  status: string
+  start: string
+  end: string
+  title: string
+  location?: string
+  attendees?: Attendee[]
+}
+
+export interface BookingResponses {
+  name: string
+  email: string
+  notes?: string
+}
+
+export interface CreateBookingInput {
+  eventTypeSlug: string
+  username: string
+  /** ISO instant of the chosen slot */
+  start: string
+  timeZone: string
+  responses: BookingResponses
+}
+
+export interface SlotsInput {
+  eventTypeSlug: string
+  username: string
+  startTime: string
+  endTime: string
+  timeZone: string
+}
+
+/** Error carrying the HTTP status; `conflict` marks a 409 (slot just taken). */
+export class CalendarError extends Error {
+  status: number
+  conflict: boolean
+  constructor(message: string, status: number) {
+    super(message)
+    this.name = 'CalendarError'
+    this.status = status
+    this.conflict = status === 409
+  }
+}
+
+interface Envelope<T> {
+  data?: T
+  error?: { message?: string }
+  message?: string
+}
+
+function messageOf(body: unknown, status: number): string {
+  const b = body as Envelope<unknown> | null
+  return b?.error?.message || b?.message || `Request failed (${status})`
+}
+
+async function readJson(res: Response): Promise<unknown> {
+  return res.json().catch(() => null)
+}
+
+async function getJson<T>(url: string, signal?: AbortSignal): Promise<T> {
+  const res = await fetch(url, { headers: { Accept: 'application/json' }, signal })
+  const body = await readJson(res)
+  if (!res.ok) throw new CalendarError(messageOf(body, res.status), res.status)
+  return (body as Envelope<T>).data as T
+}
+
+function normalizeEventType(raw: Record<string, unknown>): EventType {
+  const length =
+    (raw.length as number) ??
+    (raw.lengthInMinutes as number) ??
+    (raw.durationMinutes as number) ??
+    30
+  return {
+    id: Number(raw.id ?? 0),
+    slug: String(raw.slug ?? ''),
+    title: String(raw.title ?? ''),
+    description: String(raw.description ?? ''),
+    length,
+    locations: (raw.locations as Location[]) ?? [],
+    price: Number(raw.price ?? 0),
+    currency: String(raw.currency ?? 'usd'),
+    profile: raw.profile as Profile | undefined,
+  }
+}
+
+export async function fetchEventType(
+  api: string,
+  eventSlug: string,
+  username: string,
+  signal?: AbortSignal
+): Promise<EventType> {
+  const url = `${api}/atoms/event-types/${encodeURIComponent(eventSlug)}/public?username=${encodeURIComponent(username)}`
+  const raw = await getJson<Record<string, unknown>>(url, signal)
+  return normalizeEventType(raw)
+}
+
+export async function fetchSlots(
+  api: string,
+  input: SlotsInput,
+  signal?: AbortSignal
+): Promise<SlotsByDay> {
+  const q = new URLSearchParams({
+    eventTypeSlug: input.eventTypeSlug,
+    usernameList: input.username,
+    startTime: input.startTime,
+    endTime: input.endTime,
+    timeZone: input.timeZone,
+  })
+  const data = await getJson<{ slots?: SlotsByDay } | SlotsByDay>(
+    `${api}/slots/available?${q.toString()}`,
+    signal
+  )
+  // API returns { data: { slots: {...} } }; tolerate a bare map too.
+  const slots = (data as { slots?: SlotsByDay }).slots ?? (data as SlotsByDay)
+  return slots ?? {}
+}
+
+export async function createBooking(
+  api: string,
+  input: CreateBookingInput,
+  signal?: AbortSignal
+): Promise<Booking> {
+  const res = await fetch(`${api}/bookings`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      'cal-api-version': CAL_API_VERSION,
+    },
+    body: JSON.stringify({
+      eventTypeSlug: input.eventTypeSlug,
+      user: input.username,
+      start: input.start,
+      timeZone: input.timeZone,
+      responses: input.responses,
+    }),
+    signal,
+  })
+  const body = await readJson(res)
+  if (!res.ok) throw new CalendarError(messageOf(body, res.status), res.status)
+  return (body as Envelope<Booking>).data as Booking
+}
+
+export async function fetchBooking(
+  api: string,
+  uid: string,
+  signal?: AbortSignal
+): Promise<Booking> {
+  return getJson<Booking>(`${api}/bookings/${encodeURIComponent(uid)}`, signal)
+}
+
+export async function cancelBooking(
+  api: string,
+  uid: string,
+  reason?: string,
+  signal?: AbortSignal
+): Promise<Booking> {
+  const res = await fetch(`${api}/bookings/${encodeURIComponent(uid)}/cancel`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      'cal-api-version': CAL_API_VERSION,
+    },
+    body: JSON.stringify({ reason: reason ?? '' }),
+    signal,
+  })
+  const body = await readJson(res)
+  if (!res.ok) throw new CalendarError(messageOf(body, res.status), res.status)
+  return (body as Envelope<Booking>).data as Booking
+}

package/src/hooks.ts

@@ -0,0 +1,180 @@
+// React data hooks over the client. useState/useEffect only — no query lib.
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import {
+  createBooking,
+  fetchBooking,
+  fetchEventType,
+  fetchSlots,
+  CalendarError,
+  type Booking,
+  type BookingResponses,
+  type EventType,
+  type SlotsByDay,
+} from './client'
+
+export interface AsyncState<T> {
+  data: T | null
+  loading: boolean
+  error: string | null
+}
+
+export function useEventType(
+  api: string,
+  eventSlug: string,
+  username: string
+): AsyncState<EventType> {
+  const [state, setState] = useState<AsyncState<EventType>>({
+    data: null,
+    loading: true,
+    error: null,
+  })
+  useEffect(() => {
+    const ctrl = new AbortController()
+    setState({ data: null, loading: true, error: null })
+    fetchEventType(api, eventSlug, username, ctrl.signal)
+      .then((data) => setState({ data, loading: false, error: null }))
+      .catch((err: unknown) => {
+        if (ctrl.signal.aborted) return
+        setState({ data: null, loading: false, error: errorText(err) })
+      })
+    return () => ctrl.abort()
+  }, [api, eventSlug, username])
+  return state
+}
+
+export interface SlotsQuery {
+  eventTypeSlug: string
+  username: string
+  startTime: string
+  endTime: string
+  timeZone: string
+  enabled?: boolean
+}
+
+export interface SlotsState extends AsyncState<SlotsByDay> {
+  refetch: () => void
+}
+
+export function useAvailableSlots(api: string, query: SlotsQuery): SlotsState {
+  const { eventTypeSlug, username, startTime, endTime, timeZone, enabled = true } = query
+  const [state, setState] = useState<AsyncState<SlotsByDay>>({
+    data: null,
+    loading: enabled,
+    error: null,
+  })
+  const [nonce, setNonce] = useState(0)
+  const refetch = useCallback(() => setNonce((n) => n + 1), [])
+
+  useEffect(() => {
+    if (!enabled) return
+    const ctrl = new AbortController()
+    setState((s) => ({ data: s.data, loading: true, error: null }))
+    fetchSlots(
+      api,
+      { eventTypeSlug, username, startTime, endTime, timeZone },
+      ctrl.signal
+    )
+      .then((data) => setState({ data, loading: false, error: null }))
+      .catch((err: unknown) => {
+        if (ctrl.signal.aborted) return
+        setState({ data: null, loading: false, error: errorText(err) })
+      })
+    return () => ctrl.abort()
+  }, [api, eventTypeSlug, username, startTime, endTime, timeZone, enabled, nonce])
+
+  return { ...state, refetch }
+}
+
+export type SubmitResult =
+  | { ok: true; booking: Booking }
+  | { ok: false; conflict: boolean; message: string }
+
+export interface CreateBookingState {
+  submit: (input: {
+    eventTypeSlug: string
+    username: string
+    start: string
+    timeZone: string
+    responses: BookingResponses
+  }) => Promise<SubmitResult>
+  submitting: boolean
+  error: string | null
+  conflict: boolean
+  reset: () => void
+}
+
+export function useCreateBooking(api: string): CreateBookingState {
+  const [submitting, setSubmitting] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [conflict, setConflict] = useState(false)
+  const mounted = useRef(true)
+  useEffect(() => {
+    mounted.current = true
+    return () => {
+      mounted.current = false
+    }
+  }, [])
+
+  const reset = useCallback(() => {
+    setError(null)
+    setConflict(false)
+  }, [])
+
+  const submit = useCallback(
+    async (input: {
+      eventTypeSlug: string
+      username: string
+      start: string
+      timeZone: string
+      responses: BookingResponses
+    }): Promise<SubmitResult> => {
+      setSubmitting(true)
+      setError(null)
+      setConflict(false)
+      try {
+        const booking = await createBooking(api, input)
+        return { ok: true, booking }
+      } catch (err: unknown) {
+        const isConflict = err instanceof CalendarError && err.conflict
+        const message = errorText(err)
+        if (mounted.current) {
+          setError(message)
+          setConflict(isConflict)
+        }
+        return { ok: false, conflict: isConflict, message }
+      } finally {
+        if (mounted.current) setSubmitting(false)
+      }
+    },
+    [api]
+  )
+
+  return { submit, submitting, error, conflict, reset }
+}
+
+export function useBooking(api: string, uid: string | undefined): AsyncState<Booking> {
+  const [state, setState] = useState<AsyncState<Booking>>({
+    data: null,
+    loading: !!uid,
+    error: null,
+  })
+  useEffect(() => {
+    if (!uid) return
+    const ctrl = new AbortController()
+    setState({ data: null, loading: true, error: null })
+    fetchBooking(api, uid, ctrl.signal)
+      .then((data) => setState({ data, loading: false, error: null }))
+      .catch((err: unknown) => {
+        if (ctrl.signal.aborted) return
+        setState({ data: null, loading: false, error: errorText(err) })
+      })
+    return () => ctrl.abort()
+  }, [api, uid])
+  return state
+}
+
+function errorText(err: unknown): string {
+  if (err instanceof Error) return err.message
+  return 'Something went wrong'
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+// @hanzo/calendar — universal (web + native) booking UI on the Hanzo Calendar
+// backend, built with hanzogui primitives.
+
+export { Booker, type BookerProps } from './Booker'
+export { CalendarEmbed, type CalendarEmbedProps } from './CalendarEmbed'
+export { Confirmation, type ConfirmationProps } from './Confirmation'
+
+// Composable sub-views (use these to build a custom flow).
+export { EventHeader, type EventHeaderProps } from './EventHeader'
+export { MonthCalendar, type MonthCalendarProps } from './MonthCalendar'
+export { TimeSlots, type TimeSlotsProps } from './TimeSlots'
+export { BookingForm, type BookingFormProps } from './BookingForm'
+
+// Orchestration hook + data hooks.
+export {
+  useBooker,
+  type UseBookerOptions,
+  type BookerModel,
+  type BookerPhase,
+} from './useBooker'
+export {
+  useEventType,
+  useAvailableSlots,
+  useCreateBooking,
+  useBooking,
+  type AsyncState,
+  type SlotsQuery,
+  type SlotsState,
+  type CreateBookingState,
+  type SubmitResult,
+} from './hooks'
+
+// Data plane.
+export {
+  DEFAULT_API_URL,
+  CAL_API_VERSION,
+  CalendarError,
+  fetchEventType,
+  fetchSlots,
+  createBooking,
+  fetchBooking,
+  cancelBooking,
+  type EventType,
+  type Slot,
+  type SlotsByDay,
+  type Booking,
+  type Attendee,
+  type Location,
+  type Profile,
+  type BookingResponses,
+  type CreateBookingInput,
+  type SlotsInput,
+} from './client'
+
+// Time plane (Intl/Date helpers).
+export {
+  visitorTimeZone,
+  ymd,
+  monthMatrix,
+  monthRange,
+  weekdayLabels,
+  formatMonthLabel,
+  formatDayLong,
+  formatSlotTime,
+  formatBookingWhen,
+  dateFromKey,
+  startOfMonth,
+  addMonths,
+  sameMonth,
+  isBeforeToday,
+  type MonthCell,
+} from './time'

package/src/time.ts

@@ -0,0 +1,131 @@
+// Time plane — pure date/timezone helpers via Intl + Date only.
+// No external date library. Web and React Native safe.
+
+/** The visitor's IANA time zone, e.g. "America/New_York". */
+export function visitorTimeZone(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC'
+  } catch {
+    return 'UTC'
+  }
+}
+
+/** Calendar date "YYYY-MM-DD" from a Date's local components. */
+export function ymd(d: Date): string {
+  const y = d.getFullYear()
+  const m = String(d.getMonth() + 1).padStart(2, '0')
+  const day = String(d.getDate()).padStart(2, '0')
+  return `${y}-${m}-${day}`
+}
+
+export function startOfMonth(d: Date): Date {
+  return new Date(d.getFullYear(), d.getMonth(), 1)
+}
+
+export function addMonths(d: Date, n: number): Date {
+  return new Date(d.getFullYear(), d.getMonth() + n, 1)
+}
+
+export function sameMonth(a: Date, b: Date): boolean {
+  return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth()
+}
+
+/** True if the day key is strictly before today (lexicographic works on YYYY-MM-DD). */
+export function isBeforeToday(key: string): boolean {
+  return key < ymd(new Date())
+}
+
+export interface MonthCell {
+  date: Date
+  key: string
+  inMonth: boolean
+}
+
+/**
+ * A 6×7 grid of days covering the month of `viewDate`, including the leading
+ * and trailing days needed to fill whole weeks.
+ */
+export function monthMatrix(viewDate: Date, weekStartsOn = 0): MonthCell[] {
+  const year = viewDate.getFullYear()
+  const month = viewDate.getMonth()
+  const firstWeekday = new Date(year, month, 1).getDay()
+  const startOffset = (firstWeekday - weekStartsOn + 7) % 7
+  const cells: MonthCell[] = []
+  for (let i = 0; i < 42; i++) {
+    const date = new Date(year, month, 1 - startOffset + i)
+    cells.push({ date, key: ymd(date), inMonth: date.getMonth() === month })
+  }
+  return cells
+}
+
+/**
+ * ISO start/end covering the visible month, clamped so the start is never in
+ * the past (the backend rejects past ranges anyway).
+ */
+export function monthRange(viewDate: Date): { startTime: string; endTime: string } {
+  const year = viewDate.getFullYear()
+  const month = viewDate.getMonth()
+  const startOfView = new Date(year, month, 1, 0, 0, 0, 0)
+  const now = new Date()
+  const start = startOfView.getTime() > now.getTime() ? startOfView : now
+  const endOfView = new Date(year, month + 1, 0, 23, 59, 59, 999)
+  return { startTime: start.toISOString(), endTime: endOfView.toISOString() }
+}
+
+/** Short weekday headers ordered from `weekStartsOn` (0 = Sunday). */
+export function weekdayLabels(weekStartsOn = 0): string[] {
+  const fmt = new Intl.DateTimeFormat(undefined, { weekday: 'short' })
+  const out: string[] = []
+  for (let i = 0; i < 7; i++) {
+    // 2023-01-01 is a Sunday; offset from there.
+    const d = new Date(2023, 0, 1 + ((i + weekStartsOn) % 7))
+    out.push(fmt.format(d))
+  }
+  return out
+}
+
+export function formatMonthLabel(d: Date): string {
+  return new Intl.DateTimeFormat(undefined, { month: 'long', year: 'numeric' }).format(d)
+}
+
+export function formatDayLong(d: Date): string {
+  return new Intl.DateTimeFormat(undefined, {
+    weekday: 'long',
+    month: 'long',
+    day: 'numeric',
+  }).format(d)
+}
+
+/** Slot time in the visitor's zone, e.g. "9:00 AM". */
+export function formatSlotTime(iso: string, timeZone: string): string {
+  return new Intl.DateTimeFormat(undefined, {
+    hour: 'numeric',
+    minute: '2-digit',
+    timeZone,
+  }).format(new Date(iso))
+}
+
+/** Full human "when" for a confirmation, e.g. "Monday, July 27, 2026 at 9:00 AM PDT". */
+export function formatBookingWhen(iso: string, timeZone: string): string {
+  const at = new Date(iso)
+  const date = new Intl.DateTimeFormat(undefined, {
+    weekday: 'long',
+    month: 'long',
+    day: 'numeric',
+    year: 'numeric',
+    timeZone,
+  }).format(at)
+  const time = new Intl.DateTimeFormat(undefined, {
+    hour: 'numeric',
+    minute: '2-digit',
+    timeZoneName: 'short',
+    timeZone,
+  }).format(at)
+  return `${date} at ${time}`
+}
+
+/** A parsed local Date from a "YYYY-MM-DD" key (noon avoids DST edge slips). */
+export function dateFromKey(key: string): Date {
+  const [y, m, d] = key.split('-').map(Number)
+  return new Date(y, (m ?? 1) - 1, d ?? 1, 12, 0, 0, 0)
+}