altcha 0.6.7 → 0.8.0

package/README.md

@@ -2,14 +2,15 @@
 
 ALTCHA uses a proof-of-work mechanism to protect your website, APIs, and online services from spam and abuse. Unlike other solutions, ALTCHA is self-hosted, does not use cookies nor fingerprinting, does not track users, and is fully compliant with GDPR.
 
-https://altcha.org
+Visit [ALTCHA](https://altcha.org) for more information.
 
-## Benefits
+## Features
 
-- __Friction-less__ - Using PoW instead of visual puzzles.
-- __Cookie-less__ - GDPR compliant by design.
-- __Self-hosted__ - Without reliance on external providers in self-hosted mode.
-- __SaaS available__ - Visit [altcha.org](https://altcha.org/docs/api) to get started with the SaaS API.
+- **Frictionless CAPTCHA Alternative** - Employs proof-of-work (PoW) instead of visual puzzles.
+- **Data Obfuscation** - Safeguards your email address from scraping.
+- **Cookie-less** - Designed to be GDPR compliant by default.
+- **Self-hosted** - Operates independently without relying on external providers.
+- **SaaS Available** - Get started with the SaaS API at [altcha.org/docs/api](https://altcha.org/docs/api).
 
 ## Examples
 
@@ -26,6 +27,9 @@ https://altcha.org
 - [PHP](https://github.com/altcha-org/altcha-lib-php)
 - [Go](https://github.com/altcha-org/altcha-lib-go)
 - [Python](https://github.com/altcha-org/altcha-lib-py)
+- [Java](https://github.com/altcha-org/altcha-lib-java)
+- [Ruby](https://github.com/altcha-org/altcha-lib-rb)
+- [Elixir](https://github.com/altcha-org/altcha-lib-ex)
 
 ## Plugins
 
@@ -89,7 +93,9 @@ Required options (at least one is required):
 
 Additional options:
 
+- __analytics__ - Enable analytics with [ALTCHA Forms](https://altcha.org/forms/). See [HTML submissions documentation](https://altcha.org/docs/forms/features/html-submissions).
 - __auto__ - Automatically verify without user interaction (possible values: `onfocus`, `onload`, `onsubmit`).
+- __beaconurl__ - URL to which analytics data will be sent using a beacon POST if the form is abandoned. This option is only used when `analytics` is enabled.
 - __blockspam__ - Only used in conjunction with the `spamfilter` option. If enabled, it will block form submission and fail verification if the Spam Filter returns a negative classification. This effectively prevents submission of the form.
 - __delay__ - The artificial delay in milliseconds to apply before the verification (defaults to 0).
 - __expire__ - The challenge expiration (duration in milliseconds).
@@ -100,10 +106,11 @@ Additional options:
 - __hidelogo__ - Hide the ALTCHA logo.
 - __maxnumber__ - The max. number to iterate to (defaults to 1,000,000).
 - __name__ - The name of the hidden field containing the payload (defaults to "altcha").
+- __obfuscated__ - The [obfuscated data](https://altcha.org/docs/obfuscation) provided as a base64-encoded string. Use only without `challengeurl`/`challengejson`.
 - __spamfilter__ - Enable [Spam Filter](#spam-filter).
-- __strings__ - JSON-encoded translation strings. Refer to [customization](/docs/widget-customization).
+- __strings__ - JSON-encoded translation strings. Refer to [customization](https://altcha.org/docs/widget-customization).
 - __refetchonexpire__ - Automatically re-fetch and re-validate when the challenge expires (defaults to true).
-- __verifyurl__ - Enable server-side verification by configuring the URL to use for verification requests. This option can be used in conjunction with `spamfilter` to enable server-side verification.
+- __verifyurl__ - URL for server-side verification requests. This option is automatically configured when the `spamfilter` option is used. Override this setting only if you are using a custom server implementation.
 - __workers__ - The number of workers to utilize for PoW (defaults to `navigator.hardwareConcurrency || 8`, max. value `16`).
 - __workerurl__ - The URL of the Worker script (defaults to `./worker.js`, only works with `external` build).
 
@@ -135,35 +142,42 @@ Available configuration options:
 
 ```ts
 export interface Configure {
-  auto?: 'onload' | 'onsubmit'; 
+  analytics?: boolean | string;
+  auto?: 'onfocus' | 'onload' | 'onsubmit';
+  beaconurl?: string;
   challenge?: {
     algorithm: string;
     challenge: string;
+    maxnumber?: number;
     salt: string;
     signature: string;
   };
+  challengeurl?: string;
   debug?: boolean;
   delay?: number;
   expire?: number;
   floating?: 'auto' | 'top' | 'bottom';
   floatinganchor?: string;
   floatingoffset?: number;
+  autorenew?: boolean;
   hidefooter?: boolean;
   hidelogo?: boolean;
   maxnumber?: number;
   mockerror?: boolean;
   name?: string;
+  obfuscated?: string;
   refetchonexpire?: boolean;
-  spamfilter: boolean | 'ipAddress' | SpamFilter;
+  spamfilter?: boolean | 'ipAddress' | SpamFilter;
   strings?: {
-    error?: string;
-    footer?: string;
-    label?: string;
-    verified?: string;
-    verifying?: string;
-    waitAlert?: string;
-  };
-  test?: boolean | number;
+    error: string;
+    expired: string;
+    footer: string;
+    label: string;
+    verified: string;
+    verifying: string;
+    waitAlert: string;
+  }
+  test?: boolean | number | 'delay';
   verifyurl?: string;
   workers?: number;
   workerurl?: string;
@@ -196,7 +210,7 @@ document.querySelector('#altcha').addEventListener('statechange', (ev) => {
 ```
 
 > [!IMPORTANT]  
-> Both programmatic configuration and event listeners have to called/attached after the ALTCHA script loads, such as within window.addEventListener('load', ...).
+> Both programmatic configuration and event listeners have to called/attached after the ALTCHA script loads, such as within `window.addEventListener('load', ...)`.
 
 ## Spam Filter
 

package/dist/altcha.d.ts

@@ -16,8 +16,10 @@ declare global {
 
   interface AltchaServerVerificationEvent extends CustomEvent<Record<string, unknown>> {}
 
-  interface AltchaWidget {
+  interface AltchaWidgetOptions {
+    analytics?: boolean | string;
     auto?: 'onfocus' | 'onload' | 'onsubmit';
+    beaconurl?: string;
     blockspam?: boolean;
     challengeurl?: string;
     challengejson?: string;
@@ -29,9 +31,10 @@ declare global {
     floatingoffset?: number;
     hidefooter?: boolean;
     hidelogo?: boolean;
-    name?: string;
     maxnumber?: number;
     mockerror?: boolean;
+    name?: string;
+    obfuscated?: string;
     refetchonexpire?: boolean;
     spamfilter?: boolean | 'ipAddress';
     strings?: string;
@@ -41,6 +44,16 @@ declare global {
     workerurl?: string;
   }
 
+  interface AltchaWidgetMethods {
+    configure: (options: AltchaWidgetOptions) => void;
+    clarify: () => Promise<void>;
+    reset: (newState: AltchaState = 'unverified', err: string | null = null) => void;
+    verify: () => Promise<void>;
+  }
+
+  interface AltchaWidget extends AltchaWidgetOptions extends AltchaWidgetMethods {
+  }
+
   declare namespace svelteHTML {
     interface IntrinsicElements {
       'altcha-widget': AltchaWidgetSvelte;
@@ -72,6 +85,7 @@ declare global {
     }
 
     interface AltchaWidgetReact extends AltchaWidget extends React.HTMLAttributes<HTMLElement> {
+      children?: React.ReactNode;
       ref?: React.RefObject<HTMLElement>;
       style?: AltchaWidgetCSSProperties;
     }