@graph8/sdk 0.370.0 → 0.374.0

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

@@ -0,0 +1,162 @@
+"use client";
+
+/**
+ * SurveySend: send a survey to an audience list now or later, then follow the send; the history of earlier sends sits below.
+ *
+ * SDK operations, in order:
+ *   1. listSurveySendingDomains (GET /feedback/sending-domains)   read      the domains a sender address may use
+ *   2. listLists (GET /lists), through ListSelect                  read      the audience
+ *   3. sendSurvey (POST /feedback/surveys/{survey_id}/send)       external  REAL MAIL to real people: ConfirmSpendDialog, sized from the chosen list
+ *   4. getSurveySend (GET /feedback/sends/{send_id})              read      polled after the send is accepted
+ * The confirmation shows the audience size read from the list itself ("up to N": people who cannot be reached, such as
+ * unsubscribed or suppressed ones, are dropped by the API). An in-app survey is not sent: it shows inside your product.
+ */
+
+import { useRef, useState } from "react";
+import { Send } 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 { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { ListSelect } from "@/g8/crm/components/list-select";
+import type { ListSelectOption } from "@/g8/crm/components/list-select";
+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 { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { useBrand } from "@/g8/hooks/use-brand";
+import { plural } from "@/g8/lib/plural";
+import { EMAIL_RE, SEND_CHANNELS, audienceSize, domainOf, scheduleIso, when } from "../lib/surveys-types";
+import type { SendAccepted, SendChannel, SendDetail, SendingDomain, Survey } from "../lib/surveys-types";
+import { SurveySendHistory } from "./survey-send-history";
+
+export interface SurveySendProps {
+  survey: Survey;
+  /** Called after a send is accepted, so a parent can refresh its numbers. */
+  onSent?: (accepted: SendAccepted) => void;
+}
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm disabled:opacity-50";
+const SETTLED = new Set(["sent", "failed", "scheduled"]);
+
+export function SurveySend({ survey, onSent }: SurveySendProps) {
+  const brand = useBrand();
+  const [list, setList] = useState<ListSelectOption | null>(null);
+  const [channel, setChannel] = useState<SendChannel>(survey.delivery_channel === "bridge" ? "bridge" : "email");
+  const [senderEmail, setSenderEmail] = useState("");
+  const [senderName, setSenderName] = useState("");
+  const [replyTo, setReplyTo] = useState("");
+  const [subject, setSubject] = useState(survey.name);
+  const [at, setAt] = useState("");
+  const [confirm, setConfirm] = useState(false);
+  const [accepted, setAccepted] = useState<SendAccepted | null>(null);
+  const [historyKey, setHistoryKey] = useState(0);
+  // The poll reads the id from a ref: start() runs its first tick before React re-renders with the new state.
+  const sendId = useRef<number | null>(null);
+
+  const domains = useG8Query((signal) => g8Get<SendingDomain[]>("/feedback/sending-domains", {}, { signal }).then((r) => r.data ?? []), [], { key: ["surveys", "domains", "verified"] });
+  const status = useJobPoll<SendDetail>((signal) => g8Get<SendDetail>(`/feedback/sends/${sendId.current}`, {}, { signal }).then((r) => r.data), {
+    isTerminal: (s) => SETTLED.has(s.status),
+    enabled: false,
+    onDone: () => setHistoryKey((n) => n + 1),
+  });
+
+  const send = useG8Mutation(async (): Promise<SendAccepted> => {
+    const body: Record<string, unknown> = { audience_ref: String(list!.id), channel };
+    if (channel === "email") {
+      body.sender_email = senderEmail.trim();
+      body.subject = subject.trim();
+      if (senderName.trim()) body.sender_name = senderName.trim();
+      if (replyTo.trim()) body.reply_to = replyTo.trim();
+    }
+    const when_ = scheduleIso(at);
+    if (when_) body.scheduled_at = when_;
+    return (await g8Post<SendAccepted>(`/feedback/surveys/${encodeURIComponent(survey.id)}/send`, body)).data;
+  }, {
+    onSuccess: (r) => { sendId.current = r.send_id; setConfirm(false); setAccepted(r); setHistoryKey((n) => n + 1); onSent?.(r); status.start(); },
+    invalidates: [["surveys", "summary"]],
+  });
+
+  if (survey.delivery_channel === "in_app") {
+    return <EmptyState title="This survey is shown inside your product" description={`An in-app survey is not sent: the widget in ${brand.linkLabel} shows it to signed-in team members, and their answers appear under Responses. Change the survey to email or chat to send it to contacts.`} />;
+  }
+  const verified = (domains.data ?? []).filter((d) => d.status === "verified");
+  const domainOk = channel === "bridge" || (EMAIL_RE.test(senderEmail.trim()) && verified.some((d) => d.domain === domainOf(senderEmail.trim())));
+  const emailOk = channel === "bridge" || (domainOk && subject.trim() !== "" && (replyTo.trim() === "" || EMAIL_RE.test(replyTo.trim())));
+  const ready = Boolean(list) && emailOk && survey.is_active && (at === "" || (scheduleIso(at) !== undefined && new Date(at).getTime() > Date.now()));
+  const size = audienceSize(list);
+  const sendsLater = Boolean(scheduleIso(at));
+
+  return (
+    <div className="grid gap-4">
+      {!survey.is_active ? <p role="note" className="text-warning-foreground text-sm">This survey is closed. Reopen it before sending.</p> : null}
+      <SectionCard title="Send this survey" description="Choose who gets it. Nothing is sent until you confirm.">
+        <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (ready) setConfirm(true); }}>
+          <div>
+            <Label htmlFor="g8-svs-list" className="mb-1">Audience list</Label>
+            <ListSelect id="g8-svs-list" label="Audience list" emptyOption="Choose a list" value={list?.id ?? ""} valueLabel={list?.title} selectClassName={SELECT} onChange={setList} />
+            {list && size === null ? <p className="text-muted-foreground mt-1 text-xs">The list does not report its size; the confirmation says so.</p> : null}
+          </div>
+          <div>
+            <Label htmlFor="g8-svs-channel" className="mb-1">Send as</Label>
+            <select id="g8-svs-channel" className={SELECT} value={channel} onChange={(e) => setChannel(e.target.value as SendChannel)}>
+              {SEND_CHANNELS.map((c) => <option key={c.value} value={c.value}>{c.label}</option>)}
+            </select>
+          </div>
+          {channel === "email" ? (
+            <>
+              <div className="grid gap-3 sm:grid-cols-2">
+                <div>
+                  <Label htmlFor="g8-svs-from" className="mb-1">From address</Label>
+                  <Input id="g8-svs-from" type="email" value={senderEmail} placeholder={verified[0] ? `survey@${verified[0].domain}` : "survey@yourdomain.com"} onChange={(e) => setSenderEmail(e.target.value)} />
+                </div>
+                <div><Label htmlFor="g8-svs-name" className="mb-1">From name (optional)</Label><Input id="g8-svs-name" value={senderName} onChange={(e) => setSenderName(e.target.value)} /></div>
+              </div>
+              {domains.loading && !domains.data ? <Skeleton className="h-4 w-48" /> : domains.error ? <ApiError error={domains.error} title="Could not load sending domains" onRetry={() => void domains.refetch()} /> : verified.length === 0 ? (
+                <p role="note" className="text-warning-foreground text-xs">No sending domain is verified yet. Verify one under Sending domains before sending email.</p>
+              ) : senderEmail.trim() && !domainOk ? (
+                <p role="alert" className="text-error text-xs">The address must be on a verified domain: {verified.map((d) => d.domain).join(", ")}.</p>
+              ) : <p className="text-muted-foreground text-xs">Verified domains: {verified.map((d) => d.domain).join(", ")}.</p>}
+              <div className="grid gap-3 sm:grid-cols-2">
+                <div><Label htmlFor="g8-svs-subject" className="mb-1">Subject</Label><Input id="g8-svs-subject" value={subject} onChange={(e) => setSubject(e.target.value)} /></div>
+                <div><Label htmlFor="g8-svs-reply" className="mb-1">Reply-to (optional)</Label><Input id="g8-svs-reply" type="email" value={replyTo} onChange={(e) => setReplyTo(e.target.value)} /></div>
+              </div>
+            </>
+          ) : null}
+          <div className="sm:w-64"><Label htmlFor="g8-svs-at" className="mb-1">Send later (optional)</Label><Input id="g8-svs-at" type="datetime-local" value={at} onChange={(e) => setAt(e.target.value)} /></div>
+          {at !== "" && scheduleIso(at) !== undefined && new Date(at).getTime() <= Date.now() ? <p role="alert" className="text-error text-xs">Pick a time in the future, or clear it to send now.</p> : null}
+          <div><Button type="submit" disabled={!ready}><Send className="size-4" />{sendsLater ? "Schedule send" : "Send survey"}</Button></div>
+        </form>
+      </SectionCard>
+      {accepted ? (
+        <SectionCard title="Last send">
+          <p className="flex flex-wrap items-center gap-2 text-sm" role="status">
+            <StatusPill tone={status.status?.status === "failed" ? "negative" : status.status?.status === "sent" ? "positive" : "info"}>{status.status?.status ?? accepted.status}</StatusPill>
+            {plural(status.status?.recipient_count ?? accepted.recipient_count, "recipient")}
+            {status.status?.scheduled_at ? `, scheduled for ${when(status.status.scheduled_at)}` : ""}
+          </p>
+          {status.error ? <ApiError error={status.error} title="Could not read the send status" onRetry={() => status.start()} /> : null}
+        </SectionCard>
+      ) : null}
+      <SurveySendHistory key={historyKey} surveyId={survey.id} />
+      <ConfirmSpendDialog
+        open={confirm}
+        tier="external"
+        title={`${sendsLater ? "Schedule" : "Send"} "${survey.name}" to ${list?.title ?? "this list"}?`}
+        recipients={size ?? undefined}
+        description={(
+          <>
+            <p>{size === null ? "The list does not report its size." : `Up to ${plural(size, "person", "people")} will be asked.`} People who unsubscribed or are suppressed are skipped. {sendsLater ? `It goes out on ${when(scheduleIso(at))}.` : "It goes out now and cannot be recalled."}</p>
+            {send.error ? <ApiError error={send.error} title="The send was refused" /> : null}
+          </>
+        )}
+        confirmLabel={sendsLater ? "Schedule" : "Send"}
+        confirming={send.loading}
+        onCancel={() => setConfirm(false)}
+        onConfirm={() => void send.mutate(undefined)}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,166 @@
+"use client";
+
+/**
+ * SurveyTriggers: automatic sends for one survey. A trigger mails an audience on a schedule, when someone joins a list, or
+ * when a record reaches a stage, without anyone pressing Send.
+ *
+ * SDK operations, in order:
+ *   1. listSurveyTriggers (GET /feedback/surveys/{survey_id}/triggers)            read
+ *   2. listSurveySendingDomains (GET /feedback/sending-domains)                    read         the sender must be on a verified domain
+ *   3. listLists (GET /lists), through ListSelect                                  read
+ *   4. createSurveyTrigger (POST /feedback/surveys/{survey_id}/triggers)          write        confirmed here (external): it will mail people on its own
+ *   5. deleteSurveyTrigger (DELETE /feedback/surveys/{survey_id}/triggers/{id})   destructive  ConfirmSpendDialog
+ * The API has no trigger update or pause: to change one, delete it and create it again.
+ */
+
+import { useState } from "react";
+import { Plus, Trash2, Zap } 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 { FormSheet } from "@/g8/components/screen/form-sheet";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useAllLists } from "@/g8/crm/hooks/use-all-lists";
+import { ListSelect } from "@/g8/crm/components/list-select";
+import type { ListSelectOption } from "@/g8/crm/components/list-select";
+import { g8Delete, g8Get, g8Post } 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 { CADENCE_DAYS, EMAIL_RE, TRIGGER_KINDS, audienceSize, domainOf } from "../lib/surveys-types";
+import type { SendingDomain, Survey, Trigger, TriggerKind } from "../lib/surveys-types";
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm";
+const kindLabel = (k: string): string => TRIGGER_KINDS.find((t) => t.value === k)?.label ?? k;
+
+export function SurveyTriggers({ survey }: { survey: Survey }) {
+  const [creating, setCreating] = useState(false);
+  const [confirmNew, setConfirmNew] = useState(false);
+  const [toDelete, setToDelete] = useState<Trigger | null>(null);
+  const [kind, setKind] = useState<TriggerKind>("scheduled");
+  const [list, setList] = useState<ListSelectOption | null>(null);
+  const [cadence, setCadence] = useState<number>(90);
+  const [stage, setStage] = useState("");
+  const [senderEmail, setSenderEmail] = useState("");
+  const [senderName, setSenderName] = useState("");
+  const [replyTo, setReplyTo] = useState("");
+  const [subject, setSubject] = useState(survey.name);
+
+  const triggers = useG8Query((signal) => g8Get<Trigger[]>(`/feedback/surveys/${encodeURIComponent(survey.id)}/triggers`, {}, { signal }).then((r) => r.data ?? []), [survey.id], { key: ["surveys", "triggers", survey.id] });
+  const domains = useG8Query((signal) => g8Get<SendingDomain[]>("/feedback/sending-domains", {}, { signal }).then((r) => r.data ?? []), [], { key: ["surveys", "domains", "verified"], enabled: creating });
+
+  const lists = useAllLists([]);
+  const needsList = kind !== "stage_entry";
+  const verified = (domains.data ?? []).filter((d) => d.status === "verified");
+  const senderOk = EMAIL_RE.test(senderEmail.trim()) && verified.some((d) => d.domain === domainOf(senderEmail.trim()));
+  const valid = senderOk && subject.trim() !== "" && (!needsList || Boolean(list)) && (kind !== "stage_entry" || stage.trim() !== "") && (replyTo.trim() === "" || EMAIL_RE.test(replyTo.trim()));
+  const reset = (): void => { setCreating(false); setConfirmNew(false); setList(null); setStage(""); setSenderEmail(""); setSenderName(""); setReplyTo(""); setSubject(survey.name); };
+
+  const create = useG8Mutation(async (): Promise<Trigger> => {
+    // Only the fields this kind uses: a stage value on a scheduled trigger would be stored and misread later.
+    const body: Record<string, unknown> = { trigger_kind: kind, sender_email: senderEmail.trim(), subject: subject.trim() };
+    if (senderName.trim()) body.sender_name = senderName.trim();
+    if (replyTo.trim()) body.reply_to = replyTo.trim();
+    if (needsList) body.audience_ref = String(list!.id);
+    if (kind === "scheduled") body.cadence_days = cadence;
+    if (kind === "stage_entry") body.stage_value = stage.trim();
+    return (await g8Post<Trigger>(`/feedback/surveys/${encodeURIComponent(survey.id)}/triggers`, body)).data;
+  }, { onSuccess: reset, invalidates: [["surveys", "triggers", survey.id]] });
+  const remove = useG8Mutation((t: Trigger) => g8Delete(`/feedback/surveys/${encodeURIComponent(survey.id)}/triggers/${encodeURIComponent(t.id)}`), {
+    onSuccess: () => setToDelete(null),
+    invalidates: [["surveys", "triggers", survey.id]],
+  });
+
+  const rows = triggers.data ?? [];
+  const size = audienceSize(list);
+  return (
+    <SectionCard
+      title="Automatic sends"
+      description="Mail this survey without pressing Send."
+      actions={<Button size="sm" onClick={() => setCreating(true)} disabled={survey.delivery_channel !== "email"}><Plus className="size-4" />New automatic send</Button>}
+    >
+      {survey.delivery_channel !== "email" ? <p className="text-muted-foreground mb-2 text-xs">Automatic sends go out by email. Switch this survey to email to add one.</p> : null}
+      {triggers.error ? <ApiError error={triggers.error} title="Could not load automatic sends" onRetry={() => void triggers.refetch()} /> : triggers.loading && !triggers.data ? <Skeleton className="h-16 w-full" aria-busy="true" /> : rows.length === 0 ? (
+        <EmptyState icon={<Zap className="size-8" />} title="No automatic sends" description="Add one to ask a list every 30, 60 or 90 days, or whenever someone joins a list or reaches a stage." />
+      ) : (
+        <ul className="grid gap-2">
+          {rows.map((t) => (
+            <li key={t.id} className="flex flex-wrap items-center justify-between gap-2 rounded-md border p-3 text-sm">
+              <div className="min-w-0">
+                <p className="font-medium">{kindLabel(t.trigger_kind)}{t.cadence_days ? `, every ${plural(t.cadence_days, "day")}` : ""}{t.stage_value ? `: ${t.stage_value}` : ""}</p>
+                <p className="text-muted-foreground truncate text-xs">From {t.sender_email} · {t.subject}{t.audience_ref ? ` · ${lists.items.find((l) => String(l.id) === t.audience_ref)?.title ?? "an audience list"}` : ""}</p>
+              </div>
+              <div className="flex items-center gap-2">
+                <StatusPill tone={t.is_active ? "positive" : "neutral"}>{t.is_active ? "active" : "inactive"}</StatusPill>
+                <Button size="sm" variant="ghost" aria-label={`Remove automatic send ${kindLabel(t.trigger_kind)}`} onClick={() => setToDelete(t)}><Trash2 className="size-4" /></Button>
+              </div>
+            </li>
+          ))}
+        </ul>
+      )}
+      <FormSheet
+        open={creating}
+        onOpenChange={(o) => { if (!o) reset(); else setCreating(true); }}
+        title="New automatic send"
+        description="Once saved, this mails people on its own. You confirm it first."
+        footer={<Button disabled={!valid} onClick={() => setConfirmNew(true)}>Add automatic send</Button>}
+      >
+        <div className="grid gap-3">
+          <div>
+            <Label htmlFor="g8-svt-kind" className="mb-1">When</Label>
+            <select id="g8-svt-kind" className={SELECT} value={kind} onChange={(e) => setKind(e.target.value as TriggerKind)}>
+              {TRIGGER_KINDS.map((k) => <option key={k.value} value={k.value}>{k.label}</option>)}
+            </select>
+            <p className="text-muted-foreground mt-1 text-xs">{TRIGGER_KINDS.find((k) => k.value === kind)?.hint}</p>
+          </div>
+          {needsList ? (
+            <div>
+              <Label htmlFor="g8-svt-list" className="mb-1">{kind === "list_entry" ? "Watched list" : "Audience list"}</Label>
+              <ListSelect id="g8-svt-list" label={kind === "list_entry" ? "Watched list" : "Audience list"} emptyOption="Choose a list" value={list?.id ?? ""} valueLabel={list?.title} selectClassName={SELECT} onChange={setList} />
+            </div>
+          ) : null}
+          {kind === "scheduled" ? (
+            <div>
+              <Label htmlFor="g8-svt-cadence" className="mb-1">Repeat every</Label>
+              <select id="g8-svt-cadence" className={SELECT} value={cadence} onChange={(e) => setCadence(Number(e.target.value))}>
+                {CADENCE_DAYS.map((d) => <option key={d} value={d}>{d} days</option>)}
+              </select>
+            </div>
+          ) : null}
+          {kind === "stage_entry" ? <div><Label htmlFor="g8-svt-stage" className="mb-1">Stage</Label><Input id="g8-svt-stage" value={stage} placeholder="closed-won" onChange={(e) => setStage(e.target.value)} /></div> : null}
+          <div><Label htmlFor="g8-svt-from" className="mb-1">From address</Label><Input id="g8-svt-from" type="email" value={senderEmail} onChange={(e) => setSenderEmail(e.target.value)} /></div>
+          {domains.data && senderEmail.trim() && !senderOk ? <p role="alert" className="text-error text-xs">{verified.length ? `Use an address on a verified domain: ${verified.map((d) => d.domain).join(", ")}.` : "No sending domain is verified yet. Verify one under Sending domains."}</p> : null}
+          <div className="grid gap-3 sm:grid-cols-2">
+            <div><Label htmlFor="g8-svt-name" className="mb-1">From name (optional)</Label><Input id="g8-svt-name" value={senderName} onChange={(e) => setSenderName(e.target.value)} /></div>
+            <div><Label htmlFor="g8-svt-reply" className="mb-1">Reply-to (optional)</Label><Input id="g8-svt-reply" type="email" value={replyTo} onChange={(e) => setReplyTo(e.target.value)} /></div>
+          </div>
+          <div><Label htmlFor="g8-svt-subject" className="mb-1">Subject</Label><Input id="g8-svt-subject" value={subject} onChange={(e) => setSubject(e.target.value)} /></div>
+        </div>
+      </FormSheet>
+      <ConfirmSpendDialog
+        open={confirmNew}
+        tier="external"
+        title={`Add an automatic send for "${survey.name}"?`}
+        recipients={needsList ? (size ?? undefined) : undefined}
+        description={<><p>{kindLabel(kind)}: this survey is emailed from {senderEmail.trim() || "the sender"} without anyone pressing Send.{needsList && size !== null ? ` The list has ${plural(size, "person", "people")} now.` : ""}</p>{create.error ? <ApiError error={create.error} title="The automatic send was refused" /> : null}</>}
+        confirmLabel="Add"
+        confirming={create.loading}
+        onCancel={() => setConfirmNew(false)}
+        onConfirm={() => void create.mutate(undefined)}
+      />
+      <ConfirmSpendDialog
+        open={toDelete !== null}
+        tier="destructive"
+        title={`Remove this automatic send?`}
+        affected={1}
+        description={<><p>{toDelete ? `${kindLabel(toDelete.trigger_kind)} stops. Surveys already sent and their answers stay.` : ""}</p>{remove.error ? <ApiError error={remove.error} title="Could not remove it" /> : null}</>}
+        confirmLabel="Remove"
+        confirming={remove.loading}
+        onCancel={() => setToDelete(null)}
+        onConfirm={() => { if (toDelete) void remove.mutate(toDelete); }}
+      />
+    </SectionCard>
+  );
+}

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 },
+      ]}
+    />
+  );
+}