ferst-core 0.9.9 → 0.10.0

package/bin/ferst-modules.mjs

@@ -7,7 +7,7 @@
 //   npx --no-install ferst-modules --json          # the raw answer
 //
 // Forms and calendars live in the portal, never in the repo: place a form with a
-// `{ "type": "form", "form": "<id>" }` block, and show the calendar by setting
+// `{ "type": "form", "form": "<its name on this site>" }` block, and show the calendar by setting
 // calendarSettings.embedUrl to the address printed here.
 import { readFileSync, realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
@@ -46,7 +46,7 @@ export function formatModules(data) {
   else if (data.forms.length === 0) out.push('  No forms yet. They are created in the portal (Forms).');
   for (const f of data.forms) {
     out.push(`  ${f.name}`);
-    out.push(`    place it with: { "type": "form", "form": "${f.id}" }`);
+    out.push(`    place it with: { "type": "form", "form": "${f.slot ?? f.id}" }`);
     out.push(`    fields: ${f.fields.map((x) => `${x.label}${x.required ? ' *' : ''}`).join(', ') || '(none)'}`);
     out.push(`    button: ${f.submitLabel}`);
   }

package/components/recipes/Form.astro

@@ -1,13 +1,14 @@
 ---
 /**
- * Form — one of the organisation's forms from the Ferst portal, placed by id. Reads the
- * form's fields, button and submit address from the platform at build time (lib/forms)
- * and renders it with the ContactForm recipe, so it looks like every other form and a
- * change made in the portal reaches the site on its next build.
+ * Form — one of the organisation's forms from the Ferst portal, placed by its name on this site
+ * (its slot; older pages give its id). Reads the form's fields, button and submit address from the
+ * platform at build time, through the site (lib/forms), and renders it with the ContactForm recipe,
+ * so it looks like every other form and a change made in the portal reaches the site on its next
+ * build.
  */
 import ContactForm from './ContactForm.astro';
 import { loadFormDefinition } from '../../lib/forms';
-import { resolveGitBase } from '../../lib/git-base.mjs';
+import { resolveGitBase, resolveSiteId } from '../../lib/git-base.mjs';
 
 interface Props {
   form: string;
@@ -16,7 +17,7 @@ interface Props {
   note?: string;
 }
 const { form, title, intro, note } = Astro.props;
-const def = await loadFormDefinition(form, { base: resolveGitBase() });
+const def = await loadFormDefinition(form, { base: resolveGitBase(), siteId: resolveSiteId() });
 ---
 
 <ContactForm

package/lib/forms.ts

@@ -1,8 +1,15 @@
 /**
- * A form placed by id (the `form` block) is read from the Ferst platform at build time, so
+ * A form placed on a page (the `form` block) is read from the Ferst platform at build time, so
  * a change made to it in the portal reaches the site on its next build — no pasted copy of
  * its fields to keep in step. A missing form or an unreachable platform fails the build:
  * better the last good deploy stays live than a form that can't be sent goes out.
+ *
+ * The block names the form by its name on this site — its slot — and the site says who it is
+ * (`siteId` in ferst-site.json): the platform answers with whichever of the organisation's forms
+ * fills that slot, and the form posts to the site's own address for it. So the organisation can
+ * swap, copy or move forms without anyone editing the site. Pages from before slots name a form
+ * by its id, which still answers; a platform that doesn't know the site (a site id from another
+ * environment) falls back to the form's id.
  */
 export interface FormField {
   name: string;
@@ -24,17 +31,35 @@ type FetchFn = (input: string, init?: RequestInit) => Promise<Response>;
 
 const cache = new Map<string, Promise<FormDefinition>>();
 
-export function loadFormDefinition(id: string, opts: { base: string; fetch?: FetchFn }): Promise<FormDefinition> {
-  const key = `${opts.base}|${id}`;
+export function loadFormDefinition(ref: string, opts: { base: string; siteId?: string | null; fetch?: FetchFn }): Promise<FormDefinition> {
+  const key = `${opts.base}|${opts.siteId ?? ''}|${ref}`;
   let hit = cache.get(key);
   if (!hit) {
-    hit = fetchDefinition(id, opts.base, opts.fetch ?? fetch);
+    hit = opts.siteId ? fetchThroughSite(ref, opts.siteId, opts.base, opts.fetch ?? fetch) : fetchDefinition(ref, opts.base, opts.fetch ?? fetch);
     cache.set(key, hit);
     hit.catch(() => cache.delete(key)); // a failure is retried by the next caller
   }
   return hit;
 }
 
+async function fetchThroughSite(slot: string, siteId: string, base: string, fetchFn: FetchFn): Promise<FormDefinition> {
+  const url = `${base}/sites/${encodeURIComponent(siteId)}/forms/${encodeURIComponent(slot)}`;
+  let res: Response;
+  try {
+    res = await fetchFn(url, { headers: { Accept: 'application/json' } });
+  } catch (e) {
+    throw new Error(`Form block: couldn’t reach the Ferst platform for form "${slot}" (${url}): ${e instanceof Error ? e.message : String(e)}`);
+  }
+  if (res.status === 404) {
+    const body = (await res.json().catch(() => ({}))) as { error?: string };
+    if (body.error === 'site_not_found') return fetchDefinition(slot, base, fetchFn);
+    throw new Error(`Form block: form "${slot}" isn’t on this site. Check its name on the site in the portal (Forms → Place on a site), or run \`npx ferst-modules\` to list this site's forms.`);
+  }
+  if (!res.ok) throw new Error(`Form block: the Ferst platform answered ${res.status} for form "${slot}" (${url}).`);
+  const def = (await res.json()) as { name: string; submit_label?: string; fields?: FormField[]; action: string };
+  return { name: def.name, submitLabel: def.submit_label || 'Send', fields: def.fields ?? [], action: def.action };
+}
+
 async function fetchDefinition(id: string, base: string, fetchFn: FetchFn): Promise<FormDefinition> {
   const url = `${base}/forms/${encodeURIComponent(id)}`;
   let res: Response;

package/lib/git-base.mjs

@@ -46,6 +46,21 @@ export function resolveGitBase(cwd = process.cwd(), branch = deploymentBranch())
   return branch === prodBranch ? PROD_GIT_BASE : DEV_GIT_BASE;
 }
 
+/**
+ * Who this site is on the Ferst platform: `FERST_SITE_ID` env, else ferst-site.json's `siteId`
+ * (written when the site was set up), else null. The Form block asks for its forms through it.
+ */
+export function resolveSiteId(cwd = process.cwd()) {
+  const fromEnv = env('FERST_SITE_ID');
+  if (fromEnv) return fromEnv;
+  try {
+    const site = JSON.parse(readFileSync(resolve(cwd, 'ferst-site.json'), 'utf8'));
+    return site && typeof site.siteId === 'string' && site.siteId.trim() ? site.siteId.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
 /** The deployment branch: CF Pages env → current git branch → main. */
 export function deploymentBranch() {
   const cf = env('CF_PAGES_BRANCH');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ferst-core",
-  "version": "0.9.9",
+  "version": "0.10.0",
   "type": "module",
   "description": "Ferst Core — the shared, brand-agnostic client-site system: Astro components, layouts, content schemas, the layered config resolver, and a neutral styling architecture that every client overrides.",
   "license": "BUSL-1.1",