@graph8/sdk 0.370.0 → 0.374.0

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

@@ -0,0 +1,228 @@
+"use client";
+
+/**
+ * Types, vocabularies and pure helpers for the surveys block.
+ *
+ * A graph8 survey is ONE question with a numeric answer (plus an optional comment): NPS (0 to 10) or CSAT (1 to 5).
+ * The vocabularies below are copied from the API's request patterns (`^(nps|csat)$`, `^(email|bridge|in_app)$`,
+ * `^(none|link|html)$`, `^(email|bridge)$`, `^(scheduled|list_entry|stage_entry)$`), not from memory: the API refuses
+ * anything else. Calls nothing.
+ */
+
+export type SurveyType = "nps" | "csat";
+export type DeliveryChannel = "email" | "bridge" | "in_app";
+export type CommentMode = "none" | "link" | "html";
+export type SendChannel = "email" | "bridge";
+export type TriggerKind = "scheduled" | "list_entry" | "stage_entry";
+export type Bucket = "day" | "week" | "month";
+
+export const SURVEY_TYPES: { value: SurveyType; label: string; hint: string; min: number; max: number }[] = [
+  { value: "nps", label: "NPS", hint: "How likely are you to recommend us? Scored 0 to 10.", min: 0, max: 10 },
+  { value: "csat", label: "CSAT", hint: "How satisfied were you? Scored 1 to 5.", min: 1, max: 5 },
+];
+export const DELIVERY_CHANNELS: { value: DeliveryChannel; label: string }[] = [
+  { value: "email", label: "Email" },
+  { value: "bridge", label: "Chat message (messaging bridge)" },
+  { value: "in_app", label: "In-app widget" },
+];
+export const COMMENT_MODES: { value: CommentMode; label: string }[] = [
+  { value: "none", label: "Score only" },
+  { value: "link", label: "Score, then a comment form" },
+  { value: "html", label: "Comment box inside the email" },
+];
+export const SEND_CHANNELS: { value: SendChannel; label: string }[] = [
+  { value: "email", label: "Email" },
+  { value: "bridge", label: "Chat message" },
+];
+export const TRIGGER_KINDS: { value: TriggerKind; label: string; hint: string }[] = [
+  { value: "scheduled", label: "On a schedule", hint: "Re-sends to the list every N days." },
+  { value: "list_entry", label: "When someone joins a list", hint: "Sends to each person who enters the watched list." },
+  { value: "stage_entry", label: "When a record reaches a stage", hint: "Sends when a record moves into the stage you name." },
+];
+export const BUCKETS: { value: Bucket; label: string }[] = [
+  { value: "day", label: "Daily" },
+  { value: "week", label: "Weekly" },
+  { value: "month", label: "Monthly" },
+];
+export const CADENCE_DAYS = [30, 60, 90] as const;
+
+/** One survey definition (SurveyResponseDTO). */
+export interface Survey {
+  id: string;
+  name: string;
+  type: string;
+  question_text: string;
+  scale_min: number;
+  scale_max: number;
+  delivery_channel: string;
+  is_active: boolean;
+  comment_mode?: string | null;
+  thank_you_copy?: string | null;
+  template_id?: number | null;
+  score_field_column_id?: string | null;
+  created_at?: string | null;
+}
+
+export interface TrendBar { period: string; total: number; promoters: number; passives: number; detractors: number; nps_score?: number | null; csat_avg?: number | null }
+export interface Summary {
+  survey_id: string;
+  type: string;
+  bucket: string;
+  delivery_channel: string;
+  total_respondents: number;
+  nps_score?: number | null;
+  promoters: number;
+  passives: number;
+  detractors: number;
+  csat_avg?: number | null;
+  satisfied?: number | null;
+  neutral?: number | null;
+  dissatisfied?: number | null;
+  response_rate: { rate: number; responded: number; sent: number };
+  time_series: TrendBar[];
+}
+export interface Trends { survey_id: string; bars: TrendBar[]; bucket: string; type: string; delivery_channel: string }
+
+export interface ResponseRow {
+  contact_id: number;
+  first_name?: string | null;
+  last_name?: string | null;
+  score: number;
+  classification?: string | null;
+  comment?: string | null;
+  channel?: string | null;
+  responded_at?: string | null;
+  response_count?: number;
+  trend?: string | null;
+  history?: { score: number; responded_at?: string | null; send_id?: number | null }[];
+}
+export interface AppUserResponseRow { app_user_id: string; channel: string; score: number; comment?: string | null; responded_at?: string | null }
+
+export interface SendRow {
+  id: number;
+  status: string;
+  channel: string;
+  audience_ref?: string | null;
+  audience_name?: string | null;
+  recipient_count?: number;
+  responded_count?: number;
+  scheduled_at?: string | null;
+  created_at?: string | null;
+  trigger_kind?: string | null;
+  delivery_breakdown?: { bounced?: number; delivered?: number; failed?: number; opened?: number; pending?: number; sent?: number };
+}
+export interface SendAccepted { send_id: number; status: string; recipient_count: number }
+export interface SendDetail { id: number; status: string; channel: string; recipient_count: number; scheduled_at?: string | null; audience_ref?: string | null; survey_id: string }
+
+export interface Trigger {
+  id: string;
+  survey_id: string;
+  trigger_kind: string;
+  is_active: boolean;
+  sender_email: string;
+  sender_name?: string | null;
+  reply_to?: string | null;
+  subject: string;
+  audience_ref?: string | null;
+  stage_value?: string | null;
+  cadence_days?: number | null;
+}
+export interface SendingDomain { id: number; domain: string; status: "verified" | "pending" | "not_set_up" }
+
+export interface OrgSummary {
+  bucket: string;
+  org_nps: { nps_score?: number | null; promoters: number; passives: number; detractors: number; total_respondents: number };
+  org_csat: { csat_avg?: number | null; total_respondents: number };
+  in_app_csat_avg?: number | null;
+  in_app_respondents?: number;
+  per_survey: { survey_id: string; name?: string | null; type: string; status?: string | null; is_active?: boolean; sent_count?: number; total_respondents: number; nps_score?: number | null; csat_avg?: number | null; promoters: number; passives: number; detractors: number }[];
+  time_series: TrendBar[];
+}
+
+export const isNps = (s: { type?: string | null }): boolean => (s.type ?? "").toLowerCase() === "nps";
+export const typeLabel = (s: { type?: string | null }): string => (isNps(s) ? "NPS" : "CSAT");
+export const scaleOf = (type: SurveyType): { min: number; max: number } => {
+  const t = SURVEY_TYPES.find((x) => x.value === type) ?? SURVEY_TYPES[0];
+  return { min: t.min, max: t.max };
+};
+export const channelLabel = (v: string | null | undefined): string => DELIVERY_CHANNELS.find((c) => c.value === v)?.label ?? (v || "Not set");
+/** A survey receives answers from the people it is sent to (or the in-app widget) while it is open. */
+export const statusOf = (s: Survey): "open" | "closed" => (s.is_active ? "open" : "closed");
+
+/** "42", "-8", or a faint dash when the API has no score (too few answers is not zero). */
+export function scoreText(v: number | null | undefined, digits = 0): string {
+  return v == null || !Number.isFinite(v) ? "-" : v.toFixed(digits).replace(/^-0$/, "0");
+}
+export function percent(part: number | null | undefined, whole: number | null | undefined): string {
+  return !whole || part == null ? "-" : `${Math.round((part / whole) * 100)}%`;
+}
+export const fullName = (r: { first_name?: string | null; last_name?: string | null; contact_id?: number }): string =>
+  [r.first_name, r.last_name].filter(Boolean).join(" ") || (r.contact_id != null ? `Contact ${r.contact_id}` : "Unknown");
+export const when = (v: string | null | undefined): string => (v ? new Date(v).toLocaleString() : "");
+
+/** The classification the API may omit, derived from the survey type's published bands (NPS 9-10 / 7-8 / 0-6; CSAT 4-5 / 3 / 1-2). */
+export function bandOf(type: string | null | undefined, score: number, given?: string | null): string {
+  if (given) return given;
+  if ((type ?? "").toLowerCase() === "csat") return score >= 4 ? "satisfied" : score === 3 ? "neutral" : "dissatisfied";
+  return score >= 9 ? "promoter" : score >= 7 ? "passive" : "detractor";
+}
+
+/** The audience size a send will reach, at most: the list's contact count, null when the list is unknown. */
+export function audienceSize(list: { contact_count?: number | null; total?: number | null } | null | undefined): number | null {
+  const n = list?.contact_count ?? list?.total;
+  return typeof n === "number" ? n : null;
+}
+
+/** Fields a person can change after creating a survey (the API does not take type, scale or comment mode on update). */
+export interface SurveyFormValues { name: string; question_text: string; thank_you_copy: string; delivery_channel: DeliveryChannel }
+
+/**
+ * Only the fields that changed. A cleared thank-you line is sent as "" (the API ignores null on update, so null would
+ * silently keep the old text); an empty name or question never reaches here because the form blocks saving it.
+ */
+export function surveyDiff(before: Survey, next: SurveyFormValues): Record<string, unknown> {
+  const diff: Record<string, unknown> = {};
+  if (next.name.trim() !== before.name) diff.name = next.name.trim();
+  if (next.question_text.trim() !== before.question_text) diff.question_text = next.question_text.trim();
+  if (next.thank_you_copy.trim() !== (before.thank_you_copy ?? "").trim()) diff.thank_you_copy = next.thank_you_copy.trim();
+  if (next.delivery_channel !== before.delivery_channel) diff.delivery_channel = next.delivery_channel;
+  return diff;
+}
+
+/** One CSV cell: quoted, quotes doubled, and a leading = + - @ tab or CR neutralised so a spreadsheet never runs a comment as a formula. */
+export function csvCell(value: unknown): string {
+  let text = value == null ? "" : String(value);
+  if (/^[=+\-@\t\r]/.test(text) && !/^-?\d+(\.\d+)?$/.test(text)) text = `'${text}`;
+  return `"${text.replace(/"/g, '""')}"`;
+}
+
+export function responsesCsv(type: string, rows: ResponseRow[]): string {
+  const head = ["contact_id", "first_name", "last_name", "score", "classification", "comment", "channel", "responded_at", "response_count"];
+  const lines = rows.map((r) => [r.contact_id, r.first_name, r.last_name, r.score, bandOf(type, r.score, r.classification), r.comment, r.channel, r.responded_at, r.response_count ?? 1].map(csvCell).join(","));
+  return [head.map(csvCell).join(","), ...lines].join("\r\n");
+}
+
+/** Hand a text file to the browser. */
+export function downloadText(filename: string, text: string, mime = "text/csv;charset=utf-8"): void {
+  const url = URL.createObjectURL(new Blob([text], { type: mime }));
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+
+export const slugName = (name: string): string => name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "survey";
+
+/** The email part of a sender after the @, lower-cased: the domain a send must be verified for. */
+export const domainOf = (email: string): string => email.split("@")[1]?.trim().toLowerCase() ?? "";
+export const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/** The API's `scheduled_at` is a date-time: a `datetime-local` value is read as local time and sent as ISO. */
+export function scheduleIso(local: string): string | undefined {
+  if (!local) return undefined;
+  const d = new Date(local);
+  return Number.isNaN(d.getTime()) ? undefined : d.toISOString();
+}

package/blocks/surveys/recipes/create-an-nps-survey.ts

@@ -0,0 +1,22 @@
+/**
+ * @title Create an NPS (or CSAT) survey and read back what the API stored
+ * @when Setting up the question you will ask. A survey is ONE question with a numeric answer: `type` is "nps" (0 to 10) or
+ * "csat" (1 to 5), fixed at creation. Creating it sends nothing; people are asked only when you call sendSurvey.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const created = await g8.api.surveys.createSurvey({
+  body: {
+    name: "Relationship NPS",
+    type: "nps",
+    question_text: "How likely are you to recommend us to a friend or colleague?",
+    delivery_channel: "email",
+    comment_mode: "link",
+    thank_you_copy: "Thank you, that helps us a lot.",
+  },
+});
+
+const survey = await g8.api.surveys.getSurvey({ path: { survey_id: created.data.id } });
+console.log(survey.data.id, survey.data.type, `${survey.data.scale_min}-${survey.data.scale_max}`, survey.data.is_active);

package/blocks/surveys/recipes/send-a-survey-and-follow-it.ts

@@ -0,0 +1,27 @@
+/**
+ * @title Send a survey to a list and follow the send
+ * @when Asking an audience now or later. This EMAILS REAL PEOPLE: have a person confirm the audience size first. The sender
+ * address must be on a verified sending domain (listSurveySendingDomains), and `scheduled_at` queues the send for later.
+ * The API answers 202 with a send id; dispatch is asynchronous, so poll getSurveySend.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function sendSurvey(surveyId: string, listId: number): Promise<{ sendId: number; status: string; recipients: number }> {
+  const domains = await g8.api.surveys.listSurveySendingDomains({});
+  const verified = domains.data.find((d) => d.status === "verified");
+  if (!verified) throw new Error("No verified sending domain. Verify one first with verifySurveyDomain.");
+
+  const accepted = await g8.api.surveys.sendSurvey({
+    path: { survey_id: surveyId },
+    body: { audience_ref: String(listId), channel: "email", sender_email: `survey@${verified.domain}`, subject: "Quick question" },
+  });
+
+  let status = accepted.data.status;
+  for (let i = 0; i < 20 && !["sent", "failed", "scheduled"].includes(status); i++) {
+    await new Promise((r) => setTimeout(r, 3000));
+    status = (await g8.api.surveys.getSurveySend({ path: { send_id: accepted.data.send_id } })).data.status;
+  }
+  return { sendId: accepted.data.send_id, status, recipients: accepted.data.recipient_count };
+}

package/blocks/surveys/recipes/survey-score-report.ts

@@ -0,0 +1,27 @@
+/**
+ * @title Report every survey's score, response rate and latest comments
+ * @when A weekly digest or a dashboard backend. A null score means too few answers to publish, which is not zero. The
+ * responses endpoint returns every answer in one read (it takes no paging), so a very large survey is a large response.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function scoreReport(): Promise<Array<{ name: string; type: string; score: number | null; answered: number; asked: number; comments: string[] }>> {
+  const surveys = await g8.api.surveys.listSurveys({});
+  const out: Array<{ name: string; type: string; score: number | null; answered: number; asked: number; comments: string[] }> = [];
+  for (const s of surveys.data) {
+    const summary = await g8.api.surveys.getSurveySummary({ path: { survey_id: s.id }, query: { bucket: "month" } });
+    const answers = await g8.api.surveys.getSurveyResponses({ path: { survey_id: s.id } });
+    const d = summary.data;
+    out.push({
+      name: s.name,
+      type: s.type,
+      score: (s.type === "nps" ? d.nps_score : d.csat_avg) ?? null,
+      answered: d.response_rate.responded,
+      asked: d.response_rate.sent,
+      comments: answers.data.responses.filter((r) => r.comment).slice(0, 5).map((r) => r.comment as string),
+    });
+  }
+  return out;
+}

package/blocks/visitors/components/snippet-install.tsx

@@ -18,6 +18,8 @@ import { useState } from "react";
 import { Button, Skeleton } from "@graph8/sdk/ui";
 import { g8Get } from "@/g8/lib/g8-client";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useAllPages } from "@/g8/hooks/use-all-pages";
+import { hasNextOf } from "@/g8/lib/paging";
 import { useJobPoll } from "@/g8/hooks/use-job-poll";
 import { ApiError } from "@/g8/components/api-error";
 import { EmptyState } from "@/g8/components/empty-state";
@@ -72,7 +74,7 @@ function CodeBlock({ label, code }: { label: string; code: string }) {
           {copied ? "Copied" : "Copy"}
         </Button>
       </div>
-      <pre className="overflow-x-auto rounded bg-gray-950 p-3 text-xs text-gray-100">
+      <pre className="overflow-x-auto rounded bg-muted p-3 text-xs text-foreground">
         <code>{code}</code>
       </pre>
     </div>
@@ -99,33 +101,40 @@ function InstallCheck({ writeKey, onInstalled }: { writeKey: string; onInstalled
       </Button>
       {check.error ? <ApiError error={check.error} /> : null}
       {s?.status === "receiving" ? (
-        <p role="status" className="text-sm text-green-700">
+        <p role="status" className="text-sm text-positive-foreground">
           Installed: {s.event_count.toLocaleString()} events received.
         </p>
       ) : null}
       {s?.status === "unknown" ? (
-        <p role="status" className="text-sm text-amber-700">
+        <p role="status" className="text-sm text-warning-foreground">
           Your workspace cannot be probed yet. Open your site once and check the Visitors feed.
         </p>
       ) : null}
       {s?.status === "no_events" && !check.polling ? (
-        <p role="status" className="text-sm text-gray-600">
+        <p role="status" className="text-sm text-muted-foreground">
           No events yet. Load a page that has the snippet, then check again.
         </p>
       ) : null}
       {s?.status === "no_events" && check.polling ? (
-        <p className="text-sm text-gray-600">No events yet. Open a page that has the snippet.</p>
+        <p className="text-sm text-muted-foreground">No events yet. Open a page that has the snippet.</p>
       ) : null}
     </div>
   );
 }
 
+/** Streams per read: every page is read, so the stream picker offers all of them. */
+const STREAM_PAGE = 50;
+
 export function SnippetInstall({ streamId, onInstalled, className }: SnippetInstallProps) {
   const brand = useBrand();
   const [selected, setSelected] = useState<string | undefined>(streamId);
-  const streams = useG8Query((signal) => g8Get<Stream[]>("/streams", { limit: 50 }, { signal }), []);
+  const streams = useAllPages<Stream>(async (page, signal) => {
+    const env = await g8Get<Stream[]>("/streams", { page, limit: STREAM_PAGE }, { signal });
+    const rows = env.data ?? [];
+    return { rows, hasNext: hasNextOf(env, STREAM_PAGE, rows.length) };
+  }, []);
   const snippet = useG8Query((signal) => g8Get<SnippetPayload>("/snippet", { stream_id: selected }, { signal }), [selected]);
-  const list = streams.data?.data ?? [];
+  const list = streams.items;
 
   if (snippet.error) return <ApiError error={snippet.error} onRetry={() => void snippet.refetch()} className={className} />;
   if (snippet.loading && !snippet.data) return <Skeleton className={`h-40 w-full ${className ?? ""}`} />;
@@ -145,7 +154,7 @@ export function SnippetInstall({ streamId, onInstalled, className }: SnippetInst
         <label className="flex items-center gap-2 text-sm">
           Website
           <select
-            className="rounded border border-gray-300 px-2 py-1"
+            className="rounded border border-input px-2 py-1"
             value={selected ?? s.stream_id ?? ""}
             onChange={(e) => setSelected(e.target.value || undefined)}
           >
@@ -159,7 +168,7 @@ export function SnippetInstall({ streamId, onInstalled, className }: SnippetInst
         </label>
       ) : null}
       {s.warning ? (
-        <p role="alert" className="rounded border border-amber-200 bg-amber-50 p-2 text-sm text-amber-900">
+        <p role="alert" className="rounded border border-warning-foreground/25 bg-warning p-2 text-sm text-warning-foreground">
           {s.warning}
         </p>
       ) : null}

package/blocks/visitors/components/traffic-chart.tsx

@@ -62,7 +62,7 @@ export function LineChart({ points, metric }: { points: TrendPoint[]; metric: Me
   const y = (v: number) => height - (v / max) * (height - 12) - 6;
   const path = values.map((v, i) => `${i === 0 ? "M" : "L"}${x(i).toFixed(1)},${y(v).toFixed(1)}`).join(" ");
   return (
-    <svg viewBox={`0 0 ${width} ${height}`} role="img" aria-label={`${metric} per day`} className="h-40 w-full text-blue-600">
+    <svg viewBox={`0 0 ${width} ${height}`} role="img" aria-label={`${metric} per day`} className="h-40 w-full text-foreground">
       <path d={path} fill="none" stroke="currentColor" strokeWidth="2" />
       {values.map((v, i) => (
         <circle key={points[i].date} cx={x(i)} cy={y(v)} r="2.5" fill="currentColor">
@@ -75,7 +75,8 @@ export function LineChart({ points, metric }: { points: TrendPoint[]; metric: Me
 
 function activeNow(envelope: unknown): number | undefined {
   const data = (envelope as { data?: Record<string, unknown> } | null)?.data;
-  const value = data?.active_users_5min ?? data?.active_5min ?? data?.active_users ?? data?.five_min ?? data?.active_now;
+  // The realtime report answers `active_5m` (reports/analytics/queries/realtime.py); the older names stay as fallbacks.
+  const value = data?.active_5m ?? data?.active_users_5min ?? data?.active_5min ?? data?.active_users ?? data?.five_min ?? data?.active_now;
   return typeof value === "number" ? value : undefined;
 }
 
@@ -113,8 +114,8 @@ export function TrafficChart({ days = 30, writeKey, realtimeSeconds = 10, classN
             </Button>
           ))}
         </div>
-        <p className="text-sm text-gray-600" aria-live="polite">
-          {now != null ? `${now} on the site now` : ""}
+        <p className="text-sm text-muted-foreground" aria-live="polite">
+          {now != null ? `${now} on the site now` : live.data || live.error ? "On the site now: -" : ""}
         </p>
       </div>
 
@@ -126,7 +127,7 @@ export function TrafficChart({ days = 30, writeKey, realtimeSeconds = 10, classN
         <EmptyState title="No traffic yet" description="Install the snippet and visits will chart here." />
       ) : (
         <div>
-          <p className="text-sm text-gray-600">
+          <p className="text-sm text-muted-foreground">
             {total.toLocaleString()} {METRICS.find((m) => m.key === metric)?.label.toLowerCase()} in {days} days
           </p>
           <LineChart points={points} metric={metric} />
@@ -136,7 +137,7 @@ export function TrafficChart({ days = 30, writeKey, realtimeSeconds = 10, classN
       {topPages.length > 0 ? (
         <table className="w-full text-sm">
           <thead>
-            <tr className="text-left text-gray-500">
+            <tr className="text-left text-muted-foreground">
               <th className="py-1">Top pages</th>
               <th className="py-1 text-right">Views</th>
             </tr>

package/blocks/visitors/components/visitor-company-card.tsx

@@ -17,7 +17,9 @@ import { useState } from "react";
 import type { ReactNode } from "react";
 import { Button, Card, CardContent, CardHeader, CardTitle, Skeleton } from "@graph8/sdk/ui";
 import { g8Get } from "@/g8/lib/g8-client";
-import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useLoadMoreList } from "@/g8/hooks/use-load-more-list";
+import { byPage, hasNextOf } from "@/g8/lib/paging";
+import { LoadMore } from "@/g8/components/paging-notices";
 import { ApiError } from "@/g8/components/api-error";
 import { companyLabel, pageLabel, pageOf, timeAgo } from "../lib/visitors-utils";
 import type { FlowEvent, VisitorGroup } from "../lib/visitors-utils";
@@ -32,33 +34,41 @@ export interface VisitorCompanyCardProps {
 }
 
 function PageList({ pages }: { pages: FlowEvent[] }) {
-  if (pages.length === 0) return <p className="text-sm text-gray-500">No page views recorded.</p>;
+  if (pages.length === 0) return <p className="text-sm text-muted-foreground">No page views recorded.</p>;
   return (
     <ol className="space-y-1 text-sm">
       {pages.map((p, i) => (
         <li key={p.message_id ?? `${p.received_at}-${i}`} className="flex justify-between gap-3">
           <span className="truncate">
             {pageLabel(p)}
-            {p.page_referrer ? <span className="ml-2 text-xs text-gray-400">from {p.page_referrer}</span> : null}
+            {p.page_referrer ? <span className="ml-2 text-xs text-muted-foreground">from {p.page_referrer}</span> : null}
           </span>
-          <span className="shrink-0 text-xs text-gray-500">{timeAgo(p.received_at)}</span>
+          <span className="shrink-0 text-xs text-muted-foreground">{timeAgo(p.received_at)}</span>
         </li>
       ))}
     </ol>
   );
 }
 
+/** Page views per read; "Load more" appends the next page of the journey. */
+const JOURNEY_PAGE = 100;
+
 function Journey({ companyId }: { companyId: number }) {
-  const journey = useG8Query(
-    (signal) =>
-      g8Get("/visitors/companies/events", { show_mode: "raw", filter: JSON.stringify({ company_id: companyId }), limit: 100 }, { signal }),
-    [companyId],
-  );
-  if (journey.loading) return <Skeleton className="h-16 w-full" />;
+  const journey = useLoadMoreList(byPage<FlowEvent>(JOURNEY_PAGE, async (page, signal) => {
+    const env = await g8Get("/visitors/companies/events", { show_mode: "raw", filter: JSON.stringify({ company_id: companyId }), page, limit: JOURNEY_PAGE }, { signal });
+    // Raw mode returns one row per page view.
+    const rows = pageOf(env).events as unknown as FlowEvent[];
+    return { rows, hasNext: hasNextOf(env, JOURNEY_PAGE, rows.length) };
+  }), [companyId]);
+  if (journey.loading && !journey.data) return <Skeleton className="h-16 w-full" />;
   if (journey.error) return <ApiError error={journey.error} onRetry={() => void journey.refetch()} />;
-  // Raw mode returns one row per page view.
-  const views = pageOf(journey.data).events as unknown as FlowEvent[];
-  return <PageList pages={views} />;
+  const views = journey.data ?? [];
+  return (
+    <>
+      <PageList pages={views} />
+      <LoadMore shown={views.length} noun="page views" hasMore={journey.hasMore} loading={journey.loadingMore} onLoadMore={journey.loadMore} />
+    </>
+  );
 }
 
 export function VisitorCompanyCard({ visit, previewPages = 5, actions, className }: VisitorCompanyCardProps) {
@@ -69,7 +79,7 @@ export function VisitorCompanyCard({ visit, previewPages = 5, actions, className
       <CardHeader className="flex flex-row items-start justify-between gap-3">
         <div>
           <CardTitle className="text-base">{companyLabel(visit)}</CardTitle>
-          <p className="text-xs text-gray-500">
+          <p className="text-xs text-muted-foreground">
             {visit.COMPANY_DOMAIN ? `${visit.COMPANY_DOMAIN} - ` : ""}last seen {timeAgo(visit.received_at)} - {plural(pages.length, "page view")}
           </p>
         </div>

package/blocks/visitors/components/visitor-feed.tsx

@@ -131,26 +131,26 @@ export function VisitorFeed({
           ))}
         </div>
       ) : (
-        <ul className="divide-y rounded border border-gray-200">
+        <ul className="divide-y rounded border border-border">
           {events.map((visit, i) => (
             <li key={`${visit.CONTACT_ID}-${visit.received_at}-${i}`}>
               <button
                 type="button"
-                className="flex w-full items-center justify-between px-3 py-2 text-left text-sm hover:bg-gray-50"
+                className="flex w-full items-center justify-between px-3 py-2 text-left text-sm hover:bg-surface-hover"
                 onClick={() => onSelectPerson?.(visit)}
               >
                 <span>
                   <span className="font-medium">{personLabel(visit)}</span>
-                  <span className="ml-2 text-xs text-gray-500">{visit.children?.[0] ? pageLabel(visit.children[0]) : ""}</span>
+                  <span className="ml-2 text-xs text-muted-foreground">{visit.children?.[0] ? pageLabel(visit.children[0]) : ""}</span>
                 </span>
-                <span className="text-xs text-gray-500">{timeAgo(visit.received_at)}</span>
+                <span className="text-xs text-muted-foreground">{timeAgo(visit.received_at)}</span>
               </button>
             </li>
           ))}
         </ul>
       )}
 
-      <div className="flex items-center justify-between text-sm text-gray-600">
+      <div className="flex items-center justify-between text-sm text-muted-foreground">
         <span>{total.toLocaleString()} visits</span>
         <div className="flex gap-2">
           <Button size="sm" variant="outline" disabled={page <= 1 || feed.loading} onClick={() => setPage((p) => p - 1)}>

package/blocks/web-analytics/README.md

@@ -0,0 +1,102 @@
+# web-analytics
+
+Website analytics for your own sites: **traffic, acquisition, audience, pages, engagement, conversions and realtime**, read from the
+tracking pipeline (the same reports as the graph8 Analytics pages). Every call is a free read. Nothing here is billable, external
+or destructive, so there are no confirmations.
+
+## Screens
+
+`WebAnalyticsScreen` (`components/web-analytics-screen.tsx`) is the finished page.
+
+```tsx
+import { WebAnalyticsScreen } from "@/g8/web-analytics/components/web-analytics-screen";
+export default function Page() { return <WebAnalyticsScreen />; }
+```
+
+One **site picker** and one **window** drive every tab and live in the URL, so a link opens the same view:
+`?site=pubKeyA,pubKeyB` (none = all sites), `?days=7|30|90|365` or `?from=YYYY-MM-DD&to=YYYY-MM-DD`, `?bots=1`, `?internal=1`, `?tab=`.
+
+| Tab | What it shows |
+|---|---|
+| Overview | visitors, new visitors, sessions, page views; daily traffic; conversion rate; top pages (a row opens the page detail) |
+| Acquisition | channels, channel trend, sources and mediums, UTM campaigns, referrals, social networks, search engines |
+| Audience | top countries, cities and languages; every country or city; languages; browsers, operating systems, devices; new or returning |
+| Pages | top, landing and exit pages; custom events; a page detail panel (`?page=/path`) with views, visitors, form submissions, bookings |
+| Engagement | sessions, pages per session, time on site, bounce and engaged share against the previous period; trend; depth and time distributions; by channel, campaign, landing page |
+| Conversions | conversion rate; funnel (visitors, viewed a form, submitted, booked); goals and their trend; forms, form trend, form analysis |
+| Realtime | active visitors in the last 5 and 30 minutes, active pages, traffic sources, locations; re-read every 10 seconds while visible |
+
+Optional props: `resolveLandingPage(path)` returns the id of the landing page at exactly that address (one match only), and `onOpenLandingPage(id)` opens it
+(the hubspot stack wires both to the pages block). `refreshSeconds` (default 10; 0 turns the realtime poll off), `toolbarActions`, `className`.
+
+## Rules the screen keeps
+
+- **Loading is visible.** Changing a site, the window or a switch dims every card (and a first load shows a skeleton). A failed or refused request clears the card and shows the error with Retry; the previous numbers never stay under an error.
+- **Unavailable is not zero.** The reports swallow a failed ClickHouse query and answer `meta.stale: true` with empty data. A card in that state says it is unavailable (with Retry), and the tiles that belong to that card go with it.
+- **Unknown rates are dashes.** A conversion rate the API sends as null (no visitors, no viewers) and any rate whose denominator is 0 shows a dash, never zero percent.
+- **No request the API refuses.** `days` 1 to 365; a custom range needs both days, real dates, start not after end, at most 365 days (Apply is disabled with the reason otherwise); site keys are letters, digits, `-`, `_`; `limit` never exceeds each report's maximum (languages 100, form analysis 100, engagement by landing page 100, realtime pages and sources 50, the rest 200); a page path must start with `/` and use plain URL characters.
+- **Sort, then cut.** Tables sort the whole list a read returned and only then show the first 10 ("Show all N"). A read that came back full says "Showing the first N".
+- **No invented defaults.** The window defaults to the API's own 30 days; bots and internal traffic stay excluded (the flags are sent only when switched on).
+
+## Types
+
+The contract answers every web analytics report with `AnalyticsResponse { success, data: object | array, meta }`: `data` is **untyped**. The row types in
+`lib/web-analytics-types.ts` are typed from the backend instead (the column aliases of `reports/analytics/queries/{audience,acquisition,behavior,conversions,engagement,realtime}.py`).
+Every field is optional and read defensively.
+
+## Install
+
+```
+npx @graph8/sdk add web-analytics
+```
+
+Installs `foundation`, `crm` and `visitors` first if missing. Everything lands under `g8/web-analytics/`. Your app's proxy must allow the `analytics` and `streams` prefixes.
+
+## Prerequisites (the human must do these)
+
+| Where | What | How to verify |
+|---|---|---|
+| The website | The graph8 tracking snippet is pasted into the site. Without it every report is empty. | The visitors block's SnippetInstall reports events received. |
+| graph8 key | `analytics:read`, and `integrations:read` for the site list | `g8.api.me.describeCurrentKey()` |
+
+## Operations (39)
+
+- `get_acquisition_campaigns_analytics_acquisition_campaigns_get`
+- `get_acquisition_channels_analytics_acquisition_channels_get`
+- `get_acquisition_channels_trend_analytics_acquisition_channels_trend_get`
+- `get_acquisition_referrals_analytics_acquisition_referrals_get`
+- `get_acquisition_search_analytics_acquisition_search_get`
+- `get_acquisition_social_analytics_acquisition_social_get`
+- `get_acquisition_sources_analytics_acquisition_sources_get`
+- `get_audience_behavior_analytics_audience_behavior_get`
+- `get_audience_demographics_analytics_audience_demographics_get`
+- `get_audience_languages_analytics_audience_languages_get`
+- `get_audience_overview_analytics_audience_overview_get`
+- `get_audience_trend_analytics_audience_trend_get`
+- `get_conversion_rate_analytics_conversions_rate_get`
+- `get_engagement_by_campaign_analytics_engagement_by_campaign_get`
+- `get_engagement_by_channel_analytics_engagement_by_channel_get`
+- `get_engagement_by_landing_page_analytics_engagement_by_landing_page_get`
+- `get_engagement_overview_analytics_engagement_overview_get`
+- `get_engagement_trend_analytics_engagement_trend_get`
+- `get_events_analytics_behavior_events_get`
+- `get_exit_pages_analytics_behavior_exit_pages_get`
+- `get_form_analysis_analytics_conversions_forms_analysis_get`
+- `get_forms_analytics_conversions_forms_get`
+- `get_forms_trend_analytics_conversions_forms_trend_get`
+- `get_funnel_analytics_conversions_funnel_get`
+- `get_geo_cities_analytics_audience_geo_cities_get`
+- `get_geo_countries_analytics_audience_geo_get`
+- `get_goals_analytics_conversions_goals_get`
+- `get_goals_trend_analytics_conversions_goals_trend_get`
+- `get_landing_pages_analytics_behavior_landing_pages_get`
+- `get_page_metrics_analytics_behavior_page_metrics_get`
+- `get_realtime_analytics_realtime_get`
+- `get_realtime_locations_analytics_realtime_locations_get`
+- `get_realtime_pages_analytics_realtime_pages_get`
+- `get_realtime_sources_analytics_realtime_sources_get`
+- `get_session_depth_distribution_analytics_engagement_depth_distribution_get`
+- `get_technology_overview_analytics_audience_technology_get`
+- `get_time_on_site_distribution_analytics_engagement_time_distribution_get`
+- `get_top_pages_analytics_behavior_pages_get`
+- `list_org_streams_streams_get`