jamdesk 1.1.142 → 1.1.144

package/vendored/components/mdx/NativeSubscribeForm.tsx

@@ -0,0 +1,172 @@
+// builder/build-service/components/mdx/NativeSubscribeForm.tsx
+'use client';
+
+import { useEffect, useState, type CSSProperties, type FormEvent } from 'react';
+
+export interface NativeSubscribeFormProps {
+  provider: string; // 'resend'
+  title?: string;
+  description?: string;
+  /** Start collapsed: a compact button that expands to the form on click. */
+  collapsed?: boolean;
+  className?: string;
+}
+
+// Solid primary button (the collapsed trigger and the form's submit share it).
+// Kept compact — the iOS 16px-min rule is for inputs, not buttons.
+const PRIMARY_BUTTON: CSSProperties = {
+  fontSize: '0.875rem', padding: '0.4rem 0.85rem', border: 0,
+  borderRadius: '0.375rem', cursor: 'pointer',
+  background: 'var(--color-primary, #2563eb)', color: '#fff',
+};
+
+// Inline text button for the "use a different email" escape hatch.
+const LINK_BUTTON: CSSProperties = {
+  background: 'none', border: 0, padding: 0, color: 'var(--color-primary, #2563eb)',
+  cursor: 'pointer', textDecoration: 'underline', font: 'inherit',
+};
+
+/** Site-wide "this visitor already subscribed" flag. Per-origin (localStorage is
+ *  already scoped to the published site), so one signup is remembered across
+ *  every changelog page rather than re-nagging the same reader. */
+const SUBSCRIBED_KEY = 'jd_subscribed';
+
+function readSubscribed(): boolean {
+  try {
+    return typeof window !== 'undefined' &&
+      window.localStorage.getItem(SUBSCRIBED_KEY) === '1';
+  } catch {
+    // Private-mode / storage-disabled: fail open (show the form).
+    return false;
+  }
+}
+
+function rememberSubscribed(): void {
+  try {
+    window.localStorage.setItem(SUBSCRIBED_KEY, '1');
+  } catch {
+    // Best-effort — a storage failure just means we re-show next visit.
+  }
+}
+
+/** Same-origin endpoint. Hosted-at-/docs sites serve the signup under /docs,
+ *  mirroring useChat's `/docs/_chat` swap (builder/cli/vendored/hooks/useChat.ts). */
+function subscribeEndpoint(): string {
+  if (typeof window !== 'undefined' && window.location.pathname.startsWith('/docs')) {
+    return '/docs/_jd/subscribe';
+  }
+  return '/_jd/subscribe';
+}
+
+/**
+ * On-brand, first-party signup form for native-capture providers (Resend). Posts
+ * the email to Jamdesk's same-origin /_jd/subscribe; the customer's API key stays
+ * server-side. No third-party script — safe to render anywhere the live component
+ * renders (published ISR + CLI dev; the editor uses the placeholder).
+ *
+ * Two display refinements, native-only (we control this DOM, unlike vendor
+ * embeds):
+ *   - `collapsed`: render a compact button that expands to the form on click.
+ *   - Already-subscribed memory: once a visitor subscribes, every later mount
+ *     shows a one-line "you're subscribed" with a "use a different email" escape
+ *     hatch instead of the full form. The flag is read AFTER mount (useEffect)
+ *     so SSR/first-paint stays deterministic and hydration never mismatches.
+ */
+export function NativeSubscribeForm({ provider, title, description, collapsed, className }: NativeSubscribeFormProps) {
+  const [email, setEmail] = useState('');
+  const [status, setStatus] = useState<'idle' | 'submitting' | 'done' | 'error'>('idle');
+  // Set after mount only — keeps the server/first-client render deterministic.
+  const [remembered, setRemembered] = useState(false);
+  // The visitor explicitly opened the form (collapsed trigger or "different email").
+  const [forceOpen, setForceOpen] = useState(false);
+
+  useEffect(() => {
+    if (readSubscribed()) setRemembered(true);
+  }, []);
+
+  async function onSubmit(e: FormEvent<HTMLFormElement>) {
+    e.preventDefault();
+    if (status === 'submitting') return;
+    const jd_hp = (e.currentTarget.elements.namedItem('jd_hp') as HTMLInputElement | null)?.value ?? '';
+    setStatus('submitting');
+    try {
+      const res = await fetch(subscribeEndpoint(), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email, jd_hp, provider }),
+      });
+      if (res.ok) {
+        rememberSubscribed();
+        setRemembered(true);
+        setStatus('done');
+      } else {
+        setStatus('error');
+      }
+    } catch {
+      setStatus('error');
+    }
+  }
+
+  const wrapperClass = `jd-emailsubscribe not-prose my-6 ${className ?? ''}`.trim();
+
+  if (status === 'done') {
+    return (
+      <div className={wrapperClass} role="status">
+        {title && <p className="mb-1 font-semibold text-theme-text-primary">{title}</p>}
+        <p className="text-sm text-theme-text-secondary">Thanks — you&rsquo;re subscribed.</p>
+      </div>
+    );
+  }
+
+  // Already-subscribed wins over the collapsed trigger: a returning subscriber
+  // sees the status line, not a generic "Subscribe" button.
+  if (remembered && !forceOpen) {
+    return (
+      <div className={wrapperClass}>
+        <p className="text-sm text-theme-text-secondary">
+          You&rsquo;re subscribed to the newsletter.{' '}
+          <button type="button" onClick={() => { setEmail(''); setStatus('idle'); setForceOpen(true); }}
+            style={LINK_BUTTON}>
+            Use a different email?
+          </button>
+        </p>
+      </div>
+    );
+  }
+
+  // Collapsed: a compact button standing in for the whole form until clicked.
+  if (collapsed && !forceOpen) {
+    return (
+      <div className={wrapperClass}>
+        <button type="button" onClick={() => setForceOpen(true)} style={PRIMARY_BUTTON}>
+          {title || 'Subscribe to updates'}
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div className={wrapperClass}>
+      {title && <p className="mb-1 font-semibold text-theme-text-primary">{title}</p>}
+      {description && <p className="mb-3 text-sm text-theme-text-secondary">{description}</p>}
+      <form onSubmit={onSubmit} style={{ display: 'flex', gap: '0.5rem', flexWrap: 'wrap', alignItems: 'center', maxWidth: '28rem' }}>
+        {/* Honeypot: a deliberately odd name (NOT website/url/email, which password
+            managers autofill — a filled honeypot silently drops a real user). Bots
+            fill it; humans can't see it. Off-screen + aria-hidden + tabIndex -1. */}
+        <input type="text" name="jd_hp" tabIndex={-1} autoComplete="off" aria-hidden="true"
+          defaultValue="" style={{ position: 'absolute', left: '-5000px' }} />
+        {/* font-size:16px avoids iOS auto-zoom (monorepo UI rule). */}
+        <input type="email" name="email" required value={email}
+          onChange={(e) => { setEmail(e.target.value); if (status === 'error') setStatus('idle'); }}
+          disabled={status === 'submitting'} placeholder="you@example.com" aria-label="Email address"
+          style={{ flex: 1, minWidth: 0, fontSize: '16px', padding: '0.4rem 0.75rem', border: '1px solid var(--color-border, #d4d4d8)', borderRadius: '0.375rem', background: 'var(--color-bg-primary, #fff)', color: 'var(--color-text-primary, #18181b)' }} />
+        <button type="submit" disabled={status === 'submitting'} style={PRIMARY_BUTTON}>
+          {status === 'submitting' ? 'Subscribing…' : 'Subscribe'}
+        </button>
+      </form>
+      {status === 'error' && (
+        <p className="mt-2 text-sm text-amber-700 dark:text-amber-400" role="alert">Something went wrong. Please try again.</p>
+      )}
+    </div>
+  );
+}

package/vendored/components/navigation/Header.tsx

@@ -6,7 +6,7 @@ import Link from 'next/link';
 import { usePathname } from 'next/navigation';
 // Icons use Font Awesome CSS classes for lightweight rendering
 import type { DocsConfig, TabsPosition } from '@/lib/docs-types';
-import { normalizeLogo, getIconName } from '@/lib/docs-types';
+import { normalizeLogo, getIconString } from '@/lib/docs-types';
 import type { LayoutVariant } from '@/themes';
 import { getTheme } from '@/themes';
 import { ThemeToggle } from '@/components/theme/ThemeToggle';
@@ -136,7 +136,7 @@ export function Header({ config, layout = 'header-logo', tabsPosition: tabsPosit
     if (!hasTabs) return [];
 
     return navigationTabs.map((tab) => {
-      const iconName = getIconName(tab.icon);
+      const iconName = getIconString(tab.icon);
 
       // For external tabs, use the href directly
       if (tab.href && !tab.groups && !tab.pages) {
@@ -489,7 +489,7 @@ export function Header({ config, layout = 'header-logo', tabsPosition: tabsPosit
                       rel={isExternal ? 'noopener noreferrer' : undefined}
                       className="flex items-center gap-1.5 px-2.5 py-1.5 text-sm text-[var(--color-text-tertiary)] hover:text-[var(--color-text-primary)] transition-colors"
                     >
-                      {link.icon && <i className={`${getIconClass(getIconName(link.icon))} text-[14px]`} aria-hidden="true" />}
+                      {link.icon && <i className={`${getIconClass(getIconString(link.icon))} text-[14px]`} aria-hidden="true" />}
                       <span>{resolveLabel(link.label, link.labels)}</span>
                       {isExternal && <i className="fa-solid fa-arrow-up-right-from-square text-[10px] opacity-50" aria-hidden="true" />}
                     </a>
@@ -564,6 +564,7 @@ export function Header({ config, layout = 'header-logo', tabsPosition: tabsPosit
           isOpen={isSearchOpen}
           onClose={() => setIsSearchOpen(false)}
           popularPages={config.search?.popularPages}
+          placeholder={config.search?.prompt}
         />
       )}
       {searchDevNotice}

package/vendored/components/search/SearchModal.tsx

@@ -12,11 +12,13 @@ import { useProjectSlug } from '@/lib/project-slug-context';
 import type { SearchResult, SearchGroup } from '@/lib/search-client';
 import { useChatPanelOptional } from '@/hooks/useChatPanel';
 import { modifierKeyLabel } from '@/lib/platform-keys';
+import { getIconString, type IconConfig } from '@/lib/docs-types';
+import { getIconClass } from '@/lib/icon-utils';
 
 interface PopularPage {
   title: string;
   slug: string;
-  icon?: string;
+  icon?: IconConfig;
 }
 
 interface SearchModalProps {
@@ -24,10 +26,14 @@ interface SearchModalProps {
   onClose: () => void;
   popularPages?: PopularPage[];
   onNavigate?: (url: string) => void;
+  /** Custom placeholder for the search input (docs.json `search.prompt`) */
+  placeholder?: string;
 }
 
 const DEBOUNCE_MS = 150;
 
+const DEFAULT_SEARCH_PLACEHOLDER = 'Search documentation…';
+
 // Default popular pages fallback
 const DEFAULT_POPULAR_PAGES: PopularPage[] = [
   { title: 'Quick Start', slug: 'quickstart', icon: 'rocket' },
@@ -135,7 +141,7 @@ function countVisibleResults(rows: SearchRow[]): number {
   return rows.reduce((n, r) => (r.kind === 'expander' ? n : n + 1), 0);
 }
 
-export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: SearchModalProps) {
+export function SearchModal({ isOpen, onClose, popularPages, onNavigate, placeholder }: SearchModalProps) {
   const linkPrefix = useLinkPrefix();
   const projectSlug = useProjectSlug();
   const chatPanel = useChatPanelOptional();
@@ -522,7 +528,7 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
             <input
               ref={inputRef}
               type="search"
-              placeholder="Search documentation…"
+              placeholder={placeholder || DEFAULT_SEARCH_PLACEHOLDER}
               value={query}
               onChange={(e) => setQuery(e.target.value)}
               className="flex-1 bg-transparent text-[var(--color-text-primary)] placeholder-[var(--color-text-muted)] outline-none text-base [&::-webkit-search-cancel-button]:appearance-none [&::-webkit-search-decoration]:appearance-none"
@@ -703,7 +709,7 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
                               : 'hover:bg-[var(--color-bg-secondary)]'
                           }`}
                         >
-                          <i className={`fa-light fa-${page.icon || 'file-lines'} text-sm text-[var(--color-text-muted)]`} aria-hidden="true" />
+                          <i className={`${getIconClass(getIconString(page.icon))} text-sm text-[var(--color-text-muted)]`} aria-hidden="true" />
                           <span className="text-sm text-[var(--color-text-primary)] truncate">{page.title}</span>
                         </button>
                       ))}

package/vendored/lib/docs-types.ts

@@ -614,6 +614,35 @@ export interface StylingConfig {
 // INTEGRATIONS
 // =============================================================================
 
+/**
+ * Customer-facing newsletter / changelog-notification signup (rendered by
+ * <EmailSubscribe>). Fields mirror EmailSubscribeProps (see
+ * lib/email-subscribe-providers.ts); `placement` opts into auto-rendering on
+ * changelog (`rss: true`) pages.
+ *
+ * NOTE: distinct from the dashboard's internal `addUserToResendNewsletter`
+ * (Jamdesk's own signup list) — this is per docs-project config.
+ */
+export interface NewsletterConfig {
+  /** Shorthand provider: mailchimp | buttondown | substack | beehiiv (v1). */
+  provider?: string;
+  /** Mailchimp: full form POST action URL. */
+  action?: string;
+  /** Buttondown / Substack: account username. */
+  username?: string;
+  /** Beehiiv: full iframe embed src URL. */
+  src?: string;
+  /** Raw embed snippet (any vendor) — escape hatch. */
+  snippet?: string;
+  /** iframe height in px for iframe providers (substack/beehiiv). */
+  height?: number;
+  /** Optional heading shown above the embed. */
+  title?: string;
+  description?: string;
+  /** 'changelog' auto-mounts on `rss: true` pages; 'none' (default) = manual. */
+  placement?: 'none' | 'changelog';
+}
+
 /**
  * Analytics and integration configurations (stubs - TODO: implement)
  */
@@ -629,6 +658,7 @@ export interface IntegrationsConfig {
   hightouch?: { writeKey: string; apiHost?: string };
   hotjar?: { hjid: string; hjsv: string };
   crisp?: { websiteId: string };
+  newsletter?: NewsletterConfig;
   intercom?: { appId: string };
   koala?: { publicApiKey: string };
   logrocket?: { appId: string };
@@ -655,7 +685,7 @@ export interface SearchConfig {
   popularPages?: Array<{
     title: string;
     slug: string;
-    icon?: string;
+    icon?: IconConfig;
   }>;
 }
 
@@ -930,7 +960,7 @@ export function normalizeNavPage(page: NavigationPage): {
       .pop()
       ?.replace(/-/g, ' ')
       .replace(/\b\w/g, (l) => l.toUpperCase()) || page.page,
-    icon: getIconName(page.icon),
+    icon: getIconString(page.icon),
     tag: page.tag,
   };
 }
@@ -994,6 +1024,19 @@ export function getIconName(icon: IconConfig | undefined): string | undefined {
   return icon.name;
 }
 
+/**
+ * Flatten an icon config to the string getIconClass() understands, preserving
+ * the Font Awesome style as a "style/name" prefix (every IconStyle value is a
+ * getIconClass style prefix). Use this — not getIconName — wherever an icon is
+ * rendered, so a configured `style` survives the flatten. `library` is
+ * intentionally dropped: all icons render via Font Awesome.
+ */
+export function getIconString(icon: IconConfig | undefined): string | undefined {
+  if (!icon) return undefined;
+  if (typeof icon === 'string') return icon;
+  return icon.style ? `${icon.style}/${icon.name}` : icon.name;
+}
+
 /**
  * Get icon library from config
  */

package/vendored/lib/email-subscribe-autoplacement.ts

@@ -0,0 +1,46 @@
+// builder/build-service/lib/email-subscribe-autoplacement.ts
+import type { EmailSubscribeProps } from './email-subscribe-providers';
+
+/** Structural shape of the slice of config this resolver reads. Declared locally
+ *  so Task 2 type-checks on its own, WITHOUT waiting for Task 5 to add
+ *  `IntegrationsConfig.newsletter` — the real `DocsConfig` is structurally
+ *  assignable to this, so render-doc-page (Task 6) can pass its full config. */
+type NewsletterLike = EmailSubscribeProps & { placement?: 'none' | 'changelog' };
+
+/**
+ * Decide whether a changelog (`rss: true`) page should auto-render the
+ * configured signup. Returns the EmailSubscribe props (placement stripped) when
+ * `integrations.newsletter.placement === 'changelog'`, else null. Pure — so the
+ * gating is unit-tested without rendering the whole page.
+ */
+export function resolveAutoNewsletter(
+  rss: boolean | undefined,
+  config: { integrations?: { newsletter?: NewsletterLike } },
+  pageNewsletter?: boolean,
+): EmailSubscribeProps | null {
+  // Per-page escape hatch: frontmatter `newsletter: false` suppresses the
+  // configured auto-placement on THIS page (e.g. a non-changelog page that
+  // happens to set rss:true, or a localized changelog placing its own translated
+  // <EmailSubscribe>). Only an explicit `false` opts out.
+  if (pageNewsletter === false) return null;
+  const n = config.integrations?.newsletter;
+  if (!rss || !n || n.placement !== 'changelog') return null;
+  const { placement: _placement, ...props } = n;
+  void _placement;
+  return props;
+}
+
+/** True when the page's raw MDX already hand-places an `<EmailSubscribe>` tag.
+ *  Used to suppress auto-placement so an explicit author form isn't doubled.
+ *
+ *  Code is stripped first — fenced blocks (```…```) then inline spans (`…`) — so
+ *  a page that merely *documents* the component (a changelog entry or guide
+ *  showing `<EmailSubscribe />` in an example) isn't mistaken for a hand-placed
+ *  form and wrongly suppress its own `placement: changelog` auto-mount.
+ *  The trailing char class avoids matching `<EmailSubscribeFoo`. */
+export function mdxHasEmailSubscribe(rawContent: string): boolean {
+  const withoutCode = rawContent
+    .replace(/```[\s\S]*?```/g, '')
+    .replace(/`[^`\n]+`/g, '');
+  return /<EmailSubscribe[\s/>]/.test(withoutCode);
+}

package/vendored/lib/email-subscribe-providers.ts

@@ -0,0 +1,120 @@
+// builder/build-service/lib/email-subscribe-providers.ts
+import { NATIVE_PROVIDER_IDS } from './newsletter/descriptors';
+
+/**
+ * Props accepted by <EmailSubscribe> and (minus styling-only fields) by the
+ * docs.json `integrations.newsletter` block. All optional — the resolver
+ * decides what's renderable.
+ */
+export interface EmailSubscribeProps {
+  /** Shorthand provider key (case-insensitive). */
+  provider?: string;
+  /** Mailchimp: full form POST `action` URL. */
+  action?: string;
+  /** Buttondown / Substack: account username. */
+  username?: string;
+  /** Beehiiv: full iframe embed `src` URL. */
+  src?: string;
+  /** Raw embed snippet (any vendor) — escape hatch, takes priority. */
+  snippet?: string;
+  /** iframe height in px for iframe providers (substack/beehiiv). */
+  height?: number;
+  /** Optional on-brand heading above the embed. */
+  title?: string;
+  description?: string;
+  /** Start collapsed: render a compact "Subscribe" button that expands to the
+   *  full form on click (native providers only — embeds can't be controlled). */
+  collapsed?: boolean;
+  /** Extra class on the wrapper. */
+  className?: string;
+}
+
+export type ResolvedEmbed =
+  | { kind: 'snippet'; html: string }
+  | { kind: 'native'; provider: string }          // Phase 2: real form + capture endpoint
+  | { kind: 'native-pending'; provider: string }  // API-only, no native path yet
+  | { kind: 'none'; reason: string };
+
+/** API-only ESPs with no native path yet — friendly notice, never an error. */
+const NATIVE_PENDING_PROVIDERS = new Set(['mailersend']);
+
+/** Escape a user value before interpolating into an HTML attribute so a stray
+ *  quote/angle-bracket can't break out of the attribute or inject a tag.
+ *  Escapes single quotes too, so it stays safe even if an attribute is later
+ *  switched to single-quoted. */
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+const EMAIL_INPUT =
+  '<input type="email" name="EMAIL" required placeholder="you@example.com" ' +
+  'aria-label="Email address" ' +
+  'style="flex:1;min-width:0;font-size:16px;padding:0.5rem 0.75rem;border:1px solid var(--color-border, #d4d4d8);border-radius:0.375rem;background:var(--color-bg-primary, #fff);color:var(--color-text-primary, #18181b)" />';
+
+const SUBMIT_BUTTON =
+  '<button type="submit" ' +
+  'style="font-size:16px;padding:0.5rem 1rem;border:0;border-radius:0.375rem;cursor:pointer;background:var(--color-primary, #2563eb);color:#fff">Subscribe</button>';
+
+function formShell(action: string, emailName: string, target: string): string {
+  // `font-size:16px` on the input avoids iOS auto-zoom (monorepo UI rule).
+  // escapeAttr defends the field name even though callers pass literals today —
+  // a future provider deriving emailName from config can't inject an attribute.
+  const input = EMAIL_INPUT.replace('name="EMAIL"', `name="${escapeAttr(emailName)}"`);
+  return (
+    `<form action="${action}" method="post" target="${target}" ` +
+    `style="display:flex;gap:0.5rem;flex-wrap:wrap;align-items:center;max-width:28rem">` +
+    input +
+    SUBMIT_BUTTON +
+    `</form>`
+  );
+}
+
+function iframe(src: string, height: number): string {
+  // Height is provider-defaulted + author-overridable (`height` prop): a single
+  // magic number clips Substack's taller widget or pads Beehiiv's compact one.
+  return (
+    `<iframe src="${src}" width="100%" height="${height}" frameborder="0" scrolling="no" ` +
+    `title="Subscribe" style="border:0;background:transparent;max-width:28rem"></iframe>`
+  );
+}
+
+/** Provider shorthands whose markup is fully reconstructable from documented,
+ *  stable inputs. Mailchimp and beehiiv were here pre-native; they are now
+ *  handled by the NATIVE_PROVIDER_IDS branch above. */
+const PROVIDER_BUILDERS: Record<string, (p: EmailSubscribeProps) => ResolvedEmbed> = {
+  buttondown(p) {
+    if (!p.username) return { kind: 'none', reason: 'buttondown requires a "username"' };
+    const action = `https://buttondown.com/api/emails/embed-subscribe/${encodeURIComponent(p.username)}`;
+    return { kind: 'snippet', html: formShell(escapeAttr(action), 'email', 'popupwindow') };
+  },
+  substack(p) {
+    if (!p.username) return { kind: 'none', reason: 'substack requires a "username"' };
+    const sub = encodeURIComponent(p.username);
+    return { kind: 'snippet', html: iframe(escapeAttr(`https://${sub}.substack.com/embed`), p.height ?? 320) };
+  },
+};
+
+/** Turn EmailSubscribe props into a renderable embed decision. Pure. */
+export function resolveEmailSubscribeEmbed(p: EmailSubscribeProps): ResolvedEmbed {
+  if (p.snippet && p.snippet.trim()) return { kind: 'snippet', html: p.snippet };
+
+  const provider = p.provider?.trim().toLowerCase();
+  if (!provider) return { kind: 'none', reason: 'no provider or snippet specified' };
+  // Migration note: sites whose docs.json still says provider:"mailchimp"/"beehiiv"
+  // now resolve to a native form. With no dashboard creds the submission returns the
+  // uniform 404 and the form shows a neutral message. Owners must configure the
+  // provider in the dashboard (agreed native-replaces-embed migration).
+  if (NATIVE_PROVIDER_IDS.has(provider)) return { kind: 'native', provider };
+  if (NATIVE_PENDING_PROVIDERS.has(provider)) return { kind: 'native-pending', provider };
+
+  const builder = PROVIDER_BUILDERS[provider];
+  if (!builder) {
+    return { kind: 'none', reason: `provider "${provider}" has no shorthand — paste its embed via the "snippet" prop` };
+  }
+  return builder(p);
+}

package/vendored/lib/middleware-helpers.ts

@@ -393,6 +393,7 @@ export const INTERNAL_API_ROUTES = [
   '/api/r2',          // R2 content serving (app/api/r2/[project]/[...path]) — gated explicitly in proxy.ts
   '/api/revalidate',  // Cache revalidation (app/api/revalidate)
   '/api/search-ev',   // Search analytics proxy (app/api/search-ev)
+  '/api/subscribe',   // Newsletter subscribe endpoint (app/api/subscribe/[project]) — gated by Origin in route
   // NOTE: /api/jd is intentionally NOT here — /api/jd/unlock reads
   // x-project-slug + x-host-at-docs headers that middleware sets.
   // NOTE: /api/markdown-export is intentionally NOT here either — it serves
@@ -553,6 +554,26 @@ export function getChatApiPath(projectSlug: string): string {
   return `/api/chat/${projectSlug}`;
 }
 
+/**
+ * Check if this is a newsletter subscribe request that needs routing.
+ *
+ * @param pathname - Request pathname
+ * @returns true if this is a subscribe request
+ */
+export function isSubscribeRequest(pathname: string): boolean {
+  return pathname === '/_jd/subscribe' || pathname === '/docs/_jd/subscribe';
+}
+
+/**
+ * Get the subscribe API path for a project.
+ *
+ * @param projectSlug - Project identifier
+ * @returns Subscribe API route path
+ */
+export function getSubscribeApiPath(projectSlug: string): string {
+  return `/api/subscribe/${projectSlug}`;
+}
+
 /**
  * Check if this is a docs search request that needs routing.
  *

package/vendored/lib/navigation-resolver.ts

@@ -18,7 +18,7 @@ import type {
   ExternalAnchorConfig,
 } from './docs-types';
 
-import { normalizeNavPage, getIconName } from './docs-types';
+import { normalizeNavPage, getIconString } from './docs-types';
 import { getLanguageDisplayInfo, extractLanguageFromPath } from './language-utils';
 import { evictOldest } from './cache-utils';
 
@@ -225,7 +225,7 @@ function resolveGroup(group: GroupConfig): ResolvedGroup {
 
   return {
     name: group.group,
-    icon: getIconName(group.icon),
+    icon: getIconString(group.icon),
     tag: group.tag,
     pages: resolvedPages,
     expanded: group.expanded,
@@ -268,7 +268,7 @@ function resolveTabGroups(tab: TabConfig): ResolvedGroup[] {
 function resolveTab(tab: TabConfig): ResolvedTab {
   return {
     name: tab.tab,
-    icon: getIconName(tab.icon),
+    icon: getIconString(tab.icon),
     href: tab.href,
     isExternal: !!tab.href && !tab.groups && !tab.pages,
   };
@@ -465,7 +465,7 @@ export function resolveNavigation(
       .map((anchor: ExternalAnchorConfig) => ({
         name: anchor.name,
         href: anchor.href,
-        icon: getIconName(anchor.icon),
+        icon: getIconString(anchor.icon),
       }));
   }
 
@@ -476,7 +476,7 @@ export function resolveNavigation(
       result.externalAnchors.push({
         name: anchor.anchor,
         href: anchor.href,
-        icon: getIconName(anchor.icon),
+        icon: getIconString(anchor.icon),
       });
     }
   }

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

@@ -0,0 +1,23 @@
+import type { NewsletterAdapter, NewsletterCreds } from '../types';
+import { getDescriptor } from '../descriptors';
+import { fetchJson } from '../http';
+
+const BASE = 'https://api.beehiiv.com/v2';
+const headers = (secret: string) => ({ Authorization: `Bearer ${secret}`, 'content-type': 'application/json' });
+
+export const beehiivAdapter: NewsletterAdapter = {
+  descriptor: getDescriptor('beehiiv')!,
+  async validate(creds: NewsletterCreds) {
+    if (!creds.publicationId) return { ok: false, reason: 'publicationId required' };
+    const { status } = await fetchJson(`${BASE}/publications/${creds.publicationId}`, { method: 'GET', headers: headers(creds.secret) });
+    return status === 200 ? { ok: true } : { ok: false, reason: `publication ${status}` };
+  },
+  async addContact(email: string, creds: NewsletterCreds) {
+    if (!creds.publicationId) return { ok: false, code: 'misconfigured' };
+    const { status } = await fetchJson(`${BASE}/publications/${creds.publicationId}/subscriptions`, {
+      method: 'POST', headers: headers(creds.secret),
+      body: JSON.stringify({ email, reactivate_existing: false, send_welcome_email: false }),
+    });
+    return status >= 200 && status < 300 ? { ok: true } : { ok: false, status };
+  },
+};

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

@@ -0,0 +1,31 @@
+import type { NewsletterAdapter, NewsletterCreds } from '../types';
+import { getDescriptor } from '../descriptors';
+import { fetchJson } from '../http';
+
+const BASE = 'https://api.brevo.com/v3';
+const headers = (secret: string) => ({ 'api-key': secret, 'content-type': 'application/json' });
+
+export const brevoAdapter: NewsletterAdapter = {
+  descriptor: getDescriptor('brevo')!,
+  async validate(creds: NewsletterCreds) {
+    if (!creds.listId) return { ok: false, reason: 'listId required' };
+    // Probe the LIST, not just /account: a valid key with a wrong listId would
+    // pass /account but then drop every signup. GET the list to prove both.
+    const { status } = await fetchJson(`${BASE}/contacts/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, json } = await fetchJson(`${BASE}/contacts`, {
+      method: 'POST', headers: headers(creds.secret),
+      // updateEnabled:false → never silently re-subscribes a contact who opted out.
+      body: JSON.stringify({ email, listIds: [Number(creds.listId)], updateEnabled: false }),
+    });
+    if (status >= 200 && status < 300) return { ok: true };
+    // A returning subscriber already on the list → idempotent success, not error.
+    const code = (json as { code?: string } | null)?.code;
+    if (status === 400 && code === 'duplicate_parameter') return { ok: true };
+    return { ok: false, status };
+  },
+};