@m13v/seo-components 0.20.1 → 0.22.1

package/README.md

@@ -110,6 +110,8 @@ import { walkPages, createGuideChatHandler, logAiUsage } from "@seo/components/s
 | Export | What it does |
 |--------|-------------|
 | `walkPages()` | Discovers all pages in `src/app/`, extracts titles, descriptions, H2 sections |
+| `generateSitemap()` | Returns a `MetadataRoute.Sitemap` by walking `src/app` with priority tiers |
+| `generateRobots()` | Returns a `MetadataRoute.Robots` with default + AI-crawler allowlist + sitemap URL |
 | `createGuideChatHandler()` | Gemini streaming chat route handler |
 | `discoverGuides()` | Legacy guide discovery (delegates to `walkPages`) |
 | `getGuideContext()` | Builds page context for AI chat |
@@ -117,6 +119,48 @@ import { walkPages, createGuideChatHandler, logAiUsage } from "@seo/components/s
 | `getSupabaseAdmin()` | Supabase admin client |
 | `slugify()` | URL-safe slug utility |
 
+### Sitemap + robots (canonical setup)
+
+Every site should ship a **dynamic** sitemap and a robots.txt that references it. The library provides both as one-liners so you never hand-roll either again.
+
+```ts
+// src/app/sitemap.ts
+import type { MetadataRoute } from "next";
+import { generateSitemap } from "@seo/components/server";
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  return generateSitemap({ baseUrl: "https://yourdomain.com" });
+}
+```
+
+```ts
+// src/app/robots.ts
+import type { MetadataRoute } from "next";
+import { generateRobots } from "@seo/components/server";
+
+export default function robots(): MetadataRoute.Robots {
+  return generateRobots({ baseUrl: "https://yourdomain.com" });
+}
+```
+
+`generateSitemap()` walks `src/app/` for `page.tsx` files (skipping route groups, dynamic segments, `api/`, underscore-prefixed dirs) and applies priority tiers. For dynamic routes like `/blog/[slug]`, pass `extraEntries`:
+
+```ts
+return generateSitemap({
+  baseUrl: "https://yourdomain.com",
+  extraEntries: posts.map((p) => ({ url: `https://yourdomain.com/blog/${p.slug}` })),
+});
+```
+
+`generateRobots()` emits the default `User-agent: *` rule, a 13-bot AI allowlist (GPTBot, ChatGPT-User, ClaudeBot, Claude-Web, anthropic-ai, PerplexityBot, CCBot, Google-Extended, Bytespider, cohere-ai, Applebot, Applebot-Extended), and a sitemap URL derived from `baseUrl`. Override `aiAllowlist`, `disallow`, `extraRules`, or `sitemap` as needed.
+
+Verify live after deploy:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}\n" https://yourdomain.com/sitemap.xml  # 200
+curl -s https://yourdomain.com/robots.txt | grep sitemap.xml                 # non-empty
+```
+
 ## JSON-LD Helpers
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m13v/seo-components",
-  "version": "0.20.1",
+  "version": "0.22.1",
   "scripts": {
     "build:css": "tailwind -i src/_build.css -o dist/styles.css --minify",
     "bump:consumers": "bash scripts/bump-consumers.sh",

package/src/components/BookCallCTA.tsx

@@ -2,7 +2,21 @@
 
 import { useEffect, useState } from "react";
 import { motion, AnimatePresence } from "framer-motion";
-import { trackScheduleClick } from "../lib/track";
+import { trackScheduleClick, withBookingAttribution } from "../lib/track";
+
+/**
+ * Render the bare destination for SSR, then swap in the UTM-attributed URL
+ * after hydration so Cmd+Click / middle-click preserves the attribution.
+ * PostHog's `schedule_click` event still receives the bare destination so
+ * aggregation isn't fragmented per page.
+ */
+function useBookingHref(destination: string): string {
+  const [href, setHref] = useState(destination);
+  useEffect(() => {
+    setHref(withBookingAttribution(destination));
+  }, [destination]);
+  return href;
+}
 
 export type BookCallAppearance = "inline" | "sticky" | "hero" | "footer";
 
@@ -111,6 +125,7 @@ function InlineBookCall({
   section: string;
   site?: string;
 }) {
+  const href = useBookingHref(destination);
   return (
     <motion.div
       className="my-12 mx-auto max-w-2xl p-6 rounded-2xl border border-teal-100 dark:border-teal-800/60 bg-teal-50/40 dark:bg-teal-950/60"
@@ -126,7 +141,7 @@ function InlineBookCall({
         {description}
       </p>
       <a
-        href={destination}
+        href={href}
         target="_blank"
         rel="noopener noreferrer"
         className="inline-flex items-center gap-2 text-sm font-medium px-4 py-2 rounded-lg bg-teal-500 text-accent-contrast hover:bg-accent-dim transition-colors"
@@ -151,9 +166,10 @@ function HeroBookCall({
   section: string;
   site?: string;
 }) {
+  const href = useBookingHref(destination);
   return (
     <a
-      href={destination}
+      href={href}
       target="_blank"
       rel="noopener noreferrer"
       className="inline-flex items-center gap-2 px-5 py-2.5 rounded-lg border border-teal-200 dark:border-teal-800/60 text-sm font-medium text-teal-700 dark:text-teal-200 hover:bg-teal-50 dark:hover:bg-teal-950/60 transition-colors"
@@ -181,6 +197,7 @@ function FooterBookCall({
   section: string;
   site?: string;
 }) {
+  const href = useBookingHref(destination);
   return (
     <motion.div
       className="my-16 mx-auto max-w-3xl p-8 rounded-2xl border border-teal-200 dark:border-teal-800/60 bg-gradient-to-br from-teal-50 to-white dark:from-teal-950/70 dark:to-zinc-950 text-center"
@@ -196,7 +213,7 @@ function FooterBookCall({
         {description}
       </p>
       <a
-        href={destination}
+        href={href}
         target="_blank"
         rel="noopener noreferrer"
         className="inline-flex items-center gap-2 px-5 py-2.5 rounded-lg bg-teal-500 text-accent-contrast hover:bg-accent-dim transition-colors text-sm font-medium"
@@ -226,6 +243,7 @@ function StickyBookCall({
   scrollThreshold: number;
 }) {
   const [visible, setVisible] = useState(false);
+  const href = useBookingHref(destination);
 
   useEffect(() => {
     const handler = () => setVisible(window.scrollY > scrollThreshold);
@@ -249,7 +267,7 @@ function StickyBookCall({
               {description}
             </p>
             <a
-              href={destination}
+              href={href}
               target="_blank"
               rel="noopener noreferrer"
               className="text-sm font-medium px-4 py-2 rounded-lg bg-teal-500 text-accent-contrast hover:bg-accent-dim transition-colors"

package/src/components/InlineCta.tsx

@@ -1,7 +1,12 @@
 "use client";
 
+import { useEffect, useState } from "react";
 import { motion } from "framer-motion";
-import { trackGetStartedClick, trackScheduleClick } from "../lib/track";
+import {
+  trackGetStartedClick,
+  trackScheduleClick,
+  withBookingAttribution,
+} from "../lib/track";
 
 interface InlineCtaProps {
   heading: string;
@@ -30,6 +35,13 @@ export function InlineCta({
   site,
   section,
 }: InlineCtaProps) {
+  // For schedule CTAs, rewrite the href after hydration so the Cal.com webhook
+  // sees `metadata[utm_*]` params and can attribute the booking to this page.
+  // PostHog events still carry the bare `href` so aggregation stays clean.
+  const [renderHref, setRenderHref] = useState(href);
+  useEffect(() => {
+    setRenderHref(trackAs === "schedule" ? withBookingAttribution(href) : href);
+  }, [href, trackAs]);
   return (
     <motion.div
       className="my-12 mx-auto max-w-2xl p-6 rounded-2xl border border-teal-100 dark:border-teal-800/60 bg-teal-50/30 dark:bg-teal-950/60"
@@ -45,7 +57,7 @@ export function InlineCta({
         {body}
       </p>
       <a
-        href={href}
+        href={renderHref}
         className="inline-flex items-center gap-2 text-sm font-medium text-teal-600 dark:text-teal-300 hover:text-accent-dim transition-colors"
         onClick={() => {
           if (trackAs === "get_started") {

package/src/components/StickyBottomCta.tsx

@@ -2,7 +2,11 @@
 
 import { useState, useEffect } from "react";
 import { motion, AnimatePresence } from "framer-motion";
-import { trackGetStartedClick, trackScheduleClick } from "../lib/track";
+import {
+  trackGetStartedClick,
+  trackScheduleClick,
+  withBookingAttribution,
+} from "../lib/track";
 
 interface StickyBottomCtaProps {
   description: string;
@@ -33,6 +37,13 @@ export function StickyBottomCta({
 }: StickyBottomCtaProps) {
   const [visible, setVisible] = useState(false);
 
+  // Rewrite schedule CTAs' href after hydration so the Cal.com webhook sees
+  // `metadata[utm_*]` params and attributes the booking to this page.
+  const [renderHref, setRenderHref] = useState(href);
+  useEffect(() => {
+    setRenderHref(trackAs === "schedule" ? withBookingAttribution(href) : href);
+  }, [href, trackAs]);
+
   useEffect(() => {
     const handler = () => setVisible(window.scrollY > scrollThreshold);
     window.addEventListener("scroll", handler);
@@ -75,7 +86,7 @@ export function StickyBottomCta({
               {description}
             </p>
             <a
-              href={href}
+              href={renderHref}
               className="text-sm font-medium px-4 py-2 rounded-lg bg-teal-500 text-accent-contrast hover:bg-accent-dim transition-colors"
               onClick={onClick}
             >

package/src/index.ts

@@ -64,6 +64,7 @@ export {
   trackScheduleClick,
   trackGetStartedClick,
   trackDownloadClick,
+  withBookingAttribution,
 } from "./lib/track";
 export type {
   ScheduleClickProps,

package/src/lib/generate-robots.ts

@@ -0,0 +1,90 @@
+export type RobotsRule = {
+  userAgent: string | string[];
+  allow?: string | string[];
+  disallow?: string | string[];
+  crawlDelay?: number;
+};
+
+export type GenerateRobotsOptions = {
+  /** Absolute base URL, no trailing slash (e.g. `https://fde10x.com`). Used to build the sitemap URL. */
+  baseUrl: string;
+  /**
+   * Paths disallowed for the default `*` rule. Defaults to `["/api/"]`.
+   * Pass an empty array to allow everything.
+   */
+  disallow?: string[];
+  /**
+   * Explicit AI crawler allowlist. Each user agent gets its own rule with
+   * `allow: "/"` so operators (Google, Perplexity, etc.) can distinguish
+   * this site as AI-opted-in. Defaults to the canonical 13-bot allowlist
+   * used across every m13v property. Pass `[]` to disable.
+   */
+  aiAllowlist?: string[];
+  /** Extra rules appended after the default + AI allowlist. */
+  extraRules?: RobotsRule[];
+  /**
+   * Override the sitemap URL. Defaults to `${baseUrl}/sitemap.xml`. Pass an
+   * array when you ship multiple sitemaps.
+   */
+  sitemap?: string | string[];
+};
+
+export type GeneratedRobots = {
+  rules: RobotsRule[];
+  sitemap: string | string[];
+};
+
+const DEFAULT_AI_ALLOWLIST = [
+  "GPTBot",
+  "ChatGPT-User",
+  "ClaudeBot",
+  "Claude-Web",
+  "anthropic-ai",
+  "PerplexityBot",
+  "CCBot",
+  "Google-Extended",
+  "Bytespider",
+  "cohere-ai",
+  "Applebot",
+  "Applebot-Extended",
+];
+
+const DEFAULT_DISALLOW = ["/api/"];
+
+/**
+ * Generate a Next.js `MetadataRoute.Robots` value with a default rule, an
+ * AI-crawler allowlist, and a sitemap reference derived from `baseUrl`.
+ *
+ * ```ts
+ * // src/app/robots.ts
+ * import { generateRobots } from "@seo/components/server";
+ *
+ * export default function robots() {
+ *   return generateRobots({ baseUrl: "https://fde10x.com" });
+ * }
+ * ```
+ *
+ * Pair with `generateSitemap()` in `src/app/sitemap.ts` — the two together
+ * are the canonical SEO-infrastructure setup for a client site.
+ */
+export function generateRobots(opts: GenerateRobotsOptions): GeneratedRobots {
+  const baseUrl = opts.baseUrl.replace(/\/+$/, "");
+  const disallow = opts.disallow ?? DEFAULT_DISALLOW;
+  const aiAllowlist = opts.aiAllowlist ?? DEFAULT_AI_ALLOWLIST;
+
+  const defaultRule: RobotsRule = {
+    userAgent: "*",
+    allow: "/",
+    ...(disallow.length > 0 ? { disallow } : {}),
+  };
+
+  const aiRules: RobotsRule[] = aiAllowlist.map((userAgent) => ({
+    userAgent,
+    allow: "/",
+  }));
+
+  const rules = [defaultRule, ...aiRules, ...(opts.extraRules ?? [])];
+  const sitemap = opts.sitemap ?? `${baseUrl}/sitemap.xml`;
+
+  return { rules, sitemap };
+}

package/src/lib/guide-context.ts

@@ -24,7 +24,11 @@ export function getGuideContext(
   );
   if (!guide) return null;
 
-  // Derive appDir from contentDir to locate page files by their full href
+  // Resolve the page file on disk. `guide.href` is a URL path, which has
+  // Next.js route-group segments like `(content)` stripped out, so we cannot
+  // just join `appDir + href`. Instead, compute the URL prefix that `dir`
+  // maps to, strip it from `href`, and append the remainder to `dir` (the
+  // real filesystem path the caller passed in).
   const relDir = path.relative(process.cwd(), dir);
   const relParts = relDir.split(path.sep);
   const appIdx = relParts.indexOf("app");
@@ -32,7 +36,20 @@ export function getGuideContext(
     appIdx >= 0
       ? path.join(process.cwd(), ...relParts.slice(0, appIdx + 1))
       : dir;
-  const pagePath = path.join(appDir, guide.href, "page.tsx");
+  const relContent = path.relative(appDir, dir);
+  const urlSegments = relContent
+    ? relContent
+        .split(path.sep)
+        .filter((s) => !(s.startsWith("(") && s.endsWith(")")))
+    : [];
+  const urlPrefix = urlSegments.length ? "/" + urlSegments.join("/") : "";
+  let relHref = guide.href;
+  if (urlPrefix && relHref.startsWith(urlPrefix + "/")) {
+    relHref = relHref.slice(urlPrefix.length + 1);
+  } else if (relHref.startsWith("/")) {
+    relHref = relHref.slice(1);
+  }
+  const pagePath = path.join(dir, relHref, "page.tsx");
   let rawSource = "";
   try {
     rawSource = fs.readFileSync(pagePath, "utf-8");

package/src/lib/track.ts

@@ -8,6 +8,54 @@
 
 import { captureFromWindow } from "./analytics-context";
 
+/**
+ * Rewrite a booking URL (Cal.com, Calendly, etc.) so the booking webhook can
+ * attribute the booking back to the specific landing page it came from.
+ *
+ * Cal.com's hosted booking page captures plain `utm_source/utm_medium/utm_campaign`
+ * URL query params and stores them on the booking's metadata, which Cal.com
+ * then forwards in the webhook payload as `booking.metadata.utm_*`. We also
+ * emit Cal.com's bracketed `metadata[key]=value` form as a belt-and-braces
+ * fallback (some Cal.com surfaces accept that syntax instead). Our webhook
+ * handler (social-autoposter-website/api/webhooks/cal/route.ts) writes
+ * `booking.metadata.utm_*` into `cal_bookings.utm_source / utm_medium /
+ * utm_campaign`, so every booking carries the originating site + page path.
+ *
+ * Attribution scheme:
+ *   utm_source   = current hostname (e.g. "fazm.com")
+ *   utm_medium   = "schedule_click"
+ *   utm_campaign = current pathname (e.g. "/t/how-to-quit-weed")
+ *
+ * SSR-safe: returns the URL unchanged on the server (no `window`) or when the
+ * input cannot be parsed as a URL. Never overwrites a pre-existing query key
+ * so manual overrides on specific CTAs still win.
+ *
+ * Applied automatically by `BookCallCTA`, and by `InlineCta` /
+ * `StickyBottomCta` when `trackAs === "schedule"`. Consumers that build a
+ * custom Book-a-Call CTA MUST route their href through this helper or
+ * page-level booking attribution breaks.
+ */
+export function withBookingAttribution(destination: string): string {
+  if (typeof window === "undefined") return destination;
+  try {
+    const url = new URL(destination, window.location.href);
+    const source = window.location.hostname;
+    const campaign = window.location.pathname || "/";
+    const setIfAbsent = (key: string, value: string) => {
+      if (!url.searchParams.has(key)) url.searchParams.set(key, value);
+    };
+    setIfAbsent("utm_source", source);
+    setIfAbsent("utm_medium", "schedule_click");
+    setIfAbsent("utm_campaign", campaign);
+    setIfAbsent("metadata[utm_source]", source);
+    setIfAbsent("metadata[utm_medium]", "schedule_click");
+    setIfAbsent("metadata[utm_campaign]", campaign);
+    return url.toString();
+  } catch {
+    return destination;
+  }
+}
+
 export interface ScheduleClickProps {
   /** Absolute URL the click sends the user to (e.g. https://cal.com/team/mediar/demo). */
   destination: string;

package/src/server.ts

@@ -11,6 +11,13 @@ export type {
   GenerateSitemapOptions,
 } from "./lib/generate-sitemap";
 
+export { generateRobots } from "./lib/generate-robots";
+export type {
+  RobotsRule,
+  GenerateRobotsOptions,
+  GeneratedRobots,
+} from "./lib/generate-robots";
+
 export { slugify } from "./lib/slugify";
 
 export { createGuideChatHandler } from "./lib/guide-chat-route";