@graph8/sdk 0.370.0 → 0.373.0

package/blocks/crm/components/contact-lookup-link.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+/**
+ * ContactLookupLink: "Open contact" for something that only knows a person's email (an inbox thread, a meeting
+ * attendee, a visitor). It looks the email up in your CRM and, when exactly one contact has it, shows a button that
+ * calls `onOpen(contactId)` (route to your contacts screen: `router.push("/contacts?id=" + id)`). When nobody has that
+ * email it renders nothing, so a thread from a stranger gets no dead button.
+ *
+ * SDK operations, in order:
+ *   1. listContacts  GET /contacts?email=<email>&limit=2   (read)
+ * Nothing here is billable, external or destructive.
+ */
+
+import { Button } from "@graph8/sdk/ui";
+import { UserRound } from "lucide-react";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+
+export interface ContactLookupLinkProps {
+  /** The person's email. Nothing is looked up (and nothing rendered) without one. */
+  email?: string | null;
+  /** Called with the CRM contact id when the button is clicked. */
+  onOpen: (contactId: number) => void;
+  label?: string;
+  variant?: "default" | "outline" | "secondary" | "ghost";
+  size?: "default" | "sm";
+}
+
+export function ContactLookupLink({ email, onOpen, label = "Open contact", variant = "outline", size = "sm" }: ContactLookupLinkProps) {
+  const address = email?.trim().toLowerCase() ?? "";
+  const q = useG8Query(
+    async (signal) => ((await g8Get<Array<{ id: number; work_email?: string | null }>>("/contacts", { email: address, limit: 2, page: 1 }, { signal })).data ?? []),
+    [address],
+    { enabled: address.includes("@"), key: ["contacts", "by-email", address] },
+  );
+  const match = (q.data ?? []).find((c) => !c.work_email || c.work_email.toLowerCase() === address);
+  if (!address || !match) return null;
+  return (
+    <Button size={size} variant={variant} onClick={() => onOpen(match.id)}>
+      <UserRound className="mr-1 size-4" aria-hidden />
+      {label}
+    </Button>
+  );
+}

package/blocks/crm/components/contacts-screen.tsx

@@ -40,10 +40,12 @@ import { RecordLink } from "@/g8/components/screen/record-link";
 import { plural } from "@/g8/lib/plural";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { useUrlState } from "@/g8/hooks/use-url-state";
+import { useUrlFilters } from "@/g8/hooks/use-url-filters";
+import { ListSelect } from "./list-select";
+import { MoreFilters, TextFilter } from "@/g8/components/screen/filter-controls";
 import { g8Delete, g8Get } from "@/g8/lib/g8-client";
-import { useDebouncedValue } from "../hooks/use-debounced";
 import { usePageQuery } from "../hooks/use-page-query";
-import { contactName, errorStatus, isMasked, location } from "../lib/crm-types";
+import { contactName, contactSubtitle, errorStatus, isMasked, location } from "../lib/crm-types";
 import type { ContactRecord, ScreenActionContext } from "../lib/crm-types";
 import { Pager, SortHead, formatDay, sortRows, useBulkDelete, useRowSelection, useSort } from "../lib/screen-parts";
 import { ActivityTimeline } from "./activity-timeline";
@@ -72,8 +74,10 @@ export interface ContactsScreenProps {
   className?: string;
 }
 
-interface Filters { name: string; job_title: string; seniority_level: string; country: string }
-const NO_FILTERS: Filters = { name: "", job_title: "", seniority_level: "", country: "" };
+/** Every filter the contacts API takes (name, email, job title, seniority, company name and id, country, state, city, department, industry), plus `list`. */
+const FILTER_KEYS = ["name", "job_title", "seniority_level", "country", "email", "company_name", "company_id", "state", "city", "job_department", "industry", "list"] as const;
+type FilterKey = (typeof FILTER_KEYS)[number];
+const MORE_KEYS: readonly FilterKey[] = ["email", "company_name", "company_id", "state", "city", "job_department", "industry", "list"];
 const SENIORITY = ["C-Suite", "VP", "Director", "Manager"];
 
 function sortValue(row: ContactRecord, key: string): string | null | undefined {
@@ -101,23 +105,27 @@ export function ContactsScreen(props: ContactsScreenProps) {
   const parsedId = idParam ? Number(idParam) : null;
   /** A malformed deep link (`?id=abc`) opens nothing instead of fetching /contacts/NaN. */
   const openId = parsedId != null && Number.isFinite(parsedId) ? parsedId : null;
-  const [draft, setDraft] = useState<Filters>(NO_FILTERS);
-  const filters = useDebouncedValue(draft);
+  // The filters live in the URL (`c_email=...`), so a filtered view survives reload, Back and sharing.
+  const urlFilters = useUrlFilters(FILTER_KEYS, { prefix: "c_" });
+  const { draft, filters } = urlFilters;
+  const apiFilters = Object.fromEntries(Object.entries(filters).filter(([k, v]) => v && k !== "list"));
+  const effectiveListId = listId ?? (filters.list ? Number(filters.list) : undefined);
   const [sheet, setSheet] = useState<"new" | "import" | "dupes" | null>(null);
   const [confirmDelete, setConfirmDelete] = useState(false);
   const [note, setNote] = useState<string | null>(null);
   const { sort, toggle: toggleSort } = useSort();
 
   const list = usePageQuery<ContactRecord>(
-    (page, signal) => g8Get<ContactRecord[]>("/contacts", { page, limit: pageSize, list_id: listId, ...Object.fromEntries(Object.entries(filters).filter(([, v]) => v)) }, { signal }),
-    [listId, filters],
+    (page, signal) => g8Get<ContactRecord[]>("/contacts", { page, limit: pageSize, list_id: effectiveListId, ...apiFilters }, { signal }),
+    [effectiveListId, filters],
     pageSize,
     ["contacts", "list", "screen"],
+    urlFilters.ready,
   );
   const dupes = useG8Query((signal) => g8Get<{ pending?: number; count?: number }>("/duplicates/counts", { entity_type: "contact" }, { signal }), [], { key: ["duplicates", "counts", "contact"] });
   const selection = useRowSelection<ContactRecord>(`${listId}|${JSON.stringify(filters)}`);
   const rows = useMemo(() => sortRows(list.rows, sort, sortValue), [list.rows, sort]);
-  const hasFilters = Object.values(draft).some(Boolean);
+  const hasFilters = urlFilters.active;
   const pending = dupes.data?.data.pending ?? dupes.data?.data.count;
   const lockedOnPage = list.rows.filter((r) => isMasked(r.work_email)).length;
 
@@ -131,7 +139,7 @@ export function ContactsScreen(props: ContactsScreenProps) {
   });
   const allOnPage = rows.length > 0 && rows.every((r) => selection.selected.has(r.id));
   const reload = () => { void list.refetch(); void dupes.refetch(); };
-  const set = (key: keyof Filters, v: string) => setDraft((f) => ({ ...f, [key]: v }));
+  const set = (key: FilterKey, v: string) => urlFilters.set(key, v);
 
   useEffect(() => { setNote(null); }, [filters, listId]);
 
@@ -173,7 +181,17 @@ export function ContactsScreen(props: ContactsScreenProps) {
                     {SENIORITY.map((s) => <option key={s} value={s}>{s}</option>)}
                   </select>
                   <input aria-label="Filter by country" placeholder="Country" className="h-9 w-32 rounded-md border bg-background px-3 text-sm" value={draft.country} onChange={(e) => set("country", e.target.value)} />
-                  {hasFilters ? <Button variant="ghost" size="sm" onClick={() => setDraft(NO_FILTERS)}>Clear filters</Button> : null}
+                  <MoreFilters activeCount={MORE_KEYS.filter((k) => draft[k]).length}>
+                    <TextFilter label="email" type="email" value={draft.email} onChange={(v) => set("email", v)} className="w-44" />
+                    <TextFilter label="company name" placeholder="Company" value={draft.company_name} onChange={(v) => set("company_name", v)} />
+                    <TextFilter label="company ID" placeholder="Company ID" type="number" value={draft.company_id} onChange={(v) => set("company_id", v)} className="w-28" />
+                    <TextFilter label="industry" value={draft.industry} onChange={(v) => set("industry", v)} />
+                    <TextFilter label="department" placeholder="Department" value={draft.job_department} onChange={(v) => set("job_department", v)} />
+                    <TextFilter label="state" value={draft.state} onChange={(v) => set("state", v)} className="w-28" />
+                    <TextFilter label="city" value={draft.city} onChange={(v) => set("city", v)} className="w-32" />
+                    {listId == null ? <ListSelect label="Filter by list" emptyOption="Any list" value={draft.list} valueLabel={`List ${draft.list}`} pageSize={100} onChange={(l) => set("list", l ? String(l.id) : "")} /> : null}
+                  </MoreFilters>
+                  {hasFilters ? <Button variant="ghost" size="sm" onClick={urlFilters.clear}>Clear filters</Button> : null}
                 </>
               }
             />
@@ -229,7 +247,7 @@ export function ContactsScreen(props: ContactsScreenProps) {
                 <EmptyState
                   title={hasFilters ? "No contacts match these filters" : "No contacts yet"}
                   description={hasFilters ? "Try fewer filters." : "Add your first contact or import a file."}
-                  action={hasFilters ? <Button variant="outline" onClick={() => setDraft(NO_FILTERS)}>Clear filters</Button> : <Button onClick={() => setSheet("new")}>New contact</Button>}
+                  action={hasFilters ? <Button variant="outline" onClick={urlFilters.clear}>Clear filters</Button> : <Button onClick={() => setSheet("new")}>New contact</Button>}
                 />
               ) : null}
               <Pager page={list.page} pageCount={list.pageCount} total={list.total} noun="contacts" hasNext={list.hasNext} loading={list.loading} onPage={list.setPage} />
@@ -326,7 +344,7 @@ function ContactPanel({ full, setFull, contactId, seed, onClose, onChanged, onDe
     <>
       <DetailPanel
         title={name}
-        subtitle={[contact.job_title, contact.company?.name ?? contact.company_name].filter(Boolean).join(" at ") || "No title or company"}
+        subtitle={contactSubtitle(contact)}
         avatar={<EntityAvatar name={name} kind="person" size="lg" />}
         badges={isMasked(contact.work_email) ? <StatusPill tone="warning" dot>Locked email</StatusPill> : undefined}
         onClose={onClose}

package/blocks/crm/components/dedupe-review.tsx

@@ -21,6 +21,7 @@
 import { useState } from "react";
 import { Button, Tabs, TabsContent, TabsList, TabsTrigger } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
+import { FirstNotice } from "@/g8/components/paging-notices";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { EmptyState } from "@/g8/components/empty-state";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
@@ -53,6 +54,9 @@ function side(pair: Pair, s: "a" | "b", entity: "contact" | "company") {
   return { id: pair[`${s}_id`] as number, name: name || String([pair[`${s}_email`], pair[`${s}_domain`]].find((v) => v && !isMasked(v)) ?? `#${pair[`${s}_id`]}`), lines: lines.filter(Boolean).map((l) => (isMasked(l) ? "Locked" : String(l))) };
 }
 
+/** The recent-merges API has no paging: a full read is announced under the list. */
+const RECENT_LIMIT = 25;
+
 export function DedupeReview({ entity, onChanged, className }: DedupeReviewProps) {
   const brand = useBrand();
   const plural = entity === "contact" ? "contacts" : "companies";
@@ -67,7 +71,7 @@ export function DedupeReview({ entity, onChanged, className }: DedupeReviewProps
     const res = await g8Get<{ items: Pair[]; next_cursor?: string | null }>("/duplicates", { entity_type: entity, status: "pending", limit: 25, cursor }, { signal });
     return { data: res.data.items ?? [], pagination: { next_cursor: res.data.next_cursor ?? null } };
   }, [entity]);
-  const recent = useG8Query((signal) => g8Get<MergeRow[]>("/duplicates/recent-merges", { entity_type: entity, limit: 25 }, { signal }), [entity]);
+  const recent = useG8Query((signal) => g8Get<MergeRow[]>("/duplicates/recent-merges", { entity_type: entity, limit: RECENT_LIMIT }, { signal }), [entity]);
   const [busy, setBusy] = useState<string | null>(null);
   const dropPick = (id: string | undefined) => id && setPicked((p) => { const n = new Set(p); n.delete(id); return n; });
   const refreshAll = () => { void pairs.reload(); void counts.refetch(); void recent.refetch(); onChanged?.(); };
@@ -145,6 +149,7 @@ export function DedupeReview({ entity, onChanged, className }: DedupeReviewProps
               {m.can_undo ? <Button size="sm" variant="outline" loading={undo.loading && busy === m.id} onClick={() => void undo.mutate(m.id)}>Undo</Button> : null}
             </div>
           ))}
+          <FirstNotice shown={(recent.data?.data ?? []).length} limit={RECENT_LIMIT} noun="merges" />
         </TabsContent>
       </Tabs>
 

package/blocks/crm/components/import-wizard.tsx

@@ -20,6 +20,7 @@
 import { useEffect, useState } from "react";
 import { Button, Input, Label, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
+import { ListSelect } from "./list-select";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
@@ -38,7 +39,6 @@ export interface ImportWizardProps {
 export interface ImportResult { imported?: number | null; updated?: number | null; skipped?: number | null; failed?: number | null; list_id?: number | null }
 interface Upload { datafile_id: string; row_count?: number | null; columns: string[] }
 interface Preview { rows: Array<Record<string, unknown>>; total: number }
-interface ListOption { id: number; title: string; type?: string | null }
 
 export const IMPORT_TARGETS: Array<{ value: string; label: string }> = [
   { value: "CONTACT_FIRST_NAME", label: "First name" }, { value: "CONTACT_LAST_NAME", label: "Last name" },
@@ -80,7 +80,6 @@ export function ImportWizard({ listId, onImported, maxBytes = 5 * 1024 * 1024, c
   const [confirmOpen, setConfirmOpen] = useState(false);
   const [result, setResult] = useState<ImportResult | null>(null);
 
-  const lists = useG8Query((signal) => g8Get<ListOption[]>("/lists", { limit: 200 }, { signal }), [], { enabled: upload != null && listId == null });
   const send = useG8Mutation((file: File) => { const body = new FormData(); body.append("file", file); return g8Post<Upload>("/imports", body); }, {
     onSuccess: (r) => { setUpload(r.data); setMapping(guessMapping(r.data.columns ?? [])); },
   });
@@ -107,7 +106,7 @@ export function ImportWizard({ listId, onImported, maxBytes = 5 * 1024 * 1024, c
   if (result) {
     return (
       <div className={`flex flex-col gap-3 ${className ?? ""}`} role="status">
-        <h3 className="text-base font-semibold">Import finished</h3>
+        <h3 className="text-base font-medium">Import finished</h3>
         <p className="text-sm">{result.imported ?? 0} new, {result.updated ?? 0} updated, {result.skipped ?? 0} skipped, {result.failed ?? 0} failed.</p>
         <Button variant="outline" onClick={() => { setResult(null); setUpload(null); setMapping({}); setDestination(listId); setNewListTitle(""); setPolicy("autofill"); setEnrich(false); run.reset(); preview.reset(); }}>Import another file</Button>
       </div>
@@ -161,10 +160,7 @@ export function ImportWizard({ listId, onImported, maxBytes = 5 * 1024 * 1024, c
             <h3 className="text-sm font-medium">3. Destination and rules</h3>
             {listId == null ? (
               <div className="flex flex-wrap items-center gap-2">
-                <select aria-label="Destination list" className="h-9 rounded-md border bg-background px-2 text-sm" value={destination ?? ""} onChange={(e) => setDestination(e.target.value ? Number(e.target.value) : undefined)}>
-                  <option value="">New list...</option>
-                  {(lists.data?.data ?? []).filter((l) => !l.type || l.type === "contacts").map((l) => <option key={l.id} value={l.id}>{l.title}</option>)}
-                </select>
+                <ListSelect label="Destination list" emptyOption="New list..." type="contacts" pageSize={200} value={destination} valueLabel={newListTitle.trim() || undefined} enabled={upload != null && listId == null} selectClassName="h-9 rounded-md border bg-background px-2 text-sm" onChange={(l) => setDestination(l ? l.id : undefined)} />
                 {destination == null ? <Input aria-label="New list name" placeholder="New list name" className="w-56" value={newListTitle} onChange={(e) => setNewListTitle(e.target.value)} /> : null}
               </div>
             ) : null}

package/blocks/crm/components/list-select.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+/**
+ * ListSelect: the audience-list dropdown with the list read wired in. A native select that is searchable (server
+ * search once there is more than one page) and paged ("Load more lists"), so the 201st list is reachable. It is the
+ * foundation's ListSelect plus `GET /lists` (the foundation holds no API scope); every block that picks a list
+ * (forms, lists, newsletter, nurture, sequencer, dialer) imports this one.
+ *
+ * SDK operations, in order:
+ *   1. GET /lists?search&page&limit   (lists.listLists)   read - through lib/read-lists.ts
+ */
+import { ListSelect as BaseListSelect } from "@/g8/components/list-select";
+import type { ListSelectProps } from "@/g8/components/list-select";
+import { readLists } from "../lib/read-lists";
+
+export type { ListSelectOption } from "@/g8/components/list-select";
+
+export function ListSelect(props: Omit<ListSelectProps, "read">) {
+  return <BaseListSelect {...props} read={readLists} />;
+}

package/blocks/crm/components/record-engagement-tab.tsx

@@ -0,0 +1,103 @@
+"use client";
+
+/**
+ * RecordEngagementTab: how much a contact or company has engaged: emails, calls, meetings, LinkedIn, website visits and
+ * downloads, the last touch, and the pages visited in the last 90 days. Use it as an `extraDetailTabs` entry of
+ * ContactsScreen / CompaniesScreen:
+ *   { id: "engagement", label: "Engagement", render: (c) => <RecordEngagementTab kind="contacts" id={c.id} /> }
+ *
+ * SDK operations, in order:
+ *   1. getContactEngagementSummary  GET /contacts/{id}/engagement-summary   (read) when kind="contacts"
+ *      getCompanyEngagementSummary  GET /companies/{id}/engagement-summary  (read) when kind="companies"
+ *   2. getContactSitesVisited       GET /contacts/{id}/sites-visited?days=90  (read) when kind="contacts"
+ *      getCompanySitesVisited       GET /companies/{id}/sites-visited?days=90 (read) when kind="companies"
+ * Nothing here is billable, external or destructive. The visits list is shown ten at a time with "Show more", so the
+ * count in the heading always matches what can be reached.
+ */
+
+import { useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { Activity } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+
+/** The counts both summaries share (the contact one adds LinkedIn and the last touch). */
+interface Summary { emails?: number | null; calls?: number | null; meetings?: number | null; linkedin?: number | null; website_visits?: number | null; downloads?: number | null; contact_count?: number | null; last_contact?: string | null; last_contact_checked?: boolean | null }
+interface Visit { url?: string | null; domain?: string | null; title?: string | null; event_date?: string | null; page_type?: string | null }
+interface Visits { visits?: Visit[] | null; total_visits?: number | null }
+
+const STEP = 10;
+const DAYS = 90;
+
+function dataOf<T>(env: unknown): T {
+  const d = (env as { data?: unknown } | null)?.data;
+  return (d && typeof d === "object" ? d : {}) as T;
+}
+
+function when(iso: string | null | undefined): string {
+  const d = iso ? new Date(iso) : null;
+  return d && !Number.isNaN(d.getTime()) ? d.toLocaleDateString(undefined, { month: "short", day: "numeric", year: "numeric" }) : "";
+}
+
+const count = (n: number | null | undefined): string => (typeof n === "number" ? n.toLocaleString() : "-");
+
+export interface RecordEngagementTabProps {
+  kind: "contacts" | "companies";
+  id: number;
+}
+
+export function RecordEngagementTab({ kind, id }: RecordEngagementTabProps) {
+  const [shown, setShown] = useState(STEP);
+  const summary = useG8Query(async (signal) => dataOf<Summary>(await g8Get(`/${kind}/${id}/engagement-summary`, undefined, { signal })), [kind, id]);
+  const visits = useG8Query(async (signal) => dataOf<Visits>(await g8Get(`/${kind}/${id}/sites-visited`, { days: DAYS }, { signal })), [kind, id]);
+
+  if (summary.error) return <ApiError error={summary.error} title="Could not load engagement" onRetry={() => void summary.refetch()} />;
+  if (!summary.data) return <Skeleton className="h-32 w-full" aria-label="Loading engagement" />;
+  const s = summary.data;
+  const items = [
+    { label: "Emails", value: count(s.emails) },
+    { label: "Calls", value: count(s.calls) },
+    { label: "Meetings", value: count(s.meetings) },
+    ...(kind === "contacts" ? [{ label: "LinkedIn", value: count(s.linkedin) }] : [{ label: "People", value: count(s.contact_count) }]),
+    { label: "Website visits", value: count(s.website_visits) },
+    { label: "Downloads", value: count(s.downloads) },
+    ...(kind === "contacts" ? [{ label: "Last touch", value: when(s.last_contact) || (s.last_contact_checked === false ? "Not checked" : "No touch yet") }] : []),
+  ];
+  const rows = visits.data?.visits ?? [];
+  const total = rows.length;
+  const reported = visits.data?.total_visits ?? total;
+  return (
+    <div className="space-y-4">
+      <KeyValueList columns={2} items={items} />
+      <section aria-label="Pages visited" className="space-y-2">
+        <h3 className="text-sm font-medium">Pages visited, last {DAYS} days</h3>
+        {visits.error ? <ApiError error={visits.error} title="Could not load pages visited" onRetry={() => void visits.refetch()} /> : null}
+        {!visits.error && !visits.data ? <Skeleton className="h-16 w-full" aria-label="Loading pages visited" /> : null}
+        {visits.data && total === 0 ? <EmptyState compact icon={<Activity className="size-8" />} title="No pages visited" description={`No website visits in the last ${DAYS} days.`} /> : null}
+        {total > 0 ? (
+          <>
+            <ul className="divide-y rounded-md border">
+              {rows.slice(0, shown).map((v, i) => (
+                <li key={`${v.url}-${i}`} className="flex items-center justify-between gap-3 p-3 text-sm">
+                  <span className="min-w-0">
+                    <span className="block truncate font-medium">{v.title || v.url || "Page"}</span>
+                    <span className="block truncate text-xs text-muted-foreground">{[v.domain, v.page_type].filter(Boolean).join(" · ")}</span>
+                  </span>
+                  <span className="shrink-0 text-xs text-muted-foreground">{when(v.event_date)}</span>
+                </li>
+              ))}
+            </ul>
+            <div className="flex items-center justify-between text-sm text-muted-foreground">
+              <span role="status">Showing {Math.min(shown, total).toLocaleString()} of {total.toLocaleString()} visits</span>
+              {shown < total ? <Button size="sm" variant="outline" onClick={() => setShown((n) => n + STEP)}>Show more</Button> : null}
+            </div>
+            {reported > total ? <p role="note" className="text-xs text-muted-foreground">The API returned {total.toLocaleString()} of {reported.toLocaleString()} visits in this window. Narrow it in the visitors screen to see the rest.</p> : null}
+          </>
+        ) : null}
+      </section>
+    </div>
+  );
+}

package/blocks/crm/components/record-form.tsx

@@ -178,7 +178,7 @@ export function RecordForm(props: RecordFormProps) {
 
       {validation ? <p role="alert" className="text-sm text-destructive">{validation}</p> : null}
       {duplicate ? (
-        <div role="alert" className="rounded-md border border-amber-300 bg-amber-50 p-3 text-sm">
+        <div role="alert" className="rounded-md border border-warning-foreground/30 bg-warning p-3 text-sm">
           A contact with this email or LinkedIn URL already exists{existingId ? ` (id ${existingId})` : ""}.
           {props.onDuplicate ? <Button type="button" variant="link" size="sm" onClick={() => props.onDuplicate?.(existingId)}>Open the existing contact</Button> : null}
         </div>

package/blocks/crm/components/tasks-screen.tsx

@@ -37,8 +37,9 @@ import { RecordLink } from "@/g8/components/screen/record-link";
 import { plural } from "@/g8/lib/plural";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { useUrlState } from "@/g8/hooks/use-url-state";
+import { useUrlFilters } from "@/g8/hooks/use-url-filters";
+import { MoreFilters, TextFilter } from "@/g8/components/screen/filter-controls";
 import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
-import { useDebouncedValue } from "../hooks/use-debounced";
 import { usePageQuery } from "../hooks/use-page-query";
 import { errorStatus } from "../lib/crm-types";
 import { Pager, formatDay, useBulkDelete, useRowSelection } from "../lib/screen-parts";
@@ -54,6 +55,8 @@ export interface WorkspaceTask extends TaskItem {
 }
 
 export interface TasksScreenProps {
+  /** The signed-in person's user id. With it the toolbar gets a "My tasks" toggle (assignee filter); without it the toggle is hidden. */
+  currentUserId?: string;
   pageSize?: number;
   /** Which tab opens first. Default "open". */
   initialStatus?: "open" | "completed" | "all";
@@ -85,6 +88,10 @@ function PriorityPill({ priority }: { priority?: number | null }) {
   return <StatusPill tone={priority === 1 ? "negative" : priority === 2 ? "warning" : "neutral"}>{PRIORITY[priority] ?? "Low"}</StatusPill>;
 }
 
+/** Every filter the tasks API takes besides the status tab: search, priority, type, linked record type, assignee, creator, source meeting; `mine` = assigned to the signed-in person. */
+const FILTER_KEYS = ["search", "priority", "task_type", "entity_type", "assignee_id", "created_by", "source_meeting_id", "mine"] as const;
+type FilterKey = (typeof FILTER_KEYS)[number];
+
 export function TasksScreen(props: TasksScreenProps) {
   const { pageSize = 25 } = props;
   const [idParam, setIdParamRaw] = useUrlState("id");
@@ -94,28 +101,35 @@ export function TasksScreen(props: TasksScreenProps) {
   const setIdParam = (v: string | null): void => { if (v == null) setView(null); setIdParamRaw(v); };
   const openId = idParam || null;
   const [tab, setTab] = useState<Tab>(props.initialStatus ?? "open");
-  const [search, setSearch] = useState("");
-  const [priority, setPriority] = useState("");
-  const [taskType, setTaskType] = useState("");
-  const [entityType, setEntityType] = useState(props.defaultRecord?.entity_type ?? "");
-  const q = useDebouncedValue(search);
+  // Filters live in the URL (`t_priority=1`, `t_mine=1`), so a filtered view survives reload, Back and sharing.
+  const urlFilters = useUrlFilters(FILTER_KEYS, { prefix: "t_" });
+  const { draft, filters } = urlFilters;
+  const search = draft.search;
+  const priority = draft.priority;
+  const taskType = draft.task_type;
+  const entityType = props.defaultRecord?.entity_type ?? draft.entity_type;
+  const q = filters.search;
+  // "My tasks" needs the signed-in person's user id: the app passes it as `currentUserId` (the pickers block's
+  // useCurrentMember gives it), so this screen holds no team-members scope of its own.
+  const assigneeId = draft.mine && props.currentUserId ? props.currentUserId : filters.assignee_id || undefined;
   const [sheet, setSheet] = useState<"new" | "edit" | null>(null);
   const [confirmDelete, setConfirmDelete] = useState(false);
   const [note, setNote] = useState<string | null>(null);
 
-  const scope = { status: tab === "all" ? undefined : tab, search: q || undefined, priority: priority || undefined, task_type: taskType || undefined, entity_type: entityType || undefined, entity_id: props.defaultRecord?.entity_id };
+  const scope = { status: tab === "all" ? undefined : tab, search: q || undefined, priority: filters.priority || undefined, task_type: filters.task_type || undefined, entity_type: (props.defaultRecord?.entity_type ?? filters.entity_type) || undefined, assignee_id: assigneeId, created_by: filters.created_by || undefined, source_meeting_id: filters.source_meeting_id || undefined, entity_id: props.defaultRecord?.entity_id };
   const list = usePageQuery<WorkspaceTask>(
     (page, signal) => g8Get<WorkspaceTask[]>("/tasks", { limit: pageSize, offset: (page - 1) * pageSize, ...scope }, { signal }),
-    [scope.status, scope.search, scope.priority, scope.task_type, scope.entity_type, scope.entity_id],
+    [scope.status, scope.search, scope.priority, scope.task_type, scope.entity_type, scope.entity_id, scope.assignee_id, scope.created_by, scope.source_meeting_id],
     pageSize,
     ["tasks", "list", "screen"],
+    urlFilters.ready,
   );
   const recordScope = { entity_type: props.defaultRecord?.entity_type, entity_id: props.defaultRecord?.entity_id };
   const openCount = useG8Query((signal) => g8Get<WorkspaceTask[]>("/tasks", { status: "open", limit: 1, ...recordScope }, { signal }), [recordScope.entity_type, recordScope.entity_id], { key: ["tasks", "count", "open", recordScope] });
   const doneCount = useG8Query((signal) => g8Get<WorkspaceTask[]>("/tasks", { status: "completed", limit: 1, ...recordScope }, { signal }), [recordScope.entity_type, recordScope.entity_id], { key: ["tasks", "count", "completed", recordScope] });
   const selection = useRowSelection<WorkspaceTask>(JSON.stringify(scope));
   const reload = () => { void list.refetch(); void openCount.refetch(); void doneCount.refetch(); };
-  const hasFilters = Boolean(search || priority || taskType || entityType);
+  const hasFilters = Boolean(search || priority || taskType || draft.entity_type || draft.assignee_id || draft.created_by || draft.source_meeting_id || draft.mine);
   const overdue = list.rows.filter(isOverdue).length;
 
   const toggle = useG8Mutation((t: WorkspaceTask) => g8Patch(`/tasks/${t.id}`, { status: t.status === "completed" ? "open" : "completed" }), { invalidates: ["tasks"], onSuccess: reload });
@@ -130,7 +144,7 @@ export function TasksScreen(props: TasksScreenProps) {
     if (openId && gone.includes(openId)) setIdParam(null);
     reload();
   });
-  useEffect(() => { setNote(null); }, [tab, q, priority, taskType, entityType]);
+  useEffect(() => { setNote(null); }, [tab, filters]);
   const allOnPage = list.rows.length > 0 && list.rows.every((r) => selection.selected.has(r.id));
 
   return (
@@ -162,21 +176,27 @@ export function TasksScreen(props: TasksScreenProps) {
         list={
           <div className="flex flex-col gap-3">
             <Toolbar
-              search={{ value: search, onChange: setSearch, placeholder: "Search tasks by title" }}
+              search={{ value: search, onChange: (v) => urlFilters.set("search", v), debounceMs: 0, placeholder: "Search tasks by title" }}
               filters={
                 <>
-                  <select aria-label="Filter by priority" className="h-9 rounded-md border bg-background px-2 text-sm" value={priority} onChange={(e) => setPriority(e.target.value)}>
+                  <select aria-label="Filter by priority" className="h-9 rounded-md border bg-background px-2 text-sm" value={priority} onChange={(e) => urlFilters.set("priority", e.target.value)}>
                     <option value="">Any priority</option><option value="1">High</option><option value="2">Medium</option><option value="3">Low</option>
                   </select>
-                  <select aria-label="Filter by type" className="h-9 rounded-md border bg-background px-2 text-sm" value={taskType} onChange={(e) => setTaskType(e.target.value)}>
+                  <select aria-label="Filter by type" className="h-9 rounded-md border bg-background px-2 text-sm" value={taskType} onChange={(e) => urlFilters.set("task_type", e.target.value)}>
                     <option value="">Any type</option>{TASK_TYPES.map((t) => <option key={t} value={t}>{label(t)}</option>)}
                   </select>
                   {props.defaultRecord ? null : (
-                    <select aria-label="Filter by linked record" className="h-9 rounded-md border bg-background px-2 text-sm" value={entityType} onChange={(e) => setEntityType(e.target.value)}>
+                    <select aria-label="Filter by linked record" className="h-9 rounded-md border bg-background px-2 text-sm" value={entityType} onChange={(e) => urlFilters.set("entity_type", e.target.value)}>
                       <option value="">Any record</option>{ENTITY_TYPES.map((t) => <option key={t} value={t}>{label(t)}</option>)}
                     </select>
                   )}
-                  {hasFilters ? <Button variant="ghost" size="sm" onClick={() => { setSearch(""); setPriority(""); setTaskType(""); setEntityType(props.defaultRecord?.entity_type ?? ""); }}>Clear filters</Button> : null}
+                  {props.currentUserId ? <Button variant={draft.mine ? "default" : "outline"} size="sm" aria-pressed={Boolean(draft.mine)} onClick={() => urlFilters.set("mine", draft.mine ? "" : "1")}>My tasks</Button> : null}
+                  <MoreFilters activeCount={["assignee_id", "created_by", "source_meeting_id"].filter((k) => draft[k as FilterKey]).length}>
+                    <TextFilter label="assignee ID" placeholder="Assignee user ID" value={draft.assignee_id} onChange={(v) => urlFilters.set("assignee_id", v)} className="w-48" />
+                    <TextFilter label="creator ID" placeholder="Created by user ID" value={draft.created_by} onChange={(v) => urlFilters.set("created_by", v)} className="w-48" />
+                    <TextFilter label="meeting ID" placeholder="Source meeting ID" value={draft.source_meeting_id} onChange={(v) => urlFilters.set("source_meeting_id", v)} className="w-48" />
+                  </MoreFilters>
+                  {hasFilters ? <Button variant="ghost" size="sm" onClick={urlFilters.clear}>Clear filters</Button> : null}
                 </>
               }
             />

package/blocks/crm/hooks/use-all-lists.ts

@@ -0,0 +1,18 @@
+"use client";
+
+/**
+ * useAllLists: every list of the workspace, for a screen that must look one up by id (its size, its name). The lists API
+ * pages (`page`, `limit`), so this reads page after page (100 each, up to 20 pages) instead of one capped `limit=200`
+ * call; `truncated` says the page cap was reached. To CHOOSE a list use ListSelect (searchable, paged).
+ *
+ * SDK operations: GET /lists?page&limit   (lists.listLists)   read - through lib/read-lists.ts
+ */
+import { useAllPages } from "@/g8/hooks/use-all-pages";
+import type { ListSelectOption } from "@/g8/components/list-select";
+import { readLists } from "../lib/read-lists";
+
+const PAGE = 100;
+
+export function useAllLists(deps: readonly unknown[] = [], enabled = true) {
+  return useAllPages<ListSelectOption>((page, signal) => readLists("", page, PAGE, signal), deps, { enabled });
+}

package/blocks/crm/hooks/use-page-query.ts

@@ -34,12 +34,14 @@ export function usePageQuery<T>(
   deps: readonly unknown[],
   pageSize = 25,
   cacheKey?: readonly unknown[],
+  /** Hold the read (for example until URL filters are known). Default true. */
+  enabled = true,
 ): UsePageQueryResult<T> {
   const key = JSON.stringify(deps);
   const [state, setState] = useState({ key, page: 1 });
   const page = state.key === key ? state.page : 1;
   const queryKey: G8QueryKey | undefined = cacheKey ? [...cacheKey, { page, pageSize, deps: key }] : undefined;
-  const query = useG8Query((signal) => fetchPage(page, signal), [key, page], { key: queryKey });
+  const query = useG8Query((signal) => fetchPage(page, signal), [key, page], { key: queryKey, enabled });
 
   const info = query.data?.pagination as Partial<PageInfo> | undefined;
   const rows = (query.data?.data ?? []) as T[];

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

@@ -31,6 +31,8 @@ export interface ContactRecord {
   last_name?: string | null;
   full_name?: string | null;
   work_email?: string | null;
+  /** Personal addresses, comma separated. */
+  personal_emails?: string | null;
   direct_phone?: string | null;
   mobile_phone?: string | null;
   job_title?: string | null;
@@ -107,6 +109,18 @@ export function contactName(c: Pick<ContactRecord, "first_name" | "last_name" |
   return joined || c.full_name || (c.work_email && !isMasked(c.work_email) ? c.work_email : "") || (c.id != null ? `#${c.id}` : "-");
 }
 
+/**
+ * The line under a contact's name: "VP of Sales at Acme". The company is the company's own name (`company.name`, else the
+ * list row's `company_name`); it never falls back to anything about the person. "at ..." is left out when there is no
+ * title or no company. A company that happens to share the person's name (a freelancer) is shown as the API sent it.
+ */
+export function contactSubtitle(c: Pick<ContactRecord, "job_title" | "company_name" | "company">): string {
+  const company = [c.company?.name, c.company_name].map((n) => (n ?? "").trim()).find((n) => n !== "");
+  const title = (c.job_title ?? "").trim();
+  if (title && company) return `${title} at ${company}`;
+  return title || company || "No title or company";
+}
+
 /** A company's display name: name, then domain, then `#id`, then a dash. Never "Unnamed". */
 export function companyName(c: { name?: string | null; domain?: string | null; id?: number | string }): string {
   return c.name || c.domain || (c.id != null ? `#${c.id}` : "-");

package/blocks/crm/lib/read-lists.ts

@@ -0,0 +1,16 @@
+"use client";
+
+/**
+ * readLists: one page of audience lists, for ListSelect and useAllLists.
+ *
+ * SDK operations: GET /lists?search&page&limit   (lists.listLists)   read
+ */
+import { g8Get } from "@/g8/lib/g8-client";
+import { hasNextOf } from "@/g8/lib/paging";
+import type { ListSelectOption, ListsReader } from "@/g8/components/list-select";
+
+export const readLists: ListsReader = async (q, page, pageSize, signal) => {
+  const env = await g8Get<ListSelectOption[]>("/lists", { search: q || undefined, page, limit: pageSize }, { signal });
+  const rows = (env.data ?? []) as ListSelectOption[];
+  return { rows, hasNext: hasNextOf(env, pageSize, rows.length) };
+};