@prosopo/procaptcha-bundle 4.2.5 → 4.4.0

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

@@ -0,0 +1,155 @@
+// 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";
+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, start } = await import("../index.js");
+
+const SITE_KEY = "5CcNvLUdiXFpzKDMjThGLSK9rhWHA1H4EF3zrgkpkjAdqmuP";
+
+const makeWidget = (): CreatedWidget => ({
+	root: { unmount: vi.fn(), render: vi.fn() } as unknown as Root,
+	container: document.createElement("div"),
+});
+
+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([makeWidget()]);
+	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([makeWidget()]);
+		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

@@ -15,19 +15,34 @@
 import createCache, { type EmotionCache } from "@emotion/cache";
 import { CacheProvider } from "@emotion/react";
 import type { Ti18n } from "@prosopo/locale";
-import type {
-	Callbacks,
-	ProcaptchaClientConfigOutput,
-	ProcaptchaRenderOptions,
+import {
+	type Callbacks,
+	Placement,
+	type PlacementType,
+	type ProcaptchaClientConfigOutput,
+	type ProcaptchaRenderOptions,
 } from "@prosopo/types";
 import type { ReactNode } from "react";
 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";
 
+const resolveRequestedPlacement = (
+	element: Element,
+	renderOptions: ProcaptchaRenderOptions,
+): PlacementType | undefined => {
+	const requested =
+		renderOptions.placement ?? element.getAttribute("data-placement");
+	if (!requested) return undefined;
+
+	const parsed = Placement.safeParse(requested);
+	return parsed.success ? parsed.data : undefined;
+};
+
 interface RenderSettings {
 	identifierPrefix: string;
 	emotionCacheKey: string;
@@ -46,16 +61,20 @@ class CaptchaRenderer {
 		widgetContainer: HTMLElement,
 		sourceElement?: Element,
 	): Root {
-		const config = createConfig(
-			renderOptions.siteKey,
-			renderOptions.theme,
-			renderOptions.language,
-			isWeb2,
+		const config = createConfig({
+			siteKey: renderOptions.siteKey,
+			theme: renderOptions.theme,
+			language: renderOptions.language,
+			web2: isWeb2,
 			invisible,
-			renderOptions.userAccountAddress,
-			renderOptions.ipv4,
-			renderOptions.ipv6,
-		);
+			placement: resolveRequestedPlacement(
+				sourceElement || container,
+				renderOptions,
+			),
+			userAccountAddress: renderOptions.userAccountAddress,
+			ipv4: renderOptions.ipv4,
+			ipv6: renderOptions.ipv6,
+		});
 		this.readAndValidateSettings(
 			sourceElement || container,
 			config,
@@ -94,6 +113,7 @@ class CaptchaRenderer {
 		setValidChallengeLength(renderOptions, element, config);
 		setLanguage(renderOptions, element, config);
 		setClientSessionId(renderOptions, element, config);
+		setStartMode(renderOptions, element, config);
 	}
 
 	protected makeEmotionCache(

package/src/util/configCreator.ts

@@ -15,23 +15,39 @@
 import type { Languages } from "@prosopo/locale";
 import {
 	EnvironmentTypesSchema,
+	type PlacementType,
 	type ProcaptchaClientConfigOutput,
 	ProcaptchaConfigSchema,
+	resolvePlacement,
 } from "@prosopo/types";
 
+interface CreateConfigOptions {
+	siteKey?: string;
+	theme?: "light" | "dark";
+	language?: (typeof Languages)[keyof typeof Languages];
+	web2?: boolean;
+	invisible?: boolean;
+	placement?: PlacementType;
+	userAccountAddress?: string;
+	ipv4?: boolean;
+	ipv6?: boolean;
+}
+
 function createConfig(
-	siteKey?: string,
-	theme: "light" | "dark" = "light",
-	language?: (typeof Languages)[keyof typeof Languages],
-	web2 = true,
-	invisible = false,
-	userAccountAddress?: string,
-	ipv4 = false,
-	ipv6 = false,
+	options: CreateConfigOptions = {},
 ): ProcaptchaClientConfigOutput {
-	if (!siteKey) {
-		siteKey = process.env.PROSOPO_SITE_KEY || "";
-	}
+	const {
+		theme = "light",
+		language,
+		web2 = true,
+		invisible = false,
+		placement,
+		userAccountAddress,
+		ipv4 = false,
+		ipv6 = false,
+	} = options;
+
+	const siteKey = options.siteKey || process.env.PROSOPO_SITE_KEY || "";
 
 	return ProcaptchaConfigSchema.parse({
 		defaultEnvironment: process.env.PROSOPO_DEFAULT_ENVIRONMENT
@@ -45,6 +61,7 @@ function createConfig(
 		mongoAtlasUri: process.env.PROSOPO_MONGO_EVENTS_URI || "",
 		web2,
 		mode: invisible ? "invisible" : "visible",
+		placement: resolvePlacement(placement, invisible),
 		theme,
 		language,
 		ipv4,
@@ -53,3 +70,4 @@ function createConfig(
 }
 
 export { createConfig };
+export type { CreateConfigOptions };

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);
+};

package/src/util/widgetFactory.ts

@@ -29,6 +29,12 @@ import type { CaptchaRenderer } from "./captcha/captchaRenderer.js";
 import { resolveLanguage } from "./language.js";
 import type { WidgetThemeResolver } from "./widgetThemeResolver.js";
 
+/** A mounted widget and the element it listens on for `procaptcha:execute`. */
+interface CreatedWidget {
+	root: Root;
+	container: HTMLElement;
+}
+
 class WidgetFactory {
 	private captchaRenderer: CaptchaRenderer | null = null;
 	private _i18n: Ti18n | null = null;
@@ -49,7 +55,7 @@ class WidgetFactory {
 		renderOptions: ProcaptchaRenderOptions,
 		isWeb2 = true,
 		invisible = false,
-	): Promise<Root[]> {
+	): Promise<CreatedWidget[]> {
 		return Promise.all(
 			containers.map((container) => {
 				const callbacks = getDefaultCallbacks(container);
@@ -71,7 +77,7 @@ class WidgetFactory {
 		callbacks: Callbacks,
 		isWeb2 = true,
 		invisible = false,
-	): Promise<Root> {
+	): Promise<CreatedWidget> {
 		renderOptions.theme = this.widgetThemeResolver.resolveWidgetTheme(
 			container,
 			renderOptions,
@@ -127,7 +133,7 @@ class WidgetFactory {
 			container,
 		);
 
-		return captchaRoot;
+		return { root: captchaRoot, container: widgetContainer };
 	}
 
 	protected async getCaptchaRenderer(
@@ -158,3 +164,4 @@ class WidgetFactory {
 }
 
 export { WidgetFactory };
+export type { CreatedWidget };