@m13v/seo-components 0.6.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m13v/seo-components",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "39 animated React components for programmatic SEO pages. Remotion video, Magic UI style animations, trust signals, JSON-LD helpers. Teal/cyan brand, light-theme only.",
   "type": "module",
   "main": "./src/index.ts",
@@ -43,11 +43,19 @@
     "framer-motion": ">=11",
     "remotion": ">=4",
     "@remotion/player": ">=4",
-    "lottie-react": ">=2"
+    "lottie-react": ">=2",
+    "@google/generative-ai": ">=0.24",
+    "@supabase/supabase-js": ">=2",
+    "@assistant-ui/react": ">=0.7",
+    "posthog-js": ">=1.100"
   },
   "peerDependenciesMeta": {
     "remotion": { "optional": true },
     "@remotion/player": { "optional": true },
-    "lottie-react": { "optional": true }
+    "lottie-react": { "optional": true },
+    "@google/generative-ai": { "optional": true },
+    "@supabase/supabase-js": { "optional": true },
+    "@assistant-ui/react": { "optional": true },
+    "posthog-js": { "optional": true }
   }
 }

package/src/components/GuideChatPanel.tsx

@@ -0,0 +1,541 @@
+"use client";
+
+import {
+  AssistantRuntimeProvider,
+  ComposerPrimitive,
+  MessagePrimitive,
+  ThreadPrimitive,
+  useLocalRuntime,
+  useThreadRuntime,
+  type ChatModelAdapter,
+} from "@assistant-ui/react";
+import { usePathname } from "next/navigation";
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+/* ------------------------------------------------------------------ */
+/*  PostHog helper (works with any posthog setup on window or global)  */
+/* ------------------------------------------------------------------ */
+
+function capture(event: string, props?: Record<string, unknown>) {
+  const w = typeof window !== "undefined" ? (window as unknown as Record<string, unknown>) : null;
+  const ph = w?.posthog as
+    | { capture?: (e: string, p?: Record<string, unknown>) => void; __loaded?: boolean }
+    | undefined;
+  ph?.capture?.(event, props);
+}
+
+function onPosthogLoaded(fn: () => void) {
+  if (typeof window === "undefined") return;
+  const w = window as unknown as Record<string, unknown>;
+  const ph = w.posthog as { __loaded?: boolean } | undefined;
+  if (ph?.__loaded) {
+    fn();
+  } else {
+    window.addEventListener("posthog:loaded", fn, { once: true });
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/*  Slug extraction                                                    */
+/* ------------------------------------------------------------------ */
+
+function slugFromPath(pathname: string | null, pattern?: RegExp): string {
+  if (!pathname) return "";
+  const re = pattern ?? /^\/t\/([^/]+)/;
+  const m = pathname.match(re);
+  return m ? m[1] : "";
+}
+
+/* ------------------------------------------------------------------ */
+/*  Chat adapter                                                       */
+/* ------------------------------------------------------------------ */
+
+function makeAdapter(
+  getSlug: () => string,
+  apiEndpoint: string,
+  app: string,
+): ChatModelAdapter {
+  return {
+    async *run({ messages, abortSignal }) {
+      const slug = getSlug();
+      const lastUserMsg = messages[messages.length - 1];
+      const userQuery =
+        lastUserMsg?.content
+          .map((p) => (p.type === "text" ? p.text : ""))
+          .join("") ?? "";
+
+      const payload = {
+        slug,
+        messages: messages.map((m) => ({
+          role: m.role === "assistant" ? "assistant" : "user",
+          content: m.content
+            .map((p) => (p.type === "text" ? p.text : ""))
+            .join(""),
+        })),
+      };
+
+      capture("guide_chat_message_sent", {
+        app,
+        slug,
+        query: userQuery,
+        query_length: userQuery.length,
+        message_count: messages.length,
+      });
+
+      const startedAt = Date.now();
+      const res = await fetch(apiEndpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(payload),
+        signal: abortSignal,
+      });
+
+      if (!res.ok || !res.body) {
+        const errText = await res.text().catch(() => "");
+        capture("guide_chat_response_failed", {
+          app,
+          slug,
+          query: userQuery,
+          status: res.status,
+          error: errText || "no body",
+          latency_ms: Date.now() - startedAt,
+        });
+        throw new Error(`guide-chat ${res.status}: ${errText || "no body"}`);
+      }
+
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buf = "";
+      let accumulated = "";
+      let toolRounds = 0;
+      let inputTokens = 0;
+      let outputTokens = 0;
+      let model = "";
+      let requestId = "";
+
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        const lines = buf.split("\n");
+        buf = lines.pop() ?? "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+          try {
+            const evt = JSON.parse(trimmed) as
+              | { type: "delta"; text: string }
+              | {
+                  type: "done";
+                  usage: { inputTokens?: number; outputTokens?: number };
+                  requestId: string;
+                  toolRounds?: number;
+                  model?: string;
+                }
+              | { type: "error"; error: string };
+            if (evt.type === "delta") {
+              accumulated += evt.text;
+              yield { content: [{ type: "text", text: accumulated }] };
+            } else if (evt.type === "done") {
+              toolRounds = evt.toolRounds ?? 0;
+              inputTokens = evt.usage?.inputTokens ?? 0;
+              outputTokens = evt.usage?.outputTokens ?? 0;
+              model = evt.model ?? "";
+              requestId = evt.requestId ?? "";
+            } else if (evt.type === "error") {
+              throw new Error(evt.error);
+            }
+          } catch {
+            // ignore malformed line
+          }
+        }
+      }
+
+      capture("guide_chat_response_received", {
+        app,
+        slug,
+        query: userQuery,
+        response: accumulated,
+        response_length: accumulated.length,
+        latency_ms: Date.now() - startedAt,
+        tool_rounds: toolRounds,
+        input_tokens: inputTokens,
+        output_tokens: outputTokens,
+        model,
+        request_id: requestId,
+      });
+
+      yield {
+        content: [{ type: "text", text: accumulated }],
+        status: { type: "complete", reason: "stop" },
+      };
+    },
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/*  Summary hook                                                       */
+/* ------------------------------------------------------------------ */
+
+interface SummaryData {
+  text: string | null;
+  questions: string[];
+  loading: boolean;
+  slug: string;
+}
+
+function useSummary(
+  slug: string,
+  apiEndpoint: string,
+  app: string,
+): SummaryData {
+  const [text, setText] = useState<string | null>(null);
+  const [questions, setQuestions] = useState<string[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    if (!slug) {
+      setLoading(false);
+      return;
+    }
+    setLoading(true);
+    setText(null);
+    setQuestions([]);
+
+    const ac = new AbortController();
+    const startedAt = Date.now();
+
+    (async () => {
+      try {
+        const res = await fetch(apiEndpoint, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            slug,
+            messages: [
+              {
+                role: "user",
+                content:
+                  "Briefly summarize what this article covers and what the reader will learn from it in 2-3 sentences. Focus on the article's content and key takeaways, not on describing the product itself. Then write a line containing only three dashes (---). Then list exactly 3 follow-up questions a reader of this article might ask, one per line.",
+              },
+            ],
+          }),
+          signal: ac.signal,
+        });
+
+        if (!res.ok || !res.body) {
+          setLoading(false);
+          return;
+        }
+
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = "";
+        let accumulated = "";
+
+        while (true) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          buf += decoder.decode(value, { stream: true });
+          const lines = buf.split("\n");
+          buf = lines.pop() ?? "";
+          for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed) continue;
+            try {
+              const evt = JSON.parse(trimmed) as
+                | { type: "delta"; text: string }
+                | { type: "done" }
+                | { type: "error" };
+              if (evt.type === "delta") accumulated += evt.text;
+            } catch {
+              /* skip */
+            }
+          }
+        }
+
+        const halves = accumulated.split("---");
+        const summaryText = halves[0].trim();
+        const qRaw = halves.slice(1).join("---").trim();
+        const qs = qRaw
+          .split("\n")
+          .map((l) =>
+            l
+              .replace(/^\d+[\.\)]\s*/, "")
+              .replace(/^\*+\s*/, "")
+              .replace(/\*+$/, "")
+              .trim(),
+          )
+          .filter((l) => l.length > 10)
+          .slice(0, 3);
+
+        setText(summaryText || null);
+        setQuestions(qs);
+
+        capture("guide_chat_summary_loaded", {
+          app,
+          slug,
+          summary: summaryText || "",
+          summary_length: summaryText.length,
+          questions: qs,
+          question_count: qs.length,
+          latency_ms: Date.now() - startedAt,
+        });
+      } catch (e) {
+        if ((e as Error).name !== "AbortError") {
+          console.error("[guide-chat] summary fetch:", e);
+        }
+      } finally {
+        setLoading(false);
+      }
+    })();
+
+    return () => ac.abort();
+  }, [slug, apiEndpoint, app]);
+
+  return { text, questions, loading, slug };
+}
+
+/* ------------------------------------------------------------------ */
+/*  Public API                                                         */
+/* ------------------------------------------------------------------ */
+
+export interface GuideChatPanelProps {
+  /** App identifier for analytics (e.g. "cyrano") */
+  app?: string;
+  /** API endpoint for the guide chat. Defaults to "/api/guide-chat" */
+  apiEndpoint?: string;
+  /** Regex to extract slug from pathname. Must have one capture group. Defaults to /^\\/t\\/([^/]+)/ */
+  slugPattern?: RegExp;
+  /** Panel header label. Defaults to "page assistant" */
+  label?: string;
+}
+
+export function GuideChatPanel({
+  app = "default",
+  apiEndpoint = "/api/guide-chat",
+  slugPattern,
+  label = "page assistant",
+}: GuideChatPanelProps) {
+  const pathname = usePathname();
+  const slug = slugFromPath(pathname, slugPattern);
+
+  useEffect(() => {
+    if (!slug) return;
+    onPosthogLoaded(() =>
+      capture("guide_chat_panel_viewed", { app, slug }),
+    );
+  }, [slug, app]);
+
+  if (!slug) return null;
+
+  return (
+    <aside className="hidden lg:flex flex-col sticky top-0 h-screen w-80 xl:w-96 bg-white border-l border-zinc-200">
+      <div className="flex items-center gap-2 px-4 py-3 border-b border-zinc-100">
+        <span className="w-1.5 h-1.5 rounded-full bg-teal-500 inline-block" />
+        <span className="font-mono text-xs tracking-tight text-zinc-900">
+          {label}
+        </span>
+      </div>
+      <ChatThread
+        key={slug}
+        slug={slug}
+        apiEndpoint={apiEndpoint}
+        app={app}
+      />
+    </aside>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  Chat thread                                                        */
+/* ------------------------------------------------------------------ */
+
+function ChatThread({
+  slug,
+  apiEndpoint,
+  app,
+}: {
+  slug: string;
+  apiEndpoint: string;
+  app: string;
+}) {
+  const adapter = useMemo(
+    () => makeAdapter(() => slug, apiEndpoint, app),
+    [slug, apiEndpoint, app],
+  );
+  const runtime = useLocalRuntime(adapter);
+  const summary = useSummary(slug, apiEndpoint, app);
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <ThreadPrimitive.Root className="flex-1 flex flex-col min-h-0">
+        <ThreadPrimitive.Viewport className="flex-1 overflow-y-auto px-4 py-4">
+          <SummarySection summary={summary} app={app} />
+          <ThreadPrimitive.Messages
+            components={{ UserMessage, AssistantMessage }}
+          />
+          <ThreadPrimitive.If running>
+            <TypingIndicator />
+          </ThreadPrimitive.If>
+        </ThreadPrimitive.Viewport>
+        <div className="px-3 py-3 border-t border-zinc-100">
+          <Composer />
+        </div>
+      </ThreadPrimitive.Root>
+    </AssistantRuntimeProvider>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  Summary + question chips                                           */
+/* ------------------------------------------------------------------ */
+
+function SummarySection({
+  summary,
+  app,
+}: {
+  summary: SummaryData;
+  app: string;
+}) {
+  if (summary.loading) {
+    return (
+      <div className="mb-4 space-y-2 animate-pulse">
+        <div className="h-3 bg-zinc-100 rounded w-3/4" />
+        <div className="h-3 bg-zinc-100 rounded w-full" />
+        <div className="h-3 bg-zinc-100 rounded w-5/6" />
+        <div className="mt-3 h-8 bg-zinc-50 rounded w-full" />
+        <div className="h-8 bg-zinc-50 rounded w-full" />
+        <div className="h-8 bg-zinc-50 rounded w-full" />
+      </div>
+    );
+  }
+
+  if (!summary.text) return null;
+
+  return (
+    <div className="mb-4 space-y-3">
+      <div className="rounded-lg px-3 py-2.5 bg-zinc-50 border border-zinc-100 text-[13px] text-zinc-900 font-mono leading-relaxed whitespace-pre-wrap">
+        {summary.text}
+      </div>
+      {summary.questions.length > 0 && (
+        <QuestionChips
+          questions={summary.questions}
+          slug={summary.slug}
+          app={app}
+        />
+      )}
+    </div>
+  );
+}
+
+function QuestionChips({
+  questions,
+  slug,
+  app,
+}: {
+  questions: string[];
+  slug: string;
+  app: string;
+}) {
+  const threadRuntime = useThreadRuntime();
+
+  const send = useCallback(
+    (q: string, index: number) => {
+      capture("guide_chat_question_chip_clicked", {
+        app,
+        slug,
+        question: q,
+        chip_index: index,
+        question_count: questions.length,
+      });
+      threadRuntime.append({
+        role: "user",
+        content: [{ type: "text" as const, text: q }],
+      });
+    },
+    [threadRuntime, slug, app, questions.length],
+  );
+
+  return (
+    <div className="space-y-1.5">
+      {questions.map((q, i) => (
+        <button
+          key={i}
+          onClick={() => send(q, i)}
+          className="w-full text-left px-3 py-2 rounded-lg border border-zinc-200 bg-white hover:border-teal-300 hover:text-teal-700 transition-colors text-[12px] font-mono text-zinc-600 leading-snug"
+        >
+          {q}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  Chat primitives                                                    */
+/* ------------------------------------------------------------------ */
+
+function UserMessage() {
+  return (
+    <MessagePrimitive.Root className="mb-3 flex justify-end">
+      <div className="max-w-[85%] rounded-lg px-3 py-2 bg-teal-50 border border-teal-100 text-[13px] text-zinc-900 font-mono whitespace-pre-wrap">
+        <MessagePrimitive.Parts />
+      </div>
+    </MessagePrimitive.Root>
+  );
+}
+
+function AssistantMessage() {
+  return (
+    <MessagePrimitive.Root className="mb-3 flex justify-start">
+      <div className="max-w-[90%] rounded-lg px-3 py-2 bg-zinc-50 border border-zinc-100 text-[13px] text-zinc-900 font-mono leading-relaxed whitespace-pre-wrap">
+        <MessagePrimitive.Parts />
+      </div>
+    </MessagePrimitive.Root>
+  );
+}
+
+function TypingIndicator() {
+  return (
+    <div className="mb-3 flex justify-start">
+      <div className="rounded-lg px-3 py-2 bg-zinc-50 border border-zinc-100 text-[13px] text-zinc-400 font-mono">
+        <span className="inline-flex gap-1">
+          <span className="w-1 h-1 bg-zinc-400 rounded-full animate-pulse" />
+          <span className="w-1 h-1 bg-zinc-400 rounded-full animate-pulse [animation-delay:150ms]" />
+          <span className="w-1 h-1 bg-zinc-400 rounded-full animate-pulse [animation-delay:300ms]" />
+        </span>
+      </div>
+    </div>
+  );
+}
+
+function Composer() {
+  return (
+    <ComposerPrimitive.Root className="flex items-end gap-2 rounded-lg border border-zinc-200 bg-white focus-within:border-teal-300 focus-within:ring-2 focus-within:ring-teal-500/20 transition">
+      <ComposerPrimitive.Input
+        placeholder="ask a question..."
+        className="flex-1 bg-transparent px-3 py-2 text-[13px] font-mono text-zinc-900 placeholder:text-zinc-400 focus:outline-none resize-none max-h-32"
+        rows={1}
+      />
+      <ComposerPrimitive.Send
+        className="m-1 p-1.5 rounded-md bg-teal-600 text-white hover:bg-teal-700 disabled:bg-zinc-300 disabled:cursor-not-allowed transition-colors"
+        aria-label="Send"
+      >
+        <svg
+          width="14"
+          height="14"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <line x1="22" y1="2" x2="11" y2="13" />
+          <polygon points="22 2 15 22 11 13 2 9 22 2" />
+        </svg>
+      </ComposerPrimitive.Send>
+    </ComposerPrimitive.Root>
+  );
+}

package/src/index.ts

@@ -54,6 +54,20 @@ export { MotionSequence } from "./components/MotionSequence";
 export { RemotionClip, ConceptReveal } from "./components/RemotionClip";
 export { LottiePlayer } from "./components/LottiePlayer";
 
+// Guide chat (AI page assistant)
+export { GuideChatPanel } from "./components/GuideChatPanel";
+export type { GuideChatPanelProps } from "./components/GuideChatPanel";
+
+// Guide chat server utilities (import via @seo/components/lib/*)
+export { createGuideChatHandler } from "./lib/guide-chat-route";
+export type { GuideChatConfig } from "./lib/guide-chat-route";
+export { logAiUsage, computeCostUsd } from "./lib/ai-usage";
+export type { LogAiUsageArgs } from "./lib/ai-usage";
+export { discoverGuides } from "./lib/discover-guides";
+export type { GuideEntry } from "./lib/discover-guides";
+export { getGuideContext, buildGuideIndex, buildSystemPrompt } from "./lib/guide-context";
+export type { GuideContext, BuildSystemPromptOptions } from "./lib/guide-context";
+
 // Magic UI style components
 export { Marquee } from "./components/Marquee";
 export { AnimatedBeam } from "./components/AnimatedBeam";

package/src/lib/ai-usage.ts

@@ -0,0 +1,54 @@
+import { getSupabaseAdmin } from "./supabase-admin";
+
+const PRICING_USD_PER_MTOK: Record<string, { input: number; output: number }> = {
+  "gemini-flash-latest":  { input: 0.30, output: 2.50 },
+  "gemini-2.5-flash":     { input: 0.30, output: 2.50 },
+  "gemini-pro-latest":    { input: 1.25, output: 10.00 },
+};
+
+function pricing(model: string) {
+  return PRICING_USD_PER_MTOK[model] ?? { input: 0, output: 0 };
+}
+
+export function computeCostUsd(
+  model: string,
+  inputTokens: number,
+  outputTokens: number,
+): number {
+  const p = pricing(model);
+  const cost = (inputTokens * p.input + outputTokens * p.output) / 1_000_000;
+  return Math.round(cost * 1_000_000) / 1_000_000;
+}
+
+export interface LogAiUsageArgs {
+  app: string;
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens?: number;
+  requestId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export async function logAiUsage(args: LogAiUsageArgs): Promise<void> {
+  const total = args.totalTokens ?? args.inputTokens + args.outputTokens;
+  const cost = computeCostUsd(args.model, args.inputTokens, args.outputTokens);
+  try {
+    const supabase = getSupabaseAdmin();
+    const { error } = await supabase.from("ai_usage").insert({
+      app: args.app,
+      model: args.model,
+      input_tokens: args.inputTokens,
+      output_tokens: args.outputTokens,
+      total_tokens: total,
+      cost_usd: cost,
+      request_id: args.requestId ?? null,
+      metadata: args.metadata ?? null,
+    });
+    if (error) {
+      console.error("[ai-usage] insert failed:", error.message);
+    }
+  } catch (e) {
+    console.error("[ai-usage] unexpected error:", e);
+  }
+}

package/src/lib/discover-guides.ts

@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const TITLE_RE = /const\s+TITLE\s*=\s*"([^"]+)"/;
+const DESC_RE = /const\s+DESCRIPTION\s*=\s*"([^"]+)"/;
+const DATE_RE = /const\s+DATE_PUBLISHED\s*=\s*"([^"]+)"/;
+const H2_RE = /<h2\b[^>]*>([\s\S]*?)<\/h2>/g;
+
+export interface GuideEntry {
+  slug: string;
+  title: string;
+  description: string;
+  datePublished: string;
+  sections: { id: string; title: string }[];
+  hasFaq: boolean;
+}
+
+let cachedDir: string | null = null;
+let cachedGuides: GuideEntry[] | null = null;
+
+export function discoverGuides(contentDir?: string): GuideEntry[] {
+  const dir = contentDir ?? path.join(process.cwd(), "src/app/(content)/t");
+
+  if (cachedDir === dir && cachedGuides) return cachedGuides;
+
+  if (!fs.existsSync(dir)) return [];
+
+  const slugs = fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !d.name.startsWith("["))
+    .map((d) => d.name);
+
+  const guides: GuideEntry[] = [];
+  for (const slug of slugs) {
+    const pagePath = path.join(dir, slug, "page.tsx");
+    let src: string;
+    try {
+      src = fs.readFileSync(pagePath, "utf-8");
+    } catch {
+      continue;
+    }
+
+    const title = src.match(TITLE_RE)?.[1] ?? "";
+    const description = src.match(DESC_RE)?.[1] ?? "";
+    const datePublished = src.match(DATE_RE)?.[1] ?? "";
+    if (!title) continue;
+
+    const sections: { id: string; title: string }[] = [];
+    let m: RegExpExecArray | null;
+    while ((m = H2_RE.exec(src)) !== null) {
+      const raw = m[1].replace(/<[^>]+>/g, "").trim();
+      if (raw) {
+        const id = raw
+          .toLowerCase()
+          .replace(/[^a-z0-9]+/g, "-")
+          .replace(/^-|-$/g, "");
+        sections.push({ id, title: raw });
+      }
+    }
+
+    guides.push({
+      slug,
+      title,
+      description,
+      datePublished,
+      sections,
+      hasFaq: /<FaqSection\b/.test(src),
+    });
+  }
+
+  guides.sort(
+    (a, b) =>
+      (b.datePublished || "").localeCompare(a.datePublished || "") ||
+      a.title.localeCompare(b.title),
+  );
+
+  cachedDir = dir;
+  cachedGuides = guides;
+  return guides;
+}

package/src/lib/guide-chat-route.ts

@@ -0,0 +1,351 @@
+import { NextRequest } from "next/server";
+import {
+  GoogleGenerativeAI,
+  SchemaType,
+  type FunctionDeclaration,
+  type FunctionDeclarationsTool,
+  type Part,
+} from "@google/generative-ai";
+import {
+  buildSystemPrompt,
+  getGuideContext,
+  buildGuideIndex,
+} from "./guide-context";
+import { discoverGuides } from "./discover-guides";
+import { logAiUsage } from "./ai-usage";
+
+const MODEL_ID = "gemini-flash-latest";
+const MAX_TOOL_ROUNDS = 3;
+const RATE_LIMIT_MAX = 20;
+const RATE_LIMIT_WINDOW_MS = 60 * 60 * 1000;
+
+const ipHits = new Map<string, number[]>();
+
+function ratelimit(ip: string): { ok: boolean; remaining: number } {
+  const now = Date.now();
+  const hits = (ipHits.get(ip) ?? []).filter(
+    (t) => now - t < RATE_LIMIT_WINDOW_MS,
+  );
+  if (hits.length >= RATE_LIMIT_MAX) {
+    ipHits.set(ip, hits);
+    return { ok: false, remaining: 0 };
+  }
+  hits.push(now);
+  ipHits.set(ip, hits);
+  return { ok: true, remaining: RATE_LIMIT_MAX - hits.length };
+}
+
+/* ------------------------------------------------------------------ */
+/*  Tool declarations                                                  */
+/* ------------------------------------------------------------------ */
+
+function buildToolDeclarations(brand: string): FunctionDeclarationsTool[] {
+  const getGuideContentDecl: FunctionDeclaration = {
+    name: "get_guide_content",
+    description: `Load the full text content of any guide page on the ${brand} site by its slug. Use this when the visitor asks about a topic covered in another guide, or when you need to cross-reference information.`,
+    parameters: {
+      type: SchemaType.OBJECT,
+      properties: {
+        slug: {
+          type: SchemaType.STRING,
+          description:
+            "The guide slug (e.g. 'some-topic'). See the guide index in the system prompt for available slugs.",
+        },
+      },
+      required: ["slug"],
+    },
+  };
+
+  const searchGuidesDecl: FunctionDeclaration = {
+    name: "search_guides",
+    description:
+      "Search across all guide pages for a keyword or topic. Returns matching guide titles and the sections that mention the query. Use this when you need to find which guide covers a specific topic.",
+    parameters: {
+      type: SchemaType.OBJECT,
+      properties: {
+        query: {
+          type: SchemaType.STRING,
+          description: "The search term or topic to find across guides.",
+        },
+      },
+      required: ["query"],
+    },
+  };
+
+  return [{ functionDeclarations: [getGuideContentDecl, searchGuidesDecl] }];
+}
+
+/* ------------------------------------------------------------------ */
+/*  Tool execution                                                     */
+/* ------------------------------------------------------------------ */
+
+function executeGetGuideContent(
+  args: { slug: string },
+  contentDir: string,
+): Record<string, unknown> {
+  const ctx = getGuideContext(args.slug, contentDir);
+  if (!ctx) {
+    return {
+      error: `Guide "${args.slug}" not found. Check the guide index for valid slugs.`,
+    };
+  }
+  return {
+    slug: ctx.slug,
+    title: ctx.title,
+    description: ctx.description,
+    sections: ctx.sections.map((s) => s.title),
+    content: ctx.body,
+  };
+}
+
+function executeSearchGuides(
+  args: { query: string },
+  contentDir: string,
+): Record<string, unknown> {
+  const query = args.query.toLowerCase();
+  const guides = discoverGuides(contentDir);
+  const results: { slug: string; title: string; matchingSections: string[] }[] =
+    [];
+
+  for (const g of guides) {
+    const titleMatch = g.title.toLowerCase().includes(query);
+    const descMatch = g.description.toLowerCase().includes(query);
+    const matchingSections = g.sections
+      .filter((s) => s.title.toLowerCase().includes(query))
+      .map((s) => s.title);
+
+    if (titleMatch || descMatch || matchingSections.length > 0) {
+      results.push({ slug: g.slug, title: g.title, matchingSections });
+    }
+  }
+
+  if (results.length === 0) {
+    return {
+      results: [],
+      message: `No guides found matching "${args.query}". Try a broader term.`,
+    };
+  }
+  return { results };
+}
+
+function executeTool(
+  name: string,
+  args: Record<string, unknown>,
+  contentDir: string,
+): Record<string, unknown> {
+  switch (name) {
+    case "get_guide_content":
+      return executeGetGuideContent(args as { slug: string }, contentDir);
+    case "search_guides":
+      return executeSearchGuides(args as { query: string }, contentDir);
+    default:
+      return { error: `Unknown tool: ${name}` };
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/*  Config & factory                                                   */
+/* ------------------------------------------------------------------ */
+
+export interface GuideChatConfig {
+  /** App identifier for token accounting (e.g. "cyrano", "pieline") */
+  app: string;
+  /** Brand name shown in system prompt (e.g. "Cyrano", "PieLine") */
+  brand: string;
+  /** Short site description for system prompt context */
+  siteDescription?: string;
+  /** Path to content directory relative to project root. Defaults to "src/app/t" */
+  contentDir?: string;
+}
+
+interface ChatMessage {
+  role: "user" | "assistant";
+  content: string;
+}
+
+export function createGuideChatHandler(config: GuideChatConfig) {
+  const {
+    app,
+    brand,
+    siteDescription,
+    contentDir: relDir,
+  } = config;
+
+  const contentDir = relDir
+    ? `${process.cwd()}/${relDir}`
+    : `${process.cwd()}/src/app/t`;
+
+  return async function POST(req: NextRequest) {
+    const ip =
+      req.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ||
+      req.headers.get("x-real-ip") ||
+      "unknown";
+
+    const rl = ratelimit(ip);
+    if (!rl.ok) {
+      return new Response(
+        JSON.stringify({ error: "rate_limit_exceeded", retry_after_minutes: 60 }),
+        { status: 429, headers: { "content-type": "application/json" } },
+      );
+    }
+
+    let body: { messages?: ChatMessage[]; slug?: string };
+    try {
+      body = await req.json();
+    } catch {
+      return new Response(JSON.stringify({ error: "invalid_json" }), {
+        status: 400,
+        headers: { "content-type": "application/json" },
+      });
+    }
+
+    const messages = Array.isArray(body.messages) ? body.messages : [];
+    const slug = typeof body.slug === "string" ? body.slug : "";
+
+    if (messages.length === 0) {
+      return new Response(JSON.stringify({ error: "no_messages" }), {
+        status: 400,
+        headers: { "content-type": "application/json" },
+      });
+    }
+
+    const ctx = slug ? getGuideContext(slug, contentDir) : null;
+    const systemPrompt = ctx
+      ? buildSystemPrompt({ ctx, brand, siteDescription, contentDir })
+      : `You are an assistant for the ${brand} website. Help the user with general questions.\n\nAll guides on this site:\n${buildGuideIndex(contentDir)}`;
+
+    const apiKey = process.env.GEMINI_API_KEY;
+    if (!apiKey) {
+      return new Response(JSON.stringify({ error: "missing_gemini_key" }), {
+        status: 500,
+        headers: { "content-type": "application/json" },
+      });
+    }
+
+    const requestId = crypto.randomUUID();
+    const tools = buildToolDeclarations(brand);
+
+    const genAI = new GoogleGenerativeAI(apiKey);
+    const model = genAI.getGenerativeModel({
+      model: MODEL_ID,
+      systemInstruction: systemPrompt,
+      tools,
+    });
+
+    const history = messages.slice(0, -1).map((m) => ({
+      role: m.role === "assistant" ? ("model" as const) : ("user" as const),
+      parts: [{ text: m.content }],
+    }));
+    const lastUser = messages[messages.length - 1];
+    const chat = model.startChat({ history });
+
+    let toolRounds = 0;
+    let currentRequest: string | Part[] = lastUser.content;
+    let finalText: string | null = null;
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+
+    while (toolRounds <= MAX_TOOL_ROUNDS) {
+      let result;
+      try {
+        result = await chat.sendMessage(currentRequest);
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        console.error(`[guide-chat:${app}] gemini error:`, msg);
+        return new Response(
+          JSON.stringify({ error: "gemini_failed", detail: msg }),
+          { status: 502, headers: { "content-type": "application/json" } },
+        );
+      }
+
+      const response = result.response;
+      const fnCalls = response.functionCalls();
+
+      if (!fnCalls || fnCalls.length === 0) {
+        finalText = response.text();
+
+        const usage = response.usageMetadata;
+        const inputTokens = usage?.promptTokenCount ?? 0;
+        const outputTokens = usage?.candidatesTokenCount ?? 0;
+        totalInputTokens += inputTokens;
+        totalOutputTokens += outputTokens;
+        const totalTokens =
+          usage?.totalTokenCount ?? inputTokens + outputTokens;
+
+        logAiUsage({
+          app,
+          model: MODEL_ID,
+          inputTokens,
+          outputTokens,
+          totalTokens,
+          requestId,
+          metadata: {
+            feature: "guide-chat",
+            slug: slug || null,
+            ip,
+            toolRounds,
+          },
+        }).catch((err) =>
+          console.error(`[guide-chat:${app}] logAiUsage:`, err),
+        );
+
+        break;
+      }
+
+      const functionResponses: Part[] = fnCalls.map((fc) => ({
+        functionResponse: {
+          name: fc.name,
+          response: executeTool(
+            fc.name,
+            fc.args as Record<string, unknown>,
+            contentDir,
+          ),
+        },
+      }));
+
+      currentRequest = functionResponses;
+      toolRounds++;
+    }
+
+    if (finalText === null) {
+      return new Response(
+        JSON.stringify({ error: "max_tool_rounds_exceeded" }),
+        { status: 502, headers: { "content-type": "application/json" } },
+      );
+    }
+
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+      start(controller) {
+        controller.enqueue(
+          encoder.encode(
+            JSON.stringify({ type: "delta", text: finalText }) + "\n",
+          ),
+        );
+        controller.enqueue(
+          encoder.encode(
+            JSON.stringify({
+              type: "done",
+              usage: {
+                inputTokens: totalInputTokens,
+                outputTokens: totalOutputTokens,
+              },
+              requestId,
+              toolRounds,
+              model: MODEL_ID,
+            }) + "\n",
+          ),
+        );
+        controller.close();
+      },
+    });
+
+    return new Response(stream, {
+      headers: {
+        "content-type": "application/x-ndjson; charset=utf-8",
+        "cache-control": "no-store",
+        "x-request-id": requestId,
+      },
+    });
+  };
+}

package/src/lib/guide-context.ts

@@ -0,0 +1,112 @@
+import fs from "node:fs";
+import path from "node:path";
+import { discoverGuides, type GuideEntry } from "./discover-guides";
+
+export interface GuideContext {
+  slug: string;
+  title: string;
+  description: string;
+  datePublished: string;
+  sections: { id: string; title: string }[];
+  body: string;
+}
+
+export function getGuideContext(
+  slug: string,
+  contentDir?: string,
+): GuideContext | null {
+  const dir = contentDir ?? path.join(process.cwd(), "src/app/(content)/t");
+  const guide = discoverGuides(dir).find((g) => g.slug === slug);
+  if (!guide) return null;
+
+  const pagePath = path.join(dir, slug, "page.tsx");
+  let rawSource = "";
+  try {
+    rawSource = fs.readFileSync(pagePath, "utf-8");
+  } catch {
+    return null;
+  }
+
+  const body = extractReadableText(rawSource).slice(0, 12_000);
+  return {
+    slug: guide.slug,
+    title: guide.title,
+    description: guide.description,
+    datePublished: guide.datePublished,
+    sections: guide.sections,
+    body,
+  };
+}
+
+function extractReadableText(src: string): string {
+  const lines = src.split("\n");
+  const out: string[] = [];
+  let depth = 0;
+  let inReturn = false;
+  for (const line of lines) {
+    if (!inReturn && /return\s*\(/.test(line)) {
+      inReturn = true;
+    }
+    if (!inReturn) continue;
+    depth += (line.match(/\(/g) || []).length;
+    depth -= (line.match(/\)/g) || []).length;
+    out.push(line);
+    if (inReturn && depth <= 0) break;
+  }
+  const jsx = out.join("\n");
+  return jsx
+    .replace(/<[^>]+>/g, " ")
+    .replace(/\{[^{}]*\}/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function buildGuideIndex(contentDir?: string): string {
+  const guides = discoverGuides(contentDir);
+  if (guides.length === 0) return "No guides available.";
+  return guides
+    .map((g) => {
+      const sections = g.sections.map((s) => s.title).join(", ");
+      return `- slug: "${g.slug}" | title: "${g.title}" | sections: [${sections}]`;
+    })
+    .join("\n");
+}
+
+export interface BuildSystemPromptOptions {
+  ctx: GuideContext;
+  brand: string;
+  siteDescription?: string;
+  contentDir?: string;
+}
+
+export function buildSystemPrompt(opts: BuildSystemPromptOptions): string {
+  const { ctx, brand, siteDescription, contentDir } = opts;
+  const sectionList = ctx.sections.map((s) => `- ${s.title}`).join("\n");
+  const guideIndex = buildGuideIndex(contentDir);
+
+  return [
+    `You are an assistant embedded in the ${brand} website.`,
+    siteDescription ? `Site context: ${siteDescription}` : "",
+    "The visitor is reading a specific article (guide page). Your job is to help them understand the article they are reading.",
+    "",
+    "IMPORTANT: When summarizing or answering, focus on what the ARTICLE covers and what the reader will learn from it. Do NOT just describe the product. Describe the article's content, structure, and key takeaways.",
+    "",
+    "Ground answers in the provided page content. If the question is outside the page, use the get_guide_content tool to look up other pages, or say so briefly and answer from general knowledge.",
+    "Keep answers concise and use plain text. No markdown headings. Inline code is fine.",
+    "",
+    `CURRENT ARTICLE: "${ctx.title}"`,
+    `Slug: ${ctx.slug}`,
+    ctx.description ? `Description: ${ctx.description}` : "",
+    "",
+    "Sections in this article:",
+    sectionList,
+    "",
+    "Article content (trimmed):",
+    ctx.body,
+    "",
+    "ALL GUIDES ON THIS SITE (use get_guide_content tool to read any of them):",
+    guideIndex,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}

package/src/lib/supabase-admin.ts

@@ -0,0 +1,15 @@
+import { createClient, type SupabaseClient } from "@supabase/supabase-js";
+
+let cached: SupabaseClient | null = null;
+
+export function getSupabaseAdmin(): SupabaseClient {
+  if (cached) return cached;
+  const url = process.env.NEXT_PUBLIC_SUPABASE_URL;
+  const key = process.env.SUPABASE_SERVICE_KEY;
+  if (!url) throw new Error("Missing env.NEXT_PUBLIC_SUPABASE_URL");
+  if (!key) throw new Error("Missing env.SUPABASE_SERVICE_KEY");
+  cached = createClient(url, key, {
+    auth: { persistSession: false, autoRefreshToken: false },
+  });
+  return cached;
+}