@owlmeans/web-captcha 0.0.0-stage → 0.1.19-rc.0

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# @owlmeans/web-captcha
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The browser half of OwlMeans captcha: a loader for Google's invisible, score-based reCAPTCHA v3 and
+a React hook over it. It has no `@owlmeans/*` dependencies, so a size-sensitive bundle (an embedded
+widget) can carry it alone. The server half — verifying the token — is `@owlmeans/captcha`.
+
+## Installation
+
+```bash
+bun add @owlmeans/web-captcha@^0.1.19-rc.0
+```
+
+## Concepts
+
+- **Lazy** — nothing touches the page at import. The script `api.js?render=<site key>` is injected
+  on the first `prepare` or `token` call, so the module is safe under server rendering and in tests;
+  without a page a call fails with `CaptchaLoadError('unavailable')`.
+- **One script per site key** — concurrent and later calls share one load per loader; use the shared
+  `captchaLoader` so every form of a page shares it too. A failed load is forgotten, so the next call
+  injects the script again.
+- **Badge** — by default the loader adds one document style hiding Google's badge. A page that hides
+  it must show Google's notice ("This site is protected by reCAPTCHA and the Google Privacy Policy
+  and Terms of Service apply.") next to the form.
+- **Failures** — every failure is a `CaptchaLoadError` whose `reason` is `load` (the script did not
+  load), `timeout` (not ready within `loadTimeout`, 15 s), `unavailable` (no page, or the script
+  came without its API) or `execute` (no token within `executeTimeout`, 20 s).
+
+## Usage
+
+```typescript
+import { captchaLoader } from '@owlmeans/web-captcha'
+
+void captchaLoader.prepare(siteKey)                          // e.g. when the form opens
+const token = await captchaLoader.token(siteKey, 'email_pin') // per submit; send it to the server
+```
+
+```tsx
+import { useCaptcha } from '@owlmeans/web-captcha/react'
+
+const { ready, error, execute } = useCaptcha({ siteKey: options.captcha?.siteKey ?? null, action: 'email_pin' })
+
+const submit = async () => {
+  const captcha = await execute()          // null while the captcha is off
+  await api.sendPin({ email, ...(captcha != null ? { captcha } : {}) })
+}
+```
+
+## API
+
+| Export | Description |
+|---|---|
+| `createCaptchaLoader(options?)` | A `CaptchaLoader`: `prepare(siteKey)`, `token(siteKey, action)` |
+| `captchaLoader` | The shared ready instance |
+| `CaptchaLoadError` | `Error` with `reason: 'load' \| 'timeout' \| 'execute' \| 'unavailable'` |
+| `RECAPTCHA_SCRIPT_URL`, `CAPTCHA_LOAD_TIMEOUT`, `CAPTCHA_EXECUTE_TIMEOUT` | Google's script, `15_000`, `20_000` |
+| `CAPTCHA_SCRIPT_ATTRIBUTE`, `CAPTCHA_STYLE_ATTRIBUTE`, `CAPTCHA_BADGE_CSS` | What the loader marks and injects |
+| `CaptchaLoader`, `CaptchaLoaderOptions`, `CaptchaLoadErrorReason`, `Grecaptcha`, `CaptchaWindow`, `CaptchaDocument` | Types |
+| `useCaptcha({ siteKey, action, loader? })` (`./react`) | `{ ready, error, execute }`; `siteKey` `null` = off: `ready` true, `execute()` resolves `null` |
+| `UseCaptchaOptions`, `UseCaptchaResult` (`./react`) | The hook's types |
+
+`CaptchaLoaderOptions`: `hideBadge` (default `true`), `loadTimeout`, `executeTimeout`, `scriptUrl`,
+and `document` / `window` to load into another page (or a test's stand-in) instead of the globals.
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded agent skills under `agent-meta/`. After installing your
+`@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
+your project's skill store (`.agents/skills/`):
+
+```sh
+npx @owlmeans/agent-skills@^0.1.19-rc.0
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 3,
+  "package": "@owlmeans/web-captcha",
+  "version": "0.1.19-rc.0",
+  "generatedAt": "2026-11-01T17:08:08.485Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "web-captcha",
+      "category": "package-specific",
+      "file": "skills/web-captcha/SKILL.md",
+      "canonicalPath": ".agents/skills/web-captcha/SKILL.md"
+    }
+  ]
+}

package/agent-meta/skills/web-captcha/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: web-captcha
+description: How to use @owlmeans/web-captcha — the browser half of OwlMeans captcha, with no @owlmeans dependencies. The lazy reCAPTCHA v3 loader (createCaptchaLoader, the shared captchaLoader — one script per site key, the badge hidden, a failed load forgotten), CaptchaLoadError and its four reasons, and the useCaptcha React hook (./react) that answers null while the captcha is off. Auto-invoked when a form or an embedded widget needs a reCAPTCHA v3 token, when importing captchaLoader or useCaptcha, or when phrasing a captcha load failure.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/web-captcha
+
+**Layer:** Web (L0 — no `@owlmeans/*` dependencies; React an optional peer, used only by `./react`)
+**Install:** `"@owlmeans/web-captcha": "^0.1.19-rc.0"` in `dependencies`
+**Server half:** `@owlmeans/captcha` (`makeCaptchaCheck` verifies what this produces)
+
+Zero framework dependencies is deliberate: a size-sensitive bundle — an embedded IIFE widget that
+must not pull ajv in through an `@owlmeans` package index — can carry it alone.
+
+## Key Exports
+
+| Export | Description |
+|---|---|
+| `createCaptchaLoader(options?)` | A `CaptchaLoader`: `prepare(siteKey)`, `token(siteKey, action)` |
+| `captchaLoader` | The shared ready instance — use it so every form of a page shares one script |
+| `CaptchaLoadError` | `Error` with `reason: 'load' \| 'timeout' \| 'execute' \| 'unavailable'` |
+| `RECAPTCHA_SCRIPT_URL`, `CAPTCHA_LOAD_TIMEOUT`, `CAPTCHA_EXECUTE_TIMEOUT` | Google's `api.js`, `15_000`, `20_000` |
+| `CAPTCHA_SCRIPT_ATTRIBUTE`, `CAPTCHA_STYLE_ATTRIBUTE`, `CAPTCHA_BADGE_CSS` | `data-owlmeans-captcha`, `data-owlmeans-captcha-style`, `.grecaptcha-badge{visibility:hidden}` |
+| `useCaptcha({ siteKey, action, loader? })` (`./react`) | `{ ready, error, execute }` |
+| `CaptchaLoaderOptions` | `hideBadge` (default `true`), `loadTimeout`, `executeTimeout`, `scriptUrl`, `document` / `window` (load into another page or a test stand-in) |
+
+## Behaviour
+
+- **Lazy.** Nothing touches the page at import: `api.js?render=<site key>` is injected on the first
+  `prepare` or `token`. Safe under server rendering and in tests; without a page a call fails with
+  `CaptchaLoadError('unavailable')`.
+- **One script per site key per loader**; concurrent calls share the load. A failed load is
+  forgotten, so the next call injects the script again.
+- **Badge.** The loader adds one document rule hiding Google's badge. A page that hides it must show
+  Google's notice next to the form ("This site is protected by reCAPTCHA and the Google Privacy
+  Policy and Terms of Service apply.", both linked).
+- **Failures** — `load` (script did not load), `timeout` (not ready within 15 s), `unavailable` (no
+  page, or the script came without its API), `execute` (no token within 20 s). A caller maps the
+  reason to its own sentence: `load`/`timeout`/`unavailable` read as "blocked" (an extension or a
+  network blocks Google), `execute` as "verification failed".
+
+## Usage
+
+```typescript
+import { captchaLoader } from '@owlmeans/web-captcha'
+
+void captchaLoader.prepare(siteKey)                           // when the form opens
+const token = await captchaLoader.token(siteKey, 'inquiry')   // per submit — never reuse a token
+```
+
+```tsx
+import { useCaptcha } from '@owlmeans/web-captcha/react'
+
+const { ready, error, execute } = useCaptcha({ siteKey: options.captcha?.siteKey ?? null, action: 'email_pin' })
+
+const submit = async () => {
+  const captcha = await execute()      // null while the captcha is off; throws CaptchaLoadError
+  await api.sendPin({ email, ...(captcha != null ? { captcha } : {}) })
+}
+```
+
+## Rules
+
+- `siteKey` `null` or `''` means OFF: `ready` is true at once and `execute()` resolves `null` — send
+  no captcha field at all rather than an empty one.
+- Fetch a fresh token for every protected request: a token is verifiable once, within two minutes,
+  and is bound to the action it was executed for — the server's strict check compares it exactly.
+- Load the script on the user's first interaction with the form (`prepare` on open), not with the
+  page: Google's script is a third-party request the cookie notice may not yet cover.
+
+## External docs
+
+- https://developers.google.com/recaptcha/docs/v3 — `api.js?render=<site key>`, `grecaptcha.ready` then `execute(siteKey, { action })` per protected action
+
+## Related
+
+`captcha` (the server half) · `web-auth-email` (the e-mail card's send-PIN and password sign-in) ·
+`common-inquiry` / `web-inquiry` (the inquiry widget a CRM serves loads reCAPTCHA through this package)

package/build/consts.d.ts

@@ -0,0 +1,16 @@
+/** Google's reCAPTCHA v3 script; `?render=<site key>` selects the invisible, score-based widget. */
+export declare const RECAPTCHA_SCRIPT_URL = "https://www.google.com/recaptcha/api.js";
+/** Marks the script the loader injected; its value is the site key. */
+export declare const CAPTCHA_SCRIPT_ATTRIBUTE = "data-owlmeans-captcha";
+/** Marks the document style that hides Google's badge. */
+export declare const CAPTCHA_STYLE_ATTRIBUTE = "data-owlmeans-captcha-style";
+/**
+ * The one document-level rule the loader adds unless told not to: Google's badge hidden. A page
+ * that hides it must show Google's notice ("This site is protected by reCAPTCHA…") itself.
+ */
+export declare const CAPTCHA_BADGE_CSS = ".grecaptcha-badge{visibility:hidden}";
+/** How long the script may take to become ready, in milliseconds. */
+export declare const CAPTCHA_LOAD_TIMEOUT = 15000;
+/** How long one `execute` may take, in milliseconds. */
+export declare const CAPTCHA_EXECUTE_TIMEOUT = 20000;
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,eAAO,MAAM,oBAAoB,4CAA4C,CAAA;AAE7E,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,0BAA0B,CAAA;AAE/D,0DAA0D;AAC1D,eAAO,MAAM,uBAAuB,gCAAgC,CAAA;AAEpE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,yCAAyC,CAAA;AAEvE,qEAAqE;AACrE,eAAO,MAAM,oBAAoB,QAAS,CAAA;AAE1C,wDAAwD;AACxD,eAAO,MAAM,uBAAuB,QAAS,CAAA"}

package/build/consts.js

@@ -0,0 +1,16 @@
+/** Google's reCAPTCHA v3 script; `?render=<site key>` selects the invisible, score-based widget. */
+export const RECAPTCHA_SCRIPT_URL = 'https://www.google.com/recaptcha/api.js';
+/** Marks the script the loader injected; its value is the site key. */
+export const CAPTCHA_SCRIPT_ATTRIBUTE = 'data-owlmeans-captcha';
+/** Marks the document style that hides Google's badge. */
+export const CAPTCHA_STYLE_ATTRIBUTE = 'data-owlmeans-captcha-style';
+/**
+ * The one document-level rule the loader adds unless told not to: Google's badge hidden. A page
+ * that hides it must show Google's notice ("This site is protected by reCAPTCHA…") itself.
+ */
+export const CAPTCHA_BADGE_CSS = '.grecaptcha-badge{visibility:hidden}';
+/** How long the script may take to become ready, in milliseconds. */
+export const CAPTCHA_LOAD_TIMEOUT = 15_000;
+/** How long one `execute` may take, in milliseconds. */
+export const CAPTCHA_EXECUTE_TIMEOUT = 20_000;
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,MAAM,CAAC,MAAM,oBAAoB,GAAG,yCAAyC,CAAA;AAE7E,uEAAuE;AACvE,MAAM,CAAC,MAAM,wBAAwB,GAAG,uBAAuB,CAAA;AAE/D,0DAA0D;AAC1D,MAAM,CAAC,MAAM,uBAAuB,GAAG,6BAA6B,CAAA;AAEpE;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,sCAAsC,CAAA;AAEvE,qEAAqE;AACrE,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAA;AAE1C,wDAAwD;AACxD,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAA"}

package/build/errors.d.ts

@@ -0,0 +1,7 @@
+import type { CaptchaLoadErrorReason } from './types.js';
+/** The captcha could not give a token; `reason` says which step failed. */
+export declare class CaptchaLoadError extends Error {
+    readonly reason: CaptchaLoadErrorReason;
+    constructor(reason: CaptchaLoadErrorReason, message?: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/build/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAExD,2EAA2E;AAC3E,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAgB,MAAM,EAAE,sBAAsB,CAAA;IAE9C,YAAY,MAAM,EAAE,sBAAsB,EAAE,OAAO,GAAE,MAA4B,EAAE,OAAO,CAAC,EAAE,YAAY,EAIxG;CACF"}

package/build/errors.js

@@ -0,0 +1,10 @@
+/** The captcha could not give a token; `reason` says which step failed. */
+export class CaptchaLoadError extends Error {
+    reason;
+    constructor(reason, message = `captcha:${reason}`, options) {
+        super(message, options);
+        this.name = 'CaptchaLoadError';
+        this.reason = reason;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/build/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,2EAA2E;AAC3E,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzB,MAAM,CAAwB;IAE9C,YAAY,MAA8B,EAAE,OAAO,GAAW,WAAW,MAAM,EAAE,EAAE,OAAsB;QACvG,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAA;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;CACF"}

package/build/index.d.ts

@@ -0,0 +1,5 @@
+export type * from './types.js';
+export * from './consts.js';
+export * from './errors.js';
+export * from './loader.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}

package/build/index.js

@@ -0,0 +1,4 @@
+export * from './consts.js';
+export * from './errors.js';
+export * from './loader.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}

package/build/loader.d.ts

@@ -0,0 +1,9 @@
+import type { CaptchaLoader, CaptchaLoaderOptions } from './types.js';
+/**
+ * Google's reCAPTCHA v3 loader. Nothing touches the page until `prepare` or `token` is called, so
+ * the module is safe to import during server rendering and in tests.
+ */
+export declare const createCaptchaLoader: (options?: CaptchaLoaderOptions) => CaptchaLoader;
+/** The shared loader of a page: one script per site key across every caller. */
+export declare const captchaLoader: CaptchaLoader;
+//# sourceMappingURL=loader.d.ts.map

package/build/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAC+B,aAAa,EAAE,oBAAoB,EAC7E,MAAM,YAAY,CAAA;AAEnB;;;GAGG;AACH,eAAO,MAAM,mBAAmB,aAAa,oBAAoB,KAAQ,aA2GxE,CAAA;AAED,gFAAgF;AAChF,eAAO,MAAM,aAAa,eAAwB,CAAA"}

package/build/loader.js

@@ -0,0 +1,105 @@
+import { CAPTCHA_BADGE_CSS, CAPTCHA_EXECUTE_TIMEOUT, CAPTCHA_LOAD_TIMEOUT, CAPTCHA_SCRIPT_ATTRIBUTE, CAPTCHA_STYLE_ATTRIBUTE, RECAPTCHA_SCRIPT_URL, } from './consts.js';
+import { CaptchaLoadError } from './errors.js';
+/**
+ * Google's reCAPTCHA v3 loader. Nothing touches the page until `prepare` or `token` is called, so
+ * the module is safe to import during server rendering and in tests.
+ */
+export const createCaptchaLoader = (options = {}) => {
+    const hideBadge = options.hideBadge ?? true;
+    const loadTimeout = options.loadTimeout ?? CAPTCHA_LOAD_TIMEOUT;
+    const executeTimeout = options.executeTimeout ?? CAPTCHA_EXECUTE_TIMEOUT;
+    const scriptUrl = options.scriptUrl ?? RECAPTCHA_SCRIPT_URL;
+    const loads = new Map();
+    const documentOf = () => options.document ?? (typeof document !== 'undefined' ? document : null);
+    const windowOf = () => options.window ?? (typeof window !== 'undefined' ? window : null);
+    const addBadgeStyle = (page) => {
+        if (page.querySelector(`style[${CAPTCHA_STYLE_ATTRIBUTE}]`) != null) {
+            return;
+        }
+        const style = page.createElement('style');
+        style.setAttribute(CAPTCHA_STYLE_ATTRIBUTE, '');
+        style.textContent = CAPTCHA_BADGE_CSS;
+        page.head.appendChild(style);
+    };
+    const inject = (siteKey) => new Promise((resolve, reject) => {
+        const page = documentOf();
+        const host = windowOf();
+        if (page == null || host == null) {
+            reject(new CaptchaLoadError('unavailable', 'reCAPTCHA needs a page to load into'));
+            return;
+        }
+        const script = page.createElement('script');
+        let settled = false;
+        let timer;
+        const fail = (reason, message) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                script.remove();
+                reject(new CaptchaLoadError(reason, message));
+            }
+        };
+        timer = setTimeout(() => { fail('timeout', 'reCAPTCHA did not become ready in time'); }, loadTimeout);
+        script.addEventListener('error', () => { fail('load', 'reCAPTCHA failed to load'); });
+        script.addEventListener('load', () => {
+            const grecaptcha = host.grecaptcha;
+            if (grecaptcha == null || typeof grecaptcha.ready !== 'function') {
+                fail('unavailable', 'reCAPTCHA loaded without its API');
+                return;
+            }
+            grecaptcha.ready(() => {
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timer);
+                    resolve(host.grecaptcha ?? grecaptcha);
+                }
+            });
+        });
+        script.src = `${scriptUrl}${scriptUrl.includes('?') ? '&' : '?'}render=${encodeURIComponent(siteKey)}`;
+        script.async = true;
+        script.setAttribute(CAPTCHA_SCRIPT_ATTRIBUTE, siteKey);
+        if (hideBadge) {
+            addBadgeStyle(page);
+        }
+        page.head.appendChild(script);
+    });
+    const readyOf = (siteKey) => {
+        const known = loads.get(siteKey);
+        if (known != null) {
+            return known;
+        }
+        const loading = inject(siteKey);
+        loads.set(siteKey, loading);
+        loading.catch(() => { loads.delete(siteKey); });
+        return loading;
+    };
+    const prepare = async (siteKey) => {
+        await readyOf(siteKey);
+    };
+    const token = async (siteKey, action) => {
+        const grecaptcha = await readyOf(siteKey);
+        let timer;
+        try {
+            const value = await Promise.race([
+                Promise.resolve(grecaptcha.execute(siteKey, { action })),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => { reject(new Error('reCAPTCHA execute timed out')); }, executeTimeout);
+                }),
+            ]);
+            if (typeof value !== 'string' || value === '') {
+                throw new Error('reCAPTCHA gave no token');
+            }
+            return value;
+        }
+        catch (error) {
+            throw new CaptchaLoadError('execute', `reCAPTCHA refused: ${String(error)}`, { cause: error });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    return { prepare, token };
+};
+/** The shared loader of a page: one script per site key across every caller. */
+export const captchaLoader = createCaptchaLoader();
+//# sourceMappingURL=loader.js.map

package/build/loader.js.map

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

package/build/react/types.d.ts

@@ -0,0 +1,22 @@
+import type { CaptchaLoader } from '../types.js';
+export interface UseCaptchaOptions {
+    /** The site key the server advertised; `null` (or `''`) = captcha off. */
+    siteKey: string | null;
+    /** The exact action the server checks this form's token for. */
+    action: string;
+    /** Default: the shared `captchaLoader`. */
+    loader?: CaptchaLoader;
+}
+export interface UseCaptchaResult {
+    /** The script is ready for the site key — or the captcha is off. */
+    ready: boolean;
+    /** The last load or execute failure, cleared by the next success. */
+    error: Error | null;
+    /**
+     * A fresh token for the action, or `null` while the captcha is off.
+     *
+     * @throws {CaptchaLoadError} when the script cannot load or Google gives no token.
+     */
+    execute: () => Promise<string | null>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/react/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/react/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAA;IACd,2CAA2C;IAC3C,MAAM,CAAC,EAAE,aAAa,CAAA;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,KAAK,EAAE,OAAO,CAAA;IACd,qEAAqE;IACrE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB;;;;OAIG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CACtC"}

package/build/react/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/react/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/react/types.ts"],"names":[],"mappings":""}

package/build/react/use-captcha.d.ts

@@ -0,0 +1,8 @@
+import type { UseCaptchaOptions, UseCaptchaResult } from './types.js';
+/**
+ * reCAPTCHA v3 for one form: starts loading the script as soon as a site key is known and gives a
+ * fresh token per submit. With no site key the captcha is off — `ready` is true and `execute`
+ * resolves `null`, so the form sends no captcha at all.
+ */
+export declare const useCaptcha: ({ siteKey, action, loader }: UseCaptchaOptions) => UseCaptchaResult;
+//# sourceMappingURL=use-captcha.d.ts.map

package/build/react/use-captcha.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-captcha.d.ts","sourceRoot":"","sources":["../../src/react/use-captcha.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAKrE;;;;GAIG;AACH,eAAO,MAAM,UAAU,gCAAiD,iBAAiB,KAAG,gBAgD3F,CAAA"}

package/build/react/use-captcha.js

@@ -0,0 +1,56 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { CaptchaLoadError } from '../errors.js';
+import { captchaLoader } from '../loader.js';
+const errorOf = (failure, reason) => failure instanceof Error ? failure : new CaptchaLoadError(reason, String(failure));
+/**
+ * reCAPTCHA v3 for one form: starts loading the script as soon as a site key is known and gives a
+ * fresh token per submit. With no site key the captcha is off — `ready` is true and `execute`
+ * resolves `null`, so the form sends no captcha at all.
+ */
+export const useCaptcha = ({ siteKey, action, loader = captchaLoader }) => {
+    const key = siteKey != null && siteKey !== '' ? siteKey : null;
+    const [ready, setReady] = useState(key == null);
+    const [error, setError] = useState(null);
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => { mounted.current = false; };
+    }, []);
+    useEffect(() => {
+        setError(null);
+        if (key == null) {
+            setReady(true);
+            return;
+        }
+        let current = true;
+        setReady(false);
+        loader.prepare(key).then(() => { if (current) {
+            setReady(true);
+        } }, (failure) => { if (current) {
+            setError(errorOf(failure, 'load'));
+        } });
+        return () => { current = false; };
+    }, [key, loader]);
+    const execute = useCallback(async () => {
+        if (key == null) {
+            return null;
+        }
+        try {
+            const token = await loader.token(key, action);
+            if (mounted.current) {
+                setReady(true);
+                setError(null);
+            }
+            return token;
+        }
+        catch (failure) {
+            const reported = errorOf(failure, 'execute');
+            if (mounted.current) {
+                setError(reported);
+            }
+            throw reported;
+        }
+    }, [key, action, loader]);
+    return { ready, error, execute };
+};
+//# sourceMappingURL=use-captcha.js.map

package/build/react/use-captcha.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-captcha.js","sourceRoot":"","sources":["../../src/react/use-captcha.ts"],"names":[],"mappings":"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"}

package/build/react.d.ts

@@ -0,0 +1,3 @@
+export type * from './react/types.js';
+export * from './react/use-captcha.js';
+//# sourceMappingURL=react.d.ts.map

package/build/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,mBAAmB,kBAAkB,CAAA;AACrC,cAAc,wBAAwB,CAAA"}

package/build/react.js

@@ -0,0 +1,2 @@
+export * from './react/use-captcha.js';
+//# sourceMappingURL=react.js.map

package/build/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AACA,cAAc,wBAAwB,CAAA"}

package/build/types.d.ts

@@ -0,0 +1,51 @@
+/** The part of Google's `grecaptcha` (v3, `render=<site key>`) the loader uses. */
+export interface Grecaptcha {
+    ready: (callback: () => void) => void;
+    execute: (siteKey: string, options: {
+        action: string;
+    }) => PromiseLike<string>;
+}
+/** The window as the loader reads it: only Google's global. */
+export interface CaptchaWindow {
+    grecaptcha?: Grecaptcha;
+}
+/** The document as the loader uses it: one script and one style appended to its head. */
+export interface CaptchaDocument extends Pick<Document, 'createElement' | 'querySelector' | 'head'> {
+}
+/**
+ * Why a captcha could not give a token: the script failed to `load`, did not become ready in time
+ * (`timeout`), there is no page or no API to use (`unavailable`), or Google gave no token (`execute`).
+ */
+export type CaptchaLoadErrorReason = 'load' | 'timeout' | 'execute' | 'unavailable';
+export interface CaptchaLoaderOptions {
+    /** Add the document style that hides Google's badge. Default `true`. */
+    hideBadge?: boolean;
+    /** Milliseconds the script may take to become ready. Default `CAPTCHA_LOAD_TIMEOUT`. */
+    loadTimeout?: number;
+    /** Milliseconds one `execute` may take. Default `CAPTCHA_EXECUTE_TIMEOUT`. */
+    executeTimeout?: number;
+    /** The script address `?render=<site key>` is added to. Default `RECAPTCHA_SCRIPT_URL`. */
+    scriptUrl?: string;
+    /** The page to load into. Default: the global `document`, read at call time. */
+    document?: CaptchaDocument;
+    /** Where Google's global appears. Default: the global `window`, read at call time. */
+    window?: CaptchaWindow;
+}
+/** Google's reCAPTCHA v3, loaded on first use — never at import. */
+export interface CaptchaLoader {
+    /**
+     * Inject `api.js?render=<siteKey>` once per key (and, unless disabled, the document style that
+     * hides Google's badge); resolves once `grecaptcha` is ready. A failure is forgotten, so the next
+     * call injects again.
+     *
+     * @throws {CaptchaLoadError} `load`, `timeout` or `unavailable`.
+     */
+    prepare: (siteKey: string) => Promise<void>;
+    /**
+     * A fresh token for `action`, loading the script first when needed.
+     *
+     * @throws {CaptchaLoadError} what `prepare` throws, or `execute` when Google gives no token in time.
+     */
+    token: (siteKey: string, action: string) => Promise<string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAA;IACrC,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,WAAW,CAAC,MAAM,CAAC,CAAA;CAC/E;AAED,+DAA+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAA;CACxB;AAED,yFAAyF;AACzF,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe,GAAG,MAAM,CAAC;CAAG;AAEtG;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAA;AAEnF,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,eAAe,CAAA;IAC1B,sFAAsF;IACtF,MAAM,CAAC,EAAE,aAAa,CAAA;CACvB;AAED,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C;;;;OAIG;IACH,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC5D"}

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@owlmeans/web-captcha",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.19-rc.0",
+  "license": "MIT",
+  "description": "Browser half of OwlMeans captcha — the invisible score-based reCAPTCHA v3 loader and a React hook; no OwlMeans dependencies.",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 2 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    },
+    "./react": {
+      "import": "./build/react.js",
+      "require": "./build/react.js",
+      "default": "./build/react.js",
+      "module": "./build/react.js",
+      "types": "./build/react.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "react": "*"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "^0.1.19-rc.0",
+    "@types/bun": "^1.4.2",
+    "@types/react": "^19.3.0",
+    "nodemon": "^3.1.14",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,20 @@
+/** Google's reCAPTCHA v3 script; `?render=<site key>` selects the invisible, score-based widget. */
+export const RECAPTCHA_SCRIPT_URL = 'https://www.google.com/recaptcha/api.js'
+
+/** Marks the script the loader injected; its value is the site key. */
+export const CAPTCHA_SCRIPT_ATTRIBUTE = 'data-owlmeans-captcha'
+
+/** Marks the document style that hides Google's badge. */
+export const CAPTCHA_STYLE_ATTRIBUTE = 'data-owlmeans-captcha-style'
+
+/**
+ * The one document-level rule the loader adds unless told not to: Google's badge hidden. A page
+ * that hides it must show Google's notice ("This site is protected by reCAPTCHA…") itself.
+ */
+export const CAPTCHA_BADGE_CSS = '.grecaptcha-badge{visibility:hidden}'
+
+/** How long the script may take to become ready, in milliseconds. */
+export const CAPTCHA_LOAD_TIMEOUT = 15_000
+
+/** How long one `execute` may take, in milliseconds. */
+export const CAPTCHA_EXECUTE_TIMEOUT = 20_000

package/src/errors.ts

@@ -0,0 +1,12 @@
+import type { CaptchaLoadErrorReason } from './types.js'
+
+/** The captcha could not give a token; `reason` says which step failed. */
+export class CaptchaLoadError extends Error {
+  public readonly reason: CaptchaLoadErrorReason
+
+  constructor(reason: CaptchaLoadErrorReason, message: string = `captcha:${reason}`, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'CaptchaLoadError'
+    this.reason = reason
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export type * from './types.js'
+export * from './consts.js'
+export * from './errors.js'
+export * from './loader.js'

package/src/loader.ts

@@ -0,0 +1,124 @@
+import {
+  CAPTCHA_BADGE_CSS, CAPTCHA_EXECUTE_TIMEOUT, CAPTCHA_LOAD_TIMEOUT, CAPTCHA_SCRIPT_ATTRIBUTE, CAPTCHA_STYLE_ATTRIBUTE,
+  RECAPTCHA_SCRIPT_URL,
+} from './consts.js'
+import { CaptchaLoadError } from './errors.js'
+import type {
+  CaptchaDocument, CaptchaLoadErrorReason, CaptchaLoader, CaptchaLoaderOptions, CaptchaWindow, Grecaptcha,
+} from './types.js'
+
+/**
+ * Google's reCAPTCHA v3 loader. Nothing touches the page until `prepare` or `token` is called, so
+ * the module is safe to import during server rendering and in tests.
+ */
+export const createCaptchaLoader = (options: CaptchaLoaderOptions = {}): CaptchaLoader => {
+  const hideBadge = options.hideBadge ?? true
+  const loadTimeout = options.loadTimeout ?? CAPTCHA_LOAD_TIMEOUT
+  const executeTimeout = options.executeTimeout ?? CAPTCHA_EXECUTE_TIMEOUT
+  const scriptUrl = options.scriptUrl ?? RECAPTCHA_SCRIPT_URL
+  const loads = new Map<string, Promise<Grecaptcha>>()
+
+  const documentOf = (): CaptchaDocument | null =>
+    options.document ?? (typeof document !== 'undefined' ? document : null)
+
+  const windowOf = (): CaptchaWindow | null =>
+    options.window ?? (typeof window !== 'undefined' ? window as unknown as CaptchaWindow : null)
+
+  const addBadgeStyle = (page: CaptchaDocument): void => {
+    if (page.querySelector(`style[${CAPTCHA_STYLE_ATTRIBUTE}]`) != null) {
+      return
+    }
+    const style = page.createElement('style')
+    style.setAttribute(CAPTCHA_STYLE_ATTRIBUTE, '')
+    style.textContent = CAPTCHA_BADGE_CSS
+    page.head.appendChild(style)
+  }
+
+  const inject = (siteKey: string): Promise<Grecaptcha> => new Promise<Grecaptcha>((resolve, reject) => {
+    const page = documentOf()
+    const host = windowOf()
+    if (page == null || host == null) {
+      reject(new CaptchaLoadError('unavailable', 'reCAPTCHA needs a page to load into'))
+      return
+    }
+
+    const script = page.createElement('script')
+    let settled = false
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const fail = (reason: CaptchaLoadErrorReason, message: string): void => {
+      if (!settled) {
+        settled = true
+        clearTimeout(timer)
+        script.remove()
+        reject(new CaptchaLoadError(reason, message))
+      }
+    }
+    timer = setTimeout(() => { fail('timeout', 'reCAPTCHA did not become ready in time') }, loadTimeout)
+
+    script.addEventListener('error', () => { fail('load', 'reCAPTCHA failed to load') })
+    script.addEventListener('load', () => {
+      const grecaptcha = host.grecaptcha
+      if (grecaptcha == null || typeof grecaptcha.ready !== 'function') {
+        fail('unavailable', 'reCAPTCHA loaded without its API')
+        return
+      }
+      grecaptcha.ready(() => {
+        if (!settled) {
+          settled = true
+          clearTimeout(timer)
+          resolve(host.grecaptcha ?? grecaptcha)
+        }
+      })
+    })
+
+    script.src = `${scriptUrl}${scriptUrl.includes('?') ? '&' : '?'}render=${encodeURIComponent(siteKey)}`
+    script.async = true
+    script.setAttribute(CAPTCHA_SCRIPT_ATTRIBUTE, siteKey)
+    if (hideBadge) {
+      addBadgeStyle(page)
+    }
+    page.head.appendChild(script)
+  })
+
+  const readyOf = (siteKey: string): Promise<Grecaptcha> => {
+    const known = loads.get(siteKey)
+    if (known != null) {
+      return known
+    }
+    const loading = inject(siteKey)
+    loads.set(siteKey, loading)
+    loading.catch(() => { loads.delete(siteKey) })
+
+    return loading
+  }
+
+  const prepare: CaptchaLoader['prepare'] = async siteKey => {
+    await readyOf(siteKey)
+  }
+
+  const token: CaptchaLoader['token'] = async (siteKey, action) => {
+    const grecaptcha = await readyOf(siteKey)
+    let timer: ReturnType<typeof setTimeout> | undefined
+    try {
+      const value = await Promise.race([
+        Promise.resolve(grecaptcha.execute(siteKey, { action })),
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(() => { reject(new Error('reCAPTCHA execute timed out')) }, executeTimeout)
+        }),
+      ])
+      if (typeof value !== 'string' || value === '') {
+        throw new Error('reCAPTCHA gave no token')
+      }
+      return value
+    } catch (error) {
+      throw new CaptchaLoadError('execute', `reCAPTCHA refused: ${String(error)}`, { cause: error })
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  return { prepare, token }
+}
+
+/** The shared loader of a page: one script per site key across every caller. */
+export const captchaLoader = createCaptchaLoader()

package/src/react/types.ts

@@ -0,0 +1,23 @@
+import type { CaptchaLoader } from '../types.js'
+
+export interface UseCaptchaOptions {
+  /** The site key the server advertised; `null` (or `''`) = captcha off. */
+  siteKey: string | null
+  /** The exact action the server checks this form's token for. */
+  action: string
+  /** Default: the shared `captchaLoader`. */
+  loader?: CaptchaLoader
+}
+
+export interface UseCaptchaResult {
+  /** The script is ready for the site key — or the captcha is off. */
+  ready: boolean
+  /** The last load or execute failure, cleared by the next success. */
+  error: Error | null
+  /**
+   * A fresh token for the action, or `null` while the captcha is off.
+   *
+   * @throws {CaptchaLoadError} when the script cannot load or Google gives no token.
+   */
+  execute: () => Promise<string | null>
+}

package/src/react/use-captcha.ts

@@ -0,0 +1,63 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { CaptchaLoadError } from '../errors.js'
+import { captchaLoader } from '../loader.js'
+import type { CaptchaLoadErrorReason } from '../types.js'
+import type { UseCaptchaOptions, UseCaptchaResult } from './types.js'
+
+const errorOf = (failure: unknown, reason: CaptchaLoadErrorReason): Error =>
+  failure instanceof Error ? failure : new CaptchaLoadError(reason, String(failure))
+
+/**
+ * reCAPTCHA v3 for one form: starts loading the script as soon as a site key is known and gives a
+ * fresh token per submit. With no site key the captcha is off — `ready` is true and `execute`
+ * resolves `null`, so the form sends no captcha at all.
+ */
+export const useCaptcha = ({ siteKey, action, loader = captchaLoader }: UseCaptchaOptions): UseCaptchaResult => {
+  const key = siteKey != null && siteKey !== '' ? siteKey : null
+  const [ready, setReady] = useState<boolean>(key == null)
+  const [error, setError] = useState<Error | null>(null)
+  const mounted = useRef(true)
+
+  useEffect(() => {
+    mounted.current = true
+    return () => { mounted.current = false }
+  }, [])
+
+  useEffect(() => {
+    setError(null)
+    if (key == null) {
+      setReady(true)
+      return
+    }
+    let current = true
+    setReady(false)
+    loader.prepare(key).then(
+      () => { if (current) { setReady(true) } },
+      (failure: unknown) => { if (current) { setError(errorOf(failure, 'load')) } }
+    )
+
+    return () => { current = false }
+  }, [key, loader])
+
+  const execute = useCallback(async (): Promise<string | null> => {
+    if (key == null) {
+      return null
+    }
+    try {
+      const token = await loader.token(key, action)
+      if (mounted.current) {
+        setReady(true)
+        setError(null)
+      }
+      return token
+    } catch (failure) {
+      const reported = errorOf(failure, 'execute')
+      if (mounted.current) {
+        setError(reported)
+      }
+      throw reported
+    }
+  }, [key, action, loader])
+
+  return { ready, error, execute }
+}

package/src/react.ts

@@ -0,0 +1,2 @@
+export type * from './react/types.js'
+export * from './react/use-captcha.js'

package/src/types.ts

@@ -0,0 +1,52 @@
+/** The part of Google's `grecaptcha` (v3, `render=<site key>`) the loader uses. */
+export interface Grecaptcha {
+  ready: (callback: () => void) => void
+  execute: (siteKey: string, options: { action: string }) => PromiseLike<string>
+}
+
+/** The window as the loader reads it: only Google's global. */
+export interface CaptchaWindow {
+  grecaptcha?: Grecaptcha
+}
+
+/** The document as the loader uses it: one script and one style appended to its head. */
+export interface CaptchaDocument extends Pick<Document, 'createElement' | 'querySelector' | 'head'> {}
+
+/**
+ * Why a captcha could not give a token: the script failed to `load`, did not become ready in time
+ * (`timeout`), there is no page or no API to use (`unavailable`), or Google gave no token (`execute`).
+ */
+export type CaptchaLoadErrorReason = 'load' | 'timeout' | 'execute' | 'unavailable'
+
+export interface CaptchaLoaderOptions {
+  /** Add the document style that hides Google's badge. Default `true`. */
+  hideBadge?: boolean
+  /** Milliseconds the script may take to become ready. Default `CAPTCHA_LOAD_TIMEOUT`. */
+  loadTimeout?: number
+  /** Milliseconds one `execute` may take. Default `CAPTCHA_EXECUTE_TIMEOUT`. */
+  executeTimeout?: number
+  /** The script address `?render=<site key>` is added to. Default `RECAPTCHA_SCRIPT_URL`. */
+  scriptUrl?: string
+  /** The page to load into. Default: the global `document`, read at call time. */
+  document?: CaptchaDocument
+  /** Where Google's global appears. Default: the global `window`, read at call time. */
+  window?: CaptchaWindow
+}
+
+/** Google's reCAPTCHA v3, loaded on first use — never at import. */
+export interface CaptchaLoader {
+  /**
+   * Inject `api.js?render=<siteKey>` once per key (and, unless disabled, the document style that
+   * hides Google's badge); resolves once `grecaptcha` is ready. A failure is forgotten, so the next
+   * call injects again.
+   *
+   * @throws {CaptchaLoadError} `load`, `timeout` or `unavailable`.
+   */
+  prepare: (siteKey: string) => Promise<void>
+  /**
+   * A fresh token for `action`, loading the script first when needed.
+   *
+   * @throws {CaptchaLoadError} what `prepare` throws, or `execute` when Google gives no token in time.
+   */
+  token: (siteKey: string, action: string) => Promise<string>
+}

package/tests/context.ts

@@ -0,0 +1,73 @@
+import type { CaptchaDocument, CaptchaWindow, Grecaptcha } from '../src/types.js'
+
+/** An element as the loader uses it: attributes, listeners, `src`/`async`/`textContent`, `remove`. */
+export interface PageElement {
+  tag: string
+  attributes: Record<string, string>
+  src?: string
+  async?: boolean
+  textContent?: string | null
+  removed: boolean
+  setAttribute: (name: string, value: string) => void
+  addEventListener: (type: string, listener: () => void) => void
+  remove: () => void
+  /** Run the listeners of `type`, as the browser would. */
+  fire: (type: string) => void
+}
+
+export interface TestPage {
+  document: CaptchaDocument
+  window: CaptchaWindow
+  /** What the loader appended to the head, in order (removed ones included, flagged). */
+  head: PageElement[]
+  /** The scripts still in the head. */
+  scripts: () => PageElement[]
+  /** Google's script arrives: `grecaptcha` (ready at once) is installed and `load` fires. */
+  arrive: (script: PageElement, grecaptcha?: Grecaptcha | null) => void
+}
+
+const makeElement = (tag: string): PageElement => {
+  const listeners: Record<string, (() => void)[]> = {}
+  const element: PageElement = {
+    tag,
+    attributes: {},
+    removed: false,
+    setAttribute: (name, value) => { element.attributes[name] = value },
+    addEventListener: (type, listener) => { (listeners[type] ??= []).push(listener) },
+    remove: () => { element.removed = true },
+    fire: type => { (listeners[type] ?? []).forEach(listener => listener()) },
+  }
+
+  return element
+}
+
+/** A page stand-in (document + window) for the loader's pure logic — no browser. */
+export const makeTestPage = (): TestPage => {
+  const head: PageElement[] = []
+  const window: CaptchaWindow = {}
+
+  const querySelector = (selector: string): PageElement | null => {
+    const [, tag, attribute] = /^(\w+)\[([^\]=]+)\]$/.exec(selector) ?? []
+
+    return head.find(element => !element.removed && element.tag === tag && attribute in element.attributes) ?? null
+  }
+
+  const document = {
+    head: { appendChild: (element: PageElement) => { head.push(element); return element } },
+    createElement: makeElement,
+    querySelector,
+  } as unknown as CaptchaDocument
+
+  const arrive: TestPage['arrive'] = (script, grecaptcha) => {
+    window.grecaptcha = grecaptcha === null ? undefined : grecaptcha ?? {
+      ready: callback => { callback() },
+      execute: async (siteKey, { action }) => `token:${siteKey}:${action}`,
+    }
+    script.fire('load')
+  }
+
+  return {
+    document, window, head, arrive,
+    scripts: () => head.filter(element => element.tag === 'script' && !element.removed),
+  }
+}

package/tests/loader.spec.ts

@@ -0,0 +1,112 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  CAPTCHA_BADGE_CSS, CAPTCHA_SCRIPT_ATTRIBUTE, CAPTCHA_STYLE_ATTRIBUTE, RECAPTCHA_SCRIPT_URL,
+} from '../src/consts.js'
+import { CaptchaLoadError } from '../src/errors.js'
+import { captchaLoader, createCaptchaLoader } from '../src/loader.js'
+import type { CaptchaLoaderOptions } from '../src/types.js'
+import { makeTestPage } from './context.js'
+
+const loaderOn = (page = makeTestPage(), options: CaptchaLoaderOptions = {}) =>
+  ({ page, loader: createCaptchaLoader({ document: page.document, window: page.window, ...options }) })
+
+const failure = async (promise: Promise<unknown>): Promise<CaptchaLoadError> => {
+  try {
+    await promise
+  } catch (error) {
+    expect(error).toBeInstanceOf(CaptchaLoadError)
+    return error as CaptchaLoadError
+  }
+  throw new Error('expected a failure')
+}
+
+describe('@owlmeans/web-captcha — loader', () => {
+  test('injects one script per site key, with the badge style once, and resolves when grecaptcha is ready', async () => {
+    const { page, loader } = loaderOn()
+
+    const first = loader.prepare('key one')
+    const again = loader.prepare('key one')
+    expect(page.scripts()).toHaveLength(1)
+    const [script] = page.scripts()
+    expect(script.src).toBe(`${RECAPTCHA_SCRIPT_URL}?render=key%20one`)
+    expect(script.async).toBe(true)
+    expect(script.attributes[CAPTCHA_SCRIPT_ATTRIBUTE]).toBe('key one')
+
+    page.arrive(script)
+    await Promise.all([first, again])
+    await loader.prepare('key one')
+    expect(page.scripts()).toHaveLength(1)
+
+    const second = loader.prepare('key-two')
+    page.arrive(page.scripts()[1])
+    await second
+    expect(page.scripts()).toHaveLength(2)
+    const styles = page.head.filter(element => element.tag === 'style')
+    expect(styles).toHaveLength(1)
+    expect(styles[0].attributes).toHaveProperty(CAPTCHA_STYLE_ATTRIBUTE)
+    expect(styles[0].textContent).toBe(CAPTCHA_BADGE_CSS)
+  })
+
+  test('a load that fails or never becomes ready is refused with its reason, and forgotten', async () => {
+    const { page, loader } = loaderOn(makeTestPage(), { loadTimeout: 5 })
+
+    const timedOut = await failure(loader.prepare('k'))
+    expect(timedOut.reason).toBe('timeout')
+    expect(page.scripts()).toHaveLength(0)
+
+    const erroring = loader.prepare('k')
+    page.scripts()[0].fire('error')
+    expect((await failure(erroring)).reason).toBe('load')
+
+    const bare = loader.prepare('k')
+    page.arrive(page.scripts()[0], null)
+    expect((await failure(bare)).reason).toBe('unavailable')
+
+    const retried = loader.prepare('k')
+    page.arrive(page.scripts()[0])
+    await retried
+    expect(page.head.filter(element => element.tag === 'script')).toHaveLength(4)
+    expect(page.scripts()).toHaveLength(1)
+  })
+
+  test('without a page nothing is touched at import, and a call is unavailable', async () => {
+    expect(typeof (globalThis as { document?: unknown }).document).toBe('undefined')
+    expect((await failure(captchaLoader.prepare('k'))).reason).toBe('unavailable')
+    expect((await failure(createCaptchaLoader().token('k', 'a'))).reason).toBe('unavailable')
+  })
+
+  test('hideBadge: false adds no document style; a script url with a query keeps it', async () => {
+    const { page, loader } = loaderOn(makeTestPage(), { hideBadge: false, scriptUrl: 'https://www.recaptcha.net/recaptcha/api.js?hl=pl' })
+
+    const ready = loader.prepare('k')
+    page.arrive(page.scripts()[0])
+    await ready
+    expect(page.head.map(element => element.tag)).toEqual(['script'])
+    expect(page.scripts()[0].src).toBe('https://www.recaptcha.net/recaptcha/api.js?hl=pl&render=k')
+  })
+})
+
+describe('@owlmeans/web-captcha — token', () => {
+  test('loads on demand and executes the action', async () => {
+    const { page, loader } = loaderOn()
+
+    const token = loader.token('k', 'email_pin')
+    page.arrive(page.scripts()[0])
+    expect(await token).toBe('token:k:email_pin')
+    expect(await loader.token('k', 'email_password')).toBe('token:k:email_password')
+    expect(page.scripts()).toHaveLength(1)
+  })
+
+  test('no token, a throwing or a hanging execute is an execute failure', async () => {
+    for (const execute of [
+      async () => '',
+      () => { throw new Error('denied') },
+      () => new Promise<string>(() => {}),
+    ]) {
+      const { page, loader } = loaderOn(makeTestPage(), { executeTimeout: 5 })
+      const token = loader.token('k', 'email_pin')
+      page.arrive(page.scripts()[0], { ready: callback => { callback() }, execute })
+      expect((await failure(token)).reason).toBe('execute')
+    }
+  })
+})

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.react.json"
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/",
+    "outDir": "./build/"
+  },
+  "exclude": [
+    "./dist/**/*",
+    "./build/**/*",
+    "./tests/**/*",
+    "./*.ts"
+  ]
+}