@silverassist/recaptcha 0.1.0 → 0.2.1

package/dist/types/index.d.mts

@@ -1,9 +1,12 @@
 /**
- * reCAPTCHA v3 Integration Types
+ * @module @silverassist/recaptcha/types
+ * @description reCAPTCHA v3 Integration Types - Type definitions for Google
+ * reCAPTCHA v3 integration with Next.js.
  *
- * Type definitions for Google reCAPTCHA v3 integration with Next.js.
- *
- * @packageDocumentation
+ * @author Miguel Colmenares <me@miguelcolmenares.com>
+ * @license Polyform-Noncommercial-1.0.0
+ * @version 0.2.1
+ * @see {@link https://github.com/SilverAssist/recaptcha|GitHub Repository}
  */
 /**
  * reCAPTCHA v3 verification API response from Google
@@ -53,10 +56,34 @@ interface RecaptchaWrapperProps {
     siteKey?: string;
     /** Token refresh interval in ms (default: 90000 = 90 seconds) */
     refreshInterval?: number;
-    /** Callback when token is generated */
+    /**
+     * Callback when token is generated.
+     * @remarks Should be memoized with useCallback to prevent unnecessary re-renders.
+     * @example
+     * ```tsx
+     * const handleToken = useCallback((token: string) => {
+     *   console.log('Token:', token);
+     * }, []);
+     * <RecaptchaWrapper action="form" onTokenGenerated={handleToken} />
+     * ```
+     */
     onTokenGenerated?: (token: string) => void;
-    /** Callback when an error occurs */
+    /**
+     * Callback when an error occurs.
+     * @remarks Should be memoized with useCallback to prevent unnecessary re-renders.
+     * @example
+     * ```tsx
+     * const handleError = useCallback((error: Error) => {
+     *   console.error('reCAPTCHA error:', error);
+     * }, []);
+     * <RecaptchaWrapper action="form" onError={handleError} />
+     * ```
+     */
     onError?: (error: Error) => void;
+    /** Enable lazy loading (default: false for backward compatibility) */
+    lazy?: boolean;
+    /** IntersectionObserver rootMargin for lazy loading (default: "200px") */
+    lazyRootMargin?: string;
 }
 /**
  * Configuration options for reCAPTCHA validation
@@ -91,6 +118,15 @@ declare global {
                 action: string;
             }) => Promise<string>;
         };
+        /** Flag to track if reCAPTCHA script has loaded */
+        __recaptchaLoaded?: boolean;
+        /** Flag to track if reCAPTCHA script is currently loading */
+        __recaptchaLoading?: boolean;
+        /** Callbacks to execute when script finishes loading */
+        __recaptchaCallbacks?: Array<{
+            onLoad: () => void;
+            onError: (error: Error) => void;
+        }>;
     }
 }
 

package/dist/types/index.d.ts

@@ -1,9 +1,12 @@
 /**
- * reCAPTCHA v3 Integration Types
+ * @module @silverassist/recaptcha/types
+ * @description reCAPTCHA v3 Integration Types - Type definitions for Google
+ * reCAPTCHA v3 integration with Next.js.
  *
- * Type definitions for Google reCAPTCHA v3 integration with Next.js.
- *
- * @packageDocumentation
+ * @author Miguel Colmenares <me@miguelcolmenares.com>
+ * @license Polyform-Noncommercial-1.0.0
+ * @version 0.2.1
+ * @see {@link https://github.com/SilverAssist/recaptcha|GitHub Repository}
  */
 /**
  * reCAPTCHA v3 verification API response from Google
@@ -53,10 +56,34 @@ interface RecaptchaWrapperProps {
     siteKey?: string;
     /** Token refresh interval in ms (default: 90000 = 90 seconds) */
     refreshInterval?: number;
-    /** Callback when token is generated */
+    /**
+     * Callback when token is generated.
+     * @remarks Should be memoized with useCallback to prevent unnecessary re-renders.
+     * @example
+     * ```tsx
+     * const handleToken = useCallback((token: string) => {
+     *   console.log('Token:', token);
+     * }, []);
+     * <RecaptchaWrapper action="form" onTokenGenerated={handleToken} />
+     * ```
+     */
     onTokenGenerated?: (token: string) => void;
-    /** Callback when an error occurs */
+    /**
+     * Callback when an error occurs.
+     * @remarks Should be memoized with useCallback to prevent unnecessary re-renders.
+     * @example
+     * ```tsx
+     * const handleError = useCallback((error: Error) => {
+     *   console.error('reCAPTCHA error:', error);
+     * }, []);
+     * <RecaptchaWrapper action="form" onError={handleError} />
+     * ```
+     */
     onError?: (error: Error) => void;
+    /** Enable lazy loading (default: false for backward compatibility) */
+    lazy?: boolean;
+    /** IntersectionObserver rootMargin for lazy loading (default: "200px") */
+    lazyRootMargin?: string;
 }
 /**
  * Configuration options for reCAPTCHA validation
@@ -91,6 +118,15 @@ declare global {
                 action: string;
             }) => Promise<string>;
         };
+        /** Flag to track if reCAPTCHA script has loaded */
+        __recaptchaLoaded?: boolean;
+        /** Flag to track if reCAPTCHA script is currently loading */
+        __recaptchaLoading?: boolean;
+        /** Callbacks to execute when script finishes loading */
+        __recaptchaCallbacks?: Array<{
+            onLoad: () => void;
+            onError: (error: Error) => void;
+        }>;
     }
 }
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@silverassist/recaptcha",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Google reCAPTCHA v3 integration for Next.js applications with Server Actions support",
   "author": "Miguel Colmenares <me@miguelcolmenares.com>",
   "license": "Polyform-Noncommercial-1.0.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/SilverAssist/recaptcha.git"
+    "url": "git+https://github.com/SilverAssist/recaptcha.git"
   },
   "bugs": {
     "url": "https://github.com/SilverAssist/recaptcha/issues"
@@ -105,6 +105,7 @@
     "react-dom": ">=18.0.0"
   },
   "devDependencies": {
+    "@silverassist/copilot-prompts-kit": "^1.2.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@types/jest": "^30.0.0",