@graph8/sdk 0.362.0 → 0.373.0

package/blocks/surveys/components/account-nps.tsx

@@ -0,0 +1,69 @@
+"use client";
+
+/**
+ * AccountNps: how the people at one company scored you.
+ *
+ * SDK operations, in order:
+ *   1. listCompanies, through CompanyPicker                                              read   find the company by name (skipped when you pass `companyId`)
+ *   2. getCompanySurveyNps (GET /feedback/companies/{company_id}/nps)                    read   account NPS, split, coverage and each contact's latest score
+ * Pass `companyId` to show a company you already have open (for example in a company page). The account score is hidden by the API when there are too few answers.
+ */
+
+import { useState } from "react";
+import { Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatStrip } from "@/g8/components/screen/stat-strip";
+import { CompanyPicker } from "@/g8/pickers/components/company-picker";
+import type { CompanyOption } from "@/g8/pickers/components/company-picker";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { plural } from "@/g8/lib/plural";
+import { bandOf, fullName, percent, scoreText, when } from "../lib/surveys-types";
+
+interface CompanyNps {
+  company_id: number;
+  nps_score?: number | null;
+  suppressed: boolean;
+  promoters: number;
+  passives: number;
+  detractors: number;
+  total_respondents: number;
+  coverage: { rate: number; responded: number; total_contacts: number };
+  contacts: { contact_id: number; first_name?: string | null; last_name?: string | null; score?: number | null; classification?: string | null; responded?: boolean; last_responded_at?: string | null }[];
+}
+export interface AccountNpsProps { companyId?: number; className?: string }
+
+export function AccountNps({ companyId, className }: AccountNpsProps) {
+  const [picked, setPicked] = useState<CompanyOption | null>(null);
+  const id = companyId ?? picked?.id;
+  const nps = useG8Query((signal) => g8Get<CompanyNps>(`/feedback/companies/${id}/nps`, {}, { signal }).then((r) => r.data), [id], { enabled: id != null, key: ["surveys", "company-nps", id ?? ""] });
+  const d = nps.data;
+  return (
+    <SectionCard title="Account NPS" description="How the people at one company scored you." className={className}>
+      <div className="grid gap-3">
+        {companyId == null ? <div><Label htmlFor="g8-sva-company" className="mb-1">Company</Label><CompanyPicker id="g8-sva-company" value={picked} onChange={setPicked} /></div> : null}
+        {id == null ? <EmptyState compact title="Choose a company" description="Its NPS, coverage and each contact's latest score appear here." /> : nps.error ? <ApiError error={nps.error} title="Could not load the account NPS" onRetry={() => void nps.refetch()} /> : !d ? <Skeleton className="h-24 w-full" aria-busy="true" /> : (
+          <>
+            <StatStrip items={[
+              { label: "Account NPS", value: d.suppressed ? "-" : scoreText(d.nps_score, 0), hint: d.suppressed ? "Hidden: too few answers to publish a score." : `${plural(d.total_respondents, "person", "people")} answered.` },
+              { label: "Coverage", value: percent(d.coverage.responded, d.coverage.total_contacts), hint: `${d.coverage.responded} of ${d.coverage.total_contacts} contacts answered.` },
+              { label: "Split", value: `${d.promoters} / ${d.passives} / ${d.detractors}`, hint: "Promoters, passives, detractors." },
+            ]} />
+            {d.contacts.length === 0 ? <p className="text-muted-foreground text-sm">No contact at this company has answered.</p> : (
+              <ul className="grid gap-1 text-sm">
+                {d.contacts.map((c) => (
+                  <li key={c.contact_id} className="flex items-center justify-between gap-2 rounded-md border p-2">
+                    <span>{fullName(c)}</span>
+                    <span className="text-muted-foreground text-xs">{c.responded && c.score != null ? `${c.score} · ${bandOf("nps", c.score, c.classification)} · ${when(c.last_responded_at)}` : "No answer yet"}</span>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </>
+        )}
+      </div>
+    </SectionCard>
+  );
+}

package/blocks/surveys/components/contact-survey-history.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+/**
+ * ContactSurveyHistory: every survey answer one person has given, newest first.
+ *
+ * SDK operations, in order:
+ *   1. listContacts, through ContactPicker                                       read   find the person by name (skipped when you pass `contactId`)
+ *   2. getContactSurveyHistory (GET /feedback/contacts/{contact_id}/history)     read   their answers across all surveys
+ * Pass `contactId` to show a person you already have open (for example in a contact page).
+ */
+
+import { useState } from "react";
+import { Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { ContactPicker } from "@/g8/pickers/components/contact-picker";
+import type { ContactOption } from "@/g8/pickers/components/contact-picker";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { bandOf, when } from "../lib/surveys-types";
+
+interface ContactHistory { contact_id: number; responses: { survey_id: string; survey_name?: string | null; type: string; score: number; classification?: string | null; channel?: string | null; responded_at?: string | null }[] }
+
+export interface ContactSurveyHistoryProps { contactId?: number; className?: string }
+
+export function ContactSurveyHistory({ contactId, className }: ContactSurveyHistoryProps) {
+  const [picked, setPicked] = useState<ContactOption | null>(null);
+  const id = contactId ?? picked?.id;
+  const history = useG8Query((signal) => g8Get<ContactHistory>(`/feedback/contacts/${id}/history`, {}, { signal }).then((r) => r.data), [id], { enabled: id != null, key: ["surveys", "contact-history", id ?? ""] });
+  const rows = history.data?.responses ?? [];
+  return (
+    <SectionCard title="A person's survey history" description="Every survey this person has answered, newest first." className={className}>
+      <div className="grid gap-3">
+        {contactId == null ? <div><Label htmlFor="g8-sva-contact" className="mb-1">Contact</Label><ContactPicker id="g8-sva-contact" value={picked} onChange={setPicked} /></div> : null}
+        {id == null ? <EmptyState compact title="Choose a contact" description="Their answers across all surveys appear here." /> : history.error ? <ApiError error={history.error} title="Could not load the history" onRetry={() => void history.refetch()} /> : !history.data ? <Skeleton className="h-16 w-full" aria-busy="true" /> : rows.length === 0 ? (
+          <p className="text-muted-foreground text-sm">This person has not answered a survey.</p>
+        ) : (
+          <ul className="grid gap-1 text-sm">
+            {rows.map((r, i) => (
+              <li key={`${r.survey_id}:${i}`} className="flex items-center justify-between gap-2 rounded-md border p-2">
+                <span className="min-w-0 truncate">{r.survey_name || r.type.toUpperCase()} <span className="text-muted-foreground text-xs">{when(r.responded_at)}</span></span>
+                <span className="flex items-center gap-2">Score {r.score}<StatusPill tone={r.classification === "promoter" || r.classification === "satisfied" ? "positive" : r.classification === "detractor" || r.classification === "dissatisfied" ? "negative" : "neutral"}>{bandOf(r.type, r.score, r.classification)}</StatusPill></span>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </SectionCard>
+  );
+}

package/blocks/surveys/components/org-summary.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+/**
+ * OrgSummary: org-wide NPS and CSAT across every survey, optionally for one audience list, with a rollup per survey.
+ *
+ * SDK operations, in order:
+ *   1. getSurveyOrgSummary (GET /feedback/org-summary?segment&bucket)   read   headline scores, split and per-survey rollup
+ *   2. listLists (GET /lists), through ListSelect                       read   the optional audience filter
+ * A dash is "not enough answers", never a zero score.
+ */
+
+import { useState } from "react";
+import { Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatStrip } from "@/g8/components/screen/stat-strip";
+import { ListSelect } from "@/g8/crm/components/list-select";
+import type { ListSelectOption } from "@/g8/crm/components/list-select";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { plural } from "@/g8/lib/plural";
+import { BUCKETS, scoreText } from "../lib/surveys-types";
+import type { Bucket, OrgSummary as OrgSummaryData } from "../lib/surveys-types";
+
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+
+export interface OrgSummaryProps {
+  /** Called with a survey id when a row of the rollup is chosen. */
+  onOpenSurvey?: (surveyId: string) => void;
+}
+
+export function OrgSummary({ onOpenSurvey }: OrgSummaryProps) {
+  const [bucket, setBucket] = useState<Bucket>("month");
+  const [segment, setSegment] = useState<ListSelectOption | null>(null);
+  const org = useG8Query(
+    (signal) => g8Get<OrgSummaryData>("/feedback/org-summary", { bucket, segment: segment ? String(segment.id) : undefined }, { signal }).then((r) => r.data),
+    [bucket, segment?.id],
+    { key: ["surveys", "summary", "org", bucket, segment?.id ?? ""] },
+  );
+  const d = org.data;
+  return (
+    <div className="grid gap-4">
+      <div className="flex flex-wrap items-end gap-3">
+        <div className="min-w-56">
+          <label htmlFor="g8-svo-segment" className="text-muted-foreground mb-1 block text-sm">Audience</label>
+          <ListSelect id="g8-svo-segment" label="Audience" emptyOption="All contacts" value={segment?.id ?? ""} valueLabel={segment?.title} selectClassName={SELECT} onChange={setSegment} />
+        </div>
+        <div>
+          <label htmlFor="g8-svo-bucket" className="text-muted-foreground mb-1 block text-sm">Trend by</label>
+          <select id="g8-svo-bucket" className={SELECT} value={bucket} onChange={(e) => setBucket(e.target.value as Bucket)}>{BUCKETS.map((b) => <option key={b.value} value={b.value}>{b.label}</option>)}</select>
+        </div>
+      </div>
+      {org.error ? <ApiError error={org.error} title="Could not load the overview" onRetry={() => void org.refetch()} /> : !d ? <Skeleton className="h-32 w-full" aria-busy="true" /> : (
+        <>
+          <StatStrip
+            items={[
+              { label: "Org NPS", value: scoreText(d.org_nps.nps_score, 0), hint: `${plural(d.org_nps.total_respondents, "answer")}. A dash means too few answers.` },
+              { label: "Promoters / passives / detractors", value: `${d.org_nps.promoters} / ${d.org_nps.passives} / ${d.org_nps.detractors}` },
+              { label: "Org CSAT", value: scoreText(d.org_csat.csat_avg, 1), hint: `${plural(d.org_csat.total_respondents, "answer")}, scored 1 to 5.` },
+              { label: "In-app CSAT", value: scoreText(d.in_app_csat_avg, 1), hint: `${plural(d.in_app_respondents ?? 0, "team answer")}.` },
+            ]}
+          />
+          <SectionCard title="By survey" description={plural(d.per_survey.length, "survey")} flush>
+            {d.per_survey.length === 0 ? <EmptyState title="No surveys yet" description="Create a survey to start collecting scores." compact /> : (
+              <ul className="grid">
+                {d.per_survey.map((p) => (
+                  <li key={p.survey_id} className="flex flex-wrap items-center justify-between gap-2 border-t p-3 text-sm first:border-t-0">
+                    {onOpenSurvey ? <button type="button" className="min-w-0 text-left font-medium underline-offset-2 hover:underline" aria-label={`Open ${p.name ?? p.type}`} onClick={() => onOpenSurvey(p.survey_id)}>{p.name || p.type.toUpperCase()}</button> : <span className="font-medium">{p.name || p.type.toUpperCase()}</span>}
+                    <span className="text-muted-foreground text-xs">
+                      {p.type === "nps" ? `NPS ${scoreText(p.nps_score, 0)}` : `CSAT ${scoreText(p.csat_avg, 1)}`} · {plural(p.total_respondents, "answer")}{p.sent_count != null ? ` of ${p.sent_count.toLocaleString()} asked` : ""}
+                    </span>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </SectionCard>
+        </>
+      )}
+    </div>
+  );
+}

package/blocks/surveys/components/sending-domains.tsx

@@ -0,0 +1,113 @@
+"use client";
+
+/**
+ * SendingDomains: the domains surveys may be emailed from, with their verification state, and a way to verify a new one.
+ *
+ * SDK operations, in order:
+ *   1. listSurveySendingDomains (GET /feedback/sending-domains?include_unverified=true)   read      every domain with its state
+ *   2. verifySurveyDomain (POST /feedback/sending-domains/verify)                         external  starts verification and returns the DNS records to publish: ConfirmSpendDialog
+ *   3. surveyDomainStatus (GET /feedback/sending-domains/status?domain)                   read      checks whether the domain has verified yet (this is what promotes it to the verified list)
+ * A domain only turns verified after the DNS records are published at your DNS provider; this panel cannot do that for you.
+ */
+
+import { useState } from "react";
+import { Globe, RefreshCw } from "lucide-react";
+import { Button, Input, Label, 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 { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import type { Tone } from "@/g8/components/screen/status-pill";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import type { SendingDomain } from "../lib/surveys-types";
+
+const TONE: Record<SendingDomain["status"], Tone> = { verified: "positive", pending: "warning", not_set_up: "neutral" };
+const LABEL: Record<SendingDomain["status"], string> = { verified: "verified", pending: "waiting for DNS", not_set_up: "not set up" };
+const DOMAIN_RE = /^(?=.{4,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$/i;
+
+/** The open payload the API returns for a verification: records (when present) as rows, every other scalar as a fact. */
+function Payload({ data }: { data: Record<string, unknown> }) {
+  const records = Array.isArray(data.records) ? (data.records as Record<string, unknown>[]) : Array.isArray(data.dns_records) ? (data.dns_records as Record<string, unknown>[]) : [];
+  const scalars = Object.entries(data).filter(([, v]) => v != null && typeof v !== "object");
+  return (
+    <div className="grid gap-3">
+      {scalars.length ? <KeyValueList columns={2} items={scalars.map(([k, v]) => ({ label: k.replace(/_/g, " "), value: String(v) }))} /> : null}
+      {records.length ? (
+        <div>
+          <h3 className="mb-1 text-sm font-medium">Publish these DNS records</h3>
+          <ul className="grid gap-1 text-sm">{records.map((r, i) => <li key={i} className="rounded-md border p-2 font-mono text-xs break-all">{Object.entries(r).filter(([, v]) => v != null && typeof v !== "object").map(([k, v]) => `${k}: ${String(v)}`).join("  ")}</li>)}</ul>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export function SendingDomains() {
+  const [domain, setDomain] = useState("");
+  const [confirm, setConfirm] = useState(false);
+  const [result, setResult] = useState<{ domain: string; data: Record<string, unknown> } | null>(null);
+  const [checking, setChecking] = useState<string | null>(null);
+
+  const domains = useG8Query((signal) => g8Get<SendingDomain[]>("/feedback/sending-domains", { include_unverified: true }, { signal }).then((r) => r.data ?? []), [], { key: ["surveys", "domains", "all"] });
+  const clean = domain.trim().toLowerCase();
+  const valid = DOMAIN_RE.test(clean);
+
+  const verify = useG8Mutation(async (): Promise<Record<string, unknown>> => (await g8Post<Record<string, unknown>>("/feedback/sending-domains/verify", { domain: clean })).data ?? {}, {
+    onSuccess: (data) => { setConfirm(false); setResult({ domain: clean, data }); setDomain(""); },
+    invalidates: [["surveys", "domains"]],
+  });
+  const check = useG8Mutation(async (d: string) => {
+    setChecking(d);
+    try {
+      return { domain: d, data: (await g8Get<Record<string, unknown>>("/feedback/sending-domains/status", { domain: d })).data ?? {} };
+    } finally {
+      setChecking(null);
+    }
+  }, { onSuccess: (r) => setResult(r), invalidates: [["surveys", "domains"]] });
+
+  const rows = domains.data ?? [];
+  return (
+    <div className="grid gap-4">
+      <SectionCard title="Sending domains" description="A survey email must come from an address on a verified domain.">
+        {domains.error ? <ApiError error={domains.error} title="Could not load sending domains" onRetry={() => void domains.refetch()} /> : domains.loading && !domains.data ? <Skeleton className="h-16 w-full" aria-busy="true" /> : rows.length === 0 ? (
+          <EmptyState icon={<Globe className="size-8" />} title="No sending domains yet" description="Verify a domain below, publish its DNS records, then check its status." />
+        ) : (
+          <ul className="grid gap-2">
+            {rows.map((d) => (
+              <li key={d.id} className="flex flex-wrap items-center justify-between gap-2 rounded-md border p-3 text-sm">
+                <span className="font-medium">{d.domain}</span>
+                <span className="flex items-center gap-2">
+                  <StatusPill tone={TONE[d.status]}>{LABEL[d.status]}</StatusPill>
+                  {d.status !== "verified" ? <Button size="sm" variant="outline" aria-label={`Check status of ${d.domain}`} loading={checking === d.domain} disabled={checking !== null} onClick={() => void check.mutate(d.domain)}><RefreshCw className="size-4" />Check status</Button> : null}
+                </span>
+              </li>
+            ))}
+          </ul>
+        )}
+        {check.error ? <div className="mt-2"><ApiError error={check.error} title="Could not check the domain" /></div> : null}
+      </SectionCard>
+      <SectionCard title="Verify a domain" description="Starts verification and shows the DNS records to publish at your DNS provider.">
+        <form className="flex flex-wrap items-end gap-2" onSubmit={(e) => { e.preventDefault(); if (valid) setConfirm(true); }}>
+          <div className="min-w-64 flex-1"><Label htmlFor="g8-svd-domain" className="mb-1">Domain</Label><Input id="g8-svd-domain" value={domain} placeholder="feedback.yourcompany.com" onChange={(e) => setDomain(e.target.value)} /></div>
+          <Button type="submit" disabled={!valid}>Verify domain</Button>
+        </form>
+        {domain.trim() && !valid ? <p role="alert" className="text-error mt-1 text-xs">Enter a domain such as feedback.yourcompany.com, without http:// or an address.</p> : null}
+      </SectionCard>
+      {result ? <SectionCard title={`Result for ${result.domain}`}><Payload data={result.data} /></SectionCard> : null}
+      <ConfirmSpendDialog
+        open={confirm}
+        tier="external"
+        title={`Start verifying ${clean}?`}
+        description={<><p>This registers the domain for survey email and returns DNS records to publish. It does not send any mail. Running it again re-reads the records.</p>{verify.error ? <ApiError error={verify.error} title="Could not start verification" /> : null}</>}
+        confirmLabel="Verify"
+        confirming={verify.loading}
+        onCancel={() => setConfirm(false)}
+        onConfirm={() => void verify.mutate(undefined)}
+      />
+    </div>
+  );
+}

package/blocks/surveys/components/survey-form.tsx

@@ -0,0 +1,126 @@
+"use client";
+
+/**
+ * SurveyForm: create a survey (name, type, question, channel, comment capture, thank-you line, optional scale) or edit one.
+ *
+ * SDK operations, in order:
+ *   1. getSurvey (GET /feedback/surveys/{survey_id})     read   edit only: the FULL record is read before the form shows
+ *   2. createSurvey (POST /feedback/surveys)             write  a survey that is open but sends nothing until you send it
+ *   3. updateSurvey (PATCH /feedback/surveys/{survey_id}) write name, question, thank-you line and channel; only changed fields
+ * The type, scale and comment mode are fixed at creation (the API's update takes none of them); to change one, create a
+ * new survey. After a save the survey's cache entries and the survey list are refreshed, so reopening the form shows
+ * what was saved. Nothing here reaches people: sending is SurveySend's job, behind a confirmation.
+ */
+
+import { useState } from "react";
+import { Button, Input, Label, Skeleton, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useBrand } from "@/g8/hooks/use-brand";
+import { COMMENT_MODES, DELIVERY_CHANNELS, SURVEY_TYPES, channelLabel, scaleOf, surveyDiff, typeLabel } from "../lib/surveys-types";
+import type { CommentMode, DeliveryChannel, Survey, SurveyType } from "../lib/surveys-types";
+
+export interface SurveyFormProps {
+  /** Edit this survey; omit to create a new one. */
+  survey?: Survey;
+  onSaved: (survey: Survey) => void;
+  onCancel?: () => void;
+}
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm disabled:opacity-50";
+
+/** Edit mode reads the full survey first: a list row may omit fields, and saving a form seeded from it would blank them. */
+export function SurveyForm({ survey, onSaved, onCancel }: SurveyFormProps) {
+  const full = useG8Query(
+    (signal) => g8Get<Survey>(`/feedback/surveys/${encodeURIComponent(survey!.id)}`, {}, { signal }).then((r) => r.data),
+    [survey?.id],
+    { enabled: Boolean(survey), key: ["surveys", "detail", survey?.id ?? ""], placeholderData: survey },
+  );
+  if (!survey) return <SurveyFields onSaved={onSaved} onCancel={onCancel} />;
+  if (full.error && (!full.data || full.isPlaceholderData)) return <ApiError error={full.error} title="Could not load this survey" onRetry={() => void full.refetch()} />;
+  if (!full.data || full.isPlaceholderData || full.data.id !== survey.id) return <Skeleton className="h-40 w-full" aria-label="Loading survey" />;
+  return <SurveyFields key={full.data.id} survey={full.data} onSaved={onSaved} onCancel={onCancel} />;
+}
+
+function SurveyFields({ survey, onSaved, onCancel }: SurveyFormProps) {
+  const brand = useBrand();
+  const editing = Boolean(survey);
+  const [name, setName] = useState(survey?.name ?? "");
+  const [type, setType] = useState<SurveyType>(survey?.type === "csat" ? "csat" : "nps");
+  const [question, setQuestion] = useState(survey?.question_text ?? "");
+  const [thanks, setThanks] = useState(survey?.thank_you_copy ?? "");
+  const [channel, setChannel] = useState<DeliveryChannel>((survey?.delivery_channel as DeliveryChannel) ?? "email");
+  const [comment, setComment] = useState<CommentMode>("none");
+  const defaults = scaleOf(type);
+  const [min, setMin] = useState<string>("");
+  const [max, setMax] = useState<string>("");
+  const lo = min === "" ? defaults.min : Number(min);
+  const hi = max === "" ? defaults.max : Number(max);
+  const scaleOk = Number.isInteger(lo) && Number.isInteger(hi) && lo < hi;
+  const suggestion = type === "nps" ? `How likely are you to recommend ${brand.name} to a friend or colleague?` : "How satisfied are you with your experience?";
+  const valid = name.trim() !== "" && (editing ? question.trim() !== "" : scaleOk);
+
+  const save = useG8Mutation(async (): Promise<Survey> => {
+    if (survey) {
+      const diff = surveyDiff(survey, { name, question_text: question, thank_you_copy: thanks, delivery_channel: channel });
+      if (Object.keys(diff).length === 0) return survey;
+      return (await g8Patch<Survey>(`/feedback/surveys/${encodeURIComponent(survey.id)}`, diff)).data;
+    }
+    const body: Record<string, unknown> = { name: name.trim(), type, question_text: question.trim() || suggestion, delivery_channel: channel, comment_mode: comment };
+    if (thanks.trim()) body.thank_you_copy = thanks.trim();
+    if (lo !== defaults.min) body.scale_min = lo;
+    if (hi !== defaults.max) body.scale_max = hi;
+    return (await g8Post<Survey>("/feedback/surveys", body)).data;
+  }, { onSuccess: onSaved, invalidates: (saved) => [["surveys", "list"], ["surveys", "detail", saved.id], ["surveys", "summary"]] });
+
+  return (
+    <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (valid) void save.mutate(undefined); }}>
+      <div><Label htmlFor="g8-sv-name" className="mb-1">Name</Label><Input id="g8-sv-name" value={name} onChange={(e) => setName(e.target.value)} placeholder="Quarterly relationship NPS" /></div>
+      <div className="grid gap-3 sm:grid-cols-2">
+        <div>
+          <Label htmlFor="g8-sv-type" className="mb-1">Survey type</Label>
+          <select id="g8-sv-type" className={SELECT} value={type} disabled={editing} onChange={(e) => { setType(e.target.value as SurveyType); setMin(""); setMax(""); }}>
+            {SURVEY_TYPES.map((t) => <option key={t.value} value={t.value}>{t.label}</option>)}
+          </select>
+          <p className="text-muted-foreground mt-1 text-xs">{editing ? `${typeLabel({ type })} is fixed once a survey exists.` : SURVEY_TYPES.find((t) => t.value === type)?.hint}</p>
+        </div>
+        <div>
+          <Label htmlFor="g8-sv-channel" className="mb-1">Where it is shown</Label>
+          <select id="g8-sv-channel" className={SELECT} value={channel} onChange={(e) => setChannel(e.target.value as DeliveryChannel)}>
+            {DELIVERY_CHANNELS.map((c) => <option key={c.value} value={c.value}>{c.label}</option>)}
+          </select>
+        </div>
+      </div>
+      <div>
+        <Label htmlFor="g8-sv-question" className="mb-1">Question</Label>
+        <Textarea id="g8-sv-question" rows={2} value={question} placeholder={editing ? undefined : suggestion} onChange={(e) => setQuestion(e.target.value)} />
+        {!editing ? <p className="text-muted-foreground mt-1 text-xs">Left blank, the standard {typeLabel({ type })} question above is used.</p> : null}
+      </div>
+      <div><Label htmlFor="g8-sv-thanks" className="mb-1">Thank-you line (optional)</Label><Textarea id="g8-sv-thanks" rows={2} value={thanks} onChange={(e) => setThanks(e.target.value)} /></div>
+      {editing ? (
+        <p className="text-muted-foreground text-sm">
+          Answers are scored {survey!.scale_min} to {survey!.scale_max}. Comment capture ({COMMENT_MODES.find((m) => m.value === survey!.comment_mode)?.label ?? "score only"}) and the scale are fixed once a survey exists; create a new survey to change them. Shown through: {channelLabel(survey!.delivery_channel)}.
+        </p>
+      ) : (
+        <div className="grid gap-3 sm:grid-cols-3">
+          <div>
+            <Label htmlFor="g8-sv-comment" className="mb-1">Comments</Label>
+            <select id="g8-sv-comment" className={SELECT} value={comment} onChange={(e) => setComment(e.target.value as CommentMode)}>
+              {COMMENT_MODES.map((m) => <option key={m.value} value={m.value}>{m.label}</option>)}
+            </select>
+          </div>
+          <div><Label htmlFor="g8-sv-min" className="mb-1">Lowest score</Label><Input id="g8-sv-min" type="number" value={min} placeholder={String(defaults.min)} onChange={(e) => setMin(e.target.value)} /></div>
+          <div><Label htmlFor="g8-sv-max" className="mb-1">Highest score</Label><Input id="g8-sv-max" type="number" value={max} placeholder={String(defaults.max)} onChange={(e) => setMax(e.target.value)} /></div>
+          {!scaleOk ? <p role="alert" className="text-error text-xs sm:col-span-3">The lowest score must be a whole number below the highest.</p> : null}
+        </div>
+      )}
+      {save.error ? <ApiError error={save.error} title="Could not save the survey" /> : null}
+      <div className="flex gap-2">
+        <Button type="submit" loading={save.loading} disabled={!valid}>{editing ? "Save changes" : "Create survey"}</Button>
+        {onCancel ? <Button type="button" variant="outline" onClick={onCancel}>Cancel</Button> : null}
+      </div>
+    </form>
+  );
+}

package/blocks/surveys/components/survey-responses.tsx

@@ -0,0 +1,145 @@
+"use client";
+
+/**
+ * SurveyResponses: every answer to one survey, with search, a band filter, a detail sheet per answer and a CSV export.
+ *
+ * SDK operations, in order:
+ *   1. getSurveyResponses (GET /feedback/surveys/{survey_id}/responses)                   read   contact answers (one unpaged read: the API returns every answer)
+ *   2. getSurveyAppUserResponses (GET /feedback/surveys/{survey_id}/app-user-responses)   read   answers from your own team through the in-app widget
+ * The export is built in the browser from the rows on screen (filters applied): the API has no export endpoint.
+ * Nothing here writes or reaches anyone.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Download } from "lucide-react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import type { Tone } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { plural } from "@/g8/lib/plural";
+import { bandOf, downloadText, fullName, isNps, responsesCsv, slugName, when } from "../lib/surveys-types";
+import type { AppUserResponseRow, ResponseRow, Survey } from "../lib/surveys-types";
+
+export interface SurveyResponsesProps {
+  survey: Pick<Survey, "id" | "type" | "name">;
+  /** Render a link to the person behind an answer (for example to your contact page). */
+  renderContact?: (row: ResponseRow) => ReactNode;
+}
+
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+const BAND_TONE: Record<string, Tone> = { promoter: "positive", satisfied: "positive", passive: "neutral", neutral: "neutral", detractor: "negative", dissatisfied: "negative" };
+
+export function SurveyResponses({ survey, renderContact }: SurveyResponsesProps) {
+  const [who, setWho] = useState<"contacts" | "team">("contacts");
+  const [search, setSearch] = useState("");
+  const [band, setBand] = useState("");
+  const [open, setOpen] = useState<ResponseRow | null>(null);
+  const nps = isNps(survey);
+
+  const contacts = useG8Query((signal) => g8Get<{ responses?: ResponseRow[] }>(`/feedback/surveys/${encodeURIComponent(survey.id)}/responses`, {}, { signal }).then((r) => r.data?.responses ?? []), [survey.id], { key: ["surveys", "responses", survey.id] });
+  const team = useG8Query((signal) => g8Get<{ responses?: AppUserResponseRow[] }>(`/feedback/surveys/${encodeURIComponent(survey.id)}/app-user-responses`, {}, { signal }).then((r) => r.data?.responses ?? []), [survey.id], { key: ["surveys", "app-responses", survey.id], enabled: who === "team" });
+
+  const q = search.trim().toLowerCase();
+  const rows = (contacts.data ?? [])
+    .filter((r) => (!band || bandOf(survey.type, r.score, r.classification) === band) && (!q || `${fullName(r)} ${r.comment ?? ""}`.toLowerCase().includes(q)))
+    .sort((a, b) => (b.responded_at ?? "").localeCompare(a.responded_at ?? ""));
+  const bands = nps ? ["promoter", "passive", "detractor"] : ["satisfied", "neutral", "dissatisfied"];
+
+  const header = (
+    <Toolbar
+      search={who === "contacts" ? { value: search, onChange: setSearch, placeholder: "Search answers" } : undefined}
+      filters={(
+        <>
+          <select aria-label="Whose answers" className={SELECT} value={who} onChange={(e) => setWho(e.target.value as "contacts" | "team")}>
+            <option value="contacts">Contacts</option><option value="team">Your team (in-app)</option>
+          </select>
+          {who === "contacts" ? (
+            <select aria-label="Answer band" className={SELECT} value={band} onChange={(e) => setBand(e.target.value)}>
+              <option value="">All answers</option>{bands.map((b) => <option key={b} value={b}>{b[0].toUpperCase() + b.slice(1)}s</option>)}
+            </select>
+          ) : null}
+        </>
+      )}
+      actions={who === "contacts" ? <Button size="sm" variant="outline" disabled={rows.length === 0} onClick={() => downloadText(`${slugName(survey.name)}-responses.csv`, responsesCsv(survey.type, rows))}><Download className="size-4" />Export {plural(rows.length, "answer")} (CSV)</Button> : undefined}
+    />
+  );
+
+  if (who === "team") {
+    const t = team.data ?? [];
+    return (
+      <div className="grid gap-3">
+        {header}
+        {team.error ? <ApiError error={team.error} title="Could not load team answers" onRetry={() => void team.refetch()} /> : team.loading && !team.data ? <Skeleton className="h-20 w-full" aria-busy="true" /> : t.length === 0 ? (
+          <EmptyState title="No in-app answers" description="Answers from signed-in team members appear here when the survey is shown in-app." />
+        ) : (
+          <ul className="grid gap-2">{t.map((r, i) => (
+            <li key={`${r.app_user_id}:${i}`} className="rounded-md border p-3 text-sm">
+              <p className="font-medium">Score {r.score} <span className="text-muted-foreground text-xs font-normal">{when(r.responded_at)}</span></p>
+              {r.comment ? <p className="mt-1 whitespace-pre-wrap">{r.comment}</p> : null}
+            </li>
+          ))}</ul>
+        )}
+      </div>
+    );
+  }
+  return (
+    <div className="grid gap-3">
+      {header}
+      {contacts.error ? <ApiError error={contacts.error} title="Could not load the answers" onRetry={() => void contacts.refetch()} /> : contacts.loading && !contacts.data ? (
+        <div aria-busy="true" className="grid gap-2"><Skeleton className="h-12 w-full" /><Skeleton className="h-12 w-full" /><Skeleton className="h-12 w-full" /></div>
+      ) : (contacts.data ?? []).length === 0 ? <EmptyState title="No answers yet" description="Send the survey, or wait for people to answer." /> : rows.length === 0 ? (
+        <EmptyState title="No answers match" description="Try another search or band." />
+      ) : (
+        <>
+          <p role="status" className="text-muted-foreground text-xs">{rows.length === (contacts.data ?? []).length ? `All ${plural(rows.length, "answer")}` : `${rows.length.toLocaleString()} of ${plural((contacts.data ?? []).length, "answer")}`}</p>
+          <ul className="grid gap-2">
+            {rows.map((r) => {
+              const b = bandOf(survey.type, r.score, r.classification);
+              return (
+                <li key={r.contact_id} className="flex items-center justify-between gap-3 rounded-md border p-3">
+                  <button type="button" className="min-w-0 flex-1 text-left" aria-label={`Open answer from ${fullName(r)}`} onClick={() => setOpen(r)}>
+                    <span className="block truncate font-medium">{fullName(r)} <span className="text-muted-foreground font-normal">scored {r.score}</span></span>
+                    <span className="text-muted-foreground block truncate text-xs">{r.comment || "No comment"} · {when(r.responded_at)}</span>
+                  </button>
+                  <StatusPill tone={BAND_TONE[b] ?? "neutral"}>{b}</StatusPill>
+                </li>
+              );
+            })}
+          </ul>
+        </>
+      )}
+      <FormSheet open={open !== null} onOpenChange={(o) => { if (!o) setOpen(null); }} title={open ? fullName(open) : "Answer"} description={`Answer to ${survey.name}`}>
+        {open ? (
+          <div className="grid gap-4">
+            <KeyValueList
+              columns={2}
+              items={[
+                { label: "Score", value: String(open.score) },
+                { label: "Band", value: bandOf(survey.type, open.score, open.classification) },
+                { label: "Answered", value: when(open.responded_at) },
+                { label: "Channel", value: open.channel || "" },
+                { label: "Times answered", value: String(open.response_count ?? 1) },
+                { label: "Trend", value: open.trend || "" },
+                { label: "Comment", value: open.comment || "", wide: true },
+              ]}
+            />
+            {open.history && open.history.length > 1 ? (
+              <div>
+                <h3 className="mb-1 text-sm font-medium">Earlier scores</h3>
+                <ul className="grid gap-1 text-sm">{open.history.map((h, i) => <li key={i}>{h.score} <span className="text-muted-foreground text-xs">{when(h.responded_at)}</span></li>)}</ul>
+              </div>
+            ) : null}
+            {renderContact?.(open)}
+          </div>
+        ) : null}
+      </FormSheet>
+    </div>
+  );
+}