fix(seo): clear remaining docs audit errors (MARTECH-19) (#1007)

* fix(seo): clear remaining docs audit errors (MARTECH-19)

Clears the broken-link / 404 / duplicate-canonical errors that remained
after MARTECH-16:

- Redirect /:locale/resources -> /:locale/resources/integrations (the
  toolkit breadcrumb's "Resources" link had no page).
- Integrations index: drop bare "-api" duplicate cards, de-dupe same-URL
  entries (notion), and render doc-less catalog toolkits non-clickable
  instead of linking to 404s.
- Add self-referential canonical to every toolkit page.
- Fix the Square auth page link (squareupapi -> squareup-api).
- Replace in-content mailto: links with a client-rendered <ContactEmail>
  so Cloudflare can't rewrite them into broken /cdn-cgi links (the
  <!--email_off--> marker is infeasible: it breaks the MDX build and the
  dangerouslySetInnerHTML workaround is a banned lint error).
- Add tests/integration-index-links.test.ts to guard component-generated
  and dynamic-slug links, which the MDX-only scan missed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* test(seo): derive index-link assertions from live data (MARTECH-19)

CI tests the PR merged into main, and main shipped real pages for several
toolkits this PR treated as doc-less (datadog, vercel, ashby, customerio,
apollo, discordbot, freshdesk). That made the hard-coded "datadog is a
dropped duplicate" assertion false against the merged data.

Rebuild the test to derive its cases from the live catalog + route set,
and add a synthetic unit test that exercises the drop/dedup/hidden/
doc-less logic deterministically, so toolkit-data changes can't make it
stale again. Also merges latest main into the branch.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* test(seo): generalize index-link tests, drop toolkit-name coupling

Use placeholder toolkits in the resolveIndexToolkits unit tests and
derive the static-page check from a filesystem scan instead of naming
Tavily, so adding or removing a real toolkit (e.g. shipping Discord docs)
never requires editing this test. Also drop the "some non-clickable"
assertion, which would fail once every toolkit has its own page — an
improvement, not a regression.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore(seo): document ContactEmail's hardcoded /en locale (review nit)

Address PR review: note that CONTACT_PAGE is intentionally pinned to the
English contact page (content is en-only today; a /<locale>/ link could
404), with a TODO to make it locale-aware once translated content ships.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Juan Ibarlucea <juanibarlucea@192.168.1.2>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

app/_components/contact-email.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import Link from "next/link";
+import type { ReactNode } from "react";
+import { useEffect, useState } from "react";
+
+// TODO(i18n): hardcoded to the English contact page. Docs content is en-only
+// today, so this is the safe target (a /<locale>/ link could 404 for locales
+// without the page). When translated content ships, derive the active locale
+// (e.g. via usePathname) and point at /<locale>/resources/contact-us.
+const CONTACT_PAGE = "/en/resources/contact-us";
+
+type ContactEmailProps = {
+  /** Local part of the address, e.g. "security" for security@arcade.dev. */
+  user: string;
+  /** Domain of the address, e.g. "arcade.dev". */
+  domain: string;
+  /** Visible link text. Keep it free of the raw address (see below). */
+  children: ReactNode;
+};
+
+/**
+ * A mailto link whose address is assembled only after hydration.
+ *
+ * Cloudflare's Email Address Obfuscation runs at the edge on the server-rendered
+ * HTML and rewrites any `mailto:`/address it finds into a
+ * `/cdn-cgi/l/email-protection` link, which crawlers report as broken. By keeping
+ * the address out of the SSR markup — we render a plain link to the contact page
+ * until the component mounts — there is nothing for Cloudflare to rewrite, while
+ * real users still get a working `mailto:`. Pass visible text via `children`
+ * (not the literal address) so it isn't exposed server-side either.
+ */
+export function ContactEmail({ user, domain, children }: ContactEmailProps) {
+  const [address, setAddress] = useState<string | null>(null);
+
+  useEffect(() => {
+    setAddress(`${user}@${domain}`);
+  }, [user, domain]);
+
+  if (address) {
+    return <a href={`mailto:${address}`}>{children}</a>;
+  }
+
+  return <Link href={CONTACT_PAGE}>{children}</Link>;
+}

app/_lib/integration-catalog.ts

@@ -0,0 +1,52 @@
+import type { Toolkit } from "@arcadeai/design-system";
+import { TOOLKITS } from "@arcadeai/design-system/metadata/toolkits";
+import { PARTNER_TOOLKITS } from "@/app/_data/partner-toolkits";
+import { readToolkitData } from "./toolkit-data";
+import { normalizeToolkitId, type ToolkitWithDocsLink } from "./toolkit-slug";
+
+const getToolkitDocsLink = (toolkit: Toolkit): string | undefined => {
+  if ("docsLink" in toolkit) {
+    const value = (toolkit as ToolkitWithDocsLink).docsLink;
+    return value ?? undefined;
+  }
+  return;
+};
+
+/**
+ * The full integrations catalog the index renders: design-system toolkits
+ * (enriched with a `docsLink` from their data file when the catalog entry
+ * lacks one, so the card's slug matches the generated page) plus docs-local
+ * partner toolkits.
+ */
+export const getToolkitsWithDocsLinks = async (): Promise<
+  ToolkitWithDocsLink[]
+> => {
+  const docsLinkById = new Map<string, string>();
+
+  await Promise.all(
+    TOOLKITS.map(async (toolkit) => {
+      const existing = getToolkitDocsLink(toolkit);
+      if (existing) {
+        return;
+      }
+
+      const data = await readToolkitData(toolkit.id);
+      if (data?.metadata?.docsLink) {
+        docsLinkById.set(
+          normalizeToolkitId(toolkit.id),
+          data.metadata.docsLink
+        );
+      }
+    })
+  );
+
+  const dsToolkits: ToolkitWithDocsLink[] = TOOLKITS.map((toolkit) => {
+    const existing = getToolkitDocsLink(toolkit);
+    const docsLink =
+      existing ?? docsLinkById.get(normalizeToolkitId(toolkit.id));
+
+    return docsLink ? { ...toolkit, docsLink } : toolkit;
+  });
+
+  return [...dsToolkits, ...PARTNER_TOOLKITS];
+};

app/_lib/integration-index.ts

@@ -0,0 +1,67 @@
+import { getToolkitSlug, type ToolkitWithDocsLink } from "./toolkit-slug";
+
+const INTEGRATIONS_BASE = "/en/resources/integrations";
+
+/**
+ * The integrations link a toolkit card points to: `/en/resources/integrations/
+ * <category>/<slug>`. Mirrors the slug + category logic used to generate the
+ * dynamic `[toolkitId]` routes so cards and pages agree.
+ */
+export function toIntegrationLink(toolkit: {
+  id: string;
+  docsLink?: string | null;
+  category?: string | null;
+}): string {
+  const slug = getToolkitSlug({ id: toolkit.id, docsLink: toolkit.docsLink });
+  const category = toolkit.category ?? "others";
+  return `${INTEGRATIONS_BASE}/${category}/${slug}`;
+}
+
+export type ResolvedIndexToolkit = ToolkitWithDocsLink & { hasPage: boolean };
+
+/**
+ * Decide which catalog toolkits the integrations index should render, and
+ * whether each one links to a real page.
+ *
+ * The design-system catalog carries legacy bare-name entries (e.g. "Datadog"
+ * alongside "DatadogApi") and doc-less placeholders (e.g. "Discord") that have
+ * no generated docs page — linking to them 404s. Given the set of links that
+ * actually resolve (`validLinks`: dynamic toolkit routes + authored static
+ * pages), this:
+ *   - drops a bare entry when its `-api` sibling owns the real page (collapses
+ *     Datadog/DatadogApi, Vercel/VercelApi, Ashby/AshbyApi, Customerio/...),
+ *   - de-dupes entries that resolve to the same URL (e.g. Notion/NotionToolkit),
+ *   - flags the rest with `hasPage` so the caller can render doc-less toolkits
+ *     as non-clickable cards instead of as broken links.
+ */
+export function resolveIndexToolkits(
+  toolkits: ToolkitWithDocsLink[],
+  validLinks: ReadonlySet<string>
+): ResolvedIndexToolkit[] {
+  const seen = new Set<string>();
+  const resolved: ResolvedIndexToolkit[] = [];
+
+  for (const toolkit of toolkits) {
+    // Hidden toolkits never render in the index (matches the client filter).
+    if (toolkit.isHidden) {
+      continue;
+    }
+
+    const link = toIntegrationLink(toolkit);
+    const hasPage = validLinks.has(link);
+
+    // A bare duplicate of a real "-api" toolkit: drop it; the real card stays.
+    if (!hasPage && validLinks.has(`${link}-api`)) {
+      continue;
+    }
+
+    // Collapse multiple catalog entries that point at the same URL.
+    if (seen.has(link)) {
+      continue;
+    }
+    seen.add(link);
+    resolved.push({ ...toolkit, hasPage });
+  }
+
+  return resolved;
+}

app/_lib/toolkit-static-params.ts

@@ -186,3 +186,67 @@ export async function getToolkitStaticParamsForCategory(
     .filter((route) => route.category === category)
     .map((route) => ({ toolkitId: route.toolkitId }));
 }
+
+const INTEGRATIONS_APP_DIR = join(
+  process.cwd(),
+  "app",
+  "en",
+  "resources",
+  "integrations"
+);
+
+const PAGE_FILE_NAMES = new Set(["page.mdx", "page.tsx"]);
+
+/**
+ * Authored static integration pages (e.g. partner pages like `search/tavily`
+ * and `tool-feedback`) live next to the dynamic `[toolkitId]` routes. They are
+ * real pages but are not part of `listToolkitRoutes`, so enumerate them from
+ * disk under the known integration categories.
+ */
+const listStaticIntegrationLinks = async (): Promise<string[]> => {
+  const links: string[] = [];
+
+  for (const category of INTEGRATION_CATEGORIES) {
+    const categoryDir = join(INTEGRATIONS_APP_DIR, category);
+    try {
+      const slugs = await readdir(categoryDir, { withFileTypes: true });
+      for (const slug of slugs) {
+        if (!slug.isDirectory() || slug.name.startsWith("[")) {
+          continue;
+        }
+        const files = await readdir(join(categoryDir, slug.name));
+        if (files.some((file) => PAGE_FILE_NAMES.has(file))) {
+          links.push(`/en/resources/integrations/${category}/${slug.name}`);
+        }
+      }
+    } catch {
+      // Category dir missing or unreadable — skip it.
+    }
+  }
+
+  return links;
+};
+
+/**
+ * The full set of links the integrations index may point at and that actually
+ * resolve: dynamic toolkit routes plus authored static pages. Used to decide
+ * whether a catalog card should be clickable.
+ */
+export async function listValidIntegrationLinks(options?: {
+  dataDir?: string;
+  toolkitsCatalog?: ToolkitCatalogEntry[];
+}): Promise<Set<string>> {
+  const routes = await listToolkitRoutes(options);
+  const links = new Set<string>(
+    routes.map(
+      (route) =>
+        `/en/resources/integrations/${route.category}/${route.toolkitId}`
+    )
+  );
+
+  for (const staticLink of await listStaticIntegrationLinks()) {
+    links.add(staticLink);
+  }
+
+  return links;
+}

app/en/references/auth-providers/oauth2/page.mdx

@@ -5,6 +5,7 @@ description: Authorize tools and agents with any OAuth 2.0-compatible provider
 
 import { Tabs, Callout, Steps } from "nextra/components";
 import ToggleContent from "@/app/_components/toggle-content";
+import { ContactEmail } from "@/app/_components/contact-email";
 
 # OAuth 2.0
 
@@ -125,8 +126,11 @@ The ID of the provider (`hooli` in this example) can be any string. It's used to
 Each service expects a slightly different set of values in the `oauth2` section. Refer to the configuration reference below, and to your service's documentation to understand what values are required.
 
 <Callout>
-  If you need help configuring a specific provider, [get in touch with
-  us](mailto:contact@arcade.dev)!
+  If you need help configuring a specific provider,{" "}
+  <ContactEmail domain="arcade.dev" user="contact">
+    get in touch with us
+  </ContactEmail>
+  !
 </Callout>
 
 </Steps>

app/en/references/auth-providers/page.mdx

@@ -6,6 +6,7 @@ description: Registry of all auth providers available in the Arcade ecosystem
 # Auth Providers
 
 import { ToolCard } from "@/app/_components/tool-card";
+import { ContactEmail } from "@/app/_components/contact-email";
 
 Auth providers enable users to seamlessly and securely allow Arcade tools to access their data.
 
@@ -156,7 +157,7 @@ For more information on how to customize your auth provider, select an auth prov
   />
 </div>
 
-If the auth provider you need is not listed, try the [OAuth 2.0](/references/auth-providers/oauth2) provider, or [get in touch](mailto:contact@arcade.dev) with us!
+If the auth provider you need is not listed, try the [OAuth 2.0](/references/auth-providers/oauth2) provider, or <ContactEmail domain="arcade.dev" user="contact">get in touch</ContactEmail> with us!
 
 ## Using multiple providers of the same type
 

app/en/references/auth-providers/square/page.mdx

@@ -6,7 +6,7 @@ The Square auth provider enables tools and agents to call [Square APIs](https://
 
 <Callout>
   Want to quickly get started with Square in your agent or AI app? The pre-built
-  [Arcade Square MCP Server](/resources/integrations/productivity/squareupapi)
+  [Arcade Square MCP Server](/resources/integrations/productivity/squareup-api)
   is what you want!
 </Callout>
 
@@ -16,7 +16,7 @@ This page describes how to use and configure Square auth with Arcade.
 
 This auth provider is used by:
 
-- The [Arcade Square MCP Server](/resources/integrations/productivity/squareupapi), which provides pre-built tools for interacting with Square
+- The [Arcade Square MCP Server](/resources/integrations/productivity/squareup-api), which provides pre-built tools for interacting with Square
 - Your [app code](#using-square-auth-in-app-code) that needs to call the Square API
 - Or, your [custom tools](#using-square-auth-in-custom-tools) that need to call the Square API
 
@@ -247,7 +247,7 @@ const token = authResponse.context.token;
 
 ## Using Square auth in custom tools
 
-You can use the pre-built [Arcade Square MCP Server](/resources/integrations/productivity/squareupapi) to quickly build agents and AI apps that interact with Square.
+You can use the pre-built [Arcade Square MCP Server](/resources/integrations/productivity/squareup-api) to quickly build agents and AI apps that interact with Square.
 
 If the pre-built tools in the Square MCP Server don't meet your needs, you can author your own [custom tools](/guides/create-tools/tool-basics/build-mcp-server) that interact with the Square API.
 

app/en/resources/faq/page.mdx

@@ -7,6 +7,7 @@ import { Button } from "@arcadeai/design-system";
 import { MessagesSquare } from "lucide-react";
 import Link from "next/link";
 import { Tabs } from "nextra/components";
+import { ContactEmail } from "@/app/_components/contact-email";
 
 # Frequently Asked Questions
 
@@ -42,7 +43,7 @@ This is an important observation. Technically, both included and custom provider
 
 ### Can my users connect multiple accounts of the same provider?
 
-Please [contact us](mailto:support@arcade.dev) if you need this feature.
+Please <ContactEmail domain="arcade.dev" user="support">contact us</ContactEmail> if you need this feature.
 
 ### Can I authenticate multiple tools at once?
 

app/en/resources/integrations/_lib/toolkit-docs-page.tsx

@@ -2,7 +2,7 @@ import type { Metadata } from "next";
 import { notFound } from "next/navigation";
 import { ToolkitPage } from "@/app/_components/toolkit-docs";
 import { readToolkitData } from "@/app/_lib/toolkit-data";
-import { normalizeToolkitId } from "@/app/_lib/toolkit-slug";
+import { getToolkitSlug, normalizeToolkitId } from "@/app/_lib/toolkit-slug";
 import {
   getToolkitStaticParamsForCategory,
   type IntegrationCategory,
@@ -43,9 +43,20 @@ export function createToolkitDocsPage(category: IntegrationCategory) {
       return {};
     }
 
+    // Canonicalize to the toolkit's preferred slug so any alias that resolves
+    // to the same content (e.g. a normalized id vs. its docsLink slug) points
+    // search engines at one URL.
+    const canonicalSlug = getToolkitSlug({
+      id: data.id,
+      docsLink: data.metadata?.docsLink,
+    });
+
     return {
       title: data.label || data.id,
       description: data.description || "Generated MCP server documentation.",
+      alternates: {
+        canonical: `/en/resources/integrations/${category}/${canonicalSlug}`,
+      },
     };
   };