@graph8/sdk 0.303.0 → 0.357.0

package/blocks/social-ads/recipes/sync-audience-and-launch.ts

@@ -0,0 +1,41 @@
+/**
+ * @title Sync a list to an ad platform and launch a campaign on it
+ * @when Retargeting or lookalike campaigns from a graph8 list. The ad account must already be connected in graph8
+ * (OAuth happens in the app only; the API cannot do it). Both steps are EXTERNAL: creating a sync sends the list's
+ * contacts to the platform, launching creates a campaign that spends from the ad account. Get a human to approve the
+ * list (and its size), the platform, the daily budget and the dates. Start and end are date-only: pass "YYYY-MM-DD".
+ * A 409 on create means that list is already synced to that platform: reuse the existing sync.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function syncList(audienceId: number, platform: "meta" | "linkedin" | "google" | "x") {
+  const res = await g8.api.audienceSyncs.createAudienceSync({ body: { audience_id: audienceId, platform, mode: "mirror", refresh_cadence_hours: 24 } });
+  return (res.data as { id: number }).id;
+}
+
+export async function pushNow(syncId: number) {
+  return g8.api.audienceSyncs.triggerAudienceSync({ path: { config_id: syncId } });
+}
+
+/**
+ * HTTP 200 does NOT mean launched: a refused launch answers 200 with `status: "error"` and a `message`. Check it.
+ * `currency` defaults to USD; Google needs `creative_image_url`.
+ */
+export async function launch(syncId: number, name: string, dailyBudget: number, destinationUrl: string, startDate: string, endDate?: string, currency = "USD") {
+  const res = await g8.api.adCampaigns.launchAdCampaign({
+    path: { config_id: syncId },
+    body: { name, daily_budget: dailyBudget, currency, destination_url: destinationUrl, start_date: startDate, ...(endDate ? { end_date: endDate } : {}) },
+  });
+  const body = res.data as { status?: string; message?: string };
+  if (body.status === "error" || body.status === "failed") throw new Error(body.message ?? "The platform refused the launch");
+  return res.data;
+}
+
+/** Results by campaign for the last `days`; join on `platform_campaign_id` (one sync can carry several campaigns, so `sync_config_id` alone would sum them). Spend is in each campaign's currency. */
+export async function results(days = 30) {
+  const [campaigns, metrics] = await Promise.all([g8.api.adCampaigns.listAdCampaigns(), g8.api.adCampaigns.getPerCampaignMetrics({ query: { days } })]);
+  const rows = ((metrics.data as { metrics?: Array<{ sync_config_id: number; platform_campaign_id?: string; impressions: number; clicks: number; spend: number }> }).metrics) ?? [];
+  return campaigns.data.map((c) => ({ id: c.id, name: c.name, status: c.status, metrics: rows.filter((m) => m.sync_config_id === c.sync_config_id && (!c.platform_campaign_id || m.platform_campaign_id === c.platform_campaign_id)) }));
+}

package/blocks/visitors/README.md

@@ -0,0 +1,56 @@
+# visitors
+
+See which companies and people visit your website, install the graph8 tracking snippet and prove it works,
+and chart traffic. The Apollo / 6sense "website visitors" screen.
+
+Depends on: `crm`. Install: `npx @graph8/sdk add visitors`.
+
+## Components
+
+| Component | What it does | Tiers |
+|---|---|---|
+| `VisitorFeed` | Polled feed of company visits (default) and identified people. Paging, refresh, bots excluded. | read |
+| `VisitorCompanyCard` | One visiting company with its page views; "Full journey" loads every page view. | read |
+| `SnippetInstall` | Streams picker, React and script-tag snippets with copy, and an install check that polls until events arrive. | read |
+| `TrafficChart` | Visitors, sessions or page views per day (inline SVG), top pages, "N on the site now". | read |
+
+Everything here is read tier: no confirmation dialog is needed. No component spends credits or contacts anyone.
+
+## The flow, in order
+
+1. **Get the snippet.** `SnippetInstall` -> `listOrgStreams` (the websites) -> `getOrgSnippet` with the chosen
+   `stream_id`. The `write_key` it returns is PUBLIC and goes in page source.
+2. **The human installs it** (paste into the site or the Next.js layout). This is the one step the agent cannot do.
+3. **Prove it.** "Check installation" polls `checkTrackingInstallation` with that `write_key` until
+   `status` is `receiving` (also `no_events`, `unknown`). It backs off and gives up after about 5 minutes.
+4. **Show visitors.** `VisitorFeed` -> `listCompanyVisitorEvents` (`show_mode=grouped`) and, on the People tab,
+   `listContactVisitorEvents`. Each grouped row's `COMPANY_ID` feeds the card's journey call
+   (`filter={"company_id": id}`, `show_mode=raw`).
+5. **Chart traffic.** `TrafficChart` -> `getAudienceTrend`, `getTopPages`, `getRealtime` (re-read every 10 s).
+
+## Prerequisites
+
+- Tracking snippet on the site (`where: "app"`). Verify: Check installation reports events received.
+- A website stream exists in the workspace (`where: "api"`): `GET /streams` is non-empty.
+- The People tab joins visits to contacts, so the API key also needs the contacts read scope.
+
+## Defaults (do not ask the human)
+
+- Poll the feed every 30 s; realtime every 10 s (there are no streams or sockets).
+- Companies tab first; bots and internal traffic excluded; 25 rows per page.
+- The org's main stream unless the person picks another.
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| `list_company_visitor_events_visitors_companies_events_get` | GET /visitors/companies/events | read | VisitorFeed, VisitorCompanyCard |
+| `list_contact_visitor_events_visitors_contacts_events_get` | GET /visitors/contacts/events | read | VisitorFeed |
+| `list_org_streams_streams_get` | GET /streams | read | SnippetInstall |
+| `get_org_snippet_snippet_get` | GET /snippet | read | SnippetInstall |
+| `check_tracking_installation_visitors_installation_check_get` | GET /visitors/installation-check | read | SnippetInstall |
+| `get_audience_trend_analytics_audience_trend_get` | GET /analytics/audience/trend | read | TrafficChart |
+| `get_realtime_analytics_realtime_get` | GET /analytics/realtime | read | TrafficChart |
+| `get_top_pages_analytics_behavior_pages_get` | GET /analytics/behavior/pages | read | TrafficChart |
+
+Recipes (`recipes/`): `check-snippet-installed.ts`, `recent-company-visits.ts`, `traffic-summary.ts`.

package/blocks/visitors/block.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "visitors",
+  "title": "Website visitors",
+  "summary": "See which companies and people visit your site, install the tracking snippet, and chart traffic.",
+  "features": [
+    "live-ish company and people visitor feed",
+    "company visit journey",
+    "tracking snippet with install check",
+    "traffic trend, realtime and top pages"
+  ],
+  "dependsOn": [
+    "crm"
+  ],
+  "operations": [
+    "list_company_visitor_events_visitors_companies_events_get",
+    "list_contact_visitor_events_visitors_contacts_events_get",
+    "list_org_streams_streams_get",
+    "get_org_snippet_snippet_get",
+    "check_tracking_installation_visitors_installation_check_get",
+    "get_audience_trend_analytics_audience_trend_get",
+    "get_realtime_analytics_realtime_get",
+    "get_top_pages_analytics_behavior_pages_get"
+  ],
+  "components": [
+    {
+      "name": "VisitorFeed",
+      "file": "components/visitor-feed.tsx",
+      "purpose": "Polled feed of company and identified-person visits with paging and refresh.",
+      "operations": [
+        "list_company_visitor_events_visitors_companies_events_get",
+        "list_contact_visitor_events_visitors_contacts_events_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "VisitorCompanyCard",
+      "file": "components/visitor-company-card.tsx",
+      "purpose": "One visiting company with its page views and an on-demand full journey.",
+      "operations": [
+        "list_company_visitor_events_visitors_companies_events_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "SnippetInstall",
+      "file": "components/snippet-install.tsx",
+      "purpose": "Show the React and script-tag snippets for a website stream and poll until events arrive.",
+      "operations": [
+        "list_org_streams_streams_get",
+        "get_org_snippet_snippet_get",
+        "check_tracking_installation_visitors_installation_check_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "TrafficChart",
+      "file": "components/traffic-chart.tsx",
+      "purpose": "Daily visitors, sessions and page views as an SVG line chart, with top pages and a realtime counter.",
+      "operations": [
+        "get_audience_trend_analytics_audience_trend_get",
+        "get_realtime_analytics_realtime_get",
+        "get_top_pages_analytics_behavior_pages_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    }
+  ],
+  "hooks": [],
+  "lib": [
+    {
+      "file": "lib/visitors-utils.ts",
+      "purpose": "Visitor event types, label and time helpers, and envelope readers shared by the components."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/check-snippet-installed.ts",
+      "title": "Fetch the tracking snippet and confirm events are arriving",
+      "when": "Onboarding a website."
+    },
+    {
+      "file": "recipes/recent-company-visits.ts",
+      "title": "List the companies that visited your site recently",
+      "when": "Building a who-is-on-our-site view or a daily digest."
+    },
+    {
+      "file": "recipes/traffic-summary.ts",
+      "title": "Summarise site traffic for the last N days",
+      "when": "A weekly report or dashboard header."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "snippet-on-site",
+      "description": "The graph8 tracking snippet is pasted into the website the visitors feed should watch.",
+      "where": "app",
+      "verify": "SnippetInstall's Check installation reports events received (GET /visitors/installation-check status is receiving)."
+    },
+    {
+      "id": "website-stream",
+      "description": "The workspace has at least one website stream (it gives the write key).",
+      "where": "api",
+      "verify": "GET /streams returns at least one stream."
+    }
+  ],
+  "scopes": [
+    "analytics:read",
+    "integrations:read",
+    "visitors:read"
+  ],
+  "defaults": [
+    {
+      "decision": "Visitor feed refresh",
+      "default": "Poll every 30 seconds (no streams exist)",
+      "askHuman": false
+    },
+    {
+      "decision": "Bots and internal traffic",
+      "default": "Excluded",
+      "askHuman": false
+    },
+    {
+      "decision": "Which website stream to show",
+      "default": "The org's main stream",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

package/blocks/visitors/components/snippet-install.tsx

@@ -0,0 +1,169 @@
+"use client";
+
+/**
+ * SnippetInstall: shows the tracking snippet for a website stream, then watches for the first events so
+ * the person knows the install worked.
+ *
+ * SDK operations, in order:
+ *   1. listOrgStreams          GET /streams                     (read; the org's websites and their write keys)
+ *   2. getOrgSnippet           GET /snippet?stream_id=          (read; write key + React and script-tag embeds)
+ *   3. checkTrackingInstallation GET /visitors/installation-check (read; polled until events arrive)
+ *
+ * Tiers: all read; no confirmation. The write key is the PUBLIC browser key, safe to ship in a page.
+ * Step 3 is a poll with backoff (there is no push): it stops at "receiving", or after about 5 minutes.
+ * The person must paste the snippet into their site (a `where: "app"` prerequisite) before step 3 can pass.
+ */
+
+import { useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+
+export interface SnippetInstallProps {
+  /** Pre-select a stream id (from listOrgStreams). Default: the org's main stream. */
+  streamId?: string;
+  /** Called once events are seen. */
+  onInstalled?: () => void;
+  className?: string;
+}
+
+interface Stream {
+  id: string;
+  name: string;
+  domains?: string[];
+  is_default?: boolean;
+}
+
+interface SnippetPayload {
+  write_key: string;
+  react_snippet: string;
+  script_tag: string;
+  stream_id?: string | null;
+  stream_name?: string | null;
+  warning?: string | null;
+  action_required?: boolean;
+}
+
+interface InstallStatus {
+  status: "receiving" | "no_events" | "unknown";
+  event_count: number;
+  last_event_at: string | null;
+}
+
+function CodeBlock({ label, code }: { label: string; code: string }) {
+  const [copied, setCopied] = useState(false);
+  const copy = async () => {
+    try {
+      await navigator.clipboard.writeText(code);
+      setCopied(true);
+    } catch {
+      setCopied(false);
+    }
+  };
+  return (
+    <div className="space-y-1">
+      <div className="flex items-center justify-between">
+        <span className="text-sm font-medium">{label}</span>
+        <Button size="sm" variant="outline" onClick={() => void copy()}>
+          {copied ? "Copied" : "Copy"}
+        </Button>
+      </div>
+      <pre className="overflow-x-auto rounded bg-gray-950 p-3 text-xs text-gray-100">
+        <code>{code}</code>
+      </pre>
+    </div>
+  );
+}
+
+function InstallCheck({ writeKey, onInstalled }: { writeKey: string; onInstalled?: () => void }) {
+  const check = useJobPoll<InstallStatus>(
+    async (signal) => (await g8Get<InstallStatus>("/visitors/installation-check", { write_key: writeKey }, { signal })).data,
+    {
+      isTerminal: (s) => s.status === "receiving" || s.status === "unknown",
+      enabled: false,
+      intervalMs: 5000,
+      maxIntervalMs: 15000,
+      maxAttempts: 25,
+      onDone: (s) => s.status === "receiving" && onInstalled?.(),
+    },
+  );
+  const s = check.status;
+  return (
+    <div className="space-y-2" aria-live="polite">
+      <Button onClick={check.start} disabled={check.polling}>
+        {check.polling ? "Waiting for the first visit..." : "Check installation"}
+      </Button>
+      {check.error ? <ApiError error={check.error} /> : null}
+      {s?.status === "receiving" ? (
+        <p role="status" className="text-sm text-green-700">
+          Installed: {s.event_count.toLocaleString()} events received.
+        </p>
+      ) : null}
+      {s?.status === "unknown" ? (
+        <p role="status" className="text-sm text-amber-700">
+          Your workspace cannot be probed yet. Open your site once and check the Visitors feed.
+        </p>
+      ) : null}
+      {s?.status === "no_events" && !check.polling ? (
+        <p role="status" className="text-sm text-gray-600">
+          No events yet. Load a page that has the snippet, then check again.
+        </p>
+      ) : null}
+      {s?.status === "no_events" && check.polling ? (
+        <p className="text-sm text-gray-600">No events yet. Open a page that has the snippet.</p>
+      ) : null}
+    </div>
+  );
+}
+
+export function SnippetInstall({ streamId, onInstalled, className }: SnippetInstallProps) {
+  const [selected, setSelected] = useState<string | undefined>(streamId);
+  const streams = useG8Query((signal) => g8Get<Stream[]>("/streams", { limit: 50 }, { signal }), []);
+  const snippet = useG8Query((signal) => g8Get<SnippetPayload>("/snippet", { stream_id: selected }, { signal }), [selected]);
+  const list = streams.data?.data ?? [];
+
+  if (snippet.error) return <ApiError error={snippet.error} onRetry={() => void snippet.refetch()} className={className} />;
+  if (snippet.loading && !snippet.data) return <Skeleton className={`h-40 w-full ${className ?? ""}`} />;
+  const s = snippet.data?.data;
+  if (!s)
+    return (
+      <EmptyState
+        title="No tracking stream yet"
+        description="Create a website stream in graph8 first, then come back for its snippet."
+        className={className}
+      />
+    );
+
+  return (
+    <div className={`space-y-4 ${className ?? ""}`}>
+      {list.length > 1 ? (
+        <label className="flex items-center gap-2 text-sm">
+          Website
+          <select
+            className="rounded border border-gray-300 px-2 py-1"
+            value={selected ?? s.stream_id ?? ""}
+            onChange={(e) => setSelected(e.target.value || undefined)}
+          >
+            {list.map((st) => (
+              <option key={st.id} value={st.id}>
+                {st.name}
+                {st.domains?.length ? ` (${st.domains[0]})` : ""}
+              </option>
+            ))}
+          </select>
+        </label>
+      ) : null}
+      {s.warning ? (
+        <p role="alert" className="rounded border border-amber-200 bg-amber-50 p-2 text-sm text-amber-900">
+          {s.warning}
+        </p>
+      ) : null}
+      <CodeBlock label="React / Next.js" code={s.react_snippet} />
+      <CodeBlock label="Any website (script tag)" code={s.script_tag} />
+      <InstallCheck key={s.write_key} writeKey={s.write_key} onInstalled={onInstalled} />
+    </div>
+  );
+}

package/blocks/visitors/components/traffic-chart.tsx

@@ -0,0 +1,156 @@
+"use client";
+
+/**
+ * TrafficChart: visitors, sessions and page views over time, with who is on the site right now and the
+ * pages they are on. Pure inline SVG, so it needs no chart library.
+ *
+ * SDK operations, in order:
+ *   1. getAudienceTrend  GET /analytics/audience/trend    (read; one row per day: users, sessions, page_views)
+ *   2. getRealtime       GET /analytics/realtime          (read; active users now, polled every 10 s)
+ *   3. getTopPages       GET /analytics/behavior/pages    (read; top pages by views)
+ *
+ * Tiers: all read; no confirmation. Realtime has no stream: the component re-reads every `realtimeSeconds`
+ * (default 10, the endpoint's cache TTL; 0 turns it off). Pass `writeKey` to scope to one website stream.
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { seriesOf } from "../lib/visitors-utils";
+
+export interface TrafficChartProps {
+  days?: number;
+  writeKey?: string;
+  realtimeSeconds?: number;
+  className?: string;
+}
+
+interface TrendPoint {
+  date: string;
+  users?: number;
+  new_users?: number;
+  sessions?: number;
+  page_views?: number;
+}
+
+interface PageRow {
+  page_path?: string;
+  path?: string;
+  url?: string;
+  page_title?: string;
+  views?: number;
+  page_views?: number;
+  unique_visitors?: number;
+}
+
+type Metric = "users" | "sessions" | "page_views";
+const METRICS: Array<{ key: Metric; label: string }> = [
+  { key: "users", label: "Visitors" },
+  { key: "sessions", label: "Sessions" },
+  { key: "page_views", label: "Page views" },
+];
+
+export function LineChart({ points, metric }: { points: TrendPoint[]; metric: Metric }) {
+  const width = 600;
+  const height = 160;
+  const values = points.map((p) => p[metric] ?? 0);
+  const max = Math.max(1, ...values);
+  const x = (i: number) => (points.length <= 1 ? width / 2 : (i / (points.length - 1)) * width);
+  const y = (v: number) => height - (v / max) * (height - 12) - 6;
+  const path = values.map((v, i) => `${i === 0 ? "M" : "L"}${x(i).toFixed(1)},${y(v).toFixed(1)}`).join(" ");
+  return (
+    <svg viewBox={`0 0 ${width} ${height}`} role="img" aria-label={`${metric} per day`} className="h-40 w-full text-blue-600">
+      <path d={path} fill="none" stroke="currentColor" strokeWidth="2" />
+      {values.map((v, i) => (
+        <circle key={points[i].date} cx={x(i)} cy={y(v)} r="2.5" fill="currentColor">
+          <title>{`${points[i].date}: ${v}`}</title>
+        </circle>
+      ))}
+    </svg>
+  );
+}
+
+function activeNow(envelope: unknown): number | undefined {
+  const data = (envelope as { data?: Record<string, unknown> } | null)?.data;
+  const value = data?.active_users_5min ?? data?.active_5min ?? data?.active_users ?? data?.five_min ?? data?.active_now;
+  return typeof value === "number" ? value : undefined;
+}
+
+export function TrafficChart({ days = 30, writeKey, realtimeSeconds = 10, className }: TrafficChartProps) {
+  const [metric, setMetric] = useState<Metric>("users");
+  const scope = { days, write_key: writeKey };
+  const trend = useG8Query((signal) => g8Get("/analytics/audience/trend", scope, { signal }), [days, writeKey]);
+  const pages = useG8Query((signal) => g8Get("/analytics/behavior/pages", { ...scope, limit: 8 }, { signal }), [days, writeKey]);
+  const live = useG8Query((signal) => g8Get("/analytics/realtime", { write_key: writeKey }, { signal }), [writeKey]);
+
+  useEffect(() => {
+    if (!realtimeSeconds) return;
+    const timer = setInterval(() => void live.refetch(), realtimeSeconds * 1000);
+    return () => clearInterval(timer);
+  }, [realtimeSeconds, live.refetch]);
+
+  const points = seriesOf<TrendPoint>(trend.data);
+  const topPages = seriesOf<PageRow>(pages.data);
+  const total = points.reduce((sum, p) => sum + (p[metric] ?? 0), 0);
+  const now = activeNow(live.data);
+
+  return (
+    <div className={`space-y-4 ${className ?? ""}`}>
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <div className="inline-flex gap-1" role="group" aria-label="Metric">
+          {METRICS.map((m) => (
+            <Button
+              key={m.key}
+              size="sm"
+              variant={metric === m.key ? "default" : "outline"}
+              aria-pressed={metric === m.key}
+              onClick={() => setMetric(m.key)}
+            >
+              {m.label}
+            </Button>
+          ))}
+        </div>
+        <p className="text-sm text-gray-600" aria-live="polite">
+          {now != null ? `${now} on the site now` : ""}
+        </p>
+      </div>
+
+      {trend.error ? (
+        <ApiError error={trend.error} onRetry={() => void trend.refetch()} />
+      ) : trend.loading && !trend.data ? (
+        <Skeleton className="h-40 w-full" />
+      ) : points.length === 0 ? (
+        <EmptyState title="No traffic yet" description="Install the snippet and visits will chart here." />
+      ) : (
+        <div>
+          <p className="text-sm text-gray-600">
+            {total.toLocaleString()} {METRICS.find((m) => m.key === metric)?.label.toLowerCase()} in {days} days
+          </p>
+          <LineChart points={points} metric={metric} />
+        </div>
+      )}
+
+      {topPages.length > 0 ? (
+        <table className="w-full text-sm">
+          <thead>
+            <tr className="text-left text-gray-500">
+              <th className="py-1">Top pages</th>
+              <th className="py-1 text-right">Views</th>
+            </tr>
+          </thead>
+          <tbody>
+            {topPages.map((p, i) => (
+              <tr key={i} className="border-t">
+                <td className="py-1">{p.page_path ?? p.path ?? p.url ?? p.page_title ?? "-"}</td>
+                <td className="py-1 text-right">{(p.views ?? p.page_views ?? 0).toLocaleString()}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      ) : null}
+    </div>
+  );
+}

package/blocks/visitors/components/visitor-company-card.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+/**
+ * VisitorCompanyCard: one company that visited your site, with the pages it viewed and, on request,
+ * its full journey.
+ *
+ * SDK operations, in order:
+ *   1. listCompanyVisitorEvents  GET /visitors/companies/events  (read; only when "Full journey" is clicked,
+ *      with filter={"company_id": <id>} and show_mode=raw)
+ *
+ * Tiers: read only; no confirmation. Pass a grouped visit from `VisitorFeed` (or any
+ * `/visitors/companies/events?show_mode=grouped` row) as `visit`. `actions` slot: put your own buttons
+ * ("Add to list", "Open company") next to the name.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, Skeleton } from "@graph8/sdk/ui";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { ApiError } from "@/g8/components/api-error";
+import { companyLabel, pageLabel, pageOf, timeAgo } from "../lib/visitors-utils";
+import type { FlowEvent, VisitorGroup } from "../lib/visitors-utils";
+
+export interface VisitorCompanyCardProps {
+  visit: VisitorGroup;
+  /** Pages shown before "Full journey". Default 5. */
+  previewPages?: number;
+  actions?: ReactNode;
+  className?: string;
+}
+
+function PageList({ pages }: { pages: FlowEvent[] }) {
+  if (pages.length === 0) return <p className="text-sm text-gray-500">No page views recorded.</p>;
+  return (
+    <ol className="space-y-1 text-sm">
+      {pages.map((p, i) => (
+        <li key={p.message_id ?? `${p.received_at}-${i}`} className="flex justify-between gap-3">
+          <span className="truncate">
+            {pageLabel(p)}
+            {p.page_referrer ? <span className="ml-2 text-xs text-gray-400">from {p.page_referrer}</span> : null}
+          </span>
+          <span className="shrink-0 text-xs text-gray-500">{timeAgo(p.received_at)}</span>
+        </li>
+      ))}
+    </ol>
+  );
+}
+
+function Journey({ companyId }: { companyId: number }) {
+  const journey = useG8Query(
+    (signal) =>
+      g8Get("/visitors/companies/events", { show_mode: "raw", filter: JSON.stringify({ company_id: companyId }), limit: 100 }, { signal }),
+    [companyId],
+  );
+  if (journey.loading) return <Skeleton className="h-16 w-full" />;
+  if (journey.error) return <ApiError error={journey.error} onRetry={() => void journey.refetch()} />;
+  // Raw mode returns one row per page view.
+  const views = pageOf(journey.data).events as unknown as FlowEvent[];
+  return <PageList pages={views} />;
+}
+
+export function VisitorCompanyCard({ visit, previewPages = 5, actions, className }: VisitorCompanyCardProps) {
+  const [showJourney, setShowJourney] = useState(false);
+  const pages = visit.children ?? [];
+  return (
+    <Card className={className} data-testid="visitor-company-card">
+      <CardHeader className="flex flex-row items-start justify-between gap-3">
+        <div>
+          <CardTitle className="text-base">{companyLabel(visit)}</CardTitle>
+          <p className="text-xs text-gray-500">
+            {visit.COMPANY_DOMAIN ? `${visit.COMPANY_DOMAIN} - ` : ""}last seen {timeAgo(visit.received_at)} - {pages.length} page view
+            {pages.length === 1 ? "" : "s"}
+          </p>
+        </div>
+        {actions ? <div className="flex gap-2">{actions}</div> : null}
+      </CardHeader>
+      <CardContent className="space-y-3">
+        {showJourney && visit.COMPANY_ID != null ? (
+          <Journey companyId={visit.COMPANY_ID} />
+        ) : (
+          <PageList pages={pages.slice(0, previewPages)} />
+        )}
+        {visit.COMPANY_ID != null ? (
+          <Button variant="link" size="sm" className="px-0" onClick={() => setShowJourney((v) => !v)}>
+            {showJourney ? "Show summary" : "Full journey"}
+          </Button>
+        ) : null}
+      </CardContent>
+    </Card>
+  );
+}