@graph8/sdk 0.303.0 → 0.357.0

package/blocks/search/components/save-to-list-dialog.tsx

@@ -0,0 +1,135 @@
+"use client";
+
+/**
+ * SaveToListDialog: save everything a search matches into a NEW list. This is also how locked
+ * ("***") emails and phones are revealed: contacts that were masked in the search results are
+ * real, unlocked records once they sit in a list.
+ *
+ * SDK operations, in order:
+ *   1. saveContactSearch | saveCompanySearch  POST /search/contacts/save | /search/companies/save   (billable)
+ *        { filters, list_title, max_results }  -> 202 { list_id, list_title, estimated_total, status: "processing" }
+ *        Goes through ConfirmSpendDialog first. Answers 402 when a trial's contact cap is reached.
+ *   2. listLists                              GET /lists?search=<list_title>   (read)
+ *        polled with useJobPoll until the list with that list_id is `completed` or `failed`
+ *        (the save runs in the background; there is no stream to wait on).
+ *
+ * The API can only save into a new list. To add chosen people to an existing list, save first and
+ * then use AddToListButton from the lists block on the saved list's members.
+ */
+
+import { useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, Input, Label } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { SEARCH_WINDOW, completeFilters } from "../lib/search-types";
+import type { SearchCondition, SearchResource } from "../lib/search-types";
+
+export interface SavedListInfo {
+  id: number;
+  title: string;
+  status?: string | null;
+  total?: number;
+  contact_count?: number | null;
+  company_count?: number | null;
+  status_detail?: string | null;
+}
+
+export interface SaveToListDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  resource?: SearchResource;
+  filters: SearchCondition[];
+  /** What the search reported as matching; used for the default size and the confirmation. */
+  estimatedTotal?: number;
+  defaultTitle?: string;
+  /** Credits one saved record costs on your plan, if you know it; shows an estimate in the confirmation. */
+  creditsPerRecord?: number;
+  /** Called once the list finished building. Route to your ContactTable listId={list.id}. */
+  onSaved?: (list: SavedListInfo) => void;
+}
+
+interface SaveResult { list_id: number; list_title: string; estimated_total: number; status: string }
+
+export function SaveToListDialog({ open, onOpenChange, resource = "contacts", filters, estimatedTotal, defaultTitle, creditsPerRecord, onSaved }: SaveToListDialogProps) {
+  const [title, setTitle] = useState(defaultTitle ?? "");
+  const [max, setMax] = useState(String(Math.max(1, Math.min(estimatedTotal ?? 1000, 1000))));
+  const [confirmOpen, setConfirmOpen] = useState(false);
+  const [saved, setSaved] = useState<SaveResult | null>(null);
+  // Seed the size from the match count each time the dialog opens, never leave it at 0.
+  const [seeded, setSeeded] = useState(open);
+  if (open && !seeded) { setSeeded(true); setMax(String(Math.max(1, Math.min(estimatedTotal ?? 1000, 1000)))); }
+  if (!open && seeded) setSeeded(false);
+
+  const count = Math.max(1, Math.min(Number(max) || 0, SEARCH_WINDOW));
+  const effective = Math.min(count, estimatedTotal ?? count);
+  const valid = title.trim().length > 0 && Number(max) >= 1 && Number(max) <= SEARCH_WINDOW && completeFilters(filters).length > 0;
+
+  const save = useG8Mutation(
+    () => g8Post<SaveResult>(`/search/${resource}/save`, { filters: completeFilters(filters), list_title: title.trim(), max_results: count }),
+    { onSuccess: (res) => { setConfirmOpen(false); setSaved(res.data); } },
+  );
+  const progress = useJobPoll<SavedListInfo | null>(
+    async (signal) => {
+      const res = await g8Get<SavedListInfo[]>("/lists", { search: saved!.list_title, limit: 50 }, { signal });
+      return ((res.data ?? []) as SavedListInfo[]).find((l) => l.id === saved!.list_id) ?? null;
+    },
+    { enabled: saved != null, intervalMs: 2000, isTerminal: (l) => l?.status === "completed" || l?.status === "failed" },
+  );
+
+  const list = progress.status;
+  const failed = list?.status === "failed";
+  const finished = progress.done && !failed;
+  const close = () => { onOpenChange(false); setSaved(null); setConfirmOpen(false); save.reset(); };
+
+  return (
+    <Dialog open={open} onOpenChange={(o) => (o ? onOpenChange(true) : close())}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Save results to a new list</DialogTitle>
+          <DialogDescription>Saving adds the matches to your CRM and unlocks their emails and phones.</DialogDescription>
+        </DialogHeader>
+
+        {saved ? (
+          <div role="status" className="flex flex-col gap-1 text-sm">
+            {failed ? <p className="font-medium text-destructive">The list could not be built{list?.status_detail ? `: ${list.status_detail}` : "."}</p>
+              : finished ? <p className="font-medium">Saved {(list?.contact_count ?? list?.company_count ?? list?.total ?? 0).toLocaleString()} {resource} to "{saved.list_title}".</p>
+              : <p>Building "{saved.list_title}"... about {saved.estimated_total.toLocaleString()} records. This keeps running if you close this window.</p>}
+            {progress.error && !progress.done ? <ApiError error={progress.error} title="Could not check progress" onRetry={() => progress.start()} /> : null}
+          </div>
+        ) : (
+          <div className="flex flex-col gap-3">
+            <div className="flex flex-col gap-1"><Label htmlFor="save-title">List name</Label><Input id="save-title" value={title} onChange={(e) => setTitle(e.target.value)} /></div>
+            <div className="flex flex-col gap-1">
+              <Label htmlFor="save-max">How many to save (up to {SEARCH_WINDOW.toLocaleString()})</Label>
+              <Input id="save-max" inputMode="numeric" value={max} onChange={(e) => setMax(e.target.value)} />
+              {estimatedTotal != null ? <p className="text-xs text-muted-foreground">The search matches about {estimatedTotal.toLocaleString()}.</p> : null}
+            </div>
+            {save.error ? <ApiError error={save.error} title="Could not start the save" /> : null}
+          </div>
+        )}
+
+        <DialogFooter>
+          <Button variant="ghost" onClick={close}>{saved ? (finished || failed ? "Done" : "Close") : "Cancel"}</Button>
+          {!saved ? <Button disabled={!valid} onClick={() => setConfirmOpen(true)}>Save {effective.toLocaleString()} {resource}</Button> : null}
+          {finished && list && onSaved ? <Button onClick={() => { onSaved(list); close(); }}>Open list</Button> : null}
+        </DialogFooter>
+
+        <ConfirmSpendDialog
+          open={confirmOpen}
+          tier="billable"
+          title={`Save up to ${effective.toLocaleString()} ${resource} to "${title.trim()}"`}
+          description="The list is created in your workspace and filled in the background. Revealing contact details can use credits on your plan."
+          estimatedCredits={creditsPerRecord != null ? effective * creditsPerRecord : undefined}
+          affected={effective}
+          confirmLabel="Save"
+          confirming={save.loading}
+          onConfirm={() => void save.mutate(undefined)}
+          onCancel={() => setConfirmOpen(false)}
+        />
+      </DialogContent>
+    </Dialog>
+  );
+}

package/blocks/search/components/saved-searches.tsx

@@ -0,0 +1,95 @@
+"use client";
+
+/**
+ * SavedSearches: keep searches you run often. Save the current filters under a name, load one back
+ * into FilterBuilder, delete the ones you no longer need.
+ *
+ * SDK operations, in order:
+ *   1. listSavedSearches   GET    /search/saved-searches?scope=<resource>   (read)   the key's OWN saved searches
+ *   2. saveSearch          POST   /search/saved-searches { title, scope, icp_query }   (write)
+ *   3. deleteSavedSearch   DELETE /search/saved-searches/{query_id}           (destructive, ConfirmSpendDialog)
+ *
+ * What is stored: `icp_query = { format: "g8-sdk-v1", resource, filters }` with the PUBLIC filter names, so a
+ * search saved here loads back here. Searches saved in the graph8 app use the app's own format; they are
+ * listed but cannot be loaded (shown as "Saved in the graph8 app").
+ */
+
+import { useState } from "react";
+import { Button, Input, Skeleton } 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 { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Post } from "@/g8/lib/g8-client";
+import { completeFilters } from "../lib/search-types";
+import type { SearchCondition, SearchResource } from "../lib/search-types";
+
+export const SAVED_FORMAT = "g8-sdk-v1";
+
+interface SavedSearch {
+  id: number;
+  title: string;
+  scope: string;
+  icp_query: { format?: string; filters?: SearchCondition[] } & Record<string, unknown>;
+  created_at?: string | null;
+}
+
+export interface SavedSearchesProps {
+  resource?: SearchResource;
+  /** The filters being edited now: what "Save current" stores. */
+  current: SearchCondition[];
+  /** Load a saved search into your FilterBuilder state (and usually run it). */
+  onLoad: (filters: SearchCondition[], saved: { id: number; title: string }) => void;
+  className?: string;
+}
+
+function loadable(s: SavedSearch): boolean {
+  return s.icp_query?.format === SAVED_FORMAT && Array.isArray(s.icp_query.filters) && s.icp_query.filters.length > 0;
+}
+
+export function SavedSearches({ resource = "contacts", current, onLoad, className }: SavedSearchesProps) {
+  const [title, setTitle] = useState("");
+  const [deleting, setDeleting] = useState<SavedSearch | null>(null);
+  const ready = completeFilters(current);
+
+  const list = useG8Query((signal) => g8Get<SavedSearch[]>("/search/saved-searches", { scope: resource }, { signal }), [resource]);
+  const save = useG8Mutation(
+    () => g8Post("/search/saved-searches", { title: title.trim(), scope: resource, icp_query: { format: SAVED_FORMAT, resource, filters: ready } }),
+    { onSuccess: () => { setTitle(""); void list.refetch(); } },
+  );
+  const remove = useG8Mutation((id: number) => g8Delete(`/search/saved-searches/${id}`), { onSuccess: () => { setDeleting(null); void list.refetch(); } });
+
+  const items = (list.data?.data ?? []) as SavedSearch[];
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      <form className="flex items-center gap-2" onSubmit={(e) => { e.preventDefault(); if (title.trim() && ready.length) void save.mutate(undefined); }}>
+        <Input aria-label="Name this search" placeholder="Name this search" value={title} onChange={(e) => setTitle(e.target.value)} />
+        <Button type="submit" size="sm" variant="outline" loading={save.loading} disabled={!title.trim() || ready.length === 0}>Save current</Button>
+      </form>
+      {save.error ? <ApiError error={save.error} title="Could not save the search" /> : null}
+      {remove.error ? <ApiError error={remove.error} title="Could not delete the search" /> : null}
+      {list.error ? <ApiError error={list.error} title="Could not load saved searches" onRetry={() => void list.refetch()} /> : null}
+      {list.loading && !list.data ? <Skeleton className="h-10 w-full" /> : null}
+      {!list.loading && !list.error && items.length === 0 ? <EmptyState title="No saved searches" description="Save the filters you use often." /> : null}
+
+      <ul className="flex flex-col gap-2">
+        {items.map((s) => (
+          <li key={s.id} className="flex items-center justify-between gap-2 rounded-md border p-3" data-testid="saved-search">
+            <div className="min-w-0">
+              <p className="truncate text-sm font-medium">{s.title}</p>
+              <p className="text-xs text-muted-foreground">{loadable(s) ? `${s.icp_query.filters!.length} filter${s.icp_query.filters!.length === 1 ? "" : "s"}` : "Saved in the graph8 app"}</p>
+            </div>
+            <div className="flex gap-1">
+              <Button size="sm" variant="outline" disabled={!loadable(s)} onClick={() => onLoad(s.icp_query.filters!, { id: s.id, title: s.title })}>Load</Button>
+              <Button size="sm" variant="ghost" onClick={() => setDeleting(s)}>Delete</Button>
+            </div>
+          </li>
+        ))}
+      </ul>
+
+      <ConfirmSpendDialog open={deleting != null} tier="destructive" title={`Delete "${deleting?.title ?? ""}"`} description="Lists already built from this search are not affected."
+        affected={1} confirming={remove.loading} onConfirm={() => deleting && void remove.mutate(deleting.id)} onCancel={() => setDeleting(null)} />
+    </div>
+  );
+}

package/blocks/search/hooks/use-filter-options.ts

@@ -0,0 +1,41 @@
+"use client";
+
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import type { SearchResource } from "../lib/search-types";
+
+export interface FilterOption {
+  /** Normalised value: send this back as the filter value. */
+  id: string;
+  label: string;
+  count?: number | null;
+}
+
+const cache = new Map<string, FilterOption[]>();
+
+/**
+ * The distinct values a field holds (`GET /search/filter-options`), so a filter can offer real
+ * choices instead of guessed strings (a guessed industry silently returns zero rows). Cached per
+ * resource and field for the life of the page. `enabled: false` makes no request.
+ */
+export function useFilterOptions(resource: SearchResource, field: string, enabled = true) {
+  const key = `${resource}:${field}`;
+  const query = useG8Query(
+    async (signal) => {
+      const hit = cache.get(key);
+      if (hit) return hit;
+      const res = await g8Get<Record<string, FilterOption[]>>("/search/filter-options", { resource, fields: [field] }, { signal });
+      const options = res.data?.[field] ?? [];
+      cache.set(key, options);
+      return options;
+    },
+    [key],
+    { enabled },
+  );
+  return { options: query.data ?? [], loading: query.loading, error: query.error };
+}
+
+/** Test hook: forget cached option lists. */
+export function clearFilterOptionsCache(): void {
+  cache.clear();
+}

package/blocks/search/lib/search-types.ts

@@ -0,0 +1,149 @@
+"use client";
+
+/**
+ * Filter vocabulary and result shapes for prospect search. Field names are the PUBLIC ones
+ * `POST /search/contacts` and `POST /search/companies` take (job_title, company_industry...), not the
+ * app's raw index names.
+ *
+ * Masked results: search sends "***" in place of a locked email/phone and lists the field in
+ * `locked_fields`. `isLocked` is the one check every component uses.
+ */
+
+export type SearchResource = "contacts" | "companies";
+export type SearchOperator = "any_of" | "contains" | "all_of" | "none_of" | "is_empty" | "is_not_empty" | "between" | "exists";
+
+export interface SearchCondition {
+  field: string;
+  operator: SearchOperator;
+  value?: unknown[];
+}
+
+export type FieldKind = "text" | "enum" | "number" | "presence";
+/** Where a value picker gets its suggestions: the fixed value set of the field, or type-ahead. */
+export type Suggest = "options" | "autocomplete" | "none";
+
+export interface FieldMeta {
+  key: string;
+  label: string;
+  kind: FieldKind;
+  suggest: Suggest;
+}
+
+export const CONTACT_FIELDS: FieldMeta[] = [
+  { key: "job_title", label: "Job title", kind: "text", suggest: "autocomplete" },
+  { key: "seniority_level", label: "Seniority", kind: "enum", suggest: "options" },
+  { key: "job_department", label: "Department", kind: "enum", suggest: "options" },
+  { key: "role", label: "Role", kind: "text", suggest: "none" },
+  { key: "skills", label: "Skills", kind: "text", suggest: "none" },
+  { key: "country", label: "Country", kind: "enum", suggest: "options" },
+  { key: "state", label: "State", kind: "text", suggest: "none" },
+  { key: "city", label: "City", kind: "text", suggest: "none" },
+  { key: "company_name", label: "Company name", kind: "text", suggest: "autocomplete" },
+  { key: "company_domain", label: "Company domain", kind: "text", suggest: "autocomplete" },
+  { key: "company_industry", label: "Industry", kind: "enum", suggest: "options" },
+  { key: "company_employee_count", label: "Company size", kind: "enum", suggest: "options" },
+  { key: "company_country", label: "Company country", kind: "enum", suggest: "options" },
+  { key: "company_revenue", label: "Company revenue", kind: "text", suggest: "none" },
+  { key: "company_founded_year", label: "Company founded", kind: "number", suggest: "none" },
+  { key: "work_email", label: "Has work email", kind: "presence", suggest: "none" },
+  { key: "direct_phone", label: "Has direct phone", kind: "presence", suggest: "none" },
+  { key: "mobile_phone", label: "Has mobile phone", kind: "presence", suggest: "none" },
+  { key: "linkedin_url", label: "Has LinkedIn", kind: "presence", suggest: "none" },
+];
+
+export const COMPANY_FIELDS: FieldMeta[] = [
+  { key: "name", label: "Name", kind: "text", suggest: "autocomplete" },
+  { key: "domain", label: "Domain", kind: "text", suggest: "autocomplete" },
+  { key: "industry", label: "Industry", kind: "enum", suggest: "options" },
+  { key: "industry_group", label: "Industry group", kind: "enum", suggest: "options" },
+  { key: "employee_count", label: "Employees", kind: "enum", suggest: "options" },
+  { key: "revenue", label: "Revenue", kind: "text", suggest: "none" },
+  { key: "founded_year", label: "Founded", kind: "number", suggest: "none" },
+  { key: "country", label: "Country", kind: "enum", suggest: "options" },
+  { key: "state", label: "State", kind: "text", suggest: "none" },
+  { key: "city", label: "City", kind: "text", suggest: "none" },
+];
+
+export const OPERATORS_BY_KIND: Record<FieldKind, SearchOperator[]> = {
+  text: ["any_of", "contains", "all_of", "none_of", "is_empty", "is_not_empty"],
+  enum: ["any_of", "none_of", "is_empty", "is_not_empty"],
+  number: ["between", "any_of", "is_empty", "is_not_empty"],
+  presence: ["exists", "is_empty"],
+};
+
+export const OPERATOR_LABEL: Record<SearchOperator, string> = {
+  any_of: "is any of", contains: "contains", all_of: "has all of", none_of: "is none of",
+  is_empty: "is empty", is_not_empty: "is not empty", between: "is between", exists: "exists",
+};
+
+export const NO_VALUE_OPERATORS: SearchOperator[] = ["is_empty", "is_not_empty", "exists"];
+
+export function fieldsFor(resource: SearchResource): FieldMeta[] {
+  return resource === "contacts" ? CONTACT_FIELDS : COMPANY_FIELDS;
+}
+
+/** A condition the API will accept: value-less operators need no value, `between` needs two, others at least one. */
+export function isComplete(c: SearchCondition): boolean {
+  if (NO_VALUE_OPERATORS.includes(c.operator)) return true;
+  const values = (c.value ?? []).filter((v) => String(v).trim() !== "");
+  return c.operator === "between" ? values.length === 2 : values.length > 0;
+}
+
+export function completeFilters(filters: SearchCondition[]): SearchCondition[] {
+  return filters.filter(isComplete);
+}
+
+export interface SearchPagination {
+  page: number;
+  limit: number;
+  total: number;
+  has_next: boolean;
+  total_available?: number | null;
+  total_is_lower_bound?: boolean | null;
+  notes?: string[] | null;
+}
+
+export interface ProspectContact {
+  first_name?: string | null;
+  last_name?: string | null;
+  work_email?: string | null;
+  personal_emails?: string | null;
+  direct_phone?: string | null;
+  mobile_phone?: string | null;
+  job_title?: string | null;
+  seniority_level?: string | null;
+  linkedin_url?: string | null;
+  city?: string | null;
+  state?: string | null;
+  country?: string | null;
+  company_name?: string | null;
+  company_domain?: string | null;
+  company_industry?: string | null;
+  locked_fields?: string[];
+}
+
+export interface ProspectCompany {
+  name?: string | null;
+  domain?: string | null;
+  industry?: string | null;
+  employee_count?: string | null;
+  revenue?: string | null;
+  city?: string | null;
+  state?: string | null;
+  country?: string | null;
+  linkedin_url?: string | null;
+}
+
+/** True when a value exists but is locked ("***", or named in `locked_fields`) until the contact is saved to a list. */
+export function isLocked(item: ProspectContact, field: keyof ProspectContact): boolean {
+  const v = item[field];
+  return item.locked_fields?.includes(field as string) === true || (typeof v === "string" && v.trim() === "***");
+}
+
+/** Never put the placeholder on screen as a value. */
+export function visible(item: ProspectContact, field: keyof ProspectContact): string {
+  return isLocked(item, field) ? "" : String(item[field] ?? "");
+}
+
+/** The most records one search can page through (page x limit). */
+export const SEARCH_WINDOW = 10_000;

package/blocks/search/recipes/explore-filter-values.ts

@@ -0,0 +1,27 @@
+/**
+ * @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.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function industryOptions() {
+  const res = await g8.api.search.getFilterOptions({ query: { resource: "contacts", fields: ["company_industry", "seniority_level"] } });
+  return res.data; // { company_industry: [{ id, label, count }], seniority_level: [...] }
+}
+
+export async function suggestCompanies(typed: string) {
+  const res = await g8.api.search.getAutocompleteSuggestions({ query: { resource: "contacts", field: "company_name", value: typed, size: 8 } });
+  return res.data;
+}
+
+/** What exists among a subset: industries among companies in Spain (needs at least one filter). */
+export async function industriesIn(country: string) {
+  const res = await g8.api.search.getFilteredFilterOptions({
+    body: { resource: "companies", fields: ["industry"], filters: [{ field: "country", operator: "any_of", value: [country] }] },
+  });
+  return res.data;
+}

package/blocks/search/recipes/saved-searches.ts

@@ -0,0 +1,34 @@
+/**
+ * @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.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function saveIcp() {
+  const saved = await g8.api.search.saveSearch({
+    body: {
+      title: "VP Sales at software companies",
+      scope: "contacts",
+      icp_query: {
+        format: "g8-sdk-v1",
+        resource: "contacts",
+        filters: [{ field: "job_title", operator: "any_of", value: ["VP Sales"] }],
+      },
+    },
+  });
+  return saved.data;
+}
+
+export async function mySearches() {
+  const res = await g8.api.search.listSavedSearches({ query: { scope: "contacts" } });
+  return res.data;
+}
+
+/** Soft delete; lists already built from the search are untouched. */
+export async function remove(queryId: number) {
+  const res = await g8.api.search.deleteSavedSearch({ path: { query_id: queryId } });
+  return res.data;
+}

package/blocks/search/recipes/search-and-save-to-list.ts

@@ -0,0 +1,37 @@
+/**
+ * @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.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const FILTERS = [
+  { field: "job_title", operator: "any_of" as const, value: ["VP Sales", "Head of Sales"] },
+  { field: "company_industry", operator: "any_of" as const, value: ["computer software"] },
+];
+
+export async function preview() {
+  const { data, pagination } = await g8.search.contacts({ filters: FILTERS, page: 1, limit: 25 });
+  const usable = data.filter((c) => c.work_email && c.work_email !== "***" && !c.locked_fields?.includes("work_email"));
+  return { matches: pagination?.total_available ?? pagination?.total, withVisibleEmail: usable.length, sample: data.slice(0, 3) };
+}
+
+/** Only after a person approved the spend. The API saves into a NEW list; it answers 202 and builds in the background. */
+export async function saveAndRead(listTitle: string, maxResults = 200) {
+  const started = await g8.search.saveContacts({ filters: FILTERS, list_title: listTitle, max_results: maxResults });
+
+  let status = started.status;
+  for (let i = 0; i < 60 && status === "processing"; i++) {
+    await new Promise((r) => setTimeout(r, 2000));
+    const lists = await g8.api.lists.listLists({ query: { search: listTitle, limit: 50 } });
+    status = (lists.data.find((l) => l.id === started.list_id)?.status as string | undefined) ?? status;
+  }
+  if (status !== "completed") throw new Error(`list ${started.list_id} is ${status}`);
+
+  const members = await g8.lists.contacts(started.list_id, 1, 100);
+  return { listId: started.list_id, total: members.total, contactIds: members.data.map((c) => c.id) };
+}

package/blocks/sequencer/README.md

@@ -0,0 +1,87 @@
+# sequencer
+
+Build multi-channel outreach (email, LinkedIn, calls), launch it, enroll contacts, and watch results. The
+Apollo / Outreach "sequences" screen.
+
+Depends on: `lists` (the audience) and `mailboxes` (the sender). Install: `npx @graph8/sdk add sequencer`.
+
+## Components
+
+| Component | What it does | Tiers |
+|---|---|---|
+| `SequenceList` | Sequences with status. Launch (after a copy preview), pause, resume, duplicate, archive. | read, write, external, destructive |
+| `SequenceBuilder` | Build a draft (email, LinkedIn, call, call task + a sender), or edit an existing sequence's steps. | read, write, external, destructive |
+| `StepEditor` | One step's form, with the rules the API only enforces at send time. | read |
+| `EnrollDialog` | Confirm and enroll contacts, with the recipient count and a deliverability warning. | read, external |
+| `SequenceStats` | Totals, per-step progress, skip reasons, per-contact state with pause and resume. | read, write, external |
+
+Launch, pause, resume, enroll and step edits reach or change what real people receive, so each opens
+`ConfirmSpendDialog` first (with the recipient count where it applies). Archive is destructive and the API cannot
+un-archive.
+
+## The flow, in order
+
+1. **Pick a sender and an audience.** `SequenceBuilder` -> `listMailboxes` (the chosen mailbox `id` and `email`
+   become the sequence channel) and `listLists` (the list `id` becomes `associated_list_id`).
+2. **Create the draft.** `createSequence` with all steps and the channel in one call (confirmed; nobody is contacted).
+   It returns the sequence `id`.
+3. **Check the copy.** `SequenceList` -> `previewSequence` before launch: `will_send_as_shown` and `content_issues`
+   catch broken tokens that would otherwise be deleted silently or block the launch with a 400.
+4. **Launch.** `runSequence` (confirmed with the contact count). Draft -> live.
+5. **Enroll more contacts.** `EnrollDialog` -> `addContactsToSequence` with `contact_ids` AND the `list_id` they
+   came from (both required). Already-enrolled contacts are skipped, so a retry never duplicates.
+6. **Watch.** `SequenceStats` -> `getSequenceStats`, `getSequenceAnalytics`, `listSequenceContacts`. Pause one
+   contact (`pauseSequenceContact`, write) or resume them (`resumeSequenceContact`, confirmed).
+
+## Step rules (why `StepEditor` exists)
+
+- **Email**: use `input_type: "MANUAL_TEMPLATE"` for your own subject and body. `ON_DEMAND` ignores them (the AI
+  writes each email from `instructions`).
+- **LinkedIn** is the `HEYREACH` step type: `linkedin_action_type` is required, and the copy goes in that action's
+  own key (`linkedin_connection_message`, `linkedin_message_text`, `linkedin_inmail_body`), never `body`.
+- **Call** is `PHONE`; **call task** is `MANUAL_DIALER` (a person works it in the dialer). Do-not-call numbers are never dialed by default.
+- `time_interval` is in seconds (the UI works in days). A step's `step_data` is replaced wholesale on update, so the
+  editor always sends the complete object.
+- Search results are masked until saved to a list: enroll contacts that already live in a list.
+
+## Prerequisites
+
+- A connected sending mailbox (`where: "api"`). Google and Microsoft are connected in the graph8 app.
+- An audience list with the contacts (`where: "api"`).
+- A LinkedIn sender account for LinkedIn steps (`where: "app"`): a sequence with LinkedIn steps and no sender cannot launch.
+
+## Defaults (do not ask the human)
+
+- Two days between steps; stop on reply; the person writes the email copy.
+- **Ask the human**: who to enroll and when to launch. Never launch or enroll without approval of the count.
+- SMS and WhatsApp steps exist in the API (`SMS`, `WHATSAPP`, `message_body`) but this block's builder covers email, LinkedIn, call and call task.
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| `list_sequences_sequences_get` | GET /sequences | read | SequenceList |
+| `preview_sequence_sequences__sequence_id__preview_get` | GET /sequences/{sequence_id}/preview | read | SequenceList |
+| `run_sequence_sequences__sequence_id__run_post` | POST /sequences/{sequence_id}/run | external | SequenceList |
+| `pause_sequence_sequences__sequence_id__pause_post` | POST /sequences/{sequence_id}/pause | external | SequenceList |
+| `resume_sequence_sequences__sequence_id__resume_post` | POST /sequences/{sequence_id}/resume | external | SequenceList |
+| `duplicate_sequence_sequences__sequence_id__duplicate_post` | POST /sequences/{sequence_id}/duplicate | write | SequenceList |
+| `archive_sequence_sequences__sequence_id__archive_post` | POST /sequences/{sequence_id}/archive | destructive | SequenceList |
+| `list_mailboxes_mailboxes_get` | GET /mailboxes | read | SequenceBuilder |
+| `list_lists_lists_get` | GET /lists | read | SequenceBuilder |
+| `create_sequence_sequences_post` | POST /sequences | external | SequenceBuilder |
+| `list_sequence_steps_sequences__sequence_id__steps_get` | GET /sequences/{sequence_id}/steps | read | SequenceBuilder |
+| `get_sequence_sequences__sequence_id__get` | GET /sequences/{sequence_id} | read | SequenceBuilder, EnrollDialog |
+| `add_sequence_steps_sequences__sequence_id__steps_post` | POST /sequences/{sequence_id}/steps | write | SequenceBuilder |
+| `update_sequence_step_sequences__sequence_id__steps__step_id__patch` | PATCH /sequences/{sequence_id}/steps/{step_id} | external | SequenceBuilder |
+| `delete_sequence_step_sequences__sequence_id__steps__step_id__delete` | DELETE /sequences/{sequence_id}/steps/{step_id} | destructive | SequenceBuilder |
+| `get_outreach_connection_integrations_linkedin_outreach_connection_get` | GET /integrations/linkedin-outreach/connection | read | StepEditor |
+| `get_safe_to_send_deliverability_safe_to_send_get` | GET /deliverability/safe-to-send | read | EnrollDialog |
+| `add_contacts_to_sequence_sequences__sequence_id__contacts_post` | POST /sequences/{sequence_id}/contacts | external | EnrollDialog |
+| `get_sequence_stats_sequences__sequence_id__stats_get` | GET /sequences/{sequence_id}/stats | read | SequenceStats |
+| `get_sequence_analytics_sequences__sequence_id__analytics_get` | GET /sequences/{sequence_id}/analytics | read | SequenceStats |
+| `list_sequence_contacts_sequences__sequence_id__contacts_get` | GET /sequences/{sequence_id}/contacts | read | SequenceStats |
+| `pause_sequence_contact_sequences__sequence_id__contacts__contact_id__pause_post` | POST /sequences/{sequence_id}/contacts/{contact_id}/pause | write | SequenceStats |
+| `resume_sequence_contact_sequences__sequence_id__contacts__contact_id__resume_post` | POST /sequences/{sequence_id}/contacts/{contact_id}/resume | external | SequenceStats |
+
+Recipes (`recipes/`): `create-multichannel-sequence.ts`, `launch-and-enroll.ts`, `sequence-report.ts`, `pause-when-unsafe.ts`.