@stelstone/server 0.26.3 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stelstone/server",
-  "version": "0.26.3",
+  "version": "0.27.0",
   "description": "Runtime-agnostic CMS server built on the Web Fetch API, with pluggable adapters for content, media, auth, and build.",
   "license": "MIT",
   "repository": {
@@ -17,7 +17,7 @@
   ],
   "type": "module",
   "bin": {
-    "stelstone": "./bin/stelstone.mjs"
+    "stelstone": "bin/stelstone.mjs"
   },
   "scripts": {
     "test": "node --test 'test/**/*.test.mjs'"

package/src/core/config-schema.mjs

@@ -247,7 +247,9 @@ function checkForms(config, report, { getSecret }) {
     report.error("forms", "must be an object of formName → definition");
     return;
   }
-  if (Object.keys(forms).length && !mail) {
+  // A form with a forward has somewhere to put a submission even without mail.
+  const needsMail = Object.values(forms).some((def) => !isPlainObject(def) || !def.forward);
+  if (needsMail && !mail) {
     report.warn("forms", "defined without config.mail — submissions will answer 503 until mail is configured");
   }
   for (const [name, def] of Object.entries(forms)) {
@@ -256,8 +258,12 @@ function checkForms(config, report, { getSecret }) {
       report.error(at, "must be an object");
       continue;
     }
-    if (!def.to || typeof def.to !== "string" || !def.to.includes("@")) {
+    // `to` is what the e-mail copy needs. A form that only forwards has
+    // somewhere to put a submission without one.
+    if (def.to === undefined && !def.forward) {
       report.error(`${at}.to`, "is required and must be an email address");
+    } else if (def.to !== undefined && (typeof def.to !== "string" || !def.to.includes("@"))) {
+      report.error(`${at}.to`, "must be an email address");
     }
     if (def.subject !== undefined && typeof def.subject !== "string" && typeof def.subject !== "function") {
       report.error(`${at}.subject`, "must be a string or a (fields) => string function");
@@ -271,6 +277,47 @@ function checkForms(config, report, { getSecret }) {
         report.warn(`${at}.turnstile`, `${secretEnv} is not set — verification will answer 503`);
       }
     }
+    checkForward(def.forward, `${at}.forward`, report, getSecret);
+  }
+}
+
+/** `forward`: post the submission on to another service, e.g. a CRM. */
+function checkForward(forward, at, report, getSecret) {
+  if (forward === undefined) return;
+  if (!isPlainObject(forward)) {
+    report.error(at, "must be an object like { url, keyEnv?, body? }");
+    return;
+  }
+
+  let url;
+  try {
+    url = new URL(forward.url);
+  } catch {
+    report.error(`${at}.url`, "is required and must be an absolute http(s) URL");
+  }
+  if (forward.urlEnv !== undefined && typeof forward.urlEnv !== "string") {
+    report.error(`${at}.urlEnv`, "must be the NAME of an environment variable overriding url");
+  }
+  if (url && url.protocol !== "https:" && url.hostname !== "localhost") {
+    report.error(`${at}.url`, "must use https outside localhost — the payload carries personal data");
+  }
+
+  if (forward.body !== undefined && typeof forward.body !== "function") {
+    report.error(`${at}.body`, "must be a (fields) => object function");
+  }
+  if (forward.headers !== undefined && !isPlainObject(forward.headers)) {
+    report.error(`${at}.headers`, "must be an object of header → value");
+  }
+  if (forward.keyHeader !== undefined && typeof forward.keyHeader !== "string") {
+    report.error(`${at}.keyHeader`, "must be a header name like \"x-api-key\"");
+  }
+
+  if (forward.keyEnv === undefined) {
+    report.warn(`${at}.keyEnv`, "is not set — the request will carry no credential");
+  } else if (typeof forward.keyEnv !== "string") {
+    report.error(`${at}.keyEnv`, "must be the NAME of the environment variable holding the key");
+  } else if (!getSecret(forward.keyEnv)) {
+    report.warn(`${at}.keyEnv`, `${forward.keyEnv} is not set — forwarding will fail`);
   }
 }
 

package/src/core/forms.mjs

@@ -64,6 +64,51 @@ export function formatMessage(fields, { skip = [] } = {}) {
     .join("\n");
 }
 
+/** The fields a sink should see: no honeypot, no spent Turnstile token. */
+export function submissionFields(fields, honeypot) {
+  const hidden = new Set([honeypot, "form-name", "cf-turnstile-response"]);
+  return Object.fromEntries(Object.entries(fields).filter(([key]) => !hidden.has(key)));
+}
+
+/**
+ * Posts a submission on to another HTTP service — a CRM, an automation hook,
+ * whatever the site points it at. The secret travels by env name so it lives
+ * in the deployment rather than in cms.config, and the shape is the site's to
+ * decide: `body(fields)` maps the form onto whatever the far end expects, and
+ * without it the cleaned fields go as they are.
+ *
+ * Throws on anything but a 2xx; the caller decides what a failure means.
+ */
+export async function postForward(forward, fields, env) {
+  // `urlEnv` wins when the deployment sets it, so one config can point a
+  // preview worker at a staging service without editing the file. A Worker
+  // reads bindings rather than process.env, which is why this is a name to
+  // look up rather than something the config computes at import time.
+  const url = (forward.urlEnv && env(forward.urlEnv)) || forward.url;
+  const headers = { "content-type": "application/json", ...(forward.headers ?? {}) };
+  if (forward.keyEnv) {
+    const key = env(forward.keyEnv);
+    if (!key) throw new Error(`${forward.keyEnv} is not set`);
+    headers[forward.keyHeader ?? "x-api-key"] = key;
+  }
+
+  const body = typeof forward.body === "function" ? forward.body(fields) : fields;
+  const res = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    // Keep the far end's own words — a 400 from a CRM usually names the field
+    // it rejected, and that is what makes the failure fixable.
+    const detail = (await res.text().catch(() => "")).slice(0, 300).trim();
+    throw new Error(
+      `Forward to ${new URL(url).host} failed with HTTP ${res.status}` +
+        (detail ? `: ${detail}` : ""),
+    );
+  }
+}
+
 /**
  * Fixed-window in-memory rate limiter for the Node runtime. Per-process by
  * design — the Node server is a single process, and forms are a trickle.

package/src/routes.mjs

@@ -26,7 +26,14 @@
 
 import { queryPages } from "./adapters/_shared.mjs";
 import { SERVER_VERSION } from "./version.mjs";
-import { readFormFields, fieldsError, formatMessage, clientIp } from "./core/forms.mjs";
+import {
+  readFormFields,
+  fieldsError,
+  formatMessage,
+  clientIp,
+  submissionFields,
+  postForward,
+} from "./core/forms.mjs";
 
 function ok(json) {
   return { json };
@@ -516,7 +523,26 @@ export const apiRoutes = [
         return { status: 429, json: { error: "Too many submissions — please wait a minute" } };
       }
 
-      if (!adapters.mail?.configured) {
+      // Two sinks, and a submission survives on either one. The forward runs
+      // first so that when it fails the e-mail can carry the reason to whoever
+      // reads it — otherwise a CRM outage is invisible until someone notices
+      // the leads stopped arriving.
+      let forwardError = null;
+      if (def.forward) {
+        try {
+          await postForward(def.forward, submissionFields(fields, honeypot), env);
+        } catch (err) {
+          forwardError = err.message;
+        }
+      }
+      const forwarded = !!def.forward && !forwardError;
+
+      // No `to` means the form was set up to forward only — there is no
+      // e-mail copy to send, and nothing missing.
+      const mailReady = !!def.to && !!adapters.mail?.configured;
+      if (!mailReady) {
+        if (forwarded) return success();
+        if (forwardError) return { status: 502, json: { error: forwardError } };
         return {
           status: 503,
           json: { error: "Mail delivery is not configured — set config.mail and its API key" },
@@ -528,15 +554,21 @@ export const apiRoutes = [
           ? def.subject(fields)
           : def.subject || `Yeni form gönderimi: ${params.name}`;
       const replyTo = def.replyTo ? fields[def.replyTo] : undefined;
+      const text = forwardError
+        ? `${formatMessage(fields, { skip: [honeypot] })}\n\n---\nBu gönderim CRM'e iletilemedi: ${forwardError}`
+        : formatMessage(fields, { skip: [honeypot] });
 
       try {
         await adapters.mail.send({
           to: def.to,
           subject,
-          text: formatMessage(fields, { skip: [honeypot] }),
+          text,
           ...(replyTo ? { replyTo } : {}),
         });
       } catch (err) {
+        // The forward already has the submission, so the visitor has nothing
+        // to retry — only the copy for humans went missing.
+        if (forwarded) return success();
         return { status: 502, json: { error: err.message } };
       }
       return success();

package/src/version.mjs

@@ -5,4 +5,4 @@
  * require() and no import.meta.url, so reading the manifest at runtime yields
  * "unknown" there.
  */
-export const SERVER_VERSION = "0.26.3";
+export const SERVER_VERSION = "0.27.0";