@ingram-tech/nk-forms 0.2.0

package/README.md

@@ -0,0 +1,106 @@
+# @ingram-tech/nk-forms
+
+The contact/signup **submission pipeline** for Ingram's Next.js sites: bot
+protection, validation, rate-limit hook, and escaped email notifications behind
+one server handler and one client hook.
+
+It is a thin layer over [`@ingram-tech/bot-protection`](../bot-protection)
+(the security primitive) and [`@ingram-tech/nk-email`](../nk-email) (sending +
+`escapeHtml`). Reach for those directly when you need bot detection somewhere
+that isn't a public form (a checkout, an authed endpoint) — this package is for
+the "validate a public submission and notify a human / subscribe an address"
+shape, and deliberately does **not** try to own Stripe checkout or auth flows.
+
+## What it gives you
+
+- `handleFormSubmission(request, options)` — the fixed pipeline: rate-limit →
+  parse → bot gate → validate → deliver → uniform response. Bot hits and honest
+  submissions return the **same** 200 body, so a bot never learns it was
+  dropped. Returns a web-standard `Response` (no `next` dependency).
+- `renderNotificationEmail({ heading, fields, message, footer })` — builds
+  `{ html, text }` with **every** value escaped. Use it so escaping is the
+  default, not a per-site coin flip.
+- `mintFormToken()` — a ready-made GET handler for the signed timing token.
+- `useFormSubmit(endpoint)` / re-exported `useBotProtection` + `HoneypotInput`
+  from `@ingram-tech/nk-forms/react`.
+
+You still own your **schema** (a Zod schema — accepted structurally, no Zod
+version pin), your **fields/branding**, and your **delivery** (`onSubmit`).
+
+## Route
+
+```ts
+// app/api/contact/route.ts
+import { handleFormSubmission, renderNotificationEmail } from "@ingram-tech/nk-forms";
+import { fromAddress, sendEmail } from "@ingram-tech/nk-email";
+import { z } from "zod";
+
+export { mintFormToken as GET } from "@ingram-tech/nk-forms";
+
+const schema = z.object({
+	name: z.string().trim().min(1).max(200),
+	email: z.string().trim().email().max(320),
+	message: z.string().trim().min(1).max(5000),
+});
+
+export const POST = (request: Request) =>
+	handleFormSubmission(request, {
+		schema,
+		label: "contact",
+		onSubmit: async ({ name, email, message }) => {
+			const { html, text } = renderNotificationEmail({
+				heading: "New contact form submission",
+				fields: [
+					{ label: "Name", value: name },
+					{ label: "Email", value: email },
+				],
+				message,
+				footer: "Sent from the acme.test contact form.",
+			});
+			await sendEmail({
+				to: "studio@acme.test",
+				from: fromAddress("Acme"),
+				replyTo: email,
+				subject: `[Contact] ${name}`,
+				html,
+				text,
+			});
+		},
+	});
+```
+
+Add a rate limiter by passing `rateLimit: () => ({ ok, retryAfterMs })` — plug in
+whatever store you already use; nk-forms owns none.
+
+## Client
+
+```tsx
+"use client";
+import { HoneypotInput, useFormSubmit } from "@ingram-tech/nk-forms/react";
+
+export function ContactForm() {
+	const { honeypotRef, submit, status, error } = useFormSubmit("/api/contact");
+
+	return (
+		<form
+			onSubmit={async (e) => {
+				e.preventDefault();
+				const data = new FormData(e.currentTarget);
+				await submit(Object.fromEntries(data));
+			}}
+		>
+			<HoneypotInput inputRef={honeypotRef} />
+			{/* your fields */}
+			<button disabled={status === "submitting"}>Send</button>
+			{status === "success" && <p>Thanks — we'll be in touch.</p>}
+			{error && <p role="alert">{error}</p>}
+		</form>
+	);
+}
+```
+
+## Environment
+
+Inherits `BOT_PROTECTION_SECRET` from `@ingram-tech/bot-protection` (the timing
+layer; honeypot + BotID run without it) and the mail transport env from
+`@ingram-tech/nk-email`. This package reads no env of its own.

package/dist/email.d.ts

@@ -0,0 +1,30 @@
+/** One labelled row in a notification email. Empty/blank values are dropped. */
+export interface NotificationField {
+    label: string;
+    value: string | null | undefined;
+}
+export interface NotificationEmailOptions {
+    /** The email's heading, e.g. "New contact form submission". */
+    heading: string;
+    /** Labelled key/value rows rendered as a table. */
+    fields?: NotificationField[];
+    /** Free-text body rendered in a pre-wrap block (the user's message). */
+    message?: string | null;
+    /** Small footer line, e.g. "Sent from the acme.test contact form.". */
+    footer?: string;
+}
+export interface RenderedEmail {
+    html: string;
+    text: string;
+}
+/**
+ * Render a submission into `{ html, text }` for `sendEmail`, with **every**
+ * interpolated value escaped via `@ingram-tech/nk-email`'s `escapeHtml`.
+ *
+ * This exists because each site hand-rolled its own notification HTML and most
+ * interpolated `name`/`email`/`message` straight into the markup unescaped — an
+ * HTML-injection footgun in the inbox. Rendering through here makes escaping the
+ * default instead of a per-site coin flip.
+ */
+export declare const renderNotificationEmail: (options: NotificationEmailOptions) => RenderedEmail;
+//# sourceMappingURL=email.d.ts.map

package/dist/email.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.d.ts","sourceRoot":"","sources":["../src/email.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,wBAAwB;IACxC,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC7B,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,YAC1B,wBAAwB,KAC/B,aAgDF,CAAC"}

package/dist/email.js

@@ -0,0 +1,47 @@
+import { escapeHtml } from "@ingram-tech/nk-email";
+/**
+ * Render a submission into `{ html, text }` for `sendEmail`, with **every**
+ * interpolated value escaped via `@ingram-tech/nk-email`'s `escapeHtml`.
+ *
+ * This exists because each site hand-rolled its own notification HTML and most
+ * interpolated `name`/`email`/`message` straight into the markup unescaped — an
+ * HTML-injection footgun in the inbox. Rendering through here makes escaping the
+ * default instead of a per-site coin flip.
+ */
+export const renderNotificationEmail = (options) => {
+    const fields = (options.fields ?? []).filter((field) => typeof field.value === "string" && field.value.trim() !== "");
+    const rows = fields
+        .map((field) => `<tr><td style="padding:4px 12px 4px 0;color:#666;">${escapeHtml(field.label)}</td><td style="padding:4px 0;">${escapeHtml(field.value)}</td></tr>`)
+        .join("");
+    const table = rows
+        ? `<table style="border-collapse:collapse;font-size:14px;">${rows}</table>`
+        : "";
+    const messageBlock = options.message
+        ? `<div style="background:#f5f5f5;padding:16px;border-radius:8px;margin:16px 0;"><p style="white-space:pre-wrap;margin:0;">${escapeHtml(options.message)}</p></div>`
+        : "";
+    const footerBlock = options.footer
+        ? `<p style="color:#888;font-size:13px;margin-top:20px;">${escapeHtml(options.footer)}</p>`
+        : "";
+    const html = [
+        `<div style="font-family:sans-serif;max-width:600px;margin:0 auto;">`,
+        `<h2 style="color:#333;">${escapeHtml(options.heading)}</h2>`,
+        table,
+        messageBlock,
+        footerBlock,
+        `</div>`,
+    ]
+        .filter((part) => part !== "")
+        .join("\n");
+    const textLines = [options.heading, ""];
+    for (const field of fields) {
+        textLines.push(`${field.label}: ${field.value}`);
+    }
+    if (options.message) {
+        textLines.push("", "Message:", options.message);
+    }
+    if (options.footer) {
+        textLines.push("", "---", options.footer);
+    }
+    return { html, text: textLines.join("\n") };
+};
+//# sourceMappingURL=email.js.map

package/dist/email.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.js","sourceRoot":"","sources":["../src/email.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAwBnD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACtC,OAAiC,EACjB,EAAE;IAClB,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,MAAM,CAC3C,CAAC,KAAK,EAA6C,EAAE,CACpD,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAC7D,CAAC;IAEF,MAAM,IAAI,GAAG,MAAM;SACjB,GAAG,CACH,CAAC,KAAK,EAAE,EAAE,CACT,sDAAsD,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,mCAAmC,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,CACpJ;SACA,IAAI,CAAC,EAAE,CAAC,CAAC;IAEX,MAAM,KAAK,GAAG,IAAI;QACjB,CAAC,CAAC,2DAA2D,IAAI,UAAU;QAC3E,CAAC,CAAC,EAAE,CAAC;IAEN,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO;QACnC,CAAC,CAAC,2HAA2H,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY;QACpK,CAAC,CAAC,EAAE,CAAC;IAEN,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM;QACjC,CAAC,CAAC,yDAAyD,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM;QAC3F,CAAC,CAAC,EAAE,CAAC;IAEN,MAAM,IAAI,GAAG;QACZ,qEAAqE;QACrE,2BAA2B,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO;QAC7D,KAAK;QACL,YAAY;QACZ,WAAW;QACX,QAAQ;KACR;SACC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;SAC7B,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,MAAM,SAAS,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACxC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,SAAS,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;IAClD,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACrB,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACpB,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAC7C,CAAC,CAAC"}

package/dist/handler.d.ts

@@ -0,0 +1,58 @@
+import { type VerifyOptions } from "@ingram-tech/bot-protection";
+/**
+ * Decision returned by a caller-supplied rate limiter. nk-forms owns no store —
+ * you plug in your own (per-IP, per-user, Redis, in-memory) and just tell the
+ * handler whether this request may proceed.
+ */
+export interface RateLimitDecision {
+    ok: boolean;
+    /** Milliseconds until the caller may retry; surfaced as a Retry-After header. */
+    retryAfterMs?: number;
+}
+/**
+ * The one method the handler needs from a validator. Any Zod schema satisfies
+ * this structurally, so nk-forms never depends on (or pins) a Zod version.
+ */
+export interface FormSchema<T> {
+    safeParse(input: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+    };
+}
+interface Loggerish {
+    warn(message: string): void;
+    error(message: string, error?: unknown): void;
+}
+export interface FormHandlerOptions<T> {
+    /** Validates (and narrows) the submission. Zod strips bot-protection fields. */
+    schema: FormSchema<T>;
+    /** Deliver the validated submission: send an email, subscribe an address, … */
+    onSubmit: (data: T) => void | Promise<void>;
+    /** Optional gate run before the body is read. Return `ok: false` to 429. */
+    rateLimit?: () => RateLimitDecision | Promise<RateLimitDecision>;
+    /** Bot-protection layers, forwarded to `verifyHuman` (minus `formData`). */
+    verify?: Omit<VerifyOptions, "formData">;
+    /** Where dropped/failed submissions are logged. Defaults to no logging. */
+    logger?: Loggerish;
+    /** Label used in log lines (e.g. "contact", "newsletter"). */
+    label?: string;
+}
+/**
+ * The contact/signup submission pipeline, in fixed order:
+ *
+ *   1. rate limit      → 429 (optional; cheapest, no body needed)
+ *   2. parse JSON body → 400 on malformed input
+ *   3. bot gate        → silent 200 (honeypot + timing token + Vercel BotID)
+ *   4. schema validate → 400 on invalid fields
+ *   5. deliver         → 500 if `onSubmit` throws
+ *   6. success         → 200 { success: true }
+ *
+ * Returns a web-standard `Response`, which Next.js route handlers accept
+ * directly — nk-forms takes no `next` dependency. Pair with `mintFormToken` as
+ * the route's GET and `useFormSubmit`/`useBotProtection` on the client.
+ */
+export declare const handleFormSubmission: <T>(request: Request, options: FormHandlerOptions<T>) => Promise<Response>;
+export {};
+//# sourceMappingURL=handler.d.ts.map

package/dist/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE9E;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC5B,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,KAAK,CAAA;KAAE,CAAC;CAC3E;AAED,UAAU,SAAS;IAClB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACpC,gFAAgF;IAChF,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACjE,4EAA4E;IAC5E,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;IACzC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAYD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,GAAU,CAAC,WAClC,OAAO,WACP,kBAAkB,CAAC,CAAC,CAAC,KAC5B,OAAO,CAAC,QAAQ,CA8DlB,CAAC"}

package/dist/handler.js

@@ -0,0 +1,77 @@
+import { verifyHuman } from "@ingram-tech/bot-protection";
+const json = (data, status = 200) => new Response(JSON.stringify(data), {
+    status,
+    headers: { "content-type": "application/json" },
+});
+// Bot hits and honest submissions return the SAME 200 body — a dropped bot must
+// never be able to tell it was dropped, and a real user is never shown an error.
+const SUCCESS = { success: true };
+/**
+ * The contact/signup submission pipeline, in fixed order:
+ *
+ *   1. rate limit      → 429 (optional; cheapest, no body needed)
+ *   2. parse JSON body → 400 on malformed input
+ *   3. bot gate        → silent 200 (honeypot + timing token + Vercel BotID)
+ *   4. schema validate → 400 on invalid fields
+ *   5. deliver         → 500 if `onSubmit` throws
+ *   6. success         → 200 { success: true }
+ *
+ * Returns a web-standard `Response`, which Next.js route handlers accept
+ * directly — nk-forms takes no `next` dependency. Pair with `mintFormToken` as
+ * the route's GET and `useFormSubmit`/`useBotProtection` on the client.
+ */
+export const handleFormSubmission = async (request, options) => {
+    const label = options.label ?? "form";
+    const log = options.logger;
+    // 1. Rate limit — before touching the body so floods are cheap to reject.
+    if (options.rateLimit) {
+        const decision = await options.rateLimit();
+        if (!decision.ok) {
+            const headers = {
+                "content-type": "application/json",
+            };
+            if (decision.retryAfterMs !== undefined) {
+                headers["retry-after"] = Math.ceil(decision.retryAfterMs / 1000).toString();
+            }
+            return new Response(JSON.stringify({
+                error: "Too many requests. Please try again later.",
+            }), { status: 429, headers });
+        }
+    }
+    // 2. Read the JSON body.
+    let body;
+    try {
+        body = await request.json();
+    }
+    catch {
+        return json({ error: "Invalid request." }, 400);
+    }
+    if (typeof body !== "object" || body === null) {
+        return json({ error: "Invalid request." }, 400);
+    }
+    // 3. Bot gate. On failure, *pretend success* — never tell a bot what tripped
+    //    it, never punish a real user with a visible error.
+    const verdict = await verifyHuman({
+        ...options.verify,
+        formData: body,
+    });
+    if (!verdict.ok) {
+        log?.warn(`${label}: dropped by bot protection (${verdict.reason})`);
+        return json(SUCCESS);
+    }
+    // 4. Validate. A well-behaved schema strips the bot-protection fields.
+    const parsed = options.schema.safeParse(body);
+    if (!parsed.success) {
+        return json({ error: "Invalid form data. Please check your input." }, 400);
+    }
+    // 5. Deliver.
+    try {
+        await options.onSubmit(parsed.data);
+    }
+    catch (error) {
+        log?.error(`${label}: delivery failed`, error);
+        return json({ error: "Failed to submit. Please try again later." }, 500);
+    }
+    return json(SUCCESS);
+};
+//# sourceMappingURL=handler.js.map

package/dist/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { type FormHandlerOptions, type FormSchema, handleFormSubmission, type RateLimitDecision, } from "./handler.js";
+export { type NotificationEmailOptions, type NotificationField, type RenderedEmail, renderNotificationEmail, } from "./email.js";
+export { mintFormToken } from "./token.js";
+export { createFormToken, verifyHuman } from "@ingram-tech/bot-protection";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,oBAAoB,EACpB,KAAK,iBAAiB,GACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,uBAAuB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG3C,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+// Server entry — no React. The client hook and components live at
+// "@ingram-tech/nk-forms/react" so importing the handler never pulls in React.
+export { handleFormSubmission, } from "./handler.js";
+export { renderNotificationEmail, } from "./email.js";
+export { mintFormToken } from "./token.js";
+// Re-export the underlying primitives so a form route is a single import.
+export { createFormToken, verifyHuman } from "@ingram-tech/bot-protection";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,+EAA+E;AAC/E,OAAO,EAGN,oBAAoB,GAEpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAIN,uBAAuB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,0EAA0E;AAC1E,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/react.d.ts

@@ -0,0 +1,30 @@
+export { HoneypotInput, useBotProtection } from "@ingram-tech/bot-protection/react";
+export type FormSubmitStatus = "idle" | "submitting" | "success" | "error";
+export interface FormSubmitResult {
+    ok: boolean;
+    data?: unknown;
+}
+/**
+ * One-import client wiring for a form that POSTs JSON to `endpoint`.
+ *
+ * Wraps {@link useBotProtection} (timing token + honeypot ref) and owns submit
+ * status so the component only renders markup. The route's GET mints the token
+ * (`mintFormToken`) and its POST runs `handleFormSubmission`.
+ *
+ * @example
+ * const { honeypotRef, submit, status, error } = useFormSubmit("/api/contact");
+ * // in the form:  <HoneypotInput inputRef={honeypotRef} />
+ * // on submit:    const res = await submit({ name, email, message });
+ * //               if (res.ok) setSent(true);
+ */
+export declare function useFormSubmit(endpoint: string, options?: {
+    honeypotField?: string;
+}): {
+    honeypotRef: import("react").RefObject<HTMLInputElement | null>;
+    botFields: () => Record<string, string>;
+    ready: boolean;
+    status: FormSubmitStatus;
+    error: string | null;
+    submit: (values: Record<string, unknown>) => Promise<FormSubmitResult>;
+};
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAMA,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAEpF,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC;AAE3E,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAcD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;qBAM1E,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,OAAO,CAAC,gBAAgB,CAAC;EA6B5B"}

package/dist/react.js

@@ -0,0 +1,58 @@
+"use client";
+import { useState } from "react";
+import { useBotProtection } from "@ingram-tech/bot-protection/react";
+// Re-export the primitives so a form component needs a single import.
+export { HoneypotInput, useBotProtection } from "@ingram-tech/bot-protection/react";
+const getErrorMessage = (data) => {
+    if (typeof data === "object" &&
+        data !== null &&
+        "error" in data &&
+        typeof data.error === "string") {
+        return data.error;
+    }
+    return null;
+};
+/**
+ * One-import client wiring for a form that POSTs JSON to `endpoint`.
+ *
+ * Wraps {@link useBotProtection} (timing token + honeypot ref) and owns submit
+ * status so the component only renders markup. The route's GET mints the token
+ * (`mintFormToken`) and its POST runs `handleFormSubmission`.
+ *
+ * @example
+ * const { honeypotRef, submit, status, error } = useFormSubmit("/api/contact");
+ * // in the form:  <HoneypotInput inputRef={honeypotRef} />
+ * // on submit:    const res = await submit({ name, email, message });
+ * //               if (res.ok) setSent(true);
+ */
+export function useFormSubmit(endpoint, options) {
+    const { honeypotRef, botFields, ready } = useBotProtection(endpoint, options);
+    const [status, setStatus] = useState("idle");
+    const [error, setError] = useState(null);
+    const submit = async (values) => {
+        setStatus("submitting");
+        setError(null);
+        try {
+            const res = await fetch(endpoint, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ ...values, ...botFields() }),
+            });
+            const data = await res.json().catch(() => ({}));
+            if (!res.ok) {
+                throw new Error(getErrorMessage(data) ?? "Something went wrong. Please try again.");
+            }
+            setStatus("success");
+            return { ok: true, data };
+        }
+        catch (submitError) {
+            setStatus("error");
+            setError(submitError instanceof Error
+                ? submitError.message
+                : "Something went wrong. Please try again.");
+            return { ok: false };
+        }
+    };
+    return { honeypotRef, botFields, ready, status, error, submit };
+}
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAErE,sEAAsE;AACtE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AASpF,MAAM,eAAe,GAAG,CAAC,IAAa,EAAiB,EAAE;IACxD,IACC,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACb,OAAO,IAAI,IAAI;QACf,OAAQ,IAA2B,CAAC,KAAK,KAAK,QAAQ,EACrD,CAAC;QACF,OAAQ,IAA0B,CAAC,KAAK,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,OAAoC;IACnF,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,gBAAgB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9E,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAmB,MAAM,CAAC,CAAC;IAC/D,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IAExD,MAAM,MAAM,GAAG,KAAK,EACnB,MAA+B,EACH,EAAE;QAC9B,SAAS,CAAC,YAAY,CAAC,CAAC;QACxB,QAAQ,CAAC,IAAI,CAAC,CAAC;QACf,IAAI,CAAC;YACJ,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE;gBACjC,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,GAAG,SAAS,EAAE,EAAE,CAAC;aACnD,CAAC,CAAC;YACH,MAAM,IAAI,GAAY,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YACzD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACb,MAAM,IAAI,KAAK,CACd,eAAe,CAAC,IAAI,CAAC,IAAI,yCAAyC,CAClE,CAAC;YACH,CAAC;YACD,SAAS,CAAC,SAAS,CAAC,CAAC;YACrB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAC3B,CAAC;QAAC,OAAO,WAAW,EAAE,CAAC;YACtB,SAAS,CAAC,OAAO,CAAC,CAAC;YACnB,QAAQ,CACP,WAAW,YAAY,KAAK;gBAC3B,CAAC,CAAC,WAAW,CAAC,OAAO;gBACrB,CAAC,CAAC,yCAAyC,CAC5C,CAAC;YACF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;QACtB,CAAC;IACF,CAAC,CAAC;IAEF,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AACjE,CAAC"}

package/dist/token.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Ready-made GET handler that mints the signed timing token the client hook
+ * fetches on mount. Wire it into any form route with one line:
+ *
+ *   export { mintFormToken as GET } from "@ingram-tech/nk-forms";
+ *
+ * or alongside other GET logic:  `export const GET = () => mintFormToken();`
+ *
+ * Returns `{ token: "" }` when `BOT_PROTECTION_SECRET` is unset (the timing
+ * layer is simply disabled — honeypot + BotID still run).
+ */
+export declare const mintFormToken: () => Response;
+//# sourceMappingURL=token.d.ts.map

package/dist/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,QAAO,QAG9B,CAAC"}

package/dist/token.js

@@ -0,0 +1,16 @@
+import { createFormToken } from "@ingram-tech/bot-protection";
+/**
+ * Ready-made GET handler that mints the signed timing token the client hook
+ * fetches on mount. Wire it into any form route with one line:
+ *
+ *   export { mintFormToken as GET } from "@ingram-tech/nk-forms";
+ *
+ * or alongside other GET logic:  `export const GET = () => mintFormToken();`
+ *
+ * Returns `{ token: "" }` when `BOT_PROTECTION_SECRET` is unset (the timing
+ * layer is simply disabled — honeypot + BotID still run).
+ */
+export const mintFormToken = () => new Response(JSON.stringify({ token: createFormToken() }), {
+    headers: { "content-type": "application/json" },
+});
+//# sourceMappingURL=token.js.map

package/dist/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAa,EAAE,CAC3C,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,EAAE,CAAC,EAAE;IAC1D,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;CAC/C,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "@ingram-tech/nk-forms",
+	"version": "0.2.0",
+	"description": "Contact/signup form pipeline for Next.js sites — bot protection, validation, and escaped email notifications in one handler.",
+	"license": "MIT",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ingram-technologies/nextkit.git",
+		"directory": "packages/nk-forms"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./react": {
+			"types": "./dist/react.d.ts",
+			"import": "./dist/react.js"
+		}
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"type-check": "tsc -p tsconfig.json --noEmit",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@ingram-tech/bot-protection": "0.4.0",
+		"@ingram-tech/nk-email": "0.3.1"
+	},
+	"devDependencies": {
+		"@ingram-tech/nk-dev": "0.5.0",
+		"@types/node": "^26.1.1",
+		"@types/react": "^19.2.17",
+		"react": "^19.2.7",
+		"typescript": "^7.0.2",
+		"vitest": "^4.1.10"
+	},
+	"peerDependencies": {
+		"react": "^18.0.0 || ^19.0.0"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		}
+	}
+}