@graph8/sdk 0.362.0 → 0.373.0

package/blocks/analytics/components/report-detail.tsx

@@ -0,0 +1,84 @@
+"use client";
+
+/**
+ * ReportDetail: everything about one saved custom-object report: its definition (object, measure, grouping, filters,
+ * chart type, visibility, revision, owner dates), the latest result table, and the actions Run again and Delete.
+ *
+ * SDK operations, in order:
+ *   1. GET    /reports/{id}          (reports.getObjectReportApi)       read    the definition
+ *   2. POST   /reports/{id}/execute  (reports.executeObjectReportApi)   write   run it (creates a run record, sends nothing); runs once on open
+ *   3. DELETE /reports/{id}          (reports.archiveObjectReportApi)   DESTRUCTIVE -> ConfirmSpendDialog
+ * Editing happens in ReportBuilder (`reportId`). Preview and execute share the org's report-run slots (429 `too_many_report_runs`).
+ */
+import { useEffect, useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Post } from "@/g8/lib/g8-client";
+import { reportBody, type ReportResultData, type SavedReport } from "../lib/analytics-types";
+import { ResultTable } from "./report-builder";
+
+export interface ReportDetailProps {
+  reportId: string;
+  /** Called after the report was deleted. */
+  onDeleted?: () => void;
+  /** A result the host already holds (kept across tab switches). While set, opening does not run the report again. */
+  result?: ReportResultData | null;
+  /** Called with every fresh result, so the host can keep it. */
+  onResult?: (result: ReportResultData | null) => void;
+  className?: string;
+}
+
+type Cfg = { measures?: Array<Record<string, unknown>>; group_by?: Array<Record<string, unknown>>; filters?: unknown[] };
+
+const measureText = (m: Record<string, unknown> | undefined): string => (m ? `${String(m.kind)}${m.attribute_slug ? ` of ${String(m.attribute_slug)}` : ""}` : "");
+const groupText = (g: Record<string, unknown> | undefined): string => (g ? (g.kind === "created_at" ? `created date by ${String(g.grain ?? "month")}` : String(g.attribute_slug ?? "")) : "None");
+
+export function ReportDetail({ reportId, onDeleted, result: given, onResult, className }: ReportDetailProps) {
+  const [confirming, setConfirming] = useState(false);
+  const [own, setOwn] = useState<ReportResultData | null>(null);
+  const result = given ?? own;
+  const setResult = (r: ReportResultData | null) => { setOwn(r); onResult?.(r); };
+  const report = useG8Query(async (signal) => reportBody<SavedReport>(await g8Get(`/reports/${encodeURIComponent(reportId)}`, undefined, { signal })), [reportId]);
+  const run = useG8Mutation(async () => { const out = reportBody<ReportResultData>(await g8Post(`/reports/${encodeURIComponent(reportId)}/execute`, {})); setResult(out); return out; });
+  const remove = useG8Mutation(async () => { await g8Delete(`/reports/${encodeURIComponent(reportId)}`); }, { onSuccess: () => { setConfirming(false); onDeleted?.(); }, onError: () => setConfirming(false) });
+
+  // A different report starts clean; it runs once on open unless the host already holds a result.
+  useEffect(() => { run.reset(); if (!given) void run.mutate(undefined); }, [reportId]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const r = report.data;
+  const cfg = (r?.config ?? {}) as Cfg;
+  if (report.error) return <ApiError error={report.error} title="Could not load the report" onRetry={() => void report.refetch()} />;
+  if (!r) return <Skeleton className="h-40 w-full" aria-label="Loading report" />;
+
+  return (
+    <div className={`space-y-4 ${className ?? ""}`} data-testid="report-detail">
+      <div className="flex flex-wrap items-center gap-2">
+        <StatusPill tone={r.visibility === "private" ? "neutral" : "info"}>{r.visibility}</StatusPill>
+        <span className="text-xs text-muted-foreground">Revision {r.revision}</span>
+        <div className="ml-auto flex gap-2">
+          <Button size="sm" variant="outline" loading={run.loading} onClick={() => void run.mutate(undefined)}>Run again</Button>
+          {r.can_delete ? <Button size="sm" variant="ghost" onClick={() => setConfirming(true)}>Delete</Button> : null}
+        </div>
+      </div>
+      <KeyValueList columns={2} items={[
+        { label: "Object", value: r.source.plural_noun, mono: false },
+        { label: "Object slug", value: r.source.slug, mono: true },
+        { label: "Chart", value: r.chart_type },
+        { label: "Measure", value: (cfg.measures ?? []).map(measureText).join(", ") || "count" },
+        { label: "Grouped by", value: (cfg.group_by ?? []).map(groupText).join(", ") || "None" },
+        { label: "Filters", value: (cfg.filters ?? []).length ? `${(cfg.filters ?? []).length} applied` : "None" },
+      ]} />
+      {run.error ? <ApiError error={run.error} title="Could not run the report" onRetry={() => void run.mutate(undefined)} /> : null}
+      {run.loading && !result ? <Skeleton className="h-24 w-full" aria-label="Running report" /> : null}
+      {result ? <ResultTable result={result} /> : null}
+      {remove.error ? <ApiError error={remove.error} title="Could not delete the report" /> : null}
+      <ConfirmSpendDialog open={confirming} tier="destructive" title={`Delete "${r.title}"?`} description="The saved report is removed for everyone who can see it. The underlying records are not touched."
+        confirmLabel="Delete report" affected={1} confirming={remove.loading} onConfirm={() => void remove.mutate(undefined)} onCancel={() => setConfirming(false)} />
+    </div>
+  );
+}

package/blocks/analytics/components/trend-chart.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+/**
+ * TrendChart: a daily line chart for one outbound channel (email, calls or meetings), drawn with the kit TimeSeriesChart (recharts).
+ *
+ * SDK operations (pick the channel):
+ *   channel "email":    GET /analytics/outbound/email-metrics/trend?days=    (analytics.getEmailTrend)    read   rows { date, sent, replied, ... }
+ *   channel "calls":    GET /analytics/outbound/call-metrics/trend?days=     (analytics.getCallTrend)     read   rows { date, dials, connected, ... }
+ *   channel "meetings": GET /analytics/outbound/meeting-metrics/trend?days=  (analytics.getMeetingTrend)  read   rows { date, booked, cancelled, held, ... }
+ * Two series per channel (the volume and the outcome). Dates are plain `YYYY-MM-DD` days and are shown as UTC days.
+ */
+import { Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { TimeSeriesChart } from "@/g8/components/screen/time-series-chart";
+import { useReport } from "../hooks/use-report";
+import { formatNumber } from "../lib/analytics-types";
+
+export type TrendChannel = "email" | "calls" | "meetings";
+
+export const TREND_SERIES: Record<TrendChannel, { path: string; keys: [string, string]; labels: [string, string] }> = {
+  email: { path: "/analytics/outbound/email-metrics/trend", keys: ["sent", "replied"], labels: ["Sent", "Replied"] },
+  calls: { path: "/analytics/outbound/call-metrics/trend", keys: ["dials", "connected"], labels: ["Dials", "Connected"] },
+  meetings: { path: "/analytics/outbound/meeting-metrics/trend", keys: ["booked", "held"], labels: ["Booked", "Held"] },
+};
+
+export type TrendRow = { date?: string } & Record<string, unknown>;
+
+/** Daily values of one key, in date order. */
+export function seriesOf(rows: TrendRow[] | undefined, key: string): number[] {
+  return (Array.isArray(rows) ? rows : []).map((r) => Number(r[key] ?? 0) || 0);
+}
+
+export interface TrendChartProps {
+  channel?: TrendChannel;
+  days?: number;
+  className?: string;
+}
+
+export function TrendChart({ channel = "email", days = 30, className }: TrendChartProps) {
+  const spec = TREND_SERIES[channel];
+  const { data, loading, error, refetch } = useReport<TrendRow[]>(spec.path, { days });
+  const rows = Array.isArray(data) ? data : [];
+  const a = seriesOf(rows, spec.keys[0]);
+  const b = seriesOf(rows, spec.keys[1]);
+  const total = (v: number[]) => v.reduce((x, y) => x + y, 0);
+
+  if (error) return <ApiError error={error} title="Could not load the trend" onRetry={() => void refetch()} />;
+  if (loading && !data) return <Skeleton className="h-48 w-full" aria-label="Loading trend" />;
+  if (rows.length === 0 || total(a) === 0) return <EmptyState className={className} title="No activity in this window" description="Daily numbers appear here as emails, calls and meetings are recorded." />;
+
+  return (
+    <figure className={className} aria-label={`${channel} trend`}>
+      <div className="mb-2 flex flex-wrap gap-4 text-xs text-muted-foreground">
+        <span>{spec.labels[0]} {formatNumber(total(a))}</span>
+        <span>{spec.labels[1]} {formatNumber(total(b))}</span>
+      </div>
+      <TimeSeriesChart data={rows} xKey="date" kind="line" height={200}
+        series={[{ key: spec.keys[0], label: spec.labels[0] }, { key: spec.keys[1], label: spec.labels[1], tone: "positive" }]} />
+    </figure>
+  );
+}

package/blocks/appointments/README.md

@@ -98,3 +98,9 @@ with the full API key.
 - `03-bookings-digest.ts`: upcoming bookings, pending approvals, recorded meetings.
 - `04-calendar-invite.ts`: ad-hoc invite via `calendarInvites.createCalendarInvite` (not part of the block's
   UI; add the operation to your own proxy allowlist if you call it from the browser).
+
+## Cross-block glue
+
+- `MeetingContactLinks` (`components/meeting-contact-links.tsx`): "Open <attendee>" buttons for a booked or recorded meeting, one per attendee who is a CRM contact. Use it in `MeetingsScreen`'s `renderDetailActions`.
+
+- `RecordMeetingsTab` (`components/record-meetings-tab.tsx`): meetings booked with a contact (`getContactMeetings`, the API's 50 most recent booking events), each opening `/meetings?sel=booking:<id>`. `extraDetailTabs` entry for ContactsScreen.

package/blocks/appointments/block.json

@@ -23,10 +23,12 @@
     "get_availability_appointments_schedules__schedule_id__availability_get",
     "get_available_slots_appointments_slots_get",
     "get_booking_appointments_bookings__booking_uid__get",
+    "get_contact_meetings_contacts__contact_id__meetings_get",
     "get_event_type_appointments_event_types__event_type_id__get",
     "get_meeting_inbox_meetings__meeting_id__get",
     "list_bookings_appointments_bookings_get",
     "list_calendars_appointments_calendars_get",
+    "list_contacts_contacts_get",
     "list_event_types_event_types_get",
     "list_meetings_inbox_meetings_get",
     "list_schedules_appointments_schedules_get",
@@ -113,8 +115,12 @@
       "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": []
+      "operations": [
+        "list_bookings_appointments_bookings_get"
+      ],
+      "tiers": [
+        "read"
+      ]
     },
     {
       "name": "SchedulingScreen",
@@ -134,6 +140,30 @@
       "tiers": [
         "read"
       ]
+    },
+    {
+      "name": "MeetingContactLinks",
+      "file": "components/meeting-contact-links.tsx",
+      "purpose": "\"Open <attendee>\" buttons for a booked or recorded meeting: one per attendee who is a CRM contact; for MeetingsScreen renderDetailActions.",
+      "operations": [
+        "get_booking_appointments_bookings__booking_uid__get",
+        "get_meeting_inbox_meetings__meeting_id__get",
+        "list_contacts_contacts_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "RecordMeetingsTab",
+      "file": "components/record-meetings-tab.tsx",
+      "purpose": "The meetings booked with one contact (booked, rescheduled, cancelled), each opening in the meetings screen; an extraDetailTabs entry for ContactsScreen.",
+      "operations": [
+        "get_contact_meetings_contacts__contact_id__meetings_get"
+      ],
+      "tiers": [
+        "read"
+      ]
     }
   ],
   "hooks": [
@@ -216,6 +246,7 @@
   ],
   "scopes": [
     "campaigns:read",
+    "contacts:read",
     "meetings:delete",
     "meetings:read",
     "meetings:run",

package/blocks/appointments/components/availability-editor.tsx

@@ -23,6 +23,7 @@ import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { useSchedules } from "../hooks/use-schedules";
 import { WEEKDAYS, listOf, toHHMM, unwrap, type AvailabilityRule, type Schedule, type TimeWindow } from "../lib/appointments-types";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface AvailabilityEditorProps {
   /** Schedule to edit; defaults to the org's default schedule. */
@@ -72,6 +73,7 @@ function WindowRow({ window: w, onChange, onRemove }: { window: TimeWindow; onCh
 }
 
 function CalendarPanel({ connectUrl }: { connectUrl: string }) {
+  const brand = useBrand();
   const cals = useG8Query(async (signal) => listOf<CalendarRow>(await g8Get("/appointments/calendars", undefined, { signal }), "calendars"), []);
   return (
     <section aria-label="Calendars" className="space-y-2 rounded-lg border p-3 text-sm">
@@ -84,22 +86,26 @@ function CalendarPanel({ connectUrl }: { connectUrl: string }) {
       ))}
       {!cals.loading && !cals.error && (cals.data ?? []).length === 0 ? <p className="text-muted-foreground">No calendar connected, so busy time is not checked.</p> : null}
       <a className="underline" href={connectUrl} target="_blank" rel="noreferrer">
-        Connect or manage calendars in graph8
+        Connect or manage calendars in {brand.linkLabel}
       </a>
     </section>
   );
 }
 
-export function AvailabilityEditor({ scheduleId, connectCalendarUrl = "https://app.graph8.com", onSaved, className }: AvailabilityEditorProps) {
+export function AvailabilityEditor({ scheduleId, connectCalendarUrl: connectCalendarUrlProp, onSaved, className }: AvailabilityEditorProps) {
+  const brand = useBrand();
+  const connectCalendarUrl = connectCalendarUrlProp ?? brand.appUrl;
   const { schedules, loading: loadingSchedules, error: schedulesError } = useSchedules();
   const [picked, setPicked] = useState<number | undefined>(scheduleId);
   const activeId = picked ?? schedules[0]?.id;
   const [week, setWeek] = useState<Week>({});
   const [overrides, setOverrides] = useState<Override[]>([]);
   const [newDate, setNewDate] = useState("");
+  /** The schedule whose hours are in the form. Save is offered only for a schedule that has loaded, never over a blank week. */
+  const [appliedFor, setAppliedFor] = useState<number | undefined>(undefined);
 
   // Stale context: switching schedule must not show (or save!) the previous schedule's hours.
-  useEffect(() => { setWeek({}); setOverrides([]); }, [activeId]);
+  useEffect(() => { setWeek({}); setOverrides([]); setAppliedFor(undefined); }, [activeId]);
 
   const availability = useG8Query(
     async (signal) => unwrap<Schedule>(await g8Get(`/appointments/schedules/${activeId}/availability`, undefined, { signal })),
@@ -109,9 +115,10 @@ export function AvailabilityEditor({ scheduleId, connectCalendarUrl = "https://a
   useEffect(() => {
     const data = availability.data;
     if (!data) return;
+    setAppliedFor(activeId);
     setWeek(toWeek(data.availability ?? []));
     setOverrides((data.overrides ?? []).filter((o) => o.date).map((o) => ({ date: o.date as string, start: toHHMM(o.start_time), end: toHHMM(o.end_time, "17:00") })));
-  }, [availability.data]);
+  }, [availability.data, activeId]);
 
   const save = useG8Mutation(
     async () =>
@@ -122,10 +129,11 @@ export function AvailabilityEditor({ scheduleId, connectCalendarUrl = "https://a
     { onSuccess: () => onSaved?.() },
   );
 
+  const ready = appliedFor === activeId && !availability.error && !availability.loading;
   const setDay = (day: number, windows: TimeWindow[]) => setWeek((w) => ({ ...w, [day]: windows }));
   if (schedulesError) return <ApiError error={schedulesError} title="Could not load schedules" />;
   if (loadingSchedules) return <Skeleton className="h-64 w-full" aria-label="Loading schedules" />;
-  if (activeId == null) return <EmptyState title="No schedule yet" description="Create a working-hours schedule in graph8 (or POST /appointments/schedules), then edit it here." />;
+  if (activeId == null) return <EmptyState title="No schedule yet" description={`Create a working-hours schedule in ${brand.linkLabel} (or POST /appointments/schedules), then edit it here.`} />;
 
   return (
     <div className={`space-y-4 ${className ?? ""}`}>
@@ -141,6 +149,8 @@ export function AvailabilityEditor({ scheduleId, connectCalendarUrl = "https://a
       <p className="text-sm text-muted-foreground">Times are wall-clock hours in the schedule's time zone: {schedules.find((x) => x.id === activeId)?.time_zone ?? "the schedule's zone"}.</p>
       {availability.error ? <ApiError error={availability.error} title="Could not load availability" onRetry={() => void availability.refetch()} /> : null}
 
+      {!ready ? (availability.error ? null : <Skeleton className="h-48 w-full" aria-label="Loading availability" />) : (
+      <>
       <div className="space-y-2">
         {WEEKDAYS.map(({ day, label }) => {
           const windows = week[day] ?? [];
@@ -186,6 +196,8 @@ export function AvailabilityEditor({ scheduleId, connectCalendarUrl = "https://a
       <Button onClick={() => void save.mutate(undefined)} loading={save.loading}>
         Save availability
       </Button>
+      </>
+      )}
       <CalendarPanel connectUrl={connectCalendarUrl} />
     </div>
   );

package/blocks/appointments/components/booking-page.tsx

@@ -98,7 +98,7 @@ export function BookingPage({ eventTypeId, daysAhead = 14, timeZone, defaultAtte
   if (book.data) {
     return (
       <div className={`space-y-2 rounded-lg border p-4 ${className ?? ""}`} role="status">
-        <h2 className="text-base font-semibold">You are booked</h2>
+        <h2 className="text-base font-medium">You are booked</h2>
         <p className="text-sm">
           {eventType.data?.title ?? "Meeting"} on {formatDateTime(bookedAt ?? slot?.time, zone)}. A calendar invite was sent to {email}.
         </p>
@@ -116,7 +116,7 @@ export function BookingPage({ eventTypeId, daysAhead = 14, timeZone, defaultAtte
   return (
     <div className={`space-y-4 ${className ?? ""}`}>
       <header>
-        <h2 className="text-base font-semibold">{eventType.data?.title ?? "Book a meeting"}</h2>
+        <h2 className="text-base font-medium">{eventType.data?.title ?? "Book a meeting"}</h2>
         <p className="text-sm text-muted-foreground">
           {eventType.data ? `${eventType.data.length} minutes · ` : ""}times shown in {zone}
         </p>

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

@@ -116,7 +116,8 @@ export function EventTypeEditor({ eventTypeId, onSaved, onDeleted, className }:
   const valid = form.title.trim().length > 0 && form.length >= 5 && (slugTouched ? form.slug.trim().length > 0 : true);
 
   if (existing.error) return <ApiError error={existing.error} title="Could not load the event type" onRetry={() => void existing.refetch()} />;
-  if (eventTypeId != null && existing.loading && !existing.data) return <Skeleton className="h-64 w-full" aria-label="Loading event type" />;
+  // Also while the NEXT event type loads (the hook keeps the previous one's data meanwhile): the form is blank then, and saving it would blank the record.
+  if (eventTypeId != null && (existing.loading || !existing.data)) return <Skeleton className="h-64 w-full" aria-label="Loading event type" />;
 
   return (
     <form

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

@@ -21,6 +21,8 @@ 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";
+import { rowActivationProps } from "@/g8/hooks/use-row-activation";
+import { RecordLink } from "@/g8/components/screen/record-link";
 
 export function EventTypeOverview({ eventTypeId }: { eventTypeId: number }) {
   const q = useG8Query(async (signal) => unwrap<EventType>(await g8Get(`/appointments/event-types/${eventTypeId}`, undefined, { signal })), [eventTypeId]);
@@ -52,8 +54,8 @@ export function EventTypeBookings({ eventTypeId, pageSize = 20 }: { eventTypeId:
         <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>
+            <TableRow key={b.uid} className="cursor-pointer" {...rowActivationProps(() => setOpen(b.uid))}>
+              <TableCell><RecordLink id={b.uid} onOpen={() => setOpen(b.uid)}>{formatDateTime(b.start_time)}</RecordLink></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>

package/blocks/appointments/components/meeting-contact-links.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+/**
+ * MeetingContactLinks: "Open <attendee>" buttons for a booked or recorded meeting, one per attendee (at most three)
+ * who is a contact in your CRM. Use it in MeetingsScreen's `renderDetailActions`:
+ *   renderDetailActions={(selection) => <MeetingContactLinks selection={selection} onOpenContact={(id) => router.push(`/contacts?id=${id}`)} />}
+ *
+ * SDK operations, in order:
+ *   1. getBooking          GET /appointments/bookings/{uid}   (read)   for a booking
+ *      getMeeting          GET /inbox/meetings/{id}           (read)   for a recorded meeting
+ *   2. listContacts        GET /contacts?email=               (read)   once per attendee, via the crm ContactLookupLink
+ * Nothing here is billable, external or destructive.
+ */
+
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { ContactLookupLink } from "@/g8/crm/components/contact-lookup-link";
+import { unwrap } from "../lib/appointments-types";
+import type { MeetingSelection } from "./meeting-list";
+
+interface Attendee { email?: string | null; name?: string | null }
+
+export interface MeetingContactLinksProps {
+  selection: MeetingSelection;
+  /** Route to the contact in your contacts screen. */
+  onOpenContact: (contactId: number) => void;
+}
+
+export function MeetingContactLinks({ selection, onOpenContact }: MeetingContactLinksProps) {
+  const { kind, id } = selection;
+  const q = useG8Query(async (signal) => {
+    const path = kind === "booking" ? `/appointments/bookings/${encodeURIComponent(id)}` : `/inbox/meetings/${encodeURIComponent(id)}`;
+    return unwrap<{ attendees?: Attendee[] | null }>(await g8Get(path, undefined, { signal })).attendees ?? [];
+  }, [kind, id]);
+  const seen = new Set<string>();
+  const people = (q.data ?? []).filter((a) => {
+    const email = a.email?.trim().toLowerCase();
+    if (!email || seen.has(email)) return false;
+    seen.add(email);
+    return true;
+  }).slice(0, 3);
+  return (
+    <>
+      {people.map((a) => (
+        <ContactLookupLink key={a.email} email={a.email} label={`Open ${a.name || a.email}`} onOpen={onOpenContact} />
+      ))}
+    </>
+  );
+}

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

@@ -48,7 +48,7 @@ function RecordedDetail({ id, className }: { id: string; className?: string }) {
   const m = q.data;
   return (
     <section className={`space-y-3 ${className ?? ""}`}>
-      <h2 className="text-base font-semibold">{m.subject || "Untitled meeting"}</h2>
+      <h2 className="text-base font-medium">{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>
@@ -94,7 +94,7 @@ function BookingDetail({ uid, onChanged, className }: { uid: string; onChanged?:
 
   return (
     <section className={`space-y-4 ${className ?? ""}`}>
-      <h2 className="text-base font-semibold">{b.title || b.event_type_title || "Meeting"}</h2>
+      <h2 className="text-base font-medium">{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>

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

@@ -18,12 +18,18 @@ 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 { useUrlFilters } from "@/g8/hooks/use-url-filters";
+import { SelectFilter, TextFilter } from "@/g8/components/screen/filter-controls";
 import { formatDateTime, listOf, type Booking, type RecordedMeeting } from "../lib/appointments-types";
+import { rowActivationProps } from "@/g8/hooks/use-row-activation";
+import { RecordLink } from "@/g8/components/screen/record-link";
 
 export type MeetingView = "upcoming" | "past" | "cancelled" | "recorded";
 export type MeetingSelection = { kind: "booking"; id: string } | { kind: "meeting"; id: string };
 
 export interface MeetingListProps {
+  /** URL param the host screen reads for this record type. With it the name is a real link (Cmd-click opens it in a new tab); without it a plain button. */
+  linkParam?: string;
   onSelect?: (selection: MeetingSelection) => void;
   initialView?: MeetingView;
   pageSize?: number;
@@ -41,8 +47,8 @@ const VIEWS: ReadonlyArray<{ value: MeetingView; label: string }> = [
   { value: "recorded", label: "Recorded" },
 ];
 
-function bookingQuery(view: Exclude<MeetingView, "recorded">, now: string, page: number, take: number) {
-  const base = { skip: page * take, take };
+function bookingQuery(view: Exclude<MeetingView, "recorded">, now: string, page: number, take: number, attendeeEmail?: string) {
+  const base = { skip: page * take, take, attendee_email: attendeeEmail || undefined };
   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" };
@@ -52,36 +58,38 @@ 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;
-}
+/** Every filter the meetings (/inbox/meetings) and bookings APIs take besides the view tab. */
+const MEETING_FILTERS = ["search", "participant_email", "timeframe", "has_transcript", "attendee_email"] as const;
 
-export function MeetingList({ onSelect, initialView = "upcoming", pageSize = 20, refreshKey, selectedId, className }: MeetingListProps) {
+export function MeetingList({ linkParam, onSelect, initialView = "upcoming", pageSize = 20, refreshKey, selectedId, className }: MeetingListProps) {
   const [view, setView] = useState<MeetingView>(initialView);
   const [page, setPage] = useState(0);
-  const [search, setSearch] = useState("");
-  const query = useDebouncedText(search);
+  // Every filter the meetings and bookings APIs take lives in the URL (`m_participant_email=...`).
+  const uf = useUrlFilters(MEETING_FILTERS, { prefix: "m_" });
+  const search = uf.draft.search;
+  const query = uf.filters.search.trim();
+  const { participant_email, timeframe, has_transcript, attendee_email } = uf.filters;
   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 });
+        const env = await g8Get("/inbox/meetings", { search: query || undefined, participant_email: participant_email ? participant_email.split(",").map((e) => e.trim()).filter(Boolean) : undefined, timeframe: timeframe || undefined, has_transcript: has_transcript ? has_transcript === "yes" : 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 env = await g8Get("/appointments/bookings", bookingQuery(view, now, page, pageSize, attendee_email.trim()), { signal });
       const items = listOf<Booking>(env, "bookings");
       return { kind: "booking" as const, items, more: items.length === pageSize };
     },
-    [view, page, query, pageSize, now, refreshKey],
+    [view, page, query, participant_email, timeframe, has_transcript, attendee_email, pageSize, now, refreshKey],
+    { enabled: uf.ready },
   );
 
   const switchView = (next: MeetingView) => {
     setView(next);
     setPage(0);
   };
+  useEffect(() => { setPage(0); }, [query, participant_email, timeframe, has_transcript, attendee_email]);
   const result = rows.data;
 
   return (
@@ -94,7 +102,19 @@ export function MeetingList({ onSelect, initialView = "upcoming", pageSize = 20,
             </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}
+        {view === "recorded" ? <Input aria-label="Search meetings" className="w-56" placeholder="Search recorded meetings" value={search} onChange={(e) => uf.set("search", e.target.value)} /> : null}
+      </div>
+      <div className="flex flex-wrap items-center gap-2">
+        {view === "recorded" ? (
+          <>
+            <TextFilter label="participant email" placeholder="Participant email" type="email" value={uf.draft.participant_email} onChange={(v) => uf.set("participant_email", v)} className="w-52" />
+            <SelectFilter label="timeframe" any="Past (default)" value={uf.draft.timeframe} onChange={(v) => uf.set("timeframe", v)} options={[{ value: "upcoming", label: "Upcoming" }, { value: "all", label: "All" }]} />
+            <SelectFilter label="transcript" any="With or without transcript" value={uf.draft.has_transcript} onChange={(v) => uf.set("has_transcript", v)} options={[{ value: "yes", label: "Has a transcript" }, { value: "no", label: "No transcript" }]} />
+          </>
+        ) : (
+          <TextFilter label="attendee email" placeholder="Attendee email" type="email" value={uf.draft.attendee_email} onChange={(v) => uf.set("attendee_email", v)} className="w-52" />
+        )}
+        {uf.active ? <Button size="sm" variant="ghost" onClick={uf.clear}>Clear filters</Button> : null}
       </div>
 
       {rows.error ? (
@@ -120,17 +140,17 @@ export function MeetingList({ onSelect, initialView = "upcoming", pageSize = 20,
           <TableBody>
             {result.kind === "booking"
               ? (result.items as Booking[]).map((b) => (
-                  <TableRow key={b.uid} data-state={selectedId === b.uid ? "selected" : undefined} className="cursor-pointer" onClick={() => onSelect?.({ kind: "booking", id: b.uid })}>
+                  <TableRow key={b.uid} data-state={selectedId === b.uid ? "selected" : undefined} className="cursor-pointer" {...(onSelect ? rowActivationProps(() => 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="font-medium">{onSelect ? <RecordLink param={linkParam} id={`booking:${b.uid}`} onOpen={() => onSelect({ kind: "booking", id: b.uid })}>{b.title || b.event_type_title || "Meeting"}</RecordLink> : 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} data-state={selectedId === m.id ? "selected" : undefined} className="cursor-pointer" onClick={() => onSelect?.({ kind: "meeting", id: m.id })}>
+                  <TableRow key={m.id} data-state={selectedId === m.id ? "selected" : undefined} className="cursor-pointer" {...(onSelect ? rowActivationProps(() => 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="font-medium">{onSelect ? <RecordLink param={linkParam} id={`meeting:${m.id}`} onOpen={() => onSelect({ kind: "meeting", id: m.id })}>{m.subject || "Untitled meeting"}</RecordLink> : 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>

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

@@ -40,6 +40,7 @@ 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";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface MeetingsScreenProps {
   /** Where a person connects a calendar (graph8 app). */
@@ -99,7 +100,9 @@ function ScheduleSheet({ open, onOpenChange, onBooked }: { open: boolean; onOpen
   );
 }
 
-export function MeetingsScreen({ connectCalendarUrl = "https://app.graph8.com", renderDetailActions, extraDetailTabs, toolbarActions }: MeetingsScreenProps) {
+export function MeetingsScreen({ connectCalendarUrl: connectCalendarUrlProp, renderDetailActions, extraDetailTabs, toolbarActions }: MeetingsScreenProps) {
+  const brand = useBrand();
+  const connectCalendarUrl = connectCalendarUrlProp ?? brand.appUrl;
   const [raw, setRaw] = useUrlState("sel");
   const [mode, setMode] = useUrlState("view");
   const selection = parseSelection(raw);
@@ -143,10 +146,10 @@ export function MeetingsScreen({ connectCalendarUrl = "https://app.graph8.com",
         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}`)} />}
+        list={<MeetingList linkParam="sel" 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 title="Calendar sync" description={`Google and Microsoft sign-in happens in the ${brand.linkLabel} 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 {brand.linkLabel}<ExternalLink className="size-3.5" aria-hidden /></a>
       </SectionCard>
       <ScheduleSheet open={scheduling} onOpenChange={setScheduling} onBooked={changed} />
     </ScreenLayout>