@snutig/react 0.1.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2025 snutig GmbH
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,200 @@
+# @snutig/react
+
+React bindings for the snutig CAPTCHA widget
+
+Proof-of-work only: no puzzles, no images, nothing for a visitor to solve by hand.
+snutig runs the service; you need an account and a site key — [snutig.de](https://snutig.de).
+
+## Install
+
+```bash
+pnpm add @snutig/react   # npm i / yarn add work the same
+```
+
+Peer dependency: `react >= 18` (works with React 19 / Next.js App Router).
+
+## Quick start
+
+```tsx
+"use client"; // Next.js App Router: this component is browser-only
+
+import { SnutigCaptcha } from "@snutig/react";
+import { useState } from "react";
+
+export function ContactForm() {
+  const [token, setToken] = useState<string | null>(null);
+
+  return (
+    <form action="/api/contact" method="post">
+      <input name="email" type="email" required />
+
+      <SnutigCaptcha
+        siteKey="YOUR_SITE_KEY"
+        required
+        onSolve={setToken}
+        onReset={() => setToken(null)}
+      />
+
+      <button type="submit" disabled={!token}>
+        Absenden
+      </button>
+    </form>
+  );
+}
+```
+
+The widget writes its token into a hidden `<input name="snutig-token">` it manages
+itself, so a plain form post carries it with no extra wiring — `onSolve` is only
+needed if you also want it in React state (to gate the submit button, for
+instance). With `required`, native form validation blocks submission until solved.
+
+## Invisible mode
+
+`hidden` renders no visible widget: there is nothing to click, so you start the
+solve yourself and submit once it resolves.
+
+```tsx
+const captcha = useRef<SnutigCaptchaHandle>(null);
+const form = useRef<HTMLFormElement>(null);
+
+async function onSubmit(e: React.FormEvent) {
+  e.preventDefault();
+  const { success } = (await captcha.current?.solve()) ?? { success: false };
+  if (!success) return; // onError already fired with the reason
+  form.current?.submit(); // the token is in the managed hidden input
+}
+
+<form ref={form} action="/api/contact" method="post" onSubmit={onSubmit}>
+  <input name="email" type="email" required />
+  <SnutigCaptcha
+    ref={captcha}
+    siteKey={siteKey}
+    hidden
+    onError={setError}
+  />
+  <button type="submit">Absenden</button>
+</form>;
+```
+
+Three things to know:
+
+- **It is plan-gated.** Invisible solving is the `hiddenMode` entitlement (Pro and
+  up). Visibility is not something a server can check, so the server instead
+  reports the entitlement on every challenge, and an unlicensed widget **degrades
+  to a visible badge** in the bottom-right corner on its first solve rather than
+  letting the form through unchecked. Your form keeps working either way — it just
+  stops being invisible, the same spirit as the quota grace period. Check the
+  entitlement in the dashboard (Websites → Integration) if a badge appears.
+- **`required` does not apply.** A browser will not report a validation error on a
+  control the user cannot see; it refuses to submit and shows nothing. So `hidden`
+  ignores `required` and warns on the console. Gate the submit yourself, as above.
+- **No speculative pre-solve.** The widget normally warms a solve on the first
+  mouse/keyboard interaction, which it skips while it is invisible — so an
+  invisible solve starts cold and takes proportionally longer. Call `solve()`
+  before you strictly need the token (on first field blur, say) if that matters.
+
+## Verify on your server
+
+A token proves the check ran in a browser. It is **not** trustworthy until your
+server verifies it — always do this before accepting the submission.
+
+```ts
+const res = await fetch(`https://api.captcha.snutig.dev/${siteKey}/siteverify`, {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({
+    secret: process.env.SNUTIG_SECRET_KEY, // secret key — server-side only
+    response: token, // the "snutig-token" form field
+  }),
+});
+
+const { success } = await res.json();
+if (!success)
+  return new Response("CAPTCHA-Überprüfung fehlgeschlagen.", { status: 400 });
+```
+
+Tokens are single-use: verify once, and call `reset()` before letting the user
+resubmit after a failure.
+
+## Imperative control
+
+```tsx
+const captcha = useRef<SnutigCaptchaHandle>(null);
+
+await captcha.current?.solve(); // start a solve without a click
+captcha.current?.reset(); // clear the token + hidden field
+captcha.current?.token; // current token, or null
+```
+
+## Props
+
+| Prop                  | Default               | What it does                                                                                               |
+| --------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `siteKey`             | —                     | Website key from the dashboard (Websites → Keys). Public.                                                  |
+| `apiUrl`              | the snutig API        | `https://api.captcha.snutig.dev`. Override only for a staging deployment.                                   |
+| `endpoint`            | `<apiUrl>/<siteKey>/` | Full challenge base — only for a reverse-proxied path.                                                     |
+| `fieldName`           | `"snutig-token"`      | `name` of the managed hidden input.                                                                        |
+| `required`            | `false`               | Blocks native submission until solved. Ignored with `hidden`.                                              |
+| `hidden`              | `false`               | Invisible mode — no visible widget, solve from the ref. Needs the `hiddenMode` plan entitlement.           |
+| `workers`             | `hardwareConcurrency` | Solver worker count.                                                                                       |
+| `locale`              | `"de"`                | `"de"` = the WordPress plugin's wording; `"en"` = the widget's own defaults.                               |
+| `labels`              | —                     | Per-label overrides, merged over the locale's set.                                                         |
+| `theme`               | `"snutig"`            | `"external"` to use the imported stylesheet instead of the injected one, `"none"` to style it yourself.    |
+| `troubleshootingUrl`  | —                     | Help link, shown only after a failure.                                                                     |
+| `nonce`               | —                     | CSP nonce for the injected script and styles.                                                              |
+| `className` / `style` | —                     | Applied to the wrapper — `<div class="snutig-captcha">`, or `snutig-captcha-unstyled` with `theme="none"`. |
+| `onSolve(token)`      | —                     | Solved.                                                                                                    |
+| `onError(error)`      | —                     | Failed — `{ code, message }`; see `SnutigErrorCode`.                                                       |
+| `onProgress(pct)`     | —                     | Solve progress, 0–100.                                                                                     |
+| `onReset()`           | —                     | Token cleared (expiry or `reset()`).                                                                       |
+
+## Theming
+
+The widget renders into a shadow root, so it is themed through CSS custom
+properties, which inherit across the shadow boundary. By default this package
+injects one `<style>` with the snutig brand tokens — sage `#99b596` on black,
+12px radius — kept in sync with the plugin's `assets/snutig-captcha.css`.
+
+Override the tokens on the wrapper:
+
+```tsx
+<SnutigCaptcha
+  {...props}
+  style={
+    {
+      "--snutig-bg": "#0b0b0b",
+      "--snutig-border-radius": "8px",
+    } as React.CSSProperties
+  }
+/>
+```
+
+`--snutig-primary`, `--snutig-bg`, `--snutig-fg` and `--snutig-border-radius` are
+the main knobs; see `THEME_CSS` for the full list. One caveat: the checkmark and
+error cross are inline SVG data URIs with the brand colors baked in, so recoloring
+those means replacing `--snutig-checkmark` / `--snutig-error-cross` outright.
+
+Prefer a stylesheet over the injected tag (strict CSP, or your own build
+pipeline)? Pass `theme="external"` and import the CSS instead:
+
+```ts
+import "@snutig/react/theme.css";
+```
+
+`theme="none"` is the other case — no theme at all. The stylesheet is
+document-wide and keyed on the wrapper class, so an unthemed instance renders
+as `<div class="snutig-captcha-unstyled">` and stays unstyled even when another
+instance on the page injects the brand theme.
+
+## Notes
+
+- **The solver is not in this package.** It loads
+  `<apiUrl>/widget/v1/widget.js` once per page and dedupes concurrent mounts, so
+  many widgets on one page cost one request. The wire protocol is versioned with
+  the API, which is why there is no vendored or CDN-hosted copy — and why you never
+  have to match a version of this package to anything server-side.
+- **Custom element, one definition.** `<snutig-captcha>` registers itself on first
+  load; a page that already has it (a WordPress page, another React root) reuses it.
+- **Not SSR-rendered.** Server rendering emits the tag and its attributes; the
+  widget upgrades and takes over on the client. No hydration mismatch, no DOM
+  access during render.

package/dist/SnutigCaptcha.d.ts

@@ -0,0 +1,99 @@
+import type { CSSProperties } from "react";
+import type { SnutigLabels, SnutigLocale } from "./labels.js";
+import type { SnutigCaptchaElement, SnutigErrorDetail, SolveResult } from "./types.js";
+export interface SnutigCaptchaProps {
+    /** Website key from the dashboard (Websites → Keys). */
+    siteKey: string;
+    /**
+     * snutig captcha API base URL. Defaults to the managed service
+     * (`https://api.captcha.snutig.dev`) — set it only for a staging deployment.
+     */
+    apiUrl?: string;
+    /**
+     * Full challenge endpoint base, overriding `apiUrl` + `siteKey`
+     * (`<apiUrl>/<siteKey>/`). Rarely needed — for a reverse-proxied path.
+     */
+    endpoint?: string;
+    /**
+     * `name` of the hidden input the token is written to, for plain form posts.
+     * Defaults to `snutig-token`.
+     */
+    fieldName?: string;
+    /**
+     * Blocks native form submission until solved, via constraint validation
+     * (the widget participates as a form-associated element).
+     */
+    required?: boolean;
+    /**
+     * Invisible mode: no visible widget — nothing for the user to click, so the
+     * solve has to be started from the ref (`solve()`, typically in `onSubmit`).
+     *
+     * Plan-gated (`hiddenMode`). A site that is not licensed for invisible solving
+     * gets `widget.hiddenMode: false` on its challenge, and the widget then
+     * degrades to a visible badge in the bottom-right corner rather than letting a
+     * form ship without a check — so this never *breaks*, it only stops being
+     * invisible.
+     *
+     * `required` does not apply: constraint validation cannot report a problem on
+     * an element the user cannot see (the browser refuses to submit and shows
+     * nothing), so it is ignored here.
+     */
+    hidden?: boolean;
+    /** Solver worker count. Defaults to `navigator.hardwareConcurrency`. */
+    workers?: number;
+    /** Label set. Defaults to `"de"` — the wording the WordPress plugin ships. */
+    locale?: SnutigLocale;
+    /** Per-label overrides, merged over the locale's set. */
+    labels?: Partial<SnutigLabels>;
+    /**
+     * `"snutig"` (default) injects the brand theme and marks the wrapper for it.
+     * `"external"` marks the wrapper but injects nothing — for importing
+     * `@snutig/react/theme.css` through your own pipeline (or under a strict CSP).
+     * `"none"` leaves the widget unstyled even when another instance on the page is
+     * themed: the brand CSS targets the wrapper class, so an unthemed instance has to
+     * not carry it.
+     */
+    theme?: "snutig" | "external" | "none";
+    /** Help link, shown only after a failure. */
+    troubleshootingUrl?: string;
+    /** CSP nonce for the injected script + styles. */
+    nonce?: string;
+    className?: string;
+    style?: CSSProperties;
+    /** Solved — `token` goes to your server's `POST /:siteKey/siteverify`. */
+    onSolve?: (token: string) => void;
+    onError?: (error: SnutigErrorDetail) => void;
+    /** Solve progress, 0–100. */
+    onProgress?: (progress: number) => void;
+    /** Token cleared — on expiry, or via `reset()`. */
+    onReset?: () => void;
+}
+export interface SnutigCaptchaHandle {
+    /** Starts a solve (the widget also does this on click). */
+    solve(): Promise<SolveResult>;
+    /** Clears the token and the hidden field — call after a failed submit. */
+    reset(): void;
+    /** Current token, or `null` when unsolved. */
+    readonly token: string | null;
+    /** The underlying custom element, once mounted. */
+    readonly element: SnutigCaptchaElement | null;
+}
+/**
+ * The snutig CAPTCHA widget as a React component.
+ *
+ * Wraps the `<snutig-captcha>` custom element served by the captcha server: this
+ * package loads that bundle, maps props to its attributes, and turns its
+ * `solve`/`error`/`progress`/`reset` DOM events into props. The widget renders
+ * itself into a shadow root and writes the token into a hidden input, so a plain
+ * `<form>` post carries it with no extra wiring.
+ *
+ * With `hidden` it renders nothing and solves only when `solve()` is called from
+ * the ref — the invisible mode, which is a plan entitlement the server asserts on
+ * every challenge.
+ *
+ * A token only proves the check ran in the browser — always verify it
+ * server-side with `POST <apiUrl>/<siteKey>/siteverify` before trusting the
+ * submission.
+ */
+export declare const SnutigCaptcha: import("react").ForwardRefExoticComponent<SnutigCaptchaProps & import("react").RefAttributes<SnutigCaptchaHandle>>;
+//# sourceMappingURL=SnutigCaptcha.d.ts.map

package/dist/SnutigCaptcha.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SnutigCaptcha.d.ts","sourceRoot":"","sources":["../src/SnutigCaptcha.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAO,MAAM,OAAO,CAAC;AAGhD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,KAAK,EACV,oBAAoB,EACpB,iBAAiB,EACjB,WAAW,EACZ,MAAM,YAAY,CAAC;AAyBpB,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/B;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;IACvC,6CAA6C;IAC7C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC7C,6BAA6B;IAC7B,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9B,0EAA0E;IAC1E,KAAK,IAAI,IAAI,CAAC;IACd,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC/C;AAWD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,oHA+KxB,CAAC"}