@materializecms/server 0.3.0 → 0.5.0

package/src/forms.d.ts

@@ -0,0 +1,47 @@
+import { type FormDefinition } from '@materializecms/core/page';
+import type { SubmissionFile } from '@materializecms/db';
+/** Settings for every form, kept in the "forms" setting. */
+export interface FormsSettings {
+    /** Messages older than this many months are deleted with their files; unset keeps them. */
+    keepMonths?: number;
+    /** Signs webhook calls, so the receiver can tell they come from this site. */
+    webhookSecret?: string;
+}
+export interface FieldIssue {
+    field: string;
+    message: string;
+}
+/** A sent file, before it is saved. */
+export interface IncomingFile {
+    field: string;
+    name: string;
+    type: string;
+    bytes: Uint8Array;
+}
+/**
+ * What a form sent, checked against the form on the page: only its fields, the required ones
+ * filled in, emails that look like emails, choices from the list, files of the right kind and
+ * size. Without a definition (a form the site built by hand) the values are taken as they come.
+ */
+export declare function readSubmission(raw: Record<string, unknown>, def: FormDefinition | null): Promise<{
+    data: Record<string, string>;
+    files: IncomingFile[];
+    issues: FieldIssue[];
+}>;
+/**
+ * Why a message looks like spam, without a CAPTCHA: filled in at once, too many links, links
+ * hidden in markup. Null for a message that looks real. Repeats are checked by the caller.
+ */
+export declare function spamReason(data: Record<string, string>, elapsedMs: number | null): string | null;
+/** The same words from the same form: two identical messages in a day are a repeat. */
+export declare const fingerprintOf: (form: string, data: Record<string, string>) => string;
+/** Saves a message's files in its own folder, out of reach of the public site. */
+export declare function saveFiles(dir: string, id: string, files: IncomingFile[]): Promise<SubmissionFile[]>;
+export declare const removeFiles: (dir: string, id: string) => Promise<void>;
+/** The signature of a webhook body: `sha256=` and the HMAC of the body with the site's secret. */
+export declare const webhookSignature: (secret: string, body: string) => string;
+/**
+ * Posts a message to a webhook (Zapier, Make, n8n…), signed; tries three times, waiting a little
+ * longer each time. Resolves with whether it was taken.
+ */
+export declare function sendWebhook(url: string, payload: unknown, secret: string, wait?: (ms: number) => Promise<void>): Promise<boolean>;

package/src/forms.js

@@ -0,0 +1,153 @@
+import { createHash, createHmac } from 'node:crypto';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+import { FILE_TYPES, FORM_FILE_MAX } from '@materializecms/core/page';
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const isFile = (v) => typeof v === 'object' && v !== null && 'arrayBuffer' in v && typeof v.name === 'string';
+/**
+ * What a form sent, checked against the form on the page: only its fields, the required ones
+ * filled in, emails that look like emails, choices from the list, files of the right kind and
+ * size. Without a definition (a form the site built by hand) the values are taken as they come.
+ */
+export async function readSubmission(raw, def) {
+    const data = {};
+    const files = [];
+    const issues = [];
+    if (!def) {
+        for (const [k, v] of Object.entries(raw)) {
+            if (k.startsWith('_') || typeof v !== 'string' || Object.keys(data).length >= 30)
+                continue;
+            data[k.slice(0, 80)] = v.slice(0, 5000);
+        }
+        return { data, files, issues };
+    }
+    for (const field of def.fields) {
+        const value = raw[field.name];
+        if (field.kind === 'file') {
+            const file = isFile(value) && value.size > 0 ? value : null;
+            if (!file) {
+                if (field.required)
+                    issues.push({ field: field.name, message: 'Allega un file' });
+                continue;
+            }
+            const allowed = FILE_TYPES[field.accept ?? 'any'];
+            if (!allowed.includes(extname(file.name).toLowerCase())) {
+                issues.push({ field: field.name, message: `Questo tipo di file non è accettato (${allowed.join(', ')})` });
+                continue;
+            }
+            if (file.size > FORM_FILE_MAX) {
+                issues.push({ field: field.name, message: `Il file supera ${FORM_FILE_MAX / 1024 / 1024} MB` });
+                continue;
+            }
+            files.push({
+                field: field.name,
+                name: file.name,
+                type: file.type,
+                bytes: new Uint8Array(await file.arrayBuffer()),
+            });
+            data[field.name] = file.name;
+            continue;
+        }
+        const text = typeof value === 'string' ? value.trim().slice(0, 5000) : '';
+        if (field.kind === 'checkbox') {
+            if (text)
+                data[field.name] = 'sì';
+            else if (field.required)
+                issues.push({ field: field.name, message: 'Va spuntata per inviare' });
+            continue;
+        }
+        if (!text) {
+            if (field.required)
+                issues.push({ field: field.name, message: 'Campo obbligatorio' });
+            continue;
+        }
+        if (field.kind === 'email' && !EMAIL.test(text)) {
+            issues.push({ field: field.name, message: 'Scrivi un indirizzo email valido' });
+            continue;
+        }
+        if (field.kind === 'select' && field.options?.length && !field.options.includes(text)) {
+            issues.push({ field: field.name, message: 'Scegli una delle voci dell’elenco' });
+            continue;
+        }
+        data[field.name] = text;
+    }
+    return { data, files, issues };
+}
+/** A form filled in faster than this is a bot (people need a few seconds at least). */
+const MIN_FILL_MS = 2500;
+/**
+ * Why a message looks like spam, without a CAPTCHA: filled in at once, too many links, links
+ * hidden in markup. Null for a message that looks real. Repeats are checked by the caller.
+ */
+export function spamReason(data, elapsedMs) {
+    if (elapsedMs !== null && elapsedMs >= 0 && elapsedMs < MIN_FILL_MS)
+        return 'Compilato in meno di 3 secondi';
+    const text = Object.values(data).join('\n');
+    if (/\[url=|<a\s+href|\[link=/i.test(text))
+        return 'Link nascosti nel testo';
+    const links = text.match(/https?:\/\/|www\./gi)?.length ?? 0;
+    if (links > 3)
+        return `Troppi link (${links})`;
+    return null;
+}
+/** The same words from the same form: two identical messages in a day are a repeat. */
+export const fingerprintOf = (form, data) => createHash('sha256')
+    .update(form)
+    .update(JSON.stringify(Object.entries(data)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([k, v]) => [k, v.toLowerCase().replace(/\s+/g, ' ')])))
+    .digest('hex');
+/** A file name safe on any disk, keeping its extension. */
+const safeName = (name) => name
+    .normalize('NFKD')
+    .replace(/[^\w.-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(-80) || 'file';
+/** Saves a message's files in its own folder, out of reach of the public site. */
+export async function saveFiles(dir, id, files) {
+    if (!files.length)
+        return [];
+    const folder = join(dir, id);
+    await mkdir(folder, { recursive: true });
+    const saved = [];
+    for (const [i, f] of files.entries()) {
+        const path = `${id}/${i + 1}-${safeName(f.name)}`;
+        await writeFile(join(dir, path), f.bytes);
+        saved.push({ field: f.field, name: f.name, size: f.bytes.length, type: f.type, path });
+    }
+    return saved;
+}
+export const removeFiles = (dir, id) => rm(join(dir, id), { recursive: true, force: true }).catch(() => { });
+/** The signature of a webhook body: `sha256=` and the HMAC of the body with the site's secret. */
+export const webhookSignature = (secret, body) => `sha256=${createHmac('sha256', secret).update(body).digest('hex')}`;
+/**
+ * Posts a message to a webhook (Zapier, Make, n8n…), signed; tries three times, waiting a little
+ * longer each time. Resolves with whether it was taken.
+ */
+export async function sendWebhook(url, payload, secret, wait = (ms) => new Promise((r) => setTimeout(r, ms))) {
+    const body = JSON.stringify(payload);
+    for (const delay of [0, 20_000, 120_000]) {
+        if (delay)
+            await wait(delay);
+        try {
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'user-agent': 'Materialize-Webhook',
+                    'x-materialize-signature': webhookSignature(secret, body),
+                },
+                body,
+                redirect: 'error',
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (res.ok)
+                return true;
+            // The receiver refused it on purpose: trying again would not help.
+            if (res.status >= 400 && res.status < 500 && res.status !== 429)
+                return false;
+        }
+        catch { }
+    }
+    return false;
+}

package/src/tools.js

@@ -257,7 +257,7 @@ export function assistantTools(call, page, brand) {
         },
     });
     return [
-        ...contentTools(call, getSchema).filter((t) => t.name !== 'publish_entry' && t.name !== 'unpublish_entry'),
+        ...contentTools(call, getSchema).filter((t) => !['publish_entry', 'unpublish_entry', 'schedule_entry', 'share_preview'].includes(t.name)),
         ...pageTools({ source, withId: false, brand: async () => brand }),
     ];
 }
@@ -368,6 +368,38 @@ export function contentTools(call, getSchema) {
                 return { id: doc.id, title: doc.title, published: false };
             },
         }),
+        tool({
+            name: 'schedule_entry',
+            title: 'Programmo',
+            description: 'Sets when an entry goes on the public site (publish) or comes off it (unpublish) by itself, as an ISO date with time zone, e.g. 2026-11-10T09:00:00+01:00. at null cancels. The draft as it is at that moment is what gets published.',
+            input: z.object({
+                id: z.string(),
+                action: z.enum(['publish', 'unpublish']),
+                at: z.string().nullable(),
+            }),
+            run: async (input) => {
+                const doc = await call('PUT', `/api/documents/${encodeURIComponent(input.id)}/schedule`, { action: input.action, at: input.at });
+                return {
+                    id: doc.id,
+                    title: doc.title,
+                    publishAt: doc.schedule.publish?.runAt ?? null,
+                    unpublishAt: doc.schedule.unpublish?.runAt ?? null,
+                };
+            },
+        }),
+        tool({
+            name: 'share_preview',
+            title: 'Creo un link di anteprima',
+            description: 'A secret link that shows an entry’s latest saved draft with the site’s design to someone without an account (a client, a colleague). It follows later edits. days: how long it works (default 7), null until revoked.',
+            input: z.object({
+                id: z.string(),
+                days: z.number().int().min(1).max(365).nullable().optional(),
+            }),
+            run: async (input) => {
+                const link = await call('POST', `/api/documents/${encodeURIComponent(input.id)}/previews`, { days: input.days === undefined ? 7 : input.days });
+                return { url: link.url, expiresAt: link.expiresAt };
+            },
+        }),
         tool({
             name: 'list_translations',
             title: 'Guardo le lingue',