@graph8/sdk 0.370.0 → 0.374.0

package/blocks/surveys/README.md

@@ -0,0 +1,91 @@
+# surveys
+
+NPS and CSAT surveys: ask customers **one scored question**, read the score, the answers and the trend. A survey is one question
+with a numeric answer (NPS 0 to 10, CSAT 1 to 5) and an optional comment. It is sent to an audience **list** by email or chat
+message, shown **in-app** to your own team, or sent automatically (on a schedule, when someone joins a list, when a record reaches
+a stage). A send reaches real people, so it is tier `external` and is confirmed with the audience size.
+
+## Screens
+
+`SurveysScreen` (`components/surveys-screen.tsx`) is the finished page: list, create, results, answers, send, automatic sends, settings, org overview, sending domains and account lookups.
+
+```tsx
+import { SurveysScreen } from "@/g8/surveys/components/surveys-screen";
+export default function Page() { return <SurveysScreen />; }
+```
+
+Tabs (`?tab=`): **Surveys**, **Overview**, **Sending domains**, **Accounts and people**. Open a survey (`?id=`) for Results, Responses, Send, Automatic sends, Settings and Details; `&view=full` shows it as a full page.
+
+Flows: see every survey with its type, state and channel (search; filter by type, open or closed, channel; the list is complete: the API does not page it), create one, open it to read the score, response rate, split and trend (by day, week or month), read and search its answers (filter by promoter, passive, detractor), open one answer, export the answers on screen as CSV, send it to a list now or later (confirmed with the list's size), add or remove automatic sends (both confirmed), edit the question, thank-you line and channel, **close** it (stops new sends, keeps every answer) and reopen it, delete it (confirmed), verify a sending domain (confirmed, returns the DNS records), read org-wide NPS and CSAT (all contacts or one list), look up one company's NPS and one person's answers. Optional props: `renderRowActions`, `renderDetailActions`, `renderContact`, `extraDetailTabs`, `toolbarActions`.
+
+Parts you can mount alone: `SurveyForm`, `SurveySend`, `SurveySendHistory`, `SurveyTriggers`, `SurveyResults`, `SurveyResponses`, `SendingDomains`, `OrgSummary`, `AccountNps` (pass `companyId` on a company page), `ContactSurveyHistory` (pass `contactId` on a contact page).
+
+## Install
+
+```
+npx @graph8/sdk add surveys
+```
+
+Installs `foundation`, `crm`, `lists` and `pickers` first if missing. Everything lands under `g8/surveys/`.
+
+## Prerequisites (the human must do these)
+
+| Where | What | How to verify |
+|---|---|---|
+| graph8 | A **verified sending domain** for email surveys. Verify one in the Sending domains tab (it returns DNS records), publish them at your DNS provider, then press Check status. | `GET /api/v1/feedback/sending-domains` lists it as `verified`. |
+| The business | An **audience list** of people you may ask. A person picks it and confirms the size; unsubscribed and suppressed contacts are skipped by the API. | The owner can say who is on the list and why. |
+| graph8 key | `surveys:read`, `surveys:write`, `surveys:delete`; `surveys:run` to send or verify a domain (separate from `surveys:write`); `lists:read`. | `g8.api.me.describeCurrentKey()` |
+| Your app | `allowedPrefixes` must include `feedback`, `lists`, `companies`, `contacts`. The survey endpoints live under `/feedback`, not `/surveys`. | The route file lists them. |
+
+## The flow, in order (IDs passed between steps)
+
+1. **Create**: `createSurvey({ name, type: "nps" | "csat", question_text, delivery_channel, comment_mode, thank_you_copy? })` -> **`survey.id`** (a UUID string). `type`, the scale (`scale_min`/`scale_max`) and `comment_mode` are fixed now; `updateSurvey` takes none of them.
+2. **Sender**: `listSurveySendingDomains` -> pick a `verified` domain; the sender address must be on it. A new domain: `verifySurveyDomain({ domain })` then `surveyDomainStatus({ domain })` until verified.
+3. **Audience**: a list id (`listLists`, or build one with the `lists` block) -> **`list.id`**, sent as the string `audience_ref`.
+4. **Send**: `sendSurvey(survey.id, { audience_ref, channel, sender_email, subject, scheduled_at? })` behind `ConfirmSpendDialog` showing the list's size -> **`send_id`**. It answers 202; poll `getSurveySend(send_id)` until `sent`, `failed` or `scheduled`.
+5. **Automate** (optional): `createSurveyTrigger(survey.id, { trigger_kind, sender_email, subject, audience_ref | stage_value, cadence_days })`. `scheduled` needs `audience_ref` + `cadence_days`, `list_entry` needs `audience_ref`, `stage_entry` needs `stage_value`. There is no update: delete and recreate.
+6. **Read**: `getSurveySummary` (score, response rate, split), `getSurveyTrends`, `getSurveyResponses` (every answer), `getSurveyAppUserResponses` (your team, in-app), `getSurveySends` (history), `getSurveyOrgSummary`, `getCompanySurveyNps`, `getContactSurveyHistory`.
+7. **Stop**: `updateSurvey({ is_active: false })` closes it and keeps every answer. `deleteSurvey` removes the survey **and its answers** (confirmed).
+
+## Default decisions (do not ask the human unless marked)
+
+| Decision | Default | Ask? |
+|---|---|---|
+| Survey type | NPS (0 to 10) for relationship feedback, CSAT (1 to 5) for one interaction | no |
+| Question | The standard question for the type, with the brand name | no |
+| Comment capture | Score only (`none`) | no |
+| Delivery channel | Email | no |
+| Which list is asked | None: a person always picks the audience | **yes** |
+| Sending | Never without the audience size and sender domain confirmed | no |
+| Stopping | Close, do not delete | no |
+| Trend bucket | Weekly for one survey, monthly for the org overview | no |
+
+## Operation coverage (21 surveys operations, all used)
+
+Every operation in the `surveys` namespace is reachable from `SurveysScreen`:
+`listSurveys`, `getSurvey`, `createSurvey`, `updateSurvey`, `deleteSurvey`, `sendSurvey`, `getSurveySend`, `getSurveySends`, `createSurveyTrigger`, `listSurveyTriggers`, `deleteSurveyTrigger`, `getSurveySummary`, `getSurveyTrends`, `getSurveyResponses`, `getSurveyAppUserResponses`, `getSurveyOrgSummary`, `getCompanySurveyNps`, `getContactSurveyHistory`, `listSurveySendingDomains`, `verifySurveyDomain`, `surveyDomainStatus`.
+The block also reads `listLists`, `listCompanies` and `listContacts` for its pickers.
+
+## API gaps (what the request asked for that the API does not have)
+
+| Asked for | Reality | What the block does |
+|---|---|---|
+| Several questions, question types, reordering | A survey is **one** question; "type" is only `nps` or `csat`. There is no question list or question endpoint. | Create takes the one question; the type is chosen at creation. |
+| Publish / close | No publish endpoint; `updateSurvey({ is_active })` is the switch. | Close / Reopen buttons. |
+| Edit type, scale, comment mode, template | `UpdateSurveyRequest` takes `name`, `question_text`, `thank_you_copy`, `delivery_channel`, `template_id`, `is_active` only. | Shown read-only with "create a new survey to change it". Templates have no list endpoint, so `template_id` is not offered. |
+| Clear the thank-you line | The API ignores `null` on update; only `""` clears it. | A cleared line is sent as `""`. |
+| Share link and embed code | None. The respondent link is signed per recipient inside the emailed survey; the in-app widget has no embed endpoint. | In-app surveys explain they appear inside the product; email is the way out. |
+| Export responses | No export endpoint. | CSV built in the browser from the answers on screen (formula-safe). |
+| AI generation (questions, summaries) | None for surveys. | Nothing to confirm or bill; no button. |
+| Paging and server filters | `listSurveys`, `getSurveyResponses` and `getSurveySends` take no paging or filter parameters and return everything. | The UI says "All N" and filters client-side; a survey with a very large number of answers is one large read. |
+| Pause or edit an automatic send | Triggers can only be created, listed and deleted. | Delete and recreate. |
+| Respond as a contact (`/surveys/{id}/respond`, `/in-app/pending`) | Browser-session and signed-link surfaces, deliberately not in the developer API. | Out of scope. |
+
+## Things that surprise people
+
+- The endpoints are under **`/feedback`**, not `/surveys` (the in-app router owns `/surveys`). Add `feedback` to the proxy allowlist.
+- Scores are lowercase types (`nps`, `csat`); sending channels are `email` and `bridge` only (`in_app` is a delivery channel for showing, not a send channel).
+- A score is `null` when there are too few answers (the API suppresses it). The UI shows a dash, not 0.
+- `response_rate.rate` is a fraction (0 to 1).
+- A send is dispatched asynchronously: `202` with a `send_id`, then poll. A send scheduled for later stays `scheduled`.
+- `contact_id` on an answer and in the history endpoint is the contact's primary key (the mashup contact id), not the business `CONTACT_ID` key.

package/blocks/surveys/block.json

@@ -0,0 +1,299 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "surveys",
+  "title": "Surveys (NPS and CSAT)",
+  "summary": "Ask customers one scored question (NPS or CSAT): create and edit surveys, close, send to a list with confirmation, automate sends, read scores and answers, export, verify a sending domain.",
+  "features": [
+    "create NPS and CSAT surveys with a question, channel, comment capture and thank-you line",
+    "close a survey (keeps answers) and reopen it, or delete it with confirmation",
+    "send to an audience list now or later, confirmed with the audience size",
+    "automatic sends on a schedule, on list entry or on stage entry",
+    "score, response rate, answer split and trend by day, week or month",
+    "every answer with search, band filter, detail and CSV export",
+    "org-wide NPS and CSAT, account NPS and a person's survey history",
+    "sending domain verification with the DNS records to publish"
+  ],
+  "dependsOn": [
+    "lists",
+    "pickers"
+  ],
+  "operations": [
+    "create_survey_feedback_surveys_post",
+    "create_survey_trigger_feedback_surveys__survey_id__triggers_post",
+    "delete_survey_feedback_surveys__survey_id__delete",
+    "delete_survey_trigger_feedback_surveys__survey_id__triggers__trigger_id__delete",
+    "get_company_survey_nps_feedback_companies__company_id__nps_get",
+    "get_contact_survey_history_feedback_contacts__contact_id__history_get",
+    "get_survey_app_user_responses_feedback_surveys__survey_id__app_user_responses_get",
+    "get_survey_feedback_surveys__survey_id__get",
+    "get_survey_org_summary_feedback_org_summary_get",
+    "get_survey_responses_feedback_surveys__survey_id__responses_get",
+    "get_survey_send_feedback_sends__send_id__get",
+    "get_survey_sends_feedback_surveys__survey_id__sends_get",
+    "get_survey_summary_feedback_surveys__survey_id__summary_get",
+    "get_survey_trends_feedback_surveys__survey_id__trends_get",
+    "list_companies_companies_get",
+    "list_contacts_contacts_get",
+    "list_lists_lists_get",
+    "list_survey_sending_domains_feedback_sending_domains_get",
+    "list_survey_triggers_feedback_surveys__survey_id__triggers_get",
+    "list_surveys_feedback_surveys_get",
+    "send_survey_feedback_surveys__survey_id__send_post",
+    "survey_domain_status_feedback_sending_domains_status_get",
+    "update_survey_feedback_surveys__survey_id__patch",
+    "verify_survey_domain_feedback_sending_domains_verify_post"
+  ],
+  "components": [
+    {
+      "name": "SurveysScreen",
+      "file": "components/surveys-screen.tsx",
+      "purpose": "Finished NPS and CSAT workspace: survey list with filters, create, close and reopen, delete, and per-survey results, answers, send, automatic sends and settings; org overview, sending domains and account lookups.",
+      "operations": [
+        "delete_survey_feedback_surveys__survey_id__delete",
+        "list_surveys_feedback_surveys_get",
+        "update_survey_feedback_surveys__survey_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "SurveyForm",
+      "file": "components/survey-form.tsx",
+      "purpose": "Create a survey (name, NPS or CSAT, question, channel, comments, thank-you line, scale) or edit one; edit reads the full record first and sends only changed fields.",
+      "operations": [
+        "create_survey_feedback_surveys_post",
+        "get_survey_feedback_surveys__survey_id__get",
+        "update_survey_feedback_surveys__survey_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "SurveySend",
+      "file": "components/survey-send.tsx",
+      "purpose": "Send a survey to an audience list now or later, sized from the list and confirmed; follows the send until it settles.",
+      "operations": [
+        "get_survey_send_feedback_sends__send_id__get",
+        "list_lists_lists_get",
+        "list_survey_sending_domains_feedback_sending_domains_get",
+        "send_survey_feedback_surveys__survey_id__send_post"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "SurveySendHistory",
+      "file": "components/survey-send-history.tsx",
+      "purpose": "Every send of one survey with status, audience, reach and answers.",
+      "operations": [
+        "get_survey_sends_feedback_surveys__survey_id__sends_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "SurveyTriggers",
+      "file": "components/survey-triggers.tsx",
+      "purpose": "Automatic sends for a survey: on a schedule, when someone joins a list or when a record reaches a stage; add (confirmed) and remove (confirmed).",
+      "operations": [
+        "create_survey_trigger_feedback_surveys__survey_id__triggers_post",
+        "delete_survey_trigger_feedback_surveys__survey_id__triggers__trigger_id__delete",
+        "list_lists_lists_get",
+        "list_survey_sending_domains_feedback_sending_domains_get",
+        "list_survey_triggers_feedback_surveys__survey_id__triggers_get"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "SurveyResults",
+      "file": "components/survey-results.tsx",
+      "purpose": "Headline NPS or CSAT, response rate, answer split and trend by day, week or month.",
+      "operations": [
+        "get_survey_summary_feedback_surveys__survey_id__summary_get",
+        "get_survey_trends_feedback_surveys__survey_id__trends_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "SurveyResponses",
+      "file": "components/survey-responses.tsx",
+      "purpose": "Every answer with search, band filter, per-answer detail and CSV export, plus the team's in-app answers.",
+      "operations": [
+        "get_survey_app_user_responses_feedback_surveys__survey_id__app_user_responses_get",
+        "get_survey_responses_feedback_surveys__survey_id__responses_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "SendingDomains",
+      "file": "components/sending-domains.tsx",
+      "purpose": "Domains surveys may be emailed from, their verification state, and verify a new domain (confirmed) to get its DNS records.",
+      "operations": [
+        "list_survey_sending_domains_feedback_sending_domains_get",
+        "survey_domain_status_feedback_sending_domains_status_get",
+        "verify_survey_domain_feedback_sending_domains_verify_post"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "OrgSummary",
+      "file": "components/org-summary.tsx",
+      "purpose": "Org-wide NPS and CSAT for all contacts or one audience list, with a rollup per survey.",
+      "operations": [
+        "get_survey_org_summary_feedback_org_summary_get",
+        "list_lists_lists_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "AccountNps",
+      "file": "components/account-nps.tsx",
+      "purpose": "One company's NPS, coverage and each contact's latest score; takes a companyId or finds a company by name.",
+      "operations": [
+        "get_company_survey_nps_feedback_companies__company_id__nps_get",
+        "list_companies_companies_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "ContactSurveyHistory",
+      "file": "components/contact-survey-history.tsx",
+      "purpose": "Every survey answer one person has given; takes a contactId or finds a person by name.",
+      "operations": [
+        "get_contact_survey_history_feedback_contacts__contact_id__history_get",
+        "list_contacts_contacts_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    }
+  ],
+  "hooks": [],
+  "lib": [
+    {
+      "file": "lib/surveys-types.ts",
+      "purpose": "Survey, summary, response, send and trigger types; the API's exact vocabularies (types, channels, comment modes, trigger kinds); score and band helpers; the changed-fields diff; CSV building with formula-injection guard."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/create-an-nps-survey.ts",
+      "title": "Create an NPS or CSAT survey and read it back",
+      "when": "Setting up the question you will ask; nothing is sent."
+    },
+    {
+      "file": "recipes/send-a-survey-and-follow-it.ts",
+      "title": "Send a survey to a list and follow the send",
+      "when": "Asking an audience now or later; emails real people, so a person confirms the audience size first."
+    },
+    {
+      "file": "recipes/survey-score-report.ts",
+      "title": "Report every survey's score, response rate and recent comments",
+      "when": "A weekly digest or a dashboard backend."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "sending-domain",
+      "description": "Email surveys need a VERIFIED sending domain: the sender address must be on one. Verify a domain in the Sending domains tab (it returns the DNS records), publish those records at your DNS provider, then check its status.",
+      "where": "api",
+      "verify": "GET /api/v1/feedback/sending-domains lists the domain with status verified."
+    },
+    {
+      "id": "consented-audience",
+      "description": "A list of people who may be asked for feedback. A send reaches real people and cannot be recalled; a person confirms the audience size first. Unsubscribed and suppressed contacts are skipped by the API.",
+      "where": "app",
+      "verify": "The owner confirmed the list is people you may email."
+    },
+    {
+      "id": "survey-scopes",
+      "description": "The key needs surveys:read, surveys:write, surveys:delete and, to send or verify a domain, surveys:run (an external operation separate from surveys:write). Listing audiences needs lists:read.",
+      "where": "api",
+      "verify": "g8.api.me.describeCurrentKey() lists the scopes."
+    },
+    {
+      "id": "proxy-allowlist",
+      "description": "Add \"feedback\", \"lists\", \"companies\" and \"contacts\" to allowedPrefixes in app/api/g8/[...path]/route.ts. The survey endpoints live under /feedback, not /surveys.",
+      "where": "app",
+      "verify": "The route file's allowedPrefixes contains them."
+    }
+  ],
+  "scopes": [
+    "companies:read",
+    "contacts:read",
+    "lists:read",
+    "surveys:delete",
+    "surveys:read",
+    "surveys:run",
+    "surveys:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Survey type",
+      "default": "NPS (0 to 10) for relationship feedback, CSAT (1 to 5) for a specific interaction",
+      "askHuman": false
+    },
+    {
+      "decision": "Question wording",
+      "default": "The standard question for the type, with the brand name; the person may rewrite it",
+      "askHuman": false
+    },
+    {
+      "decision": "Comment capture",
+      "default": "Score only (none); choose link to ask for a comment after the score",
+      "askHuman": false
+    },
+    {
+      "decision": "Delivery channel",
+      "default": "Email",
+      "askHuman": false
+    },
+    {
+      "decision": "Which list is asked",
+      "default": "None: a person always picks the audience",
+      "askHuman": true
+    },
+    {
+      "decision": "Sending",
+      "default": "Never without the person confirming the audience size and the sender domain",
+      "askHuman": false
+    },
+    {
+      "decision": "Stopping a survey",
+      "default": "Close it (keeps every answer); delete only when asked, after a confirmation",
+      "askHuman": false
+    },
+    {
+      "decision": "Trend bucket",
+      "default": "Weekly for one survey, monthly for the org overview",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "lucide-react": ">=0.400.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>
+  );
+}