@graph8/sdk 0.308.1 → 0.357.0

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

@@ -0,0 +1,147 @@
+"use client";
+
+/**
+ * MeetingDetail: one booking (with confirm, cancel and internal notes) or one recorded meeting (summary,
+ * topics, action items, transcript).
+ *
+ * SDK operations, in order:
+ *   booking:  GET  /appointments/bookings/{uid}                 (appointments.getBooking)     read
+ *             POST /appointments/bookings/{uid}/confirm         (appointments.confirmBooking) EXTERNAL -> ConfirmSpendDialog (accept or decline a pending booking)
+ *             POST /appointments/bookings/{uid}/cancel          (appointments.cancelBooking)  DESTRUCTIVE -> ConfirmSpendDialog (emails the attendees)
+ *             POST /appointments/bookings/{uid}/notes           (appointments.addBookingNote) EXTERNAL -> ConfirmSpendDialog
+ *   recorded: GET  /inbox/meetings/{meeting_id}                 (meetings.getMeeting)         read
+ * Pass the selection MeetingList gives you: { kind, id }.
+ */
+import { useState, type ReactNode } from "react";
+import { Button, Skeleton, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { formatDateTime, unwrap, type Booking, type RecordedMeeting } from "../lib/appointments-types";
+import type { MeetingSelection } from "./meeting-list";
+
+export interface MeetingDetailProps {
+  selection: MeetingSelection;
+  /** Called after a confirm, cancel or note so the list can refresh. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+type Pending = { kind: "confirm"; accept: boolean } | { kind: "cancel" } | { kind: "note" } | null;
+
+function Field({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <div>
+      <dt className="text-xs uppercase text-muted-foreground">{label}</dt>
+      <dd className="text-sm">{children}</dd>
+    </div>
+  );
+}
+
+function RecordedDetail({ id, className }: { id: string; className?: string }) {
+  const q = useG8Query(async (signal) => unwrap<RecordedMeeting>(await g8Get(`/inbox/meetings/${encodeURIComponent(id)}`, undefined, { signal })), [id]);
+  if (q.error) return <ApiError error={q.error} title="Could not load the meeting" onRetry={() => void q.refetch()} />;
+  if (!q.data) return <Skeleton className="h-40 w-full" aria-label="Loading meeting" />;
+  const m = q.data;
+  return (
+    <section className={`space-y-3 ${className ?? ""}`}>
+      <h2 className="text-base font-semibold">{m.subject || "Untitled meeting"}</h2>
+      <dl className="grid gap-3 sm:grid-cols-2">
+        <Field label="When">{formatDateTime(m.start_time)}</Field>
+        <Field label="Attendees">{(m.attendees ?? []).map((a) => a.name || a.email).join(", ") || "Unknown"}</Field>
+      </dl>
+      {m.transcript_summary ? <p className="whitespace-pre-wrap text-sm">{m.transcript_summary}</p> : <p className="text-sm text-muted-foreground">No summary yet ({m.transcript_status ?? "no transcript"}).</p>}
+      {m.key_topics?.length ? <p className="text-sm">Topics: {m.key_topics.join(", ")}</p> : null}
+      {m.action_items?.length ? (
+        <ul className="list-disc pl-5 text-sm">
+          {m.action_items.map((a, i) => (
+            <li key={i}>{String(a.text ?? a.title ?? a.description ?? JSON.stringify(a))}</li>
+          ))}
+        </ul>
+      ) : null}
+      {m.transcript_text ? (
+        <details className="text-sm">
+          <summary className="cursor-pointer font-medium">Transcript</summary>
+          <p className="mt-2 whitespace-pre-wrap">{m.transcript_text}</p>
+        </details>
+      ) : null}
+    </section>
+  );
+}
+
+function BookingDetail({ uid, onChanged, className }: { uid: string; onChanged?: () => void; className?: string }) {
+  const q = useG8Query(async (signal) => unwrap<Booking>(await g8Get(`/appointments/bookings/${encodeURIComponent(uid)}`, undefined, { signal })), [uid]);
+  const [pending, setPending] = useState<Pending>(null);
+  // Each action has its own input: a note is never sent as a cancellation reason, or the reverse.
+  const [note, setNote] = useState("");
+  const [cancelReason, setCancelReason] = useState("");
+  const [declineReason, setDeclineReason] = useState("");
+  const base = `/appointments/bookings/${encodeURIComponent(uid)}`;
+  const done = () => { setPending(null); void q.refetch(); onChanged?.(); };
+
+  const confirmBooking = useG8Mutation((accept: boolean) => g8Post(`${base}/confirm`, { confirmed: accept, reason: accept ? undefined : declineReason || undefined }), { onSuccess: done, onError: () => setPending(null) });
+  const cancel = useG8Mutation(() => g8Post(`${base}/cancel`, { cancellation_reason: cancelReason || undefined }), { onSuccess: done, onError: () => setPending(null) });
+  const addNote = useG8Mutation(() => g8Post(`${base}/notes`, { text: note }), { onSuccess: () => { setNote(""); done(); }, onError: () => setPending(null) });
+
+  if (q.error) return <ApiError error={q.error} title="Could not load the booking" onRetry={() => void q.refetch()} />;
+  if (!q.data) return <Skeleton className="h-40 w-full" aria-label="Loading booking" />;
+  const b = q.data;
+  const active = b.status !== "cancelled" && b.status !== "rejected";
+  const failure = confirmBooking.error ?? cancel.error ?? addNote.error;
+
+  return (
+    <section className={`space-y-4 ${className ?? ""}`}>
+      <h2 className="text-base font-semibold">{b.title || b.event_type_title || "Meeting"}</h2>
+      <dl className="grid gap-3 sm:grid-cols-2">
+        <Field label="When">{formatDateTime(b.start_time)}</Field>
+        <Field label="Status"><span className="capitalize">{b.status}</span></Field>
+        <Field label="Host">{b.host_name || b.host_email || "Unassigned"}</Field>
+        <Field label="Attendees">{b.attendees.map((a) => `${a.name ?? ""} <${a.email}>`).join(", ") || "None"}</Field>
+        {b.meeting_url ? <Field label="Link"><a className="underline" href={b.meeting_url} target="_blank" rel="noreferrer">{b.meeting_url}</a></Field> : null}
+        {b.sequence_name ? <Field label="From sequence">{b.sequence_name}</Field> : null}
+        {b.cancellation_reason ? <Field label="Cancelled because">{b.cancellation_reason}</Field> : null}
+      </dl>
+
+      {(b.internal_notes ?? []).length > 0 ? (
+        <ul className="space-y-1 text-sm" aria-label="Notes">
+          {(b.internal_notes ?? []).map((n, i) => (
+            <li key={n.id ?? i} className="rounded border p-2">{n.text}</li>
+          ))}
+        </ul>
+      ) : null}
+      {failure ? <ApiError error={failure} title="That action failed" /> : null}
+
+      {active ? (
+        <div className="space-y-2">
+          <Textarea aria-label="Note" rows={2} placeholder="Internal note" value={note} onChange={(e) => setNote(e.target.value)} />
+          <div className="flex flex-wrap gap-2">
+            {b.status === "pending" ? (
+              <>
+                <Button size="sm" onClick={() => setPending({ kind: "confirm", accept: true })}>Accept</Button>
+                <Button size="sm" variant="outline" onClick={() => setPending({ kind: "confirm", accept: false })}>Decline</Button>
+              </>
+            ) : null}
+            <Button size="sm" variant="outline" disabled={!note.trim()} onClick={() => setPending({ kind: "note" })}>Add note</Button>
+            <Button size="sm" variant="destructive" onClick={() => setPending({ kind: "cancel" })}>Cancel booking</Button>
+          </div>
+        </div>
+      ) : null}
+
+      <ConfirmSpendDialog open={pending?.kind === "confirm"} tier="external" title={pending?.kind === "confirm" && pending.accept ? "Accept this booking?" : "Decline this booking?"} description={pending?.kind === "confirm" && !pending.accept ? (<><p>The attendee is emailed the outcome.</p><Textarea aria-label="Decline reason" rows={2} placeholder="Reason (optional)" value={declineReason} onChange={(e) => setDeclineReason(e.target.value)} /></>) : "The attendee is emailed the outcome."} recipients={b.attendees.length || 1} confirming={confirmBooking.loading} onConfirm={() => pending?.kind === "confirm" && void confirmBooking.mutate(pending.accept)} onCancel={() => setPending(null)} />
+      <ConfirmSpendDialog open={pending?.kind === "cancel"} tier="destructive" title="Cancel this booking?" description={(<><p>The calendar event is removed and every attendee is emailed.</p><Textarea aria-label="Cancellation reason" rows={2} placeholder="Reason (optional)" value={cancelReason} onChange={(e) => setCancelReason(e.target.value)} /></>)} confirmLabel="Cancel booking" affected={1} confirming={cancel.loading} onConfirm={() => void cancel.mutate(undefined)} onCancel={() => setPending(null)} />
+      <ConfirmSpendDialog open={pending?.kind === "note"} tier="external" title="Add this note?" description="Notes can be shared with the attendees through booking workflows." confirmLabel="Add note" confirming={addNote.loading} onConfirm={() => void addNote.mutate(undefined)} onCancel={() => setPending(null)} />
+    </section>
+  );
+}
+
+export function MeetingDetail({ selection, onChanged, className }: MeetingDetailProps) {
+  if (!selection.id) return <EmptyState title="Select a meeting" description="Pick one from the list to see its details." />;
+  return selection.kind === "booking" ? (
+    <BookingDetail key={selection.id} uid={selection.id} onChanged={onChanged} className={className} />
+  ) : (
+    <RecordedDetail key={selection.id} id={selection.id} className={className} />
+  );
+}

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

@@ -0,0 +1,148 @@
+"use client";
+
+/**
+ * MeetingList: booked meetings (Upcoming, Past, Cancelled) and recorded meetings with transcripts.
+ *
+ * SDK operations, in order (one per view):
+ *   Upcoming / Past / Cancelled: GET /appointments/bookings?after_start=|before_end=|status=&skip=&take=
+ *                                (appointments.listBookings)  read
+ *   Recorded:                    GET /inbox/meetings?search=&page=&page_size=   (meetings.listMeetings)   read
+ * Read-only: opening a row is MeetingDetail's job (cancel and notes live there, behind confirm dialogs).
+ *
+ * A booking is something scheduled through an event type; a recorded meeting is a call that was captured
+ * (calendar sync or bot) and may have a transcript and summary. They are different records with different ids.
+ */
+import { useEffect, useMemo, useState } from "react";
+import { Button, Input, 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 { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { formatDateTime, listOf, type Booking, type RecordedMeeting } from "../lib/appointments-types";
+
+export type MeetingView = "upcoming" | "past" | "cancelled" | "recorded";
+export type MeetingSelection = { kind: "booking"; id: string } | { kind: "meeting"; id: string };
+
+export interface MeetingListProps {
+  onSelect?: (selection: MeetingSelection) => void;
+  initialView?: MeetingView;
+  pageSize?: number;
+  className?: string;
+}
+
+const VIEWS: ReadonlyArray<{ value: MeetingView; label: string }> = [
+  { value: "upcoming", label: "Upcoming" },
+  { value: "past", label: "Past" },
+  { value: "cancelled", label: "Cancelled" },
+  { value: "recorded", label: "Recorded" },
+];
+
+function bookingQuery(view: Exclude<MeetingView, "recorded">, now: string, page: number, take: number) {
+  const base = { skip: page * take, take };
+  if (view === "upcoming") return { ...base, after_start: now, sort_by: "start_time", sort_order: "asc" };
+  if (view === "past") return { ...base, before_end: now, sort_by: "start_time", sort_order: "desc" };
+  return { ...base, status: "cancelled", sort_by: "start_time", sort_order: "desc" };
+}
+
+function attendeeNames(b: Booking): string {
+  return b.attendees.map((a) => a.name || a.email).join(", ") || "No attendees";
+}
+
+function useDebouncedText(value: string, ms = 300): string {
+  const [v, setV] = useState(value);
+  useEffect(() => { const t = setTimeout(() => setV(value.trim()), ms); return () => clearTimeout(t); }, [value, ms]);
+  return v;
+}
+
+export function MeetingList({ onSelect, initialView = "upcoming", pageSize = 20, className }: MeetingListProps) {
+  const [view, setView] = useState<MeetingView>(initialView);
+  const [page, setPage] = useState(0);
+  const [search, setSearch] = useState("");
+  const query = useDebouncedText(search);
+  const now = useMemo(() => new Date().toISOString(), [view]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const rows = useG8Query(
+    async (signal) => {
+      if (view === "recorded") {
+        const env = await g8Get("/inbox/meetings", { search: query || undefined, page: page + 1, page_size: pageSize }, { signal });
+        return { kind: "meeting" as const, items: listOf<RecordedMeeting>(env), more: Boolean((env as { pagination?: { has_next?: boolean } }).pagination?.has_next) };
+      }
+      const env = await g8Get("/appointments/bookings", bookingQuery(view, now, page, pageSize), { signal });
+      const items = listOf<Booking>(env, "bookings");
+      return { kind: "booking" as const, items, more: items.length === pageSize };
+    },
+    [view, page, query, pageSize, now],
+  );
+
+  const switchView = (next: MeetingView) => {
+    setView(next);
+    setPage(0);
+  };
+  const result = rows.data;
+
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <div role="group" aria-label="View" className="flex gap-1">
+          {VIEWS.map((v) => (
+            <Button key={v.value} size="sm" variant={view === v.value ? "default" : "outline"} onClick={() => switchView(v.value)}>
+              {v.label}
+            </Button>
+          ))}
+        </div>
+        {view === "recorded" ? <Input aria-label="Search meetings" className="w-56" placeholder="Search recorded meetings" value={search} onChange={(e) => { setSearch(e.target.value); setPage(0); }} /> : null}
+      </div>
+
+      {rows.error ? (
+        <ApiError error={rows.error} title="Could not load meetings" onRetry={() => void rows.refetch()} />
+      ) : rows.loading && !result ? (
+        <div className="space-y-2" aria-busy="true" aria-label="Loading meetings">
+          {Array.from({ length: 5 }, (_, i) => (
+            <Skeleton key={i} className="h-10 w-full" />
+          ))}
+        </div>
+      ) : !result || result.items.length === 0 ? (
+        <EmptyState title={`No ${view} meetings`} description={view === "recorded" ? "Meetings appear once a connected calendar or recorder captures them." : "Bookings made through your event types show up here."} />
+      ) : (
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>When</TableHead>
+              <TableHead>{result.kind === "booking" ? "Meeting" : "Subject"}</TableHead>
+              <TableHead>{result.kind === "booking" ? "Attendees" : "Transcript"}</TableHead>
+              <TableHead>Status</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {result.kind === "booking"
+              ? (result.items as Booking[]).map((b) => (
+                  <TableRow key={b.uid} 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>
+                    <TableCell className="capitalize">{b.status}</TableCell>
+                  </TableRow>
+                ))
+              : (result.items as RecordedMeeting[]).map((m) => (
+                  <TableRow key={m.id} 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>
+                    <TableCell className="capitalize">{m.transcript_status ?? "none"}</TableCell>
+                  </TableRow>
+                ))}
+          </TableBody>
+        </Table>
+      )}
+
+      <div className="flex justify-end gap-2">
+        <Button size="sm" variant="outline" disabled={page === 0 || rows.loading} onClick={() => setPage((p) => p - 1)}>
+          Previous
+        </Button>
+        <Button size="sm" variant="outline" disabled={!result?.more || rows.loading} onClick={() => setPage((p) => p + 1)}>
+          Next
+        </Button>
+      </div>
+    </div>
+  );
+}

package/blocks/appointments/hooks/use-available-slots.ts

@@ -0,0 +1,29 @@
+"use client";
+
+/**
+ * useAvailableSlots: bookable times for an event type, grouped by local date.
+ *
+ * SDK operations: GET /appointments/slots?event_type_id=&start=&end=&time_zone= (appointments.getAvailableSlots), read.
+ *
+ * The window may be at most 60 days. The response is `{ slots: { "YYYY-MM-DD": [{ time, duration }] } }`
+ * keyed by date in the requested time zone; past times are never returned.
+ */
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { unwrap, type Slot } from "../lib/appointments-types";
+
+export function useAvailableSlots(eventTypeId: number | null | undefined, start: string, end: string, timeZone: string) {
+  const query = useG8Query(
+    async (signal) => {
+      const env = await g8Get(
+        "/appointments/slots",
+        { event_type_id: eventTypeId as number, start, end, time_zone: timeZone },
+        { signal },
+      );
+      return (unwrap<{ slots?: Record<string, Slot[]> }>(env).slots ?? {}) as Record<string, Slot[]>;
+    },
+    [eventTypeId, start, end, timeZone],
+    { enabled: eventTypeId != null },
+  );
+  return { ...query, slotsByDate: query.data ?? {} };
+}

package/blocks/appointments/hooks/use-schedules.ts

@@ -0,0 +1,18 @@
+"use client";
+
+/**
+ * useSchedules: the org's availability schedules (working hours), default first.
+ *
+ * SDK operations: GET /appointments/schedules (appointments.listSchedules), read tier.
+ */
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { listOf, type Schedule } from "../lib/appointments-types";
+
+export function useSchedules() {
+  const query = useG8Query(async (signal) => {
+    const env = await g8Get("/appointments/schedules", undefined, { signal });
+    return listOf<Schedule>(env, "schedules", "items").sort((a, b) => Number(b.is_default) - Number(a.is_default));
+  }, []);
+  return { ...query, schedules: query.data ?? [] };
+}

package/blocks/appointments/lib/appointments-types.ts

@@ -0,0 +1,159 @@
+"use client";
+
+/**
+ * Shapes and helpers shared by the appointments components.
+ *
+ * The appointments endpoints are a thin pass-through of the scheduling engine: several of them return the
+ * object itself (`{ id, title, ... }`) rather than the `{ data }` envelope the rest of the API uses. Always read
+ * responses through `unwrap()` and lists through `listOf()` so both shapes work.
+ */
+
+export interface EventType {
+  id: number;
+  title: string;
+  slug: string;
+  length: number;
+  description?: string | null;
+  hidden?: boolean;
+  requires_confirmation?: boolean;
+  minimum_booking_notice?: number;
+  schedule?: { id: number; name: string } | null;
+  scheduling_type?: string | null;
+}
+
+export interface TimeWindow {
+  start: string;
+  end: string;
+}
+
+/** Availability rule as the API stores it: ISO weekdays (1 = Monday ... 7 = Sunday) and "HH:MM" clock times. */
+export interface AvailabilityRule {
+  id?: number;
+  days?: number[] | null;
+  start_time?: string | null;
+  end_time?: string | null;
+  /** Present on date overrides ("YYYY-MM-DD"). */
+  date?: string | null;
+}
+
+export interface Schedule {
+  id: number;
+  name: string;
+  time_zone?: string | null;
+  is_default?: boolean;
+  availability?: AvailabilityRule[];
+  overrides?: AvailabilityRule[];
+}
+
+export interface Attendee {
+  id?: number;
+  email: string;
+  name?: string | null;
+  time_zone?: string | null;
+  no_show?: boolean;
+}
+
+export interface Booking {
+  id?: number;
+  uid: string;
+  title?: string | null;
+  start_time?: string | null;
+  end_time?: string | null;
+  status: string;
+  location?: string | null;
+  meeting_url?: string | null;
+  event_type_title?: string | null;
+  host_name?: string | null;
+  host_email?: string | null;
+  attendees: Attendee[];
+  sequence_name?: string | null;
+  description?: string | null;
+  cancellation_reason?: string | null;
+  internal_notes?: Array<{ id?: number; text?: string | null; created_at?: string | null }>;
+}
+
+export interface Slot {
+  time: string;
+  duration: number;
+  attendees_remaining?: number | null;
+}
+
+/** The recorded-meeting summary row from `GET /inbox/meetings`. */
+export interface RecordedMeeting {
+  id: string;
+  subject?: string | null;
+  start_time?: string | null;
+  end_time?: string | null;
+  organizer_email?: string | null;
+  meeting_url?: string | null;
+  attendees?: Array<{ email?: string | null; name?: string | null }>;
+  transcript_status?: string | null;
+  transcript_summary?: string | null;
+  key_topics?: string[] | null;
+  action_items?: Array<Record<string, unknown>> | null;
+  transcript_text?: string | null;
+}
+
+export const WEEKDAYS: ReadonlyArray<{ day: number; label: string }> = [
+  { day: 1, label: "Monday" },
+  { day: 2, label: "Tuesday" },
+  { day: 3, label: "Wednesday" },
+  { day: 4, label: "Thursday" },
+  { day: 5, label: "Friday" },
+  { day: 6, label: "Saturday" },
+  { day: 7, label: "Sunday" },
+];
+
+/** The object inside `{ data }`, or the response itself when the endpoint returns the object directly. */
+export function unwrap<T>(env: unknown): T {
+  const e = env as { data?: unknown } | null;
+  return (e && typeof e === "object" && "data" in e && e.data !== undefined && e.data !== null ? e.data : env) as T;
+}
+
+/** An array from a bare array, `{ data: [...] }`, or `{ <key>: [...] }` under any of the given keys. */
+export function listOf<T>(env: unknown, ...keys: string[]): T[] {
+  const inner = unwrap<unknown>(env);
+  if (Array.isArray(inner)) return inner as T[];
+  for (const key of keys) {
+    const v = (inner as Record<string, unknown> | null)?.[key];
+    if (Array.isArray(v)) return v as T[];
+  }
+  return [];
+}
+
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+}
+
+/** "09:00:00" and "9:00" both become "09:00" (the API accepts only HH:MM). */
+export function toHHMM(value: string | null | undefined, fallback = "09:00"): string {
+  const m = /^(\d{1,2}):(\d{2})/.exec(value ?? "");
+  return m ? `${m[1].padStart(2, "0")}:${m[2]}` : fallback;
+}
+
+export function formatDateTime(iso: string | null | undefined, timeZone?: string): string {
+  if (!iso) return "";
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return "";
+  return d.toLocaleString(undefined, { weekday: "short", month: "short", day: "numeric", hour: "numeric", minute: "2-digit", timeZone });
+}
+
+export function formatTime(iso: string, timeZone?: string): string {
+  return new Date(iso).toLocaleTimeString(undefined, { hour: "numeric", minute: "2-digit", timeZone });
+}
+
+export function localTimeZone(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+
+export function addMinutes(iso: string, minutes: number): string {
+  return new Date(new Date(iso).getTime() + minutes * 60_000).toISOString();
+}

package/blocks/appointments/lib/idempotency.ts

@@ -0,0 +1,30 @@
+"use client";
+
+/**
+ * useIdempotencyKey: one Idempotency-Key per distinct payload.
+ *
+ * The API remembers a key together with a fingerprint of the request body. Replaying the SAME body under the same
+ * key is a safe retry (a double click, a timeout). Reusing the key with a DIFFERENT body is a 409 for as long as
+ * the server holds it, and after a 5xx on a send/booking it holds the failure under the key for minutes. So the
+ * key must follow the payload: pass a string that changes whenever anything in the request body changes.
+ *
+ *   const key = useIdempotencyKey(JSON.stringify([thread.id, body, to, subject]));
+ *   g8Post(path, payload, { idempotencyKey: key.get() });
+ *   // after a success: key.rotate()
+ */
+import { useRef } from "react";
+
+export function useIdempotencyKey(fingerprint: string) {
+  const ref = useRef({ fingerprint, key: crypto.randomUUID() });
+  return {
+    /** The key for the current payload; a new one as soon as the payload differs from the last call's. */
+    get(): string {
+      if (ref.current.fingerprint !== fingerprint) ref.current = { fingerprint, key: crypto.randomUUID() };
+      return ref.current.key;
+    },
+    /** Start a new logical request (call after a success so the next identical payload is a new action). */
+    rotate(): void {
+      ref.current = { fingerprint, key: crypto.randomUUID() };
+    },
+  };
+}

package/blocks/appointments/recipes/01-create-event-type-and-hours.ts

@@ -0,0 +1,27 @@
+/**
+ * @title Create a working-hours schedule and a bookable event type
+ * @when Setting up scheduling for an org or a new rep. Both writes are low-risk (tier `write`). Days are ISO
+ * weekdays (1 = Monday ... 7 = Sunday) and times are "HH:MM". The calendar that blocks busy time must be
+ * connected by a human in the graph8 app first (OAuth is not in the API).
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+// 1. Working hours: Monday to Friday, 09:00 to 17:00.
+const schedule = (await g8.api.appointments.createSchedule({
+  body: {
+    name: "Sales hours",
+    time_zone: "America/New_York",
+    is_default: true,
+    availability: [{ days: [1, 2, 3, 4, 5], start_time: "09:00", end_time: "17:00" }],
+  },
+})) as { id?: number; data?: { id?: number } };
+const scheduleId = schedule.id ?? schedule.data?.id;
+if (!scheduleId) throw new Error("graph8 returned no schedule id");
+
+// 2. A 30 minute meeting that uses those hours. Keep the returned id: there is no list-event-types call.
+const eventType = (await g8.api.appointments.createEventType({
+  body: { title: "Intro call", slug: "intro-call", length: 30, schedule_id: scheduleId, minimum_booking_notice: 120 },
+})) as { id?: number; data?: { id?: number } };
+console.log("event type id", eventType.id ?? eventType.data?.id);

package/blocks/appointments/recipes/02-find-slots-and-book.ts

@@ -0,0 +1,34 @@
+/**
+ * @title Find open times and book a meeting for a prospect
+ * @when An agent scheduling on behalf of a rep. Booking is tier `external`: it creates a calendar event and
+ * emails the attendee, so ask a human to approve the time and the attendee first. Slots come back grouped by
+ * date in the requested time zone, never in the past, and at most 60 days ahead.
+ */
+import { randomUUID } from "node:crypto";
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const eventTypeId = Number(process.argv[2]);
+const start = new Date();
+const end = new Date(start.getTime() + 14 * 86_400_000);
+
+const res = (await g8.api.appointments.getAvailableSlots({
+  query: { event_type_id: eventTypeId, start: start.toISOString(), end: end.toISOString(), time_zone: "America/New_York" },
+})) as { data?: { slots?: Record<string, Array<{ time: string; duration: number }>> } };
+const byDate = res.data?.slots ?? {};
+const firstDate = Object.keys(byDate).sort()[0];
+const slot = firstDate ? byDate[firstDate][0] : undefined;
+if (!slot) throw new Error("No open times in the next 14 days");
+
+const booking = await g8.api.appointments.createBooking(
+  {
+    body: {
+      event_type_id: eventTypeId,
+      start_time: slot.time,
+      attendees: [{ name: "Ada Lovelace", email: "ada@example.com", time_zone: "America/New_York" }],
+    },
+  },
+  { idempotencyKey: randomUUID() },
+);
+console.log(booking);

package/blocks/appointments/recipes/03-bookings-digest.ts

@@ -0,0 +1,22 @@
+/**
+ * @title Upcoming bookings and pending approvals
+ * @when A daily digest for a rep or manager. Read-only. `listBookings` pages with `skip` and `take` (not a
+ * cursor); the body is `{ bookings: [...], total_count }`.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const now = new Date().toISOString();
+const upcoming = (await g8.api.appointments.listBookings({
+  query: { after_start: now, sort_by: "start_time", sort_order: "asc", skip: 0, take: 50 },
+})) as { bookings?: Array<{ uid: string; title?: string | null; start_time?: string | null; status: string }> };
+
+const bookings = upcoming.bookings ?? [];
+const pending = bookings.filter((b) => b.status === "pending");
+console.log(`${bookings.length} upcoming, ${pending.length} waiting for the host to confirm`);
+for (const b of bookings) console.log(b.start_time, b.title ?? "Meeting", b.status);
+
+// Recorded meetings (calendar-synced or bot-captured calls) are a different record with transcripts.
+const recorded = await g8.api.meetings.listMeetings({ query: { page: 1, page_size: 10 } });
+console.log(`${recorded.data.length} recent recorded meetings`);

package/blocks/appointments/recipes/04-calendar-invite.ts

@@ -0,0 +1,21 @@
+/**
+ * @title Create a calendar invite for an ad-hoc meeting
+ * @when You need a shareable invite (title, start, duration, link) without an event type or a booking, for
+ * example to attach to an email an agent is drafting. Tier `write`: it creates the invite record; it does not
+ * email anyone. `tz` is an IANA zone.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const invite = await g8.api.calendarInvites.createCalendarInvite({
+  body: {
+    title: "Kickoff with Acme",
+    start_at: "2026-11-02T15:00:00Z",
+    tz: "America/New_York",
+    duration_minutes: 45,
+    meeting_link: "https://meet.example.com/acme-kickoff",
+    description: "Agenda: goals, timeline, owners.",
+  },
+});
+console.log(invite.data);