@graph8/sdk 0.358.0 → 0.362.0

package/blocks/_foundation/hooks/use-url-state.ts

@@ -0,0 +1,74 @@
+"use client";
+
+/**
+ * useUrlState: one string in the URL query (`?id=123`, `?tab=activity`, `?q=ada`) as React state.
+ * The URL owns it, so the open record, the tab and the search survive reload, Back and sharing.
+ * Framework-agnostic: window.history.replaceState (pushState with `{ push: true }`) plus `popstate`,
+ * no next/navigation. SSR-safe: the server and the first client render see `defaultValue`.
+ *
+ * SDK operations: none.
+ */
+import { useCallback, useSyncExternalStore } from "react";
+
+const EVENT = "g8:urlstate";
+
+type Listener = () => void;
+
+function subscribe(listener: Listener): () => void {
+  if (typeof window !== "undefined") {
+    window.addEventListener("popstate", listener);
+    window.addEventListener(EVENT, listener);
+  }
+  return () => {
+    if (typeof window !== "undefined") {
+      window.removeEventListener("popstate", listener);
+      window.removeEventListener(EVENT, listener);
+    }
+  };
+}
+
+/** Current value of `key` in the page URL, or undefined. */
+export function readUrlParam(key: string): string | undefined {
+  if (typeof window === "undefined") return undefined;
+  const v = new URLSearchParams(window.location.search).get(key);
+  return v == null ? undefined : v;
+}
+
+export interface SetUrlStateOptions {
+  /** Add a history entry (Back returns to the previous value) instead of replacing. */
+  push?: boolean;
+}
+
+/** Write `key` into the page URL (null, undefined or "" removes it) and notify every hook. */
+export function writeUrlParam(key: string, value: string | null | undefined, options: SetUrlStateOptions = {}): void {
+  if (typeof window === "undefined") return;
+  const url = new URL(window.location.href);
+  const current = url.searchParams.get(key);
+  const next = value == null || value === "" ? null : String(value);
+  if (current === next) return;
+  if (next == null) url.searchParams.delete(key);
+  else url.searchParams.set(key, next);
+  const href = `${url.pathname}${url.search}${url.hash}`;
+  if (options.push) window.history.pushState(window.history.state, "", href);
+  else window.history.replaceState(window.history.state, "", href);
+  window.dispatchEvent(new Event(EVENT));
+}
+
+export type UrlStateSetter = (value: string | null | undefined, options?: SetUrlStateOptions) => void;
+
+/**
+ * `const [id, setId] = useUrlState("id")`: `id` is the param or `defaultValue` ("" by default); `setId(null)`
+ * or `setId("")` removes it; `setId("42", { push: true })` adds a history entry.
+ */
+export function useUrlState(key: string, defaultValue = ""): [string, UrlStateSetter] {
+  const value = useSyncExternalStore(
+    subscribe,
+    () => readUrlParam(key) ?? defaultValue,
+    () => defaultValue,
+  );
+  const set = useCallback<UrlStateSetter>(
+    (next, options) => writeUrlParam(key, next == null || next === defaultValue ? null : next, options),
+    [key, defaultValue],
+  );
+  return [value, set];
+}

package/blocks/appointments/README.md

@@ -4,6 +4,25 @@ Event types, weekly working hours, a booking page, a list of booked and recorded
 rep takes on a booking (confirm, cancel, add a note). Install with `npx @graph8/sdk add appointments`
 (depends on `crm`).
 
+## Screens
+
+- `MeetingsScreen` (`components/meetings-screen.tsx`): `<MeetingsScreen />`. Upcoming, Past, Cancelled and Recorded
+  meetings; headline numbers (upcoming, awaiting approval); open a booking (deep link `?sel=booking:<uid>`) to accept or
+  decline a pending one, add an internal note or cancel (all confirmed, they email attendees), or open a recorded
+  meeting for its summary, topics, action items and transcript. **Schedule a meeting** picks an event type, a day and a
+  time and books it for an attendee (external, confirmed). Calendar sign-in is only possible in the graph8 app, so the
+  screen shows a link-out card (`connectCalendarUrl`).
+- `SchedulingScreen` (`components/scheduling-screen.tsx`): `<SchedulingScreen />`. Event types tab: the list (from
+  `GET /event-types`), create, open one (`?id=<event type id>`) to edit or delete it (confirmed) and to try its booking
+  page. Working hours tab: weekly hours, date overrides and connected calendars for a schedule.
+- Slots for cross-block glue, all optional: `renderRowActions`, `renderDetailActions`, `extraDetailTabs`,
+  `toolbarActions`.
+
+The older note that there is no list-event-types operation is out of date: `GET /event-types` (`useEventTypes`) lists
+them, so ids no longer have to be stored. It needs the `campaigns:read` scope and `event-types` in the proxy
+`allowedPrefixes`, next to `appointments` and `inbox`.
+
+
 ## The flow, in order
 
 1. **Hours** (`AvailabilityEditor`): `GET /appointments/schedules` -> pick `schedule.id` ->
@@ -30,7 +49,7 @@ booking), `booking.uid` (list -> detail -> confirm/cancel/notes), recorded `meet
   not in the API. `AvailabilityEditor` shows connection state and links out via `connectCalendarUrl`.
 - Use an API key minted by the host. Appointments act as a person; an organisation key can read and
   list slots, but anything personal (profile, slot reservation) requires a personal key.
-- Scopes: `meetings:read`, `meetings:write`, `meetings:run`, `meetings:delete` (cancel a booking, delete an event type).
+- Scopes: `meetings:read`, `meetings:write`, `meetings:run`, `meetings:delete` (cancel a booking, delete an event type), plus `campaigns:read` for the event-type list.
 
 ## Defaults (the agent does not need to ask)
 
@@ -70,6 +89,7 @@ with the full API key.
 | `appointments.addBookingNote` | POST /appointments/bookings/{uid}/notes | external | MeetingDetail |
 | `meetings.listMeetings` | GET /inbox/meetings | read | MeetingList |
 | `meetings.getMeeting` | GET /inbox/meetings/{id} | read | MeetingDetail |
+| `gtmLaunchHelpers.listEventTypes` | GET /event-types | read | useEventTypes (both screens) |
 
 ## Recipes (server side)
 

package/blocks/appointments/block.json

@@ -27,6 +27,7 @@
     "get_meeting_inbox_meetings__meeting_id__get",
     "list_bookings_appointments_bookings_get",
     "list_calendars_appointments_calendars_get",
+    "list_event_types_event_types_get",
     "list_meetings_inbox_meetings_get",
     "list_schedules_appointments_schedules_get",
     "update_availability_appointments_schedules__schedule_id__availability_patch",
@@ -107,6 +108,32 @@
         "external",
         "destructive"
       ]
+    },
+    {
+      "name": "MeetingsScreen",
+      "file": "components/meetings-screen.tsx",
+      "purpose": "Finished meetings product: upcoming, past, cancelled and recorded meetings with detail, approvals, notes and a schedule-a-meeting flow.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "SchedulingScreen",
+      "file": "components/scheduling-screen.tsx",
+      "purpose": "Finished scheduling product: event types with settings and booking-page preview, plus weekly working hours and calendar status.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "EventTypeOverview",
+      "file": "components/event-type-related.tsx",
+      "purpose": "Read views of one event type: every field (EventTypeOverview) and the bookings made through it (EventTypeBookings, with MeetingDetail in a sheet).",
+      "operations": [
+        "get_event_type_appointments_event_types__event_type_id__get",
+        "list_bookings_appointments_bookings_get"
+      ],
+      "tiers": [
+        "read"
+      ]
     }
   ],
   "hooks": [
@@ -125,6 +152,14 @@
       "operations": [
         "get_available_slots_appointments_slots_get"
       ]
+    },
+    {
+      "name": "useEventTypes",
+      "file": "hooks/use-event-types.ts",
+      "purpose": "The org's bookable event types (the list operation the editor needs).",
+      "operations": [
+        "list_event_types_event_types_get"
+      ]
     }
   ],
   "lib": [
@@ -174,12 +209,13 @@
     },
     {
       "id": "meetings-scopes",
-      "description": "Key scopes meetings:read, meetings:write, meetings:run (booking, confirm, notes are tier external) and meetings:delete (cancel, delete event type).",
+      "description": "Key scopes meetings:read, meetings:write, meetings:run (booking, confirm, notes are tier external) and meetings:delete (cancel, delete event type), plus campaigns:read for the event-type list (GET /event-types).",
       "where": "api",
       "verify": "`g8.api.me.describeCurrentKey()` lists the meetings:* scopes."
     }
   ],
   "scopes": [
+    "campaigns:read",
     "meetings:delete",
     "meetings:read",
     "meetings:run",
@@ -213,6 +249,7 @@
     }
   ],
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
   }
 }

package/blocks/appointments/components/event-type-related.tsx

@@ -0,0 +1,75 @@
+"use client";
+
+/**
+ * Read views of one event type, as tabs of its full detail: Overview (every field) and Bookings (who booked it).
+ *
+ * SDK operations, in order:
+ *   EventTypeOverview: GET /appointments/event-types/{id}                          (appointments.getEventType)  read
+ *   EventTypeBookings: GET /appointments/bookings?event_type_ids=&skip=&take=      (appointments.listBookings)  read
+ *                      then MeetingDetail in a side sheet for the booking you open (confirm, cancel and notes
+ *                      are external or destructive there and go through ConfirmSpendDialog).
+ */
+import { useState } from "react";
+import { CalendarClock } from "lucide-react";
+import { Button, Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill, humanizeStatus, toneForStatus } from "@/g8/components/screen/status-pill";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { formatDateTime, listOf, unwrap, type Booking, type EventType } from "../lib/appointments-types";
+import { MeetingDetail } from "./meeting-detail";
+
+export function EventTypeOverview({ eventTypeId }: { eventTypeId: number }) {
+  const q = useG8Query(async (signal) => unwrap<EventType>(await g8Get(`/appointments/event-types/${eventTypeId}`, undefined, { signal })), [eventTypeId]);
+  if (q.error) return <ApiError error={q.error} title="Could not load the event type" onRetry={() => void q.refetch()} />;
+  if (!q.data) return <Skeleton className="h-32 w-full" aria-label="Loading event type" />;
+  const t = q.data;
+  return (
+    <SectionCard title="Details">
+      <KeyValueList columns={2} items={[
+        { label: "Title", value: t.title }, { label: "URL slug", value: t.slug ? `/${t.slug}` : null, mono: true }, { label: "Length", value: t.length ? `${t.length} minutes` : null },
+        { label: "Working hours", value: t.schedule?.name }, { label: "Minimum notice", value: t.minimum_booking_notice != null ? `${t.minimum_booking_notice} minutes` : null },
+        { label: "Host approval", value: t.requires_confirmation ? "Required" : "Not required" }, { label: "Visibility", value: t.hidden ? "Hidden" : "Bookable" },
+        { label: "Scheduling type", value: t.scheduling_type ?? "Single host" }, { label: "Description", value: t.description, wide: true },
+      ]} />
+    </SectionCard>
+  );
+}
+
+export function EventTypeBookings({ eventTypeId, pageSize = 20 }: { eventTypeId: number; pageSize?: number }) {
+  const [page, setPage] = useState(0);
+  const [open, setOpen] = useState<string | null>(null);
+  const q = useG8Query(async (signal) => listOf<Booking>(await g8Get("/appointments/bookings", { event_type_ids: String(eventTypeId), skip: page * pageSize, take: pageSize, sort_by: "start_time", sort_order: "desc" }, { signal }), "bookings"), [eventTypeId, page, pageSize]);
+  if (q.error) return <ApiError error={q.error} title="Could not load bookings" onRetry={() => void q.refetch()} />;
+  if (!q.data) return <Skeleton className="h-32 w-full" aria-label="Loading bookings" />;
+  if (q.data.length === 0 && page === 0) return <EmptyState icon={<CalendarClock className="size-8" />} title="No bookings yet" description="Bookings made through this event type appear here." />;
+  return (
+    <div className="space-y-3">
+      <Table>
+        <TableHeader><TableRow><TableHead>When</TableHead><TableHead>Attendees</TableHead><TableHead>Status</TableHead></TableRow></TableHeader>
+        <TableBody>
+          {q.data.map((b) => (
+            <TableRow key={b.uid} className="cursor-pointer" onClick={() => setOpen(b.uid)}>
+              <TableCell><button type="button" className="font-medium hover:underline" onClick={(e) => { e.stopPropagation(); setOpen(b.uid); }}>{formatDateTime(b.start_time)}</button></TableCell>
+              <TableCell className="max-w-64 truncate">{b.attendees.map((a) => a.name || a.email).join(", ") || "No attendees"}</TableCell>
+              <TableCell><StatusPill tone={toneForStatus(b.status)} dot>{humanizeStatus(b.status)}</StatusPill></TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+      <div className="flex justify-end gap-2">
+        <Button size="sm" variant="outline" disabled={page === 0 || q.loading} onClick={() => setPage((p) => p - 1)}>Previous</Button>
+        <Button size="sm" variant="outline" disabled={q.data.length < pageSize || q.loading} onClick={() => setPage((p) => p + 1)}>Next</Button>
+      </div>
+      <Sheet open={open != null} onOpenChange={(o) => { if (!o) setOpen(null); }}>
+        <SheetContent className="w-full overflow-y-auto sm:max-w-xl">
+          <SheetHeader><SheetTitle>Booking</SheetTitle><SheetDescription>Accept, decline, note or cancel.</SheetDescription></SheetHeader>
+          {open ? <MeetingDetail selection={{ kind: "booking", id: open }} onChanged={() => void q.refetch()} /> : null}
+        </SheetContent>
+      </Sheet>
+    </div>
+  );
+}

package/blocks/appointments/components/meeting-list.tsx

@@ -27,6 +27,10 @@ export interface MeetingListProps {
   onSelect?: (selection: MeetingSelection) => void;
   initialView?: MeetingView;
   pageSize?: number;
+  /** Change it to reload the current page (after a confirm, cancel or booking elsewhere on the screen). */
+  refreshKey?: number;
+  /** Mark this row as the open one. */
+  selectedId?: string | null;
   className?: string;
 }
 
@@ -54,7 +58,7 @@ function useDebouncedText(value: string, ms = 300): string {
   return v;
 }
 
-export function MeetingList({ onSelect, initialView = "upcoming", pageSize = 20, className }: MeetingListProps) {
+export function MeetingList({ onSelect, initialView = "upcoming", pageSize = 20, refreshKey, selectedId, className }: MeetingListProps) {
   const [view, setView] = useState<MeetingView>(initialView);
   const [page, setPage] = useState(0);
   const [search, setSearch] = useState("");
@@ -71,7 +75,7 @@ export function MeetingList({ onSelect, initialView = "upcoming", pageSize = 20,
       const items = listOf<Booking>(env, "bookings");
       return { kind: "booking" as const, items, more: items.length === pageSize };
     },
-    [view, page, query, pageSize, now],
+    [view, page, query, pageSize, now, refreshKey],
   );
 
   const switchView = (next: MeetingView) => {
@@ -116,7 +120,7 @@ export function MeetingList({ onSelect, initialView = "upcoming", pageSize = 20,
           <TableBody>
             {result.kind === "booking"
               ? (result.items as Booking[]).map((b) => (
-                  <TableRow key={b.uid} className="cursor-pointer" onClick={() => onSelect?.({ kind: "booking", id: b.uid })}>
+                  <TableRow key={b.uid} data-state={selectedId === b.uid ? "selected" : undefined} className="cursor-pointer" onClick={() => onSelect?.({ kind: "booking", id: b.uid })}>
                     <TableCell className="whitespace-nowrap">{formatDateTime(b.start_time)}</TableCell>
                     <TableCell className="font-medium">{b.title || b.event_type_title || "Meeting"}</TableCell>
                     <TableCell className="max-w-64 truncate">{attendeeNames(b)}</TableCell>
@@ -124,7 +128,7 @@ export function MeetingList({ onSelect, initialView = "upcoming", pageSize = 20,
                   </TableRow>
                 ))
               : (result.items as RecordedMeeting[]).map((m) => (
-                  <TableRow key={m.id} className="cursor-pointer" onClick={() => onSelect?.({ kind: "meeting", id: m.id })}>
+                  <TableRow key={m.id} data-state={selectedId === m.id ? "selected" : undefined} className="cursor-pointer" onClick={() => onSelect?.({ kind: "meeting", id: m.id })}>
                     <TableCell className="whitespace-nowrap">{formatDateTime(m.start_time)}</TableCell>
                     <TableCell className="font-medium">{m.subject || "Untitled meeting"}</TableCell>
                     <TableCell className="max-w-64 truncate">{m.transcript_summary || "No summary yet"}</TableCell>

package/blocks/appointments/components/meetings-screen.tsx

@@ -0,0 +1,154 @@
+"use client";
+
+/**
+ * MeetingsScreen: the finished meetings product. Upcoming, past, cancelled and recorded meetings, a detail panel
+ * for the open one, and a "Schedule a meeting" flow. No props are required.
+ *
+ * It composes: MeetingList (views, search, paging), MeetingDetail (booking or recorded meeting) and BookingPage.
+ *
+ * Flows:
+ *   - Headline numbers: meetings coming up and bookings waiting for your approval.
+ *   - Open a booking (deep link ?sel=booking:<uid>, full page with &view=full) -> accept or decline a pending one, add an internal note,
+ *     cancel (all confirmed because they email attendees). Open a recorded meeting -> summary, topics, action
+ *     items and transcript.
+ *   - Schedule a meeting: pick an event type, a day and time, enter the attendee, confirm, and the invite is
+ *     emailed (external, confirmed inside BookingPage).
+ *   - Calendar connection and working hours live in SchedulingScreen; Google or Microsoft sign-in is only possible
+ *     in the graph8 app, so this screen links out instead of showing a dead button.
+ *
+ * SDK operations (through the composed parts): listBookings, getBooking, confirmBooking (external), cancelBooking
+ * (destructive), addBookingNote (external), listMeetings, getMeeting, listEventTypes, getEventType,
+ * getAvailableSlots, createBooking (external). Every confirmation uses ConfirmSpendDialog.
+ *
+ * Slots (all optional): renderDetailActions, extraDetailTabs, toolbarActions.
+ */
+import { useMemo, useState, type ReactNode } from "react";
+import { CalendarClock, CalendarPlus, ExternalLink } from "lucide-react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useEventTypes } from "../hooks/use-event-types";
+import { listOf, type Booking } from "../lib/appointments-types";
+import { BookingPage } from "./booking-page";
+import { MeetingDetail } from "./meeting-detail";
+import { MeetingList, type MeetingSelection } from "./meeting-list";
+
+export interface MeetingsScreenProps {
+  /** Where a person connects a calendar (graph8 app). */
+  connectCalendarUrl?: string;
+  /** Extra buttons in the detail header. */
+  renderDetailActions?: (selection: MeetingSelection) => ReactNode;
+  /** Extra tabs in the detail panel (for example the contact's CRM record). */
+  extraDetailTabs?: Array<{ id: string; label: string; render: (selection: MeetingSelection) => ReactNode }>;
+  /** Extra controls next to "Schedule a meeting". */
+  toolbarActions?: ReactNode;
+}
+
+const COUNT_CAP = 100;
+
+function parseSelection(raw: string | null | undefined): MeetingSelection | null {
+  const [kind, ...rest] = (raw ?? "").split(":");
+  const id = rest.join(":");
+  return id && (kind === "booking" || kind === "meeting") ? { kind, id } : null;
+}
+
+function useBookingCounts(refreshKey: number) {
+  const now = useMemo(() => new Date().toISOString(), []);
+  const q = useG8Query(async (signal) => {
+    const [upcoming, pending] = await Promise.all([
+      g8Get("/appointments/bookings", { after_start: now, take: COUNT_CAP, skip: 0 }, { signal }),
+      g8Get("/appointments/bookings", { status: "pending", take: COUNT_CAP, skip: 0 }, { signal }),
+    ]);
+    return { upcoming: listOf<Booking>(upcoming, "bookings"), pending: listOf<Booking>(pending, "bookings") };
+  }, [now, refreshKey]);
+  return q;
+}
+
+function countLabel(list: Booking[]): string {
+  return list.length >= COUNT_CAP ? `${COUNT_CAP}+` : String(list.length);
+}
+
+function ScheduleSheet({ open, onOpenChange, onBooked }: { open: boolean; onOpenChange: (open: boolean) => void; onBooked: () => void }) {
+  const types = useEventTypes();
+  const [chosen, setChosen] = useState<number | null>(null);
+  const eventTypeId = chosen ?? types.eventTypes.find((t) => !t.hidden)?.id ?? types.eventTypes[0]?.id ?? null;
+  return (
+    <FormSheet open={open} onOpenChange={onOpenChange} title="Schedule a meeting" description="Pick a time that works for the host, then enter who is joining.">
+      {types.error ? <ApiError error={types.error} title="Could not load event types" onRetry={() => void types.refetch()} /> : types.loading && !types.data ? <Skeleton className="h-32 w-full" aria-label="Loading event types" /> : eventTypeId == null ? (
+        <EmptyState icon={<CalendarClock className="size-8" />} title="No event types yet" description="Create an event type in Scheduling first, then book meetings with it here." />
+      ) : (
+        <div className="space-y-4">
+          <div className="space-y-1">
+            <label htmlFor="schedule-event-type" className="text-sm font-medium">Event type</label>
+            <select id="schedule-event-type" className="h-9 w-full rounded-md border bg-background px-2 text-sm" value={eventTypeId} onChange={(e) => setChosen(Number(e.target.value))}>
+              {types.eventTypes.map((t) => <option key={t.id} value={t.id}>{t.title} ({t.length} min)</option>)}
+            </select>
+          </div>
+          <BookingPage eventTypeId={eventTypeId} onBooked={onBooked} />
+        </div>
+      )}
+    </FormSheet>
+  );
+}
+
+export function MeetingsScreen({ connectCalendarUrl = "https://app.graph8.com", renderDetailActions, extraDetailTabs, toolbarActions }: MeetingsScreenProps) {
+  const [raw, setRaw] = useUrlState("sel");
+  const [mode, setMode] = useUrlState("view");
+  const selection = parseSelection(raw);
+  const [version, setVersion] = useState(0);
+  const [scheduling, setScheduling] = useState(false);
+  const counts = useBookingCounts(version);
+  const changed = () => setVersion((v) => v + 1);
+  const close = () => { setRaw(null); setMode(null); };
+
+  const stats = [
+    { label: "Upcoming", value: counts.data ? countLabel(counts.data.upcoming) : "-", hint: "Meetings starting from now" },
+    { label: "Awaiting approval", value: counts.data ? countLabel(counts.data.pending) : "-", tone: counts.data && counts.data.pending.length > 0 ? ("warning" as const) : undefined, hint: "Pending bookings you can accept or decline" },
+  ];
+
+  const detail = selection ? (
+    <DetailPanel
+      title={selection.kind === "booking" ? "Booking" : "Recorded meeting"}
+      actions={renderDetailActions?.(selection)}
+      onClose={close}
+      onExpand={mode === "full" ? undefined : () => setMode("full")}
+      onCollapse={mode === "full" ? () => setMode(null) : undefined}
+      tabs={[
+        { id: "overview", label: "Overview", content: <MeetingDetail selection={selection} onChanged={changed} /> },
+        ...(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(selection) })),
+      ]}
+    />
+  ) : null;
+
+  return (
+    <ScreenLayout
+      title="Meetings"
+      description="Everything booked and recorded, and the next meeting to prepare for."
+      icon={<CalendarClock className="size-5" />}
+      actions={<><Button onClick={() => setScheduling(true)}><CalendarPlus className="size-4" aria-hidden />Schedule a meeting</Button>{toolbarActions}</>}
+      stats={stats}
+    >
+      {counts.error ? <ApiError error={counts.error} title="Could not load meeting numbers" onRetry={() => void counts.refetch()} /> : null}
+      <SplitView
+        detailOpen={Boolean(selection)}
+        onCloseDetail={close}
+        expanded={mode === "full" && Boolean(selection)}
+        onExpandedChange={(full) => setMode(full ? "full" : null)}
+        detail={detail}
+        list={<MeetingList refreshKey={version} selectedId={selection?.id ?? null} onSelect={(s) => setRaw(`${s.kind}:${s.id}`)} />}
+      />
+      <SectionCard title="Calendar sync" description="Google and Microsoft sign-in happens in the graph8 app. Once connected, booked and recorded meetings appear here.">
+        <a className="inline-flex items-center gap-1 text-sm underline" href={connectCalendarUrl} target="_blank" rel="noreferrer">Connect a calendar in graph8<ExternalLink className="size-3.5" aria-hidden /></a>
+      </SectionCard>
+      <ScheduleSheet open={scheduling} onOpenChange={setScheduling} onBooked={changed} />
+    </ScreenLayout>
+  );
+}

package/blocks/appointments/components/scheduling-screen.tsx

@@ -0,0 +1,121 @@
+"use client";
+
+/**
+ * SchedulingScreen: the finished scheduling product. Your event types (meeting links), their settings, a live
+ * preview of each booking page, and your weekly working hours and calendar status. No props are required.
+ *
+ * It composes: EventTypeEditor (create, edit, delete), BookingPage (the preview), AvailabilityEditor (hours,
+ * date overrides, connected calendars) and the useEventTypes list.
+ *
+ * Flows:
+ *   - Event types tab (full page with &view=full): see every event type with its length and status, create one, open one (deep link
+ *     ?id=<event type id>) for Overview (every field), Bookings (who booked it, open one to accept, decline, note or
+ *     cancel), Settings (edit, delete confirmed) and its Booking page preview. Booking from the preview is a real booking and emails the attendee (confirmed).
+ *   - Working hours tab: edit the weekly hours and date overrides of a schedule. Connecting a Google or Microsoft
+ *     calendar is only possible in the graph8 app, so the editor links out.
+ *
+ * SDK operations (through the composed parts): listEventTypes, getEventType, createEventType, updateEventType,
+ * deleteEventType (destructive, confirmed), listSchedules, getAvailability, updateAvailability, listCalendars,
+ * getAvailableSlots, createBooking (external, confirmed).
+ *
+ * Slots (all optional): renderRowActions, renderDetailActions, extraDetailTabs, toolbarActions.
+ */
+import { useState, type ReactNode } from "react";
+import { CalendarClock, Plus } from "lucide-react";
+import { Button, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { useEventTypes } from "../hooks/use-event-types";
+import type { EventType } from "../lib/appointments-types";
+import { AvailabilityEditor } from "./availability-editor";
+import { BookingPage } from "./booking-page";
+import { EventTypeEditor } from "./event-type-editor";
+import { EventTypeBookings, EventTypeOverview } from "./event-type-related";
+
+export interface SchedulingScreenProps {
+  /** Where a person connects a calendar (graph8 app). */
+  connectCalendarUrl?: string;
+  renderRowActions?: (eventType: EventType) => ReactNode;
+  renderDetailActions?: (eventType: EventType) => ReactNode;
+  extraDetailTabs?: Array<{ id: string; label: string; render: (eventType: EventType) => ReactNode }>;
+  toolbarActions?: ReactNode;
+}
+
+const TABS = [{ id: "types", label: "Event types" }, { id: "hours", label: "Working hours" }];
+
+export function SchedulingScreen({ connectCalendarUrl, renderRowActions, renderDetailActions, extraDetailTabs, toolbarActions }: SchedulingScreenProps) {
+  const [tabParam, setTab] = useUrlState("tab", "types");
+  const [idParam, setId] = useUrlState("id");
+  const [mode, setMode] = useUrlState("view");
+  const [creating, setCreating] = useState(false);
+  const types = useEventTypes();
+  const tab = tabParam === "hours" ? "hours" : "types";
+  const selected = types.eventTypes.find((t) => String(t.id) === idParam);
+  const selectedId = idParam && /^\d+$/.test(idParam) ? Number(idParam) : null;
+  const close = () => { setId(null); setMode(null); };
+
+  const detail = selectedId != null ? (
+    <DetailPanel
+      title={selected?.title ?? "Event type"}
+      subtitle={selected ? `${selected.length} minutes` : undefined}
+      badges={selected?.hidden ? <StatusPill tone="neutral">Hidden</StatusPill> : undefined}
+      actions={selected ? renderDetailActions?.(selected) : undefined}
+      onClose={close}
+      onExpand={mode === "full" ? undefined : () => setMode("full")}
+      onCollapse={mode === "full" ? () => setMode(null) : undefined}
+      tabs={[
+        { id: "overview", label: "Overview", content: <EventTypeOverview key={selectedId} eventTypeId={selectedId} /> },
+        { id: "bookings", label: "Bookings", content: <EventTypeBookings key={selectedId} eventTypeId={selectedId} /> },
+        { id: "settings", label: "Settings", content: <EventTypeEditor key={selectedId} eventTypeId={selectedId} onSaved={() => void types.refetch()} onDeleted={() => { close(); void types.refetch(); }} /> },
+        { id: "preview", label: "Booking page", content: <BookingPage key={selectedId} eventTypeId={selectedId} /> },
+        ...(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: selected ? t.render(selected) : null })),
+      ]}
+    />
+  ) : null;
+
+  const list = types.error ? <ApiError error={types.error} title="Could not load event types" onRetry={() => void types.refetch()} /> : types.loading && !types.data ? (
+    <div className="space-y-2" aria-busy="true" aria-label="Loading event types">{[0, 1, 2].map((i) => <Skeleton key={i} className="h-10 w-full" />)}</div>
+  ) : types.eventTypes.length === 0 ? (
+    <EmptyState icon={<CalendarClock className="size-8" />} title="No event types yet" description="An event type is a meeting link, like a 30 minute intro call. Create one and share its booking page." action={<Button onClick={() => setCreating(true)}>New event type</Button>} />
+  ) : (
+    <Table>
+      <TableHeader><TableRow><TableHead>Event type</TableHead><TableHead className="text-right">Length</TableHead><TableHead>Rules</TableHead>{renderRowActions ? <TableHead /> : null}</TableRow></TableHeader>
+      <TableBody>
+        {types.eventTypes.map((t) => (
+          <TableRow key={t.id} className="cursor-pointer" data-state={String(t.id) === idParam ? "selected" : undefined} onClick={() => setId(String(t.id))}>
+            <TableCell><button type="button" className="font-medium hover:underline" onClick={(e) => { e.stopPropagation(); setId(String(t.id)); }}>{t.title}</button><div className="text-xs text-muted-foreground">/{t.slug}</div></TableCell>
+            <TableCell className="text-right tabular-nums">{t.length} min</TableCell>
+            <TableCell className="space-x-1">
+              {t.hidden ? <StatusPill tone="neutral">Hidden</StatusPill> : <StatusPill tone="positive" dot>Bookable</StatusPill>}
+              {t.requires_confirmation ? <StatusPill tone="info">Needs approval</StatusPill> : null}
+            </TableCell>
+            {renderRowActions ? <TableCell onClick={(e) => e.stopPropagation()}>{renderRowActions(t)}</TableCell> : null}
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+
+  return (
+    <ScreenLayout
+      title="Scheduling"
+      description="Meeting links people can book, and the hours you are available."
+      icon={<CalendarClock className="size-5" />}
+      actions={<>{toolbarActions}<Button onClick={() => setCreating(true)}><Plus className="size-4" aria-hidden />New event type</Button></>}
+      tabs={TABS.map((t) => (t.id === "types" ? { ...t, count: types.data ? types.eventTypes.length : undefined } : t))}
+      activeTab={tab}
+      onTabChange={(id) => { setTab(id); close(); }}
+    >
+      {tab === "hours" ? <AvailabilityEditor connectCalendarUrl={connectCalendarUrl} /> : <SplitView detailOpen={selectedId != null} onCloseDetail={close} expanded={mode === "full" && selectedId != null} onExpandedChange={(full) => setMode(full ? "full" : null)} detail={detail} list={list} />}
+      <FormSheet open={creating} onOpenChange={setCreating} title="New event type" description="Name it, set its length and pick the working hours it uses.">
+        {creating ? <EventTypeEditor onSaved={(et) => { setCreating(false); void types.refetch(); setTab("types"); setId(String(et.id)); }} /> : null}
+      </FormSheet>
+    </ScreenLayout>
+  );
+}

package/blocks/appointments/hooks/use-event-types.ts

@@ -0,0 +1,17 @@
+"use client";
+
+/**
+ * useEventTypes: the org's bookable event types (meeting links), newest data first.
+ *
+ * SDK operations: GET /event-types?include_hidden= (gtmLaunchHelpers.listEventTypes), read tier, scope campaigns:read.
+ * This is the list operation the editor and booking screens were missing: ids no longer have to be remembered.
+ * Hidden event types are included so a rep can still edit them.
+ */
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { listOf, type EventType } from "../lib/appointments-types";
+
+export function useEventTypes() {
+  const query = useG8Query(async (signal) => listOf<EventType>(await g8Get("/event-types", { include_hidden: true }, { signal }), "event_types", "items"), []);
+  return { ...query, eventTypes: query.data ?? [] };
+}

package/blocks/block.types.ts

@@ -94,6 +94,13 @@ export interface StackNavItem {
   component: string;
   /** JSON props passed to the component on its route (for a component that needs input to render anything). */
   props?: Record<string, unknown>;
+  /** lucide-react export name shown beside the label in the sidebar (for example `Users`). */
+  icon?: string;
+  /** Sidebar section label. */
+  group?: string;
+  description?: string;
+  /** Hand-written page template (`pages/*.tsx.tmpl`, relative to `stacks/<stack-id>/`) used instead of the generic route page. */
+  page?: string;
 }
 
 export interface StackManifest {
@@ -106,4 +113,6 @@ export interface StackManifest {
   /** Install order: each block's `dependsOn` come earlier. */
   blocks: string[];
   nav: StackNavItem[];
+  /** A nav path that `/` redirects to. */
+  home?: string;
 }