@prosopo/procaptcha-common 2.9.19 → 2.10.17

package/src/state/builder.ts

@@ -0,0 +1,137 @@
+// 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 {
+	Account,
+	CaptchaResponseBody,
+	ProcaptchaApiInterface,
+	ProcaptchaState,
+	ProcaptchaStateUpdateFn,
+	TCaptchaSubmitResult,
+} from "@prosopo/types";
+
+type useRefType = <T>(defaultValue: T) => { current: T };
+type useStateType = <T>(defaultValue: T) => [T, (value: T) => void];
+
+export const buildUpdateState =
+	(state: ProcaptchaState, onStateUpdate: ProcaptchaStateUpdateFn) =>
+	(nextState: Partial<ProcaptchaState>) => {
+		// mutate the current state. Note that this is in order of properties in the nextState object.
+		// e.g. given {b: 2, c: 3, a: 1}, b will be set, then c, then a. This is because JS stores fields in insertion order by default, unless you override it with a class or such by changing the key enumeration order.
+		Object.assign(state, nextState);
+		// then call the update function for the frontend to do the same
+		onStateUpdate(nextState);
+	};
+
+/**
+ * Wrap a ref to be the same format as useState.
+ * @param useRef the useRef function from react
+ * @param defaultValue the default value if the state is not already initialised
+ * @returns a ref in the same format as a state, e.g. [value, setValue]
+ */
+const useRefAsState = <T>(
+	useRef: useRefType,
+	defaultValue: T,
+): [T, (value: T) => void] => {
+	const ref = useRef<T>(defaultValue);
+	const setter = (value: T) => {
+		ref.current = value;
+	};
+	const value: T = ref.current;
+	return [value, setter];
+};
+
+export const useProcaptcha = (
+	useState: useStateType,
+	useRef: useRefType,
+): [ProcaptchaState, ProcaptchaStateUpdateFn] => {
+	const [isHuman, setIsHuman] = useState(false);
+	const [index, setIndex] = useState(0);
+	const [solutions, setSolutions] = useState(
+		[] as [string, number, number][][],
+	);
+	const [captchaApi, setCaptchaApi] = useRefAsState<
+		ProcaptchaApiInterface | undefined
+	>(useRef, undefined);
+	const [showModal, setShowModal] = useState(false);
+	const [challenge, setChallenge] = useState<CaptchaResponseBody | undefined>(
+		undefined,
+	);
+	const [loading, setLoading] = useState(false);
+	const [account, setAccount] = useState<Account | undefined>(undefined);
+	const [dappAccount, setDappAccount] = useState<string | undefined>(undefined);
+	const [submission, setSubmission] = useRefAsState<
+		TCaptchaSubmitResult | undefined
+	>(useRef, undefined);
+	const [timeout, setTimeout] = useRefAsState<NodeJS.Timeout | undefined>(
+		useRef,
+		undefined,
+	);
+	const [successfullChallengeTimeout, setSuccessfullChallengeTimeout] =
+		useRefAsState<NodeJS.Timeout | undefined>(useRef, undefined);
+	const [sendData, setSendData] = useState(false);
+	const [attemptCount, setAttemptCount] = useState(0);
+	const [error, setError] = useState<
+		{ message: string; key: string } | undefined
+	>(undefined);
+	const [sessionId, setSessionId] = useState<string | undefined>(undefined);
+	return [
+		// the state
+		{
+			isHuman,
+			index,
+			solutions,
+			captchaApi,
+			showModal,
+			challenge,
+			loading,
+			account,
+			dappAccount,
+			submission,
+			timeout,
+			successfullChallengeTimeout,
+			sendData,
+			attemptCount,
+			error,
+			sessionId,
+		},
+		// and method to update the state
+		(nextState: Partial<ProcaptchaState>) => {
+			if (nextState.account !== undefined) setAccount(nextState.account);
+			if (nextState.isHuman !== undefined) setIsHuman(nextState.isHuman);
+			if (nextState.index !== undefined) setIndex(nextState.index);
+			// force a copy of the array to ensure a re-render
+			// nutshell: react doesn't look inside an array for changes, hence changes to the array need to result in a fresh array
+			if (nextState.solutions !== undefined)
+				setSolutions(nextState.solutions.slice());
+			if (nextState.captchaApi !== undefined)
+				setCaptchaApi(nextState.captchaApi);
+			if (nextState.showModal !== undefined) setShowModal(nextState.showModal);
+			if (nextState.challenge !== undefined) setChallenge(nextState.challenge);
+			if (nextState.loading !== undefined) setLoading(nextState.loading);
+			if (nextState.showModal !== undefined) setShowModal(nextState.showModal);
+			if (nextState.dappAccount !== undefined)
+				setDappAccount(nextState.dappAccount);
+			if (nextState.submission !== undefined)
+				setSubmission(nextState.submission);
+			if (nextState.timeout !== undefined) setTimeout(nextState.timeout);
+			if (nextState.successfullChallengeTimeout !== undefined)
+				setSuccessfullChallengeTimeout(nextState.timeout);
+			if (nextState.sendData !== undefined) setSendData(nextState.sendData);
+			if (nextState.attemptCount !== undefined)
+				setAttemptCount(nextState.attemptCount);
+			if (nextState.error !== undefined) setError(nextState.error);
+			if (nextState.sessionId !== undefined) setSessionId(nextState.sessionId);
+		},
+	];
+};

package/src/tests/defaultCallbacks.test.ts

@@ -0,0 +1,372 @@
+// 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 { ApiParams } from "@prosopo/types";
+import type { ProcaptchaRenderOptions, ProcaptchaToken } from "@prosopo/types";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+	getDefaultCallbacks,
+	setUserCallbacks,
+} from "../callbacks/defaultCallbacks.js";
+
+describe("callbacks/defaultCallbacks", () => {
+	beforeEach(() => {
+		document.body.innerHTML = "";
+		vi.clearAllMocks();
+	});
+
+	describe("getDefaultCallbacks", () => {
+		it("should return default callbacks object", () => {
+			const callbacks = getDefaultCallbacks();
+
+			expect(callbacks).toHaveProperty("onHuman");
+			expect(callbacks).toHaveProperty("onChallengeExpired");
+			expect(callbacks).toHaveProperty("onExtensionNotFound");
+			expect(callbacks).toHaveProperty("onExpired");
+			expect(callbacks).toHaveProperty("onError");
+			expect(callbacks).toHaveProperty("onClose");
+			expect(callbacks).toHaveProperty("onOpen");
+			expect(callbacks).toHaveProperty("onFailed");
+			expect(callbacks).toHaveProperty("onReset");
+			expect(callbacks).toHaveProperty("onReload");
+
+			expect(typeof callbacks.onHuman).toBe("function");
+			expect(typeof callbacks.onChallengeExpired).toBe("function");
+			expect(typeof callbacks.onError).toBe("function");
+		});
+
+		it("onHuman should add hidden input to form with token", () => {
+			const form = document.createElement("form");
+			const widget = document.createElement("div");
+			form.appendChild(widget);
+			document.body.appendChild(form);
+
+			const callbacks = getDefaultCallbacks(widget);
+			const token = "test-token-123" as ProcaptchaToken;
+
+			callbacks.onHuman(token);
+
+			const inputs = form.querySelectorAll(
+				`input[name="${ApiParams.procaptchaResponse}"]`,
+			);
+			expect(inputs.length).toBe(1);
+			expect((inputs[0] as HTMLInputElement).value).toBe(token);
+			expect((inputs[0] as HTMLInputElement).type).toBe("hidden");
+		});
+
+		it("onHuman should handle missing parent form gracefully", () => {
+			const widget = document.createElement("div");
+			document.body.appendChild(widget);
+
+			const consoleErrorSpy = vi
+				.spyOn(console, "error")
+				.mockImplementation(() => {});
+
+			const callbacks = getDefaultCallbacks(widget);
+			const token = "test-token-123" as ProcaptchaToken;
+
+			callbacks.onHuman(token);
+
+			expect(consoleErrorSpy).toHaveBeenCalledWith(
+				"Parent form not found for the element:",
+				widget,
+			);
+
+			consoleErrorSpy.mockRestore();
+		});
+
+		it("onChallengeExpired should remove procaptcha response", () => {
+			const input = document.createElement("input");
+			input.name = ApiParams.procaptchaResponse;
+			document.body.appendChild(input);
+
+			const callbacks = getDefaultCallbacks();
+			callbacks.onChallengeExpired();
+
+			expect(
+				document.getElementsByName(ApiParams.procaptchaResponse).length,
+			).toBe(0);
+		});
+
+		it("onExpired should remove procaptcha response", () => {
+			const input = document.createElement("input");
+			input.name = ApiParams.procaptchaResponse;
+			document.body.appendChild(input);
+
+			const callbacks = getDefaultCallbacks();
+			callbacks.onExpired();
+
+			expect(
+				document.getElementsByName(ApiParams.procaptchaResponse).length,
+			).toBe(0);
+		});
+
+		it("onError should remove procaptcha response and log error", () => {
+			const input = document.createElement("input");
+			input.name = ApiParams.procaptchaResponse;
+			document.body.appendChild(input);
+
+			const consoleErrorSpy = vi
+				.spyOn(console, "error")
+				.mockImplementation(() => {});
+			const callbacks = getDefaultCallbacks();
+			const error = new Error("Test error");
+
+			callbacks.onError(error);
+
+			expect(
+				document.getElementsByName(ApiParams.procaptchaResponse).length,
+			).toBe(0);
+			expect(consoleErrorSpy).toHaveBeenCalledWith(error);
+
+			consoleErrorSpy.mockRestore();
+		});
+
+		it("onFailed should show alert", () => {
+			const alertSpy = vi.spyOn(window, "alert").mockImplementation(() => {});
+			const callbacks = getDefaultCallbacks();
+
+			callbacks.onFailed();
+
+			expect(alertSpy).toHaveBeenCalledWith(
+				"Captcha challenge failed. Please try again",
+			);
+
+			alertSpy.mockRestore();
+		});
+
+		it("onReset should remove procaptcha response", () => {
+			const input = document.createElement("input");
+			input.name = ApiParams.procaptchaResponse;
+			document.body.appendChild(input);
+
+			const callbacks = getDefaultCallbacks();
+			callbacks.onReset();
+
+			expect(
+				document.getElementsByName(ApiParams.procaptchaResponse).length,
+			).toBe(0);
+		});
+	});
+
+	describe("setUserCallbacks", () => {
+		it("should wrap user callback for onHuman", () => {
+			const form = document.createElement("form");
+			const widget = document.createElement("div");
+			form.appendChild(widget);
+			document.body.appendChild(form);
+
+			const userCallback = vi.fn();
+			const renderOptions: Partial<ProcaptchaRenderOptions> = {
+				callback: userCallback,
+			};
+
+			const callbacks = getDefaultCallbacks(widget);
+			setUserCallbacks(
+				renderOptions as ProcaptchaRenderOptions,
+				callbacks,
+				widget,
+			);
+
+			const token = "test-token" as ProcaptchaToken;
+			callbacks.onHuman(token);
+
+			expect(userCallback).toHaveBeenCalledWith(token);
+			// Also verify that default behavior (adding to form) still happens
+			const inputs = form.querySelectorAll(
+				`input[name="${ApiParams.procaptchaResponse}"]`,
+			);
+			expect(inputs.length).toBeGreaterThan(0);
+		});
+
+		it("should use data attribute callback over renderOptions", () => {
+			const form = document.createElement("form");
+			const widget = document.createElement("div");
+			form.appendChild(widget);
+			document.body.appendChild(form);
+
+			const dataCallback = vi.fn();
+			const renderCallback = vi.fn();
+
+			// biome-ignore lint/suspicious/noExplicitAny: Test setup
+			(window as any).dataCallbackFn = dataCallback;
+			widget.setAttribute("data-callback", "dataCallbackFn");
+
+			const renderOptions: Partial<ProcaptchaRenderOptions> = {
+				callback: renderCallback,
+			};
+
+			const callbacks = getDefaultCallbacks(widget);
+			setUserCallbacks(
+				renderOptions as ProcaptchaRenderOptions,
+				callbacks,
+				widget,
+			);
+
+			const token = "test-token" as ProcaptchaToken;
+			callbacks.onHuman(token);
+
+			expect(dataCallback).toHaveBeenCalledWith(token);
+			expect(renderCallback).not.toHaveBeenCalled();
+
+			// biome-ignore lint/suspicious/noExplicitAny: Test cleanup
+			(window as any).dataCallbackFn = undefined;
+		});
+
+		it("should handle string callback name in renderOptions", () => {
+			const form = document.createElement("form");
+			const widget = document.createElement("div");
+			form.appendChild(widget);
+			document.body.appendChild(form);
+
+			const namedCallback = vi.fn();
+			// biome-ignore lint/suspicious/noExplicitAny: Test setup
+			(window as any).myCallback = namedCallback;
+
+			const renderOptions: Partial<ProcaptchaRenderOptions> = {
+				// biome-ignore lint/suspicious/noExplicitAny: Test string callback
+				callback: "myCallback" as any,
+			};
+
+			const callbacks = getDefaultCallbacks(widget);
+			setUserCallbacks(
+				renderOptions as ProcaptchaRenderOptions,
+				callbacks,
+				widget,
+			);
+
+			const token = "test-token" as ProcaptchaToken;
+			callbacks.onHuman(token);
+
+			expect(namedCallback).toHaveBeenCalledWith(token);
+
+			// biome-ignore lint/suspicious/noExplicitAny: Test cleanup
+			(window as any).myCallback = undefined;
+		});
+
+		it("should set expired callback from renderOptions", () => {
+			const widget = document.createElement("div");
+			const expiredCallback = vi.fn();
+
+			const renderOptions: Partial<ProcaptchaRenderOptions> = {
+				"expired-callback": expiredCallback,
+			};
+
+			const callbacks = getDefaultCallbacks(widget);
+			setUserCallbacks(
+				renderOptions as ProcaptchaRenderOptions,
+				callbacks,
+				widget,
+			);
+
+			callbacks.onExpired();
+
+			expect(expiredCallback).toHaveBeenCalled();
+		});
+
+		it("should set error callback from renderOptions", () => {
+			const widget = document.createElement("div");
+			const errorCallback = vi.fn();
+
+			const renderOptions: Partial<ProcaptchaRenderOptions> = {
+				"error-callback": errorCallback,
+			};
+
+			const callbacks = getDefaultCallbacks(widget);
+			setUserCallbacks(
+				renderOptions as ProcaptchaRenderOptions,
+				callbacks,
+				widget,
+			);
+
+			const error = new Error("Test error");
+			callbacks.onError(error);
+
+			expect(errorCallback).toHaveBeenCalledWith(error);
+		});
+
+		it("should set failed callback from renderOptions", () => {
+			const widget = document.createElement("div");
+			const failedCallback = vi.fn();
+
+			const renderOptions: Partial<ProcaptchaRenderOptions> = {
+				"failed-callback": failedCallback,
+			};
+
+			const callbacks = getDefaultCallbacks(widget);
+			setUserCallbacks(
+				renderOptions as ProcaptchaRenderOptions,
+				callbacks,
+				widget,
+			);
+
+			callbacks.onFailed();
+
+			expect(failedCallback).toHaveBeenCalled();
+		});
+
+		it("should set reset callback from renderOptions", () => {
+			const widget = document.createElement("div");
+			const resetCallback = vi.fn();
+
+			const renderOptions: Partial<ProcaptchaRenderOptions> = {
+				"reset-callback": resetCallback,
+			};
+
+			const callbacks = getDefaultCallbacks(widget);
+			setUserCallbacks(
+				renderOptions as ProcaptchaRenderOptions,
+				callbacks,
+				widget,
+			);
+
+			callbacks.onReset();
+
+			expect(resetCallback).toHaveBeenCalled();
+		});
+
+		it("should handle undefined renderOptions gracefully", () => {
+			const widget = document.createElement("div");
+			const callbacks = getDefaultCallbacks(widget);
+
+			expect(() =>
+				setUserCallbacks(undefined, callbacks, widget),
+			).not.toThrow();
+		});
+
+		it("should set open and close callbacks", () => {
+			const widget = document.createElement("div");
+			const openCallback = vi.fn();
+			const closeCallback = vi.fn();
+
+			const renderOptions: Partial<ProcaptchaRenderOptions> = {
+				"open-callback": openCallback,
+				"close-callback": closeCallback,
+			};
+
+			const callbacks = getDefaultCallbacks(widget);
+			setUserCallbacks(
+				renderOptions as ProcaptchaRenderOptions,
+				callbacks,
+				widget,
+			);
+
+			callbacks.onOpen();
+			callbacks.onClose();
+
+			expect(openCallback).toHaveBeenCalled();
+			expect(closeCallback).toHaveBeenCalled();
+		});
+	});
+});

package/src/tests/defaultEvents.test.ts

@@ -0,0 +1,80 @@
+// 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 { describe, expect, it, vi } from "vitest";
+import { getDefaultEvents } from "../callbacks/defaultEvents.js";
+
+describe("callbacks/defaultEvents", () => {
+	describe("getDefaultEvents", () => {
+		it("should merge default callbacks with provided callbacks", () => {
+			const customCallback = vi.fn();
+			const events = getDefaultEvents({
+				onHuman: customCallback,
+			});
+
+			expect(events.onHuman).toBe(customCallback);
+			expect(typeof events.onError).toBe("function");
+			expect(typeof events.onExpired).toBe("function");
+		});
+
+		it("should return all default callbacks when no custom callbacks provided", () => {
+			const events = getDefaultEvents({});
+
+			expect(typeof events.onHuman).toBe("function");
+			expect(typeof events.onChallengeExpired).toBe("function");
+			expect(typeof events.onExtensionNotFound).toBe("function");
+			expect(typeof events.onExpired).toBe("function");
+			expect(typeof events.onError).toBe("function");
+			expect(typeof events.onClose).toBe("function");
+			expect(typeof events.onOpen).toBe("function");
+			expect(typeof events.onFailed).toBe("function");
+			expect(typeof events.onReset).toBe("function");
+			expect(typeof events.onReload).toBe("function");
+		});
+
+		it("should allow overriding multiple callbacks", () => {
+			const customOnError = vi.fn();
+			const customOnExpired = vi.fn();
+			const customOnClose = vi.fn();
+
+			const events = getDefaultEvents({
+				onError: customOnError,
+				onExpired: customOnExpired,
+				onClose: customOnClose,
+			});
+
+			expect(events.onError).toBe(customOnError);
+			expect(events.onExpired).toBe(customOnExpired);
+			expect(events.onClose).toBe(customOnClose);
+			expect(typeof events.onHuman).toBe("function");
+			expect(typeof events.onFailed).toBe("function");
+		});
+
+		it("should preserve default behavior for non-overridden callbacks", () => {
+			const customOnHuman = vi.fn();
+
+			const events = getDefaultEvents({
+				onHuman: customOnHuman,
+			});
+
+			// Test that custom callback is used
+			expect(events.onHuman).toBe(customOnHuman);
+
+			// Test that other callbacks still exist and are functions
+			expect(typeof events.onError).toBe("function");
+			expect(typeof events.onExpired).toBe("function");
+			expect(typeof events.onChallengeExpired).toBe("function");
+		});
+	});
+});

package/src/tests/extensionLoader.test.ts

@@ -0,0 +1,41 @@
+// 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 { describe, expect, it, vi } from "vitest";
+import { ExtensionLoader } from "../extensionLoader.js";
+
+// Mock the imports
+vi.mock("@prosopo/account/extension/ExtensionWeb2", () => ({
+	default: { name: "ExtensionWeb2" },
+}));
+
+vi.mock("@prosopo/account/extension/ExtensionWeb3", () => ({
+	default: { name: "ExtensionWeb3" },
+}));
+
+describe("extensionLoader", () => {
+	describe("ExtensionLoader", () => {
+		it("should load ExtensionWeb2 when web2 is true", async () => {
+			const result = await ExtensionLoader(true);
+
+			expect(result).toEqual({ name: "ExtensionWeb2" });
+		});
+
+		it("should load ExtensionWeb3 when web2 is false", async () => {
+			const result = await ExtensionLoader(false);
+
+			expect(result).toEqual({ name: "ExtensionWeb3" });
+		});
+	});
+});