@graph8/sdk 0.370.0 → 0.374.0

package/blocks/web-analytics/block.json

@@ -0,0 +1,292 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "web-analytics",
+  "title": "Web analytics",
+  "summary": "Website analytics for your own sites: traffic, acquisition, audience, pages, engagement, conversions and realtime, with one site picker and window shared across tabs.",
+  "features": [
+    "one site picker and one date window (7/30/90/365 days or a validated custom range) shared by every tab through the URL",
+    "overview, acquisition (channels, sources, UTM campaigns, referrals, social, search), audience (geo, languages, technology), pages, engagement, conversions and realtime",
+    "page detail with an optional open-landing-page link by id",
+    "loading state on every filter change, an honest unavailable state when the query failed, dashes for unknown rates"
+  ],
+  "dependsOn": [
+    "visitors"
+  ],
+  "operations": [
+    "get_acquisition_campaigns_analytics_acquisition_campaigns_get",
+    "get_acquisition_channels_analytics_acquisition_channels_get",
+    "get_acquisition_channels_trend_analytics_acquisition_channels_trend_get",
+    "get_acquisition_referrals_analytics_acquisition_referrals_get",
+    "get_acquisition_search_analytics_acquisition_search_get",
+    "get_acquisition_social_analytics_acquisition_social_get",
+    "get_acquisition_sources_analytics_acquisition_sources_get",
+    "get_audience_behavior_analytics_audience_behavior_get",
+    "get_audience_demographics_analytics_audience_demographics_get",
+    "get_audience_languages_analytics_audience_languages_get",
+    "get_audience_overview_analytics_audience_overview_get",
+    "get_audience_trend_analytics_audience_trend_get",
+    "get_conversion_rate_analytics_conversions_rate_get",
+    "get_engagement_by_campaign_analytics_engagement_by_campaign_get",
+    "get_engagement_by_channel_analytics_engagement_by_channel_get",
+    "get_engagement_by_landing_page_analytics_engagement_by_landing_page_get",
+    "get_engagement_overview_analytics_engagement_overview_get",
+    "get_engagement_trend_analytics_engagement_trend_get",
+    "get_events_analytics_behavior_events_get",
+    "get_exit_pages_analytics_behavior_exit_pages_get",
+    "get_form_analysis_analytics_conversions_forms_analysis_get",
+    "get_forms_analytics_conversions_forms_get",
+    "get_forms_trend_analytics_conversions_forms_trend_get",
+    "get_funnel_analytics_conversions_funnel_get",
+    "get_geo_cities_analytics_audience_geo_cities_get",
+    "get_geo_countries_analytics_audience_geo_get",
+    "get_goals_analytics_conversions_goals_get",
+    "get_goals_trend_analytics_conversions_goals_trend_get",
+    "get_landing_pages_analytics_behavior_landing_pages_get",
+    "get_page_metrics_analytics_behavior_page_metrics_get",
+    "get_realtime_analytics_realtime_get",
+    "get_realtime_locations_analytics_realtime_locations_get",
+    "get_realtime_pages_analytics_realtime_pages_get",
+    "get_realtime_sources_analytics_realtime_sources_get",
+    "get_session_depth_distribution_analytics_engagement_depth_distribution_get",
+    "get_technology_overview_analytics_audience_technology_get",
+    "get_time_on_site_distribution_analytics_engagement_time_distribution_get",
+    "get_top_pages_analytics_behavior_pages_get",
+    "list_org_streams_streams_get"
+  ],
+  "components": [
+    {
+      "name": "WebAnalyticsScreen",
+      "file": "components/web-analytics-screen.tsx",
+      "purpose": "Finished website analytics page: seven tabs (overview, acquisition, audience, pages, engagement, conversions, realtime) sharing one site picker and one window through the URL.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "AnalyticsFilters",
+      "file": "components/analytics-filters.tsx",
+      "purpose": "The one site picker, window (7/30/90/365 days or a validated custom range) and bot/internal traffic switches.",
+      "operations": [
+        "list_org_streams_streams_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "OverviewTab",
+      "file": "components/overview-tab.tsx",
+      "purpose": "Audience tiles, daily traffic chart, conversion rate and top pages.",
+      "operations": [
+        "get_audience_overview_analytics_audience_overview_get",
+        "get_audience_trend_analytics_audience_trend_get",
+        "get_conversion_rate_analytics_conversions_rate_get",
+        "get_top_pages_analytics_behavior_pages_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "AcquisitionTab",
+      "file": "components/acquisition-tab.tsx",
+      "purpose": "Channels, channel trend, sources and mediums, UTM campaigns, referrals, social networks and search engines.",
+      "operations": [
+        "get_acquisition_campaigns_analytics_acquisition_campaigns_get",
+        "get_acquisition_channels_analytics_acquisition_channels_get",
+        "get_acquisition_channels_trend_analytics_acquisition_channels_trend_get",
+        "get_acquisition_referrals_analytics_acquisition_referrals_get",
+        "get_acquisition_search_analytics_acquisition_search_get",
+        "get_acquisition_social_analytics_acquisition_social_get",
+        "get_acquisition_sources_analytics_acquisition_sources_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "AudienceTab",
+      "file": "components/audience-tab.tsx",
+      "purpose": "Demographics at a glance, countries and cities, languages, technology, new or returning visitors.",
+      "operations": [
+        "get_audience_behavior_analytics_audience_behavior_get",
+        "get_audience_demographics_analytics_audience_demographics_get",
+        "get_audience_languages_analytics_audience_languages_get",
+        "get_geo_cities_analytics_audience_geo_cities_get",
+        "get_geo_countries_analytics_audience_geo_get",
+        "get_technology_overview_analytics_audience_technology_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "PagesTab",
+      "file": "components/pages-tab.tsx",
+      "purpose": "Top, landing and exit pages, custom events, and a page detail panel; a page can open its landing page by id.",
+      "operations": [
+        "get_events_analytics_behavior_events_get",
+        "get_exit_pages_analytics_behavior_exit_pages_get",
+        "get_landing_pages_analytics_behavior_landing_pages_get",
+        "get_page_metrics_analytics_behavior_page_metrics_get",
+        "get_top_pages_analytics_behavior_pages_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "EngagementTab",
+      "file": "components/engagement-tab.tsx",
+      "purpose": "Sessions, depth, time on site, bounce and engaged share against the previous period, distributions, by channel, campaign and landing page.",
+      "operations": [
+        "get_engagement_by_campaign_analytics_engagement_by_campaign_get",
+        "get_engagement_by_channel_analytics_engagement_by_channel_get",
+        "get_engagement_by_landing_page_analytics_engagement_by_landing_page_get",
+        "get_engagement_overview_analytics_engagement_overview_get",
+        "get_engagement_trend_analytics_engagement_trend_get",
+        "get_session_depth_distribution_analytics_engagement_depth_distribution_get",
+        "get_time_on_site_distribution_analytics_engagement_time_distribution_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "ConversionsTab",
+      "file": "components/conversions-tab.tsx",
+      "purpose": "Conversion rate, funnel, goals and their trend, forms, form trend and form analysis.",
+      "operations": [
+        "get_conversion_rate_analytics_conversions_rate_get",
+        "get_form_analysis_analytics_conversions_forms_analysis_get",
+        "get_forms_analytics_conversions_forms_get",
+        "get_forms_trend_analytics_conversions_forms_trend_get",
+        "get_funnel_analytics_conversions_funnel_get",
+        "get_goals_analytics_conversions_goals_get",
+        "get_goals_trend_analytics_conversions_goals_trend_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "RealtimeTab",
+      "file": "components/realtime-tab.tsx",
+      "purpose": "Active visitors now, active pages, traffic sources and locations; polled while visible.",
+      "operations": [
+        "get_realtime_analytics_realtime_get",
+        "get_realtime_locations_analytics_realtime_locations_get",
+        "get_realtime_pages_analytics_realtime_pages_get",
+        "get_realtime_sources_analytics_realtime_sources_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "ReportCard",
+      "file": "components/report-card.tsx",
+      "purpose": "A report in a card with loading, error, unavailable (stale), empty and dimmed-while-refreshing states.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "RankedTable",
+      "file": "components/ranked-table.tsx",
+      "purpose": "Re-sortable top-N table that sorts the whole list before cutting it, with a first-N notice.",
+      "operations": [],
+      "tiers": []
+    }
+  ],
+  "screens": [
+    {
+      "component": "WebAnalyticsScreen",
+      "path": "/web-analytics",
+      "label": "Web analytics",
+      "icon": "ChartNoAxesCombined",
+      "group": "Signals"
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useReport",
+      "file": "hooks/use-report.ts",
+      "purpose": "One report read with first-load, pending (scope changed), error and stale states.",
+      "operations": []
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/web-analytics-types.ts",
+      "purpose": "Row types typed from the backend queries (the contract leaves them untyped), envelope readers and dash-safe formatters."
+    },
+    {
+      "file": "lib/analytics-scope.ts",
+      "purpose": "The shared scope (sites, window, traffic switches) in the URL, with the checks the API enforces and each report's limit cap."
+    },
+    {
+      "file": "lib/page-path.ts",
+      "purpose": "The page path pattern the single-page report accepts."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/weekly-traffic-report.ts",
+      "title": "Summarise a site's traffic, sources and conversion for a window",
+      "when": "A weekly digest or dashboard header."
+    },
+    {
+      "file": "recipes/best-landing-pages.ts",
+      "title": "Rank landing pages by sessions and engagement",
+      "when": "Deciding which landing pages to promote or rewrite."
+    },
+    {
+      "file": "recipes/form-conversion-check.ts",
+      "title": "Find forms that get views but few submissions",
+      "when": "A conversion review."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "snippet-on-site",
+      "description": "The graph8 tracking snippet is pasted into the website. Without it every report is empty.",
+      "where": "app",
+      "verify": "GET /visitors/installation-check reports status receiving (the visitors block's SnippetInstall)."
+    },
+    {
+      "id": "website-stream",
+      "description": "The workspace has at least one website stream; its write key is what the site picker filters on.",
+      "where": "api",
+      "verify": "GET /streams returns at least one stream with a write_key."
+    }
+  ],
+  "scopes": [
+    "analytics:read",
+    "integrations:read"
+  ],
+  "defaults": [
+    {
+      "decision": "Window",
+      "default": "Last 30 days",
+      "askHuman": false
+    },
+    {
+      "decision": "Sites",
+      "default": "All sites (no filter)",
+      "askHuman": false
+    },
+    {
+      "decision": "Bots and internal traffic",
+      "default": "Excluded (the API's default)",
+      "askHuman": false
+    },
+    {
+      "decision": "Realtime refresh",
+      "default": "Every 10 seconds while the page is visible",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "lucide-react": ">=0.400"
+  }
+}

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

@@ -0,0 +1,154 @@
+"use client";
+
+/**
+ * AcquisitionTab: where visitors come from.
+ *   Channels            sessions and bounce rate per channel group (Direct, Organic Search, Paid Search, Email, ...)
+ *   Channel trend       sessions per day, for all channels or one chosen channel
+ *   Sources and mediums / Campaigns (UTM) / Referrals    ranked tables you can re-sort; sorting ranks the whole list, then cuts it
+ *   Social / Search engines    the networks and engines that sent visitors
+ *
+ * SDK operations, in order (all read, free). RankedTable renders a FirstNotice ("Showing the first N") when a read came back full:
+ *   1. getAcquisitionChannels       GET /analytics/acquisition/channels
+ *   2. getAcquisitionChannelsTrend  GET /analytics/acquisition/channels/trend
+ *   3. getAcquisitionSources        GET /analytics/acquisition/sources     (limit 200)
+ *   4. getAcquisitionCampaigns      GET /analytics/acquisition/campaigns   (limit 200)
+ *   5. getAcquisitionReferrals      GET /analytics/acquisition/referrals   (limit 200)
+ *   6. getAcquisitionSocial         GET /analytics/acquisition/social
+ *   7. getAcquisitionSearch         GET /analytics/acquisition/search
+ * Types: see lib/web-analytics-types.ts (the contract leaves these payloads untyped).
+ */
+import { useMemo, useState } from "react";
+import { BarList } from "@/g8/components/screen/bar-list";
+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, fmtInt, fmtPct, num, readRows, str } from "../lib/web-analytics-types";
+import type { CampaignRow, Channel, ChannelTrendPoint, Referral, Row, SourceMedium } from "../lib/web-analytics-types";
+import { RankedTable } from "./ranked-table";
+import { ReportCard } from "./report-card";
+
+const SELECT = "h-8 rounded-md border bg-background px-2 text-sm";
+
+function ChannelTrend({ rows }: { rows: ChannelTrendPoint[] }) {
+  const [channel, setChannel] = useState("");
+  const channels = useMemo(() => [...new Set(rows.map((r) => str(r.channel)).filter(Boolean))].sort(), [rows]);
+  const data = useMemo(() => {
+    const byDay = new Map<string, number>();
+    for (const r of rows) {
+      if (channel && str(r.channel) !== channel) continue;
+      byDay.set(str(r.date), (byDay.get(str(r.date)) ?? 0) + (num(r.sessions) ?? 0));
+    }
+    return [...byDay.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([date, sessions]) => ({ date, sessions }));
+  }, [rows, channel]);
+  return (
+    <div className="space-y-2">
+      <select aria-label="Channel" className={SELECT} value={channel} onChange={(e) => setChannel(e.target.value)}>
+        <option value="">All channels</option>
+        {channels.map((c) => <option key={c} value={c}>{c}</option>)}
+      </select>
+      <TimeSeriesChart data={data} xKey="date" series={[{ key: "sessions", label: "Sessions" }]} kind="bar" height={200} formatX={fmtDay} formatY={(v) => v.toLocaleString()} />
+    </div>
+  );
+}
+
+function NameBars({ rows, name, value }: { rows: Row[]; name: string; value: string }) {
+  return <BarList items={rows.map((r) => ({ label: str(r[name]) || "Unknown", value: num(r[value]) ?? 0 }))} />;
+}
+
+export function AcquisitionTab({ scope }: { scope: ScopeState }) {
+  const q = windowedQuery(scope);
+  const channels = useReport(async (signal) => readRows<Channel>(await g8Get("/analytics/acquisition/channels", q, { signal })), scope.key);
+  const trend = useReport(async (signal) => readRows<ChannelTrendPoint>(await g8Get("/analytics/acquisition/channels/trend", q, { signal })), scope.key);
+  const sources = useReport(async (signal) => readRows<SourceMedium>(await g8Get("/analytics/acquisition/sources", { ...q, limit: LIMITS.sources }, { signal })), scope.key);
+  const campaigns = useReport(async (signal) => readRows<CampaignRow>(await g8Get("/analytics/acquisition/campaigns", { ...q, limit: LIMITS.campaigns }, { signal })), scope.key);
+  const referrals = useReport(async (signal) => readRows<Referral>(await g8Get("/analytics/acquisition/referrals", { ...q, limit: LIMITS.referrals }, { signal })), scope.key);
+  const social = useReport(async (signal) => readRows(await g8Get("/analytics/acquisition/social", q, { signal })), scope.key);
+  const search = useReport(async (signal) => readRows(await g8Get("/analytics/acquisition/search", q, { signal })), scope.key);
+  const none = (rows: unknown[]) => rows.length === 0;
+  return (
+    <div className="grid gap-4 lg:grid-cols-2">
+      <ReportCard title="Channels" description="Sessions by channel group" report={channels} isEmpty={none}>
+        {(rows) => (
+          <RankedTable
+            rows={rows}
+            noun="channels"
+            defaultSort="sessions"
+            rowKey={(r, i) => str(r.channel) || String(i)}
+            columns={[
+              { key: "channel", label: "Channel", render: (r) => str(r.channel) || "Unknown", sortBy: (r) => str(r.channel) },
+              { 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) },
+              { key: "page_views", label: "Page views", numeric: true, render: (r) => fmtInt(r.page_views), sortBy: (r) => num(r.page_views) },
+              { key: "bounce", label: "Bounce rate", numeric: true, render: (r) => fmtPct(r.bounce_rate), sortBy: (r) => num(r.bounce_rate) },
+            ]}
+          />
+        )}
+      </ReportCard>
+      <ReportCard title="Channel trend" description="Sessions per day" report={trend} isEmpty={none} skeletonHeight={240}>
+        {(rows) => <ChannelTrend rows={rows} />}
+      </ReportCard>
+      <ReportCard className="lg:col-span-2" title="Sources and mediums" report={sources} isEmpty={none}>
+        {(rows) => (
+          <RankedTable
+            rows={rows}
+            noun="sources"
+            limit={LIMITS.sources}
+            defaultSort="sessions"
+            rowKey={(r, i) => `${str(r.source)}|${str(r.medium)}|${i}`}
+            columns={[
+              { key: "source", label: "Source", render: (r) => str(r.source) || "Unknown", sortBy: (r) => str(r.source) },
+              { key: "medium", label: "Medium", render: (r) => str(r.medium) || "Unknown", sortBy: (r) => str(r.medium) },
+              { 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) },
+              { key: "page_views", label: "Page views", numeric: true, render: (r) => fmtInt(r.page_views), sortBy: (r) => num(r.page_views) },
+            ]}
+          />
+        )}
+      </ReportCard>
+      <ReportCard className="lg:col-span-2" title="Campaigns" description="From the utm_campaign tag" report={campaigns} isEmpty={none} emptyTitle="No tagged campaigns in this window" emptyDescription="Add utm_campaign to your links and they appear here.">
+        {(rows) => (
+          <RankedTable
+            rows={rows}
+            noun="campaigns"
+            limit={LIMITS.campaigns}
+            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) },
+              { key: "medium", label: "Medium", render: (r) => str(r.medium), sortBy: (r) => str(r.medium) },
+              { 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) },
+              { key: "page_views", label: "Page views", numeric: true, render: (r) => fmtInt(r.page_views), sortBy: (r) => num(r.page_views) },
+            ]}
+          />
+        )}
+      </ReportCard>
+      <ReportCard className="lg:col-span-2" title="Referrals" description="Other websites that sent visitors" report={referrals} isEmpty={none}>
+        {(rows) => (
+          <RankedTable
+            rows={rows}
+            noun="referrers"
+            limit={LIMITS.referrals}
+            defaultSort="sessions"
+            rowKey={(r, i) => `${str(r.referrer)}|${i}`}
+            columns={[
+              { key: "referrer", label: "Referrer", render: (r) => str(r.referrer) || "Unknown", sortBy: (r) => str(r.referrer) },
+              { 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) },
+              { key: "page_views", label: "Page views", numeric: true, render: (r) => fmtInt(r.page_views), sortBy: (r) => num(r.page_views) },
+            ]}
+          />
+        )}
+      </ReportCard>
+      <ReportCard title="Social networks" description="Visitors by network" report={social} isEmpty={none} emptyTitle="No social visits in this window">
+        {(rows) => <NameBars rows={rows} name="network" value="users" />}
+      </ReportCard>
+      <ReportCard title="Search engines" description="Visitors by engine" report={search} isEmpty={none} emptyTitle="No search visits in this window">
+        {(rows) => <NameBars rows={rows} name="search_engine" value="users" />}
+      </ReportCard>
+    </div>
+  );
+}

package/blocks/web-analytics/components/analytics-filters.tsx

@@ -0,0 +1,161 @@
+"use client";
+
+/**
+ * AnalyticsFilters: the one site picker, window and traffic switches that drive every tab (state lives in the URL, see
+ * lib/analytics-scope.ts).
+ *
+ *   Sites     every website stream of the workspace, as checkboxes (none checked = all sites). A stream without a write
+ *             key cannot be filtered on, so it is shown disabled.
+ *   Window    7 / 30 / 90 / 365 days, or a custom range. The custom range is only applied when the API would accept it
+ *             (both days, real dates, start not after end, at most 365 days); otherwise Apply is disabled and says why.
+ *   Traffic   "Include bots" and "Include internal traffic" (both off by default, and only sent when on).
+ *
+ * SDK operations, in order:
+ *   1. listOrgStreams  GET /streams?page&limit   (read; the sites, paged with useAllPages)
+ */
+import { useEffect, useRef, useState } from "react";
+import { Globe } from "lucide-react";
+import { Button, Skeleton, cn } from "@graph8/sdk/ui";
+import { useAllPages } from "@/g8/hooks/use-all-pages";
+import { g8Get } from "@/g8/lib/g8-client";
+import { hasNextOf } from "@/g8/lib/paging";
+import { MoreFilters } from "@/g8/components/screen/filter-controls";
+import { DAY_PRESETS, RANGE_PROBLEM_TEXT, rangeProblem, todayUtc } from "../lib/analytics-scope";
+import type { ScopeState } from "../lib/analytics-scope";
+
+interface Stream {
+  id: string;
+  name?: string;
+  domains?: string[];
+  write_key?: string | null;
+}
+
+const STREAM_PAGE = 50;
+
+function SitePicker({ scope }: { scope: ScopeState }) {
+  const [open, setOpen] = useState(false);
+  const box = useRef<HTMLDivElement>(null);
+  // Close on a click outside or Escape, like any menu.
+  useEffect(() => {
+    if (!open) return;
+    const away = (e: MouseEvent) => { if (box.current && !box.current.contains(e.target as Node)) setOpen(false); };
+    const esc = (e: KeyboardEvent) => { if (e.key === "Escape") setOpen(false); };
+    document.addEventListener("mousedown", away);
+    document.addEventListener("keydown", esc);
+    return () => { document.removeEventListener("mousedown", away); document.removeEventListener("keydown", esc); };
+  }, [open]);
+  const streams = useAllPages<Stream>(async (page, signal) => {
+    const env = await g8Get<Stream[]>("/streams", { page, limit: STREAM_PAGE }, { signal });
+    const rows = env.data ?? [];
+    return { rows, hasNext: hasNextOf(env, STREAM_PAGE, rows.length) };
+  }, []);
+  const keyed = streams.items.filter((s) => s.write_key && /^[A-Za-z0-9_-]+$/.test(s.write_key));
+  const known = new Set(keyed.map((s) => s.write_key!));
+  const unknown = streams.loaded ? scope.sites.filter((k) => !known.has(k)) : [];
+  const toggle = (key: string) => scope.setSites(scope.sites.includes(key) ? scope.sites.filter((k) => k !== key) : [...scope.sites, key]);
+  const nameOf = (key: string) => keyed.find((s) => s.write_key === key)?.name ?? key;
+  const label = scope.sites.length === 0 ? "All sites" : scope.sites.length === 1 ? nameOf(scope.sites[0]) : `${scope.sites.length} sites`;
+  return (
+    <div className="relative" ref={box}>
+      <Button type="button" variant="outline" size="sm" aria-expanded={open} aria-haspopup="true" aria-label={`Sites: ${label}`} onClick={() => setOpen((o) => !o)}>
+        <Globe className="size-4" strokeWidth={1.5} aria-hidden />
+        {label}
+      </Button>
+      {open ? (
+        <div role="group" aria-label="Sites" className="absolute left-0 top-full z-30 mt-1 w-72 rounded-md border border-border bg-popover p-2 text-sm shadow-md">
+          {streams.loading && !streams.loaded ? (
+            <Skeleton className="h-16 w-full" />
+          ) : streams.error ? (
+            <div className="space-y-2 p-1">
+              <p className="text-error-foreground">Could not load your sites.</p>
+              <Button type="button" size="sm" variant="outline" onClick={streams.refetch}>Retry</Button>
+            </div>
+          ) : (
+            <ul className="max-h-64 space-y-0.5 overflow-auto">
+              <li>
+                <label className="flex cursor-pointer items-center gap-2 rounded px-2 py-1.5 hover:bg-surface-hover">
+                  <input type="checkbox" checked={scope.sites.length === 0} onChange={() => scope.setSites([])} />
+                  <span>All sites</span>
+                </label>
+              </li>
+              {keyed.map((s) => (
+                <li key={s.id}>
+                  <label className="flex cursor-pointer items-center gap-2 rounded px-2 py-1.5 hover:bg-surface-hover">
+                    <input type="checkbox" checked={scope.sites.includes(s.write_key!)} onChange={() => toggle(s.write_key!)} />
+                    <span className="min-w-0 truncate">{s.name || s.domains?.[0] || s.write_key}</span>
+                    {s.domains?.[0] && s.name ? <span className="min-w-0 truncate text-xs text-text-color-muted">{s.domains[0]}</span> : null}
+                  </label>
+                </li>
+              ))}
+              {streams.items.filter((s) => !keyed.includes(s)).map((s) => (
+                <li key={s.id} className="flex items-center gap-2 px-2 py-1.5 text-text-color-muted">
+                  <input type="checkbox" disabled aria-label={`${s.name || s.id} has no write key`} />
+                  <span className="truncate">{s.name || s.id}</span>
+                  <span className="text-xs">no write key</span>
+                </li>
+              ))}
+              {unknown.map((k) => (
+                <li key={k}>
+                  <label className="flex cursor-pointer items-center gap-2 rounded px-2 py-1.5 hover:bg-surface-hover">
+                    <input type="checkbox" checked onChange={() => toggle(k)} />
+                    <span className="truncate">{k}</span>
+                    <span className="text-xs text-text-color-muted">not in this workspace</span>
+                  </label>
+                </li>
+              ))}
+              {keyed.length === 0 && streams.items.length === 0 ? <li className="px-2 py-1.5 text-text-color-muted">No sites yet. Install the tracking snippet first.</li> : null}
+            </ul>
+          )}
+          {streams.truncated ? <p role="note" className="px-1 pt-1 text-xs text-text-color-muted">Showing the first {streams.items.length} sites.</p> : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function WindowPicker({ scope }: { scope: ScopeState }) {
+  const w = scope.window;
+  const [custom, setCustom] = useState(w.kind === "range");
+  const [from, setFrom] = useState(w.from ?? "");
+  const [to, setTo] = useState(w.to ?? "");
+  useEffect(() => {
+    if (w.kind === "range") { setFrom(w.from ?? ""); setTo(w.to ?? ""); setCustom(true); }
+  }, [w.kind, w.from, w.to]);
+  const problem = rangeProblem(from, to);
+  const today = todayUtc();
+  return (
+    <div className="flex flex-wrap items-center gap-2">
+      <div role="group" aria-label="Window" className="inline-flex gap-1">
+        {DAY_PRESETS.map((d) => (
+          <Button key={d} type="button" size="sm" variant={w.kind === "days" && w.days === d && !custom ? "default" : "outline"} aria-pressed={w.kind === "days" && w.days === d && !custom} onClick={() => { setCustom(false); scope.setDays(d); }}>
+            {d === 365 ? "1 year" : `${d} days`}
+          </Button>
+        ))}
+        <Button type="button" size="sm" variant={custom ? "default" : "outline"} aria-pressed={custom} onClick={() => setCustom((c) => !c)}>Custom</Button>
+      </div>
+      {custom ? (
+        <div role="group" aria-label="Custom range" className="flex flex-wrap items-center gap-1.5">
+          <input type="date" aria-label="From day" className="h-8 rounded-md border bg-background px-2 text-sm" value={from} max={to || today} onChange={(e) => setFrom(e.target.value)} />
+          <span className="text-xs text-text-color-muted" aria-hidden>to</span>
+          <input type="date" aria-label="To day" className="h-8 rounded-md border bg-background px-2 text-sm" value={to} min={from || undefined} max={today} onChange={(e) => setTo(e.target.value)} />
+          <Button type="button" size="sm" disabled={problem !== null} onClick={() => scope.setRange(from, to)}>Apply range</Button>
+          {problem && (from || to) ? <span role="status" className={cn("text-xs", problem === "incomplete" ? "text-text-color-muted" : "text-error-foreground")}>{RANGE_PROBLEM_TEXT[problem]}</span> : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export function AnalyticsFilters({ scope, showWindow = true }: { scope: ScopeState; showWindow?: boolean }) {
+  const hidden = (scope.bots ? 1 : 0) + (scope.internal ? 1 : 0);
+  return (
+    <div className="flex flex-wrap items-center gap-2" data-testid="analytics-filters">
+      <SitePicker scope={scope} />
+      {showWindow ? <WindowPicker scope={scope} /> : <span className="text-xs text-text-color-muted">Realtime ignores the window</span>}
+      <MoreFilters activeCount={hidden} label="Traffic">
+        <label className="flex items-center gap-1.5 text-sm"><input type="checkbox" checked={scope.bots} onChange={(e) => scope.setBots(e.target.checked)} />Include bots and crawlers</label>
+        <label className="flex items-center gap-1.5 text-sm"><input type="checkbox" checked={scope.internal} onChange={(e) => scope.setInternal(e.target.checked)} />Include internal traffic</label>
+      </MoreFilters>
+    </div>
+  );
+}