@nauth-toolkit/client-angular 0.1.91 → 0.1.92

package/lib/recaptcha.service.d.ts

@@ -0,0 +1,195 @@
+import { InjectionToken } from '@angular/core';
+import * as i0 from "@angular/core";
+/**
+ * Detects the current platform environment
+ */
+type Platform = 'web' | 'capacitor-webview' | 'capacitor-native' | 'ssr';
+/**
+ * reCAPTCHA version type
+ */
+type RecaptchaVersion = 'v2' | 'v3' | 'enterprise';
+/**
+ * reCAPTCHA configuration for RecaptchaService
+ *
+ * Internal configuration interface used by RecaptchaService.
+ * Use RecaptchaAngularConfig from tokens.ts for app configuration.
+ */
+export interface RecaptchaServiceConfig {
+    enabled: boolean;
+    version: RecaptchaVersion;
+    siteKey: string;
+    action?: string;
+    autoLoadScript?: boolean;
+    language?: string;
+}
+/**
+ * Injection token for reCAPTCHA configuration
+ */
+export declare const RECAPTCHA_CONFIG: InjectionToken<RecaptchaServiceConfig>;
+/**
+ * Google reCAPTCHA service for Angular applications.
+ *
+ * Provides lazy loading of reCAPTCHA script and platform-aware token generation.
+ * Automatically detects platform (web, Capacitor WebView, Capacitor native, SSR)
+ * and skips reCAPTCHA in environments where it's not supported or needed.
+ *
+ * Features:
+ * - Lazy script loading (only loads when needed)
+ * - v2 (checkbox) and v3 (invisible) support
+ * - Platform detection (web, Capacitor, SSR)
+ * - Automatic skip for Capacitor native mode
+ * - Automatic skip for SSR
+ *
+ * @example v3 Automatic Mode
+ * ```typescript
+ * constructor(private recaptcha: RecaptchaService) {}
+ *
+ * async login() {
+ *   const token = await this.recaptcha.execute('login');
+ *   await this.auth.login(email, password, token);
+ * }
+ * ```
+ *
+ * @example v2 Manual Mode
+ * ```typescript
+ * ngOnInit() {
+ *   this.recaptcha.render('recaptcha-container', (token) => {
+ *     this.recaptchaToken = token;
+ *   });
+ * }
+ * ```
+ */
+export declare class RecaptchaService {
+    private platformId;
+    private config?;
+    private scriptLoaded;
+    private scriptLoading;
+    private platform;
+    private widgetId;
+    constructor(platformId: string, config?: RecaptchaServiceConfig);
+    /**
+     * Detect the current platform environment.
+     *
+     * Detection priority:
+     * 1. SSR (not in browser) → 'ssr'
+     * 2. Capacitor native (no web view) → 'capacitor-native'
+     * 3. Capacitor WebView → 'capacitor-webview'
+     * 4. Web browser → 'web'
+     *
+     * @returns Detected platform type
+     *
+     * @example
+     * ```typescript
+     * const platform = this.detectPlatform();
+     * if (platform === 'capacitor-native') {
+     *   // Skip reCAPTCHA, use device attestation
+     * }
+     * ```
+     */
+    private detectPlatform;
+    /**
+     * Get the current platform.
+     *
+     * @returns Current platform type
+     */
+    getPlatform(): Platform;
+    /**
+     * Check if reCAPTCHA should be skipped for current platform.
+     *
+     * Skips for:
+     * - SSR (no window object)
+     * - Capacitor native (use device attestation instead)
+     *
+     * @returns True if should skip reCAPTCHA
+     */
+    shouldSkip(): boolean;
+    /**
+     * Load Google reCAPTCHA script if not already loaded.
+     *
+     * Script URL format:
+     * - v2: https://www.google.com/recaptcha/api.js
+     * - v3: https://www.google.com/recaptcha/api.js?render={siteKey}
+     * - Enterprise: https://www.google.com/recaptcha/enterprise.js?render={siteKey}
+     *
+     * @returns Promise that resolves when script is loaded
+     *
+     * @throws Error if config is missing or script fails to load
+     */
+    loadScript(): Promise<void>;
+    /**
+     * Inject the reCAPTCHA script into the DOM.
+     *
+     * @returns Promise that resolves when script loads
+     */
+    private injectScript;
+    /**
+     * Execute reCAPTCHA v3/Enterprise challenge (invisible).
+     *
+     * Automatically loads script if needed and generates a token.
+     * Skips automatically for SSR and Capacitor native.
+     *
+     * @param action - Action name for v3 analytics (e.g., 'login', 'signup')
+     * @returns Promise resolving to reCAPTCHA token, or undefined if skipped
+     *
+     * @throws Error if version is v2, config missing, or execution fails
+     *
+     * @example
+     * ```typescript
+     * const token = await this.recaptcha.execute('login');
+     * if (token) {
+     *   await this.auth.login(email, password, token);
+     * }
+     * ```
+     */
+    execute(action?: string): Promise<string | undefined>;
+    /**
+     * Render reCAPTCHA v2 checkbox widget.
+     *
+     * @param containerId - DOM element ID or element to render in
+     * @param callback - Callback when user completes challenge
+     * @returns Promise resolving to widget ID
+     *
+     * @throws Error if version is not v2, config missing, or render fails
+     *
+     * @example
+     * ```typescript
+     * ngAfterViewInit() {
+     *   this.recaptcha.render('recaptcha-container', (token) => {
+     *     this.recaptchaToken = token;
+     *     this.loginForm.patchValue({ recaptchaToken: token });
+     *   });
+     * }
+     * ```
+     */
+    render(containerId: string, callback: (token: string) => void): Promise<number>;
+    /**
+     * Get response token from v2 widget.
+     *
+     * @param widgetId - Widget ID (optional, uses last rendered widget if not provided)
+     * @returns reCAPTCHA token or null if not completed
+     *
+     * @example
+     * ```typescript
+     * const token = this.recaptcha.getResponse();
+     * if (token) {
+     *   await this.auth.login(email, password, token);
+     * }
+     * ```
+     */
+    getResponse(widgetId?: number): string | null;
+    /**
+     * Reset v2 widget (clear response).
+     *
+     * @param widgetId - Widget ID (optional, uses last rendered widget if not provided)
+     *
+     * @example
+     * ```typescript
+     * // After failed login
+     * this.recaptcha.reset();
+     * ```
+     */
+    reset(widgetId?: number): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RecaptchaService, [null, { optional: true; }]>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<RecaptchaService>;
+}
+export {};

package/lib/social-redirect-callback.guard.d.ts

@@ -12,6 +12,7 @@ import { type CanActivateFn } from '@angular/router';
  * - If `exchangeToken` exists: exchanges it via backend (SDK handles navigation automatically).
  * - If no `exchangeToken`: treat as cookie-success path (SDK handles navigation automatically).
  * - If `error` exists: redirects to oauthError route.
+ * - If auto-redirect is disabled (redirectUrls set to null): returns true to activate the route.
  *
  * @example
  * ```typescript

package/ngmodule/auth.service.d.ts

@@ -1,6 +1,7 @@
 import { Router } from '@angular/router';
 import { Observable } from 'rxjs';
 import { AngularHttpAdapter } from './http-adapter';
+import { RecaptchaService } from '../lib/recaptcha.service';
 import { NAuthClient, NAuthClientConfig, ChallengeResponse, AuthResponse, TokenResponse, AuthUser, ConfirmForgotPasswordResponse, ForgotPasswordResponse, ResetPasswordWithCodeResponse, UpdateProfileRequest, GetChallengeDataResponse, GetSetupDataResponse, MFAStatus, MFADevice, AuthEvent, SocialProvider, SocialLoginOptions, LinkedAccountsResponse, SocialVerifyRequest, AuditHistoryResponse, AdminOperations } from '@nauth-toolkit/client';
 import * as i0 from "@angular/core";
 /**
@@ -37,6 +38,7 @@ import * as i0 from "@angular/core";
  */
 export declare class AuthService {
     private router?;
+    private recaptchaService?;
     private readonly client;
     private readonly config;
     private readonly currentUserSubject;
@@ -48,8 +50,9 @@ export declare class AuthService {
      * @param config - Injected client configuration (required)
      * @param httpAdapter - Angular HTTP adapter for making requests (required)
      * @param router - Angular Router (optional, automatically used for navigation if available)
+     * @param recaptchaService - RecaptchaService (optional, for automatic token generation)
      */
-    constructor(config: NAuthClientConfig, httpAdapter: AngularHttpAdapter, router?: Router);
+    constructor(config: NAuthClientConfig, httpAdapter: AngularHttpAdapter, router?: Router, recaptchaService?: RecaptchaService);
     /**
      * Current user observable.
      */
@@ -105,28 +108,35 @@ export declare class AuthService {
     /**
      * Login with identifier and password.
      *
+     * Automatically generates reCAPTCHA token if configured (v3 only).
+     * For v2 manual mode, pass the token explicitly.
+     *
      * @param identifier - User email or username
      * @param password - User password
+     * @param recaptchaToken - Optional reCAPTCHA token (for v2 manual mode or when auto-generation is disabled)
      * @returns Promise with auth response or challenge
      *
-     * @example
+     * @example Basic Login
      * ```typescript
      * const response = await this.auth.login('user@example.com', 'password');
-     * if (response.challengeName) {
-     *   // Handle challenge
-     * } else {
-     *   // Login successful
-     * }
+     * ```
+     *
+     * @example With Manual reCAPTCHA (v2)
+     * ```typescript
+     * const response = await this.auth.login('user@example.com', 'password', recaptchaToken);
      * ```
      */
-    login(identifier: string, password: string): Promise<AuthResponse>;
+    login(identifier: string, password: string, recaptchaToken?: string): Promise<AuthResponse>;
     /**
      * Signup with credentials.
      *
+     * Automatically generates reCAPTCHA token if configured (v3 only).
+     * For v2 manual mode, include token in payload.
+     *
      * @param payload - Signup request payload
      * @returns Promise with auth response or challenge
      *
-     * @example
+     * @example Basic Signup
      * ```typescript
      * const response = await this.auth.signup({
      *   email: 'new@example.com',
@@ -134,6 +144,15 @@ export declare class AuthService {
      *   firstName: 'John',
      * });
      * ```
+     *
+     * @example With Manual reCAPTCHA (v2)
+     * ```typescript
+     * const response = await this.auth.signup({
+     *   email: 'new@example.com',
+     *   password: 'SecurePass123!',
+     *   recaptchaToken: token,
+     * });
+     * ```
      */
     signup(payload: Parameters<NAuthClient['signup']>[0]): Promise<AuthResponse>;
     /**
@@ -655,6 +674,22 @@ export declare class AuthService {
      * Update challenge state after auth response.
      */
     private updateChallengeState;
-    static ɵfac: i0.ɵɵFactoryDeclaration<AuthService, [null, null, { optional: true; }]>;
+    /**
+     * Get reCAPTCHA token - auto-generate for v3 or use provided token.
+     *
+     * Handles platform detection:
+     * - Web browser: Generate token if enabled and v3
+     * - Capacitor native: Skip (use device attestation instead)
+     * - SSR: Skip
+     * - Manual mode (v2 or manualChallenge=true): Requires explicit token
+     *
+     * @param providedToken - Explicitly provided token (v2 manual mode)
+     * @param action - Action name for v3 analytics
+     * @returns reCAPTCHA token or undefined
+     *
+     * @private
+     */
+    private getRecaptchaToken;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AuthService, [null, null, { optional: true; }, { optional: true; }]>;
     static ɵprov: i0.ɵɵInjectableDeclaration<AuthService>;
 }

package/ngmodule/tokens.d.ts

@@ -1,5 +1,102 @@
 import { InjectionToken } from '@angular/core';
 import { NAuthClientConfig } from '@nauth-toolkit/client';
+/**
+ * reCAPTCHA configuration for Angular client.
+ *
+ * Extends base client RecaptchaConfig with Angular-specific options.
+ *
+ * @example v3 Automatic Mode
+ * ```typescript
+ * {
+ *   enabled: true,
+ *   version: 'v3',
+ *   siteKey: '6LcExample_Site_Key',
+ *   action: 'login',
+ *   autoLoadScript: true,
+ * }
+ * ```
+ *
+ * @example v2 Manual Mode
+ * ```typescript
+ * {
+ *   enabled: true,
+ *   version: 'v2',
+ *   siteKey: '6LcExample_Site_Key',
+ *   manualChallenge: true,
+ * }
+ * ```
+ */
+export interface RecaptchaAngularConfig {
+    /**
+     * Enable/disable reCAPTCHA.
+     * Set to false to disable even if configured (useful for testing).
+     */
+    enabled: boolean;
+    /**
+     * reCAPTCHA version: v2 (checkbox), v3 (invisible), or enterprise.
+     */
+    version: 'v2' | 'v3' | 'enterprise';
+    /**
+     * Site key from Google reCAPTCHA console.
+     * This is safe to expose publicly (it's the public key).
+     */
+    siteKey: string;
+    /**
+     * Action name for v3/Enterprise analytics.
+     * Helps track which actions are being protected.
+     * Common values: 'login', 'signup', 'submit'
+     *
+     * @default 'submit'
+     */
+    action?: string;
+    /**
+     * Manual challenge mode (v2 only).
+     * If true, you must manually call RecaptchaService.render() and get token.
+     * If false, AuthService auto-generates token before login/signup.
+     *
+     * @default false
+     */
+    manualChallenge?: boolean;
+    /**
+     * Automatically load the Google reCAPTCHA script.
+     * If false, you must manually load the script.
+     *
+     * @default true
+     */
+    autoLoadScript?: boolean;
+    /**
+     * Language code for reCAPTCHA widget (v2 only).
+     * @example 'en', 'es', 'fr', 'de'
+     * @default Browser language
+     */
+    language?: string;
+}
+/**
+ * Angular-specific NAuth configuration.
+ *
+ * Extends base NAuthClientConfig with Angular-specific options.
+ *
+ * @example
+ * ```typescript
+ * const config: NAuthAngularConfig = {
+ *   baseUrl: 'https://api.example.com/auth',
+ *   tokenDelivery: 'cookies',
+ *   recaptcha: {
+ *     enabled: true,
+ *     version: 'v3',
+ *     siteKey: '6LcExample_Site_Key',
+ *     action: 'login',
+ *   },
+ * };
+ * ```
+ */
+export interface NAuthAngularConfig extends NAuthClientConfig {
+    /**
+     * Google reCAPTCHA configuration (optional).
+     * Provides bot protection for login/signup endpoints.
+     */
+    recaptcha?: RecaptchaAngularConfig;
+}
 /**
  * Injection token for providing NAuthClientConfig in Angular apps.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauth-toolkit/client-angular",
-  "version": "0.1.91",
+  "version": "0.1.92",
   "description": "Angular adapter for nauth-toolkit client SDK",
   "keywords": [
     "nauth",
@@ -24,7 +24,7 @@
   "peerDependencies": {
     "@angular/common": ">=17.0.0",
     "@angular/core": ">=17.0.0",
-    "@nauth-toolkit/client": "^0.1.91",
+    "@nauth-toolkit/client": "^0.1.92",
     "rxjs": "^7.0.0 || ^8.0.0"
   },
   "dependencies": {

package/public-api.d.ts

@@ -13,3 +13,4 @@ export * from './ngmodule/nauth.module';
 export * from './lib/auth.interceptor';
 export * from './lib/auth.guard';
 export * from './lib/social-redirect-callback.guard';
+export * from './lib/recaptcha.service';