@silverassist/recaptcha 0.1.0

package/dist/types/index.d.mts

@@ -0,0 +1,97 @@
+/**
+ * reCAPTCHA v3 Integration Types
+ *
+ * Type definitions for Google reCAPTCHA v3 integration with Next.js.
+ *
+ * @packageDocumentation
+ */
+/**
+ * reCAPTCHA v3 verification API response from Google
+ *
+ * @see https://developers.google.com/recaptcha/docs/verify
+ */
+interface RecaptchaVerifyResponse {
+    /** Whether the verification was successful */
+    success: boolean;
+    /** Score between 0.0 and 1.0 (1.0 = very likely human) */
+    score: number;
+    /** Action name from the client */
+    action: string;
+    /** Timestamp of the challenge (ISO format) */
+    challenge_ts: string;
+    /** Hostname of the site where reCAPTCHA was solved */
+    hostname: string;
+    /** Error codes if verification failed */
+    "error-codes"?: string[];
+}
+/**
+ * Result of reCAPTCHA validation in server action
+ */
+interface RecaptchaValidationResult {
+    /** Whether the validation passed */
+    success: boolean;
+    /** The score from Google (0.0 - 1.0) */
+    score: number;
+    /** Error message if validation failed */
+    error?: string;
+    /** Whether validation was skipped (not configured) */
+    skipped?: boolean;
+    /** Raw response from Google API */
+    rawResponse?: RecaptchaVerifyResponse;
+}
+/**
+ * Props for RecaptchaWrapper client component
+ */
+interface RecaptchaWrapperProps {
+    /** Action name for reCAPTCHA analytics (e.g., "contact_form", "signup") */
+    action: string;
+    /** Name attribute for the hidden input (default: "recaptchaToken") */
+    inputName?: string;
+    /** ID attribute for the hidden input */
+    inputId?: string;
+    /** Override site key (default: uses NEXT_PUBLIC_RECAPTCHA_SITE_KEY) */
+    siteKey?: string;
+    /** Token refresh interval in ms (default: 90000 = 90 seconds) */
+    refreshInterval?: number;
+    /** Callback when token is generated */
+    onTokenGenerated?: (token: string) => void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+}
+/**
+ * Configuration options for reCAPTCHA validation
+ */
+interface RecaptchaConfig {
+    /** Google reCAPTCHA verification endpoint */
+    verifyUrl: string;
+    /** Default score threshold for validation */
+    defaultScoreThreshold: number;
+    /** Default token refresh interval in milliseconds */
+    tokenRefreshInterval: number;
+}
+/**
+ * Options for validateRecaptcha function
+ */
+interface RecaptchaValidationOptions {
+    /** Minimum score to pass (default: 0.5) */
+    scoreThreshold?: number;
+    /** Explicit secret key (default: uses RECAPTCHA_SECRET_KEY env) */
+    secretKey?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Global window interface extension for reCAPTCHA
+ */
+declare global {
+    interface Window {
+        grecaptcha: {
+            ready: (callback: () => void) => void;
+            execute: (siteKey: string, options: {
+                action: string;
+            }) => Promise<string>;
+        };
+    }
+}
+
+export type { RecaptchaConfig, RecaptchaValidationOptions, RecaptchaValidationResult, RecaptchaVerifyResponse, RecaptchaWrapperProps };

package/dist/types/index.d.ts

@@ -0,0 +1,97 @@
+/**
+ * reCAPTCHA v3 Integration Types
+ *
+ * Type definitions for Google reCAPTCHA v3 integration with Next.js.
+ *
+ * @packageDocumentation
+ */
+/**
+ * reCAPTCHA v3 verification API response from Google
+ *
+ * @see https://developers.google.com/recaptcha/docs/verify
+ */
+interface RecaptchaVerifyResponse {
+    /** Whether the verification was successful */
+    success: boolean;
+    /** Score between 0.0 and 1.0 (1.0 = very likely human) */
+    score: number;
+    /** Action name from the client */
+    action: string;
+    /** Timestamp of the challenge (ISO format) */
+    challenge_ts: string;
+    /** Hostname of the site where reCAPTCHA was solved */
+    hostname: string;
+    /** Error codes if verification failed */
+    "error-codes"?: string[];
+}
+/**
+ * Result of reCAPTCHA validation in server action
+ */
+interface RecaptchaValidationResult {
+    /** Whether the validation passed */
+    success: boolean;
+    /** The score from Google (0.0 - 1.0) */
+    score: number;
+    /** Error message if validation failed */
+    error?: string;
+    /** Whether validation was skipped (not configured) */
+    skipped?: boolean;
+    /** Raw response from Google API */
+    rawResponse?: RecaptchaVerifyResponse;
+}
+/**
+ * Props for RecaptchaWrapper client component
+ */
+interface RecaptchaWrapperProps {
+    /** Action name for reCAPTCHA analytics (e.g., "contact_form", "signup") */
+    action: string;
+    /** Name attribute for the hidden input (default: "recaptchaToken") */
+    inputName?: string;
+    /** ID attribute for the hidden input */
+    inputId?: string;
+    /** Override site key (default: uses NEXT_PUBLIC_RECAPTCHA_SITE_KEY) */
+    siteKey?: string;
+    /** Token refresh interval in ms (default: 90000 = 90 seconds) */
+    refreshInterval?: number;
+    /** Callback when token is generated */
+    onTokenGenerated?: (token: string) => void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+}
+/**
+ * Configuration options for reCAPTCHA validation
+ */
+interface RecaptchaConfig {
+    /** Google reCAPTCHA verification endpoint */
+    verifyUrl: string;
+    /** Default score threshold for validation */
+    defaultScoreThreshold: number;
+    /** Default token refresh interval in milliseconds */
+    tokenRefreshInterval: number;
+}
+/**
+ * Options for validateRecaptcha function
+ */
+interface RecaptchaValidationOptions {
+    /** Minimum score to pass (default: 0.5) */
+    scoreThreshold?: number;
+    /** Explicit secret key (default: uses RECAPTCHA_SECRET_KEY env) */
+    secretKey?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Global window interface extension for reCAPTCHA
+ */
+declare global {
+    interface Window {
+        grecaptcha: {
+            ready: (callback: () => void) => void;
+            execute: (siteKey: string, options: {
+                action: string;
+            }) => Promise<string>;
+        };
+    }
+}
+
+export type { RecaptchaConfig, RecaptchaValidationOptions, RecaptchaValidationResult, RecaptchaVerifyResponse, RecaptchaWrapperProps };

package/dist/types/index.js

@@ -0,0 +1,4 @@
+'use strict';
+
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/types/index.mjs

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/types/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.mjs"}

package/package.json

@@ -0,0 +1,123 @@
+{
+  "name": "@silverassist/recaptcha",
+  "version": "0.1.0",
+  "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"
+  },
+  "bugs": {
+    "url": "https://github.com/SilverAssist/recaptcha/issues"
+  },
+  "homepage": "https://github.com/SilverAssist/recaptcha#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "recaptcha",
+    "recaptcha-v3",
+    "google-recaptcha",
+    "nextjs",
+    "next",
+    "react",
+    "server-actions",
+    "spam-protection",
+    "bot-detection"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./client": {
+      "import": {
+        "types": "./dist/client/index.d.mts",
+        "default": "./dist/client/index.mjs"
+      },
+      "require": {
+        "types": "./dist/client/index.d.ts",
+        "default": "./dist/client/index.js"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/server/index.d.mts",
+        "default": "./dist/server/index.mjs"
+      },
+      "require": {
+        "types": "./dist/server/index.d.ts",
+        "default": "./dist/server/index.js"
+      }
+    },
+    "./types": {
+      "import": {
+        "types": "./dist/types/index.d.mts",
+        "default": "./dist/types/index.mjs"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/types/index.js"
+      }
+    },
+    "./constants": {
+      "import": {
+        "types": "./dist/constants/index.d.mts",
+        "default": "./dist/constants/index.mjs"
+      },
+      "require": {
+        "types": "./dist/constants/index.d.ts",
+        "default": "./dist/constants/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup && node add-use-client.js",
+    "dev": "tsup --watch",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run lint && npm run build && npm run test",
+    "release": "npm run prepublishOnly && npm publish --access public"
+  },
+  "peerDependencies": {
+    "next": ">=14.0.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.0.10",
+    "@types/react": "^19.2.9",
+    "@types/react-dom": "^19.2.3",
+    "jest": "^30.2.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "next": "^16.1.5",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "ts-jest": "^29.4.6",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}