ngx-recaptcha-v3 1.0.0

package/README.md

@@ -0,0 +1,275 @@
+# ngx-recaptcha-v3
+
+A production-grade, enterprise-ready, tree-shakable Angular library for integrating Google reCAPTCHA v2 (Checkbox & Invisible), v3, and Enterprise. Fully compatible with Angular 12 through 22, SSR‑safe (Universal), and native Angular Signals‑ready.
+
+---
+
+## Key Features
+
+- **Full Angular Compatibility**: Out‑of‑the‑box support for Angular 12 to 22.
+- **First‑Class Signals Support**: Decoupled `ngx-recaptcha-v3/signals` entry point for modern reactive applications (Angular 16+).
+- **SSR & Hydration Safe**: Strictly guards DOM operations on the server side using `isPlatformBrowser`.
+- **Zoneless Support**: Executes heavy execution logic outside `Zone.js` context for high performance.
+- **Dynamic Re‑Render**: V2 widget automatically re‑renders when inputs (theme, size, tabIndex, siteKey) change! No manual cleanup required!
+- **Tree‑Shakable Secondary Entry Points**: Only import what you use (`core`, `v2`, `v3`, `enterprise`, `signals`, `forms`, `testing`).
+- **ControlValueAccessor (CVA)**: Native support for Reactive Forms and Template‑driven Forms.
+- **Region & Domain Flex**: Easily switch between `google.com` and `recaptcha.net` (for restricted regions).
+
+---
+
+## Folder & Entrypoint Architecture
+
+To avoid breaking compilation in legacy Angular environments (versions 12–15) that do not support Signals, the codebase utilizes isolated secondary entry points:
+
+- `ngx-recaptcha-v3/core`: Script loading lifecycle, dynamic configuration tokens.
+- `ngx-recaptcha-v3/v2`: V2 Checkbox and Invisible component.
+- `ngx-recaptcha-v3/v3`: Score‑based execution service.
+- `ngx-recaptcha-v3/enterprise`: Score‑based Enterprise service.
+- `ngx-recaptcha-v3/forms`: Angular Forms ControlValueAccessor directive.
+- `ngx-recaptcha-v3/signals`: Reactive signals wrapper (Angular 16+ only).
+- `ngx-recaptcha-v3/testing`: Mock services and providers for Jest/Karma test isolation.
+
+---
+
+## Installation
+
+```bash
+npm install ngx-recaptcha-v3
+```
+
+Configure your global settings during the application bootstrap phase:
+
+### Standard Module Bootstrapping (Angular 12+)
+```typescript
+import { NgModule } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+import { RECAPTCHA_CONFIG, RecaptchaConfig } from 'ngx-recaptcha-v3/core';
+import { AppComponent } from './app.component';
+
+const recaptchaConfig: RecaptchaConfig = {
+  v2SiteKey: 'YOUR_V2_SITE_KEY',
+  v3SiteKey: 'YOUR_V3_SITE_KEY',
+  recaptchaDomain: 'google.com'
+};
+
+@NgModule({
+  declarations: [AppComponent],
+  imports: [BrowserModule],
+  providers: [
+    { provide: RECAPTCHA_CONFIG, useValue: recaptchaConfig }
+  ],
+  bootstrap: [AppComponent]
+})
+export class AppModule {}
+```
+
+### Standalone Bootstrapping (Angular 14+)
+```typescript
+import { bootstrapApplication } from '@angular/platform-browser';
+import { RECAPTCHA_CONFIG, RecaptchaConfig } from 'ngx-recaptcha-v3/core';
+import { AppComponent } from './app/app.component';
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    {
+      provide: RECAPTCHA_CONFIG,
+      useValue: {
+        v2SiteKey: 'YOUR_V2_SITE_KEY',
+        v3SiteKey: 'YOUR_V3_SITE_KEY',
+        useEnterprise: false
+      } as RecaptchaConfig
+    }
+  ]
+});
+```
+
+---
+
+## Usage Examples
+
+### 1. reCAPTCHA v2 Checkbox with Reactive Forms
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { FormGroup, FormControl, Validators, ReactiveFormsModule } from '@angular/forms';
+import { RecaptchaV2Component } from 'ngx-recaptcha-v3/v2';
+import { RecaptchaValueAccessorDirective } from 'ngx-recaptcha-v3/forms';
+
+@Component({
+  selector: 'app-login',
+  template: `
+    <form [formGroup]="loginForm" (ngSubmit)="onSubmit()">
+      <input formControlName="username" type="text" placeholder="Username" />
+      
+      <!-- Toggle theme to test dynamic re-render! -->
+      <div style="margin: 1rem 0;">
+        <label style="margin-right: 1rem;">
+          <input type="radio" [value]="'light'" (change)="setTheme('light')" [checked]="theme() === 'light'"> Light
+        </label>
+        <label>
+          <input type="radio" [value]="'dark'" (change)="setTheme('dark')" [checked]="theme() === 'dark'"> Dark
+        </label>
+      </div>
+      
+      <!-- CVA Directive Automatically Binds value to FormGroup -->
+      <ngx-recaptcha-v3 
+        [siteKey]="'YOUR_V2_SITE_KEY'"
+        [theme]="theme()"
+        formControlName="recaptcha">
+      </ngx-recaptcha-v3>
+      
+      <button [disabled]="loginForm.invalid" type="submit">Login</button>
+    </form>
+  `,
+  standalone: true,
+  imports: [ReactiveFormsModule, RecaptchaV2Component, RecaptchaValueAccessorDirective]
+})
+export class LoginComponent {
+  theme = signal<'light' | 'dark'>('light');
+  
+  loginForm = new FormGroup({
+    username: new FormControl('', Validators.required),
+    recaptcha: new FormControl(null, Validators.required)
+  });
+  
+  setTheme(newTheme: 'light' | 'dark'): void {
+    this.theme.set(newTheme);
+  }
+
+  onSubmit() {
+    console.log(this.loginForm.value);
+  }
+}
+```
+
+**Dynamic Re‑Render Feature**: `RecaptchaV2Component` now supports automatic re‑rendering when any of its inputs (siteKey, theme, size, tabIndex) change! This means you can dynamically switch between light/dark themes, or normal/compact/invisible sizes at runtime without any manual cleanup!
+
+### 2. reCAPTCHA v3 Execution Service (RxJS & Promise)
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { RecaptchaV3Service } from 'ngx-recaptcha-v3/v3';
+
+@Component({
+  selector: 'app-payment',
+  template: `
+    <div style="display: flex; gap: 1rem;">
+      <button (click)="processPaymentRxjs()">Pay Now (RxJS)</button>
+      <button (click)="processPaymentAsync()">Pay Now (Async/Await)</button>
+    </div>
+  `,
+  standalone: true
+})
+export class PaymentComponent {
+  private recaptchaV3 = inject(RecaptchaV3Service);
+
+  processPaymentRxjs(): void {
+    this.recaptchaV3.execute('checkout').subscribe({
+      next: (token) => {
+        // Send token to backend API for verification assessment
+        console.log('Action token resolved (RxJS):', token);
+      },
+      error: (err) => {
+        console.error('Resolution error (RxJS):', err);
+      }
+    });
+  }
+  
+  async processPaymentAsync(): Promise<void> {
+    try {
+      const token = await this.recaptchaV3.executeAsync('checkout');
+      console.log('Action token resolved (Async/Await):', token);
+    } catch (err) {
+      console.error('Resolution error (Async/Await):', err);
+    }
+  }
+}
+```
+
+### 3. Reactive Signals Integration (Angular 16+)
+
+```typescript
+import { Component, effect, inject } from '@angular/core';
+import { RecaptchaSignalService } from 'ngx-recaptcha-v3/signals';
+import { RecaptchaV2Component } from 'ngx-recaptcha-v3/v2';
+
+@Component({
+  selector: 'app-signals-page',
+  template: `
+    <ngx-recaptcha-v3 
+      [siteKey]="'YOUR_V2_SITE_KEY'"
+      (resolved)="recaptchaSignals.setToken($event)"
+      (error)="recaptchaSignals.setError('Load Error occurred')">
+    </ngx-recaptcha-v3>
+
+    @if (recaptchaSignals.verified()) {
+      <p>Verification successful! Token: {{ recaptchaSignals.token() }}</p>
+    }
+  `,
+  standalone: true,
+  imports: [RecaptchaV2Component]
+})
+export class SignalsPageComponent {
+  recaptchaSignals = inject(RecaptchaSignalService);
+  
+  constructor() {
+    // Intercept state reactively
+    effect(() => {
+      if (this.recaptchaSignals.verified()) {
+        console.log('User verified with token:', this.recaptchaSignals.token());
+      }
+    });
+  }
+}
+```
+
+---
+
+## SSR (Server‑Side Rendering) Support
+The library contains native safety guards. When rendering on a server environment, the script loading will gracefully bypass DOM manipulation and execute empty mock resolutions. This ensures standard universal/SSR pipelines do not trigger `window` or `document` reference execution errors.
+
+---
+
+## Unit Testing Setup
+
+The library provides testing mocks under the `/testing` sub‑entrypoint.
+
+```typescript
+import { TestBed } from '@angular/core/testing';
+import { RecaptchaV3Service } from 'ngx-recaptcha-v3/v3';
+import { RecaptchaMockV3Service } from 'ngx-recaptcha-v3/testing';
+
+describe('MyService', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [
+        { provide: RecaptchaV3Service, useClass: RecaptchaMockV3Service }
+      ]
+    });
+  });
+
+  // Your unit tests...
+});
+```
+
+---
+
+## Migration Guide (From `ng-recaptcha`)
+
+If migrating from legacy packages like `ng-recaptcha`:
+
+1. Remove old configurations and modules from your app imports.
+2. Update imports from `ng-recaptcha` to `ngx-recaptcha-v3/v2`, `ngx-recaptcha-v3/v3`, or `ngx-recaptcha-v3/core`.
+3. Provide settings using the unified configuration injection token: `RECAPTCHA_CONFIG`.
+4. Replace event listeners `(resolved)` with signals using `RecaptchaSignalService` if using Angular 16+.
+
+---
+
+## FAQ & Troubleshooting
+
+### Why is my reCAPTCHA script not loading?
+- Double‑check that you provided `v2SiteKey` or `v3SiteKey` inside the `RECAPTCHA_CONFIG` InjectionToken.
+- Verify that your network has direct access to `google.com` or switch config settings to use `recaptchaDomain: 'recaptcha.net'`.
+
+### Is it compatible with Angular Zoneless mode?
+Yes. The library is built with zoneless capability, utilizing custom element zones via `NgZone.runOutsideAngular` to handle script callbacks without triggering change detection cycles redundantly.

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "ngx-recaptcha-v3",
+  "version": "1.0.0",
+  "description": "A modern, standalone Google reCAPTCHA library for Angular supporting v2, v3, enterprise, reactive forms, and signals. Fully compatible with Angular versions 12–22",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Tapdiq49/ngx-recaptcha-v3"
+  },
+  "homepage": "https://github.com/Tapdiq49/ngx-recaptcha-v3/blob/main/README.md",
+  "keywords": [
+    "angular",
+    "recaptcha",
+    "google-recaptcha",
+    "ng-recaptcha",
+    "captcha",
+    "recaptcha-v2",
+    "recaptcha-v3",
+    "recaptcha-enterprise",
+    "angular-forms",
+    "control-value-accessor",
+    "angular-signals"
+  ],
+  "peerDependencies": {
+    "@angular/common": "^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0",
+    "@angular/core": "^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0",
+    "@angular/forms": "^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@angular/forms": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "author": "",
+  "license": "MIT",
+  "files": [
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "module": "fesm2022/ngx-recaptcha-v3.mjs",
+  "typings": "types/ngx-recaptcha-v3.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/ngx-recaptcha-v3.d.ts",
+      "default": "./fesm2022/ngx-recaptcha-v3.mjs"
+    },
+    "./core": {
+      "types": "./types/ngx-recaptcha-v3-core.d.ts",
+      "default": "./fesm2022/ngx-recaptcha-v3-core.mjs"
+    },
+    "./enterprise": {
+      "types": "./types/ngx-recaptcha-v3-enterprise.d.ts",
+      "default": "./fesm2022/ngx-recaptcha-v3-enterprise.mjs"
+    },
+    "./forms": {
+      "types": "./types/ngx-recaptcha-v3-forms.d.ts",
+      "default": "./fesm2022/ngx-recaptcha-v3-forms.mjs"
+    },
+    "./signals": {
+      "types": "./types/ngx-recaptcha-v3-signals.d.ts",
+      "default": "./fesm2022/ngx-recaptcha-v3-signals.mjs"
+    },
+    "./testing": {
+      "types": "./types/ngx-recaptcha-v3-testing.d.ts",
+      "default": "./fesm2022/ngx-recaptcha-v3-testing.mjs"
+    },
+    "./v2": {
+      "types": "./types/ngx-recaptcha-v3-v2.d.ts",
+      "default": "./fesm2022/ngx-recaptcha-v3-v2.mjs"
+    },
+    "./v3": {
+      "types": "./types/ngx-recaptcha-v3-v3.d.ts",
+      "default": "./fesm2022/ngx-recaptcha-v3-v3.mjs"
+    }
+  },
+  "sideEffects": false,
+  "type": "module"
+}