@verbb/formie-browser 1.0.0

package/src/js/modules/captchas/recaptcha-enterprise.ts

@@ -0,0 +1,138 @@
+import {
+    defineCaptchaModule,
+} from '#modules/captchas/api';
+import { CAPTCHA_EXECUTE_WAIT_FOR_VALUE_MS } from '#modules/captchas/constants';
+import {
+    loadRecaptchaGlobal,
+    type RecaptchaGlobal,
+    type RecaptchaProviderOptions,
+} from '#modules/captchas/recaptcha-shared';
+
+type RecaptchaEnterpriseProviderOptions = RecaptchaProviderOptions & {
+    enterpriseType?: string | null;
+    action?: string;
+};
+
+// Enterprise is intentionally still one module because Google ships these as
+// one SDK with three web-facing modes:
+// - checkbox: rendered widget, user solves before submit
+// - score: no visible widget, execute() returns a score token
+// - policy: execute() triggers the challenge/assessment flow for policy keys
+//
+// Shared captcha services should not know about any of those distinctions, so
+// this module owns the branching itself.
+export const recaptchaEnterpriseModule = defineCaptchaModule<RecaptchaEnterpriseProviderOptions, RecaptchaGlobal, number | string>({
+    id: 'recaptcha-enterprise',
+    defaultPlaceholderSelector: '[data-recaptcha-placeholder]',
+    defaultTokenFieldNames: ['g-recaptcha-response'],
+    load: ({ options }) => {
+        // Score/policy keys use the site-key `render=` script mode, while
+        // checkbox still behaves like an explicit widget render.
+        return loadRecaptchaGlobal(
+            options.provider,
+            true,
+            options.provider.enterpriseType === 'score' || options.provider.enterpriseType === 'policy' ? (options.provider.siteKey || undefined) : undefined,
+        );
+    },
+    mount: ({ api, container, provider, services }) => {
+        const enterpriseApi = api.enterprise || api;
+
+        return new Promise((resolve) => {
+            enterpriseApi.ready(() => {
+                if (provider.enterpriseType !== 'checkbox') {
+                    // Score and policy modes do not produce a widget id. As
+                    // with reCAPTCHA v3, we keep the site key as the managed
+                    // instance value so the provider still fits the generic
+                    // managed-captcha lifecycle.
+                    resolve(provider.siteKey || `recaptcha-enterprise-${provider.enterpriseType || 'score'}`);
+                    return;
+                }
+
+                // Checkbox mode is a true rendered widget and therefore follows
+                // the more traditional render/callback/reset lifecycle.
+                resolve(enterpriseApi.render(container, {
+                    sitekey: provider.siteKey || '',
+                    theme: provider.theme || 'light',
+                    badge: provider.badge || 'bottomright',
+                    size: provider.size || 'normal',
+                    action: provider.action || 'submit',
+                    callback: (token?: string) => {
+                        if (typeof token === 'string' && token.trim() !== '') {
+                            services.tokens.write(token.trim());
+                        }
+
+                        services.errors.clear();
+                    },
+                    'expired-callback': () => {
+                        services.tokens.clear();
+                        services.errors.clear();
+                    },
+                    'error-callback': () => {
+                        services.tokens.clear();
+                    },
+                }));
+            });
+        });
+    },
+    screen: async({ api, widget, provider, placeholder, services, stageCtx }) => {
+        const enterpriseApi = api.enterprise || api;
+
+        if (provider.enterpriseType === 'checkbox') {
+            // Checkbox mode behaves like reCAPTCHA v2 checkbox: by submit time
+            // we only verify that the user has already solved the widget.
+            if (services.tokens.has()) {
+                return;
+            }
+
+            const message = services.errors.getDefaultMessage();
+            services.errors.show(message, placeholder);
+            stageCtx.abort(message);
+            return;
+        }
+
+        if (services.tokens.has()) {
+            return;
+        }
+
+        if (provider.enterpriseType === 'score' || provider.enterpriseType === 'policy') {
+            // Score and policy-based keys execute by site key and can resolve
+            // directly to a token. We write that token into the shared transport
+            // layer so the backend can validate it in the usual way.
+            const token = await enterpriseApi.execute(provider.siteKey || '', { action: provider.action || 'submit' });
+
+            if (typeof token === 'string' && token.trim() !== '') {
+                services.tokens.write(token.trim());
+            }
+        } else {
+            // Fallback branch for any future Enterprise widget-like mode.
+            enterpriseApi.execute(widget);
+        }
+
+        const hasToken = await services.tokens.wait(CAPTCHA_EXECUTE_WAIT_FOR_VALUE_MS);
+
+        if (!hasToken) {
+            const message = services.errors.getDefaultMessage();
+            services.errors.show(message, placeholder);
+            stageCtx.abort(message);
+        }
+    },
+    reset: ({ api, widget, provider, services }) => {
+        const enterpriseApi = api.enterprise || api;
+
+        if (provider.enterpriseType === 'checkbox') {
+            // Only checkbox mode has a long-lived rendered widget to reset.
+            enterpriseApi.reset(widget);
+        }
+
+        services.tokens.clear();
+    },
+    unmount: ({ api, widget, provider, services }) => {
+        const enterpriseApi = api.enterprise || api;
+
+        if (provider.enterpriseType === 'checkbox') {
+            enterpriseApi.reset(widget);
+        }
+
+        services.tokens.clear();
+    },
+});

package/src/js/modules/captchas/recaptcha-shared.ts

@@ -0,0 +1,69 @@
+import { loadScriptAndEnsureGlobal } from '#utils/scripts';
+import { CAPTCHA_PROVIDER_LOAD_TIMEOUT_MS } from '#modules/captchas/constants';
+import { getScriptAttributes } from '#modules/captchas/utils';
+
+// reCAPTCHA is the one place where a provider-local "shared" file still earns
+// its keep: v2 checkbox, v2 invisible, v3, and Enterprise all rely on the same
+// Google global and script-loading rules, but use different module lifecycles.
+export type RecaptchaGlobal = {
+    ready: (callback: () => void) => void;
+    render: (container: HTMLElement, options: Record<string, unknown>) => number | string;
+    execute: (widgetIdOrSiteKey?: number | string, options?: Record<string, unknown>) => Promise<string> | void;
+    getResponse?: (widgetId?: number | string) => string;
+    reset: (widgetId?: number | string) => void;
+    enterprise?: {
+        ready: (callback: () => void) => void;
+        render: (container: HTMLElement, options: Record<string, unknown>) => number | string;
+        execute: (widgetIdOrSiteKey?: number | string, options?: Record<string, unknown>) => Promise<string> | void;
+        getResponse?: (widgetId?: number | string) => string;
+        reset: (widgetId?: number | string) => void;
+    };
+};
+
+export type RecaptchaProviderOptions = {
+    siteKey?: string | null;
+    badge?: string;
+    theme?: string;
+    size?: string;
+    language?: string;
+    loadingMethod?: string;
+    action?: string;
+    enterpriseType?: string | null;
+};
+
+export async function loadRecaptchaGlobal(
+    options: RecaptchaProviderOptions,
+    enterprise = false,
+    renderValue?: string,
+): Promise<RecaptchaGlobal> {
+    // Google reCAPTCHA has two loading styles:
+    // - `render=explicit` for widget-based modes where the module later calls
+    //   `grecaptcha.render(container, ...)`
+    // - `render=<siteKey>` for execute-by-site-key modes such as v3 and some
+    //   Enterprise flows
+    //
+    // That distinction matters across multiple reCAPTCHA modules, which is why
+    // this helper is worth sharing even though singular providers were inlined.
+    const language = typeof options.language === 'string' && options.language.trim() !== '' ? options.language.trim() : 'en';
+    const { async, defer } = getScriptAttributes(options.loadingMethod);
+    const host = enterprise ? 'https://www.google.com/recaptcha/enterprise.js' : 'https://www.recaptcha.net/recaptcha/api.js';
+    const render = typeof renderValue === 'string' && renderValue.trim() !== '' ? renderValue.trim() : 'explicit';
+    const src = new URL(host);
+
+    src.searchParams.set('render', render);
+    src.searchParams.set('hl', language);
+
+    // Badge placement is configured on the script URL for the execute-by-site-
+    // key flows because there is no later widget render call to carry it.
+    if (render !== 'explicit' && typeof options.badge === 'string' && options.badge.trim() !== '') {
+        src.searchParams.set('badge', options.badge.trim());
+    }
+
+    return loadScriptAndEnsureGlobal<RecaptchaGlobal>('grecaptcha', {
+        id: enterprise ? 'FORMIE_RECAPTCHA_ENTERPRISE_SCRIPT' : 'FORMIE_RECAPTCHA_SCRIPT',
+        src: src.toString(),
+        async,
+        defer,
+        timeoutMs: CAPTCHA_PROVIDER_LOAD_TIMEOUT_MS,
+    });
+}

package/src/js/modules/captchas/recaptcha-v2-checkbox.ts

@@ -0,0 +1,72 @@
+import {
+    defineCaptchaModule,
+} from '#modules/captchas/api';
+import {
+    loadRecaptchaGlobal,
+    type RecaptchaGlobal,
+    type RecaptchaProviderOptions,
+} from '#modules/captchas/recaptcha-shared';
+
+// This is the classic checkbox widget. The important distinction from the
+// invisible/score flows is that we never trigger execution ourselves; the user
+// must solve the already-rendered widget before submit succeeds.
+export const recaptchaV2CheckboxModule = defineCaptchaModule<RecaptchaProviderOptions, RecaptchaGlobal, number | string>({
+    id: 'recaptcha-v2-checkbox',
+    defaultPlaceholderSelector: '[data-recaptcha-placeholder]',
+    defaultTokenFieldNames: ['g-recaptcha-response'],
+    load: ({ options }) => {
+        return loadRecaptchaGlobal(options.provider);
+    },
+    mount: ({ api, container, provider, services }) => {
+        return new Promise((resolve) => {
+            api.ready(() => {
+                // For checkbox mode the Google SDK gives us a widget id, which
+                // later becomes important for reset/unmount.
+                resolve(api.render(container, {
+                    sitekey: provider.siteKey || '',
+                    theme: provider.theme || 'light',
+                    size: provider.size || 'normal',
+                    callback: (token?: string) => {
+                        // Checkbox mode solves interactively before submit, so
+                        // the callback is the point where the transport layer
+                        // finally becomes "screen-stage ready".
+                        if (typeof token === 'string' && token.trim() !== '') {
+                            services.tokens.write(token.trim());
+                        }
+
+                        services.errors.clear();
+                    },
+                    'expired-callback': () => {
+                        services.tokens.clear();
+                        services.errors.clear();
+                    },
+                    'error-callback': () => {
+                        services.tokens.clear();
+                    },
+                }));
+            });
+        });
+    },
+    screen: ({ placeholder, services, stageCtx }) => {
+        // Checkbox mode does not execute at submit time. We simply check if the
+        // user already solved it; if not, abort immediately with a field-style
+        // error and let the user interact with the widget.
+        if (services.tokens.has()) {
+            return;
+        }
+
+        const message = services.errors.getDefaultMessage();
+        services.errors.show(message, placeholder);
+        stageCtx.abort(message);
+    },
+    reset: ({ api, widget, services }) => {
+        // A successful AJAX submit or form reset should leave the checkbox
+        // rendered but unsolved, so `reset()` is the right provider behavior.
+        api.reset(widget);
+        services.tokens.clear();
+    },
+    unmount: ({ api, widget, services }) => {
+        api.reset(widget);
+        services.tokens.clear();
+    },
+});

package/src/js/modules/captchas/recaptcha-v2-invisible.ts

@@ -0,0 +1,108 @@
+import {
+    defineCaptchaModule,
+} from '#modules/captchas/api';
+import { CAPTCHA_EXECUTE_WAIT_FOR_VALUE_MS } from '#modules/captchas/constants';
+import {
+    loadRecaptchaGlobal,
+    type RecaptchaGlobal,
+    type RecaptchaProviderOptions,
+} from '#modules/captchas/recaptcha-shared';
+
+type RecaptchaWidgetState = {
+    id: number | string;
+};
+
+async function waitForRecaptchaResponse(api: RecaptchaGlobal, widgetId: number | string, timeoutMs = 1000): Promise<string | undefined> {
+    // Invisible reCAPTCHA does not always synchronously pass the final token
+    // through the callback at the exact moment we need it. Polling `getResponse`
+    // gives us a provider-local fallback without leaking Google-specific logic
+    // into shared captcha services.
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() < deadline) {
+        const response = typeof api.getResponse === 'function' ? api.getResponse(widgetId) : '';
+
+        if (typeof response === 'string' && response.trim() !== '') {
+            return response.trim();
+        }
+
+        await new Promise((resolve) => {
+            window.setTimeout(resolve, 100);
+        });
+    }
+
+    return undefined;
+}
+
+export const recaptchaV2InvisibleModule = defineCaptchaModule<RecaptchaProviderOptions, RecaptchaGlobal, RecaptchaWidgetState>({
+    id: 'recaptcha-v2-invisible',
+    defaultPlaceholderSelector: '[data-recaptcha-placeholder]',
+    defaultTokenFieldNames: ['g-recaptcha-response'],
+    load: ({ options }) => {
+        return loadRecaptchaGlobal(options.provider);
+    },
+    mount: ({ api, container, provider, services }) => {
+        return new Promise((resolve) => {
+            api.ready(() => {
+                const widgetId = api.render(container, {
+                    sitekey: provider.siteKey || '',
+                    badge: provider.badge || 'bottomright',
+                    size: 'invisible',
+                    callback: (token?: string) => {
+                        // Google sometimes passes the token directly and other
+                        // times expects consumers to read it back from the
+                        // widget response API. Normalize both paths here.
+                        const response = typeof token === 'string' && token.trim() !== ''
+                            ? token.trim()
+                            : (typeof api.getResponse === 'function' ? api.getResponse(widgetId) : '');
+
+                        if (response) {
+                            services.tokens.write(response);
+                        }
+
+                        services.errors.clear();
+                    },
+                    'expired-callback': () => {
+                        services.tokens.clear();
+                        services.errors.clear();
+                    },
+                    'error-callback': () => {
+                        services.tokens.clear();
+                    },
+                });
+
+                resolve({
+                    // Keep the widget id in a tiny object so later lifecycle
+                    // methods have a stable shape to work with.
+                    id: widgetId,
+                });
+            });
+        });
+    },
+    screen: async({ api, widget, placeholder, services, stageCtx }) => {
+        // If we already have a token, do not re-execute the invisible widget.
+        if (services.tokens.has()) {
+            return;
+        }
+
+        // Invisible mode needs an explicit submit-time execute call.
+        api.execute(widget.id);
+        const token = await waitForRecaptchaResponse(api, widget.id);
+
+        if (typeof token === 'string' && token.trim() !== '') {
+            services.tokens.write(token.trim());
+        }
+
+        const hasToken = await services.tokens.wait(CAPTCHA_EXECUTE_WAIT_FOR_VALUE_MS);
+
+        if (!hasToken) {
+            const message = services.errors.getDefaultMessage();
+            services.errors.show(message, placeholder);
+            stageCtx.abort(message);
+        }
+    },
+    unmount: ({ api, widget, services }) => {
+        api.reset(widget.id);
+        services.tokens.clear();
+    },
+});

package/src/js/modules/captchas/recaptcha-v3.ts

@@ -0,0 +1,62 @@
+import {
+    defineCaptchaModule,
+} from '#modules/captchas/api';
+import { CAPTCHA_EXECUTE_WAIT_FOR_VALUE_MS } from '#modules/captchas/constants';
+import {
+    loadRecaptchaGlobal,
+    type RecaptchaGlobal,
+    type RecaptchaProviderOptions,
+} from '#modules/captchas/recaptcha-shared';
+
+// reCAPTCHA v3 is the "no visible widget" score flow. We still mount a module
+// instance so it can participate in the same submit lifecycle as other
+// providers, but most of the work happens at screen time.
+export const recaptchaV3Module = defineCaptchaModule<RecaptchaProviderOptions, RecaptchaGlobal, number | string>({
+    id: 'recaptcha-v3',
+    defaultPlaceholderSelector: '[data-recaptcha-placeholder]',
+    defaultTokenFieldNames: ['g-recaptcha-response'],
+    load: ({ options }) => {
+        // Score-based flows use a site-key `render=` mode instead of an
+        // explicit widget render, so the loader needs the site key up front.
+        return loadRecaptchaGlobal(options.provider, false, options.provider.siteKey || undefined);
+    },
+    mount: ({ api, provider }) => {
+        return new Promise((resolve) => {
+            api.ready(() => {
+                // There is no real widget id for v3. We store the site key as
+                // the "widget" value purely so the managed factory can treat
+                // this provider like every other captcha module instance.
+                resolve(provider.siteKey || 'recaptcha-v3');
+            });
+        });
+    },
+    screen: async({ api, provider, placeholder, services, stageCtx }) => {
+        // If a token already exists we can skip execution, which matters for
+        // re-renders or multi-step flows where the same challenge was already
+        // completed very recently.
+        if (services.tokens.has()) {
+            return;
+        }
+
+        // v3 returns its token directly from `execute()`, unlike widget-based
+        // captchas that signal completion later via callbacks.
+        const token = await api.execute(provider.siteKey || '', { action: provider.action || 'submit' });
+
+        if (typeof token === 'string' && token.trim() !== '') {
+            services.tokens.write(token.trim());
+        }
+
+        // We still wait on the shared token layer so the module follows the
+        // same transport contract as every other captcha provider.
+        const hasToken = await services.tokens.wait(CAPTCHA_EXECUTE_WAIT_FOR_VALUE_MS);
+
+        if (!hasToken) {
+            const message = services.errors.getDefaultMessage();
+            services.errors.show(message, placeholder);
+            stageCtx.abort(message);
+        }
+    },
+    unmount: ({ services }) => {
+        services.tokens.clear();
+    },
+});

package/src/js/modules/captchas/snaptcha.ts

@@ -0,0 +1,10 @@
+import { definePassiveCaptchaModule } from '#modules/captchas/api';
+
+// Snaptcha is the remaining "passive" captcha style: there is no browser SDK
+// to load and no user-facing widget to render. The shared passive factory is a
+// good fit here because the provider is really just about keeping a hidden
+// transport value in sync across renders and token refreshes.
+export const snaptchaModule = definePassiveCaptchaModule({
+    id: 'snaptcha',
+    defaultPlaceholderSelector: '[data-snaptcha-captcha-placeholder]',
+});

package/src/js/modules/captchas/turnstile.ts

@@ -0,0 +1,131 @@
+import {
+    defineCaptchaModule,
+} from '#modules/captchas/api';
+import {
+    CAPTCHA_EXECUTE_WAIT_FOR_VALUE_MS,
+    CAPTCHA_PROVIDER_LOAD_TIMEOUT_MS,
+    CAPTCHA_SUBMIT_WAIT_FOR_VALUE_MS,
+} from '#modules/captchas/constants';
+import { loadScriptAndEnsureGlobal } from '#utils/scripts';
+import { getScriptAttributes } from '#modules/captchas/utils';
+
+// Narrow local contract for the Cloudflare Turnstile browser SDK.
+type TurnstileGlobal = {
+    render: (container: HTMLElement, options: Record<string, unknown>) => string;
+    execute: (widgetId: string) => void;
+    reset: (widgetId: string) => void;
+};
+
+// Provider-specific options only. Generic captcha concerns are handled by the
+// shared captcha services/factory layer.
+type TurnstileProviderOptions = {
+    siteKey?: string | null;
+    theme?: string;
+    size?: string;
+    appearance?: string;
+    execution?: string;
+    loadingMethod?: string;
+};
+
+function getTurnstileWaitForValueMs(provider: TurnstileProviderOptions): number {
+    const appearance = provider.appearance || 'always';
+    const execution = provider.execution || (appearance === 'execute' ? 'execute' : 'render');
+
+    return execution === 'execute' ? CAPTCHA_EXECUTE_WAIT_FOR_VALUE_MS : CAPTCHA_SUBMIT_WAIT_FOR_VALUE_MS;
+}
+
+async function loadTurnstileGlobal(options: TurnstileProviderOptions): Promise<TurnstileGlobal> {
+    // Turnstile is simpler than hCaptcha/reCAPTCHA: once the script has loaded,
+    // the global is ready to use immediately. This helper stays local because
+    // the URL and readiness assumptions are specific to Turnstile.
+    const { async, defer } = getScriptAttributes(options.loadingMethod);
+
+    return loadScriptAndEnsureGlobal<TurnstileGlobal>('turnstile', {
+        id: 'FORMIE_TURNSTILE_SCRIPT',
+        src: 'https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit',
+        async,
+        defer,
+        timeoutMs: CAPTCHA_PROVIDER_LOAD_TIMEOUT_MS,
+    });
+}
+
+export const turnstileModule = defineCaptchaModule<TurnstileProviderOptions, TurnstileGlobal, string>({
+    id: 'turnstile',
+    defaultPlaceholderSelector: '[data-turnstile-placeholder]',
+    defaultTokenFieldNames: ['cf-turnstile-response'],
+    load: ({ options }) => {
+        // Load once, then let the managed captcha factory share the resolved
+        // SDK across any remount/reset work for this form.
+        return loadTurnstileGlobal(options.provider);
+    },
+    mount: ({ api, container, provider, services }) => {
+        // Turnstile has two related concepts:
+        // - `appearance`: when/if the widget should visibly appear
+        // - `execution`: whether the challenge runs automatically or only when
+        //   we explicitly call `turnstile.execute(widget)` during submit
+        //
+        // We normalize that relationship here because it is a provider concern,
+        // not something the shared captcha module should need to understand.
+        const appearance = provider.appearance || 'always';
+        const execution = provider.execution || (appearance === 'execute' ? 'execute' : 'render');
+
+        return api.render(container, {
+            sitekey: provider.siteKey || '',
+            theme: provider.theme || 'auto',
+            size: provider.size || 'normal',
+            appearance,
+            execution,
+            callback: (token?: string) => {
+                // Turnstile verification completed successfully, so copy its
+                // token into the shared transport inputs for backend submit.
+                if (typeof token === 'string' && token.trim() !== '') {
+                    services.tokens.write(token.trim());
+                }
+
+                services.errors.clear();
+            },
+            'expired-callback': () => {
+                // Expired tokens must be removed immediately so a later submit
+                // cannot reuse something Turnstile no longer accepts.
+                services.tokens.clear();
+                services.errors.clear();
+            },
+            'timeout-callback': () => {
+                // Treat timeouts like expiry: the challenge must be solved again.
+                services.tokens.clear();
+                services.errors.clear();
+            },
+            'error-callback': () => {
+                // Provider-side failures should not leave stale transport state.
+                services.tokens.clear();
+            },
+        });
+    },
+    screen: ({ api, widget, placeholder, services, provider, stageCtx }) => {
+        // Submit-time rule: if a valid token already exists, do nothing. This
+        // covers cases where Turnstile solved itself on load or before submit.
+        if (services.tokens.has()) {
+            return;
+        }
+
+        // Otherwise explicitly ask Turnstile to run now. This is what supports
+        // "run on submit" style configurations without the shared module
+        // needing any Turnstile-specific policy logic.
+        api.execute(widget);
+        return services.tokens.wait(getTurnstileWaitForValueMs(provider)).then((hasToken) => {
+            if (!hasToken) {
+                // No token arrived in time, so block the screen stage and show
+                // the shared themed inline error next to the active placeholder.
+                const message = services.errors.getDefaultMessage();
+                services.errors.show(message, placeholder);
+                stageCtx.abort(message);
+            }
+        });
+    },
+    unmount: ({ api, widget, services }) => {
+        // Reset provider state whenever the widget is torn down so the DOM
+        // transport layer and the provider widget stay in sync.
+        api.reset(widget);
+        services.tokens.clear();
+    },
+});

package/src/js/modules/captchas/utils.ts

@@ -0,0 +1,85 @@
+import { sleep } from '#utils/async';
+
+export function getScriptAttributes(loadingMethod?: string): { async: boolean; defer: boolean } {
+    const normalized = String(loadingMethod || 'asyncDefer').toLowerCase();
+
+    return {
+        async: normalized.includes('async'),
+        defer: normalized.includes('defer'),
+    };
+}
+
+export function getInputValue(root: ParentNode, name: string): string {
+    const inputs = Array.from(root.querySelectorAll(`input[name="${name}"], textarea[name="${name}"]`)) as Array<HTMLInputElement | HTMLTextAreaElement>;
+
+    for (const input of inputs) {
+        const value = String(input.value || '').trim();
+
+        if (value !== '') {
+            return value;
+        }
+    }
+
+    return '';
+}
+
+export function hasCaptchaValue(root: ParentNode, names: string[]): boolean {
+    return names.some((name) => {
+        return getInputValue(root, name) !== '';
+    });
+}
+
+export function clearCaptchaValues(root: ParentNode, names: string[]): void {
+    names.forEach((name) => {
+        const inputs = Array.from(root.querySelectorAll(`input[name="${name}"], textarea[name="${name}"]`)) as Array<HTMLInputElement | HTMLTextAreaElement>;
+
+        inputs.forEach((input) => {
+            input.value = '';
+        });
+    });
+}
+
+export function ensureCaptchaValueInput(
+    root: ParentNode,
+    name: string,
+    {
+        value = '',
+        container,
+    }: {
+        value?: string;
+        container?: HTMLElement | null;
+    } = {},
+): HTMLInputElement {
+    let input = root.querySelector(`input[name="${name}"]`) as HTMLInputElement | null;
+
+    if (!input) {
+        input = document.createElement('input');
+        input.type = 'hidden';
+        input.name = name;
+
+        const target = container || (root instanceof HTMLElement ? root : null);
+        target?.appendChild(input);
+    }
+
+    input.value = value;
+
+    return input;
+}
+
+export async function waitForCaptchaValue(root: ParentNode, names: string[], waitForValueMs: number): Promise<boolean> {
+    if (hasCaptchaValue(root, names)) {
+        return true;
+    }
+
+    const deadline = Date.now() + Math.max(waitForValueMs, 0);
+
+    while (Date.now() < deadline) {
+        await sleep(120);
+
+        if (hasCaptchaValue(root, names)) {
+            return true;
+        }
+    }
+
+    return false;
+}