@graph8/sdk 0.373.0 → 0.374.0

package/blocks/campaigns/README.md

@@ -18,7 +18,7 @@ deep-linkable (`?tab=campaigns|profile|personas`, `?id=` the record, `?dtab=` th
 - **Company profile tab**: the profile plus ICPs; `IcpDetail` shows every field and edits, pins or archives.
 - **Personas tab**: `PersonaDetail` shows every field, the campaigns that target it, and edits, pins or archives.
 
-Slot props: `toolbarActions`, `renderDetailActions(campaign)`, `extraDetailTabs`, `websiteUrl`. Prerequisites: a
+Slot props: `toolbarActions`, `renderDetailActions(campaign)`, `extraDetailTabs`, `websiteUrl`. `CampaignLinksTab` (`components/campaign-links.tsx`) is a ready `extraDetailTabs` entry: the campaign's landing pages, workflows and newsletters, each opening in your app (`onOpenLandingPage`, `onOpenWorkflow`, `onOpenNewsletter`), with link and unlink for landing pages and newsletters and unlink only for workflows (the API has no link operation for them; a newsletter that belongs to another campaign is not offered, because linking moves it). Prerequisites: a
 company profile with the real website, an active mailbox, a contact list, and credits for AI generation.
 `IcpEditor` and `PersonaEditor` gained optional `onOpen` and `refreshKey`; `CampaignAssets` optional
 `documentId` and `onDocumentChange`.

package/blocks/campaigns/block.json

@@ -42,16 +42,25 @@
     "get_persona_personas__persona_id__get",
     "get_safe_to_send_deliverability_safe_to_send_get",
     "launch_campaign_campaigns__campaign_id__launch_post",
+    "link_landing_page_to_campaign_campaigns__campaign_id__landing_pages_post",
+    "link_newsletter_campaign_newsletters__newsletter_id__campaign_put",
     "list_campaign_documents_campaigns__campaign_id__documents_get",
+    "list_campaign_landing_pages_campaigns__campaign_id__landing_pages_get",
+    "list_campaign_workflows_campaigns__campaign_id__workflows_get",
     "list_campaigns_campaigns_get",
     "list_campaigns_for_picker_campaigns_picker_get",
     "list_icps_icps_get",
+    "list_landing_pages_landing_pages_get",
     "list_mailboxes_mailboxes_get",
+    "list_newsletters_newsletters_get",
     "list_personas_personas_get",
     "pin_icp_icps__icp_id__pin_post",
     "pin_persona_personas__persona_id__pin_post",
     "recommend_campaign_personas_campaigns_recommend_personas_post",
     "regenerate_campaign_document_campaigns__campaign_id__documents__document_id__regenerate_post",
+    "unlink_campaign_workflow_campaigns__campaign_id__workflows__link_id__delete",
+    "unlink_landing_page_from_campaign_campaigns__campaign_id__landing_pages__landing_page_id__delete",
+    "unlink_newsletter_campaign_newsletters__newsletter_id__campaign_delete",
     "unpin_icp_icps__icp_id__unpin_post",
     "unpin_persona_personas__persona_id__unpin_post",
     "update_campaign_campaigns__campaign_id__patch",
@@ -307,6 +316,27 @@
         "write",
         "destructive"
       ]
+    },
+    {
+      "name": "CampaignLinksTab",
+      "file": "components/campaign-links.tsx",
+      "purpose": "The landing pages, workflows and newsletters tied to one campaign: each row opens the record in your app, landing pages and newsletters can be linked and unlinked (workflows only unlinked, the API has no link operation). Use as an extraDetailTabs entry of CampaignsScreen.",
+      "operations": [
+        "list_campaign_landing_pages_campaigns__campaign_id__landing_pages_get",
+        "link_landing_page_to_campaign_campaigns__campaign_id__landing_pages_post",
+        "unlink_landing_page_from_campaign_campaigns__campaign_id__landing_pages__landing_page_id__delete",
+        "list_landing_pages_landing_pages_get",
+        "list_campaign_workflows_campaigns__campaign_id__workflows_get",
+        "unlink_campaign_workflow_campaigns__campaign_id__workflows__link_id__delete",
+        "list_newsletters_newsletters_get",
+        "link_newsletter_campaign_newsletters__newsletter_id__campaign_put",
+        "unlink_newsletter_campaign_newsletters__newsletter_id__campaign_delete"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
     }
   ],
   "hooks": [
@@ -378,7 +408,10 @@
     "campaigns:launch",
     "campaigns:read",
     "campaigns:run",
-    "campaigns:write"
+    "campaigns:write",
+    "newsletter:delete",
+    "newsletter:read",
+    "newsletter:write"
   ],
   "defaults": [
     {

package/blocks/campaigns/components/campaign-links.tsx

@@ -0,0 +1,180 @@
+"use client";
+
+/**
+ * CampaignLinksTab: the landing pages, workflows and newsletters tied to ONE campaign. Each row opens the record in
+ * your app (`onOpen*` callbacks route to your own screens), and a landing page or newsletter can be linked or unlinked
+ * here. Use it as an `extraDetailTabs` entry of CampaignsScreen:
+ *   { id: "links", label: "Links", render: (c) => <CampaignLinksTab campaignId={c.id} onOpenLandingPage={(id) => router.push(`/pages?id=${id}`)} /> }
+ *
+ * SDK operations, in order:
+ *   1. listCampaignLandingPages   GET    /campaigns/{id}/landing-pages                    (read)
+ *      listLandingPages           GET    /landing-pages?limit&offset                      (read; the "link a page" choices, paged)
+ *      linkLandingPageToCampaign  POST   /campaigns/{id}/landing-pages                    (write)
+ *      unlinkLandingPageFromCampaign DELETE /campaigns/{id}/landing-pages/{page}          (DESTRUCTIVE tier -> ConfirmSpendDialog; the page itself is kept)
+ *   2. listCampaignWorkflows      GET    /campaigns/{id}/workflows                        (read)
+ *      unlinkCampaignWorkflow     DELETE /campaigns/{id}/workflows/{link_id}              (DESTRUCTIVE tier -> ConfirmSpendDialog; the workflow itself is kept)
+ *   3. listNewsletters            GET    /newsletters                                     (read; each row names its campaign_id)
+ *      linkNewsletterCampaign     PUT    /newsletters/{id}/campaign                       (write; a newsletter has ONE campaign)
+ *      unlinkNewsletterCampaign   DELETE /newsletters/{id}/campaign                       (DESTRUCTIVE tier -> ConfirmSpendDialog; the newsletter is kept)
+ *
+ * API gaps, stated on screen: there is no operation that links a workflow to a campaign (only list, edit and unlink),
+ * and a newsletter that already belongs to ANOTHER campaign is not offered, because linking replaces its campaign.
+ */
+
+import { useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ExternalLink, Link2, Unlink } from "lucide-react";
+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 { useAllPages } from "@/g8/hooks/use-all-pages";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { hasNextOf } from "@/g8/lib/paging";
+import { text } from "../lib/campaigns-utils";
+
+export interface CampaignLinksTabProps {
+  /** The campaign (id or slug as the list gave it). */
+  campaignId: string;
+  /** Route to a landing page / workflow / newsletter in your app. A section without its callback shows names only. */
+  onOpenLandingPage?: (landingPageId: string) => void;
+  onOpenWorkflow?: (workflowId: string) => void;
+  onOpenNewsletter?: (newsletterId: string) => void;
+  className?: string;
+}
+
+type Row = Record<string, unknown>;
+const PAGE = 100;
+
+/** The rows of a list payload under any of the keys the API mirrors them on. */
+export function rowsOf(env: unknown, ...keys: string[]): Row[] {
+  const data = (env as { data?: unknown } | null)?.data;
+  if (Array.isArray(data)) return data as Row[];
+  const o = (data ?? {}) as Record<string, unknown>;
+  for (const k of ["items", ...keys]) if (Array.isArray(o[k])) return o[k] as Row[];
+  return [];
+}
+
+const idOf = (v: unknown): string => text(v).trim();
+
+function LinkRow({ name, meta, onOpen, onUnlink, busy }: { name: string; meta?: string; onOpen?: () => void; onUnlink?: () => void; busy?: boolean }) {
+  return (
+    <li className="flex items-center justify-between gap-3 py-2 text-sm">
+      <span className="min-w-0 truncate"><span className="font-medium">{name}</span>{meta ? <span className="text-muted-foreground"> · {meta}</span> : null}</span>
+      <span className="flex shrink-0 gap-2">
+        {onOpen ? <Button size="sm" variant="outline" onClick={onOpen} aria-label={`Open ${name}`}><ExternalLink className="mr-1 size-4" aria-hidden />Open</Button> : null}
+        {onUnlink ? <Button size="sm" variant="ghost" disabled={busy} onClick={onUnlink} aria-label={`Unlink ${name}`}><Unlink className="mr-1 size-4" aria-hidden />Unlink</Button> : null}
+      </span>
+    </li>
+  );
+}
+
+function LinkPicker({ label, options, busy, onLink }: { label: string; options: Array<{ id: string; name: string }>; busy: boolean; onLink: (id: string) => void }) {
+  const [value, setValue] = useState("");
+  return (
+    <div className="flex items-center gap-2 pt-2">
+      <select aria-label={label} className="h-9 min-w-56 rounded-md border bg-background px-2 text-sm" value={value} onChange={(e) => setValue(e.target.value)}>
+        <option value="">{options.length ? label : "Nothing left to link"}</option>
+        {options.map((o) => <option key={o.id} value={o.id}>{o.name}</option>)}
+      </select>
+      <Button size="sm" disabled={!value || busy} loading={busy} onClick={() => { onLink(value); setValue(""); }}><Link2 className="mr-1 size-4" aria-hidden />Link</Button>
+    </div>
+  );
+}
+
+type Pending = { kind: "page" | "workflow" | "newsletter"; id: string; name: string };
+
+export function CampaignLinksTab({ campaignId, onOpenLandingPage, onOpenWorkflow, onOpenNewsletter, className }: CampaignLinksTabProps) {
+  const base = `/campaigns/${encodeURIComponent(campaignId)}`;
+  const pages = useG8Query(async (signal) => rowsOf(await g8Get(`${base}/landing-pages`, undefined, { signal }), "landing_pages"), [campaignId], { key: ["campaigns", "links", "pages", campaignId] });
+  const flows = useG8Query(async (signal) => rowsOf(await g8Get(`${base}/workflows`, undefined, { signal }), "workflows"), [campaignId], { key: ["campaigns", "links", "workflows", campaignId] });
+  const letters = useG8Query(async (signal) => rowsOf(await g8Get("/newsletters", undefined, { signal }), "newsletters"), [campaignId], { key: ["campaigns", "links", "newsletters"] });
+  const allPages = useAllPages<Row>(async (page, signal) => {
+    const env = await g8Get("/landing-pages", { limit: PAGE, offset: (page - 1) * PAGE }, { signal });
+    const rows = rowsOf(env, "pages", "landing_pages");
+    return { rows, hasNext: hasNextOf(env, PAGE, rows.length) };
+  }, [], { pageSize: PAGE });
+  const [pending, setPending] = useState<Pending | null>(null);
+  const refresh = () => { void pages.refetch(); void flows.refetch(); void letters.refetch(); };
+  const link = useG8Mutation(async (v: { kind: "page" | "newsletter"; id: string }) => {
+    if (v.kind === "page") await g8Post(`${base}/landing-pages`, { landing_page_id: v.id });
+    else await g8Put(`/newsletters/${encodeURIComponent(v.id)}/campaign`, { campaign_id: campaignId });
+  }, { onSuccess: refresh });
+  const unlink = useG8Mutation(async (p: Pending) => {
+    try {
+      if (p.kind === "page") await g8Delete(`${base}/landing-pages/${encodeURIComponent(p.id)}`);
+      else if (p.kind === "workflow") await g8Delete(`${base}/workflows/${encodeURIComponent(p.id)}`);
+      else await g8Delete(`/newsletters/${encodeURIComponent(p.id)}/campaign`);
+    } catch (err) {
+      if ((err as { status?: number }).status !== 404) throw err; // already unlinked counts as done
+    }
+  }, { onSuccess: () => { setPending(null); refresh(); }, onError: () => setPending(null) });
+
+  const linkedPages = (pages.data ?? []).map((r) => {
+    const lp = (r.landing_page ?? {}) as Row;
+    return { id: idOf(lp.id) || idOf(r.landing_page_id), name: text(lp.name) || `Landing page ${idOf(lp.id) || idOf(r.landing_page_id)}`, status: text(lp.status) };
+  }).filter((p) => p.id);
+  const linkedFlows = (flows.data ?? []).map((r) => ({ linkId: idOf(r.id), workflowId: idOf(r.workflow_id), name: text(r.workflow_name) || `Workflow ${idOf(r.workflow_id)}`, status: text(r.status), role: text(r.role) })).filter((w) => w.linkId);
+  const thisLetters = (letters.data ?? []).filter((n) => idOf(n.campaign_id) === campaignId);
+  const freeLetters = (letters.data ?? []).filter((n) => !idOf(n.campaign_id)).map((n) => ({ id: idOf(n.id), name: text(n.name) || `Newsletter ${idOf(n.id)}` }));
+  const linkedIds = new Set(linkedPages.map((p) => p.id));
+  const pageChoices = allPages.items.map((r) => ({ id: idOf(r.id), name: text(r.name) || `Landing page ${idOf(r.id)}` })).filter((p) => p.id && !linkedIds.has(p.id));
+  const otherLetters = (letters.data ?? []).filter((n) => idOf(n.campaign_id) && idOf(n.campaign_id) !== campaignId).length;
+
+  return (
+    <div className={`space-y-4 ${className ?? ""}`}>
+      <SectionCard title="Landing pages" description="Pages visitors land on from this campaign. Unlinking keeps the page.">
+        {pages.error ? <ApiError error={pages.error} title="Could not load landing pages" onRetry={() => void pages.refetch()} /> : !pages.data ? <Skeleton className="h-16 w-full" aria-label="Loading landing pages" /> : linkedPages.length === 0 ? (
+          <EmptyState compact title="No landing page linked" description="Link a page below." />
+        ) : (
+          <ul className="divide-y" aria-label="Linked landing pages">
+            {linkedPages.map((p) => <LinkRow key={p.id} name={p.name} meta={p.status || undefined} onOpen={onOpenLandingPage ? () => onOpenLandingPage(p.id) : undefined} onUnlink={() => setPending({ kind: "page", id: p.id, name: p.name })} busy={unlink.loading} />)}
+          </ul>
+        )}
+        {allPages.error ? <ApiError error={allPages.error} title="Could not load the pages to link" onRetry={allPages.refetch} /> : allPages.loaded ? <LinkPicker label="Link a landing page" options={pageChoices} busy={link.loading} onLink={(id) => void link.mutate({ kind: "page", id })} /> : null}
+        {allPages.truncated ? <p className="pt-1 text-xs text-muted-foreground">Showing the first {allPages.items.length} landing pages.</p> : null}
+      </SectionCard>
+
+      <SectionCard title="Workflows" description="Automations that run for this campaign. Unlinking keeps the workflow.">
+        {flows.error ? <ApiError error={flows.error} title="Could not load workflows" onRetry={() => void flows.refetch()} /> : !flows.data ? <Skeleton className="h-16 w-full" aria-label="Loading workflows" /> : linkedFlows.length === 0 ? (
+          <EmptyState compact title="No workflow linked" />
+        ) : (
+          <ul className="divide-y" aria-label="Linked workflows">
+            {linkedFlows.map((w) => <LinkRow key={w.linkId} name={w.name} meta={[w.role, w.status].filter(Boolean).join(", ") || undefined} onOpen={onOpenWorkflow && w.workflowId ? () => onOpenWorkflow(w.workflowId) : undefined} onUnlink={() => setPending({ kind: "workflow", id: w.linkId, name: w.name })} busy={unlink.loading} />)}
+          </ul>
+        )}
+        <p className="pt-2 text-xs text-muted-foreground">Linking a new workflow to a campaign is not available through the API yet.</p>
+      </SectionCard>
+
+      <SectionCard title="Newsletters" description="A newsletter belongs to one campaign. Unlinking keeps the newsletter.">
+        {letters.error ? <ApiError error={letters.error} title="Could not load newsletters" onRetry={() => void letters.refetch()} /> : !letters.data ? <Skeleton className="h-16 w-full" aria-label="Loading newsletters" /> : (
+          <>
+            {thisLetters.length === 0 ? <EmptyState compact title="No newsletter linked" /> : (
+              <ul className="divide-y" aria-label="Linked newsletters">
+                {thisLetters.map((n) => <LinkRow key={idOf(n.id)} name={text(n.name) || `Newsletter ${idOf(n.id)}`} meta={text(n.status) || undefined} onOpen={onOpenNewsletter ? () => onOpenNewsletter(idOf(n.id)) : undefined} onUnlink={() => setPending({ kind: "newsletter", id: idOf(n.id), name: text(n.name) || `Newsletter ${idOf(n.id)}` })} busy={unlink.loading} />)}
+              </ul>
+            )}
+            <LinkPicker label="Link a newsletter" options={freeLetters} busy={link.loading} onLink={(id) => void link.mutate({ kind: "newsletter", id })} />
+            {otherLetters > 0 ? <p className="pt-1 text-xs text-muted-foreground">{otherLetters} {otherLetters === 1 ? "newsletter belongs" : "newsletters belong"} to other campaigns and {otherLetters === 1 ? "is" : "are"} not listed, because linking would move {otherLetters === 1 ? "it" : "them"}.</p> : null}
+          </>
+        )}
+      </SectionCard>
+
+      {link.error ? <ApiError error={link.error} title="Could not link" onRetry={link.reset} /> : null}
+      {unlink.error ? <ApiError error={unlink.error} title="Could not unlink" onRetry={unlink.reset} /> : null}
+      <ConfirmSpendDialog
+        open={pending !== null}
+        tier="destructive"
+        title={`Unlink "${pending?.name ?? ""}" from this campaign?`}
+        description={pending?.kind === "page" ? "The landing page stays published and keeps its other campaigns. Only the tie to this campaign is removed." : pending?.kind === "workflow" ? "The workflow itself is kept. It stops being part of this campaign." : "The newsletter is kept and keeps sending. It is no longer part of this campaign."}
+        confirmLabel="Unlink"
+        affected={1}
+        confirming={unlink.loading}
+        onCancel={() => setPending(null)}
+        onConfirm={() => { if (pending) void unlink.mutate(pending); }}
+      />
+    </div>
+  );
+}

package/blocks/company-intelligence/components/research-run.tsx

@@ -75,8 +75,12 @@ export function ResearchRun({ onChanged, className }: ResearchRunProps) {
   const sources = runSteps(run ?? undefined).length;
   const records = docs.data?.length;
 
+  // The confirm's source count comes from the last run's status read: hold Research until that read settled (success or
+  // error), so the dialog never opens with a missing count. After an error the confirm says what it collects, no number.
+  const countPending = latest.loading || (!activeId && Boolean(shownId) && lastRun.loading);
+
   const askResearch = () => {
-    if (!website) return;
+    if (!website || countPending) return;
     ask({
       tier: "billable",
       title: `Research ${website}`,
@@ -132,7 +136,7 @@ export function ResearchRun({ onChanged, className }: ResearchRunProps) {
               {target.suggested && !typed ? <button type="button" className="text-xs underline underline-offset-2" onClick={() => setTyped(target.suggested ?? "")}>Use {target.suggested} from your workspace settings</button> : null}
             </div>
           )}
-          <Button type="button" onClick={askResearch} disabled={!website || running}>{running ? "Researching..." : latest.run ? "Research again" : "Research website"}</Button>
+          <Button type="button" onClick={askResearch} disabled={!website || running || countPending} title={countPending ? "Loading the last run" : undefined}>{running ? "Researching..." : latest.run ? "Research again" : "Research website"}</Button>
           {finishedWithinHour(latest.run) ? (
             <label className="flex items-center gap-1.5 text-sm"><input type="checkbox" checked={force} onChange={(e) => setForce(e.target.checked)} />Run again even though one finished in the last hour</label>
           ) : null}

package/blocks/crm/README.md

@@ -18,6 +18,23 @@ Three finished screens compose the parts below into complete workspaces. Each ne
 | `CompaniesScreen` | Same flow for accounts: filters (name, domain, industry, country), detail with People, Activity, Notes, Tasks, create (domain required), edit, delete, duplicate review. | `renderRowActions(row, { reload })`, `renderDetailActions(company, { reload })`, `extraDetailTabs`, `toolbarActions`, `renderBulkActions`, `onOpenContact` |
 | `TasksScreen` | The workspace-wide task queue: Open / Completed / All, search, priority / type / linked-record filters, tick to complete or reopen, create, edit, delete, bulk complete and delete, overdue marker. | `renderRowActions`, `renderDetailActions`, `toolbarActions`, `defaultRecord`, `onOpenRecord` |
 
+### Record actions on contacts
+
+`ContactsScreen` also carries the write actions a CRM needs. Each exists three ways, a row (the "..." button), a selection (the bar
+above the table) and the open contact, and each is an exported component you can place yourself.
+
+| Action | Component | Notes |
+|---|---|---|
+| Assign or remove the owner of a WHOLE LIST | `OwnerAssignListButton` (via `ContactsScreen`'s `renderOwnerPicker`) | Never for a selection: the API assigns owners by filter (`list_id` + `filterModel`) across every match, and has no id-addressed owner write (API gap: `assign-owner` needs an `ids` field). The picker is injected (`renderOwnerPicker={(p) => <MemberPicker label="New owner" {...p} />}`) so crm stays free of the pickers block; without it the action is hidden. Offered only with a list in scope and no other filter; N is the list's real count; assign and remove are both confirmed with the list and N. |
+| Tags | `ContactTagChips` (open contact), `TagAssignButton` (selection), `TagManager` (create, rename, recolour, archive, delete, merge) | Delete states how many contacts lose the tag and can move them to another tag first. Merge removes the source tags. A tag's description cannot be cleared (the API ignores null), so it is not editable. |
+| Edit one field on a selection | `BulkUpdateButton` | Title, department, seniority, city, state, country. Chunks of 100, "N of M updated". Clearing is not offered (no documented clear). |
+| Verify email | `VerifyEmailButton` | Billable, about 1 credit per email. Only contacts with an unlocked email are counted and sent; the result line shows the credits actually charged. Max 1000. |
+| Unlock info | `UnlockInfoButton` | Billable, 1 credit per newly unlocked contact. Only locked contacts are counted and sent. Max 1000 per call. |
+| AI documents | `ContactDocumentsTab` | Write, rewrite, write all, read. Billable with no published price, so the confirm shows none. Rewrite replaces the stored text. |
+| Signals and next best step | `ContactInsightsTab` | Signals load on open. The next best step is a billable GET, so it is a button behind a confirm. |
+
+Prerequisites added: the `enrichment:run` scope (verify, unlock, documents, next best step). The owner action needs the `team-members` prefix and `team:read` only in apps that inject a picker (they already include `pickers`).
+
 ```tsx
 "use client";
 import { ContactsScreen } from "@/components/g8/crm/contacts-screen";
@@ -152,5 +169,7 @@ Ask the person: who may delete or merge records (decide it in the proxy's `autho
 ## Cross-block glue
 
 - `ContactLookupLink` (`components/contact-lookup-link.tsx`): "Open contact" for something that only knows an email (an inbox thread, a meeting attendee). It looks the email up (`GET /contacts?email=`) and shows a button only when a contact has it; `onOpen(contactId)` routes to your contacts screen. `ContactsScreen.onOpenCompany`, `CompaniesScreen.onOpenContact` and `TasksScreen.onOpenRecord` are the other ends of the same links: the stack pages pass them (`router.push("/companies?id=...")`).
+- `ContactLookupLink` can also create: pass `createIfMissing` (optionally with the sender's `firstName`/`lastName`) and a stranger gets "Add to contacts" (`POST /contacts`, then it opens the new contact). Nothing is offered while the lookup loads or after it failed.
+- `RecordOpenLinks` (`components/record-open-links.tsx`): "Open contact" and "Open company" for something that only knows ids (a call log entry, a visitor). The ids are verified with `GET /contacts/{id}` and `GET /companies/{id}` first (optionally against an expected company domain or contact name), so a link never points at a missing or wrong record.
 
 - `RecordEngagementTab` (`components/record-engagement-tab.tsx`): engagement counts, last touch (contacts) and pages visited for a contact or company, an `extraDetailTabs` entry: `{ id: "engagement", label: "Engagement", render: (c) => <RecordEngagementTab kind="contacts" id={c.id} /> }`. Reads `getContactEngagementSummary` / `getCompanyEngagementSummary` and `getContactSitesVisited` / `getCompanySitesVisited`. Also: the contact subtitle is `contactSubtitle(contact)` ("VP of Sales at Acme"; the company is never the person's own name, and "at" is left out without a company).

package/blocks/crm/block.json

@@ -10,7 +10,12 @@
     "CSV/Excel import wizard with column mapping and preview",
     "duplicate review with merge, bulk merge and undo",
     "locked (masked) emails and phones shown as Locked, never as values",
-    "finished ContactsScreen, CompaniesScreen and TasksScreen (list, detail, create, edit, delete, import, duplicates)"
+    "finished ContactsScreen, CompaniesScreen and TasksScreen (list, detail, create, edit, delete, import, duplicates)",
+    "assign owner to all contacts of a list with an injected team-member picker (never for a selection), confirmed with the list and N",
+    "contact tags: chips on the contact, add or remove on a selection, and a tag manager (create, rename, recolour, archive, delete, merge)",
+    "bulk edit of one field on a selection",
+    "verify emails and unlock locked contacts, each confirmed with the real count and cost",
+    "AI documents, signals and an on-demand next best step on the open contact"
   ],
   "dependsOn": [
     "foundation"
@@ -20,9 +25,13 @@
     "assert_company_companies_assert_put",
     "assert_contact_contacts_assert_put",
     "assert_contacts_batch_contacts_assert_batch_put",
+    "assign_contact_owner_contacts_assign_owner_post",
+    "assign_contact_tags_contacts_tags_assign_post",
+    "bulk_update_contacts_contacts_bulk_update_post",
     "create_company_companies_post",
     "create_company_note_companies__company_id__notes_post",
     "create_company_task_companies__company_id__tasks_post",
+    "create_contact_tag_contacts_tags_post",
     "create_contacts_contacts_post",
     "create_field_fields_post",
     "create_global_task_tasks_post",
@@ -31,17 +40,25 @@
     "create_task_contacts__contact_id__tasks_post",
     "delete_company_companies__company_id__delete",
     "delete_contact_contacts__contact_id__delete",
+    "delete_contact_tag_contacts_tags__tag_id__delete",
     "delete_note_notes__note_id__delete",
     "delete_task_tasks__task_id__delete",
     "duplicate_counts_duplicates_counts_get",
+    "generate_all_contact_documents_contacts__contact_id__documents_generate_all_post",
+    "generate_contact_document_contacts__contact_id__documents_types__doc_type__generate_post",
     "get_activity_feed_activity_feed_get",
     "get_bulk_merge_status_duplicates_bulk_merge__run_id__get",
     "get_company_companies__company_id__get",
     "get_company_engagement_summary_companies__company_id__engagement_summary_get",
     "get_company_sites_visited_companies__company_id__sites_visited_get",
     "get_contact_contacts__contact_id__get",
+    "get_contact_document_contacts__contact_id__documents_types__doc_type__get",
     "get_contact_engagement_summary_contacts__contact_id__engagement_summary_get",
+    "get_contact_generation_status_contacts__contact_id__documents_generation_status_get",
+    "get_contact_next_best_step_contacts__contact_id__next_best_step_get",
+    "get_contact_signals_contacts__contact_id__signals_get",
     "get_contact_sites_visited_contacts__contact_id__sites_visited_get",
+    "get_contact_tag_ids_contacts__contact_id__tags_get",
     "get_task_tasks__task_id__get",
     "import_contacts_imports__import_id__contacts_post",
     "list_all_tasks_tasks_get",
@@ -50,6 +67,7 @@
     "list_company_notes_companies__company_id__notes_get",
     "list_company_tasks_companies__company_id__tasks_get",
     "list_contact_fields_fields_get",
+    "list_contact_tags_contacts_tags_get",
     "list_contact_tasks_contacts__contact_id__tasks_get",
     "list_contacts_contacts_get",
     "list_duplicates_duplicates_get",
@@ -58,16 +76,22 @@
     "list_recent_merges_duplicates_recent_merges_get",
     "merge_company_companies__company_id__merge_post",
     "merge_contact_contacts__contact_id__merge_post",
+    "merge_contact_tags_contacts_tags_merge_post",
     "preview_import_file_imports__import_id__preview_post",
+    "regenerate_contact_document_contacts__contact_id__documents_types__doc_type__regenerate_post",
     "reject_suggestion_duplicates__suggestion_id__reject_post",
     "set_field_values_batch_fields_values_batch_patch",
     "start_bulk_merge_duplicates_bulk_merge_post",
+    "unassign_contact_tags_contacts_tags_unassign_post",
     "undo_merge_duplicates_undo_merge__merge_history_id__post",
+    "unlock_contact_info_contacts_unlock_info_post",
     "update_company_companies__company_id__patch",
     "update_contact_contacts__contact_id__patch",
+    "update_contact_tag_contacts_tags__tag_id__patch",
     "update_note_notes__note_id__patch",
     "update_task_tasks__task_id__patch",
-    "upload_import_file_imports_post"
+    "upload_import_file_imports_post",
+    "verify_contact_emails_contacts_verify_email_post"
   ],
   "components": [
     {
@@ -268,15 +292,36 @@
     {
       "name": "ContactsScreen",
       "file": "components/contacts-screen.tsx",
-      "purpose": "Finished contacts workspace: search, filters, sort, paging, bulk delete, detail panel with activity/notes/tasks, create, edit, CSV import and duplicate review. No required props; slot props for other blocks.",
+      "purpose": "Finished contacts workspace: search, filters, sort, paging, owner column, bulk delete, detail panel with activity/notes/tasks/AI documents/insights, create, edit, CSV import and duplicate review, plus record actions: assign owner to a whole list (with an injected picker), tags (chips, bulk, manager), bulk edit, verify email and unlock info. No required props; slot props for other blocks.",
       "operations": [
+        "assign_contact_owner_contacts_assign_owner_post",
+        "assign_contact_tags_contacts_tags_assign_post",
+        "bulk_update_contacts_contacts_bulk_update_post",
+        "create_contact_tag_contacts_tags_post",
         "delete_contact_contacts__contact_id__delete",
+        "delete_contact_tag_contacts_tags__tag_id__delete",
         "duplicate_counts_duplicates_counts_get",
+        "generate_all_contact_documents_contacts__contact_id__documents_generate_all_post",
+        "generate_contact_document_contacts__contact_id__documents_types__doc_type__generate_post",
         "get_contact_contacts__contact_id__get",
-        "list_contacts_contacts_get"
+        "get_contact_document_contacts__contact_id__documents_types__doc_type__get",
+        "get_contact_generation_status_contacts__contact_id__documents_generation_status_get",
+        "get_contact_next_best_step_contacts__contact_id__next_best_step_get",
+        "get_contact_signals_contacts__contact_id__signals_get",
+        "get_contact_tag_ids_contacts__contact_id__tags_get",
+        "list_contact_tags_contacts_tags_get",
+        "list_contacts_contacts_get",
+        "merge_contact_tags_contacts_tags_merge_post",
+        "regenerate_contact_document_contacts__contact_id__documents_types__doc_type__regenerate_post",
+        "unassign_contact_tags_contacts_tags_unassign_post",
+        "unlock_contact_info_contacts_unlock_info_post",
+        "update_contact_tag_contacts_tags__tag_id__patch",
+        "verify_contact_emails_contacts_verify_email_post"
       ],
       "tiers": [
         "read",
+        "write",
+        "billable",
         "destructive"
       ]
     },
@@ -326,10 +371,24 @@
     {
       "name": "ContactLookupLink",
       "file": "components/contact-lookup-link.tsx",
-      "purpose": "\"Open contact\" button for something that only knows an email (inbox thread, meeting attendee, visitor): looks the email up in the CRM and calls onOpen(contactId); renders nothing when nobody has it.",
+      "purpose": "\"Open contact\" button for something that only knows an email (inbox thread, meeting attendee, visitor, form submission): looks the email up in the CRM and calls onOpen(contactId); renders nothing when nobody has it, or with createIfMissing offers \"Add to contacts\" (creates the contact from the email and opens it).",
       "operations": [
+        "create_contacts_contacts_post",
         "list_contacts_contacts_get"
       ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "RecordOpenLinks",
+      "file": "components/record-open-links.tsx",
+      "purpose": "\"Open contact\" and \"Open company\" buttons for something that only knows ids (a call log entry, a website visitor). The ids are verified against the CRM first (and a company's domain, when given), so a button never points at a missing or wrong record.",
+      "operations": [
+        "get_company_companies__company_id__get",
+        "get_contact_contacts__contact_id__get"
+      ],
       "tiers": [
         "read"
       ]
@@ -347,6 +406,133 @@
       "tiers": [
         "read"
       ]
+    },
+    {
+      "name": "OwnerAssignListButton",
+      "file": "components/owner-assign.tsx",
+      "purpose": "\"Assign owner to all N contacts in this list\" with an injected team-member picker (renderPicker), hidden without one. Never for a selection: the API assigns by filter. Both assign and remove are confirmed with the list and N.",
+      "operations": [
+        "assign_contact_owner_contacts_assign_owner_post"
+      ],
+      "tiers": [
+        "write"
+      ]
+    },
+    {
+      "name": "ContactTagChips",
+      "file": "components/contact-tag-chips.tsx",
+      "purpose": "The tags on one contact as chips with remove buttons and an Add tag picker that can create a tag.",
+      "operations": [
+        "assign_contact_tags_contacts_tags_assign_post",
+        "create_contact_tag_contacts_tags_post",
+        "get_contact_tag_ids_contacts__contact_id__tags_get",
+        "list_contact_tags_contacts_tags_get",
+        "unassign_contact_tags_contacts_tags_unassign_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "TagAssignButton",
+      "file": "components/tag-assign.tsx",
+      "purpose": "Add tags to, or remove tags from, a selection of contacts.",
+      "operations": [
+        "assign_contact_tags_contacts_tags_assign_post",
+        "list_contact_tags_contacts_tags_get",
+        "unassign_contact_tags_contacts_tags_unassign_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "TagManager",
+      "file": "components/tag-manager.tsx",
+      "purpose": "Create, rename, recolour, archive, delete and merge contact tags. Delete and merge are confirmed.",
+      "operations": [
+        "create_contact_tag_contacts_tags_post",
+        "delete_contact_tag_contacts_tags__tag_id__delete",
+        "list_contact_tags_contacts_tags_get",
+        "merge_contact_tags_contacts_tags_merge_post",
+        "update_contact_tag_contacts_tags__tag_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "BulkUpdateButton",
+      "file": "components/bulk-update.tsx",
+      "purpose": "Set one field (title, department, seniority, city, state, country) on every selected contact.",
+      "operations": [
+        "bulk_update_contacts_contacts_bulk_update_post"
+      ],
+      "tiers": [
+        "write"
+      ]
+    },
+    {
+      "name": "VerifyEmailButton",
+      "file": "components/verify-email-button.tsx",
+      "purpose": "Verify the work emails of a selection (billable, confirmed with the real count and cost).",
+      "operations": [
+        "verify_contact_emails_contacts_verify_email_post"
+      ],
+      "tiers": [
+        "billable"
+      ]
+    },
+    {
+      "name": "UnlockInfoButton",
+      "file": "components/unlock-info-button.tsx",
+      "purpose": "Unlock the locked contacts of a selection (billable, confirmed with the locked count and cost).",
+      "operations": [
+        "unlock_contact_info_contacts_unlock_info_post"
+      ],
+      "tiers": [
+        "billable"
+      ]
+    },
+    {
+      "name": "ContactRowActions",
+      "file": "components/contact-row-actions.tsx",
+      "purpose": "The row's ... button: owner, tags, verify and unlock for one contact.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "ContactDocumentsTab",
+      "file": "components/contact-documents-tab.tsx",
+      "purpose": "AI documents about one contact: status, write, rewrite, write all (billable, confirmed) and read.",
+      "operations": [
+        "generate_all_contact_documents_contacts__contact_id__documents_generate_all_post",
+        "generate_contact_document_contacts__contact_id__documents_types__doc_type__generate_post",
+        "get_contact_document_contacts__contact_id__documents_types__doc_type__get",
+        "get_contact_generation_status_contacts__contact_id__documents_generation_status_get",
+        "regenerate_contact_document_contacts__contact_id__documents_types__doc_type__regenerate_post"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "ContactInsightsTab",
+      "file": "components/contact-insights-tab.tsx",
+      "purpose": "Signals for one contact and an on-demand next best step (billable, confirmed).",
+      "operations": [
+        "get_contact_next_best_step_contacts__contact_id__next_best_step_get",
+        "get_contact_signals_contacts__contact_id__signals_get"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
     }
   ],
   "hooks": [
@@ -373,6 +559,14 @@
       "name": "useAllLists",
       "file": "hooks/use-all-lists.ts",
       "purpose": "Every list, page after page, for lookups by id (a list's size or name); ListSelect is the picker."
+    },
+    {
+      "name": "useContactTags",
+      "file": "hooks/use-contact-tags.ts",
+      "purpose": "The org's contact tags with counts, cached so chips, dialogs and the manager refresh together.",
+      "operations": [
+        "list_contact_tags_contacts_tags_get"
+      ]
     }
   ],
   "lib": [
@@ -387,6 +581,10 @@
     {
       "file": "lib/read-lists.ts",
       "purpose": "One page of audience lists (GET /lists), the read behind ListSelect and useAllLists."
+    },
+    {
+      "file": "lib/record-actions.ts",
+      "purpose": "Tag type, the id-set grid filter, the paid-batch cap, unlock and verify target sets and cost constants, bulk-edit fields and the verify summary, shared by the record-action components."
     }
   ],
   "recipes": [
@@ -421,7 +619,7 @@
     {
       "id": "api-key-scopes",
       "where": "api",
-      "description": "The server API key carries the scopes in this block's `scopes` (contacts, companies, lists and notes/tasks read+write; contacts:delete for bulk merge).",
+      "description": "The server API key carries the scopes in this block's `scopes` (contacts, companies, lists and notes/tasks read+write; contacts:delete for bulk merge; enrichment:run for verify email, unlock info, AI documents and next best step, all of which spend credits).",
       "verify": "recipes/verify-proxy-key.ts passes and g8.api.me.describeCurrentKey() lists the scopes."
     },
     {
@@ -438,6 +636,7 @@
     "contacts:delete",
     "contacts:read",
     "contacts:write",
+    "enrichment:run",
     "fields:read",
     "fields:write",
     "lists:read",