@gravixar/forms 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gravixar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# @gravixar/forms
+
+Public form submissions for server actions and route handlers. A form is defined once: its schema, bot gate,
+identity and delivery. `submit` then runs them in the order live forms do:
+
+1. **The bot gate, on the raw input.** A honeypot and a time trap, and optionally Vercel BotID. It runs before
+   validation, so a bot never sees an error naming the field it should have left empty. A bot gets the same "ok"
+   as a person, and every ignored submission is logged with its reason.
+2. **Validation**, with any [Standard Schema](https://standardschema.dev) validator (zod v4 is one), static or
+   built per locale for localized messages. The result has the first error per field path.
+3. **An id.** Parts you choose are hashed into a stable id, so a bot replaying one payload makes one record.
+4. **Delivery steps**, in order, each returning evidence. **In production, a required step that isn't configured
+   fails the submission**, so a missing API key shows the visitor an error instead of losing what they sent.
+
+It was extracted from three live forms: a bilingual enquiry form, a registration form stored for a CRM, and a
+booking endpoint behind BotID.
+
+## Two entry points
+
+- `@gravixar/forms`: client-safe. The field names a form renders, and the types. A test walks this entry's module
+  graph and fails if it reaches server code, because a client component ships everything it imports.
+- `@gravixar/forms/server`: everything that runs a submission.
+
+## Define
+
+```ts
+// src/forms/enquiry.ts
+import { defineForm, resendMailer } from "@gravixar/forms/server";
+import { Resend } from "resend";
+import { z } from "zod";
+
+const mailer = resendMailer({ Resend, from: "Website <website@example.com>", fromEnv: "ENQUIRY_FROM" });
+
+export const enquiry = defineForm({
+  name: "enquiry", // the record's kind, the dedupe namespace, the log prefix
+  schema: ({ locale }) =>
+    z.object({
+      name: z.string().trim().min(2, msg.name[locale]).max(120),
+      email: z.union([z.literal(""), z.email(msg.email[locale])]),
+      message: z.string().trim().min(1, msg.message[locale]).max(5000),
+    }),
+  // Optional. Default: honeypot "website", time trap on "ts" (2 s to 24 h), no BotID.
+  gate: { botId: checkBotId },
+  // Optional: parts hashed into the id. Omit for a random id.
+  dedupe: (data) => [normalizeEmail(data.email), data.name],
+  // A function of the step builders, so each step's callbacks see the schema's output.
+  deliver: ({ blob, email }) => [
+    blob({ store, path: (s) => `enquiries/${s.receivedAt.slice(0, 7)}.jsonl`, required: true }),
+    email({
+      mailer,
+      to: process.env.ENQUIRY_TO,
+      subject: (s) => `Enquiry from ${s.data.name}`,
+      text: (s) => s.data.message,
+      replyTo: (s) => s.data.email || undefined,
+      required: false, // stored already, so a failed email is recorded, not fatal
+    }),
+  ],
+});
+```
+
+`defineForm` throws a `FormError` when a definition can't work: no required step, two steps with one name, a
+schema that validates a gate field, a name that isn't a lower-case id. It throws when the module loads, so the
+mistake fails the build.
+
+## Submit
+
+```ts
+// src/app/actions.ts
+"use server";
+import { fromFormData, metaFromHeaders } from "@gravixar/forms/server";
+import type { FormState } from "@gravixar/forms";
+import { headers } from "next/headers";
+import { enquiry } from "@/forms/enquiry";
+
+export async function submitEnquiry(_prev: FormState, fd: FormData): Promise<FormState> {
+  const locale = pickLocale(fd);
+  const result = await enquiry.submit(fromFormData(fd), { locale, meta: metaFromHeaders(await headers()) });
+  if (result.outcome === "failed") return { status: "error", errors: { form: msg.failed[locale] } };
+  return result.state;
+}
+```
+
+`result.outcome` is `delivered`, `ignored` (a bot), `invalid` (with `errors`) or `failed` (a required step
+failed). `result.state` is ready for `useActionState`. `fromFormData` turns an absent field into `undefined`,
+never `null`, and treats an empty file input as absent. List repeated fields in `{ multiple: ["files"] }`.
+
+## Render
+
+```tsx
+import { HONEYPOT_FIELD, TIMESTAMP_FIELD, honeypotInputProps } from "@gravixar/forms";
+
+<div className="hp" aria-hidden="true">
+  <label>Website<input {...honeypotInputProps} /></label>
+</div>
+<input type="hidden" name={TIMESTAMP_FIELD} value={renderedAt} /> {/* Date.now(), set once on mount */}
+```
+
+Put the honeypot off-screen with CSS, not `display: none`, which some bots skip. **A form without the timestamp is
+ignored**, so add it before switching a live form over.
+
+## Delivery steps
+
+- `email({ mailer, to, subject, text, replyTo?, attachments?, required })`. When `to` is empty, the step isn't
+  configured. `toAttachments(files)` turns uploads into attachments.
+- `blob({ store, path, toLine?, required })` appends one JSON line per submission, the format a CRM sync reads.
+  `store` is a `LineStore`, `{ configured(), appendLine(path, line) }`, over whatever storage the site uses.
+  `toLine` returns the record to write; by default it is the whole submission.
+- A site's own step implements `DeliveryStep<T>`: `{ name, required, configured(), run(submission) }`, where
+  `run` returns `{ ok: true, ref? }` or `{ ok: false, error }`. A throw is caught and recorded the same way.
+
+Every step runs, so one failing doesn't stop another from delivering. Outside production, a step that isn't
+configured only logs the submission (a dry run). Production is `VERCEL_ENV=production` on Vercel, whose previews
+also set `NODE_ENV=production`, and `NODE_ENV=production` elsewhere.
+
+`resendMailer({ Resend, from, fromEnv?, replyTo?, replyToEnv?, apiKeyEnv? })` takes the SDK's class, so this
+package doesn't depend on `resend`. The key is read on each send. The SDK returns API and network failures as
+`{ error }` instead of throwing, so the mailer reads `error` on every send.
+
+## Helpers
+
+- `normalizeEmail(email)` collapses Gmail's dots and `+tags` to the one inbox they reach. For dedupe only.
+- `stableId(parts)`: SHA-256 of the parts joined by `|`, first 32 hex characters, with Web Crypto.
+- `checkGate(input, options?)`: the gate on its own, for a route handler that isn't a form.
+
+## License
+
+[MIT](LICENSE)

package/dist/fields.d.ts

@@ -0,0 +1,18 @@
+/** The honeypot. It is rendered off-screen, so a person never fills it and a bot that fills every input does. */
+export declare const HONEYPOT_FIELD = "website";
+/** The time the form was rendered, in Unix milliseconds, set once when the form mounts. */
+export declare const TIMESTAMP_FIELD = "ts";
+/**
+ * The honeypot name Gravixar's private backend package used. The gate accepts it as well, so forms that render it
+ * keep working when that package re-exports this one.
+ */
+export declare const LEGACY_HONEYPOT_FIELD = "hp_website";
+/**
+ * Spread onto the honeypot `<input>`. Keyboard users can't tab into it and autofill leaves it alone. Place it
+ * off-screen with CSS, not `display: none`, which some bots skip.
+ */
+export declare const honeypotInputProps: {
+    readonly name: "website";
+    readonly tabIndex: -1;
+    readonly autoComplete: "off";
+};

package/dist/fields.js

@@ -0,0 +1,18 @@
+/*
+ * The field names a form component renders and the server checks. Both entry points export them from here, so the
+ * hidden inputs and the gate can't drift apart. This module imports nothing: it is part of the client entry's graph.
+ */
+/** The honeypot. It is rendered off-screen, so a person never fills it and a bot that fills every input does. */
+export const HONEYPOT_FIELD = "website";
+/** The time the form was rendered, in Unix milliseconds, set once when the form mounts. */
+export const TIMESTAMP_FIELD = "ts";
+/**
+ * The honeypot name Gravixar's private backend package used. The gate accepts it as well, so forms that render it
+ * keep working when that package re-exports this one.
+ */
+export const LEGACY_HONEYPOT_FIELD = "hp_website";
+/**
+ * Spread onto the honeypot `<input>`. Keyboard users can't tab into it and autofill leaves it alone. Place it
+ * off-screen with CSS, not `display: none`, which some bots skip.
+ */
+export const honeypotInputProps = { name: HONEYPOT_FIELD, tabIndex: -1, autoComplete: "off" };

package/dist/form.d.ts

@@ -0,0 +1,73 @@
+import { type GateOptions } from "./gate.js";
+import { type BlobStepOptions, type EmailStepOptions } from "./steps.js";
+import type { StandardSchema } from "./standard-schema.js";
+import type { Submission, SubmissionMeta, SubmitResult } from "./types.js";
+/** A form definition that can't work. Thrown when the module loads, so it fails the site's build. */
+export declare class FormError extends Error {
+    name: string;
+}
+/** Vercel BotID's verdict, from `checkBotId()` in `botid/server`. */
+export interface BotIdVerdict {
+    isBot?: boolean;
+    isVerifiedBot?: boolean;
+}
+/** What a step reports. The form adds the step's name and the time to make its `Evidence`. */
+export type StepOutcome = {
+    ok: true;
+    ref?: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** One place a submission goes. `emailStep` and `blobStep` are two; a site can write its own. */
+export interface DeliveryStep<T> {
+    readonly name: string;
+    /** A required step that fails makes the submission `failed`. At least one step must be required. */
+    readonly required: boolean;
+    /** False when a key, token or address is missing. */
+    configured(): boolean;
+    /** What a missing configuration needs, for the log: `"RESEND_API_KEY"`. */
+    readonly needs?: string;
+    /** Returns the failure rather than throwing it; a throw is caught and recorded the same way. */
+    run(submission: Submission<T>): Promise<StepOutcome>;
+}
+/** The output type of a Standard Schema validator. */
+export type InferOutput<S extends StandardSchema> = NonNullable<S["~standard"]["types"]>["output"];
+export interface FormDefinition<S extends StandardSchema, T = InferOutput<S>> {
+    /** Lower-case id: the record's kind, the dedupe namespace and the log prefix. */
+    name: string;
+    /** A Standard Schema validator (zod v4 is one), or a function that builds one per locale for its messages. */
+    schema: S | ((context: {
+        locale: string;
+    }) => S);
+    gate?: GateOptions & {
+        /** Blocks unverified bots. For forms that email an address the caller supplies. */
+        botId?: () => Promise<BotIdVerdict>;
+    };
+    /** Parts that identify a submission, hashed with the form's name into its id. Omit for a random id. */
+    dedupe?: (data: T) => readonly string[];
+    /**
+     * Run in order. Every step runs, so one failing doesn't stop another from delivering.
+     *
+     * Write it as a function of the step builders, `({ email, blob }) => [...]`: they are bound to the schema's output,
+     * so each step's callbacks see typed data. TypeScript can't carry that type into `emailStep(...)` calls in a plain
+     * array; a plain array suits steps that are already typed, such as a site's own.
+     */
+    deliver: readonly DeliveryStep<T>[] | ((steps: StepBuilders<T>) => readonly DeliveryStep<T>[]);
+}
+/** `emailStep` and `blobStep`, bound to a form's data type. */
+export interface StepBuilders<T> {
+    email(options: EmailStepOptions<T>): DeliveryStep<T>;
+    blob(options: BlobStepOptions<T>): DeliveryStep<T>;
+}
+export interface SubmitContext {
+    locale: string;
+    meta?: SubmissionMeta;
+}
+export interface Form<T> {
+    readonly name: string;
+    /** Gate, then validation, then the id, then every delivery step. Resolves; it doesn't throw for a bad submission. */
+    submit(input: Record<string, unknown>, context: SubmitContext): Promise<SubmitResult<T>>;
+}
+/** Defines a form. Throws a `FormError` when the definition can't work, so the mistake fails the build. */
+export declare function defineForm<S extends StandardSchema>(definition: FormDefinition<S>): Form<InferOutput<S>>;

package/dist/form.js

@@ -0,0 +1,150 @@
+import { HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELD, TIMESTAMP_FIELD } from "./fields.js";
+import { checkGate, gateFields } from "./gate.js";
+import { errorMessage, isProduction, randomId, stableId } from "./helpers.js";
+import { blobStep, emailStep } from "./steps.js";
+/** A form definition that can't work. Thrown when the module loads, so it fails the site's build. */
+export class FormError extends Error {
+    name = "FormError";
+}
+const OK = { status: "ok" };
+/** Defines a form. Throws a `FormError` when the definition can't work, so the mistake fails the build. */
+export function defineForm(definition) {
+    const { name, schema, gate = {}, dedupe } = definition;
+    const deliver = typeof definition.deliver === "function"
+        ? definition.deliver({ email: emailStep, blob: blobStep })
+        : definition.deliver;
+    const log = `[forms:${name}]`;
+    if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+        throw new FormError(`Form name "${name}" must be a lower-case id, such as "enquiry".`);
+    }
+    if (!deliver.some((step) => step.required)) {
+        throw new FormError(`${log} needs at least one required delivery step, or a failed delivery would pass as success.`);
+    }
+    const stepNames = deliver.map((step) => step.name);
+    const repeated = stepNames.find((step, i) => stepNames.indexOf(step) !== i);
+    if (repeated)
+        throw new FormError(`${log} has two delivery steps named "${repeated}". Give one a \`name\`.`);
+    const fields = gateFields(gate);
+    if (gate.honeypot !== false && gate.timeTrap !== false) {
+        const timestamp = gate.timeTrap?.field ?? TIMESTAMP_FIELD;
+        if ([gate.honeypot ?? HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELD].includes(timestamp)) {
+            throw new FormError(`${log} uses "${timestamp}" for both the honeypot and the timestamp.`);
+        }
+    }
+    if (gate.timeTrap) {
+        const { minMs = 0, maxAgeMs = Infinity } = gate.timeTrap;
+        if (!(minMs >= 0 && maxAgeMs > minMs)) {
+            throw new FormError(`${log} time trap needs 0 <= minMs < maxAgeMs, not ${minMs} and ${maxAgeMs}.`);
+        }
+    }
+    if (typeof schema !== "function")
+        assertNoClash(schema);
+    function assertNoClash(built) {
+        const clash = schemaKeys(built)?.find((key) => fields.includes(key));
+        if (clash) {
+            throw new FormError(`${log} validates "${clash}", which the gate reads and removes. Rename the field, or set the gate's field.`);
+        }
+    }
+    function ignored(reason) {
+        // Silent to the bot, never to us: browsers autofill hidden fields, and this is the one path that can drop a
+        // real person without an error or a record.
+        console.warn(`${log} ignored a submission: ${reason}`);
+        return { outcome: "ignored", reason, state: OK };
+    }
+    return {
+        name,
+        async submit(input, context) {
+            const verdict = checkGate(input, gate);
+            if (!verdict.ok)
+                return ignored(verdict.reason);
+            if (gate.botId) {
+                let bot;
+                try {
+                    bot = await gate.botId();
+                }
+                catch (error) {
+                    // Fail open: the static gate has already passed, and dropping a real person silently is the worse error.
+                    console.error(`${log} BotID check failed, so it was skipped: ${errorMessage(error)}`);
+                }
+                if (bot?.isBot && !bot.isVerifiedBot)
+                    return ignored("botid");
+            }
+            const built = typeof schema === "function" ? schema({ locale: context.locale }) : schema;
+            if (typeof schema === "function")
+                assertNoClash(built);
+            const values = { ...input };
+            for (const field of fields)
+                delete values[field];
+            const result = await built["~standard"].validate(values);
+            if (result.issues) {
+                const errors = firstErrors(result.issues);
+                return { outcome: "invalid", errors, state: { status: "error", errors } };
+            }
+            const data = result.value;
+            const submission = {
+                id: dedupe ? await stableId([name, ...dedupe(data)]) : randomId(),
+                form: name,
+                data,
+                locale: context.locale,
+                meta: context.meta ?? {},
+                receivedAt: new Date().toISOString(),
+            };
+            const production = isProduction();
+            const evidence = [];
+            let failed = false;
+            for (const step of deliver) {
+                const record = await runStep(step, submission, production, log);
+                evidence.push(record);
+                if (!record.ok && step.required)
+                    failed = true;
+            }
+            return failed
+                ? { outcome: "failed", id: submission.id, evidence, state: { status: "error" } }
+                : { outcome: "delivered", id: submission.id, evidence, state: OK };
+        },
+    };
+}
+async function runStep(step, submission, production, log) {
+    const at = () => new Date().toISOString();
+    const needs = step.needs ? ` (needs ${step.needs})` : "";
+    if (!step.configured()) {
+        if (!production) {
+            console.info(`${log} dry run: "${step.name}" is not configured${needs}, submission ${submission.id}`);
+            return { step: step.name, ok: true, dryRun: true, at: at() };
+        }
+        console.error(`${log} "${step.name}" is not configured${needs}, so submission ${submission.id} was not sent there`);
+        return { step: step.name, ok: false, error: `not configured${needs}`, at: at() };
+    }
+    let outcome;
+    try {
+        outcome = await step.run(submission);
+    }
+    catch (error) {
+        outcome = { ok: false, error: errorMessage(error) };
+    }
+    if (!outcome.ok) {
+        console.error(`${log} "${step.name}" failed for submission ${submission.id}: ${outcome.error}`);
+        return { step: step.name, ok: false, error: outcome.error, at: at() };
+    }
+    return outcome.ref === undefined
+        ? { step: step.name, ok: true, at: at() }
+        : { step: step.name, ok: true, ref: outcome.ref, at: at() };
+}
+/** The first message per field path; an issue with no path is keyed `form`. */
+function firstErrors(issues) {
+    const errors = {};
+    for (const issue of issues) {
+        const key = (issue.path ?? []).map((part) => String(typeof part === "object" ? part.key : part)).join(".") || "form";
+        errors[key] ??= issue.message;
+    }
+    return errors;
+}
+/** An object schema's field names, where the validator exposes them: zod's `shape`, valibot's `entries`. */
+function schemaKeys(schema) {
+    for (const property of ["shape", "entries"]) {
+        const value = schema[property];
+        if (typeof value === "object" && value !== null)
+            return Object.keys(value);
+    }
+    return undefined;
+}

package/dist/gate.d.ts

@@ -0,0 +1,30 @@
+import type { GateReason } from "./types.js";
+/** The fastest a person fills a form, in milliseconds. */
+export declare const MIN_FILL_MS = 2000;
+/** A form older than this was cached or replayed, in milliseconds. */
+export declare const MAX_FORM_AGE_MS: number;
+export interface GateOptions {
+    /** The honeypot field. Default `"website"`; `"hp_website"` is always checked too. `false` turns it off. */
+    honeypot?: string | false;
+    /** The time trap. On by default, and a missing timestamp fails it. `false` turns it off. */
+    timeTrap?: {
+        field?: string;
+        minMs?: number;
+        maxAgeMs?: number;
+    } | false;
+}
+export type GateVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: GateReason;
+};
+/** The field names the gate reads, so they can be kept out of validation. */
+export declare function gateFields(options?: GateOptions): string[];
+/**
+ * The bot gate, on the raw input, before validation: a validator that rejected a filled honeypot would name the
+ * field in its error, telling a bot exactly what to leave empty. Pure and synchronous; BotID is a form option.
+ *
+ * An absent value is `undefined` or `null`. Anything else in the honeypot other than blank text trips it.
+ */
+export declare function checkGate(input: Record<string, unknown>, options?: GateOptions, nowMs?: number): GateVerdict;

package/dist/gate.js

@@ -0,0 +1,52 @@
+import { HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELD, TIMESTAMP_FIELD } from "./fields.js";
+/** The fastest a person fills a form, in milliseconds. */
+export const MIN_FILL_MS = 2_000;
+/** A form older than this was cached or replayed, in milliseconds. */
+export const MAX_FORM_AGE_MS = 24 * 60 * 60 * 1000;
+/** The field names the gate reads, so they can be kept out of validation. */
+export function gateFields(options = {}) {
+    const fields = new Set();
+    if (options.honeypot !== false)
+        fields.add(options.honeypot ?? HONEYPOT_FIELD).add(LEGACY_HONEYPOT_FIELD);
+    if (options.timeTrap !== false)
+        fields.add(options.timeTrap?.field ?? TIMESTAMP_FIELD);
+    return [...fields];
+}
+/**
+ * The bot gate, on the raw input, before validation: a validator that rejected a filled honeypot would name the
+ * field in its error, telling a bot exactly what to leave empty. Pure and synchronous; BotID is a form option.
+ *
+ * An absent value is `undefined` or `null`. Anything else in the honeypot other than blank text trips it.
+ */
+export function checkGate(input, options = {}, nowMs = Date.now()) {
+    if (options.honeypot !== false) {
+        for (const field of [options.honeypot ?? HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELD]) {
+            if (filled(input[field]))
+                return { ok: false, reason: "honeypot_filled" };
+        }
+    }
+    if (options.timeTrap !== false) {
+        const { field = TIMESTAMP_FIELD, minMs = MIN_FILL_MS, maxAgeMs = MAX_FORM_AGE_MS } = options.timeTrap ?? {};
+        const raw = input[field];
+        if (raw === undefined || raw === null || raw === "")
+            return { ok: false, reason: "ts_missing" };
+        if (typeof raw !== "string" && typeof raw !== "number")
+            return { ok: false, reason: "ts_invalid" };
+        const ts = Number(raw);
+        if (!Number.isFinite(ts))
+            return { ok: false, reason: "ts_invalid" };
+        const age = nowMs - ts;
+        if (age < minMs)
+            return { ok: false, reason: "ts_too_fast" };
+        if (age > maxAgeMs)
+            return { ok: false, reason: "ts_stale" };
+    }
+    return { ok: true };
+}
+function filled(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === "string")
+        return value.trim().length > 0;
+    return true;
+}

package/dist/helpers.d.ts

@@ -0,0 +1,36 @@
+import type { SubmissionMeta } from "./types.js";
+/**
+ * Collapses an address to the inbox it reaches. Gmail ignores dots and everything after `+`, so a bot can mint
+ * endless unique-looking addresses for one mailbox. For dedupe only: never reject with it, and never store it in
+ * place of what the person typed.
+ */
+export declare function normalizeEmail(email: string): string;
+/**
+ * SHA-256 of the parts joined by `|`, as its first 32 hex characters. A bot replaying one payload makes one id, so
+ * a store keyed on it keeps one record. Web Crypto, never `node:crypto`, so no Node builtin can reach a client chunk.
+ */
+export declare function stableId(parts: readonly string[]): Promise<string>;
+/** A random id in the same shape as `stableId`. */
+export declare function randomId(): string;
+export type FormValue = string | File;
+/**
+ * Turns `FormData` into a plain object for `form.submit`. An absent field is `undefined`, never `null`: a `null`
+ * from `fd.get()` once read as a malformed honeypot, and as a timestamp 56 years old. An empty file input (a
+ * zero-byte `File`, which browsers send when nothing is chosen) counts as absent. A field listed in `multiple`
+ * is always an array. Strings are passed as typed; trimming is the schema's job.
+ */
+export declare function fromFormData(fd: FormData, options?: {
+    multiple?: readonly string[];
+}): Record<string, FormValue | FormValue[] | undefined>;
+/** The IP and user agent of a request, from its headers (Next's `await headers()`, or `request.headers`). */
+export declare function metaFromHeaders(headers: {
+    get(name: string): string | null;
+}): SubmissionMeta;
+/** Reads an environment variable where there is one: Node, and the server runtimes that provide `process.env`. */
+export declare function env(name: string): string | undefined;
+/**
+ * Production means a submission that isn't delivered is lost. On Vercel that is `VERCEL_ENV=production` (previews
+ * run with `NODE_ENV=production` too, so it can't be used there); elsewhere, `NODE_ENV=production`.
+ */
+export declare function isProduction(): boolean;
+export declare function errorMessage(error: unknown): string;

package/dist/helpers.js

@@ -0,0 +1,80 @@
+/**
+ * Collapses an address to the inbox it reaches. Gmail ignores dots and everything after `+`, so a bot can mint
+ * endless unique-looking addresses for one mailbox. For dedupe only: never reject with it, and never store it in
+ * place of what the person typed.
+ */
+export function normalizeEmail(email) {
+    const lower = email.trim().toLowerCase();
+    const at = lower.lastIndexOf("@");
+    if (at < 1)
+        return lower;
+    const local = lower.slice(0, at);
+    const domain = lower.slice(at + 1);
+    if (domain !== "gmail.com" && domain !== "googlemail.com")
+        return lower;
+    return `${(local.split("+")[0] ?? "").replace(/\./g, "")}@gmail.com`;
+}
+/**
+ * SHA-256 of the parts joined by `|`, as its first 32 hex characters. A bot replaying one payload makes one id, so
+ * a store keyed on it keeps one record. Web Crypto, never `node:crypto`, so no Node builtin can reach a client chunk.
+ */
+export async function stableId(parts) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(parts.join("|")));
+    return hex(new Uint8Array(digest)).slice(0, 32);
+}
+/** A random id in the same shape as `stableId`. */
+export function randomId() {
+    return crypto.randomUUID().replaceAll("-", "");
+}
+function hex(bytes) {
+    let out = "";
+    for (const byte of bytes)
+        out += byte.toString(16).padStart(2, "0");
+    return out;
+}
+/**
+ * Turns `FormData` into a plain object for `form.submit`. An absent field is `undefined`, never `null`: a `null`
+ * from `fd.get()` once read as a malformed honeypot, and as a timestamp 56 years old. An empty file input (a
+ * zero-byte `File`, which browsers send when nothing is chosen) counts as absent. A field listed in `multiple`
+ * is always an array. Strings are passed as typed; trimming is the schema's job.
+ */
+export function fromFormData(fd, options = {}) {
+    const multiple = new Set(options.multiple ?? []);
+    const out = {};
+    for (const key of new Set(fd.keys())) {
+        const values = fd.getAll(key).filter((value) => typeof value === "string" || value.size > 0);
+        if (multiple.has(key))
+            out[key] = values;
+        else if (values.length > 0)
+            out[key] = values[0];
+    }
+    for (const key of multiple)
+        out[key] ??= [];
+    return out;
+}
+/** The IP and user agent of a request, from its headers (Next's `await headers()`, or `request.headers`). */
+export function metaFromHeaders(headers) {
+    const meta = {};
+    const ip = headers.get("x-forwarded-for")?.split(",")[0]?.trim() || headers.get("x-real-ip")?.trim();
+    const userAgent = headers.get("user-agent");
+    if (ip)
+        meta.ip = ip;
+    if (userAgent)
+        meta.userAgent = userAgent;
+    return meta;
+}
+/** Reads an environment variable where there is one: Node, and the server runtimes that provide `process.env`. */
+export function env(name) {
+    return globalThis.process?.env?.[name];
+}
+/**
+ * Production means a submission that isn't delivered is lost. On Vercel that is `VERCEL_ENV=production` (previews
+ * run with `NODE_ENV=production` too, so it can't be used there); elsewhere, `NODE_ENV=production`.
+ */
+export function isProduction() {
+    const vercel = env("VERCEL_ENV");
+    return vercel ? vercel === "production" : env("NODE_ENV") === "production";
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { HONEYPOT_FIELD, TIMESTAMP_FIELD, honeypotInputProps } from "./fields.js";
+export type { Evidence, FormState, GateReason, SubmitResult } from "./types.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+/*
+ * @gravixar/forms: the client-safe entry. A form component imports the field names and types from here. Everything
+ * that runs a submission is in `@gravixar/forms/server`: a client component that imports server code ships it to
+ * the browser, so nothing reachable from this file may import a Node builtin or server code. A test walks this
+ * entry's module graph to hold that.
+ */
+export { HONEYPOT_FIELD, TIMESTAMP_FIELD, honeypotInputProps } from "./fields.js";

package/dist/server.d.ts

@@ -0,0 +1,11 @@
+export { defineForm, FormError } from "./form.js";
+export type { BotIdVerdict, DeliveryStep, Form, FormDefinition, InferOutput, StepBuilders, StepOutcome, SubmitContext } from "./form.js";
+export { checkGate, MAX_FORM_AGE_MS, MIN_FILL_MS } from "./gate.js";
+export type { GateOptions, GateVerdict } from "./gate.js";
+export { fromFormData, metaFromHeaders, normalizeEmail, stableId } from "./helpers.js";
+export type { FormValue } from "./helpers.js";
+export { blobStep, emailStep, resendMailer, toAttachments } from "./steps.js";
+export type { Attachment, BlobStepOptions, EmailStepOptions, LineStore, MailMessage, Mailer, ResendClient } from "./steps.js";
+export { HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELD, TIMESTAMP_FIELD, honeypotInputProps } from "./fields.js";
+export type { StandardIssue, StandardResult, StandardSchema } from "./standard-schema.js";
+export type { Evidence, FormState, GateReason, Submission, SubmissionMeta, SubmitResult } from "./types.js";

package/dist/server.js

@@ -0,0 +1,13 @@
+/*
+ * @gravixar/forms/server: everything that runs a submission. Import it from server actions and route handlers only.
+ *
+ * A form defines its schema, gate, identity and delivery once; `submit` then runs them in the order the live forms
+ * do: the bot gate on the raw input, validation, the id, then every delivery step. In production a required step
+ * that isn't configured fails the submission, so a missing key shows the visitor an error instead of losing what
+ * they sent.
+ */
+export { defineForm, FormError } from "./form.js";
+export { checkGate, MAX_FORM_AGE_MS, MIN_FILL_MS } from "./gate.js";
+export { fromFormData, metaFromHeaders, normalizeEmail, stableId } from "./helpers.js";
+export { blobStep, emailStep, resendMailer, toAttachments } from "./steps.js";
+export { HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELD, TIMESTAMP_FIELD, honeypotInputProps } from "./fields.js";

package/dist/standard-schema.d.ts

@@ -0,0 +1,23 @@
+export interface StandardSchema<Input = unknown, Output = Input> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+    };
+}
+export type StandardResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: readonly StandardIssue[];
+};
+export interface StandardIssue {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | {
+        readonly key: PropertyKey;
+    })[] | undefined;
+}

package/dist/standard-schema.js

@@ -0,0 +1,3 @@
+// The Standard Schema v1 interface (https://standardschema.dev), declared here as the spec asks instead of taken
+// as a dependency. zod v4, valibot and arktype implement it, so a site brings whichever validator it already uses.
+export {};

package/dist/steps.d.ts

@@ -0,0 +1,109 @@
+import type { DeliveryStep, StepOutcome } from "./form.js";
+import type { Submission } from "./types.js";
+type Maybe<T> = T | Promise<T>;
+export interface Attachment {
+    filename: string;
+    /** Bytes, or a base64 string. */
+    content: Uint8Array | string;
+}
+export interface MailMessage {
+    to: string | readonly string[];
+    subject: string;
+    text: string;
+    replyTo?: string;
+    attachments?: readonly Attachment[];
+}
+/** Sends one message. `resendMailer` is one; a test or another provider can be another. */
+export interface Mailer {
+    configured(): boolean;
+    /** What a missing configuration needs, for the log. */
+    readonly needs?: string;
+    /** Returns the failure rather than throwing it. */
+    send(message: MailMessage): Promise<StepOutcome>;
+}
+export interface EmailStepOptions<T> {
+    /** Default `"email"`. Set it when a form has two email steps. */
+    name?: string;
+    mailer: Mailer;
+    /** Usually an environment variable. When it is empty, the step isn't configured. */
+    to: string | readonly string[] | undefined;
+    subject: (submission: Submission<T>) => string;
+    text: (submission: Submission<T>) => string;
+    replyTo?: (submission: Submission<T>) => string | undefined;
+    attachments?: (submission: Submission<T>) => Maybe<readonly Attachment[]>;
+    required: boolean;
+}
+/** Emails each submission. */
+export declare function emailStep<T>(options: EmailStepOptions<T>): DeliveryStep<T>;
+/** The part of the Resend SDK the mailer uses. */
+export interface ResendClient {
+    emails: {
+        send(payload: {
+            from: string;
+            to: string | string[];
+            subject: string;
+            text: string;
+            replyTo?: string;
+            attachments?: {
+                filename: string;
+                content: string;
+            }[];
+        }): Promise<{
+            data: {
+                id: string;
+            } | null;
+            error: {
+                name?: string;
+                message: string;
+            } | null;
+        }>;
+    };
+}
+/**
+ * A mailer over the Resend SDK. Pass the SDK's class (`import { Resend } from "resend"`), so this package doesn't
+ * depend on it. The key is read on every send, so one added after boot works without a restart.
+ *
+ * Resend returns API and network failures as `{ error }` instead of throwing, so a `try/catch` alone sees none of
+ * them. This reads `error` on every send, and catches a throw as well.
+ */
+export declare function resendMailer(options: {
+    Resend: new (key: string) => ResendClient;
+    /** Default `"RESEND_API_KEY"`. */
+    apiKeyEnv?: string;
+    /** The sender, `"Name <address@domain>"`. */
+    from: string;
+    /** An environment variable that overrides `from` when set. */
+    fromEnv?: string;
+    /** Used when a step doesn't set its own. */
+    replyTo?: string;
+    replyToEnv?: string;
+}): Mailer & {
+    client(): ResendClient | null;
+    readonly from: string;
+    readonly replyTo: string | undefined;
+};
+/** Uploaded files as attachments, with names reduced to safe characters. */
+export declare function toAttachments(files: readonly File[]): Promise<Attachment[]>;
+/** Appends one line to a file. A site adapts its storage to this: Vercel Blob, a bucket, a database table. */
+export interface LineStore {
+    configured(): boolean;
+    /** What a missing configuration needs, for the log. */
+    readonly needs?: string;
+    /** Throws when the line wasn't written. */
+    appendLine(path: string, line: string): Promise<void>;
+}
+export interface BlobStepOptions<T> {
+    /** Default `"blob"`. */
+    name?: string;
+    store: LineStore;
+    path: (submission: Submission<T>) => string;
+    /** The record to write. Default: the whole submission. */
+    toLine?: (submission: Submission<T>) => unknown;
+    required: boolean;
+}
+/**
+ * Appends each submission as one JSON line: the format a CRM sync reads month by month. By default the line is
+ * the whole submission; `toLine` returns the record to write instead. Files in the data don't survive JSON.
+ */
+export declare function blobStep<T>(options: BlobStepOptions<T>): DeliveryStep<T>;
+export {};

package/dist/steps.js

@@ -0,0 +1,134 @@
+import { env, errorMessage } from "./helpers.js";
+/** Emails each submission. */
+export function emailStep(options) {
+    const { mailer, to } = options;
+    const recipients = typeof to === "string" ? [to] : (to ?? []);
+    const hasRecipient = recipients.some((address) => address.trim() !== "");
+    return {
+        name: options.name ?? "email",
+        required: options.required,
+        configured: () => hasRecipient && mailer.configured(),
+        get needs() {
+            const missing = [];
+            if (!mailer.configured())
+                missing.push(mailer.needs ?? "a mailer");
+            if (!hasRecipient)
+                missing.push("a recipient");
+            return missing.length > 0 ? missing.join(" and ") : undefined;
+        },
+        async run(submission) {
+            const message = {
+                to: recipients,
+                subject: options.subject(submission),
+                text: options.text(submission),
+            };
+            const replyTo = options.replyTo?.(submission);
+            if (replyTo)
+                message.replyTo = replyTo;
+            const attachments = await options.attachments?.(submission);
+            if (attachments?.length)
+                message.attachments = attachments;
+            return mailer.send(message);
+        },
+    };
+}
+/**
+ * A mailer over the Resend SDK. Pass the SDK's class (`import { Resend } from "resend"`), so this package doesn't
+ * depend on it. The key is read on every send, so one added after boot works without a restart.
+ *
+ * Resend returns API and network failures as `{ error }` instead of throwing, so a `try/catch` alone sees none of
+ * them. This reads `error` on every send, and catches a throw as well.
+ */
+export function resendMailer(options) {
+    const apiKeyEnv = options.apiKeyEnv ?? "RESEND_API_KEY";
+    let client = null;
+    let clientKey;
+    const mailer = {
+        needs: apiKeyEnv,
+        configured: () => Boolean(env(apiKeyEnv)),
+        /** The SDK client, built once per key. `null` without a key. */
+        client() {
+            const key = env(apiKeyEnv);
+            if (!key)
+                return null;
+            if (!client || clientKey !== key) {
+                client = new options.Resend(key);
+                clientKey = key;
+            }
+            return client;
+        },
+        get from() {
+            return (options.fromEnv && env(options.fromEnv)) || options.from;
+        },
+        get replyTo() {
+            return (options.replyToEnv && env(options.replyToEnv)) || options.replyTo;
+        },
+        async send(message) {
+            const resend = mailer.client();
+            if (!resend)
+                return { ok: false, error: `${apiKeyEnv} is not set` };
+            const replyTo = message.replyTo ?? mailer.replyTo;
+            try {
+                const { data, error } = await resend.emails.send({
+                    from: mailer.from,
+                    to: typeof message.to === "string" ? message.to : [...message.to],
+                    subject: message.subject,
+                    text: message.text,
+                    ...(replyTo ? { replyTo } : {}),
+                    ...(message.attachments?.length
+                        ? {
+                            attachments: message.attachments.map(({ filename, content }) => ({
+                                filename,
+                                // The SDK puts content into a JSON body as it is, where bytes would not survive; base64 does.
+                                content: typeof content === "string" ? content : base64(content),
+                            })),
+                        }
+                        : {}),
+                });
+                if (error)
+                    return { ok: false, error: `${error.name ?? "error"}: ${error.message}` };
+                if (!data?.id)
+                    return { ok: false, error: "Resend returned neither an id nor an error" };
+                return { ok: true, ref: data.id };
+            }
+            catch (error) {
+                return { ok: false, error: errorMessage(error) };
+            }
+        },
+    };
+    return mailer;
+}
+/** Uploaded files as attachments, with names reduced to safe characters. */
+export async function toAttachments(files) {
+    return Promise.all(files.map(async (file) => ({
+        filename: file.name.replace(/[^\w.\- ]+/g, "_").slice(0, 120),
+        content: new Uint8Array(await file.arrayBuffer()),
+    })));
+}
+function base64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(binary);
+}
+/**
+ * Appends each submission as one JSON line: the format a CRM sync reads month by month. By default the line is
+ * the whole submission; `toLine` returns the record to write instead. Files in the data don't survive JSON.
+ */
+export function blobStep(options) {
+    const { store } = options;
+    const step = {
+        name: options.name ?? "blob",
+        required: options.required,
+        configured: () => store.configured(),
+        async run(submission) {
+            const path = options.path(submission);
+            const line = JSON.stringify(options.toLine ? options.toLine(submission) : submission);
+            if (line === undefined)
+                return { ok: false, error: "toLine returned nothing to write" };
+            await store.appendLine(path, line);
+            return { ok: true, ref: path };
+        },
+    };
+    return store.needs ? { ...step, needs: store.needs } : step;
+}

package/dist/types.d.ts

@@ -0,0 +1,60 @@
+/** What a server action returns to `useActionState`. A bot and a person get the same "ok". */
+export type FormState = {
+    status: "idle" | "ok" | "error";
+    errors?: Record<string, string>;
+};
+/** Why the gate ignored a submission. For logs only: never tell the client which check tripped. */
+export type GateReason = "honeypot_filled" | "ts_missing" | "ts_invalid" | "ts_too_fast" | "ts_stale" | "botid";
+/** What one delivery step did with a submission. */
+export interface Evidence {
+    step: string;
+    ok: boolean;
+    /** Where it went: an email id, a file path. */
+    ref?: string;
+    error?: string;
+    /** The step wasn't configured outside production, so it only logged the submission. */
+    dryRun?: boolean;
+    at: string;
+}
+/** Request details kept with a submission, for forensics. */
+export interface SubmissionMeta {
+    ip?: string;
+    userAgent?: string;
+}
+/** A validated submission, as the delivery steps receive it. */
+export interface Submission<T> {
+    /** 32 hex characters: derived from the form's `dedupe` parts, or random. */
+    id: string;
+    form: string;
+    data: T;
+    locale: string;
+    meta: SubmissionMeta;
+    receivedAt: string;
+}
+export type SubmitResult<T> = 
+/** Every required step delivered. */
+{
+    outcome: "delivered";
+    id: string;
+    evidence: Evidence[];
+    state: FormState;
+}
+/** The gate stopped a bot. Its state is the same "ok" a person gets. */
+ | {
+    outcome: "ignored";
+    reason: GateReason;
+    state: FormState;
+}
+/** The first error per field path, in the locale's messages. */
+ | {
+    outcome: "invalid";
+    errors: Record<string, string>;
+    state: FormState;
+}
+/** A required step failed. Show the localized error and a fallback contact. */
+ | {
+    outcome: "failed";
+    id: string;
+    evidence: Evidence[];
+    state: FormState;
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+// Types shared by both entry points. This module has no runtime code.
+export {};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@gravixar/forms",
+  "version": "0.1.0",
+  "description": "Public form submissions for server actions: a bot gate that runs before validation, any Standard Schema validator, stable ids for dedupe, and delivery steps that fail closed in production.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p test/tsconfig.json",
+    "test": "node --test \"test/*.test.mjs\"",
+    "prepack": "tsc -p tsconfig.json",
+    "prepublishOnly": "tsc -p tsconfig.json && tsc -p test/tsconfig.json && node --test \"test/*.test.mjs\""
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gravixar-sv/gravixar-kit.git",
+    "directory": "packages/forms"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "resend": "^6.30.0",
+    "typescript": "^6.0.3",
+    "zod": "^4.6.5"
+  }
+}