jamdesk 1.1.142 → 1.1.143

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/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 };

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/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 };
+  },
+};

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 };
+  },
+};