@graph8/sdk 0.373.0 → 0.374.0

package/blocks/web-analytics/components/audience-tab.tsx

@@ -0,0 +1,135 @@
+"use client";
+
+/**
+ * AudienceTab: who the visitors are.
+ *   At a glance      the top 10 countries, cities and languages in one read
+ *   Locations        every country or city (switch), as a re-sortable table
+ *   Languages        the browser languages
+ *   Technology       browsers, operating systems and devices
+ *   New or returning visitors, and how many page views each group made
+ *
+ * SDK operations, in order (all read, free). RankedTable renders a FirstNotice ("Showing the first N") when a read came back full:
+ *   1. getAudienceDemographics  GET /analytics/audience/demographics
+ *   2. getGeoCountries          GET /analytics/audience/geo           (limit 200)
+ *   3. getGeoCities             GET /analytics/audience/geo/cities    (limit 200)
+ *   4. getAudienceLanguages     GET /analytics/audience/languages     (limit 100, the API maximum)
+ *   5. getTechnologyOverview    GET /analytics/audience/technology
+ *   6. getAudienceBehavior      GET /analytics/audience/behavior
+ * Location rows without a country are not guessed: they read "Unknown".
+ */
+import { useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { BarList } from "@/g8/components/screen/bar-list";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useReport } from "../hooks/use-report";
+import { LIMITS, windowedQuery } from "../lib/analytics-scope";
+import type { ScopeState } from "../lib/analytics-scope";
+import { fmtInt, fmtPct, num, pctOf, readGroups, readRows, str, sumOf } from "../lib/web-analytics-types";
+import type { GeoCity, GeoCountry, Language, NewVsReturning, Row } from "../lib/web-analytics-types";
+import { RankedTable } from "./ranked-table";
+import { ReportCard } from "./report-card";
+
+const bars = (rows: Row[], name: string, value = "users") => <BarList items={rows.map((r) => ({ label: str(r[name]) || "Unknown", value: num(r[value]) ?? 0 }))} />;
+const GROUP_KEYS = ["countries", "cities", "languages"] as const;
+const TECH_KEYS = ["browsers", "operating_systems", "devices"] as const;
+
+function GroupColumn({ title, children }: { title: string; children: React.ReactNode }) {
+  return (
+    <div className="min-w-0 space-y-2">
+      <h4 className="text-xs font-medium uppercase tracking-wide text-text-color-muted">{title}</h4>
+      {children}
+    </div>
+  );
+}
+
+function Countries({ scope }: { scope: ScopeState }) {
+  const q = windowedQuery(scope);
+  const report = useReport(async (signal) => readRows<GeoCountry>(await g8Get("/analytics/audience/geo", { ...q, limit: LIMITS.geo }, { signal })), scope.key);
+  return (
+    <ReportCard title="Countries" report={report} isEmpty={(r) => r.length === 0} emptyDescription="Locations need GeoIP enrichment on the tracking pipeline.">
+      {(rows) => (
+        <RankedTable rows={rows} noun="countries" limit={LIMITS.geo} defaultSort="users" rowKey={(r, i) => `${str(r.country_code)}|${i}`} columns={[
+          { key: "country", label: "Country", render: (r) => str(r.country) || "Unknown", sortBy: (r) => str(r.country) },
+          { key: "users", label: "Visitors", numeric: true, render: (r) => fmtInt(r.users), sortBy: (r) => num(r.users) },
+          { key: "sessions", label: "Sessions", numeric: true, render: (r) => fmtInt(r.sessions), sortBy: (r) => num(r.sessions) },
+        ]} />
+      )}
+    </ReportCard>
+  );
+}
+
+function Cities({ scope }: { scope: ScopeState }) {
+  const q = windowedQuery(scope);
+  const report = useReport(async (signal) => readRows<GeoCity>(await g8Get("/analytics/audience/geo/cities", { ...q, limit: LIMITS.cities }, { signal })), scope.key);
+  return (
+    <ReportCard title="Cities" report={report} isEmpty={(r) => r.length === 0} emptyDescription="Locations need GeoIP enrichment on the tracking pipeline.">
+      {(rows) => (
+        <RankedTable rows={rows} noun="cities" limit={LIMITS.cities} defaultSort="users" rowKey={(r, i) => `${str(r.city)}|${str(r.country_code)}|${i}`} columns={[
+          { key: "city", label: "City", render: (r) => str(r.city) || "Unknown", sortBy: (r) => str(r.city) },
+          { key: "region", label: "Region", render: (r) => str(r.region), sortBy: (r) => str(r.region) },
+          { key: "country", label: "Country", render: (r) => str(r.country), sortBy: (r) => str(r.country) },
+          { key: "users", label: "Visitors", numeric: true, render: (r) => fmtInt(r.users), sortBy: (r) => num(r.users) },
+          { key: "sessions", label: "Sessions", numeric: true, render: (r) => fmtInt(r.sessions), sortBy: (r) => num(r.sessions) },
+        ]} />
+      )}
+    </ReportCard>
+  );
+}
+
+export function AudienceTab({ scope }: { scope: ScopeState }) {
+  const q = windowedQuery(scope);
+  const [place, setPlace] = useState<"countries" | "cities">("countries");
+  const demographics = useReport(async (signal) => readGroups(await g8Get("/analytics/audience/demographics", q, { signal }), GROUP_KEYS), scope.key);
+  const languages = useReport(async (signal) => readRows<Language>(await g8Get("/analytics/audience/languages", { ...q, limit: LIMITS.languages }, { signal })), scope.key);
+  const tech = useReport(async (signal) => readGroups(await g8Get("/analytics/audience/technology", q, { signal }), TECH_KEYS), scope.key);
+  const behavior = useReport(async (signal) => readRows<NewVsReturning>(await g8Get("/analytics/audience/behavior", q, { signal })), scope.key);
+  return (
+    <div className="grid gap-4 lg:grid-cols-2">
+      <ReportCard className="lg:col-span-2" title="At a glance" description="Top 10 of each" report={demographics} isEmpty={(d) => d === null || GROUP_KEYS.every((k) => d[k].length === 0)}>
+        {(d) => (
+          <div className="grid gap-6 md:grid-cols-3">
+            <GroupColumn title="Countries">{bars(d!["countries"], "country")}</GroupColumn>
+            <GroupColumn title="Cities">{bars(d!["cities"], "city")}</GroupColumn>
+            <GroupColumn title="Languages">{bars(d!["languages"], "language")}</GroupColumn>
+          </div>
+        )}
+      </ReportCard>
+      <div className="space-y-2 lg:col-span-2">
+        <div role="group" aria-label="Locations by" className="inline-flex gap-1">
+          <Button type="button" size="sm" variant={place === "countries" ? "default" : "outline"} aria-pressed={place === "countries"} onClick={() => setPlace("countries")}>Countries</Button>
+          <Button type="button" size="sm" variant={place === "cities" ? "default" : "outline"} aria-pressed={place === "cities"} onClick={() => setPlace("cities")}>Cities</Button>
+        </div>
+        {place === "countries" ? <Countries scope={scope} /> : <Cities scope={scope} />}
+      </div>
+      <ReportCard title="Languages" report={languages} isEmpty={(r) => r.length === 0}>
+        {(rows) => (
+          <RankedTable rows={rows} noun="languages" limit={LIMITS.languages} defaultSort="users" rowKey={(r, i) => `${str(r.language)}|${i}`} columns={[
+            { key: "language", label: "Language", render: (r) => str(r.language) || "Unknown", sortBy: (r) => str(r.language) },
+            { key: "users", label: "Visitors", numeric: true, render: (r) => fmtInt(r.users), sortBy: (r) => num(r.users) },
+            { key: "sessions", label: "Sessions", numeric: true, render: (r) => fmtInt(r.sessions), sortBy: (r) => num(r.sessions) },
+          ]} />
+        )}
+      </ReportCard>
+      <ReportCard title="New or returning" report={behavior} isEmpty={(r) => r.length === 0}>
+        {(rows) => {
+          const total = sumOf(rows, (r) => r.users);
+          return (
+            <div className="space-y-2">
+              <BarList items={rows.map((r) => ({ label: `${str(r.user_type) || "Unknown"} visitors`, value: num(r.users) ?? 0, display: `${fmtInt(r.users)} (${fmtPct(pctOf(r.users, total), 0)})` }))} />
+              <p className="text-xs text-text-color-muted">{rows.map((r) => `${str(r.user_type) || "Unknown"}: ${fmtInt(r.page_views)} page views`).join(". ")}.</p>
+            </div>
+          );
+        }}
+      </ReportCard>
+      <ReportCard className="lg:col-span-2" title="Technology" report={tech} isEmpty={(d) => d === null || TECH_KEYS.every((k) => d[k].length === 0)}>
+        {(d) => (
+          <div className="grid gap-6 md:grid-cols-3">
+            <GroupColumn title="Browsers">{bars(d!["browsers"], "browser")}</GroupColumn>
+            <GroupColumn title="Operating systems">{bars(d!["operating_systems"], "os")}</GroupColumn>
+            <GroupColumn title="Devices">{bars(d!["devices"], "device_category")}</GroupColumn>
+          </div>
+        )}
+      </ReportCard>
+    </div>
+  );
+}

package/blocks/web-analytics/components/conversions-tab.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+/**
+ * ConversionsTab: what visitors do that matters.
+ *   Summary        visitors, converters and the conversion rate (a dash when there were no visitors)
+ *   Funnel         site visitors, viewed a form, submitted a form, booked a meeting, with the step-to-step rate
+ *   Goals          completions and conversion rate per goal, and a daily trend
+ *   Forms          submissions per form, a daily trend, and form analysis (viewers, submitters, conversion rate)
+ * Rates the API sends as null (no visitors or no viewers) stay a dash; a rate is never filled in with 0%.
+ *
+ * SDK operations, in order (all read, free). RankedTable renders a FirstNotice ("Showing the first N") when a read came back full:
+ *   1. getConversionRate  GET /analytics/conversions/rate
+ *   2. getFunnel          GET /analytics/conversions/funnel
+ *   3. getGoals           GET /analytics/conversions/goals
+ *   4. getGoalsTrend      GET /analytics/conversions/goals/trend
+ *   5. getForms           GET /analytics/conversions/forms           (limit 200)
+ *   6. getFormsTrend      GET /analytics/conversions/forms/trend
+ *   7. getFormAnalysis    GET /analytics/conversions/forms/analysis  (limit 100, the API maximum)
+ */
+import { useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { BarList } from "@/g8/components/screen/bar-list";
+import { StatStrip } from "@/g8/components/screen/stat-strip";
+import { TimeSeriesChart } from "@/g8/components/screen/time-series-chart";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useReport } from "../hooks/use-report";
+import { LIMITS, windowedQuery } from "../lib/analytics-scope";
+import type { ScopeState } from "../lib/analytics-scope";
+import { fmtDateTime, fmtDay, fmtInt, fmtPct, num, pctOf, readRow, readRows, str } from "../lib/web-analytics-types";
+import type { ConversionRate, FormAnalysisRow, FormRow, FormTrendPoint, FunnelStep, GoalRow, GoalTrendPoint } from "../lib/web-analytics-types";
+import { RankedTable } from "./ranked-table";
+import { ReportCard } from "./report-card";
+
+const GOAL_SERIES = [
+  { key: "total_conversions", label: "All conversions" },
+  { key: "form_submissions", label: "Form submissions" },
+  { key: "meetings_booked", label: "Meetings booked" },
+  { key: "unique_converters", label: "People who converted" },
+] as const;
+
+function Funnel({ steps }: { steps: FunnelStep[] }) {
+  const ordered = [...steps].sort((a, b) => (num(a.step_order) ?? 0) - (num(b.step_order) ?? 0));
+  return (
+    <div className="space-y-3">
+      <BarList
+        emphasizeFirst={false}
+        items={ordered.map((s, i) => {
+          const prev = i > 0 ? num(ordered[i - 1].users) : undefined;
+          const step = i > 0 ? pctOf(s.users, prev) : undefined;
+          return { label: str(s.step), value: num(s.users) ?? 0, display: `${fmtInt(s.users)} (${fmtPct(s.percentage, 1)} of visitors${i > 0 ? `, ${fmtPct(step, 1)} of previous step` : ""})` };
+        })}
+      />
+    </div>
+  );
+}
+
+export function ConversionsTab({ scope }: { scope: ScopeState }) {
+  const q = windowedQuery(scope);
+  const [series, setSeries] = useState<(typeof GOAL_SERIES)[number]["key"]>("total_conversions");
+  const rate = useReport(async (signal) => readRow<ConversionRate>(await g8Get("/analytics/conversions/rate", q, { signal })), scope.key);
+  const funnel = useReport(async (signal) => readRows<FunnelStep>(await g8Get("/analytics/conversions/funnel", q, { signal })), scope.key);
+  const goals = useReport(async (signal) => readRows<GoalRow>(await g8Get("/analytics/conversions/goals", q, { signal })), scope.key);
+  const goalsTrend = useReport(async (signal) => readRows<GoalTrendPoint>(await g8Get("/analytics/conversions/goals/trend", q, { signal })), scope.key);
+  const forms = useReport(async (signal) => readRows<FormRow>(await g8Get("/analytics/conversions/forms", { ...q, limit: LIMITS.forms }, { signal })), scope.key);
+  const formsTrend = useReport(async (signal) => readRows<FormTrendPoint>(await g8Get("/analytics/conversions/forms/trend", q, { signal })), scope.key);
+  const analysis = useReport(async (signal) => readRows<FormAnalysisRow>(await g8Get("/analytics/conversions/forms/analysis", { ...q, limit: LIMITS.formAnalysis }, { signal })), scope.key);
+  const none = (rows: unknown[]) => rows.length === 0;
+  const label = GOAL_SERIES.find((s) => s.key === series)!.label;
+  return (
+    <div className="grid gap-4 lg:grid-cols-2">
+      <ReportCard className="lg:col-span-2" title="Summary" report={rate} isEmpty={(d) => d === null}>
+        {(d) => (
+          <StatStrip items={[
+            { label: "Visitors", value: fmtInt(d!.total_visitors) },
+            { label: "Converted", value: fmtInt(d!.total_converters) },
+            { label: "Conversion rate", value: fmtPct(d!.conversion_rate, 2), hint: "A dash means there were no visitors in this window." },
+          ]} />
+        )}
+      </ReportCard>
+      <ReportCard title="Funnel" description="Site visitors to booked meeting" report={funnel} isEmpty={none}>
+        {(steps) => <Funnel steps={steps} />}
+      </ReportCard>
+      <ReportCard title="Goals" report={goals} isEmpty={none} emptyTitle="No goal completions in this window">
+        {(rows) => (
+          <RankedTable rows={rows} noun="goals" defaultSort="completions" rowKey={(r, i) => `${str(r.goal_name)}|${i}`} columns={[
+            { key: "goal", label: "Goal", render: (r) => str(r.goal_name) || "Unknown", sortBy: (r) => str(r.goal_name) },
+            { key: "completions", label: "Completions", numeric: true, render: (r) => fmtInt(r.completions), sortBy: (r) => num(r.completions) },
+            { key: "people", label: "People", numeric: true, render: (r) => fmtInt(r.unique_completions), sortBy: (r) => num(r.unique_completions) },
+            { key: "rate", label: "Conversion rate", numeric: true, render: (r) => fmtPct(r.conversion_rate, 2), sortBy: (r) => num(r.conversion_rate) },
+          ]} />
+        )}
+      </ReportCard>
+      <ReportCard
+        className="lg:col-span-2"
+        title="Goals over time"
+        report={goalsTrend}
+        isEmpty={none}
+        skeletonHeight={220}
+        actions={<div role="group" aria-label="Goal metric" className="flex flex-wrap gap-1">{GOAL_SERIES.map((s) => <Button key={s.key} type="button" size="sm" variant={series === s.key ? "default" : "outline"} aria-pressed={series === s.key} onClick={() => setSeries(s.key)}>{s.label}</Button>)}</div>}
+      >
+        {(rows) => <TimeSeriesChart data={rows.map((r) => ({ ...r }))} xKey="date" series={[{ key: series, label }]} kind="bar" height={220} formatX={fmtDay} formatY={(v) => v.toLocaleString()} />}
+      </ReportCard>
+      <ReportCard className="lg:col-span-2" title="Forms" description="Submissions per form" report={forms} isEmpty={none} emptyTitle="No form submissions in this window">
+        {(rows) => (
+          <RankedTable rows={rows} noun="forms" limit={LIMITS.forms} defaultSort="submissions" rowKey={(r, i) => `${str(r.form_id)}|${i}`} columns={[
+            { key: "form", label: "Form", render: (r) => str(r.form_name) || str(r.form_id) || "Unknown", sortBy: (r) => str(r.form_name) },
+            { key: "submissions", label: "Submissions", numeric: true, render: (r) => fmtInt(r.submissions), sortBy: (r) => num(r.submissions) },
+            { key: "submitters", label: "People", numeric: true, render: (r) => fmtInt(r.unique_submitters), sortBy: (r) => num(r.unique_submitters) },
+            { key: "latest", label: "Latest", render: (r) => fmtDateTime(r.latest_submission), sortBy: (r) => str(r.latest_submission) || undefined },
+          ]} />
+        )}
+      </ReportCard>
+      <ReportCard title="Form submissions over time" report={formsTrend} isEmpty={none} skeletonHeight={200}>
+        {(rows) => <TimeSeriesChart data={rows.map((r) => ({ ...r }))} xKey="date" series={[{ key: "submissions", label: "Submissions" }]} kind="bar" height={200} formatX={fmtDay} formatY={(v) => v.toLocaleString()} />}
+      </ReportCard>
+      <ReportCard title="Form analysis" description="How many viewers submit" report={analysis} isEmpty={none}>
+        {(rows) => (
+          <RankedTable rows={rows} noun="forms" limit={LIMITS.formAnalysis} defaultSort="rate" rowKey={(r, i) => `${str(r.form_id)}|${i}`} columns={[
+            { key: "form", label: "Form", render: (r) => str(r.form_name) || str(r.form_id) || "Unknown", sortBy: (r) => str(r.form_name) },
+            { key: "viewers", label: "Viewers", numeric: true, render: (r) => fmtInt(r.viewers), sortBy: (r) => num(r.viewers) },
+            { key: "submitters", label: "Submitters", numeric: true, render: (r) => fmtInt(r.unique_submitters), sortBy: (r) => num(r.unique_submitters) },
+            { key: "rate", label: "Conversion rate", numeric: true, render: (r) => fmtPct(r.conversion_rate, 2), sortBy: (r) => num(r.conversion_rate) },
+          ]} />
+        )}
+      </ReportCard>
+    </div>
+  );
+}

package/blocks/web-analytics/components/engagement-tab.tsx

@@ -0,0 +1,123 @@
+"use client";
+
+/**
+ * EngagementTab: how deeply visitors use the site.
+ *   Summary          sessions, pages per session, time on site, bounce rate, engaged share, each against the previous period
+ *   Trend            one daily metric at a time
+ *   Depth and time   how sessions spread over pages viewed and over time on site
+ *   By channel / campaign / landing page   re-sortable tables
+ * A session is one visitor's activity within one hour; "engaged" means more than one page and more than 30 seconds.
+ * A change against the previous period is shown only when the API sent it (it is null when the previous period had no data).
+ *
+ * SDK operations, in order (all read, free). RankedTable renders a FirstNotice ("Showing the first N") when a read came back full:
+ *   1. getEngagementOverview        GET /analytics/engagement/overview
+ *   2. getEngagementTrend           GET /analytics/engagement/trend
+ *   3. getSessionDepthDistribution  GET /analytics/engagement/depth-distribution
+ *   4. getTimeOnSiteDistribution    GET /analytics/engagement/time-distribution
+ *   5. getEngagementByChannel       GET /analytics/engagement/by-channel
+ *   6. getEngagementByCampaign      GET /analytics/engagement/by-campaign      (limit 200)
+ *   7. getEngagementByLandingPage   GET /analytics/engagement/by-landing-page  (limit 100, the API maximum)
+ */
+import { useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { BarList } from "@/g8/components/screen/bar-list";
+import { StatStrip } from "@/g8/components/screen/stat-strip";
+import type { StatItem } from "@/g8/components/screen/stat-strip";
+import { TimeSeriesChart } from "@/g8/components/screen/time-series-chart";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useReport } from "../hooks/use-report";
+import { LIMITS, windowedQuery } from "../lib/analytics-scope";
+import type { ScopeState } from "../lib/analytics-scope";
+import { fmtDay, fmtDecimal, fmtInt, fmtMinutes, fmtPct, num, readRow, readRows, str } from "../lib/web-analytics-types";
+import type { DepthBucket, EngagementByCampaign, EngagementByChannel, EngagementByLanding, EngagementOverview, EngagementTrendPoint, TimeBucket } from "../lib/web-analytics-types";
+import { RankedTable } from "./ranked-table";
+import { ReportCard } from "./report-card";
+
+const METRICS = [
+  { key: "sessions", label: "Sessions", fmt: (v: number) => v.toLocaleString() },
+  { key: "avg_session_depth", label: "Pages per session", fmt: (v: number) => fmtDecimal(v, 2) },
+  { key: "avg_time_minutes", label: "Time on site", fmt: (v: number) => fmtMinutes(v) },
+  { key: "bounce_rate", label: "Bounce rate", fmt: (v: number) => fmtPct(v) },
+  { key: "engaged_sessions", label: "Engaged sessions", fmt: (v: number) => v.toLocaleString() },
+] as const;
+
+/** A change against the previous period as a tile delta; absent when the API had none. */
+function delta(v: unknown): Pick<StatItem, "delta" | "tone"> {
+  const n = num(v);
+  if (n == null) return {};
+  return { delta: n, tone: n > 0 ? "positive" : n < 0 ? "negative" : undefined };
+}
+
+function summaryTiles(d: EngagementOverview): StatItem[] {
+  return [
+    { label: "Sessions", value: fmtInt(d.total_sessions) },
+    { label: "Pages per session", value: fmtDecimal(d.avg_session_depth, 2), ...delta(d.depth_trend_pct) },
+    { label: "Time on site", value: fmtMinutes(d.avg_time_minutes), ...delta(d.time_trend_pct) },
+    { label: "Bounce rate", value: fmtPct(d.bounce_rate), hint: "Sessions with a single page view. A positive change means the bounce rate fell.", ...delta(d.bounce_trend_pct) },
+    { label: "Engaged sessions", value: fmtPct(d.engaged_pct), hint: "More than one page and more than 30 seconds", ...delta(d.engaged_trend_pct) },
+  ];
+}
+
+const NUM_COLS = <R extends { sessions?: number; avg_session_depth?: number; avg_time_minutes?: number; bounce_rate?: number; engaged_pct?: number }>() => [
+  { key: "sessions", label: "Sessions", numeric: true, render: (r: R) => fmtInt(r.sessions), sortBy: (r: R) => num(r.sessions) },
+  { key: "depth", label: "Pages", numeric: true, render: (r: R) => fmtDecimal(r.avg_session_depth, 2), sortBy: (r: R) => num(r.avg_session_depth) },
+  { key: "time", label: "Time", numeric: true, render: (r: R) => fmtMinutes(r.avg_time_minutes), sortBy: (r: R) => num(r.avg_time_minutes) },
+  { key: "bounce", label: "Bounce rate", numeric: true, render: (r: R) => fmtPct(r.bounce_rate), sortBy: (r: R) => num(r.bounce_rate) },
+  { key: "engaged", label: "Engaged", numeric: true, render: (r: R) => fmtPct(r.engaged_pct), sortBy: (r: R) => num(r.engaged_pct) },
+];
+
+export function EngagementTab({ scope }: { scope: ScopeState }) {
+  const q = windowedQuery(scope);
+  const [metric, setMetric] = useState<(typeof METRICS)[number]["key"]>("sessions");
+  const overview = useReport(async (signal) => readRow<EngagementOverview>(await g8Get("/analytics/engagement/overview", q, { signal })), scope.key);
+  const trend = useReport(async (signal) => readRows<EngagementTrendPoint>(await g8Get("/analytics/engagement/trend", q, { signal })), scope.key);
+  const depth = useReport(async (signal) => readRows<DepthBucket>(await g8Get("/analytics/engagement/depth-distribution", q, { signal })), scope.key);
+  const time = useReport(async (signal) => readRows<TimeBucket>(await g8Get("/analytics/engagement/time-distribution", q, { signal })), scope.key);
+  const byChannel = useReport(async (signal) => readRows<EngagementByChannel>(await g8Get("/analytics/engagement/by-channel", q, { signal })), scope.key);
+  const byCampaign = useReport(async (signal) => readRows<EngagementByCampaign>(await g8Get("/analytics/engagement/by-campaign", { ...q, limit: LIMITS.byCampaign }, { signal })), scope.key);
+  const byLanding = useReport(async (signal) => readRows<EngagementByLanding>(await g8Get("/analytics/engagement/by-landing-page", { ...q, limit: LIMITS.byLanding }, { signal })), scope.key);
+  const none = (rows: unknown[]) => rows.length === 0;
+  const m = METRICS.find((x) => x.key === metric)!;
+  return (
+    <div className="grid gap-4 lg:grid-cols-2">
+      <ReportCard className="lg:col-span-2" title="Summary" report={overview} isEmpty={(d) => d === null}>
+        {(d) => <StatStrip items={summaryTiles(d!)} />}
+      </ReportCard>
+      <ReportCard
+        className="lg:col-span-2"
+        title="Trend"
+        report={trend}
+        isEmpty={none}
+        skeletonHeight={220}
+        actions={
+          <div role="group" aria-label="Metric" className="flex flex-wrap gap-1">
+            {METRICS.map((x) => <Button key={x.key} type="button" size="sm" variant={metric === x.key ? "default" : "outline"} aria-pressed={metric === x.key} onClick={() => setMetric(x.key)}>{x.label}</Button>)}
+          </div>
+        }
+      >
+        {(rows) => <TimeSeriesChart data={rows.map((r) => ({ ...r }))} xKey="date" series={[{ key: metric, label: m.label }]} kind="line" height={220} formatX={fmtDay} formatY={m.fmt} />}
+      </ReportCard>
+      <ReportCard title="Pages per session" description="Share of sessions" report={depth} isEmpty={none}>
+        {(rows) => <BarList items={rows.map((r) => ({ label: str(r.depth_bucket), value: num(r.sessions) ?? 0, display: `${fmtInt(r.sessions)} (${fmtPct(r.percentage, 0)})` }))} emphasizeFirst={false} />}
+      </ReportCard>
+      <ReportCard title="Time on site" description="Share of sessions" report={time} isEmpty={none}>
+        {(rows) => <BarList items={rows.map((r) => ({ label: str(r.duration_bucket), value: num(r.sessions) ?? 0, display: `${fmtInt(r.sessions)} (${fmtPct(r.percentage, 0)})` }))} emphasizeFirst={false} />}
+      </ReportCard>
+      <ReportCard className="lg:col-span-2" title="By channel" report={byChannel} isEmpty={none}>
+        {(rows) => (
+          <RankedTable rows={rows} noun="channels" defaultSort="sessions" rowKey={(r, i) => `${str(r.channel)}|${i}`} columns={[{ key: "channel", label: "Channel", render: (r) => str(r.channel) || "Unknown", sortBy: (r) => str(r.channel) }, ...NUM_COLS<EngagementByChannel>()]} />
+        )}
+      </ReportCard>
+      <ReportCard className="lg:col-span-2" title="By campaign" report={byCampaign} isEmpty={none} emptyTitle="No tagged campaigns in this window">
+        {(rows) => (
+          <RankedTable rows={rows} noun="campaigns" limit={LIMITS.byCampaign} defaultSort="sessions" rowKey={(r, i) => `${str(r.campaign)}|${str(r.source)}|${i}`} columns={[{ key: "campaign", label: "Campaign", render: (r) => str(r.campaign) || "Unknown", sortBy: (r) => str(r.campaign) }, { key: "source", label: "Source", render: (r) => str(r.source), sortBy: (r) => str(r.source) }, ...NUM_COLS<EngagementByCampaign>()]} />
+        )}
+      </ReportCard>
+      <ReportCard className="lg:col-span-2" title="By landing page" report={byLanding} isEmpty={none}>
+        {(rows) => (
+          <RankedTable rows={rows} noun="landing pages" limit={LIMITS.byLanding} defaultSort="sessions" rowKey={(r, i) => `${str(r.landing_page)}|${i}`} columns={[{ key: "page", label: "Landing page", render: (r) => str(r.landing_page) || "Unknown", sortBy: (r) => str(r.landing_page) }, ...NUM_COLS<EngagementByLanding>()]} />
+        )}
+      </ReportCard>
+    </div>
+  );
+}

package/blocks/web-analytics/components/overview-tab.tsx

@@ -0,0 +1,102 @@
+"use client";
+
+/**
+ * OverviewTab: the headline numbers of the site for the chosen sites and window.
+ *   Audience      visitors, new visitors, sessions, page views (tiles belong to this card and vanish with it if it is unavailable)
+ *   Traffic       one daily series at a time (visitors, sessions or page views)
+ *   Conversion    visitors that converted, as a rate (a dash when there were no visitors)
+ *   Top pages     the most viewed pages; a row opens the page detail on the Pages tab
+ *
+ * SDK operations, in order (all read, free):
+ *   1. getAudienceOverview  GET /analytics/audience/overview
+ *   2. getAudienceTrend     GET /analytics/audience/trend
+ *   3. getConversionRate    GET /analytics/conversions/rate
+ *   4. getTopPages          GET /analytics/behavior/pages   (top 8 by views; the ranking, not a list to scroll)
+ * Types: see lib/web-analytics-types.ts (the contract leaves these payloads untyped).
+ */
+import { useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { BarList } from "@/g8/components/screen/bar-list";
+import { StatStrip } from "@/g8/components/screen/stat-strip";
+import { TimeSeriesChart } from "@/g8/components/screen/time-series-chart";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useReport } from "../hooks/use-report";
+import { windowedQuery } from "../lib/analytics-scope";
+import type { ScopeState } from "../lib/analytics-scope";
+import { fmtDay, fmtInt, fmtPct, num, pctOf, readRow, readRows, str } from "../lib/web-analytics-types";
+import type { AudienceOverview, ConversionRate, PageRow, TrendPoint } from "../lib/web-analytics-types";
+import { ReportCard } from "./report-card";
+
+export interface OverviewTabProps {
+  scope: ScopeState;
+  onOpenPage: (path: string) => void;
+  onGoTab: (tab: string) => void;
+}
+
+const METRICS = [
+  { key: "users", label: "Visitors" },
+  { key: "sessions", label: "Sessions" },
+  { key: "page_views", label: "Page views" },
+] as const;
+
+export function OverviewTab({ scope, onOpenPage, onGoTab }: OverviewTabProps) {
+  const q = windowedQuery(scope);
+  const [metric, setMetric] = useState<(typeof METRICS)[number]["key"]>("users");
+  const overview = useReport(async (signal) => readRow<AudienceOverview>(await g8Get("/analytics/audience/overview", q, { signal })), scope.key);
+  const trend = useReport(async (signal) => readRows<TrendPoint>(await g8Get("/analytics/audience/trend", q, { signal })), scope.key);
+  const rate = useReport(async (signal) => readRow<ConversionRate>(await g8Get("/analytics/conversions/rate", q, { signal })), scope.key);
+  const pages = useReport(async (signal) => readRows<PageRow>(await g8Get("/analytics/behavior/pages", { ...q, limit: 8 }, { signal })), scope.key);
+  const series = METRICS.find((m) => m.key === metric)!;
+  return (
+    <div className="grid gap-4 lg:grid-cols-2">
+      <ReportCard className="lg:col-span-2" title="Audience" report={overview} isEmpty={(d) => d === null}>
+        {(d) => {
+          const newShare = pctOf(d!.new_users, d!.total_users);
+          return (
+            <StatStrip
+              items={[
+                { label: "Visitors", value: fmtInt(d!.total_users) },
+                { label: "New visitors", value: fmtInt(d!.new_users), hint: newShare == null ? undefined : `${fmtPct(newShare)} of visitors in this window were new` },
+                { label: "Sessions", value: fmtInt(d!.sessions), hint: "A visitor counts once per hour of activity" },
+                { label: "Page views", value: fmtInt(d!.page_views) },
+              ]}
+            />
+          );
+        }}
+      </ReportCard>
+      <ReportCard
+        className="lg:col-span-2"
+        title="Traffic"
+        report={trend}
+        isEmpty={(rows) => rows.length === 0}
+        emptyTitle="No traffic in this window"
+        emptyDescription="Visits appear once the tracking snippet is live on the site."
+        skeletonHeight={220}
+        actions={
+          <div role="group" aria-label="Metric" className="inline-flex gap-1">
+            {METRICS.map((m) => (
+              <Button key={m.key} type="button" size="sm" variant={metric === m.key ? "default" : "outline"} aria-pressed={metric === m.key} onClick={() => setMetric(m.key)}>{m.label}</Button>
+            ))}
+          </div>
+        }
+      >
+        {(rows) => <TimeSeriesChart data={rows.map((r) => ({ ...r }))} xKey="date" series={[{ key: metric, label: series.label }]} kind="area" height={220} formatX={fmtDay} formatY={(v) => v.toLocaleString()} />}
+      </ReportCard>
+      <ReportCard title="Conversion" description="Visitors who submitted a form or booked a meeting" report={rate} isEmpty={(d) => d === null}>
+        {(d) => (
+          <div className="space-y-2">
+            <StatStrip items={[{ label: "Conversion rate", value: fmtPct(d!.conversion_rate, 2), hint: "Converting visitors divided by all visitors. A dash means there were no visitors." }, { label: "Converted", value: fmtInt(d!.total_converters) }]} />
+            <Button type="button" size="sm" variant="outline" onClick={() => onGoTab("conversions")}>See goals and funnel</Button>
+          </div>
+        )}
+      </ReportCard>
+      <ReportCard title="Top pages" description="By views" report={pages} isEmpty={(rows) => rows.length === 0} emptyTitle="No page views in this window">
+        {(rows) => (
+          <BarList
+            items={rows.map((p) => ({ label: str(p.page_path) || str(p.page_title) || "Unknown page", value: num(p.views) ?? 0, onClick: p.page_path ? () => onOpenPage(str(p.page_path)) : undefined }))}
+          />
+        )}
+      </ReportCard>
+    </div>
+  );
+}