@graph8/sdk 0.362.0 → 0.373.0

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

@@ -0,0 +1,235 @@
+"use client";
+
+/**
+ * ProspectSearchScreen: the finished prospecting page. People / Companies tabs, a filter builder with saved searches
+ * on the left, the results with paging and the locked-field banner on the right, and, once results are saved, a panel
+ * with the NEW list's real (unlocked) contacts.
+ *
+ * Composes: ScreenLayout, SplitView, DetailPanel, SectionCard (screen kit), FilterBuilder, SavedSearches,
+ * ProspectResults (results + SaveToListDialog), ContactTable (crm), AddToListButton (lists).
+ *
+ * User flows:
+ *   - choose People or Companies (`?tab=`), add filters (real value suggestions), Search, page through matches
+ *   - Clear filters; load, name and delete saved searches
+ *   - Save results to a new list (billable, confirmed, polled until built), then "Open list" shows the saved members:
+ *     emails and phones are unlocked now, and they can be added to another list from the same panel
+ *   - hand the saved list to your own next step (enrich, enroll) through `renderSavedListActions`
+ * Masked results never appear as values: locked cells read "Locked" and have no contact id until saved.
+ *
+ * SDK operations (all inside the parts it composes): getFilterOptions, getAutocompleteSuggestions (read),
+ * searchContacts / searchCompanies (read in practice), saveContactSearch / saveCompanySearch (billable, ConfirmSpendDialog),
+ * listLists (polling), listSavedSearches / saveSearch / deleteSavedSearch (destructive, ConfirmSpendDialog),
+ * listContacts + addContactsToList for the saved list's members.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Bookmark, ExternalLink, ListChecks, Play, Search, Trash2 } from "lucide-react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get } from "@/g8/lib/g8-client";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { ContactTable } from "@/g8/crm/components/contact-table";
+import { AddToListButton } from "@/g8/lists/components/add-to-list-button";
+import { OPERATOR_LABEL, completeFilters, fieldsFor, isLocked } from "../lib/search-types";
+import type { ProspectCompany, ProspectContact, SearchCondition, SearchResource } from "../lib/search-types";
+import { FilterBuilder } from "./filter-builder";
+import { ProspectResults } from "./prospect-results";
+import { SAVED_FORMAT, SavedSearches } from "./saved-searches";
+import type { SavedListInfo } from "./save-to-list-dialog";
+import { useBrand } from "@/g8/hooks/use-brand";
+
+export interface ProspectSearchScreenProps {
+  /** Which tab opens first when `?tab=` is absent. Default people. */
+  defaultResource?: SearchResource;
+  pageSize?: number;
+  confirmSearch?: boolean;
+  creditsPerRecord?: number;
+  onSaved?: (list: SavedListInfo) => void;
+  toolbarActions?: ReactNode;
+  /** Buttons for the saved list panel, for example enrich or enroll: `(list) => <BulkEnrichPanel listId={list.id} />`. */
+  renderSavedListActions?: (list: SavedListInfo) => ReactNode;
+  className?: string;
+}
+
+
+type Row = ProspectContact & ProspectCompany;
+
+interface SavedRow { id: number; title: string; scope?: string | null; icp_query?: { format?: string; filters?: SearchCondition[] } & Record<string, unknown>; created_at?: string | null }
+
+const CONTACT_FACTS: Array<[string, keyof ProspectContact]> = [
+  ["Job title", "job_title"], ["Seniority", "seniority_level"], ["Department", "job_department"], ["Work email", "work_email"], ["Direct phone", "direct_phone"],
+  ["Mobile phone", "mobile_phone"], ["Personal email", "personal_emails"], ["LinkedIn", "linkedin_url"], ["City", "city"], ["State", "state"], ["Country", "country"],
+  ["Company", "company_name"], ["Company domain", "company_domain"], ["Industry", "company_industry"],
+];
+const COMPANY_FACTS: Array<[string, keyof ProspectCompany]> = [
+  ["Domain", "domain"], ["Industry", "industry"], ["Employees", "employee_count"], ["Revenue", "revenue"], ["City", "city"], ["State", "state"], ["Country", "country"], ["LinkedIn", "linkedin_url"],
+];
+
+/** Every field of a search result. Locked values read "Locked" and are never shown; there is no contact id until it is saved to a list. */
+function ProspectDetail({ row, resource, onClose }: { row: Row; resource: SearchResource; onClose: () => void }) {
+  const person = resource === "contacts";
+  const name = person ? [row.first_name, row.last_name].filter(Boolean).join(" ") || "Contact" : row.name ?? "Company";
+  const facts = (person ? CONTACT_FACTS : COMPANY_FACTS).map(([label, key]) => {
+    const locked = person && isLocked(row, key as keyof ProspectContact);
+    const raw = (row as Record<string, unknown>)[key as string];
+    const text = typeof raw === "string" || typeof raw === "number" ? String(raw) : "";
+    const link = text && key === "linkedin_url" && !locked ? <a className="inline-flex items-center gap-1 underline" href={text.startsWith("http") ? text : `https://${text}`} target="_blank" rel="noreferrer">{text}<ExternalLink className="size-3" aria-hidden /></a> : null;
+    return { label, value: locked ? <StatusPill tone="neutral">Locked</StatusPill> : (link ?? text) };
+  });
+  const hasLocked = person && (row.locked_fields?.length ?? 0) > 0;
+  return (
+    <DetailPanel title={name} subtitle={person ? [row.job_title, row.company_name].filter(Boolean).join(" at ") : row.industry} onClose={onClose}
+      avatar={<EntityAvatar name={name} kind={person ? "person" : "company"} size="lg" />}
+      badges={hasLocked ? <StatusPill tone="warning" dot>Details locked</StatusPill> : undefined}>
+      <div className="flex flex-col gap-4 p-1">
+        <KeyValueList columns={2} items={facts} />
+        {!person && row.description ? <p className="text-sm">{String(row.description)}</p> : null}
+        <p className="text-xs text-muted-foreground">{hasLocked ? "Locked fields unlock when you save these results to a list. " : ""}A search result has no contact id: save the results to a list to work with the real record.</p>
+      </div>
+    </DetailPanel>
+  );
+}
+
+/** Saved searches of both kinds in one place, each openable (`?id=`) with its filters, Run and Delete. */
+function SavedSearchesTab({ onRun, toolbarId, setToolbarId }: { onRun: (resource: SearchResource, filters: SearchCondition[]) => void; toolbarId: string; setToolbarId: (v: string | null) => void }) {
+  const brand = useBrand();
+  const [deleting, setDeleting] = useState<SavedRow | null>(null);
+  const [view, setView] = useUrlState("view");
+  const full = view === "full";
+  const all = useG8Query(async (signal) => {
+    const [c, p] = await Promise.all((["contacts", "companies"] as const).map((scope) => g8Get<SavedRow[]>("/search/saved-searches", { scope }, { signal })));
+    return [...((c.data ?? []) as SavedRow[]), ...((p.data ?? []) as SavedRow[])];
+  }, []);
+  const remove = useG8Mutation((id: number) => g8Delete(`/search/saved-searches/${id}`), { onSuccess: (_r, id) => { setDeleting(null); if (String(id) === toolbarId) setToolbarId(null); void all.refetch(); } });
+  const rows = all.data ?? [];
+  const open = rows.find((r) => String(r.id) === toolbarId);
+  const loadable = (r: SavedRow) => r.icp_query?.format === SAVED_FORMAT && Array.isArray(r.icp_query.filters) && r.icp_query.filters.length > 0;
+  const resourceOf = (r: SavedRow): SearchResource => (r.scope === "companies" ? "companies" : "contacts");
+  const list = (
+    <div className="flex flex-col gap-3 p-1">
+      {all.error ? <ApiError error={all.error} title="Could not load saved searches" onRetry={() => void all.refetch()} /> : null}
+      {remove.error ? <ApiError error={remove.error} title="Could not delete the search" /> : null}
+      {all.loading && !all.data ? <Skeleton className="h-24 w-full" /> : null}
+      {!all.loading && !all.error && rows.length === 0 ? <EmptyState icon={<Bookmark className="size-6" aria-hidden />} title="No saved searches" description="Build filters on the People or Companies tab and name them to keep them here." /> : null}
+      <ul className="divide-y rounded-md border">
+        {rows.map((r) => (
+          <li key={r.id} className={r.id === open?.id ? "bg-muted/50" : ""}>
+            <button type="button" className="flex w-full items-center gap-3 p-3 text-left" onClick={() => setToolbarId(String(r.id))}>
+              <Bookmark className="size-4 text-muted-foreground" aria-hidden />
+              <span className="min-w-0 flex-1 truncate text-sm font-medium">{r.title}</span>
+              <StatusPill tone="neutral">{resourceOf(r) === "companies" ? "Companies" : "People"}</StatusPill>
+            </button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+  const detail = open ? (
+    <DetailPanel key={open.id} onExpand={full ? undefined : () => setView("full")} onCollapse={full ? () => setView(null) : undefined} title={open.title} subtitle={`${resourceOf(open) === "companies" ? "Companies" : "People"} search`} onClose={() => setToolbarId(null)}
+      actions={(<>
+        <Button size="sm" disabled={!loadable(open)} onClick={() => onRun(resourceOf(open), open.icp_query!.filters!)}><Play className="mr-1 size-4" aria-hidden />Run search</Button>
+        <Button size="sm" variant="outline" onClick={() => setDeleting(open)}><Trash2 className="mr-1 size-4" aria-hidden />Delete</Button>
+      </>)}>
+      <div className="flex flex-col gap-4 p-1">
+        {loadable(open) ? (
+          <ul className="flex flex-col gap-1" aria-label="Saved filters">
+            {open.icp_query!.filters!.map((f, i) => {
+              const meta = fieldsFor(resourceOf(open)).find((m) => m.key === f.field);
+              return <li key={i} className="text-sm"><strong>{meta?.label ?? f.field}</strong> {OPERATOR_LABEL[f.operator] ?? f.operator} {(f.value ?? []).map(String).join(", ")}</li>;
+            })}
+          </ul>
+        ) : <p className="text-sm text-muted-foreground">Saved in the {brand.linkLabel} app. It uses the app's own format, so it can be seen here but not run.</p>}
+        <KeyValueList items={[{ label: "Saved", value: open.created_at ? new Date(open.created_at).toLocaleDateString() : "" }, { label: "Search id", value: String(open.id), mono: true }]} columns={2} />
+      </div>
+    </DetailPanel>
+  ) : null;
+  return (
+    <>
+      <SplitView expanded={full} onExpandedChange={(e) => setView(e ? "full" : null)} list={list} detail={detail} detailOpen={open != null} onCloseDetail={() => setToolbarId(null)} detailTitle="Saved search" />
+      <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)} />
+    </>
+  );
+}
+
+export function ProspectSearchScreen({ defaultResource = "contacts", pageSize = 25, confirmSearch, creditsPerRecord, onSaved, toolbarActions, renderSavedListActions, className }: ProspectSearchScreenProps) {
+  const brand = useBrand();
+  const [tab, setTab] = useUrlState("tab", defaultResource === "companies" ? "companies" : "people");
+  const resource: SearchResource = tab === "companies" ? "companies" : "contacts";
+  const [savedId, setSavedId] = useUrlState("id");
+  const [draft, setDraft] = useState<SearchCondition[]>([]);
+  const [applied, setApplied] = useState<SearchCondition[]>([]);
+  const [saved, setSaved] = useState<SavedListInfo | null>(null);
+  const [prospect, setProspect] = useState<{ row: Row; resource: SearchResource } | null>(null);
+  const [membersKey, setMembersKey] = useState(0);
+
+  const switchTab = (id: string) => { setTab(id); setDraft([]); setApplied([]); setSaved(null); setProspect(null); setSavedId(null); };
+  const clear = () => { setDraft([]); setApplied([]); setProspect(null); };
+  const count = (l: SavedListInfo) => (l.contact_count ?? l.company_count ?? l.total ?? 0).toLocaleString();
+  const runSaved = (r: SearchResource, filters: SearchCondition[]) => { setTab(r === "companies" ? "companies" : "people"); setSavedId(null); setDraft(filters); setApplied(completeFilters(filters)); };
+
+  const left = (
+    <div className="flex min-w-0 flex-col gap-4 xl:grid xl:grid-cols-[20rem_minmax(0,1fr)]">
+      <div className="flex flex-col gap-4">
+        <SectionCard title="Filters" description="All filters must match. Pick values from the suggestions."
+          actions={<Button size="sm" variant="ghost" disabled={draft.length === 0 && applied.length === 0} onClick={clear}>Reset search</Button>}>
+          <FilterBuilder key={resource} resource={resource} value={draft} onChange={setDraft} onSearch={(f) => { setApplied(completeFilters(f)); setProspect(null); }} />
+        </SectionCard>
+        <SectionCard title="Saved searches">
+          <SavedSearches key={resource} resource={resource} current={draft} onLoad={(f) => { setDraft(f); setApplied(completeFilters(f)); setProspect(null); }} />
+        </SectionCard>
+      </div>
+      <div className="min-w-0">
+        <ProspectResults resource={resource} filters={applied} pageSize={pageSize} confirmSearch={confirmSearch} creditsPerRecord={creditsPerRecord}
+          onOpenRow={(row, r) => { setSaved(null); setProspect({ row, resource: r }); }}
+          onSaved={(list) => { setProspect(null); setSaved(list); setMembersKey((k) => k + 1); onSaved?.(list); }} />
+      </div>
+    </div>
+  );
+
+  const detail = saved ? (
+    <DetailPanel
+      key={saved.id}
+      title={saved.title}
+      subtitle={`${count(saved)} ${resource === "companies" ? "companies" : "contacts"} saved to your workspace`}
+      onClose={() => setSaved(null)}
+      actions={renderSavedListActions?.(saved)}
+    >
+      {resource === "companies"
+        ? <EmptyState icon={<ListChecks className="size-6" aria-hidden />} title="Companies saved" description={`The API has no read operation for company-list members, so review them in the ${brand.linkLabel} app.`} />
+        : (
+          <ContactTable listId={saved.id} selectable allowDelete={false} pageSize={10} refreshKey={membersKey}
+            renderBulkActions={({ ids, clear: done }) => <AddToListButton contactIds={ids} label="Add to another list" onAdded={() => done()} />} />
+        )}
+    </DetailPanel>
+  ) : prospect ? <ProspectDetail row={prospect.row} resource={prospect.resource} onClose={() => setProspect(null)} /> : null;
+
+  return (
+    <ScreenLayout
+      className={className}
+      title="Prospect search"
+      description="Find new people and companies, preview them, and save the ones you want to a list. Saving unlocks their details."
+      icon={<Search className="size-5" aria-hidden />}
+      actions={toolbarActions}
+      tabs={[{ id: "people", label: "People" }, { id: "companies", label: "Companies" }, { id: "saved", label: "Saved searches" }]}
+      activeTab={tab === "saved" ? "saved" : resource === "companies" ? "companies" : "people"}
+      onTabChange={switchTab}
+    >
+      {tab === "saved"
+        ? <SavedSearchesTab onRun={runSaved} toolbarId={savedId} setToolbarId={setSavedId} />
+        : <SplitView list={left} detail={detail} detailOpen={saved != null || prospect != null} onCloseDetail={() => { setSaved(null); setProspect(null); }} detailWidth="xl" detailTitle="Details" />}
+    </ScreenLayout>
+  );
+}

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

@@ -22,8 +22,10 @@ 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 { plural } from "@/g8/lib/plural";
 import { completeFilters } from "../lib/search-types";
 import type { SearchCondition, SearchResource } from "../lib/search-types";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export const SAVED_FORMAT = "g8-sdk-v1";
 
@@ -49,6 +51,7 @@ function loadable(s: SavedSearch): boolean {
 }
 
 export function SavedSearches({ resource = "contacts", current, onLoad, className }: SavedSearchesProps) {
+  const brand = useBrand();
   const [title, setTitle] = useState("");
   const [deleting, setDeleting] = useState<SavedSearch | null>(null);
   const ready = completeFilters(current);
@@ -78,7 +81,7 @@ export function SavedSearches({ resource = "contacts", current, onLoad, classNam
           <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>
+              <p className="text-xs text-muted-foreground">{loadable(s) ? plural(s.icp_query.filters!.length, "filter") : `Saved in the ${brand.linkLabel} 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>

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

@@ -1,8 +1,9 @@
 "use client";
 
 import { useG8Query } from "@/g8/hooks/use-g8-query";
-import { g8Get } from "@/g8/lib/g8-client";
-import type { SearchResource } from "../lib/search-types";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { completeFilters } from "../lib/search-types";
+import type { SearchCondition, SearchResource } from "../lib/search-types";
 
 export interface FilterOption {
   /** Normalised value: send this back as the filter value. */
@@ -12,21 +13,29 @@ export interface FilterOption {
 }
 
 const cache = new Map<string, FilterOption[]>();
+/** Each filter combination is its own key, so the cache is capped; the least recently used entry goes first. */
+const CACHE_LIMIT = 50;
 
 /**
  * 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}`;
+export function useFilterOptions(resource: SearchResource, field: string, enabled = true, within: SearchCondition[] = []) {
+  // With other filters already set, ask what exists WITHIN them (POST /search/filter-options): industries among
+  // companies in Spain, not every industry. An empty context falls back to the cached global list.
+  const context = completeFilters(within);
+  const key = `${resource}:${field}${context.length ? `:${JSON.stringify(context)}` : ""}`;
   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 });
+      if (hit) { cache.delete(key); cache.set(key, hit); return hit; }
+      const res = context.length
+        ? await g8Post<Record<string, FilterOption[]>>("/search/filter-options", { resource, fields: [field], filters: context }, { signal })
+        : await g8Get<Record<string, FilterOption[]>>("/search/filter-options", { resource, fields: [field] }, { signal });
       const options = res.data?.[field] ?? [];
       cache.set(key, options);
+      while (cache.size > CACHE_LIMIT) cache.delete(cache.keys().next().value as string);
       return options;
     },
     [key],
@@ -39,3 +48,8 @@ export function useFilterOptions(resource: SearchResource, field: string, enable
 export function clearFilterOptionsCache(): void {
   cache.clear();
 }
+
+/** Test hook: how many option lists are cached. */
+export function filterOptionsCacheSize(): number {
+  return cache.size;
+}

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

@@ -111,6 +111,7 @@ export interface ProspectContact {
   direct_phone?: string | null;
   mobile_phone?: string | null;
   job_title?: string | null;
+  job_department?: string | null;
   seniority_level?: string | null;
   linkedin_url?: string | null;
   city?: string | null;
@@ -132,6 +133,7 @@ export interface ProspectCompany {
   state?: string | null;
   country?: string | null;
   linkedin_url?: string | null;
+  description?: string | null;
 }
 
 /** True when a value exists but is locked ("***", or named in `locked_fields`) until the contact is saved to a list. */

package/blocks/sequencer/README.md

@@ -5,12 +5,35 @@ Apollo / Outreach "sequences" screen.
 
 Depends on: `lists` (the audience) and `mailboxes` (the sender). Install: `npx @graph8/sdk add sequencer`.
 
+## Screens
+
+`SequencesScreen` is the finished page: mount it as the route. Every record type has a complete detail view,
+deep-linkable (`?id=` the sequence, `?dtab=` the tab, `?step=` a step, `?enrollment=` a contact's enrollment).
+
+- **List** with status filter and a stat strip (live, paused, drafts, contacts in live sequences, from the first
+  100). Launch (after a copy and sender check), pause, resume, duplicate, archive, all confirmed.
+- **New sequence** (header button): the builder in a sheet (audience list, email/LinkedIn/AI call/call task steps
+  and a sender for each step type); the new draft opens right away. Nobody is contacted until you launch it.
+- **`SequenceDetail`**: Details (every field, audience), Steps, Contacts, Results, plus the same actions as the list
+  and **Enroll contacts** (pick a list, tick contacts or enroll the whole list, confirm the recipient count).
+- **`SequenceStepsPanel`**: each step is a record (channel, wait, every field, per-state counts) and opens the editor.
+- **`SequenceEnrollments`**: each enrolled contact is a record (state, step, the full contact); pause directly,
+  resume confirmed.
+
+Slot props: `toolbarActions`, `renderDetailActions(sequence)`, `extraDetailTabs`, `ownerEmail`. Needs a connected
+sender mailbox and a contact list (see Prerequisites). `SequenceList` gained an optional `onChanged`; `EnrollDialog`
+an optional `note`.
+
+Known limits: "Enroll the whole list" reads at most 5,000 contacts (the enroll endpoint needs explicit
+`contact_ids`); a bigger list is cut there and the confirm says so. `?enrollment=` opens a contact only when it is on
+the enrollments page being shown (the API has no single-enrollment read), so a link to a later page opens nothing.
+
 ## 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 |
+| `SequenceList` | Sequences with status. Launch (after a copy and sender check), pause, resume, duplicate, archive. | read, write, external, destructive |
+| `SequenceBuilder` | Build a draft (email, LinkedIn, AI call, call task, a required list and a sender per step type), 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 |
@@ -21,12 +44,23 @@ 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.
+1. **Pick the senders and an audience.** Every step type needs its own sender, or `runSequence` answers 400:
+   - email steps: a mailbox from `listMailboxes`. The channel type comes from the mailbox `source` first:
+     `inboxkit` -> `INBOXKIT`, Google -> `GMAIL`, SMTP -> `SMTP`. A directly connected Microsoft mailbox
+     (`manual_microsoft`) cannot send from sequences yet, so the builder shows it disabled with the reason.
+   - AI call steps (`PHONE`, an AI voice agent calls): a Voice AI number (`inbound_type: "ai"`) from
+     `listSequencerPhoneNumbers` (GET /sequencer/channels/phone_numbers), channel type `PHONE`.
+   - call tasks (`MANUAL_DIALER`, a rep calls from the dialer): a dialer number (`inbound_type: "dialer"`), `PHONE`.
+   - LinkedIn steps: an account from `listLinkedinAccounts` (GET /sequencer/channels/linkedin_accounts), channel type
+     `LINKEDIN` (HeyReach), or `LINKEDIN_NETRION` with `NETRION` steps when the response says `provider: "NETRION"`.
+   - the audience: `listLists`; the list `id` becomes `associated_list_id`. **Required**: the API cannot set it later.
+2. **Create the draft.** `createSequence` with all steps and channels in one call (confirmed; nobody is contacted).
+   It returns the sequence `id`. Editing later: steps that need a sender the sequence lacks offer a picker and attach
+   it with `addSequenceChannels` (POST /sequences/{id}/channels) before the steps are appended.
+3. **Check before launch.** `SequenceList` / `SequenceDetail` -> `previewSequence`. The copy verdict is per step:
+   `steps[].rendered.will_send_as_shown` and `steps[].rendered.content_issues`. An `error` issue, a step type with no
+   sender channel (`channels[]`) or a missing audience list would make `/run` answer 400, so the launch is refused
+   with the reasons; other issues are warnings in the confirm dialog.
 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.
@@ -39,7 +73,8 @@ un-archive.
   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.
+- **AI call** is `PHONE`: an AI voice agent places the call from a Voice AI number. **Call task** is `MANUAL_DIALER`
+  (a person works it in the dialer, from a dialer number). 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.
@@ -49,6 +84,7 @@ un-archive.
 - 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.
+- A Voice AI number for AI call steps and a dialer number for call tasks (`where: "app"`).
 
 ## Defaults (do not ask the human)
 
@@ -75,6 +111,10 @@ un-archive.
 | `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 |
+| `list_sequencer_phone_numbers_sequencer_channels_phone_numbers_get` | GET /sequencer/channels/phone_numbers | read | SequenceBuilder |
+| `list_linkedin_accounts_sequencer_channels_linkedin_accounts_get` | GET /sequencer/channels/linkedin_accounts | read | SequenceBuilder |
+| `list_sequence_channels_sequences__sequence_id__channels_get` | GET /sequences/{sequence_id}/channels | read | SequenceBuilder |
+| `add_sequence_channels_sequences__sequence_id__channels_post` | POST /sequences/{sequence_id}/channels | write | 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 |
@@ -85,3 +125,9 @@ un-archive.
 | `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`.
+
+## Cross-block glue
+
+- `AddToSequenceButton` (`components/add-to-sequence-button.tsx`): "Add to sequence" for any selection of contacts (live sequences only, then the enroll dialog with its preflight and confirmation). `SequencesScreen` gains optional `onOpenContact`: an enrolled person gets an "Open in contacts" button.
+
+- `RecordSequencesTab` (`components/record-sequences-tab.tsx`): a contact's enrollments with state and step (`getContactSequences`, the API's 50 most recent, with a notice when full), `AddToSequenceButton`, and a confirmed Withdraw from one sequence (`withdrawContactsFromSequences`, needs `contacts:write`). `extraDetailTabs` entry for ContactsScreen.