@casomoltd/tooling 0.34.2 → 0.36.0

package/bin/buttondown.mjs

@@ -12,19 +12,25 @@
  *   buttondown emit <dir>          write each long field out as rendered
  *   buttondown draft <file.md>     create or replace a draft
  *   buttondown upload <image>      upload an image, print its URL
- *   buttondown api <METHOD> <path> [json]
- *                                  any call, for setting up a manual test
+ *   buttondown api <METHOD> <path> [json] [--send]
+ *                                  any call, for setting up a manual test;
+ *                                  one that sends or schedules an email
+ *                                  is refused without --send
  *
  * `diff`, `apply` and `check` exit 1 on drift, a refusal or a problem, so a
  * script can gate on them.
  */
 import {
-  apply, assertApiPath, client, draft, drift, emit, loadSettings, readKey,
-  runCheck, upload, writeTokens,
+  apply, assertApiPath, assertNotSending, client, draft, drift, emit,
+  loadSettings, readKey, runCheck, upload, writeTokens,
 } from "../buttondown/engine.mjs";
 
+/** The one flag: without it, `api` refuses any call that could send an
+ *  email, and no other command takes it. */
+const SEND_FLAG = "--send";
+
 const USAGE = "usage: buttondown [diff|apply|check|tokens|emit <dir>|"
-  + "draft <file.md>|upload <image>|api <METHOD> <path> [json]]";
+  + `draft <file.md>|upload <image>|api <METHOD> <path> [json] [${SEND_FLAG}]]`;
 
 /** Each command with the fewest and most arguments it takes. */
 const ARGS = {
@@ -32,9 +38,13 @@ const ARGS = {
   emit: [1, 1], draft: [1, 1], upload: [1, 1], api: [2, 3],
 };
 
-const [command = "diff", ...args] = process.argv.slice(2);
+const argv = process.argv.slice(2);
+const send = argv.includes(SEND_FLAG);
+const [command = "diff", ...args] = argv.filter((a) => a !== SEND_FLAG);
 const [fewest, most] = ARGS[command] ?? [];
-if (fewest === undefined || args.length < fewest || args.length > most) {
+const badUsage = fewest === undefined || args.length < fewest
+  || args.length > most || (send && command !== "api");
+if (badUsage) {
   console.error(USAGE);
   process.exit(2);
 }
@@ -85,9 +95,16 @@ switch (command) {
   case "api": {
     const [method, url, body] = args;
     assertApiPath(settings, method, url);
-    const res = await (await api()).call(
-      method.toUpperCase(), url, body && JSON.parse(body),
-    );
+    const payload = body && JSON.parse(body);
+    if (!send) {
+      try {
+        assertNotSending(method, url, payload);
+      } catch (e) {
+        console.error(`buttondown: ${e.message}; add ${SEND_FLAG} to send it`);
+        process.exit(1);
+      }
+    }
+    const res = await (await api()).call(method.toUpperCase(), url, payload);
     console.log(res.status, res.data ? JSON.stringify(res.data, null, 2) : "");
     process.exit(res.ok ? 0 : 1);
   }

package/buttondown/engine.mjs

@@ -27,7 +27,8 @@
  *     },
  *   };
  *
- * `newsletter.json` holds the newsletter's short fields, `tags.json` its
+ * `newsletter.json` holds the newsletter's short fields (its `image` is
+ * also every draft's default share image), `tags.json` its
  * tags, and each file in `fields/` is the field it is named after: a
  * stylesheet is read verbatim, and an `.mjs` file's default export is the
  * field's value.
@@ -86,6 +87,19 @@ const API_PATH = new URL(API).pathname;
 /** The status of an email not yet sent. */
 const DRAFT = "draft";
 
+/**
+ * The api routes that can mail someone, judged on a `requestPath`. A write
+ * to the emails collection or to one email may carry a status that sends
+ * it, so it passes only as a draft; any action on an email (publish,
+ * send-draft and whatever Buttondown adds) or on a subscriber (a reminder,
+ * an email to one reader) is refused outright, so a new route fails closed.
+ * Creating an unactivated subscriber also mails a confirmation, and stays
+ * allowed: it is how a manual test stands in for a reader signing up, to an
+ * address the tester owns.
+ */
+const EMAIL_WRITE = new RegExp(`^${API_PATH}/emails(/[^/]+)?/?$`);
+const SENDING_ACTION = new RegExp(`^${API_PATH}/(emails|subscribers)/[^/]+/.`);
+
 const FRONT_MATTER = /^---\n([\s\S]*?)\n---\n/;
 
 /** The Buttondown fields holding the two skins. */
@@ -180,15 +194,7 @@ export async function tokenReader(file) {
 
 /** Every field the newsletter is set to: newsletter.json, then fields/. */
 export async function buildPayload(settings) {
-  const payload = JSON.parse(
-    await readFile(path.join(settings.dir, "newsletter.json"), "utf8"),
-  );
-  for (const field of IMAGE_FIELDS) {
-    if (payload[field] && !URL.canParse(payload[field])) {
-      throw new Error(`${field} must be an absolute URL, got `
-        + JSON.stringify(payload[field]));
-    }
-  }
+  const payload = await readNewsletter(settings);
   const identity = IDENTITY.filter((key) => key in payload);
   if (identity.length) {
     throw new Error(
@@ -394,7 +400,7 @@ export async function readKey(env = process.env) {
 export function client(settings, key) {
   const {newsletter} = settings;
   async function call(method, url, body, {form} = {}) {
-    const res = await fetch(new URL(API + url), {
+    const res = await fetch(requestUrl(url), {
       method,
       headers: {
         Authorization: `Token ${key}`,
@@ -452,25 +458,37 @@ export function client(settings, key) {
 
 /**
  * Refuses an `api` call that writes newsletter settings anywhere but this
- * newsletter. Judged on the path the server routes: percent-decoded, then
- * normalised, so `/%6eewsletters/<other>`, `/./newsletters/<other>` and
- * `<own>/../<other>` are seen for what they are. A path still encoded after
- * one decoding is refused outright rather than guessed at.
+ * newsletter, judged on the path the server routes (`requestPath`).
  */
 export function assertApiPath(settings, method, url) {
   if (method.toUpperCase() === "GET") return;
-  const decoded = decodeURIComponent(new URL(API + url).pathname);
-  if (decoded.includes("%")) {
-    throw new Error(`api refuses an encoded path: ${url}`);
-  }
-  const {pathname} = new URL(decoded, API);
-  const own = API_PATH + newsletterPath(settings.newsletter);
+  const pathname = requestPath(url);
+  const own = (API_PATH + newsletterPath(settings.newsletter)).toLowerCase();
   if (pathname.startsWith(`${API_PATH}/newsletters`)
     && pathname !== own && !pathname.startsWith(`${own}/`)) {
     throw new Error(`api writes under /newsletters only to ${own}`);
   }
 }
 
+/**
+ * Throws if an api call could send or schedule an email (`EMAIL_WRITE`,
+ * `SENDING_ACTION`). Sending reaches real inboxes and cannot be recalled, so
+ * the caller lets a call through only on a person's explicit say-so.
+ */
+export function assertNotSending(method, url, body) {
+  const cannotSend = ["GET", "DELETE"].includes(method.toUpperCase());
+  if (cannotSend) return;
+  const pathname = requestPath(url);
+  const status = body && typeof body === "object" ? body.status : undefined;
+  const creates = pathname.replace(/\/$/, "") === `${API_PATH}/emails`;
+  const draftOnly = status === DRAFT || (status === undefined && !creates);
+  if (SENDING_ACTION.test(pathname)
+    || (EMAIL_WRITE.test(pathname) && !draftOnly)) {
+    throw new Error(`api refuses a call that could send an email: `
+      + `${method.toUpperCase()} ${url}`);
+  }
+}
+
 /** Whether a live value already says what the repo wants. */
 export function same(field, got, want) {
   if (IMAGE_FIELDS.has(field)) {
@@ -570,7 +588,8 @@ export async function apply(settings, api, log = console.log) {
  * A draft from a markdown file whose first line, after any front matter,
  * is `# Subject`. Front matter carries the email's id once it exists, so a
  * re-run replaces that draft rather than creating a second; `slug` and
- * `description` are passed through. An email already sent is refused:
+ * `description` are passed through, and `image` (the share image) defaults
+ * to the newsletter's own. An email already sent is refused:
  * replacing it would rewrite the published archive.
  */
 export async function draft(settings, api, file, log = console.log) {
@@ -591,6 +610,10 @@ export async function draft(settings, api, file, log = console.log) {
     throw new Error("front matter has an empty `id:`; delete the line to "
       + "create a draft");
   }
+  if ("image" in fm && !fm.image) {
+    throw new Error("front matter has an empty `image:`; delete the line "
+      + "to use the newsletter's share image");
+  }
   // The marker says the body is markdown (Buttondown's `plaintext` mode).
   // Without it Buttondown guesses, and a draft once stored as rich text
   // takes the next PATCH as rich text too.
@@ -601,6 +624,15 @@ export async function draft(settings, api, file, log = console.log) {
     ...Object.fromEntries(["slug", "description"]
       .filter((k) => k in fm).map((k) => [k, fm[k]])),
   };
+  // Left unset, Buttondown takes the post's first picture as its share
+  // image, so every post would preview differently; the newsletter's own
+  // share image is the default, and `image:` in the front matter wins.
+  const image = "image" in fm
+    ? fm.image : (await readNewsletter(settings)).image;
+  if (image) {
+    assertAbsoluteUrl("image", image);
+    body.image = image;
+  }
   if (fm.id) {
     const current = await api.call("GET", `/emails/${fm.id}`);
     if (!current.ok) throw new Error(`GET email: ${detail(current)}`);
@@ -686,6 +718,50 @@ export function stripComments(text) {
   }
 }
 
+/** The URL `call` fetches for an api path, and the one the guards judge. */
+function requestUrl(url) {
+  return new URL(API + url);
+}
+
+/**
+ * The path the server routes for an `api` url, from `requestUrl`,
+ * then percent-decoded, slash-collapsed and normalised, so
+ * `/%6eewsletters/<other>`, `//emails/<id>/publish`, `/./newsletters/<other>`
+ * and `<own>/../<other>` are seen for what they are. A path still encoded
+ * after one decoding is refused outright rather than guessed at.
+ */
+function requestPath(url) {
+  const decoded = decodeURIComponent(requestUrl(url).pathname);
+  if (decoded.includes("%")) {
+    throw new Error(`api refuses an encoded path: ${url}`);
+  }
+  return new URL(decoded.replace(/\/{2,}/g, "/"), API).pathname.toLowerCase();
+}
+
+/** Throws unless an image field holds an absolute URL, since Buttondown
+ *  stores a relative one as given and the image then never loads. */
+function assertAbsoluteUrl(field, value) {
+  if (!URL.canParse(value)) {
+    throw new Error(`${field} must be an absolute URL, got `
+      + JSON.stringify(value));
+  }
+}
+
+/** newsletter.json, parsed and with its image fields checked. */
+async function readNewsletter(settings) {
+  const file = path.join(settings.dir, "newsletter.json");
+  let payload;
+  try {
+    payload = JSON.parse(await readFile(file, "utf8"));
+  } catch (error) {
+    throw new Error(`${file}: ${error.message}`, {cause: error});
+  }
+  for (const field of IMAGE_FIELDS) {
+    if (payload[field]) assertAbsoluteUrl(field, payload[field]);
+  }
+  return payload;
+}
+
 /** Why a call failed: Buttondown's `detail`, else its whole body, which
  *  names the fields it refused, else the status. */
 function detail(res) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casomoltd/tooling",
-  "version": "0.34.2",
+  "version": "0.36.0",
   "description": "Casomo's shared dev config: ESLint, Prettier, commitlint, knip & jscpd presets and dev CLIs (git hooks, readability, screenshots, design specs)",
   "license": "MIT",
   "repository": {