@graph8/sdk 0.362.0 → 0.373.0

package/blocks/surveys/components/surveys-screen.tsx

@@ -0,0 +1,234 @@
+"use client";
+
+/**
+ * SurveysScreen: the finished NPS and CSAT workspace. No props needed.
+ *
+ * Composes: ScreenLayout (title, tabs, stats), Toolbar (search, type, status and channel filters), SplitView + DetailPanel
+ * (the selected survey, deep link `?id=`), FormSheet (new survey via SurveyForm), SurveyResults, SurveyResponses, SurveySend,
+ * SurveyTriggers, SurveyForm in edit mode, OrgSummary, SendingDomains, AccountNps and ContactSurveyHistory.
+ *
+ * Tabs (`?tab=`): Surveys (list and detail), Overview (org-wide scores), Sending domains, Accounts and people.
+ * A survey's detail (`?id=`) has Results, Responses, Send, Automatic sends, Settings and Details; `&view=full` shows it as a page.
+ *
+ * User flows: see every survey with its type, state and channel; search and filter; create an NPS or CSAT survey; open one to read
+ * its score, response rate, split and trend; read, search, filter and export its answers (CSV); send it to a list now or later
+ * (confirmed with the audience size); add or remove automatic sends; edit its question, thank-you line and channel; close it
+ * (stops new sends, keeps every answer) and reopen it; delete it (confirmed); verify a sending domain; read org-wide NPS and CSAT;
+ * look up one company's NPS and one person's answers. The API has no share link, embed code, AI question writer or question
+ * list: a survey is one question (see the README for the gaps).
+ *
+ * SDK operations: listSurveys, updateSurvey (close and reopen), deleteSurvey (destructive, confirmed); everything else lives in
+ * the composed parts, which confirm every send, domain verification and removal.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { ClipboardCheck, Lock, LockOpen, Plus, Trash2 } from "lucide-react";
+import { Button, Skeleton } 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 { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Delete, g8Get, g8Patch } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { plural } from "@/g8/lib/plural";
+import { COMMENT_MODES, channelLabel, isNps, statusOf, typeLabel, when } from "../lib/surveys-types";
+import type { ResponseRow, Survey } from "../lib/surveys-types";
+import { AccountNps } from "./account-nps";
+import { ContactSurveyHistory } from "./contact-survey-history";
+import { OrgSummary } from "./org-summary";
+import { SendingDomains } from "./sending-domains";
+import { SurveyForm } from "./survey-form";
+import { SurveyResponses } from "./survey-responses";
+import { SurveyResults } from "./survey-results";
+import { SurveySend } from "./survey-send";
+import { SurveyTriggers } from "./survey-triggers";
+
+export interface SurveysScreenProps {
+  renderRowActions?: (survey: Survey) => ReactNode;
+  renderDetailActions?: (survey: Survey) => ReactNode;
+  /** Render a link to the person behind an answer (for example to your contact page). */
+  renderContact?: (row: ResponseRow) => ReactNode;
+  extraDetailTabs?: { id: string; label: string; render: (survey: Survey) => ReactNode }[];
+  toolbarActions?: ReactNode;
+  className?: string;
+}
+
+type Tab = "surveys" | "overview" | "domains" | "accounts";
+const TABS: Tab[] = ["surveys", "overview", "domains", "accounts"];
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+
+export function SurveysScreen({ renderRowActions, renderDetailActions, renderContact, extraDetailTabs, toolbarActions, className }: SurveysScreenProps) {
+  const [id, setId] = useUrlState("id", "");
+  const [view, setView] = useUrlState("view", "");
+  const [tabParam, setTabParam] = useUrlState("tab", "surveys");
+  const tab = (TABS.includes(tabParam as Tab) ? tabParam : "surveys") as Tab;
+  const expandProps = { onExpand: () => setView("full"), onCollapse: view === "full" ? () => setView(null) : undefined };
+  const [search, setSearch] = useState("");
+  const [typeFilter, setTypeFilter] = useState("");
+  const [statusFilter, setStatusFilter] = useState("");
+  const [channelFilter, setChannelFilter] = useState("");
+  const [creating, setCreating] = useState(false);
+  const [toDelete, setToDelete] = useState<Survey | null>(null);
+  const [busy, setBusy] = useState<string | null>(null);
+
+  const list = useG8Query((signal) => g8Get<Survey[]>("/feedback/surveys", {}, { signal }).then((r) => r.data ?? []), [], { key: ["surveys", "list"] });
+  const toggle = useG8Mutation((s: Survey) => g8Patch<Survey>(`/feedback/surveys/${encodeURIComponent(s.id)}`, { is_active: !s.is_active }), {
+    invalidates: (_r, s) => [["surveys", "list"], ["surveys", "detail", s.id]],
+  });
+  const remove = useG8Mutation((s: Survey) => g8Delete(`/feedback/surveys/${encodeURIComponent(s.id)}`), {
+    onSuccess: (_r, s) => { setToDelete(null); if (s.id === id) { setId(null); setView(null); } },
+    invalidates: [["surveys"]],
+  });
+  const flip = async (s: Survey): Promise<void> => {
+    setBusy(s.id);
+    await toggle.mutate(s);
+    setBusy(null);
+  };
+
+  const all = list.data ?? [];
+  const q = search.trim().toLowerCase();
+  const shown = all.filter((s) => (!typeFilter || s.type === typeFilter) && (!statusFilter || statusOf(s) === statusFilter) && (!channelFilter || s.delivery_channel === channelFilter) && (!q || `${s.name} ${s.question_text}`.toLowerCase().includes(q)));
+  const selected = all.find((s) => s.id === id);
+  const closeDetail = (): void => { setId(null); setView(null); };
+
+  const rows = list.error ? <ApiError error={list.error} title="Could not load surveys" onRetry={() => void list.refetch()} /> : list.loading && !list.data ? (
+    <div aria-busy="true" className="grid gap-2"><Skeleton className="h-16 w-full" /><Skeleton className="h-16 w-full" /><Skeleton className="h-16 w-full" /></div>
+  ) : shown.length === 0 ? (
+    <EmptyState icon={<ClipboardCheck className="size-8" />} title={all.length === 0 ? "No surveys yet" : "No surveys match"} description={all.length === 0 ? "Ask customers how likely they are to recommend you (NPS) or how satisfied they are (CSAT), and read the answers here." : "Try another search or filter."} action={all.length === 0 ? <Button onClick={() => setCreating(true)}>Create your first survey</Button> : undefined} />
+  ) : (
+    <>
+      <p role="status" className="text-muted-foreground mb-2 text-xs">{shown.length === all.length ? `All ${plural(all.length, "survey")}` : `${shown.length.toLocaleString()} of ${plural(all.length, "survey")}`}</p>
+      <ul className="grid gap-2">
+        {shown.map((s) => (
+          <li key={s.id} className={`flex flex-wrap items-center justify-between gap-2 rounded-md border p-3 ${s.id === id ? "bg-muted" : ""}`}>
+            <button type="button" className="min-w-0 flex-1 text-left" onClick={() => setId(s.id)}>
+              <span className="block truncate font-medium">{s.name}</span>
+              <span className="text-muted-foreground block truncate text-xs">{s.question_text} · {channelLabel(s.delivery_channel)}</span>
+            </button>
+            <StatusPill tone="info">{typeLabel(s)}</StatusPill>
+            <StatusPill tone={s.is_active ? "positive" : "neutral"}>{statusOf(s)}</StatusPill>
+            <div className="flex gap-1">
+              <Button size="sm" variant="ghost" aria-label={`${s.is_active ? "Close" : "Reopen"} ${s.name}`} loading={busy === s.id} disabled={busy !== null} onClick={() => void flip(s)}>{s.is_active ? <Lock className="size-4" /> : <LockOpen className="size-4" />}</Button>
+              <Button size="sm" variant="ghost" aria-label={`Delete ${s.name}`} onClick={() => setToDelete(s)}><Trash2 className="size-4" /></Button>
+              {renderRowActions?.(s)}
+            </div>
+          </li>
+        ))}
+      </ul>
+    </>
+  );
+
+  const detail = selected ? (
+    <DetailPanel
+      title={selected.name}
+      subtitle={selected.question_text}
+      badges={<><StatusPill tone="info">{typeLabel(selected)}</StatusPill><StatusPill tone={selected.is_active ? "positive" : "neutral"}>{statusOf(selected)}</StatusPill></>}
+      actions={<>{renderDetailActions?.(selected)}<Button size="sm" variant="outline" loading={busy === selected.id} disabled={busy !== null} onClick={() => void flip(selected)}>{selected.is_active ? <Lock className="size-4" /> : <LockOpen className="size-4" />}{selected.is_active ? "Close survey" : "Reopen survey"}</Button></>}
+      onClose={closeDetail}
+      {...expandProps}
+      tabs={[
+        { id: "results", label: "Results", content: <SurveyResults key={selected.id} survey={selected} /> },
+        { id: "responses", label: "Responses", content: <SurveyResponses key={selected.id} survey={selected} renderContact={renderContact} /> },
+        { id: "send", label: "Send", content: <SurveySend key={selected.id} survey={selected} /> },
+        { id: "automatic", label: "Automatic sends", content: <SurveyTriggers key={selected.id} survey={selected} /> },
+        { id: "settings", label: "Settings", content: <SurveyForm key={selected.id} survey={selected} onSaved={() => void list.refetch()} /> },
+        { id: "details", label: "Details", content: <SurveyDetails survey={selected} /> },
+        ...(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(selected) })),
+      ]}
+    />
+  ) : null;
+
+  const surveysTab = (
+    <SplitView
+      list={(
+        <div className="grid gap-3">
+          <Toolbar
+            search={{ value: search, onChange: setSearch, placeholder: "Search surveys" }}
+            filters={(
+              <>
+                <select aria-label="Filter by type" className={SELECT} value={typeFilter} onChange={(e) => setTypeFilter(e.target.value)}><option value="">All types</option><option value="nps">NPS</option><option value="csat">CSAT</option></select>
+                <select aria-label="Filter by status" className={SELECT} value={statusFilter} onChange={(e) => setStatusFilter(e.target.value)}><option value="">Open and closed</option><option value="open">Open</option><option value="closed">Closed</option></select>
+                <select aria-label="Filter by channel" className={SELECT} value={channelFilter} onChange={(e) => setChannelFilter(e.target.value)}><option value="">All channels</option><option value="email">Email</option><option value="bridge">Chat message</option><option value="in_app">In-app</option></select>
+              </>
+            )}
+            actions={toolbarActions}
+          />
+          {rows}
+        </div>
+      )}
+      detail={detail}
+      detailOpen={Boolean(selected)}
+      onCloseDetail={closeDetail}
+      expanded={view === "full"}
+      onExpandedChange={(e) => setView(e ? "full" : null)}
+      detailWidth="xl"
+    />
+  );
+
+  return (
+    <ScreenLayout
+      className={className}
+      title="Surveys"
+      description="Ask customers how likely they are to recommend you (NPS) or how satisfied they are (CSAT)."
+      icon={<ClipboardCheck className="size-5" />}
+      actions={<Button size="sm" onClick={() => setCreating(true)}><Plus className="size-4" />New survey</Button>}
+      tabs={[{ id: "surveys", label: "Surveys", count: list.data ? all.length : undefined }, { id: "overview", label: "Overview" }, { id: "domains", label: "Sending domains" }, { id: "accounts", label: "Accounts and people" }]}
+      activeTab={tab}
+      onTabChange={(next) => { setTabParam(next === "surveys" ? null : next); closeDetail(); }}
+      stats={tab === "surveys" ? [
+        { label: "Surveys", value: list.data ? all.length.toLocaleString() : "..." },
+        { label: "Open", value: all.filter((s) => s.is_active).length.toLocaleString(), tone: "positive" },
+        { label: "Closed", value: all.filter((s) => !s.is_active).length.toLocaleString() },
+        { label: "NPS / CSAT", value: `${all.filter((s) => isNps(s)).length} / ${all.filter((s) => !isNps(s)).length}` },
+      ] : undefined}
+    >
+      {tab === "surveys" ? surveysTab : tab === "overview" ? <OrgSummary onOpenSurvey={(sid) => { setTabParam(null); setId(sid); }} /> : tab === "domains" ? <SendingDomains /> : (
+        <div className="grid gap-4 lg:grid-cols-2"><AccountNps /><ContactSurveyHistory /></div>
+      )}
+      <FormSheet open={creating} onOpenChange={setCreating} title="New survey" description="One question, scored. Nothing is sent until you send it.">
+        {creating ? <SurveyForm onCancel={() => setCreating(false)} onSaved={(created) => { setCreating(false); setTabParam(null); void list.refetch(); setId(created.id); }} /> : null}
+      </FormSheet>
+      <ConfirmSpendDialog
+        open={toDelete !== null}
+        tier="destructive"
+        title={`Delete ${toDelete?.name ?? "this survey"}?`}
+        affected={1}
+        description={<><p>The survey, its automatic sends and every answer collected are removed. To stop asking but keep the answers, close it instead.</p>{remove.error ? <ApiError error={remove.error} title="Could not delete the survey" /> : null}</>}
+        confirmLabel="Delete"
+        confirming={remove.loading}
+        onCancel={() => setToDelete(null)}
+        onConfirm={() => { if (toDelete) void remove.mutate(toDelete); }}
+      />
+      {toggle.error ? <ApiError error={toggle.error} title="Could not change the survey" /> : null}
+    </ScreenLayout>
+  );
+}
+
+function SurveyDetails({ survey }: { survey: Survey }) {
+  return (
+    <KeyValueList
+      columns={2}
+      items={[
+        { label: "Name", value: survey.name },
+        { label: "Type", value: typeLabel(survey) },
+        { label: "Status", value: statusOf(survey) },
+        { label: "Question", value: survey.question_text, wide: true },
+        { label: "Scale", value: `${survey.scale_min} to ${survey.scale_max}` },
+        { label: "Shown through", value: channelLabel(survey.delivery_channel) },
+        { label: "Comments", value: COMMENT_MODES.find((m) => m.value === survey.comment_mode)?.label ?? "Score only" },
+        { label: "Thank-you line", value: survey.thank_you_copy || "", wide: true },
+        { label: "Created", value: when(survey.created_at) },
+        { label: "Survey id", value: survey.id, mono: true },
+      ]}
+    />
+  );
+}

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/README.md

@@ -5,6 +5,16 @@ and chart traffic. The Apollo / 6sense "website visitors" screen.
 
 Depends on: `crm`. Install: `npx @graph8/sdk add visitors`.
 
+## Screens
+
+`VisitorsScreen` (`components/visitors-screen.tsx`) is the finished page: copy it as your route. No props are required.
+
+- **Visitors tab**: bots/internal-traffic toggles, 7-day stat strip (visitors, sessions, page views with sparklines), the polled company/people feed, and a detail
+  panel for a clicked person with the pages they viewed. Company cards expand to the full journey.
+- **Traffic tab**: 7/30/90 day window, trend chart, top pages, "on the site now". **Install tab**: the snippet and an install check.
+- Slots: `toolbarActions`, `renderDetailActions(visit, kind)`, `extraDetailTabs` (each `{ id, label, render(visit, kind) }`; shown once the visitor row is known). Everything is read tier.
+- Prerequisite: the snippet pasted into your site (only a person can do this); People also needs `contacts:read`.
+
 ## Components
 
 | Component | What it does | Tiers |

package/blocks/visitors/block.json

@@ -71,6 +71,29 @@
       "tiers": [
         "read"
       ]
+    },
+    {
+      "name": "VisitorsScreen",
+      "file": "components/visitors-screen.tsx",
+      "purpose": "Finished website-visitors page: week stat strip, company and people feed with person detail, traffic charts and the snippet install check.",
+      "operations": [
+        "get_audience_trend_analytics_audience_trend_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "VisitorDetail",
+      "file": "components/visitor-detail.tsx",
+      "purpose": "Complete screen for one visiting company or identified person: fields, pages viewed, full journey.",
+      "operations": [
+        "list_company_visitor_events_visitors_companies_events_get",
+        "list_contact_visitor_events_visitors_contacts_events_get"
+      ],
+      "tiers": [
+        "read"
+      ]
     }
   ],
   "hooks": [],
@@ -134,6 +157,7 @@
     }
   ],
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "lucide-react": ">=0.400"
   }
 }