@graph8/sdk 0.303.0 → 0.357.0

package/blocks/lifecycle/recipes/unlock-stage-contacts.ts

@@ -0,0 +1,25 @@
+/**
+ * @title List a stage's locked contacts, then unlock the ones the person chose
+ * @when The customer needs the real emails and phones of contacts in a stage. Details arrive masked as "***" until a
+ * contact is unlocked, and unlocking charges credits per NEWLY unlocked contact (billable tier). Two steps on purpose:
+ * `listLocked` is free; call `unlock` only with the ids the person agreed to pay for. `lifecycle_id` is the stage ENTRY id.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+type Contact = { id: number; email?: string | null };
+
+export async function listLocked(stageSlug: string, limit = 50): Promise<{ stageId: string; lockedIds: number[] }> {
+  const stages = (await g8.api.revenueLifecycle.listLifecycleStages({})).data;
+  const stage = stages.find((s) => s.slug === stageSlug);
+  if (!stage) throw new Error(`No lifecycle stage "${stageSlug}"`);
+  const res = (await g8.api.revenueRecords.listLifecycleContacts({ query: { lifecycle_id: stage.id, limit } })) as { data?: { contacts?: Contact[] } };
+  return { stageId: stage.id, lockedIds: (res.data?.contacts ?? []).filter((c) => c.email === "***").map((c) => c.id) };
+}
+
+export async function unlock(stageId: string, contactIds: number[]): Promise<number | undefined> {
+  if (contactIds.length === 0) return 0;
+  const out = (await g8.api.revenueRecords.unlockLifecycleContacts({ body: { lifecycle_id: stageId, contact_ids: contactIds } })) as { data?: { credits_charged?: number } };
+  return out.data?.credits_charged;
+}

package/blocks/lists/README.md

@@ -0,0 +1,96 @@
+# lists: lists and suppressions
+
+Lists are how everything downstream (sequences, campaigns, newsletters, dialer queues) picks its audience, and
+suppressions are the do-not-contact guard those same flows obey. This block gives you the screens for both.
+It builds on the `crm` block (the members panel is a `ContactTable`).
+
+Install: `npx @graph8/sdk add lists` (installs `foundation` and `crm` first).
+
+## What you get
+
+| Component | Use it for | Embed props |
+|---|---|---|
+| `ListTable` | All lists: counts, status, create / rename / delete, members side panel with remove-from-list | `onOpen`, `allowCreate`, `pageSize`, `refreshKey` |
+| `ListPicker` | Choose a destination list (search, or create one inline) | `value`, `onChange`, `type`, `allowCreate`, `suggestedName` |
+| `AddToListButton` | "Add to list" for a selection of contacts | `contactIds`, `listId`, `onAdded`, `label` |
+| `SuppressionManager` | The do-not-contact ledger: filter, suppress by id, check, reinstate | `onOpenContact`, `pageSize` |
+
+## The flow, with the ids that pass between steps
+
+1. **Index**: `GET /lists?page&limit&search` returns lists with `id`, `title`, `type`, `total`, `status`,
+   `status_reason` (why a list failed or is stuck), `is_dynamic`.
+2. **Create**: `POST /lists { title, type: "contacts" | "companies" }` returns the new list `id`.
+3. **Fill**: `POST /lists/{list_id}/contacts { contact_ids }` (the ids come from a `ContactTable` selection or a
+   contact read). The answer says `added`, `already_member`, `not_found`. A `409` with
+   `detail.code === "CONFLICT_REVIEW_REQUIRED"` means some contacts belong to other reps: `AddToListButton`
+   shows `ready_count / warned / blocked` and retries with `conflict_resolution: "skip_all" | "add_all"`.
+4. **Members**: `ContactTable listId={id}` (or `GET /contacts?list_id=`). Removing uses
+   `DELETE /lists/{list_id}/contacts { contact_ids }`; contacts are never deleted by it.
+5. **Suppress**: `POST /contacts/suppressions/bulk-add { contact_ids, channel, reason }`; read back with
+   `GET /contacts/suppressions`. The ledger has ids only (no names or emails): open the contact for details.
+6. **Reinstate**: `POST /contacts/suppressions/reinstate { contact_ids }`. Contacts who unsubscribed themselves
+   can be refused; the answer lists them in `skipped`.
+
+```tsx
+"use client";
+import { ContactTable } from "@/components/g8/crm/contact-table";
+import { AddToListButton } from "@/components/g8/lists/add-to-list-button";
+
+export function Prospects() {
+  return (
+    <ContactTable selectable customFields
+      renderBulkActions={({ ids, clear }) => <AddToListButton contactIds={ids} onAdded={clear} />} />
+  );
+}
+```
+
+(`add` installs under `components/g8/lists/`, or `src/components/g8/lists/`; adjust the alias.)
+
+## Tiers and confirmations
+
+- Create, rename and add/remove membership are writes: the dialog you open is the confirmation.
+- `ListTable`: deleting a list and removing members are `destructive` and go through `ConfirmSpendDialog`.
+  Neither deletes contacts.
+- `SuppressionManager`: suppressing only reduces outreach, so it runs directly. Reinstating (write tier) lets
+  sequences and campaigns contact people again, so it is confirmed with `ConfirmSpendDialog` as `external`.
+
+## Prerequisites
+
+- `crm-installed` (app): `components/g8/crm/contact-table.tsx` exists (the CLI installs it).
+- `proxy-allowlist` (app): `allowedPrefixes` includes `lists` and `contacts`.
+- `suppression-permission` (api): the key has `contacts:write`, `lists:write`, `lists:delete`.
+
+## Defaults the agent can use without asking
+
+| Decision | Default |
+|---|---|
+| Type of a new list | `contacts` |
+| Channel when suppressing | `all` |
+| Rep conflicts when adding | show the counts and let the person choose |
+
+Ask the person: who may reinstate suppressed contacts (decide it in the proxy's `authorize`).
+
+## Recipes
+
+| File | Does |
+|---|---|
+| `recipes/create-list-and-add-contacts.ts` | Create a list, add contacts, handle the 409 review, read and remove members |
+| `recipes/suppress-and-reinstate.ts` | Bulk suppress, check, list by channel, reinstate (after approval) |
+| `recipes/refresh-and-check-lists.ts` | Refresh a dynamic list; read-only integrity check |
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| listLists | GET /lists | read | ListTable, ListPicker, AddToListButton |
+| createList | POST /lists | write | ListTable, ListPicker, AddToListButton |
+| updateList | PATCH /lists/{list_id} | write | ListTable |
+| deleteList | DELETE /lists/{list_id} | destructive | ListTable |
+| addContactsToList | POST /lists/{list_id}/contacts | write | AddToListButton |
+| removeContactsFromList | DELETE /lists/{list_id}/contacts | destructive | ListTable |
+| listContacts | GET /contacts?list_id= | read | ListTable (members panel) |
+| listSuppressions | GET /contacts/suppressions | read | SuppressionManager |
+| bulkAddSuppressions | POST /contacts/suppressions/bulk-add | write | SuppressionManager |
+| checkContactSuppression | GET /contacts/{contact_id}/suppression | read | SuppressionManager |
+| reinstateSuppressions | POST /contacts/suppressions/reinstate | write | SuppressionManager |
+| refreshDynamicList, checkListIntegrity | POST /lists/{id}/refresh, /lists/{id}/integrity-check | write, read | recipes |

package/blocks/lists/block.json

@@ -0,0 +1,166 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "lists",
+  "title": "Lists & suppressions",
+  "summary": "List table with members panel, list picker, add-to-list button and a do-not-contact suppression manager.",
+  "features": [
+    "list index with member counts, status, create, rename and delete",
+    "members panel built on the CRM ContactTable with remove-from-list",
+    "ListPicker (search or create) and AddToListButton for any contact selection",
+    "conflict review when contacts belong to other reps",
+    "suppression ledger by channel and reason, bulk suppress, check, reinstate"
+  ],
+  "dependsOn": [
+    "crm"
+  ],
+  "operations": [
+    "add_contacts_to_list_lists__list_id__contacts_post",
+    "bulk_add_suppressions_contacts_suppressions_bulk_add_post",
+    "check_contact_suppression_contacts__contact_id__suppression_get",
+    "check_list_integrity_lists__list_id__integrity_check_post",
+    "create_list_lists_post",
+    "delete_list_lists__list_id__delete",
+    "list_contact_fields_fields_get",
+    "list_contacts_contacts_get",
+    "list_lists_lists_get",
+    "list_suppressions_contacts_suppressions_get",
+    "refresh_dynamic_list_lists__audience_id__refresh_post",
+    "reinstate_suppressions_contacts_suppressions_reinstate_post",
+    "remove_contacts_from_list_lists__list_id__contacts_delete",
+    "update_list_lists__list_id__patch"
+  ],
+  "components": [
+    {
+      "name": "ListTable",
+      "file": "components/list-table.tsx",
+      "purpose": "All lists with counts and status; create, rename, delete; side panel with the list's members (CRM ContactTable) and remove-from-list.",
+      "operations": [
+        "list_lists_lists_get",
+        "create_list_lists_post",
+        "update_list_lists__list_id__patch",
+        "delete_list_lists__list_id__delete",
+        "remove_contacts_from_list_lists__list_id__contacts_delete",
+        "list_contacts_contacts_get",
+        "list_contact_fields_fields_get"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "ListPicker",
+      "file": "components/list-picker.tsx",
+      "purpose": "Search lists and pick one, or create a new list inline. The destination chooser for every save-to-list flow.",
+      "operations": [
+        "list_lists_lists_get",
+        "create_list_lists_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "AddToListButton",
+      "file": "components/add-to-list-button.tsx",
+      "purpose": "Add a selection of contacts to a list from a dialog; reports added, already-member and not-found, and handles the rep-conflict review.",
+      "operations": [
+        "list_lists_lists_get",
+        "create_list_lists_post",
+        "add_contacts_to_list_lists__list_id__contacts_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "SuppressionManager",
+      "file": "components/suppression-manager.tsx",
+      "purpose": "The do-not-contact ledger: filter by channel and reason, suppress by id, check a contact, reinstate (confirmed).",
+      "operations": [
+        "list_suppressions_contacts_suppressions_get",
+        "bulk_add_suppressions_contacts_suppressions_bulk_add_post",
+        "check_contact_suppression_contacts__contact_id__suppression_get",
+        "reinstate_suppressions_contacts_suppressions_reinstate_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    }
+  ],
+  "hooks": [],
+  "recipes": [
+    {
+      "file": "recipes/create-list-and-add-contacts.ts",
+      "title": "Create a list, add contacts to it and read the members",
+      "when": "Grouping people for a sequence, campaign or export. A list's `type` is `contacts` or `companies`. The list id comes from the create response; contact ids come from a contact read or search, never a guess. Adding is idempotent: contacts already in the list are reported in `already_member`, ids that do not exist in `not_found`. Contacts owned by other reps can answer 409 CONFLICT_REVIEW_REQUIRED: repeat the call with `conflict_resolution` once a person decided."
+    },
+    {
+      "file": "recipes/suppress-and-reinstate.ts",
+      "title": "Suppress contacts and reinstate them later",
+      "when": "Honouring an opt-out, a bounce or a \"do not call\" request. Suppression is respected by every sequence, campaign and newsletter. Reinstating lets outreach resume, so ask a human first. The ledger holds contact ids only; resolve names with `g8.contacts.get`."
+    },
+    {
+      "file": "recipes/refresh-and-check-lists.ts",
+      "title": "Refresh a dynamic list and check a list's health",
+      "when": "A list is built from filters (dynamic) and must be re-evaluated, or a list looks wrong (stuck importing, member count off). `refresh` re-runs the filters; the integrity check is read-only and reports problems without changing anything."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "crm-installed",
+      "where": "app",
+      "description": "The crm block is installed (the CLI does it): ListTable embeds its ContactTable.",
+      "verify": "components/g8/crm/contact-table.tsx exists."
+    },
+    {
+      "id": "proxy-allowlist",
+      "where": "app",
+      "description": "allowedPrefixes in the /api/g8 route includes `lists` and `contacts` (suppressions live under /contacts/suppressions).",
+      "verify": "GET /api/g8/lists?limit=1 and GET /api/g8/contacts/suppressions?limit=1 return 200 when signed in."
+    },
+    {
+      "id": "suppression-permission",
+      "where": "api",
+      "description": "The API key can write contacts (suppress and reinstate need contacts:write) and lists (lists:write, lists:delete).",
+      "verify": "g8.api.me.describeCurrentKey() lists contacts:write, lists:write and lists:delete."
+    }
+  ],
+  "scopes": [
+    "contacts:read",
+    "contacts:write",
+    "fields:read",
+    "lists:delete",
+    "lists:read",
+    "lists:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Type of a newly created list",
+      "default": "contacts",
+      "askHuman": false
+    },
+    {
+      "decision": "Channel when suppressing",
+      "default": "all (every channel)",
+      "askHuman": false
+    },
+    {
+      "decision": "Conflicting contacts (owned by other reps) when adding to a list",
+      "default": "Show the counts and let the person pick 'ready only' or 'ready and flagged'; never auto-pick",
+      "askHuman": false
+    },
+    {
+      "decision": "Who may reinstate suppressed contacts",
+      "default": "Anyone passing the proxy's authorize; reinstating is confirmed in the UI",
+      "askHuman": true
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

package/blocks/lists/components/add-to-list-button.tsx

@@ -0,0 +1,111 @@
+"use client";
+
+/**
+ * AddToListButton: "Add to list" for any selection of contacts. Opens a dialog with
+ * ListPicker, adds the contacts, and reports what happened (added, already in the
+ * list, not found). Drop it into ContactTable's `renderBulkActions` or ContactDetail's
+ * `renderActions`.
+ *
+ * SDK operations, in order:
+ *   1. listLists / createList          via ListPicker                          (read, write)
+ *   2. addContactsToList   POST /lists/{list_id}/contacts  { contact_ids }     (write)
+ *      A 409 CONFLICT_REVIEW_REQUIRED (contacts owned by other reps) is shown with its counts and the
+ *      choice "add ready only" or "add ready and flagged"; the call is repeated with `conflict_resolution`.
+ *
+ * Adding is a write the person just chose in the dialog, so it needs no extra confirmation. Saving a
+ * contact to a list is also how locked ("***") search results become real records.
+ */
+
+import { useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Post } from "@/g8/lib/g8-client";
+import { ListPicker } from "./list-picker";
+import type { ListSummary } from "./list-picker";
+
+export interface AddToListResult {
+  listId: number;
+  added: number;
+  already_member: number[];
+  not_found: number[];
+}
+
+export interface AddToListButtonProps {
+  contactIds: number[];
+  /** Skip the picker and add straight into this list. */
+  listId?: number;
+  label?: string;
+  variant?: "default" | "outline" | "secondary" | "ghost";
+  size?: "default" | "sm";
+  disabled?: boolean;
+  onAdded?: (result: AddToListResult) => void;
+  className?: string;
+}
+
+interface ConflictDetail { code?: string; ready_count?: number; warned?: unknown[]; blocked?: unknown[]; message?: string }
+type Resolution = "add_all" | "skip_all";
+
+function conflictOf(error: unknown): ConflictDetail | null {
+  const e = error as { status?: number; detail?: ConflictDetail } | null;
+  return e?.status === 409 && e.detail && typeof e.detail === "object" && e.detail.code === "CONFLICT_REVIEW_REQUIRED" ? e.detail : null;
+}
+
+export function AddToListButton({ contactIds, listId, label = "Add to list", variant = "outline", size = "sm", disabled, onAdded, className }: AddToListButtonProps) {
+  const [open, setOpen] = useState(false);
+  const [target, setTarget] = useState<ListSummary | null>(null);
+  const [result, setResult] = useState<AddToListResult | null>(null);
+  const destination = listId ?? target?.id;
+
+  const add = useG8Mutation(async (resolution?: Resolution) => {
+    const res = await g8Post<{ added: number; already_member?: number[]; not_found?: number[] }>(`/lists/${destination}/contacts`, {
+      contact_ids: contactIds,
+      ...(resolution ? { conflict_resolution: resolution } : {}),
+    });
+    return { listId: destination as number, added: res.data.added, already_member: res.data.already_member ?? [], not_found: res.data.not_found ?? [] };
+  }, { onSuccess: (r) => { setResult(r); onAdded?.(r); } });
+
+  const conflict = conflictOf(add.error);
+  const close = () => { setOpen(false); setResult(null); setTarget(null); add.reset(); };
+
+  return (
+    <>
+      <Button className={className} variant={variant} size={size} disabled={disabled || contactIds.length === 0} onClick={() => setOpen(true)}>{label}</Button>
+      <Dialog open={open} onOpenChange={(o) => (o ? setOpen(true) : close())}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Add {contactIds.length.toLocaleString()} contact{contactIds.length === 1 ? "" : "s"} to a list</DialogTitle>
+            <DialogDescription>Contacts already in the list are skipped.</DialogDescription>
+          </DialogHeader>
+
+          {result ? (
+            <div role="status" className="text-sm">
+              <p className="font-medium">Added {result.added.toLocaleString()} to the list.</p>
+              {result.already_member.length ? <p className="text-muted-foreground">{result.already_member.length} were already in it.</p> : null}
+              {result.not_found.length ? <p className="text-muted-foreground">{result.not_found.length} no longer exist.</p> : null}
+            </div>
+          ) : (
+            <>
+              {listId == null ? <ListPicker value={target?.id} onChange={(l) => { setTarget(l); add.reset(); }} /> : null}
+              {conflict ? (
+                <div role="alert" className="rounded-md border border-amber-300 bg-amber-50 p-3 text-sm">
+                  <p>{conflict.message ?? "Some contacts belong to other reps."}</p>
+                  <p className="mt-1">{conflict.ready_count ?? 0} ready, {conflict.warned?.length ?? 0} flagged, {conflict.blocked?.length ?? 0} blocked (never added).</p>
+                  <div className="mt-2 flex gap-2">
+                    <Button size="sm" variant="outline" loading={add.loading} onClick={() => void add.mutate("skip_all")}>Add ready only</Button>
+                    <Button size="sm" loading={add.loading} onClick={() => void add.mutate("add_all")}>Add ready and flagged</Button>
+                  </div>
+                </div>
+              ) : add.error ? <ApiError error={add.error} title="Could not add the contacts" /> : null}
+            </>
+          )}
+
+          <DialogFooter>
+            <Button variant="ghost" onClick={close}>{result ? "Done" : "Cancel"}</Button>
+            {!result ? <Button loading={add.loading && !conflict} disabled={destination == null} onClick={() => void add.mutate(undefined)}>Add to list</Button> : null}
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}

package/blocks/lists/components/list-picker.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+/**
+ * ListPicker: search lists by name, pick one, or create a new one on the spot.
+ * The destination chooser for every "save to a list" flow (AddToListButton,
+ * search results, import, sequence enrollment).
+ *
+ * SDK operations, in order:
+ *   1. listLists    GET  /lists?search&limit   (read)   lists of the wanted `type`
+ *   2. createList   POST /lists                (write)  only when `allowCreate`; the new list is selected at once
+ *
+ * Creating a list is a write that is easy to undo, so it does not need ConfirmSpendDialog.
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Input } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+
+export interface ListSummary {
+  id: number;
+  title: string;
+  type?: string | null;
+  description?: string | null;
+  status?: string | null;
+  status_reason?: string | null;
+  status_detail?: string | null;
+  total?: number;
+  contact_count?: number | null;
+  company_count?: number | null;
+  is_dynamic?: boolean;
+  created_at?: string | null;
+  updated_at?: string | null;
+}
+
+export interface ListPickerProps {
+  /** Selected list id. */
+  value?: number | null;
+  onChange: (list: ListSummary) => void;
+  /** Only lists of this type. Default "contacts". */
+  type?: "contacts" | "companies";
+  allowCreate?: boolean;
+  /** Pre-fill the new list name (for example "Search: VPs in fintech"). */
+  suggestedName?: string;
+  className?: string;
+}
+
+function useDebounced<T>(value: T, ms = 250): T {
+  const [v, setV] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setV(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return v;
+}
+
+export function ListPicker({ value, onChange, type = "contacts", allowCreate = true, suggestedName, className }: ListPickerProps) {
+  const [search, setSearch] = useState("");
+  const [newName, setNewName] = useState(suggestedName ?? "");
+  const q = useDebounced(search.trim());
+  const lists = useG8Query((signal) => g8Get<ListSummary[]>("/lists", { search: q || undefined, limit: 50 }, { signal }), [q]);
+  const create = useG8Mutation((title: string) => g8Post<ListSummary>("/lists", { title, type }), {
+    onSuccess: (res) => { setNewName(""); void lists.refetch(); onChange({ type, ...res.data, title: res.data.title ?? newName }); },
+  });
+
+  const rows = ((lists.data?.data ?? []) as ListSummary[]).filter((l) => !l.type || l.type === type);
+  return (
+    <div className={`flex flex-col gap-2 ${className ?? ""}`}>
+      <Input aria-label="Search lists" placeholder="Search lists" value={search} onChange={(e) => setSearch(e.target.value)} />
+      {lists.error ? <ApiError error={lists.error} title="Could not load lists" onRetry={() => void lists.refetch()} /> : null}
+      <ul role="listbox" aria-label="Lists" className="max-h-56 overflow-y-auto rounded-md border">
+        {lists.loading && rows.length === 0 ? <li className="p-3 text-sm text-muted-foreground">Loading lists...</li> : null}
+        {!lists.loading && !lists.error && rows.length === 0 ? <li className="p-3 text-sm text-muted-foreground">{q ? "No list matches." : "No lists yet."}</li> : null}
+        {rows.map((l) => (
+          <li key={l.id} role="option" aria-selected={l.id === value}>
+            <button type="button" className={`flex w-full items-center justify-between px-3 py-2 text-left text-sm hover:bg-accent ${l.id === value ? "bg-accent font-medium" : ""}`} onClick={() => onChange(l)}>
+              <span className="truncate">{l.title}</span>
+              <span className="text-xs text-muted-foreground">{(l.total ?? 0).toLocaleString()}</span>
+            </button>
+          </li>
+        ))}
+      </ul>
+      {allowCreate ? (
+        <form className="flex items-center gap-2" onSubmit={(e) => { e.preventDefault(); if (newName.trim()) void create.mutate(newName.trim()); }}>
+          <Input aria-label="New list name" placeholder="Or create a new list" value={newName} onChange={(e) => setNewName(e.target.value)} />
+          <Button type="submit" variant="outline" size="sm" loading={create.loading} disabled={!newName.trim()}>Create</Button>
+        </form>
+      ) : null}
+      {create.error ? <ApiError error={create.error} title="Could not create the list" /> : null}
+    </div>
+  );
+}

package/blocks/lists/components/list-table.tsx

@@ -0,0 +1,160 @@
+"use client";
+
+/**
+ * ListTable: all lists with member counts and status, create / rename / delete, and a
+ * side panel with the list's members (a ContactTable) where selected contacts can be
+ * removed from the list.
+ *
+ * SDK operations, in order:
+ *   1. listLists               GET    /lists?page&limit&search            (read)
+ *   2. createList              POST   /lists                              (write)
+ *   3. updateList              PATCH  /lists/{list_id}  { title, description }   (write)
+ *   4. deleteList              DELETE /lists/{list_id}                    (destructive, ConfirmSpendDialog)
+ *   5. listContacts            GET    /contacts?list_id=...  via ContactTable     (read)  members panel
+ *      removeContactsFromList  DELETE /lists/{list_id}/contacts  { contact_ids }  (destructive, ConfirmSpendDialog)
+ *
+ * Deleting a list never deletes its contacts; removing members from a list does not either.
+ * `status_reason` explains a list that failed to build or is stuck importing.
+ */
+
+import { useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, Input, Label, Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { ContactTable } from "@/g8/crm/components/contact-table";
+import { useDebouncedValue } from "@/g8/crm/hooks/use-debounced";
+import { usePageQuery } from "@/g8/crm/hooks/use-page-query";
+import type { ListSummary } from "./list-picker";
+
+export interface ListTableProps {
+  pageSize?: number;
+  /** Called when a list row is clicked. Without it, contact lists open the members panel. */
+  onOpen?: (list: ListSummary) => void;
+  allowCreate?: boolean;
+  refreshKey?: number;
+  className?: string;
+}
+
+function count(l: ListSummary): number {
+  return l.contact_count ?? l.company_count ?? l.total ?? 0;
+}
+
+const STATUS_STYLE: Record<string, string> = { failed: "text-destructive", processing: "text-amber-600" };
+
+export function ListTable({ pageSize = 25, onOpen, allowCreate = true, refreshKey, className }: ListTableProps) {
+  const [search, setSearch] = useState("");
+  const debouncedSearch = useDebouncedValue(search);
+  const [editing, setEditing] = useState<{ id?: number; title: string; description: string; type: "contacts" | "companies" } | null>(null);
+  const [deleting, setDeleting] = useState<ListSummary | null>(null);
+  const [members, setMembers] = useState<ListSummary | null>(null);
+  const [removing, setRemoving] = useState<number[] | null>(null);
+  const [membersKey, setMembersKey] = useState(0);
+
+  const lists = usePageQuery<ListSummary>(
+    (page, signal) => g8Get<ListSummary[]>("/lists", { page, limit: pageSize, search: debouncedSearch.trim() || undefined }, { signal }),
+    [debouncedSearch, refreshKey],
+    pageSize,
+  );
+  const save = useG8Mutation(
+    (v: NonNullable<typeof editing>) => (v.id ? g8Patch(`/lists/${v.id}`, { title: v.title, description: v.description }) : g8Post("/lists", { title: v.title, type: v.type, description: v.description || undefined })),
+    { onSuccess: () => { setEditing(null); void lists.refetch(); } },
+  );
+  const remove = useG8Mutation((id: number) => g8Delete(`/lists/${id}`), { onSuccess: () => { setDeleting(null); void lists.refetch(); } });
+  const removeMembers = useG8Mutation((v: { listId: number; ids: number[] }) => g8Delete(`/lists/${v.listId}/contacts`, { body: { contact_ids: v.ids } }), {
+    onSuccess: () => { setRemoving(null); setMembersKey((k) => k + 1); void lists.refetch(); },
+  });
+
+  const open = (l: ListSummary) => (onOpen ? onOpen(l) : l.type === "companies" ? undefined : setMembers(l));
+
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      <div className="flex flex-wrap items-center gap-2">
+        <Input aria-label="Search lists" placeholder="Search lists" className="w-64" value={search} onChange={(e) => setSearch(e.target.value)} />
+        {allowCreate ? <Button className="ml-auto" size="sm" onClick={() => setEditing({ title: "", description: "", type: "contacts" })}>New list</Button> : null}
+      </div>
+      {lists.error ? <ApiError error={lists.error} title="Could not load lists" onRetry={() => void lists.refetch()} /> : null}
+      {remove.error ? <ApiError error={remove.error} title="Could not delete the list" /> : null}
+
+      <div className="rounded-md border">
+        <Table>
+          <TableHeader>
+            <TableRow><TableHead>Name</TableHead><TableHead>Type</TableHead><TableHead className="text-right">Members</TableHead><TableHead>Status</TableHead><TableHead>Updated</TableHead><TableHead className="w-32" /></TableRow>
+          </TableHeader>
+          <TableBody>
+            {lists.loading && lists.rows.length === 0
+              ? Array.from({ length: 4 }, (_, i) => <TableRow key={`sk${i}`}><TableCell colSpan={6}><Skeleton className="h-5 w-full" /></TableCell></TableRow>)
+              : lists.rows.map((l) => (
+                  <TableRow key={l.id} data-testid={`list-row-${l.id}`} className="cursor-pointer" onClick={() => open(l)}>
+                    <TableCell className="font-medium">{l.title}{l.is_dynamic ? <span className="ml-2 text-xs text-muted-foreground">dynamic</span> : null}</TableCell>
+                    <TableCell className="capitalize">{l.type ?? "-"}</TableCell>
+                    <TableCell className="text-right">{count(l).toLocaleString()}</TableCell>
+                    <TableCell className={STATUS_STYLE[l.status ?? ""] ?? ""} title={l.status_detail ?? undefined}>{l.status_reason ? l.status_reason.replace(/_/g, " ") : l.status ?? "-"}</TableCell>
+                    <TableCell>{l.updated_at ? new Date(l.updated_at).toLocaleDateString() : "-"}</TableCell>
+                    <TableCell onClick={(e) => e.stopPropagation()}>
+                      <Button variant="ghost" size="sm" onClick={() => setEditing({ id: l.id, title: l.title, description: l.description ?? "", type: l.type === "companies" ? "companies" : "contacts" })}>Edit</Button>
+                      <Button variant="ghost" size="sm" onClick={() => setDeleting(l)}>Delete</Button>
+                    </TableCell>
+                  </TableRow>
+                ))}
+          </TableBody>
+        </Table>
+        {!lists.loading && !lists.error && lists.rows.length === 0 ? (
+          <EmptyState title={search ? "No list matches" : "No lists yet"} description={search ? "Try another name." : "A list groups contacts for a campaign, sequence or export."}
+            action={!search && allowCreate ? <Button size="sm" onClick={() => setEditing({ title: "", description: "", type: "contacts" })}>Create a list</Button> : undefined} />
+        ) : null}
+      </div>
+
+      <div className="flex items-center justify-between text-sm text-muted-foreground">
+        <span>{lists.total.toLocaleString()} lists</span>
+        <div className="flex items-center gap-2">
+          <Button variant="outline" size="sm" disabled={lists.page <= 1 || lists.loading} onClick={() => lists.setPage(lists.page - 1)}>Previous</Button>
+          <span>Page {lists.page} of {lists.pageCount}</span>
+          <Button variant="outline" size="sm" disabled={!lists.hasNext || lists.loading} onClick={() => lists.setPage(lists.page + 1)}>Next</Button>
+        </div>
+      </div>
+
+      <Dialog open={editing != null} onOpenChange={(o) => !o && setEditing(null)}>
+        <DialogContent>
+          <DialogHeader><DialogTitle>{editing?.id ? "Edit list" : "New list"}</DialogTitle><DialogDescription>Give it a name your team will recognise.</DialogDescription></DialogHeader>
+          <div className="flex flex-col gap-3">
+            <div className="flex flex-col gap-1"><Label htmlFor="list-title">Name</Label><Input id="list-title" value={editing?.title ?? ""} onChange={(e) => setEditing((v) => v && { ...v, title: e.target.value })} /></div>
+            <div className="flex flex-col gap-1"><Label htmlFor="list-desc">Description</Label><Input id="list-desc" value={editing?.description ?? ""} onChange={(e) => setEditing((v) => v && { ...v, description: e.target.value })} /></div>
+            {!editing?.id ? (
+              <div className="flex flex-col gap-1"><Label htmlFor="list-type">Holds</Label>
+                <select id="list-type" className="h-9 rounded-md border bg-background px-2 text-sm" value={editing?.type} onChange={(e) => setEditing((v) => v && { ...v, type: e.target.value as "contacts" | "companies" })}>
+                  <option value="contacts">Contacts</option><option value="companies">Companies</option>
+                </select>
+              </div>
+            ) : null}
+            {save.error ? <ApiError error={save.error} title="Could not save the list" /> : null}
+          </div>
+          <DialogFooter>
+            <Button variant="ghost" onClick={() => setEditing(null)}>Cancel</Button>
+            <Button loading={save.loading} disabled={!editing?.title.trim()} onClick={() => editing && void save.mutate({ ...editing, title: editing.title.trim() })}>Save</Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      <Sheet open={members != null} onOpenChange={(o) => !o && setMembers(null)}>
+        <SheetContent className="w-full sm:max-w-3xl overflow-y-auto p-4">
+          <SheetHeader><SheetTitle>{members?.title}</SheetTitle><SheetDescription>{members ? `${count(members).toLocaleString()} members` : ""}</SheetDescription></SheetHeader>
+          {members ? (
+            <ContactTable listId={members.id} selectable allowDelete={false} pageSize={10} refreshKey={membersKey}
+              renderBulkActions={({ ids }) => <Button size="sm" variant="outline" onClick={() => setRemoving(ids)}>Remove from list</Button>} />
+          ) : null}
+          {removeMembers.error ? <ApiError error={removeMembers.error} title="Could not remove them" /> : null}
+          {/* Inside the sheet: a modal sheet makes everything outside it inert, so the dialog must live in it. */}
+          <ConfirmSpendDialog open={removing != null} tier="destructive" title={`Remove ${removing?.length ?? 0} contacts from "${members?.title ?? "the list"}"`} description="They stay in your CRM; they only leave this list."
+            affected={removing?.length} confirmLabel="Remove" confirming={removeMembers.loading}
+            onConfirm={() => members && removing && void removeMembers.mutate({ listId: members.id, ids: removing })} onCancel={() => setRemoving(null)} />
+        </SheetContent>
+      </Sheet>
+
+      <ConfirmSpendDialog open={deleting != null} tier="destructive" title={`Delete list "${deleting?.title ?? ""}"`} description="The list is removed. Its contacts stay in your CRM."
+        affected={deleting ? count(deleting) : undefined} confirming={remove.loading} onConfirm={() => deleting && void remove.mutate(deleting.id)} onCancel={() => setDeleting(null)} />
+    </div>
+  );
+}