@prosopo/procaptcha-bundle 4.2.5 → 4.4.0

package/src/index.ts

@@ -13,11 +13,18 @@
 // limitations under the License.
 
 import { getWindowCallback } from "@prosopo/procaptcha-common";
-import type { EnvironmentTypes, ProcaptchaRenderOptions } from "@prosopo/types";
+import {
+	type EnvironmentTypes,
+	PROCAPTCHA_START_EVENT,
+	type ProcaptchaRenderOptions,
+	type ProcaptchaStartEventDetail,
+	StartModeEnum,
+} from "@prosopo/types";
 import { at } from "@prosopo/util";
 import type { Root } from "react-dom/client";
 import { extractParams, getProcaptchaScript } from "./util/config.js";
-import { WidgetFactory } from "./util/widgetFactory.js";
+import { resolveStartMode } from "./util/startMode.js";
+import { type CreatedWidget, WidgetFactory } from "./util/widgetFactory.js";
 import { WidgetThemeResolver } from "./util/widgetThemeResolver.js";
 
 const BUNDLE_NAMES = ["procaptcha.bundle.iife.js", "procaptcha.bundle.js"];
@@ -36,9 +43,12 @@ const BUNDLE_NAMES = ["procaptcha.bundle.iife.js", "procaptcha.bundle.js"];
 interface WidgetEntry {
 	root: Root;
 	element: Element;
+	/** The element the widget listens on; a targeted execute() is dispatched here. */
+	target: HTMLElement;
 	renderOptions: ProcaptchaRenderOptions;
 	isWeb2: boolean;
 	invisible: boolean;
+	unbindTrigger?: () => void;
 }
 
 const procaptchaWidgets = new Map<string, WidgetEntry>();
@@ -47,17 +57,18 @@ let widgetIdCounter = 0;
 const nextWidgetId = (): string => `procaptcha-widget-${widgetIdCounter++}`;
 
 const registerWidgets = (
-	roots: Root[],
+	widgets: CreatedWidget[],
 	elements: Element[],
 	renderOptions: ProcaptchaRenderOptions,
 	isWeb2: boolean,
 	invisible: boolean,
 ): string[] =>
-	roots.map((root, index) => {
+	widgets.map(({ root, container }, index) => {
 		const id = nextWidgetId();
 		procaptchaWidgets.set(id, {
 			root,
 			element: at(elements, index),
+			target: container,
 			renderOptions,
 			isWeb2,
 			invisible,
@@ -80,9 +91,10 @@ const widgetFactory = new WidgetFactory(new WidgetThemeResolver());
  */
 const startDetectorPrefetch = (
 	siteKey: string | null,
-	flags: { ipv4?: boolean; ipv6?: boolean },
+	flags: { ipv4?: boolean; ipv6?: boolean; startMode?: StartModeEnum },
 ): void => {
 	if (!siteKey) return;
+	if (flags.startMode === StartModeEnum.manual) return;
 	void Promise.all([
 		import("@prosopo/procaptcha-frictionless"),
 		import("@prosopo/procaptcha-common"),
@@ -117,6 +129,7 @@ const implicitRender = async () => {
 		const web3 = firstElement.getAttribute("data-web3");
 		const ipv4 = firstElement.getAttribute("data-ipv4") === "true";
 		const ipv6 = firstElement.getAttribute("data-ipv6") === "true";
+		const startMode = resolveStartMode(undefined, firstElement);
 		if (!siteKey) {
 			console.error("No site key found");
 			return;
@@ -127,27 +140,35 @@ const implicitRender = async () => {
 		// constant. Start it now so the round-trip overlaps the widget's own
 		// dynamic-import chain instead of queueing behind it —
 		// `customDetectBot` claims the in-flight promise when it eventually runs.
-		startDetectorPrefetch(siteKey, { ipv4, ipv6 });
+		startDetectorPrefetch(siteKey, { ipv4, ipv6, startMode });
 
 		const implicitRenderOptions: ProcaptchaRenderOptions = {
 			siteKey: siteKey,
 			ipv4,
 			ipv6,
+			startMode,
 		};
 
-		const root = await widgetFactory.createWidgets(
+		const widgets = await widgetFactory.createWidgets(
 			elements,
 			implicitRenderOptions,
 			!(web3 === "true"),
 		);
 
-		registerWidgets(
-			root,
+		const ids = registerWidgets(
+			widgets,
 			elements,
 			implicitRenderOptions,
 			!(web3 === "true"),
 			false,
 		);
+
+		// `data-placement` is read per element by the renderer; `data-bind` is
+		// wired here because the trigger lives outside the widget.
+		ids.forEach((id, index) => {
+			const selector = at(elements, index).getAttribute("data-bind");
+			if (selector) bindTrigger(id, selector);
+		});
 	}
 
 	// Check for invisible mode indicators (procaptcha class on buttons)
@@ -161,29 +182,37 @@ const implicitRender = async () => {
 			const callback = button.getAttribute("data-callback") || "";
 			const ipv4 = button.getAttribute("data-ipv4") === "true";
 			const ipv6 = button.getAttribute("data-ipv6") === "true";
+			const startMode = resolveStartMode(undefined, button);
 
-			startDetectorPrefetch(siteKey, { ipv4, ipv6 });
+			startDetectorPrefetch(siteKey, { ipv4, ipv6, startMode });
 
 			const buttonRenderOptions: ProcaptchaRenderOptions = {
 				siteKey: siteKey,
 				callback: callback,
 				ipv4,
 				ipv6,
+				startMode,
 			};
 
-			const root = await widgetFactory.createWidgets(
+			const widgets = await widgetFactory.createWidgets(
 				[button],
 				buttonRenderOptions,
 				true,
 				true,
 			);
 
-			registerWidgets(root, [button], buttonRenderOptions, true, true);
+			const [id] = registerWidgets(
+				widgets,
+				[button],
+				buttonRenderOptions,
+				true,
+				true,
+			);
 
 			// Add click event listener to the button
 			button.addEventListener("click", async (event) => {
 				event.preventDefault();
-				execute();
+				execute(id);
 			});
 		}
 	}
@@ -203,7 +232,10 @@ export const render = async (
 	element: Element,
 	renderOptions: ProcaptchaRenderOptions,
 ): Promise<string | undefined> => {
-	startDetectorPrefetch(renderOptions.siteKey, renderOptions);
+	startDetectorPrefetch(renderOptions.siteKey, {
+		...renderOptions,
+		startMode: resolveStartMode(renderOptions, element),
+	});
 
 	const hasInvisibleSize =
 		Object.prototype.hasOwnProperty.call(renderOptions, "size") &&
@@ -213,7 +245,7 @@ export const render = async (
 	const invisible =
 		hasInvisibleSize || element.tagName.toLowerCase() === "button";
 
-	const roots = await widgetFactory.createWidgets(
+	const widgets = await widgetFactory.createWidgets(
 		[element],
 		renderOptions,
 		isWeb2,
@@ -221,7 +253,7 @@ export const render = async (
 	);
 
 	const ids = registerWidgets(
-		roots,
+		widgets,
 		[element],
 		renderOptions,
 		isWeb2,
@@ -230,7 +262,10 @@ export const render = async (
 
 	// Deliberately not `at()`: it throws on an empty array before it consults
 	// `optional`, and zero roots is a legitimate outcome here.
-	return ids[0];
+	const id = ids[0];
+	if (id && renderOptions.bind) bindTrigger(id, renderOptions.bind);
+
+	return id;
 };
 
 export default function ready(fn: () => void) {
@@ -247,8 +282,21 @@ export default function ready(fn: () => void) {
 	}
 }
 
-export const execute = () => {
-	const containers = findProcaptchaContainers();
+/**
+ * Starts verification. With no id the event goes to `document` and every
+ * widget responds; with an id (as returned by `render()`) only that widget
+ * runs.
+ */
+export const execute = (widgetId?: string) => {
+	const targeted =
+		undefined === widgetId ? undefined : procaptchaWidgets.get(widgetId);
+
+	if (undefined !== widgetId && !targeted) {
+		console.error(`No Procaptcha widget found with id ${widgetId}`);
+		return;
+	}
+
+	const containers = targeted ? [targeted.element] : findProcaptchaContainers();
 
 	if (containers.length === 0) {
 		console.error("No Procaptcha containers found for execution");
@@ -262,14 +310,77 @@ export const execute = () => {
 			containerCount: containers.length,
 			timestamp: Date.now(),
 		},
-		bubbles: true,
+		// A targeted event must not bubble to document, where every widget listens.
+		bubbles: !targeted,
 		cancelable: true,
 	});
 
+	if (targeted) {
+		targeted.target.dispatchEvent(executeEvent);
+		return;
+	}
+
 	// Dispatch the event on the document
 	document.dispatchEvent(executeEvent);
 };
 
+/**
+ * The click's default is prevented so a submit button does not post the form
+ * before a token exists.
+ */
+const bindTrigger = (widgetId: string, selector: string): void => {
+	const entry = procaptchaWidgets.get(widgetId);
+	if (!entry) {
+		console.error(`No Procaptcha widget found with id ${widgetId}`);
+		return;
+	}
+
+	const trigger = document.querySelector(selector);
+	if (!trigger) {
+		console.error(`Procaptcha: no element matches bind selector ${selector}`);
+		return;
+	}
+
+	// Binding the same widget twice would otherwise stack listeners and leave
+	// the earlier one behind, since only the last unbind is remembered.
+	entry.unbindTrigger?.();
+
+	const onClick = (event: Event) => {
+		event.preventDefault();
+		execute(widgetId);
+	};
+
+	trigger.addEventListener("click", onClick);
+	entry.unbindTrigger = () => trigger.removeEventListener("click", onClick);
+};
+
+/** Starts a `startMode: "manual"` widget; omit the id to start all of them. */
+export const start = (widgetId?: string): void => {
+	const ids: string[] =
+		undefined === widgetId ? Array.from(procaptchaWidgets.keys()) : [widgetId];
+
+	if (ids.length === 0) {
+		console.error("No Procaptcha widgets found to start");
+		return;
+	}
+
+	for (const id of ids) {
+		const entry = procaptchaWidgets.get(id);
+		if (!entry) {
+			console.error(`No Procaptcha widget found with id ${id}`);
+			continue;
+		}
+		const detail: ProcaptchaStartEventDetail = { element: entry.element };
+		document.dispatchEvent(
+			new CustomEvent<ProcaptchaStartEventDetail>(PROCAPTCHA_START_EVENT, {
+				detail,
+				bubbles: true,
+				cancelable: false,
+			}),
+		);
+	}
+};
+
 function findProcaptchaContainers(): Element[] {
 	const containers: Element[] = [];
 
@@ -310,11 +421,12 @@ declare global {
 			reset: typeof reset;
 			remove: typeof remove;
 			execute: typeof execute;
+			start: typeof start;
 		};
 	}
 }
 
-const start = () => {
+const boot = () => {
 	// onLoadUrlCallback defines the name of the callback function to be called when the script is loaded
 	// onRenderExplicit takes values of either explicit or implicit
 	const { onloadUrlCallback, renderExplicit } = extractParams(BUNDLE_NAMES);
@@ -352,7 +464,7 @@ const start = () => {
  * widget id to reset one widget, or omit it to reset every widget on the page.
  *
  * This remounts rather than merely unmounting. The previous implementation
- * unmounted every root and then called `start()`, which only re-renders when
+ * unmounted every root and then called `boot()`, which only re-renders when
  * the page uses implicit rendering — and even then only via the
  * `document.readyState` fallback, because the script's `load` event has long
  * since fired. On an explicitly-rendered page nothing came back at all: the
@@ -360,7 +472,7 @@ const start = () => {
  * request was ever made. Rebuilding from the stored descriptor makes reset
  * behave the same way on both paths.
  *
- * `start()` is deliberately not called here any more. It re-renders implicit
+ * `boot()` is deliberately not called here any more. It re-renders implicit
  * widgets, which would double up with the remount below, and it attaches
  * another `load` listener to the script tag on every call.
  */
@@ -374,15 +486,19 @@ export const reset = async (widgetId?: string): Promise<void> => {
 
 		current.root.unmount();
 
-		const [root] = await widgetFactory.createWidgets(
+		const [widget] = await widgetFactory.createWidgets(
 			[current.element],
 			current.renderOptions,
 			current.isWeb2,
 			current.invisible,
 		);
 
-		if (root) {
-			procaptchaWidgets.set(id, { ...current, root });
+		if (widget) {
+			procaptchaWidgets.set(id, {
+				...current,
+				root: widget.root,
+				target: widget.container,
+			});
 		} else {
 			procaptchaWidgets.delete(id);
 		}
@@ -402,6 +518,7 @@ export const remove = (widgetId?: string): void => {
 	for (const id of ids) {
 		const entry = procaptchaWidgets.get(id);
 		if (!entry) continue;
+		entry.unbindTrigger?.();
 		entry.root.unmount();
 		entry.element.innerHTML = "";
 		procaptchaWidgets.delete(id);
@@ -409,7 +526,7 @@ export const remove = (widgetId?: string): void => {
 };
 
 // set the procaptcha attribute on the window
-window.procaptcha = { ready, render, reset, remove, execute };
+window.procaptcha = { ready, render, reset, remove, execute, start };
 
 // Dispatch a custom event to notify that window.procaptcha is ready
 const procaptchaReadyEvent = new CustomEvent(PROCAPTCHA_READY_EVENT, {
@@ -421,4 +538,4 @@ const procaptchaReadyEvent = new CustomEvent(PROCAPTCHA_READY_EVENT, {
 });
 document.dispatchEvent(procaptchaReadyEvent);
 
-start();
+boot();

package/src/tests/bind.unit.test.ts

@@ -0,0 +1,227 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { Root } from "react-dom/client";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { CreatedWidget } from "../util/widgetFactory.js";
+
+const mocks = vi.hoisted(() => ({
+	prefetchDetector: vi.fn(),
+	createWidgets: vi.fn(),
+}));
+
+vi.mock("@prosopo/procaptcha-frictionless", () => ({
+	prefetchDetector: mocks.prefetchDetector,
+}));
+
+vi.mock("@prosopo/procaptcha-common", () => ({
+	getWindowCallback: vi.fn(),
+	pickIpMode: vi.fn(() => undefined),
+}));
+
+vi.mock("../util/widgetFactory.js", () => ({
+	WidgetFactory: vi.fn(function () {
+		return { createWidgets: mocks.createWidgets };
+	}),
+}));
+
+const { render, remove, execute } = await import("../index.js");
+
+const SITE_KEY = "5CcNvLUdiXFpzKDMjThGLSK9rhWHA1H4EF3zrgkpkjAdqmuP";
+const EXECUTE_EVENT = "procaptcha:execute";
+
+const makeRoot = (): Root =>
+	({ unmount: vi.fn(), render: vi.fn() }) as unknown as Root;
+
+// Like the real factory, the widget lives in a child of the host element and
+// listens there, so a targeted event must be dispatched on that child.
+const createWidgetsLikeTheFactory = async (
+	hosts: Element[],
+): Promise<CreatedWidget[]> =>
+	hosts.map((host) => {
+		const container = document.createElement("div");
+		host.appendChild(container);
+		return { root: makeRoot(), container };
+	});
+
+const listenLikeAWidget = (
+	host: Element,
+): { calls: () => number; stop: () => void } => {
+	const handler = vi.fn();
+	const target = host.firstElementChild;
+	if (!target) throw new Error("expected the factory to mount a container");
+	document.addEventListener(EXECUTE_EVENT, handler);
+	target.addEventListener(EXECUTE_EVENT, handler);
+	return {
+		calls: () => handler.mock.calls.length,
+		stop: () => {
+			document.removeEventListener(EXECUTE_EVENT, handler);
+			target.removeEventListener(EXECUTE_EVENT, handler);
+		},
+	};
+};
+
+beforeEach(async () => {
+	vi.clearAllMocks();
+	await remove();
+	document.body.innerHTML = "";
+	mocks.createWidgets.mockImplementation(createWidgetsLikeTheFactory);
+});
+
+describe("execute targeting", () => {
+	it("reaches every widget when called with no id", async () => {
+		const first = document.createElement("div");
+		first.className = "p-procaptcha";
+		const second = document.createElement("div");
+		second.className = "p-procaptcha";
+		document.body.append(first, second);
+		await render(first, { siteKey: SITE_KEY });
+		await render(second, { siteKey: SITE_KEY });
+
+		const a = listenLikeAWidget(first);
+		const b = listenLikeAWidget(second);
+		execute();
+
+		expect(a.calls()).toBe(1);
+		expect(b.calls()).toBe(1);
+		a.stop();
+		b.stop();
+	});
+
+	it("reaches only the named widget when given an id", async () => {
+		const first = document.createElement("div");
+		const second = document.createElement("div");
+		document.body.append(first, second);
+		const firstId = await render(first, { siteKey: SITE_KEY });
+		await render(second, { siteKey: SITE_KEY });
+
+		const a = listenLikeAWidget(first);
+		const b = listenLikeAWidget(second);
+		execute(firstId);
+
+		expect(a.calls()).toBe(1);
+		expect(b.calls()).toBe(0);
+		a.stop();
+		b.stop();
+	});
+
+	it("does not bubble a targeted event up to document", async () => {
+		const element = document.createElement("div");
+		document.body.appendChild(element);
+		const widgetId = await render(element, { siteKey: SITE_KEY });
+
+		const documentOnly = vi.fn();
+		document.addEventListener(EXECUTE_EVENT, documentOnly);
+		execute(widgetId);
+
+		expect(documentOnly).not.toHaveBeenCalled();
+		document.removeEventListener(EXECUTE_EVENT, documentOnly);
+	});
+
+	it("reports an unknown id rather than firing every widget", async () => {
+		const element = document.createElement("div");
+		document.body.appendChild(element);
+		await render(element, { siteKey: SITE_KEY });
+
+		const error = vi
+			.spyOn(console, "error")
+			.mockImplementation(() => undefined);
+		const listener = listenLikeAWidget(element);
+		execute("procaptcha-widget-does-not-exist");
+
+		expect(listener.calls()).toBe(0);
+		expect(error).toHaveBeenCalled();
+		listener.stop();
+		error.mockRestore();
+	});
+});
+
+describe("bind", () => {
+	it("runs only the bound widget when its button is clicked", async () => {
+		const button = document.createElement("button");
+		button.id = "pay";
+		const bound = document.createElement("div");
+		const other = document.createElement("div");
+		document.body.append(button, bound, other);
+
+		await render(bound, { siteKey: SITE_KEY, bind: "#pay" });
+		await render(other, { siteKey: SITE_KEY });
+
+		const a = listenLikeAWidget(bound);
+		const b = listenLikeAWidget(other);
+		button.click();
+
+		expect(a.calls()).toBe(1);
+		expect(b.calls()).toBe(0);
+		a.stop();
+		b.stop();
+	});
+
+	it("stops the button's default action", async () => {
+		const form = document.createElement("form");
+		const button = document.createElement("button");
+		button.id = "submit-it";
+		button.type = "submit";
+		form.appendChild(button);
+		const element = document.createElement("div");
+		document.body.append(form, element);
+
+		await render(element, { siteKey: SITE_KEY, bind: "#submit-it" });
+
+		const event = new MouseEvent("click", {
+			bubbles: true,
+			cancelable: true,
+		});
+		button.dispatchEvent(event);
+
+		expect(event.defaultPrevented).toBe(true);
+	});
+
+	it("detaches the listener when the widget is removed", async () => {
+		const button = document.createElement("button");
+		button.id = "gone";
+		const element = document.createElement("div");
+		document.body.append(button, element);
+
+		await render(element, { siteKey: SITE_KEY, bind: "#gone" });
+		await remove();
+
+		const error = vi
+			.spyOn(console, "error")
+			.mockImplementation(() => undefined);
+		button.click();
+
+		expect(error).not.toHaveBeenCalled();
+		error.mockRestore();
+	});
+
+	it("reports a selector that matches nothing and still renders", async () => {
+		const error = vi
+			.spyOn(console, "error")
+			.mockImplementation(() => undefined);
+		const element = document.createElement("div");
+		document.body.appendChild(element);
+
+		const widgetId = await render(element, {
+			siteKey: SITE_KEY,
+			bind: "#nothing-here",
+		});
+
+		expect(widgetId).toBeTruthy();
+		expect(error).toHaveBeenCalledWith(
+			expect.stringContaining("#nothing-here"),
+		);
+		error.mockRestore();
+	});
+});

package/src/tests/detectorPrefetch.unit.test.ts

@@ -19,8 +19,8 @@
  * to assigning a detector inline on the widget's critical path.
  */
 
-import type { Root } from "react-dom/client";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { CreatedWidget } from "../util/widgetFactory.js";
 
 const mocks = vi.hoisted(() => ({
 	prefetchDetector: vi.fn(),
@@ -59,7 +59,7 @@ const renderAndFlush = async (
 
 beforeEach(() => {
 	vi.clearAllMocks();
-	mocks.createWidgets.mockResolvedValue([] as Root[]);
+	mocks.createWidgets.mockResolvedValue([] as CreatedWidget[]);
 });
 
 describe("render", () => {

package/src/tests/procaptchaReady.unit.test.ts

@@ -50,6 +50,7 @@ describe("procaptcha:ready event", () => {
 			expect(window.procaptcha?.ready).toBeDefined();
 			expect(window.procaptcha?.reset).toBeDefined();
 			expect(window.procaptcha?.execute).toBeDefined();
+			expect(window.procaptcha?.start).toBeDefined();
 		});
 
 		// Import the module which should set window.procaptcha and dispatch the event

package/src/tests/reset.unit.test.ts

@@ -22,6 +22,7 @@
 
 import type { Root } from "react-dom/client";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { CreatedWidget } from "../util/widgetFactory.js";
 
 const mocks = vi.hoisted(() => ({
 	prefetchDetector: vi.fn(),
@@ -50,10 +51,15 @@ const SITE_KEY = "5CcNvLUdiXFpzKDMjThGLSK9rhWHA1H4EF3zrgkpkjAdqmuP";
 const makeRoot = (): Root =>
 	({ unmount: vi.fn(), render: vi.fn() }) as unknown as Root;
 
+const makeWidget = (root: Root = makeRoot()): CreatedWidget => ({
+	root,
+	container: document.createElement("div"),
+});
+
 /** Each createWidgets call yields a distinct root, as the real factory does. */
 const queueRoots = (...roots: Root[]): void => {
 	for (const root of roots) {
-		mocks.createWidgets.mockResolvedValueOnce([root]);
+		mocks.createWidgets.mockResolvedValueOnce([makeWidget(root)]);
 	}
 };
 
@@ -62,7 +68,7 @@ beforeEach(async () => {
 	// Drop any widgets registered by a previous test — module state persists
 	// across tests in the same file.
 	await remove();
-	mocks.createWidgets.mockResolvedValue([makeRoot()]);
+	mocks.createWidgets.mockResolvedValue([makeWidget()]);
 });
 
 describe("render", () => {
@@ -78,7 +84,7 @@ describe("render", () => {
 	});
 
 	it("returns undefined when the factory creates no widget", async () => {
-		mocks.createWidgets.mockResolvedValueOnce([] as Root[]);
+		mocks.createWidgets.mockResolvedValueOnce([] as CreatedWidget[]);
 
 		const widgetId = await render(document.createElement("div"), {
 			siteKey: SITE_KEY,