@graph8/sdk 0.303.0 → 0.357.0

package/blocks/visitors/components/visitor-feed.tsx

@@ -0,0 +1,157 @@
+"use client";
+
+/**
+ * VisitorFeed: who is on your site. Companies by default (identified from the visit), people when the
+ * visitor is a known contact. It is a polled feed: the API has no stream, so it reloads on a timer.
+ *
+ * SDK operations, in order:
+ *   1. listCompanyVisitorEvents  GET /visitors/companies/events  (read; show_mode=grouped)
+ *   2. listContactVisitorEvents  GET /visitors/contacts/events   (read; People tab, needs contacts:read too)
+ *
+ * Tiers: read only; no confirmation. Bots and internal traffic are excluded unless you pass
+ * `includeBots` / `includeInternal`. Poll interval: `pollSeconds` (default 30, 0 turns it off).
+ */
+
+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 { VisitorCompanyCard } from "./visitor-company-card";
+import { pageOf, personLabel, pageLabel, timeAgo } from "../lib/visitors-utils";
+import type { VisitorGroup } from "../lib/visitors-utils";
+
+export interface VisitorFeedProps {
+  pageSize?: number;
+  pollSeconds?: number;
+  includeBots?: boolean;
+  includeInternal?: boolean;
+  /** Which tab to open on. Default "companies". */
+  initialView?: "companies" | "people";
+  onSelectPerson?: (visit: VisitorGroup) => void;
+  className?: string;
+}
+
+type View = "companies" | "people";
+
+export function VisitorFeed({
+  pageSize = 25,
+  pollSeconds = 30,
+  includeBots = false,
+  includeInternal = false,
+  initialView = "companies",
+  onSelectPerson,
+  className,
+}: VisitorFeedProps) {
+  const [view, setView] = useState<View>(initialView);
+  // The page belongs to one set of inputs: a different tab, page size or bot/internal filter starts at page 1.
+  const scope = `${view}|${pageSize}|${includeBots}|${includeInternal}`;
+  const [pageState, setPageState] = useState({ scope, n: 1 });
+  const page = pageState.scope === scope ? pageState.n : 1;
+  const setPage = (update: number | ((p: number) => number)) =>
+    setPageState({ scope, n: typeof update === "function" ? update(page) : update });
+  const rawFeed = useG8Query(
+    async (signal) => ({
+      view,
+      res: await g8Get(
+        view === "companies" ? "/visitors/companies/events" : "/visitors/contacts/events",
+        { show_mode: "grouped", page, limit: pageSize, include_bots: includeBots, include_internal: includeInternal },
+        { signal },
+      ),
+    }),
+    [view, page, pageSize, includeBots, includeInternal],
+  );
+  // Rows fetched for the other tab must never render under this one (companies would show as "Unknown visitor").
+  const feed = { ...rawFeed, data: rawFeed.data?.view === view ? rawFeed.data.res : undefined };
+
+  useEffect(() => {
+    if (!pollSeconds) return;
+    const timer = setInterval(() => void feed.refetch(), pollSeconds * 1000);
+    return () => clearInterval(timer);
+  }, [pollSeconds, feed.refetch]);
+
+  const { events, total } = pageOf(feed.data);
+  const switchTo = (next: View) => {
+    setView(next);
+    setPage(1);
+  };
+
+  return (
+    <div className={`space-y-3 ${className ?? ""}`}>
+      <div className="flex items-center justify-between">
+        <div className="inline-flex gap-1" role="group" aria-label="Visitor type">
+          <Button
+            size="sm"
+            variant={view === "companies" ? "default" : "outline"}
+            aria-pressed={view === "companies"}
+            onClick={() => switchTo("companies")}
+          >
+            Companies
+          </Button>
+          <Button
+            size="sm"
+            variant={view === "people" ? "default" : "outline"}
+            aria-pressed={view === "people"}
+            onClick={() => switchTo("people")}
+          >
+            People
+          </Button>
+        </div>
+        <Button size="sm" variant="outline" disabled={feed.loading} onClick={() => void feed.refetch()}>
+          Refresh
+        </Button>
+      </div>
+
+      {feed.error ? (
+        <ApiError error={feed.error} onRetry={() => void feed.refetch()} />
+      ) : feed.loading && !feed.data ? (
+        <div className="space-y-2">
+          <Skeleton className="h-20 w-full" />
+          <Skeleton className="h-20 w-full" />
+        </div>
+      ) : events.length === 0 ? (
+        <EmptyState
+          title={view === "companies" ? "No company visits yet" : "No identified people yet"}
+          description="Visits appear once the graph8 snippet is on your site. Check the install in SnippetInstall."
+        />
+      ) : view === "companies" ? (
+        <div className="space-y-3">
+          {events.map((visit, i) => (
+            <VisitorCompanyCard key={`${visit.COMPANY_ID}-${visit.received_at}-${i}`} visit={visit} />
+          ))}
+        </div>
+      ) : (
+        <ul className="divide-y rounded border border-gray-200">
+          {events.map((visit, i) => (
+            <li key={`${visit.CONTACT_ID}-${visit.received_at}-${i}`}>
+              <button
+                type="button"
+                className="flex w-full items-center justify-between px-3 py-2 text-left text-sm hover:bg-gray-50"
+                onClick={() => onSelectPerson?.(visit)}
+              >
+                <span>
+                  <span className="font-medium">{personLabel(visit)}</span>
+                  <span className="ml-2 text-xs text-gray-500">{visit.children?.[0] ? pageLabel(visit.children[0]) : ""}</span>
+                </span>
+                <span className="text-xs text-gray-500">{timeAgo(visit.received_at)}</span>
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <div className="flex items-center justify-between text-sm text-gray-600">
+        <span>{total.toLocaleString()} visits</span>
+        <div className="flex gap-2">
+          <Button size="sm" variant="outline" disabled={page <= 1 || feed.loading} onClick={() => setPage((p) => p - 1)}>
+            Previous
+          </Button>
+          <Button size="sm" variant="outline" disabled={feed.loading || page * pageSize >= total} onClick={() => setPage((p) => p + 1)}>
+            Next
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/blocks/visitors/lib/visitors-utils.ts

@@ -0,0 +1,78 @@
+"use client";
+
+/**
+ * Types and helpers shared by the visitors components. Visitor payloads are open-shaped: the tracker adds
+ * fields over time and each feed carries a different set, so every field here is optional and the readers
+ * accept the upper-case names the grouped feeds use as well as lower-case ones.
+ */
+
+/** One page view inside a visit. */
+export interface FlowEvent {
+  message_id?: string;
+  received_at?: string;
+  page_title?: string | null;
+  page_path?: string | null;
+  page_host?: string | null;
+  page_referrer?: string | null;
+  sequence_name?: string | null;
+}
+
+/** A grouped company visit (`show_mode=grouped`) or a grouped person visit. */
+export interface VisitorGroup {
+  COMPANY_ID?: number;
+  COMPANY_NAME?: string | null;
+  COMPANY_DOMAIN?: string | null;
+  CONTACT_ID?: number;
+  CONTACT_FIRST_NAME?: string | null;
+  CONTACT_LAST_NAME?: string | null;
+  received_at?: string;
+  children?: FlowEvent[];
+}
+
+export interface EventPage {
+  events: VisitorGroup[];
+  total: number;
+}
+
+/** `{ data: { events, total } }` -> the page, tolerating a missing body. */
+export function pageOf(envelope: unknown): EventPage {
+  const data = (envelope as { data?: { events?: VisitorGroup[]; total?: number } } | null)?.data;
+  const events = data?.events ?? [];
+  return { events, total: data?.total ?? events.length };
+}
+
+export function companyLabel(g: VisitorGroup): string {
+  return g.COMPANY_NAME || g.COMPANY_DOMAIN || (g.COMPANY_ID != null ? `Company ${g.COMPANY_ID}` : "Unknown company");
+}
+
+export function personLabel(g: VisitorGroup): string {
+  const name = [g.CONTACT_FIRST_NAME, g.CONTACT_LAST_NAME].filter(Boolean).join(" ").trim();
+  return name || (g.CONTACT_ID != null ? `Contact ${g.CONTACT_ID}` : "Unknown visitor");
+}
+
+/** "3 min ago", "2 h ago", or a date for older visits. */
+export function timeAgo(value: string | null | undefined, now = Date.now()): string {
+  if (!value) return "-";
+  const then = new Date(value).getTime();
+  if (Number.isNaN(then)) return value;
+  const minutes = Math.max(0, Math.round((now - then) / 60000));
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes} min ago`;
+  if (minutes < 60 * 24) return `${Math.round(minutes / 60)} h ago`;
+  return new Date(then).toLocaleDateString();
+}
+
+export function pageLabel(e: FlowEvent): string {
+  return e.page_title || e.page_path || e.page_host || "page";
+}
+
+/** Rows out of an analytics response (`data` array, `data.rows`/`items`, or a bare array). */
+export function seriesOf<T>(envelope: unknown): T[] {
+  const data = (envelope as { data?: unknown } | null)?.data ?? envelope;
+  if (Array.isArray(data)) return data as T[];
+  const obj = data as Record<string, unknown> | null | undefined;
+  for (const key of ["rows", "items", "trend", "pages", "data"]) {
+    if (Array.isArray(obj?.[key])) return obj![key] as T[];
+  }
+  return [];
+}

package/blocks/visitors/recipes/check-snippet-installed.ts

@@ -0,0 +1,24 @@
+/**
+ * @title Fetch the tracking snippet and confirm events are arriving
+ * @when Onboarding a website. The snippet's write key is PUBLIC (safe in page source). Installation is
+ * proven by events arriving, not by the page containing the tag, so poll `checkTrackingInstallation` after
+ * a human has loaded a page that has the snippet. Read tier, free.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function getSnippetAndWait(streamId?: string, attempts = 12) {
+  const snippet = await g8.api.snippet.getOrgSnippet({ query: { stream_id: streamId } });
+  const writeKey = snippet.data?.write_key;
+  if (!writeKey) throw new Error("No tracking stream: create a website stream in graph8 first");
+  console.log("Paste this into the site:\n", snippet.data?.script_tag);
+
+  for (let i = 0; i < attempts; i++) {
+    const check = await g8.api.visitors.checkTrackingInstallation({ query: { write_key: writeKey } });
+    const status = (check.data as { status?: string } | undefined)?.status;
+    if (status === "receiving") return { installed: true as const, writeKey };
+    await new Promise((resolve) => setTimeout(resolve, Math.min(15000, 3000 * 1.5 ** i)));
+  }
+  return { installed: false as const, writeKey };
+}

package/blocks/visitors/recipes/recent-company-visits.ts

@@ -0,0 +1,27 @@
+/**
+ * @title List the companies that visited your site recently
+ * @when Building a "who is on our site" view or a daily digest. `show_mode: "grouped"` returns one row per
+ * company with its page views under `children`. Bots and internal traffic are excluded by default. Read tier.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+interface CompanyVisit {
+  COMPANY_ID?: number;
+  COMPANY_NAME?: string | null;
+  COMPANY_DOMAIN?: string | null;
+  received_at?: string;
+  children?: Array<{ page_path?: string | null }>;
+}
+
+export async function recentCompanyVisits(limit = 25) {
+  const res = await g8.api.visitors.listCompanyVisitorEvents({ query: { show_mode: "grouped", limit, page: 1 } });
+  const events = ((res.data as { events?: CompanyVisit[] } | undefined)?.events ?? []).map((v) => ({
+    companyId: v.COMPANY_ID,
+    name: v.COMPANY_NAME ?? v.COMPANY_DOMAIN,
+    lastSeen: v.received_at,
+    pages: (v.children ?? []).map((c) => c.page_path),
+  }));
+  return events;
+}

package/blocks/visitors/recipes/traffic-summary.ts

@@ -0,0 +1,24 @@
+/**
+ * @title Summarise site traffic for the last N days
+ * @when A weekly report or a dashboard header. Three reads (no spend): the daily trend, the top pages and
+ * who is on the site right now. Pass a stream's write key to scope to one website.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function trafficSummary(days = 7, writeKey?: string) {
+  const scope = { days, write_key: writeKey };
+  const [trend, pages, live] = await Promise.all([
+    g8.api.webAnalytics.getAudienceTrend({ query: scope }),
+    g8.api.webAnalytics.getTopPages({ query: { ...scope, limit: 10 } }),
+    g8.api.webAnalytics.getRealtime({ query: { write_key: writeKey } }),
+  ]);
+  const rows = (trend.data as Array<{ date: string; users?: number; page_views?: number }> | undefined) ?? [];
+  return {
+    visitors: rows.reduce((sum, r) => sum + (r.users ?? 0), 0),
+    pageViews: rows.reduce((sum, r) => sum + (r.page_views ?? 0), 0),
+    topPages: pages.data,
+    liveNow: live.data,
+  };
+}

package/blocks/webchat/README.md

@@ -0,0 +1,87 @@
+# webchat
+
+Configure the AI chat widget on your website and see who used it. `ChatWidgetConfig` manages chat bots, the widget's
+look, starter questions and the embed code; `ConversationList` shows the widget's visitors and the engagement funnel.
+Message threads and replies live in the `inbox` block.
+
+## Install
+
+```
+npx @graph8/sdk add webchat
+```
+
+Installs `foundation` and `crm` first if missing. Everything lands under `g8/webchat/`.
+
+## Prerequisites (the human must do these)
+
+| Where | What | How to verify |
+|---|---|---|
+| Your site | Load the graph8 tracking snippet on the pages that should show the chat; the widget ships through it (`ChatWidgetConfig` displays the code). | The launcher appears on a page with the snippet. |
+| graph8 workspace | An **answering agent** mapped to the bot. A bot with none answers nothing. | `GET /api/v1/webchat/agents?chat_bot_id=` lists an active agent. |
+| Your app | `allowedPrefixes` must include `webchat` and `snippet`. | The route file lists both. |
+
+## The flow, in order (IDs passed between steps)
+
+1. `listChatBots` -> **`bot.id`**. This is the `chat_bot_id` of nearly every other call. `createChatBot({ name })` makes one.
+2. `getWebchatSettings(chat_bot_id, surface)` -> the current theme. A `404` means the bot has none yet: `createWebchatSettings` (POST, one row per bot and surface, `409` if it exists). Otherwise `updateWebchatSettings` (PATCH, partial).
+   **Saves are live**: the next visitor sees them, there is no publish step. Colours must be hex, sizes CSS lengths; an illegible text/background pair is a 422.
+3. `listWebchatQuestions(chat_bot_id)`, `createWebchatQuestion`, `deleteWebchatQuestion` (confirmed; pass `expected_revision` when you have it).
+4. `getOrgSnippet` -> `script_tag` to paste on your pages.
+5. `ConversationList`: `listWebchatVisitors` (paged, `identified_only`, `search`) and `getWebchatVisitorFunnel`.
+
+```tsx
+// app/chat/page.tsx
+"use client";
+import { ChatWidgetConfig } from "@/g8/webchat/components/chat-widget-config";
+import { ConversationList } from "@/g8/webchat/components/conversation-list";
+
+export default function Page() {
+  return (<><ChatWidgetConfig /><ConversationList /></>);
+}
+```
+
+## Default decisions (do not ask the human unless marked)
+
+| Decision | Default | Ask? |
+|---|---|---|
+| Surface to style | `external` (public website) | no |
+| First bot shown | The default bot, else the first | no |
+| Colours | Leave unset unless the brand colours are known | **yes** |
+| Saving | Live immediately; style a new bot before production pages load the snippet | no |
+
+## Things that surprise people
+
+- **No conversations endpoint here.** Webchat has visitors and a funnel; the actual messages are inbox threads.
+- **Responses are passed through and only partly typed.** The visitor columns (name, email, company, last seen) are read from whichever of several keys is present.
+- **`abandonment_window_minutes` on the funnel is not applied by the API yet**, and `answer_feedback` / `conversation_abandoned` stages are absent rather than zero. Do not build on them.
+- **Deleting settings** (`deleteWebchatSettings`) reverts to defaults, which every visitor sees at once. The block does not expose it.
+
+## Recipes (server-side, `recipes/`)
+
+- `create-bot-and-style-widget.ts`: bot, theme, starter questions.
+- `list-chat-visitors.ts`: identified visitors and the funnel.
+
+## What is in the block
+
+| Component | File | What it is |
+|---|---|---|
+| `ChatWidgetConfig` | `components/chat-widget-config.tsx` | Pick or create a chat bot, style its widget, manage starter questions and copy the embed code. |
+| `ConversationList` | `components/conversation-list.tsx` | People who used the widget, identified where possible, with the engagement funnel counts. |
+
+## Operations
+
+Tiers: `read` and `write` need no confirmation; `destructive` always opens `ConfirmSpendDialog` first.
+
+| Operation | Method and path | Tier | Scope | Used by |
+|---|---|---|---|---|
+| `webChat.listChatBots` | `GET /api/v1/webchat/chat-bots` | read | `inbox:read` | ChatWidgetConfig |
+| `webChat.createChatBot` | `POST /api/v1/webchat/chat-bots` | write | `inbox:write` | ChatWidgetConfig |
+| `webChat.getWebchatSettings` | `GET /api/v1/webchat/settings` | read | `inbox:read` | ChatWidgetConfig |
+| `webChat.createWebchatSettings` | `POST /api/v1/webchat/settings` | write | `inbox:write` | ChatWidgetConfig |
+| `webChat.updateWebchatSettings` | `PATCH /api/v1/webchat/settings` | write | `inbox:write` | ChatWidgetConfig |
+| `webChat.listWebchatQuestions` | `GET /api/v1/webchat/questions` | read | `inbox:read` | ChatWidgetConfig |
+| `webChat.createWebchatQuestion` | `POST /api/v1/webchat/questions` | write | `inbox:write` | ChatWidgetConfig |
+| `webChat.deleteWebchatQuestion` | `DELETE /api/v1/webchat/questions/{question_id}` | destructive | `inbox:delete` | ChatWidgetConfig |
+| `snippet.getOrgSnippet` | `GET /api/v1/snippet` | read | `integrations:read` | ChatWidgetConfig |
+| `webChat.listWebchatVisitors` | `GET /api/v1/webchat/visitors` | read | `inbox:read` | ConversationList |
+| `webChat.getWebchatVisitorFunnel` | `GET /api/v1/webchat/visitors/funnel` | read | `inbox:read` | ConversationList |

package/blocks/webchat/block.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "webchat",
+  "title": "Web chat",
+  "summary": "Configure the website chat widget (bots, styling, starter questions, embed code) and see who used it.",
+  "features": [
+    "chat bots with a default",
+    "live widget styling with validation",
+    "starter questions",
+    "embed code from the tracking snippet",
+    "chat visitors list and engagement funnel"
+  ],
+  "dependsOn": [
+    "crm"
+  ],
+  "operations": [
+    "list_chat_bots_webchat_chat_bots_get",
+    "create_chat_bot_webchat_chat_bots_post",
+    "get_webchat_settings_webchat_settings_get",
+    "create_webchat_settings_webchat_settings_post",
+    "update_webchat_settings_webchat_settings_patch",
+    "list_webchat_questions_webchat_questions_get",
+    "create_webchat_question_webchat_questions_post",
+    "delete_webchat_question_webchat_questions__question_id__delete",
+    "get_org_snippet_snippet_get",
+    "list_webchat_visitors_webchat_visitors_get",
+    "get_webchat_visitor_funnel_webchat_visitors_funnel_get"
+  ],
+  "components": [
+    {
+      "name": "ChatWidgetConfig",
+      "file": "components/chat-widget-config.tsx",
+      "purpose": "Pick or create a chat bot, style its widget, manage starter questions and copy the embed code.",
+      "operations": [
+        "list_chat_bots_webchat_chat_bots_get",
+        "create_chat_bot_webchat_chat_bots_post",
+        "get_webchat_settings_webchat_settings_get",
+        "create_webchat_settings_webchat_settings_post",
+        "update_webchat_settings_webchat_settings_patch",
+        "list_webchat_questions_webchat_questions_get",
+        "create_webchat_question_webchat_questions_post",
+        "delete_webchat_question_webchat_questions__question_id__delete",
+        "get_org_snippet_snippet_get"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "ConversationList",
+      "file": "components/conversation-list.tsx",
+      "purpose": "People who used the widget, identified where possible, with the engagement funnel counts.",
+      "operations": [
+        "list_webchat_visitors_webchat_visitors_get",
+        "get_webchat_visitor_funnel_webchat_visitors_funnel_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    }
+  ],
+  "hooks": [],
+  "lib": [
+    {
+      "file": "lib/webchat-types.ts",
+      "purpose": "Bot, settings, question and visitor types with tolerant readers and colour/length validators."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/create-bot-and-style-widget.ts",
+      "title": "Create a chat bot, style its widget, add starter questions",
+      "when": "First-time chat setup."
+    },
+    {
+      "file": "recipes/list-chat-visitors.ts",
+      "title": "List identified chat visitors and the funnel",
+      "when": "A daily pull of people who chatted, to route hot ones to sales."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "snippet-on-site",
+      "description": "The graph8 tracking snippet must load on the pages that should show the chat; the widget ships through it. ChatWidgetConfig shows the code, a human or the agent pastes it into the site.",
+      "where": "app",
+      "verify": "The widget launcher appears on a page that loads the snippet."
+    },
+    {
+      "id": "answering-agent",
+      "description": "A chat bot answers nothing until an answering agent is mapped to it (POST /webchat/agents, or in the graph8 app). Build or pick the agent with the agents block or the app.",
+      "where": "api",
+      "verify": "GET /api/v1/webchat/agents?chat_bot_id= lists an active agent."
+    },
+    {
+      "id": "proxy-allowlist",
+      "description": "Add \"webchat\" and \"snippet\" to allowedPrefixes in app/api/g8/[...path]/route.ts.",
+      "where": "app",
+      "verify": "The route file's allowedPrefixes contains both."
+    }
+  ],
+  "scopes": [
+    "inbox:delete",
+    "inbox:read",
+    "inbox:write",
+    "integrations:read"
+  ],
+  "defaults": [
+    {
+      "decision": "Which surface to style",
+      "default": "external (the public website widget)",
+      "askHuman": false
+    },
+    {
+      "decision": "Which bot to open first",
+      "default": "The default bot, else the first",
+      "askHuman": false
+    },
+    {
+      "decision": "Widget colours",
+      "default": "Leave unset (graph8 defaults) unless the brand colours are known",
+      "askHuman": true
+    },
+    {
+      "decision": "Saving widget settings",
+      "default": "Saves are live immediately; style a new bot before production pages load the snippet",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}