@graph8/sdk 0.370.0 → 0.373.0

package/blocks/social-ads/components/social-screen.tsx

@@ -1,15 +1,18 @@
 "use client";
 
 /**
- * SocialScreen: the finished social publishing page. Two tabs:
+ * SocialScreen: the finished social publishing page. Four tabs:
  *   Posts     every post by status (SocialPostList): publish a draft, cancel a scheduled post, delete. "New post" opens the
  *             composer in a side sheet (PostComposer): write or draft with AI, save, schedule or publish.
- *   Accounts  the connected social accounts with their publishing capacity. Connecting an account (LinkedIn sign-in) only
- *             works in the graph8 app, so this tab links out instead of offering a dead button.
+ *   Accounts  the connected social accounts with their publishing capacity; disconnect one (confirmed). Connecting an account
+ *             (LinkedIn sign-in) only works in the graph8 app, so this tab links out instead of offering a dead button.
+ *   Ideas     post ideas mined from your signals and content (SocialIdeas); "Draft a post" opens the composer with the idea as the brief.
+ *   Performance  totals and a per-day table for a window (SocialPerformance); a live post also has a Performance tab of its own.
  *
  * Every post opens a complete detail screen (PostDetail, `?id=`, full page with `?view=full`).
  *
- * SDK operations: one read of listSocialPosts (page_size 1) for the per-status counts in the stat strip. Composes
+ * SDK operations: one read of listSocialPosts (page_size 1) for the per-status counts in the stat strip, and
+ * disconnectSocialAccount (DELETE /social/accounts/{id}, destructive, confirmed: publishing from it stops). Composes
  * PostComposer (billable AI drafts, external schedule/publish, all confirmed), SocialPostList (external + destructive,
  * confirmed) and useSocialAccounts (read).
  */
@@ -35,6 +38,11 @@ import { PostComposer } from "./post-composer";
 import { SocialPostList } from "./social-post-list";
 import { PostDetail } from "./post-detail";
 import { brandUrl, useBrand } from "@/g8/hooks/use-brand";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useConfirmAction } from "@/g8/components/confirmed-action";
+import { g8Delete } from "@/g8/lib/g8-client";
+import { SocialIdeas } from "./social-ideas";
+import { SocialPerformance } from "./social-performance";
 
 export interface SocialScreenProps {
   /** Where "Connect" sends people. Default: graph8 Settings > Integrations. */
@@ -49,6 +57,7 @@ const APP_PATH = "/studio/settings?tab=integrations";
 function Accounts({ connectUrl }: { connectUrl: string }) {
   const brand = useBrand();
   const { accounts, loading, error, refetch } = useSocialAccounts();
+  const { ask, dialog, failure } = useConfirmAction();
   if (error) return <ApiError error={error} onRetry={() => void refetch()} />;
   if (loading && accounts.length === 0) return <p className="text-sm text-muted-foreground" role="status">Loading accounts...</p>;
   if (accounts.length === 0) {
@@ -61,6 +70,9 @@ function Accounts({ connectUrl }: { connectUrl: string }) {
     );
   }
   return (
+    <>
+    {failure ? <ApiError error={failure} title="Could not disconnect the account" /> : null}
+    <ConfirmSpendDialog {...dialog} />
     <ul className="grid gap-3 md:grid-cols-2">
       {accounts.map((a) => (
         <li key={a.id}>
@@ -74,11 +86,17 @@ function Accounts({ connectUrl }: { connectUrl: string }) {
                 </p>
               </div>
               {a.profile_url ? <a className="text-sm underline" href={a.profile_url} target="_blank" rel="noreferrer">Profile</a> : null}
+              <Button size="sm" variant="ghost" aria-label={`Disconnect ${a.display_name ?? a.provider}`} onClick={() => ask({
+                tier: "destructive", title: `Disconnect ${a.display_name ?? a.provider}`, confirmLabel: "Disconnect", affected: 1,
+                description: `Publishing and scheduled posts from this account stop. Posts already live stay live. Connect it again in ${brand.linkLabel} to resume.`,
+                tolerateStatus: [404], run: () => g8Delete(`/social/accounts/${encodeURIComponent(a.id)}`), onDone: () => void refetch(),
+              })}>Disconnect</Button>
             </div>
           </SectionCard>
         </li>
       ))}
     </ul>
+    </>
   );
 }
 
@@ -86,11 +104,12 @@ export function SocialScreen(props: SocialScreenProps) {
   const brand = useBrand();
   const connectUrl = props.connectUrl ?? brandUrl(brand, APP_PATH);
   const [tabValue, setTab] = useUrlState("tab", "posts");
-  const tab = tabValue === "accounts" ? "accounts" : "posts";
+  const tab = tabValue === "accounts" || tabValue === "ideas" || tabValue === "performance" ? tabValue : "posts";
   const [id, setId] = useUrlState("id", "");
   const [view, setView] = useUrlState("view", "");
   const expanded = view === "full" && Boolean(id);
   const [composing, setComposing] = useState(false);
+  const [composeBrief, setComposeBrief] = useState("");
   const [refreshKey, setRefreshKey] = useState(0);
   const counts = useG8Query(async (signal) => (await g8Get<SocialPostPage>("/social/posts", { page: 1, page_size: 1 }, { signal })).data, [refreshKey]);
 
@@ -112,13 +131,15 @@ export function SocialScreen(props: SocialScreenProps) {
       actions={
         <>
           {props.toolbarActions}
-          <Button onClick={() => setComposing(true)}>
+          <Button onClick={() => { setComposeBrief(""); setComposing(true); }}>
             <Plus className="mr-1.5 size-4" /> New post
           </Button>
         </>
       }
       tabs={[
         { id: "posts", label: "Posts" },
+        { id: "ideas", label: "Ideas" },
+        { id: "performance", label: "Performance" },
         { id: "accounts", label: "Accounts" },
       ]}
       activeTab={tab}
@@ -144,11 +165,17 @@ export function SocialScreen(props: SocialScreenProps) {
               onChanged={() => setRefreshKey((k) => k + 1)} />
           ) : null}
         />
+      ) : tab === "ideas" ? (
+        <SocialIdeas onUse={(brief) => { setComposeBrief(brief); setComposing(true); }} />
+      ) : tab === "performance" ? (
+        <SocialPerformance />
       ) : (
         <Accounts connectUrl={connectUrl} />
       )}
       <FormSheet open={composing} onOpenChange={setComposing} title="New post" description="Write it, draft it with AI, then save, schedule or publish.">
         <PostComposer
+          key={composeBrief}
+          initialBrief={composeBrief || undefined}
           onSaved={() => {
             setComposing(false);
             setRefreshKey((k) => k + 1);

package/blocks/social-ads/lib/ads-extra.ts

@@ -0,0 +1,67 @@
+"use client";
+
+/**
+ * Helpers for the ads and social management components (campaign editor, campaign ads, creative tools, revisions,
+ * concepts, performance, ideas). These endpoints return open dicts, so every reader accepts what is present.
+ */
+export type Rec = Record<string, unknown>;
+
+export function asRec(value: unknown): Rec {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Rec) : {};
+}
+
+export function str(value: unknown, fallback = ""): string {
+  return typeof value === "string" ? value : value == null ? fallback : String(value);
+}
+
+export function num(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+export function rowsOf<T = Rec>(data: unknown, ...keys: string[]): T[] {
+  if (Array.isArray(data)) return data as T[];
+  const rec = asRec(data);
+  for (const key of [...keys, "items"]) if (Array.isArray(rec[key])) return rec[key] as T[];
+  return [];
+}
+
+export const whenText = (v: unknown): string => {
+  const d = new Date(str(v));
+  return Number.isNaN(d.getTime()) ? "" : d.toLocaleString();
+};
+
+/** What the API's `/editable` map says about one field. A field it does not list is treated as not editable. */
+export interface FieldCapability { editable: boolean; reason?: string; consequences: string[] }
+
+export function capabilityOf(editable: unknown, field: string): FieldCapability {
+  const f = asRec(asRec(asRec(editable).fields)[field]);
+  return { editable: f.editable === true, reason: str(f.reason) || undefined, consequences: rowsOf<string>(f.consequences).map(String) };
+}
+
+/** A money string from an input: a positive number with at most two decimals, else undefined. */
+export function parseMoney(raw: string): number | undefined {
+  const t = raw.trim();
+  if (!/^\d+(\.\d{1,2})?$/.test(t)) return undefined;
+  const n = Number(t);
+  return n > 0 ? n : undefined;
+}
+
+/** `YYYY-MM-DD` from an API date or midnight-UTC timestamp, for a date input. Never goes through the local zone. */
+export function dateInput(value: unknown): string {
+  const t = str(value);
+  return /^\d{4}-\d{2}-\d{2}/.test(t) ? t.slice(0, 10) : "";
+}
+
+export interface CampaignEdit { name?: string; daily_budget?: number; end_date?: string; spend_cap?: number }
+
+/** The body of an edit: only fields that differ from the saved campaign. Empty means nothing to save. */
+export function campaignChanges(saved: { name?: unknown; daily_budget?: unknown; end_date?: unknown }, draft: { name: string; daily_budget: string; end_date: string; spend_cap: string }): CampaignEdit {
+  const out: CampaignEdit = {};
+  if (draft.name.trim() && draft.name.trim() !== str(saved.name)) out.name = draft.name.trim();
+  const budget = parseMoney(draft.daily_budget);
+  if (budget !== undefined && budget !== num(saved.daily_budget)) out.daily_budget = budget;
+  if (/^\d{4}-\d{2}-\d{2}$/.test(draft.end_date) && draft.end_date !== dateInput(saved.end_date)) out.end_date = draft.end_date;
+  const cap = parseMoney(draft.spend_cap);
+  if (cap !== undefined) out.spend_cap = cap;
+  return out;
+}

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