@graph8/sdk 0.370.0 → 0.374.0

package/blocks/web-analytics/lib/analytics-scope.ts

@@ -0,0 +1,155 @@
+"use client";
+
+/**
+ * The scope every report shares: which sites, which window, and whether bots and internal traffic count. It lives in the
+ * URL (`site`, `days`, `from`, `to`, `bots`, `internal`), so one site picker and one window drive every tab and a link
+ * opens the same view.
+ *
+ * What the API rejects is never sent (each of these is a 400 from the backend):
+ *  - a site key that is not letters, digits, `-` or `_` (`write_key` goes into a SQL list; the router refuses anything else);
+ *  - `date_from` without `date_to`, an inverted range, a range wider than 365 days, a day that is not a calendar date;
+ *  - `days` outside 1..365.
+ * A URL that carries such a value is read as if the value were absent, and the picker shows the window really in use.
+ *
+ * SDK operations: none.
+ */
+import { useCallback } from "react";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+
+export const MAX_WINDOW_DAYS = 365;
+export const DAY_PRESETS = [7, 30, 90, 365] as const;
+export const DEFAULT_DAYS = 30;
+
+/** Largest `limit` each list report accepts (the contract's maximum); a bigger value is a 422. */
+export const LIMITS = {
+  campaigns: 200, sources: 200, referrals: 200, geo: 200, cities: 200, languages: 100,
+  topPages: 200, landing: 200, exit: 200, events: 200, forms: 200, formAnalysis: 100,
+  byLanding: 100, byCampaign: 200, realtimePages: 50, realtimeSources: 50, realtimeLocations: 200,
+} as const;
+
+const KEY_RE = /^[A-Za-z0-9_-]+$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/** Site keys from a comma list: only valid tokens, deduplicated and sorted (the API sorts them too). */
+export function parseSites(raw: string): string[] {
+  const keys = raw.split(",").map((k) => k.trim()).filter((k) => KEY_RE.test(k));
+  return [...new Set(keys)].sort();
+}
+
+/** A real calendar day as a UTC timestamp, or undefined. */
+export function dayMs(s: string): number | undefined {
+  if (!DATE_RE.test(s)) return undefined;
+  const t = Date.parse(`${s}T00:00:00Z`);
+  if (Number.isNaN(t) || new Date(t).toISOString().slice(0, 10) !== s) return undefined;
+  return t;
+}
+
+export function todayUtc(now: number = Date.now()): string {
+  return new Date(now).toISOString().slice(0, 10);
+}
+
+export type RangeProblem = "incomplete" | "invalid" | "inverted" | "too_wide" | null;
+
+/** Why a from/to pair cannot be sent, or null when it can. */
+export function rangeProblem(from: string, to: string): RangeProblem {
+  if (!from || !to) return "incomplete";
+  const a = dayMs(from);
+  const b = dayMs(to);
+  if (a == null || b == null) return "invalid";
+  if (a > b) return "inverted";
+  if ((b - a) / 86400000 + 1 > MAX_WINDOW_DAYS) return "too_wide";
+  return null;
+}
+
+export const RANGE_PROBLEM_TEXT: Record<Exclude<RangeProblem, null>, string> = {
+  incomplete: "Pick both a start and an end day.",
+  invalid: "Use real calendar days.",
+  inverted: "The start day must not be after the end day.",
+  too_wide: `A range can span at most ${MAX_WINDOW_DAYS} days.`,
+};
+
+export interface WindowSpec {
+  kind: "days" | "range";
+  days: number;
+  from?: string;
+  to?: string;
+}
+
+/** The window the URL describes: a valid from/to pair wins, otherwise `days` (clamped to a real preset-or-number), else 30. */
+export function resolveWindow(daysRaw: string, from: string, to: string): WindowSpec {
+  if (rangeProblem(from, to) === null) {
+    const span = Math.round((dayMs(to)! - dayMs(from)!) / 86400000) + 1;
+    return { kind: "range", days: span, from, to };
+  }
+  const n = Number(daysRaw);
+  const days = Number.isInteger(n) && n >= 1 && n <= MAX_WINDOW_DAYS ? n : DEFAULT_DAYS;
+  return { kind: "days", days };
+}
+
+export function describeWindow(w: WindowSpec): string {
+  if (w.kind === "range") return `${w.from} to ${w.to}`;
+  return `Last ${w.days} days`;
+}
+
+export interface Scope {
+  sites: string[];
+  window: WindowSpec;
+  bots: boolean;
+  internal: boolean;
+}
+
+export type ReportQuery = Record<string, string | number | boolean | undefined>;
+
+/** Query for a windowed report. Switches are sent only when on (the API's default is off). */
+export function windowedQuery(scope: Scope): ReportQuery {
+  const q: ReportQuery = trafficQuery(scope);
+  if (scope.window.kind === "range") {
+    q.date_from = scope.window.from;
+    q.date_to = scope.window.to;
+  } else {
+    q.days = scope.window.days;
+  }
+  return q;
+}
+
+/** Query for a report that has no window (realtime): sites and traffic switches only. */
+export function trafficQuery(scope: Scope): ReportQuery {
+  const q: ReportQuery = {};
+  if (scope.sites.length) q.write_key = scope.sites.join(",");
+  if (scope.bots) q.include_bots = true;
+  if (scope.internal) q.include_internal = true;
+  return q;
+}
+
+/** Stable text for a scope, used as the dependency of every report read. */
+export function scopeKey(scope: Scope): string {
+  return JSON.stringify([scope.sites, scope.window, scope.bots, scope.internal]);
+}
+
+export interface ScopeState extends Scope {
+  setSites: (sites: string[]) => void;
+  setDays: (days: number) => void;
+  setRange: (from: string, to: string) => void;
+  setBots: (on: boolean) => void;
+  setInternal: (on: boolean) => void;
+  key: string;
+}
+
+export function useAnalyticsScope(): ScopeState {
+  const [siteRaw, setSite] = useUrlState("site", "");
+  const [daysRaw, setDaysRaw] = useUrlState("days", "");
+  const [from, setFrom] = useUrlState("from", "");
+  const [to, setTo] = useUrlState("to", "");
+  const [botsRaw, setBotsRaw] = useUrlState("bots", "");
+  const [internalRaw, setInternalRaw] = useUrlState("internal", "");
+  const sites = parseSites(siteRaw);
+  const window = resolveWindow(daysRaw, from, to);
+  const scope: Scope = { sites, window, bots: botsRaw === "1", internal: internalRaw === "1" };
+
+  const setSites = useCallback((next: string[]) => setSite(next.length ? parseSites(next.join(",")).join(",") : null), [setSite]);
+  const setDays = useCallback((d: number) => { setFrom(null); setTo(null); setDaysRaw(d === DEFAULT_DAYS ? null : String(d)); }, [setFrom, setTo, setDaysRaw]);
+  const setRange = useCallback((a: string, b: string) => { if (rangeProblem(a, b) === null) { setDaysRaw(null); setFrom(a); setTo(b); } }, [setDaysRaw, setFrom, setTo]);
+  const setBots = useCallback((on: boolean) => setBotsRaw(on ? "1" : null), [setBotsRaw]);
+  const setInternal = useCallback((on: boolean) => setInternalRaw(on ? "1" : null), [setInternalRaw]);
+  return { ...scope, setSites, setDays, setRange, setBots, setInternal, key: scopeKey(scope) };
+}

package/blocks/web-analytics/lib/page-path.ts

@@ -0,0 +1,14 @@
+"use client";
+
+/**
+ * A page path the single-page report accepts. The backend (reports/analytics/routers/web_analytics_router.py,
+ * `_PAGE_PATH_RE`) answers 400 for anything else, so a path that fails this is never requested.
+ *
+ * SDK operations: none.
+ */
+export const PAGE_PATH_RE = /^\/[A-Za-z0-9/_\-.~%]*$/;
+export const PAGE_PATH_MAX = 1000;
+
+export function isReportablePath(path: string): boolean {
+  return path.length > 0 && path.length <= PAGE_PATH_MAX && PAGE_PATH_RE.test(path);
+}

package/blocks/web-analytics/lib/web-analytics-types.ts

@@ -0,0 +1,187 @@
+"use client";
+
+/**
+ * Types and readers for the web analytics reports.
+ *
+ * TYPED FROM THE BACKEND, NOT THE CONTRACT. The contract answers every web analytics report with
+ * `AnalyticsResponse { success, data: object | array, meta }`: `data` is untyped. The row shapes below are the column
+ * aliases of the ClickHouse queries (reports/analytics/queries/{audience,acquisition,behavior,conversions,engagement,
+ * realtime}.py) as the service returns them (reports/analytics/services/web_analytics_service.py). Every field is optional
+ * and read defensively, so a column the backend adds or renames never breaks a screen.
+ *
+ * Two facts about the envelope matter to every card:
+ *  - `meta.stale: true` means the query FAILED (or timed out) and the service swallowed the error. With no cached copy,
+ *    `data` is empty ([] or {}), which looks exactly like "no traffic". The cards say "unavailable", never "0".
+ *  - single-row reports (audience overview, conversion rate, engagement overview, realtime) answer an object; the rest
+ *    answer an array of rows.
+ */
+
+export interface AnalyticsMeta {
+  org_id?: string;
+  days?: number;
+  cached?: boolean;
+  stale?: boolean;
+  cache_ttl?: number;
+  timestamp?: string;
+  query_time_ms?: number | null;
+}
+
+export interface AnalyticsEnvelope<T> {
+  success?: boolean;
+  data?: T;
+  meta?: AnalyticsMeta;
+}
+
+/** A report after reading: its data, and whether the backend flagged it stale. */
+export interface ReportData<T> {
+  data: T;
+  stale: boolean;
+}
+
+export type Row = Record<string, unknown>;
+
+/** The value as a finite number, or undefined (ClickHouse decimals may arrive as numeric strings). */
+export function num(v: unknown): number | undefined {
+  if (typeof v === "number") return Number.isFinite(v) ? v : undefined;
+  if (typeof v === "string" && v.trim() !== "") {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+  }
+  return undefined;
+}
+
+export function str(v: unknown): string {
+  return typeof v === "string" ? v : v == null ? "" : String(v);
+}
+
+/** The rows of a list report. A non-array `data` (an object where a list is expected) is no rows. */
+export function readRows<T = Row>(env: unknown): ReportData<T[]> {
+  const e = env as AnalyticsEnvelope<unknown> | null | undefined;
+  return { data: Array.isArray(e?.data) ? (e!.data as T[]) : [], stale: e?.meta?.stale === true };
+}
+
+/** The row of a single-row report. `{}` and `[]` (a swallowed failure) are no row (null). */
+export function readRow<T = Row>(env: unknown): ReportData<T | null> {
+  const e = env as AnalyticsEnvelope<unknown> | null | undefined;
+  const d = e?.data;
+  const row = d && typeof d === "object" && !Array.isArray(d) && Object.keys(d).length > 0 ? (d as T) : null;
+  return { data: row, stale: e?.meta?.stale === true };
+}
+
+/** A report whose `data` is an object of named lists (technology, demographics). Missing lists are empty. */
+export function readGroups<K extends string>(env: unknown, keys: readonly K[]): ReportData<Record<K, Row[]> | null> {
+  const { data, stale } = readRow<Record<string, unknown>>(env);
+  if (!data) return { data: null, stale };
+  const out = {} as Record<K, Row[]>;
+  for (const k of keys) out[k] = Array.isArray(data[k]) ? (data[k] as Row[]) : [];
+  return { data: out, stale };
+}
+
+// ---------------------------------------------------------------- row shapes (from the query aliases)
+
+export interface AudienceOverview { total_users?: number; new_users?: number; page_views?: number; sessions?: number }
+export interface TrendPoint { date?: string; users?: number; new_users?: number; page_views?: number; sessions?: number }
+export interface NewVsReturning { user_type?: "New" | "Returning" | string; users?: number; page_views?: number }
+export interface GeoCountry { country?: string; country_code?: string; users?: number; sessions?: number }
+export interface GeoCity { city?: string; region?: string; country?: string; country_code?: string; users?: number; sessions?: number }
+export interface Language { language?: string; users?: number; sessions?: number }
+export interface Channel { channel?: string; users?: number; sessions?: number; page_views?: number; bounce_rate?: number | null }
+export interface ChannelTrendPoint { date?: string; channel?: string; users?: number; sessions?: number }
+export interface SourceMedium { source?: string; medium?: string; users?: number; sessions?: number; page_views?: number }
+export interface CampaignRow { campaign?: string; source?: string; medium?: string; users?: number; sessions?: number; page_views?: number }
+export interface Referral { referrer?: string; users?: number; sessions?: number; page_views?: number }
+export interface PageRow { page_path?: string; page_title?: string; views?: number; unique_visitors?: number; avg_time_on_page?: number | null; bounce_rate?: number | null }
+export interface LandingRow { landing_page?: string; landing_title?: string; sessions?: number; users?: number }
+export interface ExitRow { exit_page?: string; exit_title?: string; exits?: number; users?: number }
+export interface EventRow { event_name?: string; event_category?: string; event_action?: string; event_label?: string; total_events?: number; unique_users?: number; first_seen?: string; last_seen?: string }
+export interface PageMetrics { views?: number; unique_visitors?: number; form_submissions?: number; bookings?: number }
+export interface GoalRow { goal_name?: string; completions?: number; unique_completions?: number; total_visitors?: number; conversion_rate?: number | null }
+export interface GoalTrendPoint { date?: string; form_submissions?: number; meetings_booked?: number; total_conversions?: number; unique_converters?: number }
+export interface ConversionRate { total_visitors?: number; total_converters?: number; conversion_rate?: number | null }
+export interface FormRow { form_id?: string; form_name?: string; submissions?: number; unique_submitters?: number; first_submission?: string; latest_submission?: string }
+export interface FormTrendPoint { date?: string; submissions?: number; unique_submitters?: number; unique_forms?: number }
+export interface FormAnalysisRow { form_id?: string; form_name?: string; viewers?: number; submissions?: number; unique_submitters?: number; conversion_rate?: number | null }
+export interface FunnelStep { step?: string; step_order?: number; users?: number; percentage?: number | null }
+export interface EngagementOverview {
+  total_sessions?: number; avg_session_depth?: number; avg_time_minutes?: number; bounce_rate?: number; engaged_sessions?: number; engaged_pct?: number;
+  depth_trend_pct?: number | null; time_trend_pct?: number | null; bounce_trend_pct?: number | null; engaged_trend_pct?: number | null;
+}
+export interface EngagementTrendPoint { date?: string; sessions?: number; avg_session_depth?: number; avg_time_minutes?: number; bounce_rate?: number; engaged_sessions?: number }
+export interface DepthBucket { depth_bucket?: string; sessions?: number; percentage?: number }
+export interface TimeBucket { duration_bucket?: string; sessions?: number; percentage?: number }
+export interface EngagementByChannel { channel?: string; sessions?: number; avg_session_depth?: number; avg_time_minutes?: number; bounce_rate?: number; engaged_pct?: number }
+export interface EngagementByCampaign { campaign?: string; source?: string; medium?: string; sessions?: number; users?: number; avg_session_depth?: number; avg_time_minutes?: number; bounce_rate?: number; engaged_pct?: number; engaged_sessions?: number }
+export interface EngagementByLanding { landing_page?: string; sessions?: number; avg_session_depth?: number; avg_time_minutes?: number; bounce_rate?: number; engaged_pct?: number }
+export interface RealtimeOverview { active_5m?: number; active_30m?: number; pageviews_5m?: number; pageviews_30m?: number; data_as_of?: string | null; data_lag_seconds?: number | null }
+export interface RealtimePage { page_path?: string; page_title?: string; views?: number; visitors?: number }
+export interface RealtimeLocation { country?: string; country_code?: string; region?: string; region_code?: string; visitors?: number; page_views?: number }
+export interface RealtimeSource { source?: string; visitors?: number; page_views?: number }
+export interface Technology { browsers?: Row[]; operating_systems?: Row[]; devices?: Row[] }
+
+// ---------------------------------------------------------------- formatting (an unknown value is a dash, never 0)
+
+export const DASH = "-";
+
+export function fmtInt(v: unknown): string {
+  const n = num(v);
+  return n == null ? DASH : Math.round(n).toLocaleString();
+}
+
+export function fmtDecimal(v: unknown, digits = 1): string {
+  const n = num(v);
+  return n == null ? DASH : n.toLocaleString(undefined, { minimumFractionDigits: 0, maximumFractionDigits: digits });
+}
+
+/** A value that is already a percentage (12.5 means 12.5%). */
+export function fmtPct(v: unknown, digits = 1): string {
+  const n = num(v);
+  return n == null ? DASH : `${n.toLocaleString(undefined, { minimumFractionDigits: 0, maximumFractionDigits: digits })}%`;
+}
+
+/** n as a percentage of d; a zero or missing denominator is a dash, never 0%. */
+export function pctOf(n: unknown, d: unknown): number | undefined {
+  const a = num(n);
+  const b = num(d);
+  return a == null || b == null || b <= 0 ? undefined : (a / b) * 100;
+}
+
+/** Minutes as "2m 14s" (under a minute: "42s"). */
+export function fmtMinutes(v: unknown): string {
+  const n = num(v);
+  if (n == null) return DASH;
+  const total = Math.round(n * 60);
+  if (total < 60) return `${total}s`;
+  const m = Math.floor(total / 60);
+  const s = total % 60;
+  return s === 0 ? `${m}m` : `${m}m ${s}s`;
+}
+
+export function fmtSeconds(v: unknown): string {
+  const n = num(v);
+  return n == null ? DASH : fmtMinutes(n / 60);
+}
+
+/** A date (YYYY-MM-DD or ISO) as "Oct 4", UTC so it never shifts a day. */
+export function fmtDay(v: unknown): string {
+  const s = str(v);
+  if (!s) return DASH;
+  const d = new Date(s.length === 10 ? `${s}T00:00:00Z` : s);
+  return Number.isNaN(d.getTime()) ? s : d.toLocaleDateString(undefined, { month: "short", day: "numeric", timeZone: "UTC" });
+}
+
+export function fmtDateTime(v: unknown): string {
+  const s = str(v);
+  if (!s) return DASH;
+  const d = new Date(s);
+  return Number.isNaN(d.getTime()) ? s : d.toLocaleString(undefined, { month: "short", day: "numeric", hour: "numeric", minute: "2-digit", timeZone: "UTC" }) + " UTC";
+}
+
+/** Sum of a numeric field over rows; undefined when no row carries it. */
+export function sumOf<T>(rows: T[], pick: (r: T) => unknown): number | undefined {
+  let total: number | undefined;
+  for (const r of rows) {
+    const n = num(pick(r));
+    if (n != null) total = (total ?? 0) + n;
+  }
+  return total;
+}

package/blocks/web-analytics/recipes/best-landing-pages.ts

@@ -0,0 +1,26 @@
+/**
+ * @title Rank landing pages by sessions and engagement
+ * @when Deciding which landing pages deserve more traffic or a rewrite. `limit` is capped per report (landing pages 200,
+ * engagement by landing page 100); a bigger value is a 422. The landing page path is the address the visitor first saw.
+ * Rows are read from the backend query aliases (reports/analytics/queries/behavior.py and engagement.py). Read tier, free.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+interface Landing { landing_page?: string; sessions?: number; users?: number }
+interface Engaged { landing_page?: string; bounce_rate?: number; engaged_pct?: number }
+interface Envelope<T> { data?: T }
+
+export async function bestLandingPages(days = 30, top = 10) {
+  const query = { days, limit: 100 };
+  const [landing, engagement] = await Promise.all([
+    g8.api.webAnalytics.getLandingPages({ query }),
+    g8.api.webAnalytics.getEngagementByLandingPage({ query }),
+  ]);
+  const byPage = new Map((((engagement as Envelope<Engaged[]>).data) ?? []).map((e) => [e.landing_page, e]));
+  return (((landing as Envelope<Landing[]>).data) ?? [])
+    .sort((a, b) => (b.sessions ?? 0) - (a.sessions ?? 0))
+    .slice(0, top)
+    .map((l) => ({ page: l.landing_page, sessions: l.sessions, bounceRate: byPage.get(l.landing_page)?.bounce_rate ?? null, engagedPct: byPage.get(l.landing_page)?.engaged_pct ?? null }));
+}

package/blocks/web-analytics/recipes/form-conversion-check.ts

@@ -0,0 +1,19 @@
+/**
+ * @title Find forms that get views but few submissions
+ * @when A conversion review. `conversion_rate` is null when a form has no viewers (for example appointment-only forms):
+ * skip those, do not read them as 0% or 100%. `limit` for form analysis is capped at 100. Read tier, free.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+interface FormAnalysis { form_id?: string; form_name?: string; viewers?: number; unique_submitters?: number; conversion_rate?: number | null }
+interface Envelope<T> { data?: T }
+
+export async function weakForms(days = 30, minViewers = 50) {
+  const res = await g8.api.webAnalytics.getFormAnalysis({ query: { days, limit: 100 } });
+  return (((res as Envelope<FormAnalysis[]>).data) ?? [])
+    .filter((f) => (f.viewers ?? 0) >= minViewers && f.conversion_rate != null)
+    .sort((a, b) => (a.conversion_rate as number) - (b.conversion_rate as number))
+    .map((f) => ({ id: f.form_id, name: f.form_name, viewers: f.viewers, rate: f.conversion_rate }));
+}

package/blocks/web-analytics/recipes/weekly-traffic-report.ts

@@ -0,0 +1,37 @@
+/**
+ * @title Summarise a site's traffic, sources and conversion for a window
+ * @when A weekly email, a Slack digest or a dashboard header. The contract types these reports as open objects
+ * (`AnalyticsResponse.data` is `object | array`), so the row shapes below come from the backend queries
+ * (reports/analytics/queries/*.py). `meta.stale: true` means the query failed and the answer is empty: treat it as
+ * "unavailable", never as zero traffic. Pass `writeKey` (a site's public key, letters, digits, - and _) to scope to one site.
+ * All read tier, free.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+interface Meta { stale?: boolean }
+interface Envelope<T> { data?: T; meta?: Meta }
+
+export async function weeklyTraffic(days = 7, writeKey?: string) {
+  const query = { days, write_key: writeKey };
+  const [overview, channels, rate] = await Promise.all([
+    g8.api.webAnalytics.getAudienceOverview({ query }),
+    g8.api.webAnalytics.getAcquisitionChannels({ query }),
+    g8.api.webAnalytics.getConversionRate({ query }),
+  ]);
+  const unavailable = [overview, channels, rate].some((r) => (r as Envelope<unknown>).meta?.stale === true);
+  if (unavailable) return { unavailable: true as const };
+  const o = (overview as Envelope<{ total_users?: number; new_users?: number; sessions?: number; page_views?: number }>).data ?? {};
+  const c = (channels as Envelope<Array<{ channel?: string; sessions?: number }>>).data ?? [];
+  const r = (rate as Envelope<{ conversion_rate?: number | null }>).data ?? {};
+  return {
+    unavailable: false as const,
+    visitors: o.total_users,
+    sessions: o.sessions,
+    pageViews: o.page_views,
+    // null means there were no visitors: report "n/a", not 0%.
+    conversionRate: r.conversion_rate ?? null,
+    topChannels: [...c].sort((a, b) => (b.sessions ?? 0) - (a.sessions ?? 0)).slice(0, 3).map((x) => x.channel),
+  };
+}

package/blocks/webchat/components/chat-widget-config.tsx

@@ -121,7 +121,7 @@ export function ChatWidgetConfig({ initialBotId, surface = "external" }: ChatWid
                 <div><Label htmlFor="g8-wc-text" className="mb-1">Reply text</Label><Input id="g8-wc-text" placeholder="#111111" value={draft.assistantMessageTextColor ?? ""} onChange={(e) => set({ assistantMessageTextColor: e.target.value })} /></div>
                 <label className="flex items-center gap-2 self-end text-sm"><input type="checkbox" checked={Boolean(draft.darkMode)} onChange={(e) => set({ darkMode: e.target.checked })} />Dark mode</label>
               </div>
-              {problem ? <p role="alert" className="text-sm text-red-700">{problem}</p> : null}
+              {problem ? <p role="alert" className="text-sm text-error-foreground">{problem}</p> : null}
               {save.error ? <ApiError error={save.error} title="Could not save the widget settings" /> : null}
               <div><Button loading={save.loading} disabled={Boolean(problem) || settings.loading || Boolean(settings.error)} onClick={() => void save.mutate(undefined)}>{exists ? "Save changes" : "Create widget settings"}</Button></div>
             </CardContent>

package/blocks/webchat/components/conversation-list.tsx

@@ -47,7 +47,7 @@ export function ConversationList({ linkParam, botId, pageSize = 25, onSelectVisi
     <div className="grid gap-3">
       {counts.length > 0 ? (
         <dl className="grid grid-cols-2 gap-2 sm:grid-cols-4">
-          {counts.map(([k, v]) => <div key={k} className="rounded-md border p-3"><dt className="text-muted-foreground text-xs">{k.replace(/_/g, " ")}</dt><dd className="text-lg font-semibold">{v.toLocaleString()}</dd></div>)}
+          {counts.map(([k, v]) => <div key={k} className="rounded-md border p-3"><dt className="text-muted-foreground text-xs">{k.replace(/_/g, " ")}</dt><dd className="text-lg font-medium">{v.toLocaleString()}</dd></div>)}
         </dl>
       ) : null}
       <form className="flex flex-wrap items-center gap-2" onSubmit={(e) => { e.preventDefault(); setPage(1); setSearch(text.trim()); }}>

package/blocks/workbench/README.md

@@ -16,7 +16,27 @@ waterfall and formula columns, quote then run, progress, unlock locked rows, sen
 **Import people** (free preview and match count, then a confirmed import; rows land locked) and **Scrape the web** (credit estimate and balance, confirmed run, polled progress) are in the table header (`SearchImportPanel`, `ScraperPanel`). Open any row (`?row=`) for `WorkbenchRowDetail`: every cell, per-cell edit, unlock, send to a list, delete. `?view=full` opens a row full-page.
 Slots: `toolbarActions`, `renderRowActions(table)`, `renderDetailActions(table)`.
 
-Prerequisites: `enrichment` and `lists` installed, proxy allowlist `workbench`, `enrichment`, `lists`; provider keys and credits as below.
+An opened table has four tabs (`?tab=`, Data is the default):
+- **Data**: the grid. Filter by one column (a "contains" text filter) and sort by one column, delete a column (confirmed), see the
+  live **Locked rows** count in the header, and from the selection panel **Send to sequence** (below). **Edit details** renames the
+  workbench or changes its description (`WorkbenchTableSettings`).
+- **Automation** (`WorkbenchAutomation`): **Auto-enrich** (the passes it would run, then a confirm with the exact pass count),
+  **Schedule** (hourly, daily, weekly or a cron whose minute is a plain number, in UTC, saved stopped until started; an AI schedule is priced from the API's run-all quote, which the server requires back as the cap; a CRM schedule collects the CRM and a limit of 1 to 1000; editing keeps the schedule's action_config), **Triggers** (when a row arrives,
+  an AI column finishes or a status changes: run the AI columns, recompute formulas, send the row to a list, call a webhook, with an
+  optional condition) and **Pipelines** (an ordered run of the recipe columns, created switched off).
+- **Import**: `WorkbenchDatafileImport` (the id of an uploaded file, optionally an AI-suggested header-to-column mapping you edit before
+  importing) and `WorkbenchCrmImport` (records from a connected CRM, 1 to 10,000).
+- **Connections** (`WorkbenchConnections`): copy new rows into another workbench by name, optionally some columns only; sync an outgoing
+  connection on demand (it stops at the first locked row); delete.
+
+**Send to sequence** (`WorkbenchSendToSequence`): pick a running sequence by name and the list the people are saved to; the confirm counts
+exactly who will be emailed. Locked rows are never sent, and an empty selection cannot be sent (an omitted row list means every row).
+
+Spend is never guessed: a started AI schedule shows the API's own per-run price (its quote); arming an AI trigger, enabling a pipeline with AI or provider steps, switching on
+auto-enrich, importing into an auto-enriching workbench and the mapping suggestion (one AI call) are billable-tier operations whose total graph8 does not publish for rows that have not arrived yet, so each confirm
+says so and shows no number. Everything that leaves the workspace (enrolling people, reading the CRM) is an external-tier confirm.
+
+Prerequisites: `enrichment` and `lists` installed, proxy allowlist `workbench`, `enrichment`, `lists`, `sequences` and `crm-syncs` (the sequence picker and the CRM list); provider keys and credits as below.
 
 ## What you get
 
@@ -115,25 +135,49 @@ Ask the person: who approves a run's price (the proxy's `authorize` decides who
 | addWorkbenchColumn | POST /workbench/tables/{table_id}/columns | write | ColumnRecipeEditor |
 | addWorkbenchRow | POST /workbench/tables/{table_id}/rows | write | WorkbenchAddRows |
 | bulkDeleteWorkbenchRows | POST /workbench/tables/{table_id}/rows/bulk-delete | destructive | WorkbenchRowActions |
+| createList | POST /lists | write | WorkbenchTriggers, WorkbenchSendToSequence |
+| createWorkbenchConnection | POST /workbench/tables/{table_id}/connections | write | WorkbenchConnections |
 | createWorkbenchFormulaColumns | POST /workbench/tables/{table_id}/formula-columns | write | ColumnRecipeEditor |
+| createWorkbenchPipeline | POST /workbench/tables/{table_id}/pipelines | billable | WorkbenchPipelines |
 | createWorkbenchTable | POST /workbench/tables | write | WorkbenchTableList |
+| createWorkbenchTrigger | POST /workbench/tables/{table_id}/triggers | billable | WorkbenchTriggers |
+| deleteWorkbenchColumn | DELETE /workbench/tables/{table_id}/columns/{column_id} | destructive | WorkbenchGrid |
+| deleteWorkbenchConnection | DELETE /workbench/tables/{table_id}/connections/{connection_id} | destructive | WorkbenchConnections |
+| deleteWorkbenchPipeline | DELETE /workbench/tables/{table_id}/pipelines/{pipeline_id} | destructive | WorkbenchPipelines |
+| deleteWorkbenchSchedule | DELETE /workbench/tables/{table_id}/schedule | destructive | WorkbenchSchedule |
 | deleteWorkbenchTable | DELETE /workbench/tables/{table_id} | destructive | WorkbenchTableList |
+| deleteWorkbenchTrigger | DELETE /workbench/tables/{table_id}/triggers/{trigger_id} | destructive | WorkbenchTriggers |
 | estimateWorkbenchScraperCredits | GET /workbench/scraper/credit-estimate | read | recipes |
 | exportWorkbenchTable | POST /workbench/tables/{table_id}/export | write | WorkbenchRowActions |
 | getWorkbenchAnalytics | GET /workbench/tables/{table_id}/analytics | read | RunProgress |
 | getWorkbenchHistory | GET /workbench/tables/{table_id}/history | read | RunProgress |
+| getWorkbenchLockedRowCount | GET /workbench/tables/{table_id}/locked-row-count | read | WorkbenchScreen |
+| getWorkbenchMappingSuggestion | GET /workbench/tables/{table_id}/suggest-mappings/{job_id} | read | WorkbenchDatafileImport |
+| getWorkbenchPipeline | GET /workbench/tables/{table_id}/pipelines/{pipeline_id} | read | WorkbenchPipelines |
+| getWorkbenchRow | GET /workbench/tables/{table_id}/rows/{row_id} | read | WorkbenchRowDetail |
+| getWorkbenchSchedule | GET /workbench/tables/{table_id}/schedule | read | WorkbenchSchedule |
 | getWorkbenchScraperRun | GET /workbench/tables/{table_id}/scraper/runs/{run_id} | read | recipes |
 | getWorkbenchTable | GET /workbench/tables/{table_id} | read | WorkbenchGrid, useWorkbenchTable |
+| importWorkbenchDatafile | POST /workbench/tables/{table_id}/import/datafile | write | WorkbenchDatafileImport |
+| importWorkbenchFromCrm | POST /workbench/tables/{table_id}/import/crm | external | WorkbenchCrmImport |
 | importWorkbenchFromSearch | POST /workbench/tables/{table_id}/import/search | billable | recipes |
+| listCrmSyncs | GET /crm-syncs | read | WorkbenchCrmImport, WorkbenchSchedule |
 | listEnrichmentProviders | GET /enrichment/providers | read | ColumnRecipeEditor |
+| listLists | GET /lists | read | WorkbenchTriggers, WorkbenchSendToSequence |
+| listSequences | GET /sequences | read | WorkbenchSendToSequence |
 | listWorkbenchColumns | GET /workbench/tables/{table_id}/columns | read | WorkbenchGrid, useWorkbenchTable |
+| listWorkbenchConnections | GET /workbench/tables/{table_id}/connections | read | WorkbenchConnections |
+| listWorkbenchEnrichmentConfigs | GET /workbench/tables/{table_id}/enrichment-configs | read | WorkbenchAutoEnrich |
+| listWorkbenchPipelines | GET /workbench/tables/{table_id}/pipelines | read | WorkbenchPipelines |
 | listWorkbenchRows | GET /workbench/tables/{table_id}/rows | read | WorkbenchGrid |
 | listWorkbenchTables | GET /workbench/tables | read | WorkbenchTableList |
 | listWorkbenchTargetFields | GET /workbench/target-fields | read | ColumnRecipeEditor |
+| listWorkbenchTriggers | GET /workbench/tables/{table_id}/triggers | read | WorkbenchTriggers |
 | mapWorkbenchColumn | PUT /workbench/tables/{table_id}/columns/{column_id}/mapping | write | ColumnRecipeEditor |
 | pasteImportWorkbenchRows | POST /workbench/tables/{table_id}/import/paste | write | WorkbenchAddRows |
 | previewWorkbenchSearchImport | POST /workbench/tables/{table_id}/import/search/preview | read | recipes |
-| quoteWorkbenchAiRun | POST /workbench/tables/{table_id}/ai/validate-credits | read | RunProgress |
+| queryWorkbenchRows | POST /workbench/tables/{table_id}/rows/query | read | WorkbenchGrid |
+| quoteWorkbenchAiRun | POST /workbench/tables/{table_id}/ai/validate-credits | read | RunProgress, WorkbenchSchedule |
 | quoteWorkbenchUnlock | POST /workbench/tables/{table_id}/unlock-quote | read | WorkbenchRowActions |
 | quoteWorkbenchWaterfallRun | POST /workbench/tables/{table_id}/waterfall/configs/{column_id}/validate-credits | read | RunProgress |
 | runWorkbenchColumnAi | POST /workbench/tables/{table_id}/columns/{col_id}/ai/run | billable | RunProgress |
@@ -142,5 +186,13 @@ Ask the person: who approves a run's price (the proxy's `authorize` decides who
 | runWorkbenchWaterfall | POST /workbench/tables/{table_id}/waterfall/configs/{column_id}/run | billable | RunProgress |
 | saveWorkbenchColumnAiConfig | PUT /workbench/tables/{table_id}/columns/{col_id}/ai-config | write | ColumnRecipeEditor |
 | saveWorkbenchWaterfall | POST /workbench/tables/{table_id}/waterfall/configs | write | ColumnRecipeEditor |
+| sendWorkbenchRowsToSequence | POST /workbench/tables/{table_id}/send-to-sequence | external | WorkbenchSendToSequence |
+| setWorkbenchAutoEnrich | PUT /workbench/tables/{table_id}/auto-enrich | billable | WorkbenchAutoEnrich |
+| setWorkbenchSchedule | PUT /workbench/tables/{table_id}/schedule | billable | WorkbenchSchedule |
+| suggestWorkbenchMappings | POST /workbench/tables/{table_id}/suggest-mappings | billable | WorkbenchDatafileImport |
+| syncWorkbenchConnection | POST /workbench/tables/{table_id}/connections/{connection_id}/sync | write | WorkbenchConnections |
 | unlockWorkbenchRows | POST /workbench/tables/{table_id}/unlock-rows | billable | WorkbenchRowActions |
+| updateWorkbenchPipeline | PUT /workbench/tables/{table_id}/pipelines/{pipeline_id} | billable | WorkbenchPipelines |
 | updateWorkbenchRow | PATCH /workbench/tables/{table_id}/rows/{row_id} | write | WorkbenchGrid |
+| updateWorkbenchTable | PUT /workbench/tables/{table_id} | write | WorkbenchTableSettings |
+| updateWorkbenchTrigger | PUT /workbench/tables/{table_id}/triggers/{trigger_id} | billable | WorkbenchTriggers |