@prosopo/procaptcha-bundle 4.2.4 → 4.3.0

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

@@ -0,0 +1,152 @@
+// 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 {
+	PROCAPTCHA_START_EVENT,
+	type ProcaptchaStartEventDetail,
+	StartModeEnum,
+} from "@prosopo/types";
+import type { Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+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, start } = await import("../index.js");
+
+const SITE_KEY = "5CcNvLUdiXFpzKDMjThGLSK9rhWHA1H4EF3zrgkpkjAdqmuP";
+
+const makeRoot = (): Root =>
+	({ unmount: vi.fn(), render: vi.fn() }) as unknown as Root;
+
+const flush = (): Promise<void> =>
+	new Promise((resolve) => setTimeout(resolve, 0));
+
+const renderWidget = async (
+	options: Partial<Parameters<typeof render>[1]> = {},
+): Promise<{ element: HTMLDivElement; id: string }> => {
+	mocks.createWidgets.mockResolvedValueOnce([makeRoot()]);
+	const element = document.createElement("div");
+	const id = await render(element, { siteKey: SITE_KEY, ...options });
+	if (!id) throw new Error("expected render to return a widget id");
+	return { element, id };
+};
+
+let received: ProcaptchaStartEventDetail[];
+const onStart = (event: Event): void => {
+	received.push((event as CustomEvent<ProcaptchaStartEventDetail>).detail);
+};
+
+beforeEach(async () => {
+	vi.clearAllMocks();
+	await remove();
+	received = [];
+	document.addEventListener(PROCAPTCHA_START_EVENT, onStart);
+});
+
+afterEach(() => {
+	document.removeEventListener(PROCAPTCHA_START_EVENT, onStart);
+});
+
+describe("start", () => {
+	it("addresses one event to each widget when no id is given", async () => {
+		const first = await renderWidget();
+		const second = await renderWidget();
+
+		start();
+
+		expect(received.map((detail) => detail.element)).toEqual([
+			first.element,
+			second.element,
+		]);
+	});
+
+	it("addresses the event to the widget whose id is given", async () => {
+		await renderWidget();
+		const second = await renderWidget();
+
+		start(second.id);
+
+		expect(received).toHaveLength(1);
+		expect(received[0]?.element).toBe(second.element);
+	});
+
+	it("reports an unknown id instead of dispatching", async () => {
+		const error = vi.spyOn(console, "error").mockImplementation(() => {});
+		await renderWidget();
+
+		start("procaptcha-widget-does-not-exist");
+
+		expect(received).toHaveLength(0);
+		expect(error).toHaveBeenCalledTimes(1);
+		error.mockRestore();
+	});
+
+	it("reports when there is nothing to start", () => {
+		const error = vi.spyOn(console, "error").mockImplementation(() => {});
+
+		start();
+
+		expect(received).toHaveLength(0);
+		expect(error).toHaveBeenCalledTimes(1);
+		error.mockRestore();
+	});
+
+	it("is exposed on window.procaptcha", () => {
+		expect(window.procaptcha.start).toBe(start);
+	});
+});
+
+describe("detector prefetch", () => {
+	it("runs on render in auto mode", async () => {
+		await renderWidget();
+		await flush();
+
+		expect(mocks.prefetchDetector).toHaveBeenCalledTimes(1);
+	});
+
+	it("is skipped in manual mode so nothing reaches the provider on load", async () => {
+		await renderWidget({ startMode: StartModeEnum.manual });
+		await flush();
+
+		expect(mocks.prefetchDetector).not.toHaveBeenCalled();
+	});
+
+	it("is skipped when the element asks for manual mode", async () => {
+		mocks.createWidgets.mockResolvedValueOnce([makeRoot()]);
+		const element = document.createElement("div");
+		element.setAttribute("data-start-mode", "manual");
+		await render(element, { siteKey: SITE_KEY });
+		await flush();
+
+		expect(mocks.prefetchDetector).not.toHaveBeenCalled();
+	});
+});

package/src/tests/util/startMode.test.ts

@@ -0,0 +1,113 @@
+// 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 ProcaptchaClientConfigOutput,
+	ProcaptchaConfigSchema,
+	type ProcaptchaRenderOptions,
+	StartModeEnum,
+} from "@prosopo/types";
+import { JSDOM } from "jsdom";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+	START_MODE_ATTRIBUTE,
+	resolveStartMode,
+	setStartMode,
+} from "../../util/startMode.js";
+
+const SITE_KEY = "5site";
+
+const makeConfig = (): ProcaptchaClientConfigOutput =>
+	ProcaptchaConfigSchema.parse({ account: { address: SITE_KEY } });
+
+const makeElement = (attributes: Record<string, string> = {}): Element => {
+	const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>");
+	const element = dom.window.document.createElement("div");
+	for (const [name, value] of Object.entries(attributes)) {
+		element.setAttribute(name, value);
+	}
+	return element;
+};
+
+const renderOptions = (
+	overrides: Partial<ProcaptchaRenderOptions> = {},
+): ProcaptchaRenderOptions => ({ siteKey: SITE_KEY, ...overrides });
+
+describe("resolveStartMode", () => {
+	beforeEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("defaults to auto", () => {
+		expect(resolveStartMode(renderOptions(), makeElement())).toBe(
+			StartModeEnum.auto,
+		);
+		expect(resolveStartMode(undefined, makeElement())).toBe(StartModeEnum.auto);
+	});
+
+	it("reads the start mode from the render options", () => {
+		expect(
+			resolveStartMode(
+				renderOptions({ startMode: StartModeEnum.manual }),
+				makeElement(),
+			),
+		).toBe(StartModeEnum.manual);
+	});
+
+	it("reads the start mode from the data attribute", () => {
+		expect(
+			resolveStartMode(
+				renderOptions(),
+				makeElement({ [START_MODE_ATTRIBUTE]: "manual" }),
+			),
+		).toBe(StartModeEnum.manual);
+	});
+
+	it("prefers the render options over the attribute", () => {
+		expect(
+			resolveStartMode(
+				renderOptions({ startMode: StartModeEnum.auto }),
+				makeElement({ [START_MODE_ATTRIBUTE]: "manual" }),
+			),
+		).toBe(StartModeEnum.auto);
+	});
+
+	it("falls back to auto on an unknown value and says so", () => {
+		const error = vi.spyOn(console, "error").mockImplementation(() => {});
+
+		expect(
+			resolveStartMode(
+				renderOptions(),
+				makeElement({ [START_MODE_ATTRIBUTE]: "later" }),
+			),
+		).toBe(StartModeEnum.auto);
+		expect(error).toHaveBeenCalledTimes(1);
+		expect(error.mock.calls[0]?.[0]).toContain("later");
+	});
+});
+
+describe("setStartMode", () => {
+	it("writes the resolved mode onto the config", () => {
+		const config = makeConfig();
+		expect(config.startMode).toBe(StartModeEnum.auto);
+
+		setStartMode(
+			renderOptions(),
+			makeElement({ [START_MODE_ATTRIBUTE]: "manual" }),
+			config,
+		);
+
+		expect(config.startMode).toBe(StartModeEnum.manual);
+	});
+});

package/src/util/captcha/captchaRenderer.tsx

@@ -25,6 +25,7 @@ import { type Root, createRoot } from "react-dom/client";
 import { setClientSessionId } from "../clientSession.js";
 import { createConfig } from "../configCreator.js";
 import { setLanguage } from "../language.js";
+import { setStartMode } from "../startMode.js";
 import { setValidChallengeLength } from "../timeout.js";
 import { BundleCaptcha } from "./components/bundleCaptcha.js";
 
@@ -94,6 +95,7 @@ class CaptchaRenderer {
 		setValidChallengeLength(renderOptions, element, config);
 		setLanguage(renderOptions, element, config);
 		setClientSessionId(renderOptions, element, config);
+		setStartMode(renderOptions, element, config);
 	}
 
 	protected makeEmotionCache(

package/src/util/startMode.ts

@@ -0,0 +1,53 @@
+// 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 ProcaptchaClientConfigOutput,
+	type ProcaptchaRenderOptions,
+	type StartMode,
+	StartModeEnum,
+	StartModeSchema,
+} from "@prosopo/types";
+
+export const START_MODE_ATTRIBUTE = "data-start-mode";
+
+export const resolveStartMode = (
+	renderOptions: ProcaptchaRenderOptions | undefined,
+	element: Element,
+): StartMode => {
+	const requested =
+		renderOptions?.startMode || element.getAttribute(START_MODE_ATTRIBUTE);
+
+	if (!requested) {
+		return StartModeEnum.auto;
+	}
+
+	const parsed = StartModeSchema.safeParse(requested);
+	if (!parsed.success) {
+		console.error(
+			`Ignoring unknown start mode "${requested}"; expected one of ${StartModeSchema.options.join(", ")}`,
+		);
+		return StartModeEnum.auto;
+	}
+
+	return parsed.data;
+};
+
+export const setStartMode = (
+	renderOptions: ProcaptchaRenderOptions | undefined,
+	element: Element,
+	config: ProcaptchaClientConfigOutput,
+): void => {
+	config.startMode = resolveStartMode(renderOptions, element);
+};