@prosopo/procaptcha-wrapper 2.6.102 → 2.6.104

package/src/render/renderer.ts

@@ -15,25 +15,39 @@
 import type { ProcaptchaRenderOptions } from "@prosopo/types";
 import { type RendererFunction, loadRenderFunction } from "./renderFunction.js";
 
-interface RendererSettings {
+export interface RendererSettings {
 	scriptUrl: string;
 	scriptId: string;
 }
 
+/** Loads the render function from a remote script. Injected so tests need no network. */
+export type LoadRenderFunction = (
+	scriptUrl: string,
+	scriptId: string,
+) => Promise<RendererFunction>;
+
 export const createRenderer = (
 	settings: RendererSettings,
+	load: LoadRenderFunction = loadRenderFunction,
 ): RendererFunction => {
-	let renderFunction: RendererFunction;
+	// The in-flight promise is cached, not just the resolved function: caching
+	// only the result lets two concurrent render() calls both see "not loaded"
+	// and each inject a script tag for the same id.
+	let pending: Promise<RendererFunction> | undefined;
 
 	const getRenderFunction = async (): Promise<RendererFunction> => {
-		if (!renderFunction) {
-			renderFunction = await loadRenderFunction(
-				settings.scriptUrl,
-				settings.scriptId,
+		if (!pending) {
+			// A failed load must not be cached, otherwise every later render()
+			// replays the same rejection and the widget can never recover.
+			pending = load(settings.scriptUrl, settings.scriptId).catch(
+				(error: unknown) => {
+					pending = undefined;
+					throw error;
+				},
 			);
 		}
 
-		return renderFunction;
+		return pending;
 	};
 
 	return async (

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

@@ -0,0 +1,47 @@
+// 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 { afterEach, describe, expect, it } from "vitest";
+import { renderProcaptcha } from "../index.js";
+
+afterEach(() => {
+	document.head.innerHTML = "";
+	document.body.innerHTML = "";
+	window.procaptcha = undefined;
+});
+
+describe("renderProcaptcha", () => {
+	it("is exported as a renderer function", () => {
+		expect(typeof renderProcaptcha).toBe("function");
+	});
+
+	it("does not touch the DOM until it is called", () => {
+		// The renderer is built at import time, but the script must only be
+		// fetched on first render — importing the package must cost nothing.
+		expect(document.head.querySelectorAll("script")).toHaveLength(0);
+	});
+
+	it("injects the build-time script url on first render", async () => {
+		const rendering = renderProcaptcha(document.createElement("div"), {
+			siteKey: "site-key",
+		});
+		await Promise.resolve();
+
+		const script = document.head.querySelector("script");
+		expect(script).not.toBeNull();
+
+		script?.dispatchEvent(new Event("error"));
+		await expect(rendering).rejects.toThrow("Failed to load script");
+	});
+});

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

@@ -0,0 +1,275 @@
+// 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 { ProcaptchaRenderOptions } from "@prosopo/types";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+	type RendererFunction,
+	loadRenderFunction,
+	loadScript,
+} from "../render/renderFunction.js";
+
+const SCRIPT_URL = "https://example.test/procaptcha.bundle.js";
+const SCRIPT_ID = "procaptcha-script";
+
+const noopRender: RendererFunction = async (): Promise<void> => {};
+
+/** The most recently appended script tag, i.e. the one a load is waiting on. */
+const lastScript = (): HTMLScriptElement => {
+	const scripts = document.head.querySelectorAll("script");
+	const script = scripts[scripts.length - 1];
+	if (undefined === script) {
+		throw new Error("no script tag was appended");
+	}
+	return script;
+};
+
+/**
+ * jsdom never fetches, so nothing ever fires load/error by itself. Wait for the
+ * tag to appear, then drive the outcome by hand.
+ */
+const settleScript = async (outcome: "load" | "error"): Promise<void> => {
+	await Promise.resolve();
+	lastScript().dispatchEvent(new Event(outcome));
+};
+
+afterEach(() => {
+	document.head.innerHTML = "";
+	document.body.innerHTML = "";
+	window.procaptcha = undefined;
+	vi.restoreAllMocks();
+});
+
+describe("loadScript", () => {
+	it("appends a script tag carrying the requested src", async () => {
+		const loading = loadScript(SCRIPT_URL);
+		await settleScript("load");
+		await loading;
+
+		expect(lastScript().src).toBe(SCRIPT_URL);
+	});
+
+	it("applies the supplied attributes to the tag", async () => {
+		const loading = loadScript(SCRIPT_URL, {
+			id: SCRIPT_ID,
+			type: "module",
+			async: true,
+			defer: true,
+		});
+		await settleScript("load");
+		await loading;
+
+		const script = lastScript();
+		expect(script.id).toBe(SCRIPT_ID);
+		expect(script.type).toBe("module");
+		expect(script.async).toBe(true);
+		expect(script.defer).toBe(true);
+	});
+
+	it("works with no attributes at all", async () => {
+		const loading = loadScript(SCRIPT_URL);
+		await settleScript("load");
+
+		await expect(loading).resolves.toBeUndefined();
+	});
+
+	it("lets an attribute override the src", async () => {
+		const loading = loadScript(SCRIPT_URL, {
+			src: "https://example.test/other.js",
+		});
+		await settleScript("load");
+		await loading;
+
+		expect(lastScript().src).toBe("https://example.test/other.js");
+	});
+
+	it("appends the tag to document.head, not the body", async () => {
+		const loading = loadScript(SCRIPT_URL);
+		await settleScript("load");
+		await loading;
+
+		expect(document.head.querySelectorAll("script")).toHaveLength(1);
+		expect(document.body.querySelectorAll("script")).toHaveLength(0);
+	});
+
+	it("rejects with an Error, not the raw DOM Event", async () => {
+		const loading = loadScript(SCRIPT_URL);
+		await settleScript("error");
+
+		await expect(loading).rejects.toBeInstanceOf(Error);
+	});
+
+	it("names the failing url in the rejection message", async () => {
+		const loading = loadScript(SCRIPT_URL);
+		await settleScript("error");
+
+		await expect(loading).rejects.toThrow(
+			`Failed to load script: ${SCRIPT_URL}`,
+		);
+	});
+
+	it("removes the failed tag so a retry leaves no duplicate id behind", async () => {
+		const first = loadScript(SCRIPT_URL, { id: SCRIPT_ID });
+		await settleScript("error");
+		await expect(first).rejects.toThrow();
+
+		expect(document.head.querySelectorAll("script")).toHaveLength(0);
+
+		const second = loadScript(SCRIPT_URL, { id: SCRIPT_ID });
+		await settleScript("load");
+		await second;
+
+		expect(document.querySelectorAll(`#${SCRIPT_ID}`)).toHaveLength(1);
+	});
+
+	it("stays pending until the script settles", async () => {
+		let settled = false;
+		const loading = loadScript(SCRIPT_URL).then(() => {
+			settled = true;
+		});
+
+		await Promise.resolve();
+		expect(settled).toBe(false);
+
+		await settleScript("load");
+		await loading;
+		expect(settled).toBe(true);
+	});
+
+	it("accepts an empty url without throwing synchronously", async () => {
+		const loading = loadScript("");
+		await settleScript("load");
+
+		await expect(loading).resolves.toBeUndefined();
+	});
+});
+
+describe("loadRenderFunction", () => {
+	it("returns the render function the script installed on window", async () => {
+		const loading = loadRenderFunction(SCRIPT_URL, SCRIPT_ID);
+		await Promise.resolve();
+		window.procaptcha = { render: noopRender };
+		lastScript().dispatchEvent(new Event("load"));
+
+		await expect(loading).resolves.toBe(noopRender);
+	});
+
+	it("requests the script as a deferred async module with the given id", async () => {
+		const loading = loadRenderFunction(SCRIPT_URL, SCRIPT_ID);
+		await Promise.resolve();
+		const script = lastScript();
+
+		expect(script.src).toBe(SCRIPT_URL);
+		expect(script.id).toBe(SCRIPT_ID);
+		expect(script.type).toBe("module");
+		expect(script.async).toBe(true);
+		expect(script.defer).toBe(true);
+
+		window.procaptcha = { render: noopRender };
+		script.dispatchEvent(new Event("load"));
+		await loading;
+	});
+
+	it("removes the tag when the script loads but is the wrong script", async () => {
+		// Same reasoning as a failed load: a retry must not find a stale tag
+		// sitting on the id it is about to reuse.
+		const loading = loadRenderFunction(SCRIPT_URL, SCRIPT_ID);
+		await settleScript("load");
+		await expect(loading).rejects.toThrow();
+
+		expect(document.getElementById(SCRIPT_ID)).toBeNull();
+	});
+
+	it("leaves a retry with exactly one tag after a wrong-script load", async () => {
+		const first = loadRenderFunction(SCRIPT_URL, SCRIPT_ID);
+		await settleScript("load");
+		await expect(first).rejects.toThrow();
+
+		const second = loadRenderFunction(SCRIPT_URL, SCRIPT_ID);
+		await Promise.resolve();
+		window.procaptcha = { render: noopRender };
+		lastScript().dispatchEvent(new Event("load"));
+
+		await expect(second).resolves.toBe(noopRender);
+		expect(document.querySelectorAll(`#${SCRIPT_ID}`)).toHaveLength(1);
+	});
+
+	it("keeps the tag when the script loads successfully", async () => {
+		const loading = loadRenderFunction(SCRIPT_URL, SCRIPT_ID);
+		await Promise.resolve();
+		window.procaptcha = { render: noopRender };
+		lastScript().dispatchEvent(new Event("load"));
+		await loading;
+
+		expect(document.getElementById(SCRIPT_ID)).not.toBeNull();
+	});
+
+	it("throws when the script loads but installs no procaptcha global", async () => {
+		const loading = loadRenderFunction(SCRIPT_URL, SCRIPT_ID);
+		await settleScript("load");
+
+		await expect(loading).rejects.toThrow(
+			"Render script does not contain the render function",
+		);
+	});
+
+	it("throws when the global exists but carries no render function", async () => {
+		const loading = loadRenderFunction(SCRIPT_URL, SCRIPT_ID);
+		await Promise.resolve();
+		// A partially-initialised global is indistinguishable from a stale one.
+		window.procaptcha = { render: undefined } as unknown as {
+			render: RendererFunction;
+		};
+		lastScript().dispatchEvent(new Event("load"));
+
+		await expect(loading).rejects.toThrow(
+			"Render script does not contain the render function",
+		);
+	});
+
+	it("propagates the load failure rather than reporting a missing function", async () => {
+		const loading = loadRenderFunction(SCRIPT_URL, SCRIPT_ID);
+		await settleScript("error");
+
+		await expect(loading).rejects.toThrow(
+			`Failed to load script: ${SCRIPT_URL}`,
+		);
+	});
+
+	it("does not check the global until the script has loaded", async () => {
+		const loading = loadRenderFunction(SCRIPT_URL, SCRIPT_ID);
+		await Promise.resolve();
+		// Set late — after injection but before load — to prove the check is
+		// deferred until the script has actually run.
+		window.procaptcha = { render: noopRender };
+		lastScript().dispatchEvent(new Event("load"));
+
+		await expect(loading).resolves.toBe(noopRender);
+	});
+
+	it("returns a function that forwards its arguments to the loaded render", async () => {
+		const render = vi.fn<RendererFunction>(async (): Promise<void> => {});
+		const loading = loadRenderFunction(SCRIPT_URL, SCRIPT_ID);
+		await Promise.resolve();
+		window.procaptcha = { render };
+		lastScript().dispatchEvent(new Event("load"));
+
+		const loaded = await loading;
+		const element = document.createElement("div");
+		const options: ProcaptchaRenderOptions = { siteKey: "site-key" };
+		await loaded(element, options);
+
+		expect(render).toHaveBeenCalledWith(element, options);
+	});
+});

package/src/tests/renderer.test-d.ts

@@ -0,0 +1,175 @@
+// 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 { Languages } from "@prosopo/locale";
+import type { CaptchaType, ProcaptchaRenderOptions } from "@prosopo/types";
+import { assertType, describe, expectTypeOf, it } from "vitest";
+import type {
+	ProcaptchaRenderOptions as ExportedRenderOptions,
+	ProcaptchaLanguages,
+	ProcaptchaType,
+} from "../index.js";
+import { renderProcaptcha } from "../index.js";
+import {
+	type RendererFunction,
+	loadRenderFunction,
+	loadScript,
+} from "../render/renderFunction.js";
+import {
+	type LoadRenderFunction,
+	type RendererSettings,
+	createRenderer,
+} from "../render/renderer.js";
+
+// This package is published, so these types are its contract with consumers.
+// Runtime tests cannot catch a signature that silently widens or drifts.
+
+describe("RendererFunction", () => {
+	it("takes an element and options, and resolves to void", () => {
+		expectTypeOf<RendererFunction>().parameters.toEqualTypeOf<
+			[HTMLElement, ProcaptchaRenderOptions]
+		>();
+		expectTypeOf<RendererFunction>().returns.toEqualTypeOf<Promise<void>>();
+	});
+
+	it("does not accept a bare Element for the mount point", () => {
+		// Narrower than Element on purpose: the render script sets style and
+		// dataset properties that only exist on HTMLElement.
+		expectTypeOf<Element>().not.toMatchTypeOf<
+			Parameters<RendererFunction>[0]
+		>();
+	});
+
+	it("requires a siteKey in the options", () => {
+		assertType<Parameters<RendererFunction>[1]>({ siteKey: "site-key" });
+		// @ts-expect-error siteKey is mandatory
+		assertType<Parameters<RendererFunction>[1]>({});
+	});
+
+	it("rejects an unknown option key", () => {
+		assertType<Parameters<RendererFunction>[1]>({
+			siteKey: "site-key",
+			// @ts-expect-error not part of the render options
+			notAnOption: true,
+		});
+	});
+});
+
+describe("renderProcaptcha", () => {
+	it("is exposed as a RendererFunction", () => {
+		expectTypeOf(renderProcaptcha).toEqualTypeOf<RendererFunction>();
+	});
+});
+
+describe("re-exported types", () => {
+	it("aliases the shared types rather than redeclaring them", () => {
+		// These are the names consumers import; they must stay tied to the
+		// shared definitions so a change upstream is not silently absorbed.
+		expectTypeOf<ProcaptchaType>().toEqualTypeOf<CaptchaType>();
+		expectTypeOf<ExportedRenderOptions>().toEqualTypeOf<ProcaptchaRenderOptions>();
+	});
+
+	it("exports the language union as a usable type", () => {
+		// `Languages` is a const object with no type meaning, so re-exporting the
+		// name as a type produced a binding consumers could not use at all.
+		expectTypeOf<ProcaptchaLanguages>().toEqualTypeOf<
+			(typeof Languages)[keyof typeof Languages]
+		>();
+		assertType<ProcaptchaLanguages>("en");
+	});
+
+	it("keeps the language union aligned with the render options", () => {
+		expectTypeOf<ProcaptchaLanguages>().toEqualTypeOf<
+			NonNullable<ProcaptchaRenderOptions["language"]>
+		>();
+	});
+
+	it("rejects a language outside the union", () => {
+		// @ts-expect-error not a supported language
+		assertType<ProcaptchaLanguages>("not-a-language");
+	});
+});
+
+describe("createRenderer", () => {
+	it("returns a RendererFunction", () => {
+		expectTypeOf(createRenderer).returns.toEqualTypeOf<RendererFunction>();
+	});
+
+	it("takes settings and an optional loader override", () => {
+		expectTypeOf(createRenderer).parameters.toEqualTypeOf<
+			[RendererSettings, (LoadRenderFunction | undefined)?]
+		>();
+	});
+
+	it("accepts a call with settings alone", () => {
+		expectTypeOf(createRenderer).toBeCallableWith({
+			scriptUrl: "url",
+			scriptId: "id",
+		});
+	});
+
+	it("requires both settings fields", () => {
+		// @ts-expect-error scriptId is mandatory
+		assertType<RendererSettings>({ scriptUrl: "url" });
+		// @ts-expect-error scriptUrl is mandatory
+		assertType<RendererSettings>({ scriptId: "id" });
+	});
+
+	it("rejects a loader that resolves to the wrong shape", () => {
+		// @ts-expect-error the loader must resolve to a RendererFunction
+		createRenderer({ scriptUrl: "url", scriptId: "id" }, async () => "nope");
+	});
+});
+
+describe("LoadRenderFunction", () => {
+	it("takes two strings and resolves to a RendererFunction", () => {
+		expectTypeOf<LoadRenderFunction>().parameters.toEqualTypeOf<
+			[string, string]
+		>();
+		expectTypeOf<LoadRenderFunction>().returns.toEqualTypeOf<
+			Promise<RendererFunction>
+		>();
+	});
+
+	it("is satisfied by the real loader", () => {
+		// The default argument of createRenderer depends on this holding.
+		expectTypeOf(loadRenderFunction).toMatchTypeOf<LoadRenderFunction>();
+	});
+});
+
+describe("loadScript", () => {
+	it("resolves to void rather than the tag it created", () => {
+		expectTypeOf(loadScript).returns.toEqualTypeOf<Promise<void>>();
+	});
+
+	it("takes an optional partial set of script attributes", () => {
+		expectTypeOf(loadScript).toBeCallableWith("url");
+		expectTypeOf(loadScript).toBeCallableWith("url", { id: "id" });
+	});
+
+	it("rejects an attribute that is not on a script element", () => {
+		// @ts-expect-error href belongs to link elements, not script
+		loadScript("url", { href: "url" });
+	});
+});
+
+describe("window.procaptcha", () => {
+	it("is declared as possibly absent", () => {
+		// The global only exists once the render script has run, so consumers
+		// must be forced to narrow before reaching for render.
+		expectTypeOf<typeof window.procaptcha>().toEqualTypeOf<
+			{ render: RendererFunction } | undefined
+		>();
+	});
+});