@graph8/sdk 0.303.0 → 0.357.0

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

@@ -0,0 +1,191 @@
+"use client";
+
+/**
+ * RecordForm: create or edit one contact or company, including the org's custom
+ * fields. `record` present = edit (only changed fields are sent); absent = create.
+ *
+ * SDK operations, in order (all `write`, so no confirm dialog):
+ *   1. listContactFields | listCompanyFields   GET   /fields | /fields/companies   which custom fields to render
+ *   2. createContacts | createCompany          POST  /contacts | /companies        create (custom values ride along on contacts)
+ *      updateContact | updateCompany           PATCH /contacts/{id} | /companies/{id}   edit, only changed base fields
+ *   3. setFieldValuesBatch                     PATCH /fields/values/batch          custom values (edit, and company create)
+ *   4. createField                             POST  /fields                       optional inline "Add custom field"
+ *
+ * Creating a contact that already exists answers 409: the form says so and offers
+ * `onDuplicate(existingId)` instead of silently creating a second copy.
+ */
+
+import { useState } from "react";
+import type { FormEvent } from "react";
+import { Button, Input, Label } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useCustomFields } from "../hooks/use-custom-fields";
+import { compact, errorDetail, errorStatus, fieldLabel } from "../lib/crm-types";
+import type { CompanyRecord, ContactRecord, FieldDef } from "../lib/crm-types";
+
+export interface RecordFormProps {
+  entity: "contact" | "company";
+  /** Edit this record. Load it with `include_custom_fields=true` to prefill custom values. */
+  record?: ContactRecord | CompanyRecord;
+  /** Create only: also add the new record to this list. */
+  listId?: number;
+  onSaved?: (result: { id: number; merged: boolean }) => void;
+  /** Create only: a contact with the same identity exists; receives its id. */
+  onDuplicate?: (existingId: number | undefined) => void;
+  onCancel?: () => void;
+  /** Show the inline "Add custom field" control. Default true. */
+  allowNewFields?: boolean;
+  className?: string;
+}
+
+interface BaseField { key: string; label: string; required?: boolean; type?: string }
+
+const CONTACT_FIELDS: BaseField[] = [
+  { key: "first_name", label: "First name" }, { key: "last_name", label: "Last name" },
+  { key: "work_email", label: "Work email", type: "email" }, { key: "job_title", label: "Job title" },
+  { key: "seniority_level", label: "Seniority" }, { key: "linkedin_url", label: "LinkedIn URL", type: "url" },
+  { key: "direct_phone", label: "Direct phone", type: "tel" }, { key: "mobile_phone", label: "Mobile phone", type: "tel" },
+  { key: "city", label: "City" }, { key: "state", label: "State" }, { key: "country", label: "Country" },
+  { key: "company_domain", label: "Company domain" },
+];
+const COMPANY_FIELDS: BaseField[] = [
+  { key: "domain", label: "Domain", required: true }, { key: "name", label: "Name" },
+  { key: "website", label: "Website", type: "url" }, { key: "industry", label: "Industry" },
+  { key: "employee_count", label: "Employees (e.g. 51-200)" }, { key: "phone", label: "Phone", type: "tel" },
+  { key: "linkedin_url", label: "LinkedIn URL", type: "url" }, { key: "city", label: "City" },
+  { key: "state", label: "State" }, { key: "country", label: "Country" },
+];
+
+type Values = Record<string, string>;
+
+function initialValues(base: BaseField[], record: RecordFormProps["record"], custom: FieldDef[]): Values {
+  const source = (record ?? {}) as unknown as Record<string, unknown>;
+  const out: Values = {};
+  for (const f of base) out[f.key] = typeof source[f.key] === "string" && source[f.key] !== "***" ? (source[f.key] as string) : "";
+  for (const f of custom) out[`cf:${f.name}`] = (record?.custom_fields?.[f.name ?? ""] ?? "") as string;
+  return out;
+}
+
+function CustomInput({ field, value, onChange }: { field: FieldDef; value: string; onChange: (v: string) => void }) {
+  const id = `cf-${field.id}`;
+  return (
+    <div className="flex flex-col gap-1">
+      <Label htmlFor={id}>{fieldLabel(field)}</Label>
+      {field.data_type === "boolean" ? (
+        <select id={id} className="h-9 rounded-md border bg-background px-2 text-sm" value={value} onChange={(e) => onChange(e.target.value)}>
+          <option value="">Not set</option><option value="true">Yes</option><option value="false">No</option>
+        </select>
+      ) : (
+        <Input id={id} type={field.data_type === "int" || field.data_type === "numeric" ? "number" : "text"} value={value} onChange={(e) => onChange(e.target.value)} />
+      )}
+    </div>
+  );
+}
+
+export function RecordForm(props: RecordFormProps) {
+  const { entity, record, listId } = props;
+  const plural = entity === "contact" ? "contacts" : "companies";
+  const base = entity === "contact" ? CONTACT_FIELDS : COMPANY_FIELDS;
+  const custom = useCustomFields(plural, listId);
+  const [edits, setEdits] = useState<Values>({});
+  const [newTitle, setNewTitle] = useState("");
+  const [newType, setNewType] = useState("text");
+  const [validation, setValidation] = useState<string | null>(null);
+
+  const initial = initialValues(base, record, custom.fields);
+  const value = (key: string) => edits[key] ?? initial[key] ?? "";
+  const set = (key: string, v: string) => setEdits((e) => ({ ...e, [key]: v }));
+
+  const addField = useG8Mutation(
+    (title: string) => g8Post("/fields", { title, data_type: newType, entity: plural, list_id: listId ?? null }),
+    { onSuccess: () => { setNewTitle(""); void custom.refetch(); } },
+  );
+
+  const save = useG8Mutation(async () => {
+    const baseValues = Object.fromEntries(base.map((f) => [f.key, value(f.key)]));
+    const customChanges = custom.fields.filter((f) => `cf:${f.name}` in edits);
+    let id = record?.id;
+    let merged = false;
+    if (record) {
+      const changed = Object.fromEntries(base.filter((f) => f.key in edits).map((f) => [f.key, edits[f.key]]));
+      if (Object.keys(changed).length) await g8Patch(`/${plural}/${record.id}`, changed);
+    } else if (entity === "contact") {
+      const customFields = Object.fromEntries(custom.fields.map((f) => [f.name!, value(`cf:${f.name}`)]).filter(([, v]) => v !== ""));
+      const created = await g8Post<{ contact_id?: number; merged?: boolean }>("/contacts", { ...compact(baseValues), list_id: listId, ...(Object.keys(customFields).length ? { custom_fields: customFields } : {}) });
+      id = created.data.contact_id;
+      merged = Boolean(created.data.merged);
+    } else {
+      const created = await g8Post<{ company_id?: number | null; merged?: boolean }>("/companies", { ...compact(baseValues), list_id: listId });
+      id = created.data.company_id ?? undefined;
+      merged = Boolean(created.data.merged);
+    }
+    const toWrite = record ? customChanges : custom.fields.filter((f) => entity === "company" && value(`cf:${f.name}`) !== "");
+    if (id != null && toWrite.length) {
+      await g8Patch("/fields/values/batch", { entity: plural, rows: [{ record_id: id, fields: toWrite.map((f) => ({ column_id: f.id, value: value(`cf:${f.name}`) || null })) }] });
+    }
+    return { id: id as number, merged };
+  }, { onSuccess: (r) => props.onSaved?.(r) });
+
+  const submit = (event: FormEvent) => {
+    event.preventDefault();
+    const missing = base.find((f) => f.required && !value(f.key).trim());
+    if (missing) return setValidation(`${missing.label} is required.`);
+    if (!record && entity === "contact" && !["first_name", "last_name", "work_email", "linkedin_url"].some((k) => value(k).trim())) {
+      return setValidation("Enter a name, an email or a LinkedIn URL.");
+    }
+    if (value("work_email") && entity === "contact" && !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(value("work_email"))) return setValidation("Work email is not a valid address.");
+    setValidation(null);
+    void save.mutate(undefined);
+  };
+
+  const duplicate = !record && errorStatus(save.error) === 409;
+  const existingId = (errorDetail(save.error)?.update as { contact_id?: number } | null | undefined)?.contact_id;
+  const dirty = Object.keys(edits).length > 0;
+
+  return (
+    <form noValidate onSubmit={submit} className={`flex flex-col gap-4 ${props.className ?? ""}`} aria-label={record ? `Edit ${entity}` : `New ${entity}`}>
+      <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
+        {base.map((f) => (
+          <div key={f.key} className="flex flex-col gap-1">
+            <Label htmlFor={`f-${f.key}`}>{f.label}{f.required ? " *" : ""}</Label>
+            <Input id={`f-${f.key}`} type={f.type ?? "text"} value={value(f.key)} onChange={(e) => set(f.key, e.target.value)} />
+          </div>
+        ))}
+      </div>
+
+      {custom.fields.length > 0 ? (
+        <fieldset className="grid grid-cols-1 gap-3 sm:grid-cols-2">
+          <legend className="mb-1 text-sm font-medium">Custom fields</legend>
+          {custom.fields.map((f) => <CustomInput key={f.id} field={f} value={value(`cf:${f.name}`)} onChange={(v) => set(`cf:${f.name}`, v)} />)}
+        </fieldset>
+      ) : null}
+      {custom.error ? <ApiError error={custom.error} title="Could not load custom fields" onRetry={() => void custom.refetch()} /> : null}
+
+      {props.allowNewFields !== false ? (
+        <div className="flex flex-wrap items-end gap-2">
+          <div className="flex flex-col gap-1"><Label htmlFor="new-field-title">New custom field</Label><Input id="new-field-title" placeholder="Field name" value={newTitle} onChange={(e) => setNewTitle(e.target.value)} /></div>
+          <select aria-label="Field type" className="h-9 rounded-md border bg-background px-2 text-sm" value={newType} onChange={(e) => setNewType(e.target.value)}>
+            <option value="text">Text</option><option value="int">Whole number</option><option value="numeric">Decimal</option><option value="boolean">Yes/no</option>
+          </select>
+          <Button type="button" variant="outline" size="sm" disabled={!newTitle.trim()} loading={addField.loading} onClick={() => void addField.mutate(newTitle.trim())}>Add field</Button>
+        </div>
+      ) : null}
+      {addField.error ? <ApiError error={addField.error} title="Could not add the field" /> : null}
+
+      {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">
+          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>
+      ) : save.error ? <ApiError error={save.error} title="Could not save" /> : null}
+
+      <div className="flex justify-end gap-2">
+        {props.onCancel ? <Button type="button" variant="ghost" onClick={props.onCancel}>Cancel</Button> : null}
+        <Button type="submit" loading={save.loading} disabled={Boolean(record) && !dirty}>{record ? "Save changes" : `Create ${entity}`}</Button>
+      </div>
+    </form>
+  );
+}

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

@@ -0,0 +1,107 @@
+"use client";
+
+/**
+ * TaskList: open and completed tasks on a contact or company, with quick add,
+ * complete/reopen and delete.
+ *
+ * SDK operations, in order:
+ *   1. listContactTasks | listCompanyTasks   GET    /contacts/{id}/tasks | /companies/{id}/tasks   (read)
+ *   2. createTask | createCompanyTask        POST   same path                                      (write)
+ *   3. updateTask                            PATCH  /tasks/{task_id}  status open|completed        (write)
+ *   4. deleteTask                            DELETE /tasks/{task_id}                               (destructive, ConfirmSpendDialog)
+ *
+ * Priority: 1 high, 2 medium, 3 low, 0 none.
+ */
+
+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, g8Patch, g8Post } from "@/g8/lib/g8-client";
+
+export interface TaskItem {
+  id: string;
+  title: string;
+  description?: string | null;
+  due_date?: string | null;
+  status?: string | null;
+  priority?: number | null;
+  assignee_name?: string | null;
+}
+
+export interface TaskListProps {
+  entity: "contact" | "company";
+  entityId: number;
+  /** Show completed tasks too. Default false. */
+  includeCompleted?: boolean;
+  onChanged?: () => void;
+  className?: string;
+}
+
+const PRIORITY = ["", "High", "Medium", "Low", "Low"];
+
+export function TaskList({ entity, entityId, includeCompleted = false, onChanged, className }: TaskListProps) {
+  const base = `/${entity === "contact" ? "contacts" : "companies"}/${entityId}/tasks`;
+  const [title, setTitle] = useState("");
+  const [due, setDue] = useState("");
+  const [priority, setPriority] = useState(2);
+  const [showDone, setShowDone] = useState(includeCompleted);
+  const [deleting, setDeleting] = useState<TaskItem | null>(null);
+
+  const tasks = useG8Query((signal) => g8Get<TaskItem[]>(base, { status: showDone ? undefined : "open" }, { signal }), [base, showDone]);
+  const done = () => { void tasks.refetch(); onChanged?.(); };
+  const add = useG8Mutation(
+    () => g8Post(base, { title: title.trim(), priority, ...(due ? { due_date: due } : {}) }),
+    { onSuccess: () => { setTitle(""); setDue(""); done(); } },
+  );
+  const toggle = useG8Mutation((t: TaskItem) => g8Patch(`/tasks/${t.id}`, { status: t.status === "completed" ? "open" : "completed" }), { onSuccess: done });
+  const remove = useG8Mutation((id: string) => g8Delete(`/tasks/${id}`), { onSuccess: () => { setDeleting(null); done(); } });
+
+  const items = (tasks.data?.data ?? []) as TaskItem[];
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      <form className="flex flex-wrap items-end gap-2" onSubmit={(e) => { e.preventDefault(); if (title.trim()) void add.mutate(undefined); }}>
+        <Input aria-label="Task title" placeholder="Add a task" className="min-w-48 flex-1" value={title} onChange={(e) => setTitle(e.target.value)} />
+        <Input aria-label="Due date" type="date" className="w-40" value={due} onChange={(e) => setDue(e.target.value)} />
+        <select aria-label="Priority" className="h-9 rounded-md border bg-background px-2 text-sm" value={priority} onChange={(e) => setPriority(Number(e.target.value))}>
+          <option value={1}>High</option><option value={2}>Medium</option><option value={3}>Low</option><option value={0}>None</option>
+        </select>
+        <Button type="submit" size="sm" loading={add.loading} disabled={!title.trim()}>Add task</Button>
+      </form>
+      <label className="flex items-center gap-2 text-sm text-muted-foreground">
+        <input type="checkbox" checked={showDone} onChange={(e) => setShowDone(e.target.checked)} /> Show completed
+      </label>
+
+      {add.error ? <ApiError error={add.error} title="Could not add the task" /> : null}
+      {toggle.error ? <ApiError error={toggle.error} title="Could not update the task" /> : null}
+      {remove.error ? <ApiError error={remove.error} title="Could not delete the task" /> : null}
+      {tasks.error ? <ApiError error={tasks.error} title="Could not load tasks" onRetry={() => void tasks.refetch()} /> : null}
+      {tasks.loading && !tasks.data ? <Skeleton className="h-12 w-full" /> : null}
+      {!tasks.loading && !tasks.error && items.length === 0 ? <EmptyState title="No tasks" description="Add a follow-up so nothing slips." /> : null}
+
+      <ul className="flex flex-col gap-2">
+        {items.map((t) => {
+          const completed = t.status === "completed";
+          return (
+            <li key={t.id} className="flex items-center gap-3 rounded-md border p-3" data-testid="task-item">
+              <input type="checkbox" aria-label={`${completed ? "Reopen" : "Complete"} ${t.title}`} checked={completed} onChange={() => void toggle.mutate(t)} />
+              <div className="min-w-0 flex-1">
+                <p className={`truncate text-sm ${completed ? "text-muted-foreground line-through" : "font-medium"}`}>{t.title}</p>
+                <p className="text-xs text-muted-foreground">
+                  {[t.due_date ? `Due ${new Date(t.due_date).toLocaleDateString(undefined, { timeZone: "UTC" })}` : null, PRIORITY[t.priority ?? 0] || null, t.assignee_name].filter(Boolean).join(" - ")}
+                </p>
+              </div>
+              <Button variant="ghost" size="sm" onClick={() => setDeleting(t)}>Delete</Button>
+            </li>
+          );
+        })}
+      </ul>
+
+      <ConfirmSpendDialog open={deleting != null} tier="destructive" title="Delete this task" description={deleting?.title} affected={1}
+        confirming={remove.loading} onConfirm={() => deleting && void remove.mutate(deleting.id)} onCancel={() => setDeleting(null)} />
+    </div>
+  );
+}

package/blocks/crm/hooks/use-custom-fields.ts

@@ -0,0 +1,18 @@
+"use client";
+
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { isCustomField } from "../lib/crm-types";
+import type { CrmEntity, FieldDef } from "../lib/crm-types";
+
+/**
+ * The org's custom columns for contacts or companies (`GET /fields`,
+ * `GET /fields/companies`). `fields` are the custom ones only, in API order;
+ * `all` includes the base columns. Pass `listId` to also get list-scoped columns. `enabled: false` makes no request.
+ */
+export function useCustomFields(entity: CrmEntity, listId?: number, enabled = true) {
+  const path = entity === "contacts" ? "/fields" : "/fields/companies";
+  const query = useG8Query((signal) => g8Get<FieldDef[]>(path, { list_id: listId }, { signal }), [path, listId], { enabled });
+  const all = (query.data?.data ?? []) as FieldDef[];
+  return { fields: all.filter(isCustomField), all, loading: query.loading, error: query.error, refetch: query.refetch };
+}

package/blocks/crm/hooks/use-debounced.ts

@@ -0,0 +1,13 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/** `value`, but only after it stopped changing for `ms`. Keeps filter boxes from firing a request per keystroke. */
+export function useDebouncedValue<T>(value: T, ms = 300): T {
+  const [v, setV] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setV(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return v;
+}

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

@@ -0,0 +1,52 @@
+"use client";
+
+import { useState } from "react";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import type { G8Envelope } from "@/g8/lib/g8-client";
+import type { PageInfo } from "../lib/crm-types";
+
+export interface UsePageQueryResult<T> {
+  rows: T[];
+  total: number;
+  page: number;
+  pageCount: number;
+  hasNext: boolean;
+  setPage: (page: number) => void;
+  loading: boolean;
+  error: unknown;
+  refetch: () => Promise<unknown>;
+}
+
+/**
+ * Page-number pagination for list endpoints that answer
+ * `{ data: T[], pagination: { page, limit, total, has_next } }` (contacts,
+ * companies, lists...). `usePaginated` follows cursors; these endpoints do not
+ * have one, so the table keeps a page number instead.
+ *
+ * Changing `deps` (a filter, a search box) goes back to page 1 without a second request.
+ */
+export function usePageQuery<T>(
+  fetchPage: (page: number, signal: AbortSignal) => Promise<G8Envelope<T[]>>,
+  deps: readonly unknown[],
+  pageSize = 25,
+): UsePageQueryResult<T> {
+  const key = JSON.stringify(deps);
+  const [state, setState] = useState({ key, page: 1 });
+  const page = state.key === key ? state.page : 1;
+  const query = useG8Query((signal) => fetchPage(page, signal), [key, page]);
+
+  const info = query.data?.pagination as Partial<PageInfo> | undefined;
+  const rows = (query.data?.data ?? []) as T[];
+  const total = info?.total ?? rows.length;
+  return {
+    rows,
+    total,
+    page,
+    pageCount: Math.max(1, Math.ceil(total / (info?.limit ?? pageSize))),
+    hasNext: info?.has_next ?? false,
+    setPage: (next) => setState({ key, page: Math.max(1, next) }),
+    loading: query.loading,
+    error: query.error,
+    refetch: query.refetch,
+  };
+}

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

@@ -0,0 +1,136 @@
+"use client";
+
+/**
+ * Shared shapes and tiny helpers for the CRM block. Types only describe the
+ * fields the components read; the API may return more.
+ *
+ * Masked fields: search results and credit-locked records send "***" instead of
+ * a real email/phone. `isMasked` is the single check every component uses, so a
+ * masked value is never rendered, copied or sent as if it were real.
+ */
+
+export interface PageInfo {
+  page: number;
+  limit: number;
+  total: number;
+  has_next: boolean;
+}
+
+export interface CompanySummary {
+  id?: number | null;
+  name?: string | null;
+  domain?: string | null;
+  industry?: string | null;
+  employee_count?: string | null;
+  logo_url?: string | null;
+}
+
+export interface ContactRecord {
+  id: number;
+  first_name?: string | null;
+  last_name?: string | null;
+  full_name?: string | null;
+  work_email?: string | null;
+  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;
+  state?: string | null;
+  country?: string | null;
+  about?: string | null;
+  company_id?: number | null;
+  company_name?: string | null;
+  company_domain?: string | null;
+  company?: CompanySummary | null;
+  owner_name?: string | null;
+  custom_fields?: Record<string, string | null> | null;
+  created_at?: string | null;
+  updated_at?: string | null;
+}
+
+export interface CompanyRecord {
+  id: number;
+  name?: string | null;
+  domain?: string | null;
+  website?: string | null;
+  description?: string | null;
+  industry?: string | null;
+  employee_count?: string | null;
+  revenue?: string | null;
+  founded_year?: number | null;
+  phone?: string | null;
+  address?: string | null;
+  city?: string | null;
+  state?: string | null;
+  country?: string | null;
+  zip?: string | null;
+  linkedin_url?: string | null;
+  logo_url?: string | null;
+  contact_count?: number | null;
+  owner_name?: string | null;
+  custom_fields?: Record<string, string | null> | null;
+  created_at?: string | null;
+  updated_at?: string | null;
+}
+
+/** A column definition from `GET /fields` (contacts) or `GET /fields/companies`. */
+export interface FieldDef {
+  id: number | null;
+  title: string;
+  name: string | null;
+  data_type: string;
+  label?: string | null;
+  is_global?: boolean;
+}
+
+export type CrmEntity = "contacts" | "companies";
+
+/** Base columns are named like CONTACT_FIRST_NAME / COMPANY_NAME; custom ones carry a slug (udo_*). */
+export function isCustomField(field: FieldDef): boolean {
+  return field.id != null && !/^(CONTACT|COMPANY)_[A-Z0-9_]+$/.test(field.name ?? "");
+}
+
+export function fieldLabel(field: FieldDef): string {
+  return field.label || field.title;
+}
+
+/** True for the "***" placeholder the API sends for a locked email or phone. */
+export function isMasked(value: unknown): boolean {
+  return typeof value === "string" && value.trim() === "***";
+}
+
+export function contactName(c: Pick<ContactRecord, "first_name" | "last_name" | "full_name" | "work_email">): string {
+  const joined = [c.first_name, c.last_name].filter(Boolean).join(" ").trim();
+  return joined || c.full_name || (c.work_email && !isMasked(c.work_email) ? c.work_email : "") || "Unnamed contact";
+}
+
+export function initials(name: string): string {
+  return name
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((p) => p[0]?.toUpperCase())
+    .join("");
+}
+
+export function location(r: { city?: string | null; state?: string | null; country?: string | null }): string {
+  return [r.city, r.state, r.country].filter(Boolean).join(", ");
+}
+
+/** Skip empty-string values so a PATCH only sends what the person actually filled. */
+export function compact<T extends Record<string, unknown>>(values: T): Partial<T> {
+  return Object.fromEntries(Object.entries(values).filter(([, v]) => v !== "" && v != null)) as Partial<T>;
+}
+
+export function errorStatus(error: unknown): number | undefined {
+  return (error as { status?: number } | null)?.status;
+}
+
+/** The `detail` object of a G8Error when the API sent one (409 duplicate hints, for example). */
+export function errorDetail(error: unknown): Record<string, unknown> | undefined {
+  const detail = (error as { detail?: unknown } | null)?.detail;
+  return detail && typeof detail === "object" && !Array.isArray(detail) ? (detail as Record<string, unknown>) : undefined;
+}

package/blocks/crm/recipes/custom-fields-and-values.ts

@@ -0,0 +1,28 @@
+/**
+ * @title Create a custom field and write values to many records at once
+ * @when Adding an org-specific column (a score, a segment) and filling it for a batch of contacts or
+ * companies. Field creation is a write; values go in with one batch call (up to 500 rows) instead of one
+ * request per record. Field ids come from the create or list response.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function scoreContacts(scores: Array<{ contactId: number; score: number }>) {
+  const existing = await g8.fields.listContactFields();
+  let field = existing.data.find((f) => f.title === "Fit score");
+  if (!field) {
+    const created = await g8.fields.create({ title: "Fit score", entity: "contacts", data_type: "int" });
+    field = { id: created.id, title: created.title, name: created.name, data_type: created.data_type, is_global: created.is_global };
+  }
+  if (field.id == null) throw new Error("Fit score has no column id");
+
+  const columnId = field.id;
+  const result = await g8.api.fields.setFieldValuesBatch({
+    body: {
+      entity: "contacts",
+      rows: scores.map((s) => ({ record_id: s.contactId, fields: [{ column_id: columnId, value: String(s.score) }] })),
+    },
+  });
+  return result.data;
+}

package/blocks/crm/recipes/dedupe-and-merge.ts

@@ -0,0 +1,30 @@
+/**
+ * @title Review duplicate suggestions and merge one pair
+ * @when Cleaning the CRM. A merge is destructive (the secondary record stops existing; undo works for
+ * 30 days), so list and preview freely but ask a human before calling `mergeContact`. The suggestion
+ * and contact ids come from the list response.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function pendingContactDuplicates() {
+  const counts = await g8.api.duplicates.duplicateCounts({ query: { entity_type: "contact" } });
+  const page = await g8.api.duplicates.listDuplicates({ query: { entity_type: "contact", status: "pending", limit: 25 } });
+  return { counts: counts.data, page: page.data };
+}
+
+/** Side-by-side comparison and blocker check; writes nothing. */
+export async function previewMerge(keepId: number, dropId: number) {
+  const preview = await g8.api.contacts.previewContactMerge({ path: { contact_id: keepId }, query: { secondary: dropId } });
+  return preview.data;
+}
+
+/** DESTRUCTIVE. Only after a person confirmed which record to keep. */
+export async function mergeConfirmed(keepId: number, dropId: number, suggestionId: string) {
+  const merged = await g8.api.contacts.mergeContact({
+    path: { contact_id: keepId },
+    body: { secondary_id: dropId, suggestion_id: suggestionId },
+  });
+  return merged.data;
+}

package/blocks/crm/recipes/notes-tasks-and-activity.ts

@@ -0,0 +1,23 @@
+/**
+ * @title Log a note, create a follow-up task and read the activity feed
+ * @when Recording what happened on a contact or company and showing the combined timeline. The feed is
+ * one read over notes, tasks, emails, calls, meetings and field changes, newest first.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function logCallOutcome(contactId: number, summary: string, followUpOn: string) {
+  await g8.notes.create(contactId, summary);
+  const task = await g8.tasks.create(contactId, { title: "Follow up", due_date: followUpOn, priority: 1 });
+
+  // Company-level notes work the same way: g8.notes.createForCompany(companyId, text).
+  const feed = await g8.api.contacts.getActivityFeed({
+    query: { entity_type: "contact", entity_id: String(contactId), types: "note,task,email,call", limit: 20 },
+  });
+  return { taskId: task.id, feed: feed.data };
+}
+
+export async function completeTask(taskId: string) {
+  return g8.tasks.update(taskId, { status: "completed" });
+}

package/blocks/crm/recipes/upsert-contact-with-company.ts

@@ -0,0 +1,33 @@
+/**
+ * @title Upsert a contact with its company and custom fields, then read it back
+ * @when Server-side sync or form handler that must write a person who may already exist. `upsert`
+ * matches on work_email, then linkedin_url, so it is safe to retry; `company_domain` links (or creates)
+ * the company; `custom_fields` are keyed by the field title or slug. The ids you need next come from
+ * the responses: look the contact up by email to get its id, never guess it.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const LIST_ID = Number(process.env.G8_LIST_ID); // a list the contact belongs to (see the lists block)
+
+export async function upsertPerson(email: string, name: { first: string; last: string }, domain: string) {
+  const result = await g8.contacts.upsert({
+    list_id: LIST_ID,
+    work_email: email,
+    first_name: name.first,
+    last_name: name.last,
+    company_domain: domain,
+    custom_fields: { "Lead source": "website" },
+    create_missing_fields: true,
+  });
+
+  // upsert answers { action, count }, not the id: find the contact by its (exact, case-insensitive) email.
+  const { data } = await g8.contacts.list({ email, limit: 1 });
+  const contact = data[0];
+  if (!contact) throw new Error(`upserted ${email} (${result.action}) but could not read it back`);
+
+  // The full record, including custom fields and the linked company.
+  const detail = await g8.api.contacts.getContact({ path: { contact_id: contact.id }, query: { include_custom_fields: true } });
+  return { action: result.action, contact: detail.data };
+}