@graph8/sdk 0.303.0 → 0.357.0

package/blocks/search/README.md

@@ -0,0 +1,129 @@
+# search: prospect search
+
+Find new people and companies in graph8's open-data index with filters, preview them, and save the ones you
+want into a list. Four components: a filter builder, a results table, a save-to-list dialog and saved
+searches. Builds on `lists` (which builds on `crm`): once results are saved, you work with real contacts.
+
+Install: `npx @graph8/sdk add search` (installs `foundation`, `crm` and `lists` first).
+
+## Read this first: search results are masked
+
+`POST /search/contacts` returns **previews**, not CRM records:
+
+- a locked email or phone arrives as `"***"` and its name is listed in `locked_fields`; `null` means no value;
+- there is **no contact id** in a result, so a search row cannot be emailed, enrolled or edited;
+- the way to unlock them is to **save the results into a list** (or enrich them).
+
+So the order is always: **search (preview) -> save to a new list -> wait for the list to finish building ->
+read the list's contacts (real, unlocked, with ids) -> enrich/verify -> enroll.** The components enforce it:
+locked cells render as **Locked**, never as the placeholder, and `ProspectResults` tells the person how many are
+locked and that saving unlocks them. Do not build a screen that treats `"***"` as an email.
+
+## What you get
+
+| Component | Use it for | Props |
+|---|---|---|
+| `FilterBuilder` | Field / operator / values rows. Enumerated fields offer the real value set, names type ahead | `resource`, `value`, `onChange`, `onSearch` |
+| `ProspectResults` | Run the search, show one page, total, paging, locked banner, open the save dialog | `resource`, `filters`, `pageSize`, `confirmSearch`, `creditsPerRecord`, `onSaved` |
+| `SaveToListDialog` | Save all matches into a NEW list (confirmed), poll until built | `open`, `onOpenChange`, `resource`, `filters`, `estimatedTotal`, `onSaved` |
+| `SavedSearches` | Name and keep filters, load, delete | `resource`, `current`, `onLoad` |
+
+`ProspectResults` with NO `filters` prop is a complete prospecting page (builder, saved searches, results): mount it as a
+route as is. With `filters` it renders just the results.
+
+Hook: `useFilterOptions(resource, field)`. Helpers in `lib/search-types.ts`: `completeFilters`, `isLocked`,
+`visible`, the field catalog.
+
+## The flow, with the ids that pass between steps
+
+1. `GET /search/filter-options?resource=contacts&fields=company_industry` -> `{ company_industry: [{ id, label, count }] }`.
+   Send the **`id`** back as the filter value.
+2. `POST /search/contacts { filters: [{ field, operator, value: [...] }], page, limit }` ->
+   `{ data: [...], pagination: { total, total_available, has_next, notes } }`. Filters are ANDed. At least one is
+   required (an unfiltered search is refused). `page * limit` may not exceed 10,000.
+3. `POST /search/contacts/save { filters, list_title, max_results }` -> **202** `{ list_id, list_title, estimated_total, status: "processing" }`.
+   Shown behind `ConfirmSpendDialog` (billable). 402 means a trial contact cap was reached.
+4. Poll `GET /lists?search=<list_title>` until the list with that `list_id` has `status: "completed"` (or `"failed"`).
+5. Read the members: `GET /contacts?list_id=<list_id>` (`ContactTable listId`). Emails and phones are now real.
+
+```tsx
+"use client";
+import { useState } from "react";
+import { FilterBuilder } from "@/components/g8/search/filter-builder";
+import { ProspectResults } from "@/components/g8/search/prospect-results";
+import { SavedSearches } from "@/components/g8/search/saved-searches";
+import type { SearchCondition } from "@/components/g8/search/lib/search-types";
+
+export default function Prospecting() {
+  const [draft, setDraft] = useState<SearchCondition[]>([]);
+  const [applied, setApplied] = useState<SearchCondition[]>([]);
+  return (
+    <div className="grid gap-4 lg:grid-cols-[22rem_1fr]">
+      <div className="flex flex-col gap-4">
+        <FilterBuilder value={draft} onChange={setDraft} onSearch={setApplied} />
+        <SavedSearches current={draft} onLoad={(filters) => { setDraft(filters); setApplied(filters); }} />
+      </div>
+      <ProspectResults filters={applied} onSaved={(list) => (window.location.href = `/lists/${list.id}`)} />
+    </div>
+  );
+}
+```
+
+(`add` flattens `components/` into `components/g8/search/` (or `src/components/g8/search/`); `lib/` and `hooks/`
+keep their folders under it. Adjust the alias to your app.)
+
+## Tiers and confirmations
+
+- Searching, filter options, autocomplete and listing saved searches are reads. The contract labels
+  `searchContacts` / `searchCompanies` **billable**, but the API router and the SDK docs both state that searching
+  does **not** consume credits; so `ProspectResults` searches on the person's click without a dialog. Pass
+  `confirmSearch` to ask first anyway. (If graph8 ever starts charging for search, flip that default.)
+- **Saving to a list is the spend.** `SaveToListDialog` always goes through `ConfirmSpendDialog` (billable) and shows
+  how many records. There is no balance or price read in the API, so an estimate appears only if you pass `creditsPerRecord`.
+- Deleting a saved search is destructive and confirmed.
+
+## Prerequisites
+
+- `lists-installed` (app): the CLI installs `lists` and `crm`.
+- `proxy-allowlist` (app): `allowedPrefixes` includes `search` and `lists`.
+- `active-subscription` (api): search and save refuse a workspace without one.
+
+## Defaults the agent can use without asking
+
+| Decision | Default |
+|---|---|
+| Confirm before each search | no (free); `confirmSearch` to opt in |
+| Records a save takes | min(matches, 1000), editable up to 10,000 |
+| New list name | `Search <date>` |
+
+Ask the person: who may save searches into the CRM (it spends credits) - decide it in the proxy's `authorize`.
+
+## Gotchas
+
+- The save endpoint can only create a **new** list. To put chosen people into an existing list, save first, then
+  use `AddToListButton` (lists block) on the new list's members.
+- Saved searches made in the graph8 app use a different stored format; they are listed but cannot be loaded here.
+  Searches saved by this block carry `icp_query.format = "g8-sdk-v1"`.
+- `between` takes exactly two values; value-less operators (`is_empty`, `is_not_empty`, `exists`) take none.
+- If a Radix dialog or sheet is open, render `ConfirmSpendDialog` inside it (a modal makes the rest of the page inert).
+
+## Recipes
+
+| File | Does |
+|---|---|
+| `recipes/search-and-save-to-list.ts` | Preview (ignoring masked emails), save, poll the list, read unlocked members |
+| `recipes/explore-filter-values.ts` | Valid filter values, type-ahead, values within a subset |
+| `recipes/saved-searches.ts` | Save, list, delete saved searches |
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| searchContacts / searchCompanies | POST /search/contacts, /search/companies | billable (see above: free in practice) | ProspectResults |
+| saveContactSearch / saveCompanySearch | POST /search/contacts/save, /search/companies/save | billable | SaveToListDialog |
+| listLists | GET /lists | read | SaveToListDialog (polling) |
+| getFilterOptions | GET /search/filter-options | read | FilterBuilder |
+| getAutocompleteSuggestions | GET /search/autocomplete | read | FilterBuilder |
+| getFilteredFilterOptions | POST /search/filter-options | read | recipe |
+| listSavedSearches / saveSearch | GET, POST /search/saved-searches | read / write | SavedSearches |
+| deleteSavedSearch | DELETE /search/saved-searches/{query_id} | destructive | SavedSearches |

package/blocks/search/block.json

@@ -0,0 +1,185 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "search",
+  "title": "Prospect search",
+  "summary": "Filter builder with real value suggestions, paged prospect results that handle locked fields, save-to-list that reveals them, and saved searches.",
+  "features": [
+    "filter builder with value suggestions from the real value sets and type-ahead",
+    "paged contact and company results with total and paging-window handling",
+    "locked emails and phones shown as Locked, with a one-step path to reveal them",
+    "save-to-list into a new list with a billable confirmation and polled progress",
+    "saved searches: save, load, delete"
+  ],
+  "dependsOn": [
+    "lists"
+  ],
+  "operations": [
+    "delete_saved_search_search_saved_searches__query_id__delete",
+    "get_autocomplete_suggestions_search_autocomplete_get",
+    "get_filter_options_search_filter_options_get",
+    "get_filtered_filter_options_search_filter_options_post",
+    "list_lists_lists_get",
+    "list_saved_searches_search_saved_searches_get",
+    "save_company_search_search_companies_save_post",
+    "save_contact_search_search_contacts_save_post",
+    "save_search_search_saved_searches_post",
+    "search_companies_search_companies_post",
+    "search_contacts_search_contacts_post"
+  ],
+  "components": [
+    {
+      "name": "FilterBuilder",
+      "file": "components/filter-builder.tsx",
+      "purpose": "Build the filter list: field, operator, values. Enumerated fields offer their real values, names type ahead. Controlled; fires onSearch with the complete filters.",
+      "operations": [
+        "get_filter_options_search_filter_options_get",
+        "get_autocomplete_suggestions_search_autocomplete_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "ProspectResults",
+      "file": "components/prospect-results.tsx",
+      "purpose": "Run the search (or, with no filters prop, a whole prospecting page with filters and saved searches) and show one page of matches with total, paging window and a locked-field banner; opens SaveToListDialog. Optional confirm before each search.",
+      "operations": [
+        "search_contacts_search_contacts_post",
+        "search_companies_search_companies_post",
+        "get_filter_options_search_filter_options_get",
+        "get_autocomplete_suggestions_search_autocomplete_get",
+        "list_saved_searches_search_saved_searches_get",
+        "save_search_search_saved_searches_post",
+        "delete_saved_search_search_saved_searches__query_id__delete",
+        "list_lists_lists_get",
+        "save_contact_search_search_contacts_save_post",
+        "save_company_search_search_companies_save_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable",
+        "destructive"
+      ]
+    },
+    {
+      "name": "SaveToListDialog",
+      "file": "components/save-to-list-dialog.tsx",
+      "purpose": "Save everything a search matches into a NEW list (billable, confirmed), then poll the list until it is built. This is how locked emails and phones are revealed.",
+      "operations": [
+        "list_lists_lists_get",
+        "save_contact_search_search_contacts_save_post",
+        "save_company_search_search_companies_save_post"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "SavedSearches",
+      "file": "components/saved-searches.tsx",
+      "purpose": "Save the current filters under a name, load one back into the builder, delete the ones no longer needed.",
+      "operations": [
+        "list_saved_searches_search_saved_searches_get",
+        "save_search_search_saved_searches_post",
+        "delete_saved_search_search_saved_searches__query_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useFilterOptions",
+      "file": "hooks/use-filter-options.ts",
+      "purpose": "The distinct values of a searchable field, cached per resource and field.",
+      "operations": [
+        "get_filter_options_search_filter_options_get"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/search-types.ts",
+      "purpose": "Filter vocabulary (fields, operators, kinds), result shapes and the locked-field helpers (isLocked, visible)."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/search-and-save-to-list.ts",
+      "title": "Preview a prospect search, save it to a list and read the unlocked contacts",
+      "when": "Building an audience from the open-data index. Search results carry no contact id and mask locked emails and phones as \"***\" (named in `locked_fields`): never treat \"***\" as a real email. Order: search (preview) -> save to a new list -> wait for the list to finish building -> read the list's contacts, which are real, unlocked records with ids -> enrich/verify -> enroll. Saving can spend credits, so ask a human first."
+    },
+    {
+      "file": "recipes/explore-filter-values.ts",
+      "title": "Look up valid filter values before searching",
+      "when": "Writing a filter on a field with a fixed value set (industry, seniority, country, company size) or a name you have to spell exactly (company, domain). A guessed value returns zero rows, indistinguishable from a correct filter that matches nothing. The `id` of each option is exactly what the search expects as a filter value."
+    },
+    {
+      "file": "recipes/saved-searches.ts",
+      "title": "Save, list and delete saved searches",
+      "when": "A search is run again and again (a weekly ICP pull). A saved search belongs to the API key's own identity, not the whole org. `icp_query` is stored as-is: keep your own format marker so you can load it back."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "lists-installed",
+      "where": "app",
+      "description": "The lists block (and crm) are installed; the CLI does it. Search results are worked with after they are saved into a list.",
+      "verify": "components/g8/lists/ and components/g8/crm/ exist."
+    },
+    {
+      "id": "proxy-allowlist",
+      "where": "app",
+      "description": "allowedPrefixes in the /api/g8 route includes `search` and `lists`.",
+      "verify": "POST /api/g8/search/contacts with a filter returns 200 when signed in."
+    },
+    {
+      "id": "active-subscription",
+      "where": "api",
+      "description": "The graph8 workspace has an active subscription (search and save endpoints refuse otherwise). Trial workspaces have a contact cap: a save over the cap answers 402.",
+      "verify": "A small search returns results; a save of a few contacts returns 202."
+    }
+  ],
+  "scopes": [
+    "lists:read",
+    "search:delete",
+    "search:read",
+    "search:run",
+    "search:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Whether searching asks for confirmation",
+      "default": "No: searching does not consume credits (router and SDK docs). Pass confirmSearch to ProspectResults to ask anyway",
+      "askHuman": false
+    },
+    {
+      "decision": "How many records a save takes",
+      "default": "min(matches, 1000); the person can raise it up to 10,000",
+      "askHuman": false
+    },
+    {
+      "decision": "Name of the list a search is saved into",
+      "default": "Search <date>",
+      "askHuman": false
+    },
+    {
+      "decision": "Credits per saved record shown in the confirmation",
+      "default": "Not shown (no balance or price read exists); pass creditsPerRecord if the plan's rate is known",
+      "askHuman": false
+    },
+    {
+      "decision": "Who may save searches into the CRM (spends credits)",
+      "default": "Anyone the proxy's authorize lets through",
+      "askHuman": true
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

package/blocks/search/components/filter-builder.tsx

@@ -0,0 +1,149 @@
+"use client";
+
+/**
+ * FilterBuilder: build the filter list a prospect search takes. One row per condition: field,
+ * operator, values. Enumerated fields (seniority, industry, country...) offer their real value set,
+ * company name/domain/job title type ahead, so nobody guesses a spelling that silently returns nothing.
+ *
+ * SDK operations, in order (all read, free; no confirm dialog):
+ *   1. getFilterOptions           GET /search/filter-options?resource&fields=...   the values of an enumerated field
+ *   2. getAutocompleteSuggestions GET /search/autocomplete?resource&field&value    type-ahead for names, domains, titles
+ *
+ * Controlled component: it never runs a search. `onSearch` is called when the person clicks Search; hand
+ * `completeFilters(value)` to ProspectResults. Incomplete rows are ignored by the search, not sent.
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Input } from "@graph8/sdk/ui";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useFilterOptions } from "../hooks/use-filter-options";
+import { NO_VALUE_OPERATORS, OPERATORS_BY_KIND, OPERATOR_LABEL, completeFilters, fieldsFor } from "../lib/search-types";
+import type { FieldMeta, SearchCondition, SearchOperator, SearchResource } from "../lib/search-types";
+
+export interface FilterBuilderProps {
+  resource?: SearchResource;
+  value: SearchCondition[];
+  onChange: (filters: SearchCondition[]) => void;
+  /** Search button. Without it the builder is just a form. */
+  onSearch?: (filters: SearchCondition[]) => void;
+  disabled?: boolean;
+  className?: string;
+}
+
+/** Pull strings out of the open autocomplete envelope, whatever list key it uses. */
+export function extractSuggestions(data: unknown): string[] {
+  const list = Array.isArray(data) ? data : ((data as Record<string, unknown> | null) && Object.values(data as Record<string, unknown>).find(Array.isArray)) || [];
+  return (list as unknown[])
+    .map((item) => (typeof item === "string" ? item : String((item as Record<string, unknown>)?.label ?? (item as Record<string, unknown>)?.value ?? (item as Record<string, unknown>)?.name ?? "")))
+    .filter(Boolean)
+    .slice(0, 8);
+}
+
+// Stable row identity across edits (update() keeps the object's id), so removing a row never hands its draft text to the next one.
+const ids = new WeakMap<object, number>();
+let nextId = 0;
+function rowId(c: SearchCondition): number {
+  if (!ids.has(c)) ids.set(c, nextId++);
+  return ids.get(c)!;
+}
+
+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;
+}
+
+function ValuePicker({ resource, meta, value, onChange, disabled }: { resource: SearchResource; meta: FieldMeta; value: unknown[]; onChange: (v: unknown[]) => void; disabled?: boolean }) {
+  const [draft, setDraft] = useState("");
+  const typed = useDebounced(draft.trim());
+  const options = useFilterOptions(resource, meta.key, meta.suggest === "options");
+  const auto = useG8Query(
+    async (signal) => extractSuggestions((await g8Get("/search/autocomplete", { resource, field: meta.key, value: typed, size: 8 }, { signal })).data),
+    [resource, meta.key, typed],
+    { enabled: meta.suggest === "autocomplete" && typed.length >= 2 },
+  );
+  const labels = new Map(options.options.map((o) => [o.id, o.label]));
+  const suggestions = meta.suggest === "options"
+    ? options.options.filter((o) => !value.includes(o.id) && o.label.toLowerCase().includes(draft.toLowerCase())).slice(0, 8).map((o) => o.id)
+    : meta.suggest === "autocomplete" && typed.length >= 2 ? auto.data ?? [] : [];
+
+  const add = (v: string) => {
+    const clean = v.trim();
+    if (clean && !value.includes(clean)) onChange([...value, clean]);
+    setDraft("");
+  };
+  return (
+    <div className="flex min-w-48 flex-1 flex-col gap-1">
+      <div className="flex flex-wrap items-center gap-1">
+        {value.map((v) => (
+          <span key={String(v)} className="inline-flex items-center gap-1 rounded-full bg-muted px-2 py-0.5 text-xs">
+            {labels.get(String(v)) ?? String(v)}
+            <button type="button" aria-label={`Remove ${String(v)}`} disabled={disabled} onClick={() => onChange(value.filter((x) => x !== v))}>x</button>
+          </span>
+        ))}
+        <Input aria-label={`${meta.label} value`} className="h-8 w-40" placeholder={meta.kind === "number" ? "e.g. 2015" : "Type and press Enter"} value={draft} disabled={disabled}
+          onChange={(e) => setDraft(e.target.value)} onKeyDown={(e) => { if (e.key === "Enter") { e.preventDefault(); add(draft); } }} />
+      </div>
+      {suggestions.length > 0 ? (
+        <ul aria-label="Suggestions" className="flex flex-wrap gap-1">
+          {suggestions.map((s) => (
+            <li key={s}><button type="button" className="rounded border px-2 py-0.5 text-xs hover:bg-accent" onClick={() => add(s)}>{labels.get(s) ?? s}</button></li>
+          ))}
+        </ul>
+      ) : null}
+    </div>
+  );
+}
+
+function BetweenPicker({ meta, value, onChange, disabled }: { meta: FieldMeta; value: unknown[]; onChange: (v: unknown[]) => void; disabled?: boolean }) {
+  return (
+    <div className="flex items-center gap-2">
+      <Input aria-label={`${meta.label} from`} className="h-8 w-24" inputMode="numeric" disabled={disabled} value={String(value[0] ?? "")} onChange={(e) => onChange([e.target.value, value[1] ?? ""])} />
+      <span className="text-sm text-muted-foreground">and</span>
+      <Input aria-label={`${meta.label} to`} className="h-8 w-24" inputMode="numeric" disabled={disabled} value={String(value[1] ?? "")} onChange={(e) => onChange([value[0] ?? "", e.target.value])} />
+    </div>
+  );
+}
+
+export function FilterBuilder({ resource = "contacts", value, onChange, onSearch, disabled, className }: FilterBuilderProps) {
+  const fields = fieldsFor(resource);
+  const meta = (key: string) => fields.find((f) => f.key === key) ?? fields[0];
+  const ready = completeFilters(value);
+  const update = (i: number, patch: Partial<SearchCondition>) => onChange(value.map((c, j) => { if (j !== i) return c; const n = { ...c, ...patch }; ids.set(n, rowId(c)); return n; }));
+
+  const changeField = (i: number, key: string) => {
+    const m = meta(key);
+    update(i, { field: key, operator: OPERATORS_BY_KIND[m.kind][0], value: [] });
+  };
+  const changeOperator = (i: number, operator: SearchOperator) => update(i, { operator, value: NO_VALUE_OPERATORS.includes(operator) ? [] : value[i].value });
+  const add = () => onChange([...value, { field: fields[0].key, operator: OPERATORS_BY_KIND[fields[0].kind][0], value: [] }]);
+
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      {value.length === 0 ? <p className="text-sm text-muted-foreground">No filters yet. Add at least one: an unfiltered search is refused.</p> : null}
+      {value.map((c, i) => {
+        const m = meta(c.field);
+        return (
+          <div key={rowId(c)} className="flex flex-wrap items-start gap-2" data-testid="filter-row">
+            <select aria-label="Field" className="h-8 rounded-md border bg-background px-2 text-sm" value={c.field} disabled={disabled} onChange={(e) => changeField(i, e.target.value)}>
+              {fields.map((f) => <option key={f.key} value={f.key}>{f.label}</option>)}
+            </select>
+            <select aria-label="Operator" className="h-8 rounded-md border bg-background px-2 text-sm" value={c.operator} disabled={disabled} onChange={(e) => changeOperator(i, e.target.value as SearchOperator)}>
+              {OPERATORS_BY_KIND[m.kind].map((o) => <option key={o} value={o}>{OPERATOR_LABEL[o]}</option>)}
+            </select>
+            {NO_VALUE_OPERATORS.includes(c.operator) ? null : c.operator === "between"
+              ? <BetweenPicker meta={m} value={c.value ?? []} disabled={disabled} onChange={(v) => update(i, { value: v })} />
+              : <ValuePicker resource={resource} meta={m} value={c.value ?? []} disabled={disabled} onChange={(v) => update(i, { value: v })} />}
+            <Button type="button" variant="ghost" size="sm" disabled={disabled} aria-label="Remove filter" onClick={() => onChange(value.filter((_, j) => j !== i))}>Remove</Button>
+          </div>
+        );
+      })}
+      <div className="flex items-center gap-2">
+        <Button type="button" variant="outline" size="sm" disabled={disabled} onClick={add}>Add filter</Button>
+        {value.length > 0 ? <Button type="button" variant="ghost" size="sm" disabled={disabled} onClick={() => onChange([])}>Clear all</Button> : null}
+        {onSearch ? <Button type="button" className="ml-auto" size="sm" disabled={disabled || ready.length === 0} onClick={() => onSearch(ready)}>Search</Button> : null}
+      </div>
+    </div>
+  );
+}

package/blocks/search/components/prospect-results.tsx

@@ -0,0 +1,175 @@
+"use client";
+
+/**
+ * ProspectResults: run a filter search (or, with no `filters` prop, a whole prospecting page) against the open-data index and show one page of matches,
+ * with paging, the total, and a "Save to list" action (SaveToListDialog).
+ *
+ * SDK operations, in order:
+ *   1. searchContacts | searchCompanies   POST /search/contacts | /search/companies   { filters, page, limit }
+ *        The contract labels this `billable`, but the router and the SDK docs say searching does NOT consume
+ *        credits, so it runs on the person's click without a dialog. Pass `confirmSearch` to put a
+ *        ConfirmSpendDialog in front of every search anyway (stricter plans, or if graph8 starts charging).
+ *   2. saveContactSearch | saveCompanySearch   via SaveToListDialog   (billable, confirmed)
+ *
+ * LOCKED FIELDS: emails and phones the org has not unlocked come back as "***" and are named in
+ * `locked_fields`. They render as Locked and are never a value you can copy or send. Results carry NO contact
+ * id: you cannot enroll or email a search row directly. Save to a list first, then work with the list's contacts.
+ *
+ * Paging window: page x limit may not exceed 10,000; narrow the filters to go further.
+ */
+
+import { useState } from "react";
+import { Button, 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 { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Post } from "@/g8/lib/g8-client";
+import type { G8Envelope } from "@/g8/lib/g8-client";
+import { SEARCH_WINDOW, completeFilters, isLocked, visible } from "../lib/search-types";
+import type { ProspectCompany, ProspectContact, SearchCondition, SearchPagination, SearchResource } from "../lib/search-types";
+import { FilterBuilder } from "./filter-builder";
+import { SavedSearches } from "./saved-searches";
+import { SaveToListDialog } from "./save-to-list-dialog";
+import type { SavedListInfo } from "./save-to-list-dialog";
+
+export interface ProspectResultsProps {
+  resource?: SearchResource;
+  /**
+   * The APPLIED filters (for example from FilterBuilder's onSearch). Nothing runs until at least one is complete.
+   * OMIT it and the component is a whole prospecting page: FilterBuilder, SavedSearches and the results.
+   */
+  filters?: SearchCondition[];
+  pageSize?: number;
+  /** Ask for confirmation before every search. Default false (searching is free). */
+  confirmSearch?: boolean;
+  /** Credits per saved record on your plan, if known, to show an estimate when saving. */
+  creditsPerRecord?: number;
+  /** Called when a saved list finished building. */
+  onSaved?: (list: SavedListInfo) => void;
+  className?: string;
+}
+
+type Row = ProspectContact & ProspectCompany;
+
+function Locked() {
+  return <span className="italic text-muted-foreground" title="Locked: save these results to a list to unlock">Locked</span>;
+}
+
+function Cell({ row, field }: { row: ProspectContact; field: keyof ProspectContact }) {
+  return isLocked(row, field) ? <Locked /> : <>{visible(row, field) || <span className="text-muted-foreground">-</span>}</>;
+}
+
+function ResultsTable({ resource = "contacts", filters, pageSize = 25, confirmSearch = false, creditsPerRecord, onSaved, className }: ProspectResultsProps & { filters: SearchCondition[] }) {
+  const applied = completeFilters(filters);
+  const key = JSON.stringify(applied);
+  const [state, setState] = useState({ key, page: 1, approved: !confirmSearch ? key : "" });
+  const page = state.key === key ? state.page : 1;
+  const approved = confirmSearch ? state.approved === key : true;
+  const [saving, setSaving] = useState(false);
+  const [asking, setAsking] = useState(false);
+
+  const search = useG8Query(
+    (signal) => g8Post<Row[]>(`/search/${resource}`, { filters: applied, page, limit: pageSize }, { signal }),
+    [resource, key, page, pageSize],
+    { enabled: applied.length > 0 && approved },
+  );
+
+  if (applied.length === 0) return <EmptyState className={className} title="Add a filter to search" description="Searches need at least one filter, for example a job title or an industry." />;
+  if (!approved) {
+    return (
+      <div className={className}>
+        <EmptyState title="Ready to search" description="Your plan asks you to confirm each search." action={<Button size="sm" onClick={() => setAsking(true)}>Run search</Button>} />
+        <ConfirmSpendDialog open={asking} tier="billable" title="Run this search" description="Searches are confirmed before they run."
+          confirmLabel="Search" onConfirm={() => { setAsking(false); setState({ key, page: 1, approved: key }); }} onCancel={() => setAsking(false)} />
+      </div>
+    );
+  }
+
+  const rows = (search.data?.data ?? []) as Row[];
+  const info = (search.data as G8Envelope<Row[]> | undefined)?.pagination as SearchPagination | undefined;
+  const available = info?.total_available ?? info?.total ?? rows.length;
+  const lowerBound = info?.total_is_lower_bound || (info?.total_available != null && info.total_available > (info?.total ?? 0));
+  const maxPage = Math.max(1, Math.floor(SEARCH_WINDOW / pageSize));
+  const lockedEmails = resource === "contacts" ? rows.filter((r) => isLocked(r, "work_email")).length : 0;
+  const lockedPhones = resource === "contacts" ? rows.filter((r) => isLocked(r, "direct_phone") || isLocked(r, "mobile_phone")).length : 0;
+
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      {search.error ? <ApiError error={search.error} title="Search failed" onRetry={() => void search.refetch()} /> : null}
+      {lockedEmails + lockedPhones > 0 ? (
+        <p role="note" className="rounded-md border bg-muted/40 px-3 py-2 text-sm">
+          {lockedEmails} emails and {lockedPhones} phones on this page are locked. Save the results to a list to unlock them.
+        </p>
+      ) : null}
+      {info?.notes?.map((n) => <p key={n} className="text-xs text-muted-foreground">{n}</p>)}
+
+      <div className="flex items-center justify-between text-sm">
+        <span className="text-muted-foreground">{search.loading && !search.data ? "Searching..." : `${available.toLocaleString()}${lowerBound ? "+" : ""} ${resource} match`}</span>
+        <Button size="sm" disabled={rows.length === 0} onClick={() => setSaving(true)}>Save results to a list</Button>
+      </div>
+
+      <div className="rounded-md border">
+        <Table>
+          <TableHeader>
+            {resource === "contacts"
+              ? <TableRow><TableHead>Name</TableHead><TableHead>Title</TableHead><TableHead>Company</TableHead><TableHead>Email</TableHead><TableHead>Phone</TableHead><TableHead>Location</TableHead></TableRow>
+              : <TableRow><TableHead>Company</TableHead><TableHead>Domain</TableHead><TableHead>Industry</TableHead><TableHead>Employees</TableHead><TableHead>Location</TableHead></TableRow>}
+          </TableHeader>
+          <TableBody>
+            {search.loading && rows.length === 0
+              ? Array.from({ length: 5 }, (_, i) => <TableRow key={`sk${i}`}><TableCell colSpan={resource === "contacts" ? 6 : 5}><Skeleton className="h-5 w-full" /></TableCell></TableRow>)
+              : rows.map((r, i) => resource === "contacts" ? (
+                  <TableRow key={i} data-testid="prospect-row">
+                    <TableCell className="font-medium">{[r.first_name, r.last_name].filter(Boolean).join(" ") || "-"}</TableCell>
+                    <TableCell>{r.job_title ?? "-"}</TableCell>
+                    <TableCell>{r.company_name ?? "-"}</TableCell>
+                    <TableCell><Cell row={r} field="work_email" /></TableCell>
+                    <TableCell>{isLocked(r, "direct_phone") || isLocked(r, "mobile_phone") ? <Locked /> : r.direct_phone || r.mobile_phone || <span className="text-muted-foreground">-</span>}</TableCell>
+                    <TableCell>{[r.city, r.state, r.country].filter(Boolean).join(", ") || "-"}</TableCell>
+                  </TableRow>
+                ) : (
+                  <TableRow key={i} data-testid="prospect-row">
+                    <TableCell className="font-medium">{r.name ?? "-"}</TableCell><TableCell>{r.domain ?? "-"}</TableCell>
+                    <TableCell>{r.industry ?? "-"}</TableCell><TableCell>{r.employee_count ?? "-"}</TableCell>
+                    <TableCell>{[r.city, r.state, r.country].filter(Boolean).join(", ") || "-"}</TableCell>
+                  </TableRow>
+                ))}
+          </TableBody>
+        </Table>
+        {!search.loading && !search.error && rows.length === 0 ? <EmptyState title="No matches" description="Loosen a filter or pick values from the suggestions." /> : null}
+      </div>
+
+      <div className="flex items-center justify-end gap-2 text-sm text-muted-foreground">
+        <Button variant="outline" size="sm" disabled={page <= 1 || search.loading} onClick={() => setState({ ...state, key, page: page - 1 })}>Previous</Button>
+        <span>Page {page}</span>
+        <Button variant="outline" size="sm" disabled={!info?.has_next || page >= maxPage || search.loading} onClick={() => setState({ ...state, key, page: page + 1 })}>Next</Button>
+      </div>
+
+      {/* Mounted only while open so its size field is seeded from the match count at that moment. */}
+      {saving ? <SaveToListDialog open onOpenChange={setSaving} resource={resource} filters={applied} estimatedTotal={available}
+        defaultTitle={`Search ${new Date().toISOString().slice(0, 10)}`} creditsPerRecord={creditsPerRecord} onSaved={onSaved} /> : null}
+    </div>
+  );
+}
+
+/**
+ * Pass `filters` to render only the results. Without it this is a self-contained prospecting page (filters, saved
+ * searches and results), so it can be mounted as a route with no props.
+ */
+export function ProspectResults(props: ProspectResultsProps) {
+  const { filters, ...rest } = props;
+  const [draft, setDraft] = useState<SearchCondition[]>([]);
+  const [applied, setApplied] = useState<SearchCondition[]>([]);
+  if (filters) return <ResultsTable {...rest} filters={filters} />;
+  const resource = props.resource ?? "contacts";
+  return (
+    <div className={`grid gap-4 lg:grid-cols-[22rem_1fr] ${props.className ?? ""}`}>
+      <div className="flex flex-col gap-4">
+        <FilterBuilder resource={resource} value={draft} onChange={setDraft} onSearch={setApplied} />
+        <SavedSearches resource={resource} current={draft} onLoad={(f) => { setDraft(f); setApplied(completeFilters(f)); }} />
+      </div>
+      <ResultsTable {...rest} className={undefined} filters={applied} />
+    </div>
+  );
+}