@prosopo/procaptcha-frictionless 2.13.23 → 2.15.0

package/dist/tests/manualStart.test.js

@@ -0,0 +1,254 @@
+import { CaptchaType, ModeEnum, PROCAPTCHA_START_EVENT, StartModeEnum, } from "@prosopo/types";
+import { act, createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const mocks = vi.hoisted(() => ({
+    mounts: [],
+}));
+const stub = (widget) => (props) => {
+    mocks.mounts.push({ widget, props });
+    return createElement("div", { "data-widget": widget });
+};
+vi.mock("@prosopo/procaptcha-pow", () => ({ ProcaptchaPow: stub("pow") }));
+vi.mock("@prosopo/procaptcha-react", () => ({ Procaptcha: stub("image") }));
+vi.mock("@prosopo/procaptcha-puzzle", () => ({
+    ProcaptchaPuzzle: stub("puzzle"),
+}));
+vi.mock("@prosopo/procaptcha-common", async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, isSecureBrowserContext: () => true };
+});
+const { ProcaptchaFrictionless } = await import("../ProcaptchaFrictionless.js");
+const SITE_KEY = "5siteKey";
+const SESSION_ID = "provider-session";
+const config = (overrides = {}) => ({
+    account: { address: SITE_KEY },
+    userAccountAddress: "",
+    web2: true,
+    mode: ModeEnum.visible,
+    startMode: StartModeEnum.manual,
+    ...overrides,
+});
+const i18nStub = {
+    isInitialized: true,
+    language: "en",
+    t: (key) => key,
+    changeLanguage: vi.fn(),
+};
+const detectionResult = () => ({
+    status: "ok",
+    captchaType: CaptchaType.image,
+    sessionId: SESSION_ID,
+    provider: { provider: { url: "https://provider.test" } },
+    userAccount: { account: { address: "5FakeUserAccountAddress" } },
+});
+const detectBotResolving = () => vi.fn().mockResolvedValue(detectionResult());
+let host;
+let root;
+const mountWrapper = async (options = {}) => {
+    const detectBot = options.detectBot ?? detectBotResolving();
+    await act(async () => {
+        root.render(createElement(ProcaptchaFrictionless, {
+            config: options.config ?? config(),
+            callbacks: {},
+            restart: vi.fn(),
+            i18n: i18nStub,
+            detectBot,
+            container: options.container,
+        }));
+    });
+    return detectBot;
+};
+const checkbox = () => {
+    const element = host.querySelector('[data-cy="captcha-checkbox"]');
+    if (!element)
+        throw new Error("expected the checkbox to be on the page");
+    return element;
+};
+const spinner = () => host.querySelector('[aria-label="Loading spinner"]');
+const lastMountOf = (widget) => {
+    const mount = mocks.mounts.filter((m) => m.widget === widget).at(-1);
+    if (!mount)
+        throw new Error(`expected the ${widget} widget to have mounted`);
+    return mount;
+};
+const setTrusted = (event, trusted) => {
+    for (const symbol of Object.getOwnPropertySymbols(event)) {
+        const impl = Reflect.get(event, symbol);
+        if (impl && typeof impl === "object" && "isTrusted" in impl) {
+            Object.defineProperty(impl, "isTrusted", {
+                configurable: true,
+                get: () => trusted,
+                set: () => undefined,
+            });
+            return;
+        }
+    }
+    throw new Error("could not reach the jsdom event implementation");
+};
+const click = async (element, options = {}) => {
+    const event = new MouseEvent("click", {
+        bubbles: true,
+        cancelable: true,
+        clientX: options.clientX ?? 0,
+        clientY: options.clientY ?? 0,
+    });
+    setTrusted(event, options.trusted ?? true);
+    await act(async () => {
+        element.dispatchEvent(event);
+    });
+};
+const dispatchStart = async (detail) => {
+    await act(async () => {
+        document.dispatchEvent(new CustomEvent(PROCAPTCHA_START_EVENT, {
+            detail,
+            bubbles: true,
+        }));
+    });
+};
+const dispatchExecute = async () => {
+    await act(async () => {
+        document.dispatchEvent(new CustomEvent("procaptcha:execute"));
+    });
+};
+beforeEach(() => {
+    mocks.mounts.length = 0;
+    host = document.createElement("div");
+    document.body.appendChild(host);
+    act(() => {
+        root = createRoot(host);
+    });
+});
+afterEach(() => {
+    act(() => {
+        root.unmount();
+    });
+    host.remove();
+    vi.clearAllMocks();
+});
+describe("manual start mode", () => {
+    it("mounts a live checkbox without running detection", async () => {
+        const detectBot = await mountWrapper();
+        expect(detectBot).not.toHaveBeenCalled();
+        expect(mocks.mounts).toHaveLength(0);
+        expect(checkbox().disabled).toBe(false);
+        expect(spinner()).toBeNull();
+    });
+    it("still runs detection on mount in auto mode", async () => {
+        const detectBot = await mountWrapper({
+            config: config({ startMode: StartModeEnum.auto }),
+        });
+        expect(detectBot).toHaveBeenCalledTimes(1);
+        expect(lastMountOf("image").props.autoStart).toBe(false);
+    });
+    it("defaults to auto when no start mode is given", async () => {
+        const detectBot = await mountWrapper({
+            config: config({ startMode: undefined }),
+        });
+        expect(detectBot).toHaveBeenCalledTimes(1);
+    });
+    describe("started by the site", () => {
+        it("runs detection on procaptcha:start and leaves the widget waiting for a click", async () => {
+            const detectBot = await mountWrapper();
+            await dispatchStart();
+            expect(detectBot).toHaveBeenCalledTimes(1);
+            const mount = lastMountOf("image").props;
+            expect(mount.autoStart).toBe(false);
+            expect(mount.startCoords).toBeUndefined();
+            expect(mount.frictionlessState?.sessionId).toBe(SESSION_ID);
+        });
+        it("honours an event addressed to its own element", async () => {
+            const widgetElement = document.createElement("div");
+            const container = document.createElement("div");
+            widgetElement.appendChild(container);
+            const detectBot = await mountWrapper({ container });
+            await dispatchStart({ element: widgetElement });
+            expect(detectBot).toHaveBeenCalledTimes(1);
+        });
+        it("ignores an event addressed to another widget's element", async () => {
+            const container = document.createElement("div");
+            document.createElement("div").appendChild(container);
+            const detectBot = await mountWrapper({ container });
+            await dispatchStart({ element: document.createElement("div") });
+            expect(detectBot).not.toHaveBeenCalled();
+            expect(checkbox().disabled).toBe(false);
+        });
+        it("receives every event when mounted without a container", async () => {
+            const detectBot = await mountWrapper();
+            await dispatchStart({ element: document.createElement("div") });
+            expect(detectBot).toHaveBeenCalledTimes(1);
+        });
+        it("opens the challenge straight away on procaptcha:execute", async () => {
+            const detectBot = await mountWrapper({
+                config: config({ mode: ModeEnum.invisible }),
+            });
+            await dispatchExecute();
+            expect(detectBot).toHaveBeenCalledTimes(1);
+            expect(lastMountOf("image").props.autoStart).toBe(true);
+        });
+        it("ignores the events once started", async () => {
+            const detectBot = await mountWrapper();
+            await dispatchStart();
+            await dispatchStart();
+            await dispatchExecute();
+            expect(detectBot).toHaveBeenCalledTimes(1);
+            expect(mocks.mounts).toHaveLength(1);
+        });
+        it("does not react to the events in auto mode", async () => {
+            const detectBot = await mountWrapper({
+                config: config({ startMode: StartModeEnum.auto }),
+            });
+            expect(detectBot).toHaveBeenCalledTimes(1);
+            await dispatchStart();
+            expect(detectBot).toHaveBeenCalledTimes(1);
+        });
+    });
+    describe("started by the user", () => {
+        it("runs detection on a checkbox click and opens the challenge where the user clicked", async () => {
+            const detectBot = await mountWrapper();
+            await click(checkbox(), { clientX: 11, clientY: 22 });
+            expect(detectBot).toHaveBeenCalledTimes(1);
+            const mount = lastMountOf("image").props;
+            expect(mount.autoStart).toBe(true);
+            expect(mount.startCoords).toEqual({ x: 11, y: 22 });
+        });
+        it("opens the challenge after a keyboard activation with no position", async () => {
+            const detectBot = await mountWrapper();
+            await click(checkbox());
+            expect(detectBot).toHaveBeenCalledTimes(1);
+            const mount = lastMountOf("image").props;
+            expect(mount.autoStart).toBe(true);
+            expect(mount.startCoords).toBeUndefined();
+        });
+        it("shows the spinner while the deferred flow runs", async () => {
+            let finish;
+            const detectBot = vi.fn().mockImplementation(() => new Promise((resolve) => {
+                finish = resolve;
+            }));
+            await mountWrapper({ detectBot });
+            await click(checkbox(), { clientX: 1, clientY: 1 });
+            expect(spinner()).not.toBeNull();
+            expect(mocks.mounts).toHaveLength(0);
+            await act(async () => {
+                finish?.(detectionResult());
+            });
+            expect(spinner()).toBeNull();
+            expect(lastMountOf("image").props.autoStart).toBe(true);
+        });
+        it("ignores a synthetic click", async () => {
+            const detectBot = await mountWrapper();
+            await click(checkbox(), { trusted: false, clientX: 1, clientY: 1 });
+            expect(detectBot).not.toHaveBeenCalled();
+        });
+        it("starts once even if the site also asks", async () => {
+            const detectBot = await mountWrapper();
+            await click(checkbox(), { clientX: 3, clientY: 4 });
+            await dispatchStart();
+            expect(detectBot).toHaveBeenCalledTimes(1);
+            expect(mocks.mounts).toHaveLength(1);
+            expect(lastMountOf("image").props.startCoords).toEqual({ x: 3, y: 4 });
+        });
+    });
+});
+//# sourceMappingURL=manualStart.test.js.map

package/dist/tests/manualStart.test.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@prosopo/procaptcha-frictionless",
-	"version": "2.13.23",
+	"version": "2.15.0",
 	"author": "PROSOPO LIMITED <info@prosopo.io>",
 	"license": "Apache-2.0",
 	"main": "dist/index.js",
@@ -30,22 +30,22 @@
 	},
 	"browserslist": ["> 0.5%, last 2 versions, not dead"],
 	"dependencies": {
-		"@prosopo/api": "4.1.4",
-		"@prosopo/common": "3.1.52",
-		"@prosopo/locale": "3.4.0",
-		"@prosopo/procaptcha-common": "2.12.5",
-		"@prosopo/procaptcha-pow": "2.11.5",
-		"@prosopo/procaptcha-puzzle": "2.11.5",
-		"@prosopo/procaptcha-react": "2.9.121",
-		"@prosopo/types": "5.5.3",
-		"@prosopo/widget-skeleton": "2.8.6",
+		"@prosopo/api": "4.1.6",
+		"@prosopo/common": "3.1.54",
+		"@prosopo/locale": "3.4.1",
+		"@prosopo/procaptcha-common": "2.13.0",
+		"@prosopo/procaptcha-pow": "2.12.0",
+		"@prosopo/procaptcha-puzzle": "2.12.0",
+		"@prosopo/procaptcha-react": "2.10.0",
+		"@prosopo/types": "5.7.0",
+		"@prosopo/widget-skeleton": "2.8.7",
 		"dotenv": "16.4.5",
 		"react": "19.2.8"
 	},
 	"devDependencies": {
-		"@prosopo/config": "3.3.12",
+		"@prosopo/config": "3.3.14",
 		"@types/node": "22.10.2",
-		"@vitest/coverage-v8": "4.1.10",
+		"@vitest/coverage-v8": "4.1.11",
 		"concurrently": "9.0.1",
 		"del-cli": "6.0.0",
 		"npm-run-all": "4.1.5",
@@ -54,7 +54,7 @@
 		"tsx": "4.20.3",
 		"typescript": "5.6.2",
 		"vite": "8.1.5",
-		"vitest": "4.1.10"
+		"vitest": "4.1.11"
 	},
 	"repository": {
 		"type": "git",

package/src/ProcaptchaFrictionless.tsx

@@ -24,10 +24,14 @@ import {
 	CaptchaType,
 	type FrictionlessState,
 	type ModeType,
+	PROCAPTCHA_START_EVENT,
 	ProcaptchaConfigSchema,
 	type ProcaptchaFrictionlessProps,
+	type ProcaptchaStartEventDetail,
+	StartModeEnum,
 } from "@prosopo/types";
 import { darkTheme, lightTheme } from "@prosopo/widget-skeleton";
+import type { KeyboardEvent, MouseEvent, TouchEvent } from "react";
 import { useEffect, useRef, useState } from "react";
 import customDetectBot from "./customDetectBot.js";
 import { evaluateFrictionlessResult } from "./frictionlessResultGuard.js";
@@ -46,6 +50,12 @@ const ProcaptchaPuzzleLoader = async () =>
 const ProcaptchaPowLoader = async () =>
 	(await import("@prosopo/procaptcha-pow")).ProcaptchaPow;
 
+const PROCAPTCHA_EXECUTE_EVENT = "procaptcha:execute";
+
+type CheckboxEvent = MouseEvent | TouchEvent | KeyboardEvent;
+
+const noopCheckboxHandler = async (_event: CheckboxEvent): Promise<void> => {};
+
 const renderPlaceholder = (
 	theme: string | undefined,
 	mode: ModeType,
@@ -53,6 +63,7 @@ const renderPlaceholder = (
 	isTranslationLoaded: boolean,
 	translationFn: (key: string) => string,
 	loading: boolean,
+	onChange: (event: CheckboxEvent) => Promise<void> = noopCheckboxHandler,
 ) => {
 	const checkboxTheme = "light" === theme ? lightTheme : darkTheme;
 
@@ -63,7 +74,7 @@ const renderPlaceholder = (
 	return (
 		<Checkbox
 			theme={checkboxTheme}
-			onChange={async () => {}}
+			onChange={onChange}
 			checked={false}
 			labelText={isTranslationLoaded ? translationFn("WIDGET.I_AM_HUMAN") : ""}
 			error={errorMessage}
@@ -116,6 +127,10 @@ export const ProcaptchaFrictionless = ({
 	// because `providerRetry` re-invokes `start` with no arguments, which would
 	// otherwise drop the flag on the first provider retry.
 	const nextMountAutoStartRef = useRef(false);
+	const manualStart = config.startMode === StartModeEnum.manual;
+	const manualStartedRef = useRef(false);
+	// The placeholder is built before `start()` exists in this scope.
+	const manualCheckboxHandlerRef = useRef(noopCheckboxHandler);
 
 	useEffect(() => {
 		if (!config.language) return;
@@ -139,7 +154,10 @@ export const ProcaptchaFrictionless = ({
 			stateRef.current.errorMessage,
 			i18n.isInitialized,
 			i18n.t,
-			true,
+			!manualStart,
+			manualStart
+				? (event: CheckboxEvent) => manualCheckboxHandlerRef.current(event)
+				: undefined,
 		),
 	);
 
@@ -269,6 +287,7 @@ export const ProcaptchaFrictionless = ({
 					autoStart={resumedAutoStart}
 					startCoords={startCoords}
 					onSessionInvalidated={onSessionInvalidated}
+					container={container}
 					onReload={onReload}
 				/>,
 			);
@@ -284,6 +303,7 @@ export const ProcaptchaFrictionless = ({
 					autoStart={resumedAutoStart}
 					startCoords={startCoords}
 					onSessionInvalidated={onSessionInvalidated}
+					container={container}
 				/>,
 			);
 		} else {
@@ -299,6 +319,7 @@ export const ProcaptchaFrictionless = ({
 					autoStart={resumedAutoStart}
 					startCoords={startCoords}
 					onSessionInvalidated={onSessionInvalidated}
+					container={container}
 				/>,
 			);
 		}
@@ -374,6 +395,59 @@ export const ProcaptchaFrictionless = ({
 		});
 	};
 
+	const startManually = async (
+		autoStart: boolean,
+		coords?: RetryCoords,
+	): Promise<void> => {
+		if (manualStartedRef.current) return;
+		manualStartedRef.current = true;
+		pendingRetryCoordsRef.current = coords ?? null;
+		nextMountAutoStartRef.current = autoStart;
+		setComponentToRender(
+			renderPlaceholder(
+				config.theme,
+				config.mode,
+				stateRef.current.errorMessage,
+				i18n.isInitialized,
+				i18n.t,
+				true,
+			),
+		);
+		await start();
+	};
+
+	manualCheckboxHandlerRef.current = async (event: CheckboxEvent) => {
+		let x = 0;
+		let y = 0;
+		const nativeEvent = event.nativeEvent;
+		if ("clientX" in nativeEvent && "clientY" in nativeEvent) {
+			x = nativeEvent.clientX;
+			y = nativeEvent.clientY;
+		}
+		await startManually(true, normaliseRetryCoords(x, y) ?? undefined);
+	};
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: intentional — `startManually` captures the mount-time `start()`, as the auto-mode effect below does.
+	useEffect(() => {
+		if (!manualStart) return;
+		const onStartEvent = (event: Event) => {
+			const detail = (event as CustomEvent<ProcaptchaStartEventDetail>).detail;
+			if (detail?.element && container && !detail.element.contains(container)) {
+				return;
+			}
+			void startManually(false);
+		};
+		const onExecuteEvent = () => {
+			void startManually(true);
+		};
+		document.addEventListener(PROCAPTCHA_START_EVENT, onStartEvent);
+		document.addEventListener(PROCAPTCHA_EXECUTE_EVENT, onExecuteEvent);
+		return () => {
+			document.removeEventListener(PROCAPTCHA_START_EVENT, onStartEvent);
+			document.removeEventListener(PROCAPTCHA_EXECUTE_EVENT, onExecuteEvent);
+		};
+	}, [manualStart, container]);
+
 	// Track which config identity has already been started for. Host
 	// pages often recreate the `callbacks` object (and sometimes the whole
 	// `config`) on every render, which — before this guard — re-fired
@@ -399,6 +473,7 @@ export const ProcaptchaFrictionless = ({
 		}`;
 		if (startedForKeyRef.current === key) return;
 		startedForKeyRef.current = key;
+		if (manualStart) return;
 		void start();
 	}, [config.account?.address, config.language, config.mode]);