npm - @cparkerwebm/webmonterey - Versions diffs - 1.0.0 - Mend

@cparkerwebm/webmonterey 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (133) hide show

package/CHANGELOG.md +56 -0
package/LICENSE +21 -0
package/README.md +104 -0
package/agents/.gitkeep +0 -0
package/dist/webm.mjs +2381 -0
package/hooks/.gitkeep +0 -0
package/package.json +101 -0
package/schema/design.json +118 -0
package/skills/launch/SKILL.md +183 -0
package/skills/new-component/SKILL.md +85 -0
package/skills/start/SKILL.md +117 -0
package/skills/traps/SKILL.md +333 -0
package/skills/upgrade/SKILL.md +42 -0
package/src/actions/index.ts +348 -0
package/src/cli/checks.test.ts +711 -0
package/src/cli/checks.ts +822 -0
package/src/cli/codemods.test.ts +42 -0
package/src/cli/codemods.ts +51 -0
package/src/cli/compare.test.ts +144 -0
package/src/cli/compare.ts +222 -0
package/src/cli/design-extract.test.ts +96 -0
package/src/cli/design-extract.ts +229 -0
package/src/cli/doctor.ts +187 -0
package/src/cli/mcp.test.ts +57 -0
package/src/cli/mcp.ts +110 -0
package/src/cli/new.ts +148 -0
package/src/cli/package-root.ts +58 -0
package/src/cli/scaffold.test.ts +230 -0
package/src/cli/scaffold.ts +424 -0
package/src/cli/seed.ts +133 -0
package/src/cli/slug.test.ts +70 -0
package/src/cli/slug.ts +109 -0
package/src/cli/sync.test.ts +137 -0
package/src/cli/sync.ts +266 -0
package/src/cli/upgrade.ts +93 -0
package/src/design/__fixtures__/tokens-v1.4.1.css +227 -0
package/src/design/brand.ts +49 -0
package/src/design/compile.test.ts +98 -0
package/src/design/compile.ts +155 -0
package/src/design/defaults.ts +315 -0
package/src/design/index.ts +18 -0
package/src/design/resolve.test.ts +80 -0
package/src/design/resolve.ts +108 -0
package/src/design/types.ts +96 -0
package/src/emails/autoresponse.test.ts +82 -0
package/src/emails/autoresponse.ts +83 -0
package/src/emails/footer.test.ts +102 -0
package/src/emails/footer.ts +91 -0
package/src/emails/index.ts +24 -0
package/src/emails/subject.test.ts +66 -0
package/src/emails/subject.ts +80 -0
package/src/emails/submission-notification.ts +76 -0
package/src/env.d.ts +12 -0
package/src/includes/cloudflare/d1/client.ts +86 -0
package/src/includes/cloudflare/r2/README.md +68 -0
package/src/includes/cloudflare/r2/media.ts +41 -0
package/src/includes/cloudflare/r2/url.test.ts +44 -0
package/src/includes/cloudflare/r2/url.ts +34 -0
package/src/includes/cloudflare/turnstile/Turnstile.astro +161 -0
package/src/includes/cloudflare/turnstile/verify.ts +157 -0
package/src/includes/cloudflare/workers/env.ts +56 -0
package/src/includes/google/tag-manager/TagManager.astro +73 -0
package/src/includes/sinch/mailgun/redirect.test.ts +96 -0
package/src/includes/sinch/mailgun/redirect.ts +96 -0
package/src/includes/sinch/mailgun/send.ts +186 -0
package/src/includes/webmonterey/animations/animations.css +347 -0
package/src/includes/webmonterey/animations/observe.test.ts +88 -0
package/src/includes/webmonterey/animations/observe.ts +209 -0
package/src/includes/webmonterey/compliance/ConsentInit.astro +74 -0
package/src/includes/webmonterey/compliance/CookieConsent.astro +558 -0
package/src/includes/webmonterey/compliance/consent-styles.test.ts +83 -0
package/src/includes/webmonterey/compliance/consent.ts +142 -0
package/src/includes/webmonterey/config.test.ts +94 -0
package/src/includes/webmonterey/config.ts +346 -0
package/src/includes/webmonterey/copy-defaults.ts +148 -0
package/src/includes/webmonterey/copy.ts +13 -0
package/src/includes/webmonterey/credits/Credit.astro +80 -0
package/src/includes/webmonterey/credits/credit.test.ts +111 -0
package/src/includes/webmonterey/credits/credit.ts +59 -0
package/src/includes/webmonterey/forms/honeypot.test.ts +40 -0
package/src/includes/webmonterey/forms/honeypot.ts +66 -0
package/src/includes/webmonterey/prose/inline.test.ts +94 -0
package/src/includes/webmonterey/prose/inline.ts +71 -0
package/src/includes/webmonterey/scroll-top/ScrollTop.astro +209 -0
package/src/includes/webmonterey/site.ts +136 -0
package/src/includes/webmonterey/structured-data/nodes.ts +315 -0
package/src/includes/webmonterey/zoned-hour.test.ts +49 -0
package/src/integration/adapter.ts +53 -0
package/src/integration/app-middleware.ts +43 -0
package/src/integration/config.ts +96 -0
package/src/integration/content.ts +66 -0
package/src/integration/image-size.test.ts +83 -0
package/src/integration/image-size.ts +100 -0
package/src/integration/index.ts +386 -0
package/src/integration/virtual.d.ts +101 -0
package/src/layouts/base.astro +402 -0
package/src/package.test.ts +121 -0
package/src/pages/404.astro +33 -0
package/src/pages/[...slug].astro +126 -0
package/src/pages/robots.txt.ts +41 -0
package/src/pages/webm.astro +23 -0
package/src/scripts/.gitkeep +0 -0
package/src/styles/base.css +185 -0
package/src/styles/global.css +47 -0
package/src/styles/layers.test.ts +32 -0
package/src/styles/layers.ts +21 -0
package/src/styles/layout.css +235 -0
package/src/styles/reset.css +135 -0
package/src/styles/utilities.css +90 -0
package/src/worker.ts +76 -0
package/template/assets/logo.svg +14 -0
package/template/assets/open-graph.png +0 -0
package/template/migrations/0001_create_submissions.sql +40 -0
package/template/migrations/README.md +41 -0
package/template/public/android-chrome-192x192.png +0 -0
package/template/public/android-chrome-512x512.png +0 -0
package/template/public/apple-touch-icon.png +0 -0
package/template/public/favicon-16x16.png +0 -0
package/template/public/favicon-32x32.png +0 -0
package/template/public/favicon.ico +0 -0
package/template/public/favicon.svg +4 -0
package/template/public/open-graph.png +0 -0
package/template/scripts/check-node.mjs +72 -0
package/template/scripts/test-hooks.mjs +96 -0
package/template/site/.editorconfig +22 -0
package/template/site/.prettierignore +15 -0
package/template/site/.prettierrc.json +17 -0
package/template/site/CLAUDE.md +245 -0
package/template/site/CONTENT.md +135 -0
package/template/site/PRIVACY-POLICY-DRAFT.md +81 -0
package/template/site/public/_headers +70 -0
package/template/site/src/forms/contact.json +45 -0
package/template/workflows/ci.yml +52 -0

package/src/includes/google/tag-manager/TagManager.astro ADDED Viewed

@@ -0,0 +1,73 @@
+---
+/*
+ * Google Tag Manager.
+ *
+ * Renders nothing unless an ID is passed, so it is safe to leave in the layout on every site
+ * whether or not the client uses GTM.
+ *
+ * USAGE — in src/layouts/base.astro:
+ *
+ *   ---
+ *   import TagManager from '../includes/google/tag-manager/TagManager.astro';
+ *   ---
+ *   <head>
+ *     <TagManager id={Astro.locals.gtmId} />       <- or a value from wrangler vars
+ *   </head>
+ *   <body>
+ *     <TagManager id={...} noscript />             <- immediately after <body>
+ *
+ * The container ID is PUBLIC — it belongs in `vars` in wrangler.jsonc, not in secrets.
+ *
+ * Placement matters: the script must be in <head>, and the <noscript> iframe must be the
+ * first thing inside <body>. GTM misbehaves otherwise.
+ */
+interface Props {
+  /** GTM container ID, `GTM-XXXXXXX`. Renders nothing when empty. */
+  id?: string;
+  /** Render the <noscript> iframe variant instead of the script. */
+  noscript?: boolean;
+}
+const { id, noscript = false } = Astro.props;
+// A malformed ID silently breaks tracking, so fail visibly at build instead. This check also
+// makes the interpolation below safe: only /^GTM-[A-Z0-9]+$/ can reach the script body.
+if (id && !/^GTM-[A-Z0-9]+$/.test(id)) {
+  throw new Error(
+    `[webm] Invalid GTM container ID "${id}". Expected the form GTM-XXXXXXX. ` +
+      `A Google Analytics measurement ID (G-XXXXXXX) is not the same thing.`,
+  );
+}
+/*
+ * Built as a string in frontmatter, then injected with `set:html`.
+ *
+ * Two things had to be avoided. Putting the raw JS inside a <script> in a JSX expression is
+ * what Astro actually wants, but Prettier's Astro parser cannot parse the braces and fails
+ * the file. Wrapping the JS in {`...`} instead makes Prettier happy and emits the braces and
+ * backticks LITERALLY — the browser reads a block statement containing a discarded string,
+ * so there is no error, no request, and no analytics at all.
+ *
+ * `set:html` on its own sidesteps both. Do NOT add `define:vars` alongside it — that
+ * combination makes Astro emit an empty script body.
+ */
+const snippet = id
+  ? `(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);})(window,document,'script','dataLayer','${id}');`
+  : null;
+---
+{snippet && !noscript && <script is:inline set:html={snippet} />}
+{
+  id && noscript && (
+    <noscript>
+      <iframe
+        src={`https://www.googletagmanager.com/ns.html?id=${id}`}
+        height="0"
+        width="0"
+        style="display:none;visibility:hidden"
+        title="Google Tag Manager"
+      />
+    </noscript>
+  )
+}

package/src/includes/sinch/mailgun/redirect.test.ts ADDED Viewed

@@ -0,0 +1,96 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { redirectRecipients, redirectedSubject } from './redirect.ts';
+import { isStagingDeployment } from '../../webmonterey/config.ts';
+const DEV = 'dev@webmonterey.com';
+test('every recipient becomes the dev address', () => {
+  const out = redirectRecipients({ to: 'client@example.com' }, DEV);
+  assert.deepEqual(out.to, [DEV]);
+  assert.equal(out.replyTo, DEV);
+});
+test('cc and bcc are dropped, not redirected', () => {
+  const out = redirectRecipients(
+    { to: 'a@example.com', cc: 'b@example.com', bcc: 'c@example.com' },
+    DEV,
+  );
+  /* A surviving bcc would be a real person receiving a test, invisibly. */
+  assert.equal(out.cc, undefined);
+  assert.equal(out.bcc, undefined);
+  assert.deepEqual(out.to, [DEV]);
+});
+test('the real recipients survive in headers', () => {
+  const out = redirectRecipients(
+    { to: ['a@example.com', 'b@example.com'], bcc: 'c@example.com', replyTo: 'r@example.com' },
+    DEV,
+  );
+  assert.equal(out.headers['X-Webm-Original-To'], 'a@example.com, b@example.com');
+  assert.equal(out.headers['X-Webm-Original-Bcc'], 'c@example.com');
+  assert.equal(out.headers['X-Webm-Original-Reply-To'], 'r@example.com');
+  assert.equal(out.headers['X-Webm-Environment'], 'staging');
+});
+test('reply-to is rewritten, because this fleet inverts it on registration mail', () => {
+  const out = redirectRecipients({ to: 'a@example.com', replyTo: 'organizer@example.com' }, DEV);
+  assert.equal(out.replyTo, DEV);
+});
+test('the subject names who it was really for', () => {
+  const out = redirectRecipients({ to: 'client@example.com' }, DEV);
+  assert.equal(
+    redirectedSubject('New enquiry', out.original),
+    '[staging → client@example.com] New enquiry',
+  );
+});
+test('a long recipient list is capped so the real subject stays visible', () => {
+  const many = ['a@x.com', 'b@x.com', 'c@x.com', 'd@x.com', 'e@x.com'];
+  assert.equal(redirectedSubject('Hello', many), '[staging → a@x.com, b@x.com, c@x.com +2] Hello');
+});
+test('an empty recipient list still marks the subject', () => {
+  assert.equal(redirectedSubject('Hello', []), '[staging] Hello');
+});
+/* --- the decision itself ------------------------------------------------ */
+test('staging config redirects, with or without a hostname', () => {
+  assert.equal(isStagingDeployment('staging'), true);
+  assert.equal(isStagingDeployment('staging', 'example.com'), true);
+});
+test('a cron on a staging site is covered, having no hostname at all', () => {
+  /* The case a request-based check cannot see: scheduled() has no Request. */
+  assert.equal(isStagingDeployment('staging', undefined), true);
+});
+test('workers.dev redirects even when the config says production', () => {
+  assert.equal(isStagingDeployment('production', 'webm-example.webmonterey.workers.dev'), true);
+  assert.equal(isStagingDeployment('production', 'workers.dev'), true);
+});
+test('a production site on its own domain sends for real', () => {
+  assert.equal(isStagingDeployment('production', 'example.com'), false);
+  assert.equal(isStagingDeployment(undefined, 'example.com'), false);
+});
+test('a www variant still sends for real', () => {
+  /* The reason this tests workers.dev rather than "not the canonical domain": a bare `domain`
+   * plus a www hostname would otherwise silently redirect a live site's mail away. */
+  assert.equal(isStagingDeployment('production', 'www.example.com'), false);
+});
+test('a domain merely ending in workers.dev is not a preview', () => {
+  assert.equal(isStagingDeployment('production', 'notworkers.dev'), false);
+});
+test('an unset environment and no hostname sends for real', () => {
+  /* Every site predating this field. Any other answer breaks their email on npm update. */
+  assert.equal(isStagingDeployment(undefined, undefined), false);
+});

package/src/includes/sinch/mailgun/redirect.ts ADDED Viewed

@@ -0,0 +1,96 @@
+/*
+ * STAGING EMAIL REDIRECTION — the recipient rewrite, as a pure function.
+ *
+ * Kept in its own file, importing nothing, for the same reason config.ts is separate from
+ * site.ts: everything here is unit tested without a build, while send.ts reaches the network and
+ * reads `virtual:webm/site`, which only exists inside one.
+ *
+ * WHAT THIS SOLVES. A preview deployment sends real email to real people. The contact form on
+ * this fleet notifies the client's own inbox and the registration flow mails whoever organises a
+ * programme, so testing a preview means a client receives test enquiries and an organizer is
+ * told somebody signed up who did not. Nothing about that is visible to whoever is testing.
+ *
+ * WHY REWRITE RATHER THAN SUPPRESS. Mailgun's test mode accepts a message and never delivers it,
+ * which verifies the API call and nothing else — not the rendering, not the deliverability, not
+ * the attachment. The whole point of sending from staging is to see the real thing arrive, so
+ * the message is sent for real and only its recipients are changed.
+ */
+/** Every field that can put a message in front of a person. */
+export interface Recipients {
+  to: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  replyTo?: string;
+}
+export interface RedirectedRecipients {
+  to: string[];
+  /*
+   * Absent, never redirected. A cc or bcc that survived would be a second real person receiving
+   * a test — and bcc especially, because nothing in the delivered message would show it happened.
+   */
+  cc: undefined;
+  bcc: undefined;
+  replyTo: string;
+  /**
+   * Diagnostic headers naming who the message was really for, so a redirected copy is still
+   * evidence of what production would have done.
+   */
+  headers: Record<string, string>;
+  /** The addresses this message was addressed to, in order, for the subject annotation. */
+  original: string[];
+}
+const list = (value: string | string[] | undefined): string[] =>
+  value === undefined ? [] : (Array.isArray(value) ? value : [value]).filter(Boolean);
+/**
+ * Point every recipient at one address, preserving what was there.
+ *
+ * `replyTo` is rewritten as well as `to`. Leaving it alone is tempting — it does not cause
+ * delivery — but this fleet deliberately INVERTS reply-to on registration mail so a registrant
+ * reaching for reply gets the organizer. In a shared dev inbox that turns one careless reply
+ * into a real message to a real organizer, which is the failure this whole module exists to
+ * prevent. The original is kept in a header instead, where it can still be checked.
+ */
+export function redirectRecipients(
+  recipients: Recipients,
+  stagingEmail: string,
+): RedirectedRecipients {
+  const to = list(recipients.to);
+  const cc = list(recipients.cc);
+  const bcc = list(recipients.bcc);
+  const original = [...to, ...cc, ...bcc];
+  const headers: Record<string, string> = { 'X-Webm-Environment': 'staging' };
+  if (to.length) headers['X-Webm-Original-To'] = to.join(', ');
+  if (cc.length) headers['X-Webm-Original-Cc'] = cc.join(', ');
+  if (bcc.length) headers['X-Webm-Original-Bcc'] = bcc.join(', ');
+  if (recipients.replyTo) headers['X-Webm-Original-Reply-To'] = recipients.replyTo;
+  return {
+    to: [stagingEmail],
+    cc: undefined,
+    bcc: undefined,
+    replyTo: stagingEmail,
+    headers,
+    original,
+  };
+}
+/**
+ * Mark the subject so a redirected message is never mistaken for a real one at a glance.
+ *
+ * The real recipients go in the subject rather than only in a header because a shared dev inbox
+ * collects mail from every client site in the fleet, and "who was this actually for" is the
+ * question being asked of it. Capped so a long cc list cannot push the real subject out of view.
+ */
+export function redirectedSubject(subject: string, original: string[]): string {
+  if (!original.length) return `[staging] ${subject}`;
+  const shown = original.slice(0, 3).join(', ');
+  const more = original.length > 3 ? ` +${original.length - 3}` : '';
+  return `[staging → ${shown}${more}] ${subject}`;
+}

package/src/includes/sinch/mailgun/send.ts ADDED Viewed

@@ -0,0 +1,186 @@
+/*
+ * Mailgun (a Sinch product) — transactional email.
+ *
+ * Used for form notifications and autoresponders. There is no SDK: Mailgun's API is a
+ * form-encoded POST, and adding a Node-oriented SDK to a Worker is more trouble than the
+ * twenty lines below.
+ *
+ * Secrets: MAILGUN_API_KEY and MAILGUN_DOMAIN. Local values in .dev.vars; production via
+ * `npx wrangler secret put MAILGUN_API_KEY`.
+ *
+ * The route that calls this needs `export const prerender = false`.
+ *
+ * Sending domain convention is `webm.<client-domain>` — keeps client deliverability separate
+ * from their own mail, so a bounce problem on one never poisons the other. The mailbox is
+ * `website@`, giving `website@webm.<client-domain>` for every template the site sends.
+ */
+import { environment, stagingEmail } from '../../webmonterey/site.ts';
+import { isStagingDeployment } from '../../webmonterey/config.ts';
+import { redirectRecipients, redirectedSubject } from './redirect.ts';
+export interface SendEmailOptions {
+  apiKey: string;
+  /** The Mailgun sending domain, e.g. `webm.example.com`. */
+  domain: string;
+  /** `Name <address@webm.example.com>` — must be on the sending domain. */
+  from: string;
+  to: string | string[];
+  subject: string;
+  /** Provide `text`, `html`, or both. Both is best for deliverability. */
+  text?: string;
+  html?: string;
+  /** Set this to the visitor's address so a reply reaches them, not the Worker. */
+  replyTo?: string;
+  cc?: string | string[];
+  bcc?: string | string[];
+  /** Mailgun tags, for filtering in their dashboard. */
+  tags?: string[];
+  /** EU-hosted accounts must pass 'eu'; sending to the wrong region fails auth. */
+  region?: 'us' | 'eu';
+  /*
+   * Files to attach.
+   *
+   * Added because friendsofthemarinalibrary.org attaches an .ics to its registration
+   * confirmation, and had put this field on a private copy of this file to do it. The rebuild
+   * pointed that site's action back here and the calendar invite silently stopped being sent -
+   * silently because an attachment is passed inside a conditional spread, where TypeScript's
+   * excess-property check does not apply, so nothing failed and nothing was said.
+   *
+   * That is the shape of a missing seam: a site needing one field kept a whole file to get it,
+   * and the copy is what a rebuild threw away. One optional field here costs nothing and ends it.
+   *
+   * `content` is a string rather than a Blob so callers stay easy to test - every generator in
+   * the fleet returns text - and the Blob is built at the last moment below.
+   */
+  attachments?: Array<{ filename: string; content: string; contentType: string }>;
+  /**
+   * The hostname this send is happening on, when there is a request to take one from.
+   *
+   * Only ever used to REDIRECT recipients away from real people on a preview — see
+   * isStagingDeployment. Omit it and the decision falls to `environment` alone, which is
+   * correct for a scheduled handler: a cron has no request, and a production cron must still
+   * send for real.
+   */
+  hostname?: string | null;
+}
+export interface SendEmailResult {
+  id: string;
+  message: string;
+}
+const ENDPOINTS = {
+  us: 'https://api.mailgun.net/v3',
+  eu: 'https://api.eu.mailgun.net/v3',
+} as const;
+/**
+ * Send one email. Throws on any non-2xx, with Mailgun's own message included — a silent
+ * failure here means a client never learns someone tried to contact them.
+ */
+export async function sendEmail(options: SendEmailOptions): Promise<SendEmailResult> {
+  const {
+    apiKey,
+    domain,
+    from,
+    to,
+    subject,
+    text,
+    html,
+    replyTo,
+    cc,
+    bcc,
+    tags,
+    region,
+    attachments,
+    hostname,
+  } = options;
+  if (!text && !html) {
+    throw new Error('[webm] sendEmail needs at least one of `text` or `html`.');
+  }
+  const body = new FormData();
+  body.set('from', from);
+  /*
+   * STAGING NEVER MAILS A REAL PERSON.
+   *
+   * Applied here, at the one place every template in the fleet passes through, rather than at
+   * each call site: the form pipeline, this site's registration action and the nightly sweep
+   * all reach Mailgun through this function, and a guard that has to be remembered per call is
+   * one that will be missed. See redirect.ts for what is rewritten and why.
+   */
+  const staging = isStagingDeployment(environment, hostname);
+  if (staging) {
+    /*
+     * REFUSE RATHER THAN GUESS. There is no default inbox in the package, so a staging site that
+     * has not named one has nowhere safe to send - and the alternative, sending to the real
+     * recipients, is the exact thing staging exists to prevent. `webm doctor` catches this
+     * before a form ever gets submitted.
+     */
+    if (!stagingEmail) {
+      throw new Error(
+        '[webm] This is a staging deployment and webmonterey.json has no "stagingEmail". ' +
+          'Refusing to send: without one the only alternative is the real recipients. Set ' +
+          'stagingEmail to the inbox that should receive test mail.',
+      );
+    }
+    const redirected = redirectRecipients({ to, cc, bcc, replyTo }, stagingEmail);
+    body.set('subject', redirectedSubject(subject, redirected.original));
+    for (const address of redirected.to) body.append('to', address);
+    for (const [name, value] of Object.entries(redirected.headers)) body.set(`h:${name}`, value);
+    body.set('h:Reply-To', redirected.replyTo);
+    /* Filterable in Mailgun, so a shared dev inbox never muddles the client's own traffic. */
+    body.append('o:tag', 'staging');
+  } else {
+    body.set('subject', subject);
+    for (const address of Array.isArray(to) ? to : [to]) body.append('to', address);
+    if (cc) for (const address of Array.isArray(cc) ? cc : [cc]) body.append('cc', address);
+    if (bcc) for (const address of Array.isArray(bcc) ? bcc : [bcc]) body.append('bcc', address);
+    if (replyTo) body.set('h:Reply-To', replyTo);
+  }
+  if (text) body.set('text', text);
+  if (html) body.set('html', html);
+  if (tags) for (const tag of tags) body.append('o:tag', tag);
+  for (const file of attachments ?? []) {
+    body.append('attachment', new Blob([file.content], { type: file.contentType }), file.filename);
+  }
+  const endpoint = `${ENDPOINTS[region ?? 'us']}/${domain}/messages`;
+  const response = await fetch(endpoint, {
+    method: 'POST',
+    headers: {
+      // Mailgun uses HTTP basic auth with the literal username "api".
+      Authorization: `Basic ${btoa(`api:${apiKey}`)}`,
+    },
+    body,
+  });
+  if (!response.ok) {
+    /*
+     * Neither the domain nor the key is interpolated here. MAILGUN_API_KEY and
+     * MAILGUN_DOMAIN sit on adjacent lines in .dev.vars.example, and a swap would otherwise
+     * put the API key into this message — which `observability` then persists into Cloudflare
+     * Workers Logs, and which reaches the browser if a caller echoes `e.message`.
+     * Mailgun's own body is capped for the same reason: it is unbounded remote input.
+     */
+    const detail = (await response.text()).slice(0, 200);
+    throw new Error(
+      `[webm] Mailgun refused the message (${response.status}): ${detail}\n` +
+        `  - 401: wrong API key, or an EU account being sent to the US endpoint\n` +
+        `  - 404: the sending domain does not exist on this account (check MAILGUN_DOMAIN)\n` +
+        `  - 400: the "from" address is not on the sending domain`,
+    );
+  }
+  return (await response.json()) as SendEmailResult;
+}