jamdesk 1.1.142 → 1.1.143

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,

package/vendored/lib/validate-content-images.ts

@@ -0,0 +1,150 @@
+/**
+ * Content Image Validation (build-service)
+ *
+ * Warns when a local image referenced from page/snippet MDX — markdown
+ * `![alt](/images/foo.webp)`, `<img src="…">`, `<Image src="…">` — points at a
+ * file that isn't in the project's collected assets. Emits non-blocking
+ * `missing_image` BuildWarning entries.
+ *
+ * Nothing else in the build covers this: validate-links.cjs skips asset
+ * extensions and the WebP converter silently ignores missing references, so a
+ * typo'd or never-uploaded image otherwise ships and only 404s in a reader's
+ * browser.
+ *
+ * PARITY TWIN of the CLI's `builder/cli/src/lib/validate-image-refs.ts` — the
+ * two run on different surfaces (in-memory maps here, filesystem walk there) so
+ * they can't share a module, but their DETECTION must agree so `jamdesk
+ * validate` and the cloud build flag the same references. The extraction
+ * (stripCodeRegions + the two regexes + the external/data skip) is copied from
+ * that file verbatim; keep them in sync. This build-service copy adds two
+ * build-only concerns the CLI lacks: resolution against the already-collected
+ * asset list (instead of fs), and convertToWebp awareness (a `.webp` reference
+ * backed by a `.png`/`.jpg` source is valid once the converter runs).
+ */
+
+import path from 'path';
+import { normalizeAssetPath } from './isr-build-executor.js';
+import type { BuildWarning } from '../shared/status-reporter.js';
+
+export interface ValidateContentImagesOptions {
+  /** When docs.json images.convertToWebp is on, a `.webp` reference is served
+   *  from a `.png`/`.jpg` source — accept those so conversion isn't flagged. */
+  convertToWebp?: boolean;
+  /** Max warnings to return (Firestore document-size guard). Default 50. */
+  cap?: number;
+}
+
+const CONVERTIBLE_EXT_RE = /\.(png|jpe?g)$/i;
+
+// --- Extraction (kept identical to the CLI twin) -----------------------------
+
+function isExternalOrDataUrl(src: string): boolean {
+  return (
+    src.startsWith('http://') ||
+    src.startsWith('https://') ||
+    src.startsWith('//') ||
+    src.startsWith('data:')
+  );
+}
+
+/**
+ * Blank out MDX regions that hold non-rendered content — HTML comments, JSX
+ * comments, fenced code blocks, inline code spans — replacing them with spaces
+ * of equal length so reported line numbers stay accurate. Image-like syntax
+ * inside these is illustrative (a tutorial showing `![alt](path)`), not a real
+ * reference, and flagging it would be a false positive.
+ */
+function stripCodeRegions(content: string): string {
+  const blank = (m: string) => m.replace(/[^\n]/g, ' ');
+  let out = content.replace(/<!--[\s\S]*?-->/g, blank);
+  out = out.replace(/\{\s*\/\*(?:(?!\*\/)[\s\S])*?\*\/\s*\}/g, blank);
+  out = out.replace(/(^|\n)[ \t]*(```|~~~)[^\n]*\n([\s\S]*?)\n[ \t]*\2(?=\n|$)/g, blank);
+  out = out.replace(/`[^`\n]+`/g, blank);
+  return out;
+}
+
+function extractImageRefs(content: string): { src: string; line: number }[] {
+  const refs: { src: string; line: number }[] = [];
+  const scan = stripCodeRegions(content);
+
+  // <img src="…"> / <Image src="…"> — string literal only (skips {expr}).
+  const jsxRegex = /<(?:img|Image)\b[^>]*?\bsrc\s*=\s*(["'])([^"'{}]+?)\1/gi;
+  // Markdown ![alt](path) — capture path before an optional title.
+  const mdRegex = /!\[[^\]]*\]\(\s*<?([^)\s<>]+)>?(?:\s+["'][^"']*["'])?\s*\)/g;
+
+  const indexToLine = (idx: number): number => {
+    let line = 1;
+    for (let i = 0; i < idx; i++) if (scan.charCodeAt(i) === 10) line++;
+    return line;
+  };
+
+  for (const m of scan.matchAll(jsxRegex)) refs.push({ src: m[2], line: indexToLine(m.index ?? 0) });
+  for (const m of scan.matchAll(mdRegex)) refs.push({ src: m[1], line: indexToLine(m.index ?? 0) });
+  return refs;
+}
+
+// --- Resolution (build-service: against the collected asset list) ------------
+
+/** Resolve a reference to the same key shape as collected asset paths
+ *  (public/ stripped). Absolute `/x` is project-rooted; a relative ref is
+ *  resolved against the referencing file's directory. */
+function resolveKey(fileKey: string, src: string): string | null {
+  const clean = src.split(/[?#]/)[0];
+  if (!clean) return null;
+  const rel = clean.startsWith('/')
+    ? clean.slice(1)
+    : path.posix.normalize(path.posix.join(path.posix.dirname(fileKey), clean));
+  return normalizeAssetPath(rel.replace(/^\/+/, ''));
+}
+
+/**
+ * @param fileContents - path -> MDX content (pages keyed by relative path,
+ *   snippets by `snippets/<name>`), as assembled in build.ts.
+ * @param assetFiles - asset paths relative to project dir (from collectAssetFiles).
+ */
+export function validateContentImages(
+  fileContents: Map<string, string>,
+  assetFiles: string[],
+  options: ValidateContentImagesOptions = {},
+): BuildWarning[] {
+  const cap = options.cap ?? 50;
+
+  const assetSet = new Set(assetFiles.map(normalizeAssetPath));
+  if (options.convertToWebp) {
+    for (const asset of assetFiles) {
+      const normalized = normalizeAssetPath(asset);
+      if (CONVERTIBLE_EXT_RE.test(normalized)) {
+        assetSet.add(normalized.replace(CONVERTIBLE_EXT_RE, '.webp'));
+      }
+    }
+  }
+
+  const warnings: BuildWarning[] = [];
+  const seen = new Set<string>();
+
+  for (const [file, content] of fileContents) {
+    if (warnings.length >= cap) break;
+    for (const { src, line } of extractImageRefs(content)) {
+      if (warnings.length >= cap) break;
+      const trimmed = src.trim();
+      if (!trimmed || isExternalOrDataUrl(trimmed)) continue;
+
+      const key = resolveKey(file, trimmed);
+      if (key === null || assetSet.has(key)) continue;
+
+      const dedupeKey = `${file}|${key}`;
+      if (seen.has(dedupeKey)) continue;
+      seen.add(dedupeKey);
+
+      warnings.push({
+        type: 'missing_image',
+        file,
+        line,
+        link: trimmed,
+        message: `Image "${trimmed}" referenced in ${file} was not found in the project`,
+      });
+    }
+  }
+
+  return warnings;
+}

package/vendored/schema/docs-schema.json

@@ -1158,6 +1158,34 @@
                             ],
                             "additionalProperties": false
                         },
+                        "newsletter": {
+                            "type": "object",
+                            "description": "Inline newsletter / changelog-notification signup rendered by <EmailSubscribe>. Customer owns the list and sending.",
+                            "properties": {
+                                "provider": {
+                                    "type": "string",
+                                    "enum": ["resend", "mailchimp", "kit", "loops", "beehiiv", "brevo", "sendgrid", "buttondown", "substack"],
+                                    "description": "Newsletter provider. Native providers (resend, mailchimp, kit, loops, beehiiv, brevo, sendgrid) are configured in the dashboard (Settings → Email signups) and render a Jamdesk-hosted capture form. buttondown and substack are embed-only — supply a \"username\" to render their iframe/form."
+                                },
+                                "action": { "type": "string", "description": "Mailchimp: full form POST action URL." },
+                                "username": { "type": "string", "description": "Buttondown / Substack account username." },
+                                "src": { "type": "string", "description": "Beehiiv: full iframe embed src URL." },
+                                "snippet": { "type": "string", "description": "Raw embed snippet (any vendor) — escape hatch." },
+                                "height": { "type": "number", "description": "iframe height in px for substack/beehiiv embeds." },
+                                "title": { "type": "string" },
+                                "description": { "type": "string" },
+                                "collapsed": {
+                                    "type": "boolean",
+                                    "description": "Native providers only: render a compact Subscribe button that expands to the form on click, instead of the full email box."
+                                },
+                                "placement": {
+                                    "type": "string",
+                                    "enum": ["none", "changelog"],
+                                    "description": "'changelog' auto-mounts on rss:true pages; 'none' (default) = manual <EmailSubscribe>."
+                                }
+                            },
+                            "additionalProperties": false
+                        },
                         "intercom": {
                             "type": "object",
                             "properties": {

package/vendored/shared/status-reporter.ts

@@ -22,7 +22,7 @@ export interface ProgressUpdate {
 }
 
 /** Warning types that can occur during builds (non-blocking) */
-export type BuildWarningType = 'broken_link' | 'auto_migrate' | 'missing_asset' | 'missing_page' | 'missing_openapi_ref' | 'inline_code_on_api_page' | 'invalid_openapi_spec' | 'missing_snippet' | 'risky_expression' | 'missing_favicon' | 'missing_description' | 'missing_logo';
+export type BuildWarningType = 'broken_link' | 'auto_migrate' | 'missing_asset' | 'missing_image' | 'missing_page' | 'missing_openapi_ref' | 'inline_code_on_api_page' | 'invalid_openapi_spec' | 'missing_snippet' | 'risky_expression' | 'missing_favicon' | 'missing_description' | 'missing_logo';
 
 /** Build warning structure */
 export interface BuildWarning {