@ingram-tech/bot-protection 0.2.0 → 0.3.0

package/README.md

@@ -59,6 +59,51 @@ export async function POST(request: Request) {
 `verifyHuman` also accepts a plain object (`{ formData: { ...fields } }`) and a
 `timing` window (`{ minMs, maxMs }`). Pass `botid: false` to skip layer 3.
 
+### Client forms (JSON POST)
+
+For client components that POST JSON instead of a server-rendered `<form>`, use
+the `/react` hook. It fetches the token from your route's `GET` on mount and
+hands you the fields to merge into the body. The route's `GET` returns the
+token; its `POST` verifies:
+
+```tsx
+"use client";
+import { HoneypotInput, useBotProtection } from "@ingram-tech/bot-protection/react";
+
+export function ContactForm() {
+	const { honeypotRef, botFields } = useBotProtection("/api/contact");
+
+	async function onSubmit(values: FormValues) {
+		await fetch("/api/contact", {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ ...values, ...botFields() }),
+		});
+	}
+	return (
+		<form onSubmit={/* ... */}>
+			{/* ...your real fields... */}
+			<HoneypotInput inputRef={honeypotRef} />
+		</form>
+	);
+}
+```
+
+```ts
+// app/api/contact/route.ts
+import { createFormToken, verifyHuman } from "@ingram-tech/bot-protection";
+
+export const GET = () => Response.json({ token: createFormToken() });
+
+export async function POST(request: Request) {
+	const body = await request.json();
+	const result = await verifyHuman({ formData: body });
+	if (!result.ok) return Response.json({ ok: true }); // silently drop
+	// ...send the email / save the lead...
+	return Response.json({ ok: true });
+}
+```
+
 The honeypot field defaults to a name browsers and password managers won't
 autofill (filling it would falsely flag real users). If that default collides
 with a real field in your form, override it on both sides — they must match:

package/dist/react.d.ts

@@ -0,0 +1,31 @@
+import { type RefObject } from "react";
+/**
+ * Client-side bot protection for forms that POST JSON to your own route.
+ *
+ * Fetches a signed timing token from `tokenEndpoint` on mount — the route's GET
+ * handler should return `{ token: createFormToken() }` — then exposes a honeypot
+ * ref plus a `botFields()` helper returning the fields to spread into the
+ * request body. The matching POST handler calls `verifyHuman({ formData: body })`.
+ *
+ * Pair with {@link HoneypotInput}, which renders the trap and wires the ref.
+ *
+ * @param tokenEndpoint - GET route that mints the token (e.g. "/api/contact").
+ *
+ * @example
+ * const { honeypotRef, botFields } = useBotProtection("/api/contact");
+ * // ...in the form:  <HoneypotInput inputRef={honeypotRef} />
+ * // ...on submit:    body: JSON.stringify({ ...values, ...botFields() })
+ */
+export declare function useBotProtection(tokenEndpoint: string): {
+    honeypotRef: RefObject<HTMLInputElement | null>;
+    botFields: () => Record<string, string>;
+};
+/**
+ * Visually-hidden honeypot input for {@link useBotProtection}. Real users never
+ * see or fill it (off-screen, aria-hidden, tabIndex -1, autofill opted out);
+ * bots that fill every field give themselves away.
+ */
+export declare function HoneypotInput({ inputRef, }: {
+    inputRef: RefObject<HTMLInputElement | null>;
+}): import("react/jsx-runtime").JSX.Element;
+//# 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":"AAEA,OAAO,EAAE,KAAK,SAAS,EAA+B,MAAM,OAAO,CAAC;AAGpE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM;;qBAW/B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;EAM5C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAC7B,QAAQ,GACR,EAAE;IACF,QAAQ,EAAE,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;CAC7C,2CAuBA"}

package/dist/react.js

@@ -0,0 +1,51 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { HONEYPOT_FIELD, TOKEN_FIELD } from "./fields";
+/**
+ * Client-side bot protection for forms that POST JSON to your own route.
+ *
+ * Fetches a signed timing token from `tokenEndpoint` on mount — the route's GET
+ * handler should return `{ token: createFormToken() }` — then exposes a honeypot
+ * ref plus a `botFields()` helper returning the fields to spread into the
+ * request body. The matching POST handler calls `verifyHuman({ formData: body })`.
+ *
+ * Pair with {@link HoneypotInput}, which renders the trap and wires the ref.
+ *
+ * @param tokenEndpoint - GET route that mints the token (e.g. "/api/contact").
+ *
+ * @example
+ * const { honeypotRef, botFields } = useBotProtection("/api/contact");
+ * // ...in the form:  <HoneypotInput inputRef={honeypotRef} />
+ * // ...on submit:    body: JSON.stringify({ ...values, ...botFields() })
+ */
+export function useBotProtection(tokenEndpoint) {
+    const [token, setToken] = useState("");
+    const honeypotRef = useRef(null);
+    useEffect(() => {
+        fetch(tokenEndpoint)
+            .then((res) => res.json())
+            .then((data) => setToken(data.token ?? ""))
+            .catch(() => { });
+    }, [tokenEndpoint]);
+    const botFields = () => ({
+        [HONEYPOT_FIELD]: honeypotRef.current?.value ?? "",
+        [TOKEN_FIELD]: token,
+    });
+    return { honeypotRef, botFields };
+}
+/**
+ * Visually-hidden honeypot input for {@link useBotProtection}. Real users never
+ * see or fill it (off-screen, aria-hidden, tabIndex -1, autofill opted out);
+ * bots that fill every field give themselves away.
+ */
+export function HoneypotInput({ inputRef, }) {
+    return (_jsx("input", { ref: inputRef, type: "text", name: HONEYPOT_FIELD, tabIndex: -1, autoComplete: "off", "aria-hidden": "true", defaultValue: "", "data-1p-ignore": true, "data-lpignore": "true", "data-form-type": "other", style: {
+            position: "absolute",
+            left: "-9999px",
+            width: "1px",
+            height: "1px",
+            overflow: "hidden",
+        } }));
+}
+//# 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,EAAkB,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,aAAqB;IACrD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC;IACvC,MAAM,WAAW,GAAG,MAAM,CAAmB,IAAI,CAAC,CAAC;IAEnD,SAAS,CAAC,GAAG,EAAE;QACd,KAAK,CAAC,aAAa,CAAC;aAClB,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;aACzB,IAAI,CAAC,CAAC,IAAwB,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;aAC9D,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACnB,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC;IAEpB,MAAM,SAAS,GAAG,GAA2B,EAAE,CAAC,CAAC;QAChD,CAAC,cAAc,CAAC,EAAE,WAAW,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAClD,CAAC,WAAW,CAAC,EAAE,KAAK;KACpB,CAAC,CAAC;IAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;AACnC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,EAC7B,QAAQ,GAGR;IACA,OAAO,CACN,gBACC,GAAG,EAAE,QAAQ,EACb,IAAI,EAAC,MAAM,EACX,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,CAAC,CAAC,EACZ,YAAY,EAAC,KAAK,iBACN,MAAM,EAClB,YAAY,EAAC,EAAE,2CAGD,MAAM,oBACL,OAAO,EACtB,KAAK,EAAE;YACN,QAAQ,EAAE,UAAU;YACpB,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,KAAK;YACb,QAAQ,EAAE,QAAQ;SAClB,GACA,CACF,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/bot-protection",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Invisible, layered bot protection for forms — honeypot + signed timing token + Vercel BotID.",
 	"license": "MIT",
 	"type": "module",
@@ -24,6 +24,10 @@
 			"types": "./dist/honeypot.d.ts",
 			"import": "./dist/honeypot.js"
 		},
+		"./react": {
+			"types": "./dist/react.d.ts",
+			"import": "./dist/react.js"
+		},
 		"./fields": {
 			"types": "./dist/fields.d.ts",
 			"import": "./dist/fields.js"