jamdesk 1.1.142 → 1.1.144

package/vendored/lib/newsletter/adapters/kit.ts

@@ -0,0 +1,35 @@
+import type { NewsletterAdapter, NewsletterCreds } from '../types';
+import { getDescriptor } from '../descriptors';
+import { fetchJson } from '../http';
+
+const BASE = 'https://api.kit.com/v4';
+const headers = (secret: string) => ({ 'X-Kit-Api-Key': secret, 'content-type': 'application/json' });
+
+export const kitAdapter: NewsletterAdapter = {
+  descriptor: getDescriptor('kit')!,
+  async validate(creds: NewsletterCreds) {
+    if (!creds.formId) return { ok: false, reason: 'formId required' };
+    // Probe the FORM resource, NOT just /account: a key that can read the account
+    // may have a wrong/inaccessible formId, which /account wouldn't catch — then
+    // every real signup 404s.
+    const { status } = await fetchJson(`${BASE}/forms/${creds.formId}/subscribers?per_page=1`,
+      { method: 'GET', headers: headers(creds.secret) });
+    return status === 200 ? { ok: true } : { ok: false, reason: `form ${status}` };
+  },
+  async addContact(email: string, creds: NewsletterCreds) {
+    if (!creds.formId) return { ok: false, code: 'misconfigured' };
+    // Kit v4 split subscriber-creation from form-attachment: POST /forms/{id}/subscribers
+    // ONLY attaches a subscriber that ALREADY exists ("The subscriber being added to the
+    // form must already exist") — for a brand-new email it returns 2xx without adding
+    // anyone. So upsert the subscriber first (idempotent: 201 new / 200 existing), then
+    // attach them to the form.
+    const created = await fetchJson(`${BASE}/subscribers`, {
+      method: 'POST', headers: headers(creds.secret), body: JSON.stringify({ email_address: email }),
+    });
+    if (created.status < 200 || created.status >= 300) return { ok: false, status: created.status };
+    const { status } = await fetchJson(`${BASE}/forms/${creds.formId}/subscribers`, {
+      method: 'POST', headers: headers(creds.secret), body: JSON.stringify({ email_address: email }),
+    });
+    return status >= 200 && status < 300 ? { ok: true } : { ok: false, status };
+  },
+};

package/vendored/lib/newsletter/adapters/loops.ts

@@ -0,0 +1,22 @@
+import type { NewsletterAdapter, NewsletterCreds } from '../types';
+import { getDescriptor } from '../descriptors';
+import { fetchJson } from '../http';
+
+const BASE = 'https://app.loops.so/api/v1';
+const headers = (secret: string) => ({ Authorization: `Bearer ${secret}`, 'content-type': 'application/json' });
+
+export const loopsAdapter: NewsletterAdapter = {
+  descriptor: getDescriptor('loops')!,
+  async validate(creds: NewsletterCreds) {
+    const { status } = await fetchJson(`${BASE}/api-key`, { method: 'GET', headers: headers(creds.secret) });
+    return status === 200 ? { ok: true } : { ok: false, reason: `api-key ${status}` };
+  },
+  async addContact(email: string, creds: NewsletterCreds) {
+    const { status } = await fetchJson(`${BASE}/contacts/create`, {
+      method: 'POST', headers: headers(creds.secret), body: JSON.stringify({ email }),
+    });
+    // 409 = contact already exists → a successful (idempotent) signup.
+    if (status === 409) return { ok: true };
+    return status >= 200 && status < 300 ? { ok: true } : { ok: false, status };
+  },
+};

package/vendored/lib/newsletter/adapters/mailchimp.ts

@@ -0,0 +1,52 @@
+// Node-runtime ONLY: uses node:crypto (MD5) + Buffer. Safe here — the subscribe
+// route is `export const runtime = 'nodejs'` and the vendored functions copy runs
+// on Node 24. Do NOT import the registry from an edge route.
+import { createHash } from 'node:crypto';
+import type { NewsletterAdapter, NewsletterCreds } from '../types';
+import { getDescriptor } from '../descriptors';
+import { fetchJson } from '../http';
+
+// SECURITY: the datacenter suffix is interpolated straight into the request host
+// (`https://${dc}.api.mailchimp.com`). The `/^[a-z]+\d+$/` test is the ONLY guard
+// stopping a malicious or typo'd key suffix from redirecting the authenticated
+// call to an attacker-controlled host (SSRF + key exfiltration). Do NOT loosen it.
+function dc(secret: string): string | null {
+  const i = secret.lastIndexOf('-');
+  const suffix = i >= 0 ? secret.slice(i + 1) : '';
+  return /^[a-z]+\d+$/.test(suffix) ? suffix : null;
+}
+function authHeader(secret: string): string {
+  return 'Basic ' + Buffer.from(`any:${secret}`).toString('base64');
+}
+function memberHash(email: string): string {
+  return createHash('md5').update(email.trim().toLowerCase()).digest('hex');
+}
+
+export const mailchimpAdapter: NewsletterAdapter = {
+  descriptor: getDescriptor('mailchimp')!,
+  async validate(creds: NewsletterCreds) {
+    const d = dc(creds.secret);
+    if (!d) return { ok: false, reason: 'key has no -datacenter suffix' };
+    if (!creds.listId) return { ok: false, reason: 'listId required' };
+    const { status } = await fetchJson(
+      `https://${d}.api.mailchimp.com/3.0/lists/${creds.listId}`,
+      { method: 'GET', headers: { Authorization: authHeader(creds.secret) } },
+    );
+    return status === 200 ? { ok: true } : { ok: false, reason: `list check ${status}` };
+  },
+  async addContact(email: string, creds: NewsletterCreds) {
+    const d = dc(creds.secret);
+    if (!d || !creds.listId) return { ok: false, code: 'misconfigured' };
+    const hash = memberHash(email);
+    const { status } = await fetchJson(
+      `https://${d}.api.mailchimp.com/3.0/lists/${creds.listId}/members/${hash}`,
+      {
+        method: 'PUT',
+        headers: { Authorization: authHeader(creds.secret), 'content-type': 'application/json' },
+        // status_if_new (not status) → never resurrects an unsubscribed member.
+        body: JSON.stringify({ email_address: email, status_if_new: 'subscribed' }),
+      },
+    );
+    return status >= 200 && status < 300 ? { ok: true } : { ok: false, status };
+  },
+};

package/vendored/lib/newsletter/adapters/resend.ts

@@ -0,0 +1,23 @@
+import { Resend } from 'resend';
+import type { NewsletterAdapter, NewsletterCreds } from '../types';
+import { getDescriptor } from '../descriptors';
+
+// Resend keeps the SDK (already a dep of build-service AND functions). validate
+// calls segments.get: Resend keys are binary (Full vs Sending) and a
+// Sending-access key cannot call segments.* — success proves Full access AND a
+// valid audience. addContact upserts WITHOUT unsubscribed:false (no resurrection).
+export const resendAdapter: NewsletterAdapter = {
+  descriptor: getDescriptor('resend')!,
+  async validate(creds: NewsletterCreds) {
+    if (!creds.audienceId) return { ok: false, reason: 'audienceId required' };
+    const { error } = await new Resend(creds.secret).segments.get(creds.audienceId);
+    // Surface Resend's error.name (e.g. "restricted_api_key" = a Sending-only
+    // key, "not_found" = wrong audience) so a failed connect is debuggable from
+    // logs. error.name is a stable, key-safe category string.
+    return error ? { ok: false, reason: error.name || 'invalid_key_or_audience' } : { ok: true };
+  },
+  async addContact(email: string, creds: NewsletterCreds) {
+    const { error } = await new Resend(creds.secret).contacts.create({ email, audienceId: creds.audienceId! });
+    return error ? { ok: false, code: error.name } : { ok: true };
+  },
+};

package/vendored/lib/newsletter/adapters/sendgrid.ts

@@ -0,0 +1,23 @@
+import type { NewsletterAdapter, NewsletterCreds } from '../types';
+import { getDescriptor } from '../descriptors';
+import { fetchJson } from '../http';
+
+const BASE = 'https://api.sendgrid.com/v3';
+const headers = (secret: string) => ({ Authorization: `Bearer ${secret}`, 'content-type': 'application/json' });
+
+export const sendgridAdapter: NewsletterAdapter = {
+  descriptor: getDescriptor('sendgrid')!,
+  async validate(creds: NewsletterCreds) {
+    if (!creds.listId) return { ok: false, reason: 'listId required' };
+    const { status } = await fetchJson(`${BASE}/marketing/lists/${creds.listId}`, { method: 'GET', headers: headers(creds.secret) });
+    return status === 200 ? { ok: true } : { ok: false, reason: `list ${status}` };
+  },
+  async addContact(email: string, creds: NewsletterCreds) {
+    if (!creds.listId) return { ok: false, code: 'misconfigured' };
+    const { status } = await fetchJson(`${BASE}/marketing/contacts`, {
+      method: 'PUT', headers: headers(creds.secret),
+      body: JSON.stringify({ list_ids: [creds.listId], contacts: [{ email }] }),
+    });
+    return status >= 200 && status < 300 ? { ok: true } : { ok: false, status };
+  },
+};

package/vendored/lib/newsletter/descriptors.ts

@@ -0,0 +1,84 @@
+import type { ProviderDescriptor } from './types';
+
+const SECRET = (label: string, placeholder: string, help?: string) =>
+  ({ key: 'secret' as const, label, placeholder, type: 'password' as const, help });
+
+export const NEWSLETTER_DESCRIPTORS: ProviderDescriptor[] = [
+  {
+    id: 'resend', label: 'Resend',
+    fields: [
+      SECRET('Resend API key', 're_live_...', 'Full access key (Sending-access keys cannot manage contacts).'),
+      {
+        key: 'audienceId', label: 'Audience ID', placeholder: '78261eea-...', type: 'text',
+        help: 'In Resend → Audiences, click the ⋯ menu on your audience → Copy ID.',
+        helpUrl: 'https://resend.com/audiences', helpLabel: 'Resend audiences',
+      },
+    ],
+    docsUrl: 'https://resend.com/api-keys', docsLabel: 'resend.com/api-keys',
+    redact: /re_[A-Za-z0-9_]{6,}/g,
+  },
+  {
+    id: 'mailchimp', label: 'Mailchimp',
+    fields: [
+      SECRET('Mailchimp API key', '...-us21', 'The key ends in your datacenter, e.g. -us21.'),
+      { key: 'listId', label: 'Audience (List) ID', placeholder: 'a1b2c3d4e5', type: 'text' },
+    ],
+    docsUrl: 'https://mailchimp.com/help/about-api-keys/', docsLabel: 'Mailchimp API keys',
+    redact: /[0-9a-f]{32}-us\d{1,2}/g,
+  },
+  {
+    id: 'kit', label: 'Kit (ConvertKit)',
+    fields: [
+      SECRET('Kit API key', 'kit_...', 'A v4 API key from your Kit account settings.'),
+      { key: 'formId', label: 'Form ID', placeholder: '1234567', type: 'text' },
+    ],
+    docsUrl: 'https://app.kit.com/account_settings/developer_settings', docsLabel: 'Kit developer settings',
+    redact: /kit_[A-Za-z0-9]{6,}/g,
+  },
+  {
+    id: 'loops', label: 'Loops',
+    fields: [SECRET('Loops API key', '...', 'An API key from Loops → Settings → API.')],
+    docsUrl: 'https://app.loops.so/settings?page=api', docsLabel: 'Loops API settings',
+    redact: /[0-9a-f]{32,}/g,
+  },
+  {
+    id: 'beehiiv', label: 'beehiiv',
+    fields: [
+      SECRET('beehiiv API key', '...', 'An API key from Settings → API.'),
+      { key: 'publicationId', label: 'Publication ID', placeholder: 'pub_...', type: 'text' },
+    ],
+    docsUrl: 'https://developers.beehiiv.com/', docsLabel: 'beehiiv API docs',
+    redact: /pub_[A-Za-z0-9-]{6,}/g,
+  },
+  {
+    id: 'brevo', label: 'Brevo',
+    fields: [
+      SECRET('Brevo API key', 'xkeysib-...', 'A v3 API key from SMTP & API → API Keys.'),
+      { key: 'listId', label: 'Contact List ID', placeholder: '2', type: 'text' },
+    ],
+    docsUrl: 'https://app.brevo.com/settings/keys/api', docsLabel: 'Brevo API keys',
+    redact: /xkeysib-[A-Za-z0-9-]{6,}/g,
+  },
+  {
+    id: 'sendgrid', label: 'SendGrid',
+    fields: [
+      SECRET('SendGrid API key', 'SG....', 'A key with Marketing → Contacts write access.'),
+      { key: 'listId', label: 'Marketing List ID', placeholder: 'uuid', type: 'text' },
+    ],
+    docsUrl: 'https://app.sendgrid.com/settings/api_keys', docsLabel: 'SendGrid API keys',
+    redact: /SG\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}/g,
+  },
+];
+
+export function getDescriptor(id: string): ProviderDescriptor | undefined {
+  const key = id.trim().toLowerCase();
+  return NEWSLETTER_DESCRIPTORS.find((d) => d.id === key);
+}
+
+/** Native-capture provider ids, derived from the descriptors. Lives HERE (pure
+ *  data) rather than in registry.ts so `email-subscribe-providers.ts` — which is
+ *  vendored into the dashboard editor — can gate on it WITHOUT importing the
+ *  adapters (which pull in `resend`/`fetch`/`node:crypto` and have no place in the
+ *  editor bundle). registry.ts re-exports this; the registry test cross-checks it
+ *  equals the adapter keys so a descriptor/adapter mismatch fails loudly. */
+export const NATIVE_PROVIDER_IDS = new Set(NEWSLETTER_DESCRIPTORS.map((d) => d.id));

package/vendored/lib/newsletter/http.ts

@@ -0,0 +1,19 @@
+/** Minimal JSON fetch with a hard timeout. Returns the status + parsed body
+ *  (null if the body isn't JSON). Never throws on non-2xx — callers branch on
+ *  `status`. Throws only on network failure / abort, which callers catch. */
+export async function fetchJson(
+  url: string,
+  init: RequestInit,
+  timeoutMs = 8000,
+): Promise<{ status: number; json: unknown }> {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { ...init, signal: ctrl.signal });
+    let json: unknown = null;
+    try { json = await res.json(); } catch { /* empty / non-JSON body */ }
+    return { status: res.status, json };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/vendored/lib/newsletter/registry.ts

@@ -0,0 +1,27 @@
+import type { NewsletterAdapter } from './types';
+import { resendAdapter } from './adapters/resend';
+import { mailchimpAdapter } from './adapters/mailchimp';
+import { kitAdapter } from './adapters/kit';
+import { loopsAdapter } from './adapters/loops';
+import { beehiivAdapter } from './adapters/beehiiv';
+import { brevoAdapter } from './adapters/brevo';
+import { sendgridAdapter } from './adapters/sendgrid';
+
+export const NEWSLETTER_ADAPTERS: Record<string, NewsletterAdapter> = {
+  resend: resendAdapter,
+  mailchimp: mailchimpAdapter,
+  kit: kitAdapter,
+  loops: loopsAdapter,
+  beehiiv: beehiivAdapter,
+  brevo: brevoAdapter,
+  sendgrid: sendgridAdapter,
+};
+
+// Single source of truth is descriptors.ts (pure data, vendored to the editor).
+// Re-export for endpoint/registry callers; the test below cross-checks it equals
+// the adapter keys, catching a descriptor-without-adapter (or vice-versa) drift.
+export { NATIVE_PROVIDER_IDS } from './descriptors';
+
+export function getAdapter(provider: string): NewsletterAdapter | undefined {
+  return NEWSLETTER_ADAPTERS[provider.trim().toLowerCase()];
+}

package/vendored/lib/newsletter/types.ts

@@ -0,0 +1,52 @@
+/** Generic, multi-provider credentials. `secret` is always the API key; the
+ *  provider-specific id fields below are present only for the providers that
+ *  need them. Stored (minus nothing) in Redis; the secret never leaves the
+ *  backend. */
+export interface NewsletterCreds {
+  provider: string;
+  secret: string;
+  enabled?: boolean;
+  audienceId?: string;    // resend
+  listId?: string;        // mailchimp, brevo, sendgrid
+  formId?: string;        // kit
+  publicationId?: string; // beehiiv
+}
+
+/** One input the dashboard card renders for a provider. `key` is the
+ *  NewsletterCreds field it populates. */
+export interface CredField {
+  key: 'secret' | 'audienceId' | 'listId' | 'formId' | 'publicationId';
+  label: string;
+  placeholder: string;
+  type: 'password' | 'text';
+  /** Short hint shown under the field. */
+  help?: string;
+  /** Optional "where to find this" link shown under the field (e.g. where a
+   *  provider exposes the id the field needs). */
+  helpUrl?: string;
+  helpLabel?: string;
+}
+
+/** Pure-data description of a provider for the dashboard UI + input validation. */
+export interface ProviderDescriptor {
+  id: string;
+  label: string;
+  /** Fields in display order; always includes the `secret` field first. */
+  fields: CredField[];
+  /** Where the owner creates the key. */
+  docsUrl: string;
+  docsLabel: string;
+  /** Matches this provider's key format, for redacting it out of error text. */
+  redact: RegExp;
+}
+
+export interface ValidateResult { ok: boolean; reason?: string; }
+export interface AddContactResult { ok: boolean; status?: number; code?: string; }
+
+export interface NewsletterAdapter {
+  descriptor: ProviderDescriptor;
+  /** Cheap live call proving the key (and id field, if any) work. */
+  validate(creds: NewsletterCreds): Promise<ValidateResult>;
+  /** Add/upsert the subscriber. Never throws on provider errors — returns ok:false. */
+  addContact(email: string, creds: NewsletterCreds): Promise<AddContactResult>;
+}

package/vendored/lib/newsletter-display.ts

@@ -0,0 +1,43 @@
+// builder/build-service/lib/newsletter-display.ts
+//
+// Prod-only (ISR) reader for the dashboard-set display copy on the newsletter
+// signup. NOT vendored — the CLI/editor have no prod Redis, and a dashboard
+// subtitle is a published-site concept. The render path stays Redis-free; this
+// is injected into renderDocPage as a lazy loader and only ever called when a
+// changelog page actually auto-places the signup.
+import { redis } from './redis';
+
+export interface NewsletterDisplay {
+  title?: string;
+  description?: string;
+}
+
+/**
+ * Read the dashboard-set title/subtitle from the `newsletter:<slug>` record the
+ * Email Signups card writes (same record the capture endpoint reads for creds).
+ * NEVER returns the secret. Fails OPEN (returns null) on any error so a Redis
+ * blip can never break a changelog render — the form just falls back to the
+ * docs.json copy.
+ */
+export async function readNewsletterDisplay(slug: string): Promise<NewsletterDisplay | null> {
+  if (!redis) return null;
+  let raw: unknown;
+  try {
+    raw = await redis.get(`newsletter:${slug}`);
+  } catch {
+    return null;
+  }
+  if (!raw) return null;
+  let obj: unknown = raw;
+  // Upstash may hand back a JSON string or an already-parsed object (mirrors the
+  // capture route's parseCreds tolerance).
+  if (typeof raw === 'string') {
+    try { obj = JSON.parse(raw); } catch { return null; }
+  }
+  if (!obj || typeof obj !== 'object') return null;
+  const c = obj as Record<string, unknown>;
+  const display: NewsletterDisplay = {};
+  if (typeof c.title === 'string' && c.title.trim()) display.title = c.title;
+  if (typeof c.description === 'string' && c.description.trim()) display.description = c.description;
+  return display.title || display.description ? display : null;
+}

package/vendored/lib/render-doc-page.tsx

@@ -89,6 +89,8 @@ import { AIActionsMenu } from '@/components/AIActionsMenu';
 import { getContextualOptions } from '@/lib/contextual-defaults';
 import { withApiSpecDownload } from '@/lib/api-spec-menu-gate';
 import { SnippetComponents } from '@/components/snippets/ProjectSnippets';
+import { EmailSubscribe } from '@/components/mdx/EmailSubscribe';
+import { resolveAutoNewsletter, mdxHasEmailSubscribe } from '@/lib/email-subscribe-autoplacement';
 
 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE';
 
@@ -130,6 +132,11 @@ export interface RenderInput {
   projectSlug: string | null;
   hostAtDocs: boolean;
   requestHeaders: Headers | null;
+  /** Lazy loader for the dashboard-set signup title/subtitle (prod ISR only —
+   *  reads Redis, so it's injected by the route, NOT imported here, to keep this
+   *  vendored module Redis-free). Called at most once, and only when a changelog
+   *  page actually auto-places the signup. */
+  loadNewsletterDisplay?: () => Promise<{ title?: string; description?: string } | null>;
 }
 
 interface FrontmatterData {
@@ -217,7 +224,11 @@ export async function buildDocMetadata(input: RenderInput): Promise<Metadata> {
   const configP = loader.getConfig();
 
   const normalizedSlug = normalizeSlugForContent(slugInput || [], hostAtDocs);
-  const slug = needsSlugRewrite(normalizedSlug)
+  // Bare `/` or `/<lang>` roots render the first nav page but keep the alias URL;
+  // suppress hreflang on them (passed to buildSeoMetadata — see its isRootAlias
+  // doc for why).
+  const isRootAlias = needsSlugRewrite(normalizedSlug);
+  const slug = isRootAlias
     ? resolveSlug(normalizedSlug, await configP)
     : normalizedSlug;
   const pagePath = slug.join('/');
@@ -241,7 +252,7 @@ export async function buildDocMetadata(input: RenderInput): Promise<Metadata> {
   const baseUrl = resolveBaseUrl(requestHeaders, projectSlug, hostAtDocs);
   const languages = config.navigation?.languages;
 
-  const seoMetadata = buildSeoMetadata(config, data, pagePath, baseUrl, languages);
+  const seoMetadata = buildSeoMetadata(config, data, pagePath, baseUrl, languages, isRootAlias);
 
   const titleValue = data.title
     ? (data.title === config.name ? { absolute: data.title } : data.title)
@@ -601,6 +612,38 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
     </a>
   ) : null;
 
+  // Auto-mount the configured signup at the top of changelog (rss:true) pages
+  // when integrations.newsletter.placement === 'changelog'. Per-page frontmatter
+  // `newsletter: false` opts a single page out — verified safe: FrontmatterData
+  // declares `[key: string]: unknown`, so the custom `newsletter` key survives
+  // parsing into `data`. Manual <EmailSubscribe> in MDX is unaffected. NOTE: this
+  // mounts on EVERY rss:true page (multi-page rss is documented) — the per-page
+  // opt-out is the control for that.
+  let autoNewsletterProps = resolveAutoNewsletter(
+    data.rss,
+    config,
+    (data as { newsletter?: boolean }).newsletter,
+  );
+  // Dashboard-set title/subtitle fills any gap docs.json left — docs.json wins
+  // when both set a field. Gated to the only case it matters (auto-placement
+  // produced props), so the Redis read never touches non-changelog renders.
+  if (autoNewsletterProps && input.loadNewsletterDisplay) {
+    const dash = await input.loadNewsletterDisplay();
+    if (dash) {
+      autoNewsletterProps = {
+        ...autoNewsletterProps,
+        title: autoNewsletterProps.title ?? dash.title,
+        description: autoNewsletterProps.description ?? dash.description,
+      };
+    }
+  }
+  // An explicit <EmailSubscribe> in the page's MDX wins over auto-placement —
+  // otherwise a changelog author who hand-places the form would get two.
+  const autoEmailSubscribe =
+    autoNewsletterProps && !mdxHasEmailSubscribe(rawContent)
+      ? <EmailSubscribe {...autoNewsletterProps} />
+      : null;
+
   const contextualOptions = getContextualOptions(config);
   const hasAiActions = contextualOptions.length > 0;
   const apiMenuOptions = withApiSpecDownload(contextualOptions, {
@@ -774,6 +817,7 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
       )}
 
       <div className={proseClasses}>
+        {autoEmailSubscribe}
         {hasView ? <ViewWrapper>{mdxContent}</ViewWrapper> : mdxContent}
 
         {!embed && <PageNavigation currentSlug={slug.join('/')} config={config} isWideMode={isWideMode || hasPanel} />}

package/vendored/lib/seo.ts

@@ -606,6 +606,13 @@ function derivePageLocale(pagePath: string, languages?: LanguageConfig[]): strin
  * @param pagePath - The page path (e.g., "getting-started/installation")
  * @param baseUrl - The base URL (e.g., "https://docs.example.com")
  * @param languages - Optional array of language configurations for hreflang tags
+ * @param isRootAlias - True when the request is a bare `/` or `/<lang>` root that
+ *   renders the first nav page's content but keeps the alias URL. Such pages emit
+ *   `canonical` → the first page's URL (to consolidate the duplicate), so they must
+ *   NOT carry hreflang: hreflang on a canonicalized-away page is the Semrush
+ *   "Conflicting hreflang and rel=canonical" defect, and it can never self-reference
+ *   the alias URL ("No self-referencing hreflang"). The canonical target page emits
+ *   the full hreflang cluster, so language discovery is preserved.
  * @returns Partial<Metadata> to spread into generateMetadata return
  */
 export function buildSeoMetadata(
@@ -614,6 +621,7 @@ export function buildSeoMetadata(
   pagePath: string,
   baseUrl: string,
   languages?: LanguageConfig[],
+  isRootAlias = false,
 ): Partial<Metadata> {
   const globalMeta = config.seo?.metatags || {};
   const pageMeta = normalizePageMetatags(frontmatter as Record<string, unknown>);
@@ -684,8 +692,11 @@ export function buildSeoMetadata(
     canonical = pageUrl;
   }
 
-  // 7b. Hreflang alternates for multi-language support
-  const hreflangLanguages = buildHreflangAlternates(baseUrl, pagePath, languages || []);
+  // 7b. Hreflang alternates for multi-language support. Suppressed on root-alias
+  // pages — see the isRootAlias param doc above for why.
+  const hreflangLanguages = isRootAlias
+    ? undefined
+    : buildHreflangAlternates(baseUrl, pagePath, languages || []);
 
   metadata.alternates = {
     canonical,