@prosopo/procaptcha-frictionless 2.16.3 → 2.16.4

package/dist/tests/executeBeforeMount.test.js

@@ -0,0 +1,152 @@
+import { CaptchaType, ModeEnum, StartModeEnum, } from "@prosopo/types";
+import { act, createElement, useEffect } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const EXECUTE_EVENT = "procaptcha:execute";
+const mocks = vi.hoisted(() => ({
+    executes: [],
+}));
+const ListeningWidget = (props) => {
+    const { container } = props;
+    const invisible = props.config.mode === "invisible";
+    useEffect(() => {
+        const onContainer = () => mocks.executes.push("container");
+        const onDocument = () => mocks.executes.push("document");
+        container?.addEventListener(EXECUTE_EVENT, onContainer);
+        if (invisible)
+            document.addEventListener(EXECUTE_EVENT, onDocument);
+        return () => {
+            container?.removeEventListener(EXECUTE_EVENT, onContainer);
+            if (invisible)
+                document.removeEventListener(EXECUTE_EVENT, onDocument);
+        };
+    }, [container, invisible]);
+    return createElement("div", { "data-widget": "image" });
+};
+vi.mock("@prosopo/procaptcha-react", () => ({ Procaptcha: ListeningWidget }));
+vi.mock("@prosopo/procaptcha-pow", () => ({ ProcaptchaPow: ListeningWidget }));
+vi.mock("@prosopo/procaptcha-puzzle", () => ({
+    ProcaptchaPuzzle: ListeningWidget,
+}));
+vi.mock("@prosopo/procaptcha-common", async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, isSecureBrowserContext: () => true };
+});
+const { ProcaptchaFrictionless } = await import("../ProcaptchaFrictionless.js");
+const config = (overrides = {}) => ({
+    account: { address: "5siteKey" },
+    userAccountAddress: "",
+    web2: true,
+    mode: ModeEnum.invisible,
+    startMode: StartModeEnum.auto,
+    ...overrides,
+});
+const i18nStub = {
+    isInitialized: true,
+    language: "en",
+    t: (key) => key,
+    changeLanguage: vi.fn(),
+};
+const detectionResult = () => ({
+    status: "ok",
+    captchaType: CaptchaType.image,
+    sessionId: "provider-session",
+    provider: { provider: { url: "https://provider.test" } },
+    userAccount: { account: { address: "5FakeUserAccountAddress" } },
+});
+const heldDetection = () => {
+    let resolve;
+    const detectBot = vi.fn().mockImplementation(() => new Promise((r) => {
+        resolve = r;
+    }));
+    const finish = async () => {
+        await act(async () => {
+            resolve?.(detectionResult());
+        });
+    };
+    return { detectBot, finish };
+};
+let host;
+let container;
+let root;
+const mountWrapper = async (detectBot, overrides = {}) => {
+    await act(async () => {
+        root.render(createElement(ProcaptchaFrictionless, {
+            config: config(overrides),
+            callbacks: {},
+            restart: vi.fn(),
+            i18n: i18nStub,
+            detectBot,
+            container,
+        }));
+    });
+};
+const dispatch = async (target) => {
+    await act(async () => {
+        target.dispatchEvent(new CustomEvent(EXECUTE_EVENT));
+    });
+};
+beforeEach(() => {
+    mocks.executes.length = 0;
+    host = document.createElement("div");
+    container = document.createElement("div");
+    document.body.append(host, container);
+    act(() => {
+        root = createRoot(host);
+    });
+});
+afterEach(() => {
+    act(() => {
+        root.unmount();
+    });
+    host.remove();
+    container.remove();
+    vi.clearAllMocks();
+});
+describe("execute() before the inner widget is listening", () => {
+    it("replays a bare execute() once the invisible widget mounts", async () => {
+        const { detectBot, finish } = heldDetection();
+        await mountWrapper(detectBot);
+        await dispatch(document);
+        expect(mocks.executes).toEqual([]);
+        await finish();
+        expect(mocks.executes).toEqual(["container"]);
+    });
+    it("replays a targeted execute() in visible mode", async () => {
+        const { detectBot, finish } = heldDetection();
+        await mountWrapper(detectBot, { mode: ModeEnum.visible });
+        await dispatch(container);
+        await finish();
+        expect(mocks.executes).toEqual(["container"]);
+    });
+    it("replays repeated early calls only once", async () => {
+        const { detectBot, finish } = heldDetection();
+        await mountWrapper(detectBot);
+        await dispatch(document);
+        await dispatch(document);
+        await finish();
+        expect(mocks.executes).toEqual(["container"]);
+    });
+    it("does not start the widget when execute() was never called", async () => {
+        const { detectBot, finish } = heldDetection();
+        await mountWrapper(detectBot);
+        await finish();
+        expect(mocks.executes).toEqual([]);
+    });
+    it("leaves an execute() after mount to the widget alone", async () => {
+        const { detectBot, finish } = heldDetection();
+        await mountWrapper(detectBot);
+        await finish();
+        await dispatch(document);
+        expect(mocks.executes).toEqual(["document"]);
+    });
+    it("ignores a bare execute() in visible mode, as the widgets do", async () => {
+        const { detectBot, finish } = heldDetection();
+        await mountWrapper(detectBot, { mode: ModeEnum.visible });
+        await dispatch(document);
+        await finish();
+        expect(mocks.executes).toEqual([]);
+    });
+});
+//# sourceMappingURL=executeBeforeMount.test.js.map

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

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

package/dist/tests/frictionlessResultGuard.test.js

@@ -16,7 +16,12 @@ describe("evaluateFrictionlessResult", () => {
         expect(evaluateFrictionlessResult({
             captchaType: "pow",
             error: { message: "Boom", key: "API.SOMETHING" },
-        })).toEqual({ kind: "error", message: "Boom", key: "API.SOMETHING" });
+        })).toEqual({
+            kind: "error",
+            message: "Boom",
+            key: "API.SOMETHING",
+            retryable: true,
+        });
     });
     it("omits key from the outcome when the server error carries no key", () => {
         const outcome = evaluateFrictionlessResult({
@@ -32,12 +37,17 @@ describe("evaluateFrictionlessResult", () => {
     it("halts when captchaType is missing (bare-string 401 body shape from access-policy / autoBan / middleware)", () => {
         expect(evaluateFrictionlessResult({
             error: undefined,
-        })).toEqual({ kind: "error", message: MISSING_CAPTCHA_TYPE_MESSAGE });
+        })).toEqual({
+            kind: "error",
+            message: MISSING_CAPTCHA_TYPE_MESSAGE,
+            retryable: false,
+        });
     });
     it("halts when both captchaType and error are absent (opaque parse failure)", () => {
         expect(evaluateFrictionlessResult({})).toEqual({
             kind: "error",
             message: MISSING_CAPTCHA_TYPE_MESSAGE,
+            retryable: false,
         });
     });
     it("prefers the structured error over the missing-captchaType message when both apply", () => {
@@ -47,6 +57,53 @@ describe("evaluateFrictionlessResult", () => {
             kind: "error",
             message: "Server error",
             key: "API.SERVER_ERROR",
+            retryable: true,
+        });
+    });
+    describe("retryable classification", () => {
+        const retryableOf = (key) => {
+            const outcome = evaluateFrictionlessResult({
+                error: { message: "msg", ...(key !== undefined && { key }) },
+            });
+            if (outcome.kind !== "error")
+                throw new Error("expected error outcome");
+            return outcome.retryable;
+        };
+        it.each([
+            "API.SITE_KEY_NOT_REGISTERED",
+            "API.INVALID_SITE_KEY",
+            "API.UNAUTHORIZED_ORIGIN_URL",
+            "API.INCORRECT_CAPTCHA_TYPE",
+        ])("shows integration fault %s rather than re-rolling", (key) => {
+            expect(retryableOf(key)).toBe(false);
+        });
+        it.each([
+            "API.ACCESS_POLICY_BLOCK",
+            "API.ABUSER_BLOCKED",
+            "API.CRAWLER_BLOCKED",
+            "API.DATACENTER_BLOCKED",
+            "API.DISALLOWED_WEBVIEW",
+            "API.MOBILE_BLOCKED",
+            "API.PROXY_BLOCKED",
+            "API.SATELLITE_BLOCKED",
+            "API.TOR_BLOCKED",
+            "API.VPN_BLOCKED",
+            "API.FORBIDDEN",
+            "API.UNAUTHORIZED",
+        ])("does not re-roll policy denial %s", (key) => {
+            expect(retryableOf(key)).toBe(false);
+        });
+        it("leaves CAPTCHA.NO_SESSION_FOUND to its own restart timer", () => {
+            expect(retryableOf("CAPTCHA.NO_SESSION_FOUND")).toBe(false);
+        });
+        it("re-rolls API.BAD_REQUEST, which is what an unhandled provider throw becomes", () => {
+            expect(retryableOf("API.BAD_REQUEST")).toBe(true);
+        });
+        it.each(["API.UNKNOWN", "API.INTERNAL_SERVER_ERROR", "DATABASE.UNKNOWN"])("re-rolls unrecognised provider fault %s", (key) => {
+            expect(retryableOf(key)).toBe(true);
+        });
+        it("does not re-roll an error with no key at all", () => {
+            expect(retryableOf(undefined)).toBe(false);
         });
     });
 });

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

@@ -1 +1 @@
-{"version":3,"file":"frictionlessResultGuard.test.js","sourceRoot":"","sources":["../../src/tests/frictionlessResultGuard.test.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EACN,4BAA4B,EAC5B,0BAA0B,GAC1B,MAAM,+BAA+B,CAAC;AAWvC,QAAQ,CAAC,4BAA4B,EAAE,GAAG,EAAE;IAC3C,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC3D,MAAM,CACL,0BAA0B,CAAC;YAC1B,WAAW,EAAE,KAAK;SAClB,CAAC,CACF,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wEAAwE,EAAE,GAAG,EAAE;QACjF,MAAM,CACL,0BAA0B,CAAC;YAC1B,WAAW,EAAE,OAAO;YACpB,KAAK,EAAE,SAAS;SAChB,CAAC,CACF,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2EAA2E,EAAE,GAAG,EAAE;QACpF,MAAM,CACL,0BAA0B,CAAC;YAC1B,WAAW,EAAE,KAAK;YAClB,KAAK,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,EAAE;SAChD,CAAC,CACF,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,EAAE,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iEAAiE,EAAE,GAAG,EAAE;QAC1E,MAAM,OAAO,GAAG,0BAA0B,CAAC;YAC1C,WAAW,EAAE,KAAK;YAClB,KAAK,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE;SAC1B,CAAC,CAAC;QACH,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QACxE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrC,MAAM,CAAC,KAAK,IAAI,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0GAA0G,EAAE,GAAG,EAAE;QAOnH,MAAM,CACL,0BAA0B,CAAC;YAG1B,KAAK,EAAE,SAAS;SAChB,CAAC,CACF,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,4BAA4B,EAAE,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yEAAyE,EAAE,GAAG,EAAE;QAClF,MAAM,CAAC,0BAA0B,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;YAC9C,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,4BAA4B;SACrC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mFAAmF,EAAE,GAAG,EAAE;QAG5F,MAAM,CACL,0BAA0B,CAAC;YAC1B,KAAK,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,EAAE,kBAAkB,EAAE;SAC3D,CAAC,CACF,CAAC,OAAO,CAAC;YACT,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,cAAc;YACvB,GAAG,EAAE,kBAAkB;SACvB,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;AACJ,CAAC,CAAC,CAAC"}
+{"version":3,"file":"frictionlessResultGuard.test.js","sourceRoot":"","sources":["../../src/tests/frictionlessResultGuard.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@prosopo/procaptcha-frictionless",
-	"version": "2.16.3",
+	"version": "2.16.4",
 	"author": "PROSOPO LIMITED <info@prosopo.io>",
 	"license": "Apache-2.0",
 	"main": "dist/index.js",
@@ -30,26 +30,26 @@
 	},
 	"browserslist": ["> 0.5%, last 2 versions, not dead"],
 	"dependencies": {
-		"@prosopo/api": "4.2.3",
-		"@prosopo/common": "3.1.55",
-		"@prosopo/locale": "3.4.2",
-		"@prosopo/procaptcha-common": "2.14.0",
-		"@prosopo/procaptcha-pow": "2.12.4",
-		"@prosopo/procaptcha-puzzle": "2.13.0",
-		"@prosopo/procaptcha-react": "2.11.0",
-		"@prosopo/types": "5.8.3",
+		"@prosopo/api": "4.2.4",
+		"@prosopo/common": "3.1.56",
+		"@prosopo/locale": "3.4.3",
+		"@prosopo/procaptcha-common": "2.14.1",
+		"@prosopo/procaptcha-pow": "2.12.5",
+		"@prosopo/procaptcha-puzzle": "2.13.1",
+		"@prosopo/procaptcha-react": "2.11.1",
+		"@prosopo/types": "5.8.4",
 		"@prosopo/widget-skeleton": "2.8.7",
 		"dotenv": "16.4.5",
-		"react": "19.2.8"
+		"react": "19.3.0"
 	},
 	"devDependencies": {
-		"@prosopo/config": "3.3.16",
+		"@prosopo/config": "3.3.17",
 		"@types/node": "22.10.2",
 		"@vitest/coverage-v8": "4.1.11",
 		"concurrently": "9.0.1",
 		"del-cli": "6.0.0",
 		"npm-run-all": "4.1.5",
-		"react-dom": "19.2.8",
+		"react-dom": "19.3.0",
 		"tslib": "2.7.0",
 		"tsx": "4.20.3",
 		"typescript": "5.6.2",

package/src/ProcaptchaFrictionless.tsx

@@ -23,6 +23,7 @@ import {
 import {
 	CaptchaType,
 	type FrictionlessState,
+	ModeEnum,
 	type ModeType,
 	PROCAPTCHA_START_EVENT,
 	ProcaptchaConfigSchema,
@@ -149,6 +150,13 @@ export const ProcaptchaFrictionless = ({
 	const manualStartedRef = useRef(false);
 	// The placeholder is built before `start()` exists in this scope.
 	const manualCheckboxHandlerRef = useRef(noopCheckboxHandler);
+	// The inner widget only listens for `procaptcha:execute` once /frictionless
+	// has answered, its chunk has loaded and it has mounted. An execute() in
+	// that window (e.g. a fast form submit) would otherwise be dropped and the
+	// challenge never open, so it is held here and replayed on mount.
+	const innerWidgetRenderedRef = useRef(false);
+	const innerWidgetListeningRef = useRef(false);
+	const pendingExecuteRef = useRef(false);
 
 	useEffect(() => {
 		if (!config.language) return;
@@ -199,6 +207,7 @@ export const ProcaptchaFrictionless = ({
 				restartComponentTimeout();
 			}, 0);
 		}
+		innerWidgetRenderedRef.current = false;
 		setComponentToRender(
 			renderPlaceholder(
 				config.theme,
@@ -321,6 +330,7 @@ export const ProcaptchaFrictionless = ({
 		const startCoords = escalationCoords ?? retryStartCoords;
 		mountCountRef.current += 1;
 		const mountKey = mountCountRef.current;
+		innerWidgetRenderedRef.current = true;
 
 		if (captchaType === CaptchaType.authenticated) {
 			// Web Bot Auth pre-verified pass-through. No challenge, no
@@ -423,6 +433,14 @@ export const ProcaptchaFrictionless = ({
 
 				const guard = evaluateFrictionlessResult(result);
 				if (guard.kind === "error") {
+					// Throwing hands this to providerRetry, which re-rolls onto a
+					// different provider. The client does not throw on a 400 with a
+					// JSON body, so without this an unrecognised provider-side
+					// failure stranded the user on the first response even when
+					// every other node was healthy.
+					if (guard.retryable) {
+						throw new Error(guard.message);
+					}
 					stateRef.current = {
 						...stateRef.current,
 						loading: false,
@@ -461,6 +479,10 @@ export const ProcaptchaFrictionless = ({
 			5,
 		).finally(() => {
 			if (stateRef.current.attemptCount >= 5) {
+				// Retries swallow the underlying error, so without this a site's
+				// error callback never fires for a failure that retried — it would
+				// have fired immediately before retrying was introduced.
+				events.onError(new Error("Cannot load CAPTCHA"));
 				fallOverWithStyle();
 				restartComponentTimeout();
 			}
@@ -475,6 +497,7 @@ export const ProcaptchaFrictionless = ({
 		manualStartedRef.current = true;
 		pendingRetryCoordsRef.current = coords ?? null;
 		nextMountAutoStartRef.current = autoStart;
+		innerWidgetRenderedRef.current = false;
 		setComponentToRender(
 			renderPlaceholder(
 				config.theme,
@@ -520,6 +543,40 @@ export const ProcaptchaFrictionless = ({
 		};
 	}, [manualStart, container]);
 
+	// Mirrors the inner widgets' own listeners: a targeted execute() arrives on
+	// the container in either mode, a bare one on document in invisible mode.
+	// Manual start has its own listener above that defers the whole flow.
+	useEffect(() => {
+		if (manualStart) return;
+		const invisible = config.mode === ModeEnum.invisible;
+		const onExecuteEvent = () => {
+			if (!innerWidgetListeningRef.current) pendingExecuteRef.current = true;
+		};
+		container?.addEventListener(PROCAPTCHA_EXECUTE_EVENT, onExecuteEvent);
+		if (invisible) {
+			document.addEventListener(PROCAPTCHA_EXECUTE_EVENT, onExecuteEvent);
+		}
+		return () => {
+			container?.removeEventListener(PROCAPTCHA_EXECUTE_EVENT, onExecuteEvent);
+			if (invisible) {
+				document.removeEventListener(PROCAPTCHA_EXECUTE_EVENT, onExecuteEvent);
+			}
+		};
+	}, [manualStart, config.mode, container]);
+
+	// Child effects run before this one, so a newly mounted inner widget is
+	// already listening when the held execute() is replayed. It goes to the
+	// container, not document, so other widgets on the page don't run twice.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: intentional — must run after every commit that swaps the rendered widget.
+	useEffect(() => {
+		innerWidgetListeningRef.current = innerWidgetRenderedRef.current;
+		if (!innerWidgetListeningRef.current || !pendingExecuteRef.current) return;
+		pendingExecuteRef.current = false;
+		(container ?? document).dispatchEvent(
+			new CustomEvent(PROCAPTCHA_EXECUTE_EVENT),
+		);
+	}, [componentToRender, 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

package/src/frictionlessResultGuard.ts

@@ -14,7 +14,41 @@
 
 export type FrictionlessGuardOutcome =
 	| { kind: "pass" }
-	| { kind: "error"; message: string; key?: string };
+	| { kind: "error"; message: string; key?: string; retryable: boolean };
+
+/**
+ * Error keys that describe the caller's situation rather than the provider's
+ * health, so re-rolling onto another provider would return the same answer.
+ *
+ * Two groups. Integration faults (site key, origin, captcha type) need the
+ * site owner to change something and the text is what tells them what. Policy
+ * denials are a decision about this visitor that every provider shares —
+ * retrying them would both mislead the user and hammer the fleet on behalf of
+ * traffic we have just refused.
+ *
+ * Anything outside this list is treated as the provider failing, not the
+ * caller: see {@link evaluateFrictionlessResult}.
+ */
+const TERMINAL_ERROR_KEYS: ReadonlySet<string> = new Set([
+	"API.SITE_KEY_NOT_REGISTERED",
+	"API.INVALID_SITE_KEY",
+	"API.UNAUTHORIZED_ORIGIN_URL",
+	"API.INCORRECT_CAPTCHA_TYPE",
+	"API.ACCESS_POLICY_BLOCK",
+	"API.ABUSER_BLOCKED",
+	"API.CRAWLER_BLOCKED",
+	"API.DATACENTER_BLOCKED",
+	"API.DISALLOWED_WEBVIEW",
+	"API.MOBILE_BLOCKED",
+	"API.PROXY_BLOCKED",
+	"API.SATELLITE_BLOCKED",
+	"API.TOR_BLOCKED",
+	"API.VPN_BLOCKED",
+	"API.FORBIDDEN",
+	"API.UNAUTHORIZED",
+	// carries its own ten-second restart in ProcaptchaFrictionless
+	"CAPTCHA.NO_SESSION_FOUND",
+]);
 
 // Fields the guard reads off the `/frictionless` result. Kept minimal
 // (subset of BotDetectionFunctionResult) so the helper can be exercised
@@ -49,14 +83,26 @@ export const evaluateFrictionlessResult = (
 	result: FrictionlessGuardInput,
 ): FrictionlessGuardOutcome => {
 	if (result.error?.message) {
+		const key = result.error.key;
 		return {
 			kind: "error",
 			message: result.error.message,
-			...(result.error.key !== undefined && { key: result.error.key }),
+			...(key !== undefined && { key }),
+			// A key we do not recognise means the provider failed in a way it
+			// has no vocabulary for — API.BAD_REQUEST is what an unhandled throw
+			// inside a handler serialises to. That is worth trying another
+			// provider for. Retrying is gated on having a key at all: the
+			// bare-string errors handled below are hard blocks, and re-rolling
+			// those would hammer the fleet for traffic already refused.
+			retryable: key !== undefined && !TERMINAL_ERROR_KEYS.has(key),
 		};
 	}
 	if (!result.captchaType) {
-		return { kind: "error", message: MISSING_CAPTCHA_TYPE_MESSAGE };
+		return {
+			kind: "error",
+			message: MISSING_CAPTCHA_TYPE_MESSAGE,
+			retryable: false,
+		};
 	}
 	return { kind: "pass" };
 };