@silverassist/recaptcha 0.1.0

package/dist/index.mjs

@@ -0,0 +1,206 @@
+import Script from 'next/script';
+import { useRef, useCallback, useEffect } from 'react';
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
+
+// src/client/index.tsx
+
+// src/constants/index.ts
+var DEFAULT_SCORE_THRESHOLD = 0.5;
+var DEFAULT_TOKEN_REFRESH_INTERVAL = 9e4;
+var RECAPTCHA_CONFIG = {
+  /** Google reCAPTCHA verification endpoint */
+  verifyUrl: "https://www.google.com/recaptcha/api/siteverify",
+  /** Default score threshold for validation */
+  defaultScoreThreshold: DEFAULT_SCORE_THRESHOLD,
+  /** Default token refresh interval */
+  tokenRefreshInterval: DEFAULT_TOKEN_REFRESH_INTERVAL
+};
+function RecaptchaWrapper({
+  action,
+  inputName = "recaptchaToken",
+  inputId = "recaptcha-token",
+  siteKey: propSiteKey,
+  refreshInterval = RECAPTCHA_CONFIG.tokenRefreshInterval,
+  onTokenGenerated,
+  onError
+}) {
+  const siteKey = propSiteKey ?? process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY;
+  const tokenInputRef = useRef(null);
+  const refreshIntervalRef = useRef(null);
+  const executeRecaptcha = useCallback(async () => {
+    if (!siteKey) {
+      return;
+    }
+    try {
+      if (typeof window !== "undefined" && window.grecaptcha) {
+        window.grecaptcha.ready(async () => {
+          try {
+            const token = await window.grecaptcha.execute(siteKey, { action });
+            if (tokenInputRef.current) {
+              tokenInputRef.current.value = token;
+            }
+            if (onTokenGenerated) {
+              onTokenGenerated(token);
+            }
+          } catch (error) {
+            console.error("[reCAPTCHA] Error executing reCAPTCHA:", error);
+            if (onError && error instanceof Error) {
+              onError(error);
+            }
+          }
+        });
+      }
+    } catch (error) {
+      console.error("[reCAPTCHA] Error:", error);
+      if (onError && error instanceof Error) {
+        onError(error);
+      }
+    }
+  }, [siteKey, action, onTokenGenerated, onError]);
+  useEffect(() => {
+    executeRecaptcha();
+    refreshIntervalRef.current = setInterval(() => {
+      executeRecaptcha();
+    }, refreshInterval);
+    return () => {
+      if (refreshIntervalRef.current) {
+        clearInterval(refreshIntervalRef.current);
+      }
+    };
+  }, [executeRecaptcha, refreshInterval]);
+  if (!siteKey) {
+    if (process.env.NODE_ENV === "development") {
+      console.warn(
+        "[reCAPTCHA] Site key not configured. Set NEXT_PUBLIC_RECAPTCHA_SITE_KEY environment variable."
+      );
+    }
+    return null;
+  }
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(
+      "input",
+      {
+        ref: tokenInputRef,
+        type: "hidden",
+        name: inputName,
+        id: inputId,
+        "data-testid": "recaptcha-token-input"
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      Script,
+      {
+        src: `https://www.google.com/recaptcha/api.js?render=${siteKey}`,
+        strategy: "afterInteractive",
+        onLoad: () => {
+          executeRecaptcha();
+        },
+        onError: () => {
+          console.error("[reCAPTCHA] Failed to load reCAPTCHA script");
+          if (onError) {
+            onError(new Error("Failed to load reCAPTCHA script"));
+          }
+        }
+      }
+    )
+  ] });
+}
+
+// src/server/index.ts
+async function validateRecaptcha(token, expectedAction, options = {}) {
+  const {
+    scoreThreshold = DEFAULT_SCORE_THRESHOLD,
+    secretKey = process.env.RECAPTCHA_SECRET_KEY,
+    debug = process.env.NODE_ENV === "development"
+  } = options;
+  if (!secretKey) {
+    if (debug) {
+      console.warn(
+        "[reCAPTCHA] Secret key not configured. Skipping validation."
+      );
+    }
+    return {
+      success: true,
+      score: 1,
+      skipped: true
+    };
+  }
+  if (!token) {
+    return {
+      success: false,
+      score: 0,
+      error: "reCAPTCHA token is missing"
+    };
+  }
+  try {
+    const response = await fetch(RECAPTCHA_CONFIG.verifyUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body: new URLSearchParams({
+        secret: secretKey,
+        response: token
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+    const data = await response.json();
+    if (debug) {
+      console.log("[reCAPTCHA] Verification response:", {
+        success: data.success,
+        score: data.score,
+        action: data.action,
+        hostname: data.hostname
+      });
+    }
+    if (!data.success) {
+      return {
+        success: false,
+        score: 0,
+        error: `reCAPTCHA verification failed: ${data["error-codes"]?.join(", ") || "Unknown error"}`,
+        rawResponse: data
+      };
+    }
+    if (data.score < scoreThreshold) {
+      return {
+        success: false,
+        score: data.score,
+        error: `reCAPTCHA score too low: ${data.score} (threshold: ${scoreThreshold})`,
+        rawResponse: data
+      };
+    }
+    if (expectedAction && data.action !== expectedAction) {
+      return {
+        success: false,
+        score: data.score,
+        error: `reCAPTCHA action mismatch: expected "${expectedAction}", got "${data.action}"`,
+        rawResponse: data
+      };
+    }
+    return {
+      success: true,
+      score: data.score,
+      rawResponse: data
+    };
+  } catch (error) {
+    console.error("[reCAPTCHA] Validation error:", error);
+    return {
+      success: false,
+      score: 0,
+      error: error instanceof Error ? `reCAPTCHA validation error: ${error.message}` : "reCAPTCHA validation error"
+    };
+  }
+}
+function isRecaptchaEnabled(secretKey) {
+  return !!(secretKey ?? process.env.RECAPTCHA_SECRET_KEY);
+}
+function getRecaptchaToken(formData, fieldName = "recaptchaToken") {
+  const token = formData.get(fieldName);
+  return typeof token === "string" ? token : null;
+}
+
+export { DEFAULT_SCORE_THRESHOLD, DEFAULT_TOKEN_REFRESH_INTERVAL, RECAPTCHA_CONFIG, RecaptchaWrapper, getRecaptchaToken, isRecaptchaEnabled, validateRecaptcha };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constants/index.ts","../src/client/index.tsx","../src/server/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * reCAPTCHA Configuration Constants\n *\n * Default configuration values for reCAPTCHA v3 integration.\n *\n * @packageDocumentation\n */\n\nimport type { RecaptchaConfig } from \"../types\";\n\n/**\n * Default score threshold for validation\n * Scores below this value are considered suspicious\n * Range: 0.0 (bot) to 1.0 (human)\n */\nexport const DEFAULT_SCORE_THRESHOLD = 0.5;\n\n/**\n * Token refresh interval in milliseconds\n * reCAPTCHA tokens expire after 2 minutes, so we refresh at 90 seconds\n * to ensure tokens are always valid when forms are submitted\n */\nexport const DEFAULT_TOKEN_REFRESH_INTERVAL = 90000;\n\n/**\n * reCAPTCHA v3 configuration constants\n */\nexport const RECAPTCHA_CONFIG: RecaptchaConfig = {\n  /** Google reCAPTCHA verification endpoint */\n  verifyUrl: \"https://www.google.com/recaptcha/api/siteverify\",\n  /** Default score threshold for validation */\n  defaultScoreThreshold: DEFAULT_SCORE_THRESHOLD,\n  /** Default token refresh interval */\n  tokenRefreshInterval: DEFAULT_TOKEN_REFRESH_INTERVAL,\n} as const;\n","/**\n * reCAPTCHA v3 Client Component\n *\n * Loads the Google reCAPTCHA script and generates tokens automatically.\n * Place inside a form to add invisible spam protection.\n *\n * @see https://developers.google.com/recaptcha/docs/v3\n * @packageDocumentation\n */\n\n\"use client\";\n\nimport Script from \"next/script\";\nimport { useCallback, useEffect, useRef } from \"react\";\nimport type { RecaptchaWrapperProps } from \"../types\";\nimport { RECAPTCHA_CONFIG } from \"../constants\";\n\n/**\n * RecaptchaWrapper - Client component for reCAPTCHA v3 integration\n *\n * Features:\n * - Loads reCAPTCHA script automatically\n * - Generates token when script loads\n * - Refreshes token periodically (tokens expire after 2 minutes)\n * - Stores token in hidden input field for form submission\n * - Graceful fallback when not configured\n *\n * @example Basic usage\n * ```tsx\n * <form action={formAction}>\n *   <RecaptchaWrapper action=\"contact_form\" />\n *   <input name=\"email\" type=\"email\" required />\n *   <button type=\"submit\">Submit</button>\n * </form>\n * ```\n *\n * @example Custom input name\n * ```tsx\n * <RecaptchaWrapper\n *   action=\"signup\"\n *   inputName=\"captchaToken\"\n *   inputId=\"signup-captcha\"\n * />\n * ```\n *\n * @example With callbacks\n * ```tsx\n * <RecaptchaWrapper\n *   action=\"payment\"\n *   onTokenGenerated={(token) => console.log(\"Token:\", token)}\n *   onError={(error) => console.error(\"Error:\", error)}\n * />\n * ```\n */\nexport function RecaptchaWrapper({\n  action,\n  inputName = \"recaptchaToken\",\n  inputId = \"recaptcha-token\",\n  siteKey: propSiteKey,\n  refreshInterval = RECAPTCHA_CONFIG.tokenRefreshInterval,\n  onTokenGenerated,\n  onError,\n}: RecaptchaWrapperProps) {\n  // Use prop siteKey or fall back to environment variable\n  const siteKey = propSiteKey ?? process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY;\n  const tokenInputRef = useRef<HTMLInputElement>(null);\n  const refreshIntervalRef = useRef<NodeJS.Timeout | null>(null);\n\n  // Execute reCAPTCHA and store token\n  const executeRecaptcha = useCallback(async () => {\n    if (!siteKey) {\n      return;\n    }\n\n    try {\n      if (typeof window !== \"undefined\" && window.grecaptcha) {\n        window.grecaptcha.ready(async () => {\n          try {\n            const token = await window.grecaptcha.execute(siteKey, { action });\n\n            // Store token in hidden input\n            if (tokenInputRef.current) {\n              tokenInputRef.current.value = token;\n            }\n\n            // Call callback if provided\n            if (onTokenGenerated) {\n              onTokenGenerated(token);\n            }\n          } catch (error) {\n            console.error(\"[reCAPTCHA] Error executing reCAPTCHA:\", error);\n            if (onError && error instanceof Error) {\n              onError(error);\n            }\n          }\n        });\n      }\n    } catch (error) {\n      console.error(\"[reCAPTCHA] Error:\", error);\n      if (onError && error instanceof Error) {\n        onError(error);\n      }\n    }\n  }, [siteKey, action, onTokenGenerated, onError]);\n\n  // Set up token refresh interval (tokens expire after 2 minutes)\n  useEffect(() => {\n    // Generate token immediately when component mounts\n    executeRecaptcha();\n\n    // Set up refresh interval\n    refreshIntervalRef.current = setInterval(() => {\n      executeRecaptcha();\n    }, refreshInterval);\n\n    // Cleanup interval on unmount\n    return () => {\n      if (refreshIntervalRef.current) {\n        clearInterval(refreshIntervalRef.current);\n      }\n    };\n  }, [executeRecaptcha, refreshInterval]);\n\n  // Don't render anything if site key is not configured\n  if (!siteKey) {\n    if (process.env.NODE_ENV === \"development\") {\n      console.warn(\n        \"[reCAPTCHA] Site key not configured. Set NEXT_PUBLIC_RECAPTCHA_SITE_KEY environment variable.\"\n      );\n    }\n    return null;\n  }\n\n  return (\n    <>\n      {/* Hidden input to store the token */}\n      <input\n        ref={tokenInputRef}\n        type=\"hidden\"\n        name={inputName}\n        id={inputId}\n        data-testid=\"recaptcha-token-input\"\n      />\n\n      {/* Load reCAPTCHA script */}\n      <Script\n        src={`https://www.google.com/recaptcha/api.js?render=${siteKey}`}\n        strategy=\"afterInteractive\"\n        onLoad={() => {\n          executeRecaptcha();\n        }}\n        onError={() => {\n          console.error(\"[reCAPTCHA] Failed to load reCAPTCHA script\");\n          if (onError) {\n            onError(new Error(\"Failed to load reCAPTCHA script\"));\n          }\n        }}\n      />\n    </>\n  );\n}\n\nexport default RecaptchaWrapper;\n","/**\n * reCAPTCHA v3 Server-Side Validation\n *\n * Functions for validating reCAPTCHA tokens in Next.js Server Actions.\n *\n * @see https://developers.google.com/recaptcha/docs/verify\n * @packageDocumentation\n */\n\nimport type {\n  RecaptchaValidationResult,\n  RecaptchaVerifyResponse,\n  RecaptchaValidationOptions,\n} from \"../types\";\nimport { RECAPTCHA_CONFIG, DEFAULT_SCORE_THRESHOLD } from \"../constants\";\n\n/**\n * Validate a reCAPTCHA token with Google's API\n *\n * @param token - The reCAPTCHA token from the client\n * @param expectedAction - The expected action name (optional, for extra security)\n * @param options - Additional validation options\n * @returns Validation result with success status and score\n *\n * @example Basic validation\n * ```ts\n * const result = await validateRecaptcha(token, \"contact_form\");\n * if (!result.success) {\n *   return { success: false, message: result.error };\n * }\n * ```\n *\n * @example Custom threshold for sensitive forms\n * ```ts\n * const result = await validateRecaptcha(token, \"payment_form\", {\n *   scoreThreshold: 0.7, // Higher threshold for payments\n *   secretKey: process.env.RECAPTCHA_SECRET_KEY,\n * });\n * ```\n *\n * @example Skip validation in development\n * ```ts\n * const result = await validateRecaptcha(token, \"test_form\", {\n *   debug: true, // Enable debug logging\n * });\n * // Returns { success: true, score: 1, skipped: true } if not configured\n * ```\n */\nexport async function validateRecaptcha(\n  token: string | null | undefined,\n  expectedAction?: string,\n  options: RecaptchaValidationOptions = {}\n): Promise<RecaptchaValidationResult> {\n  const {\n    scoreThreshold = DEFAULT_SCORE_THRESHOLD,\n    secretKey = process.env.RECAPTCHA_SECRET_KEY,\n    debug = process.env.NODE_ENV === \"development\",\n  } = options;\n\n  // Check if reCAPTCHA is configured\n  if (!secretKey) {\n    if (debug) {\n      console.warn(\n        \"[reCAPTCHA] Secret key not configured. Skipping validation.\"\n      );\n    }\n    return {\n      success: true,\n      score: 1,\n      skipped: true,\n    };\n  }\n\n  // Check if token is provided\n  if (!token) {\n    return {\n      success: false,\n      score: 0,\n      error: \"reCAPTCHA token is missing\",\n    };\n  }\n\n  try {\n    // Verify token with Google\n    const response = await fetch(RECAPTCHA_CONFIG.verifyUrl, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/x-www-form-urlencoded\",\n      },\n      body: new URLSearchParams({\n        secret: secretKey,\n        response: token,\n      }),\n    });\n\n    if (!response.ok) {\n      throw new Error(`HTTP error! status: ${response.status}`);\n    }\n\n    const data: RecaptchaVerifyResponse = await response.json();\n\n    if (debug) {\n      console.log(\"[reCAPTCHA] Verification response:\", {\n        success: data.success,\n        score: data.score,\n        action: data.action,\n        hostname: data.hostname,\n      });\n    }\n\n    // Check if verification failed\n    if (!data.success) {\n      return {\n        success: false,\n        score: 0,\n        error: `reCAPTCHA verification failed: ${data[\"error-codes\"]?.join(\", \") || \"Unknown error\"}`,\n        rawResponse: data,\n      };\n    }\n\n    // Check score threshold\n    if (data.score < scoreThreshold) {\n      return {\n        success: false,\n        score: data.score,\n        error: `reCAPTCHA score too low: ${data.score} (threshold: ${scoreThreshold})`,\n        rawResponse: data,\n      };\n    }\n\n    // Check action if provided\n    if (expectedAction && data.action !== expectedAction) {\n      return {\n        success: false,\n        score: data.score,\n        error: `reCAPTCHA action mismatch: expected \"${expectedAction}\", got \"${data.action}\"`,\n        rawResponse: data,\n      };\n    }\n\n    // Validation passed\n    return {\n      success: true,\n      score: data.score,\n      rawResponse: data,\n    };\n  } catch (error) {\n    console.error(\"[reCAPTCHA] Validation error:\", error);\n    return {\n      success: false,\n      score: 0,\n      error:\n        error instanceof Error\n          ? `reCAPTCHA validation error: ${error.message}`\n          : \"reCAPTCHA validation error\",\n    };\n  }\n}\n\n/**\n * Check if reCAPTCHA is enabled (secret key is configured)\n *\n * @param secretKey - Optional explicit secret key to check\n * @returns true if reCAPTCHA is configured\n *\n * @example\n * ```ts\n * if (isRecaptchaEnabled()) {\n *   // Require reCAPTCHA validation\n * } else {\n *   // Skip validation in development\n * }\n * ```\n */\nexport function isRecaptchaEnabled(secretKey?: string): boolean {\n  return !!(secretKey ?? process.env.RECAPTCHA_SECRET_KEY);\n}\n\n/**\n * Extract reCAPTCHA token from FormData\n *\n * @param formData - Form data containing the token\n * @param fieldName - Name of the token field (default: \"recaptchaToken\")\n * @returns The token string or null\n *\n * @example\n * ```ts\n * export async function submitForm(prevState: State, formData: FormData) {\n *   const token = getRecaptchaToken(formData);\n *   const result = await validateRecaptcha(token, \"contact_form\");\n *   // ...\n * }\n * ```\n */\nexport function getRecaptchaToken(\n  formData: FormData,\n  fieldName: string = \"recaptchaToken\"\n): string | null {\n  const token = formData.get(fieldName);\n  return typeof token === \"string\" ? token : null;\n}\n"]}

package/dist/server/index.d.mts

@@ -0,0 +1,79 @@
+import { RecaptchaValidationOptions, RecaptchaValidationResult } from '../types/index.mjs';
+
+/**
+ * reCAPTCHA v3 Server-Side Validation
+ *
+ * Functions for validating reCAPTCHA tokens in Next.js Server Actions.
+ *
+ * @see https://developers.google.com/recaptcha/docs/verify
+ * @packageDocumentation
+ */
+
+/**
+ * Validate a reCAPTCHA token with Google's API
+ *
+ * @param token - The reCAPTCHA token from the client
+ * @param expectedAction - The expected action name (optional, for extra security)
+ * @param options - Additional validation options
+ * @returns Validation result with success status and score
+ *
+ * @example Basic validation
+ * ```ts
+ * const result = await validateRecaptcha(token, "contact_form");
+ * if (!result.success) {
+ *   return { success: false, message: result.error };
+ * }
+ * ```
+ *
+ * @example Custom threshold for sensitive forms
+ * ```ts
+ * const result = await validateRecaptcha(token, "payment_form", {
+ *   scoreThreshold: 0.7, // Higher threshold for payments
+ *   secretKey: process.env.RECAPTCHA_SECRET_KEY,
+ * });
+ * ```
+ *
+ * @example Skip validation in development
+ * ```ts
+ * const result = await validateRecaptcha(token, "test_form", {
+ *   debug: true, // Enable debug logging
+ * });
+ * // Returns { success: true, score: 1, skipped: true } if not configured
+ * ```
+ */
+declare function validateRecaptcha(token: string | null | undefined, expectedAction?: string, options?: RecaptchaValidationOptions): Promise<RecaptchaValidationResult>;
+/**
+ * Check if reCAPTCHA is enabled (secret key is configured)
+ *
+ * @param secretKey - Optional explicit secret key to check
+ * @returns true if reCAPTCHA is configured
+ *
+ * @example
+ * ```ts
+ * if (isRecaptchaEnabled()) {
+ *   // Require reCAPTCHA validation
+ * } else {
+ *   // Skip validation in development
+ * }
+ * ```
+ */
+declare function isRecaptchaEnabled(secretKey?: string): boolean;
+/**
+ * Extract reCAPTCHA token from FormData
+ *
+ * @param formData - Form data containing the token
+ * @param fieldName - Name of the token field (default: "recaptchaToken")
+ * @returns The token string or null
+ *
+ * @example
+ * ```ts
+ * export async function submitForm(prevState: State, formData: FormData) {
+ *   const token = getRecaptchaToken(formData);
+ *   const result = await validateRecaptcha(token, "contact_form");
+ *   // ...
+ * }
+ * ```
+ */
+declare function getRecaptchaToken(formData: FormData, fieldName?: string): string | null;
+
+export { getRecaptchaToken, isRecaptchaEnabled, validateRecaptcha };

package/dist/server/index.d.ts

@@ -0,0 +1,79 @@
+import { RecaptchaValidationOptions, RecaptchaValidationResult } from '../types/index.js';
+
+/**
+ * reCAPTCHA v3 Server-Side Validation
+ *
+ * Functions for validating reCAPTCHA tokens in Next.js Server Actions.
+ *
+ * @see https://developers.google.com/recaptcha/docs/verify
+ * @packageDocumentation
+ */
+
+/**
+ * Validate a reCAPTCHA token with Google's API
+ *
+ * @param token - The reCAPTCHA token from the client
+ * @param expectedAction - The expected action name (optional, for extra security)
+ * @param options - Additional validation options
+ * @returns Validation result with success status and score
+ *
+ * @example Basic validation
+ * ```ts
+ * const result = await validateRecaptcha(token, "contact_form");
+ * if (!result.success) {
+ *   return { success: false, message: result.error };
+ * }
+ * ```
+ *
+ * @example Custom threshold for sensitive forms
+ * ```ts
+ * const result = await validateRecaptcha(token, "payment_form", {
+ *   scoreThreshold: 0.7, // Higher threshold for payments
+ *   secretKey: process.env.RECAPTCHA_SECRET_KEY,
+ * });
+ * ```
+ *
+ * @example Skip validation in development
+ * ```ts
+ * const result = await validateRecaptcha(token, "test_form", {
+ *   debug: true, // Enable debug logging
+ * });
+ * // Returns { success: true, score: 1, skipped: true } if not configured
+ * ```
+ */
+declare function validateRecaptcha(token: string | null | undefined, expectedAction?: string, options?: RecaptchaValidationOptions): Promise<RecaptchaValidationResult>;
+/**
+ * Check if reCAPTCHA is enabled (secret key is configured)
+ *
+ * @param secretKey - Optional explicit secret key to check
+ * @returns true if reCAPTCHA is configured
+ *
+ * @example
+ * ```ts
+ * if (isRecaptchaEnabled()) {
+ *   // Require reCAPTCHA validation
+ * } else {
+ *   // Skip validation in development
+ * }
+ * ```
+ */
+declare function isRecaptchaEnabled(secretKey?: string): boolean;
+/**
+ * Extract reCAPTCHA token from FormData
+ *
+ * @param formData - Form data containing the token
+ * @param fieldName - Name of the token field (default: "recaptchaToken")
+ * @returns The token string or null
+ *
+ * @example
+ * ```ts
+ * export async function submitForm(prevState: State, formData: FormData) {
+ *   const token = getRecaptchaToken(formData);
+ *   const result = await validateRecaptcha(token, "contact_form");
+ *   // ...
+ * }
+ * ```
+ */
+declare function getRecaptchaToken(formData: FormData, fieldName?: string): string | null;
+
+export { getRecaptchaToken, isRecaptchaEnabled, validateRecaptcha };

package/dist/server/index.js

@@ -0,0 +1,114 @@
+'use strict';
+
+// src/constants/index.ts
+var DEFAULT_SCORE_THRESHOLD = 0.5;
+var DEFAULT_TOKEN_REFRESH_INTERVAL = 9e4;
+var RECAPTCHA_CONFIG = {
+  /** Google reCAPTCHA verification endpoint */
+  verifyUrl: "https://www.google.com/recaptcha/api/siteverify",
+  /** Default score threshold for validation */
+  defaultScoreThreshold: DEFAULT_SCORE_THRESHOLD,
+  /** Default token refresh interval */
+  tokenRefreshInterval: DEFAULT_TOKEN_REFRESH_INTERVAL
+};
+
+// src/server/index.ts
+async function validateRecaptcha(token, expectedAction, options = {}) {
+  const {
+    scoreThreshold = DEFAULT_SCORE_THRESHOLD,
+    secretKey = process.env.RECAPTCHA_SECRET_KEY,
+    debug = process.env.NODE_ENV === "development"
+  } = options;
+  if (!secretKey) {
+    if (debug) {
+      console.warn(
+        "[reCAPTCHA] Secret key not configured. Skipping validation."
+      );
+    }
+    return {
+      success: true,
+      score: 1,
+      skipped: true
+    };
+  }
+  if (!token) {
+    return {
+      success: false,
+      score: 0,
+      error: "reCAPTCHA token is missing"
+    };
+  }
+  try {
+    const response = await fetch(RECAPTCHA_CONFIG.verifyUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body: new URLSearchParams({
+        secret: secretKey,
+        response: token
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+    const data = await response.json();
+    if (debug) {
+      console.log("[reCAPTCHA] Verification response:", {
+        success: data.success,
+        score: data.score,
+        action: data.action,
+        hostname: data.hostname
+      });
+    }
+    if (!data.success) {
+      return {
+        success: false,
+        score: 0,
+        error: `reCAPTCHA verification failed: ${data["error-codes"]?.join(", ") || "Unknown error"}`,
+        rawResponse: data
+      };
+    }
+    if (data.score < scoreThreshold) {
+      return {
+        success: false,
+        score: data.score,
+        error: `reCAPTCHA score too low: ${data.score} (threshold: ${scoreThreshold})`,
+        rawResponse: data
+      };
+    }
+    if (expectedAction && data.action !== expectedAction) {
+      return {
+        success: false,
+        score: data.score,
+        error: `reCAPTCHA action mismatch: expected "${expectedAction}", got "${data.action}"`,
+        rawResponse: data
+      };
+    }
+    return {
+      success: true,
+      score: data.score,
+      rawResponse: data
+    };
+  } catch (error) {
+    console.error("[reCAPTCHA] Validation error:", error);
+    return {
+      success: false,
+      score: 0,
+      error: error instanceof Error ? `reCAPTCHA validation error: ${error.message}` : "reCAPTCHA validation error"
+    };
+  }
+}
+function isRecaptchaEnabled(secretKey) {
+  return !!(secretKey ?? process.env.RECAPTCHA_SECRET_KEY);
+}
+function getRecaptchaToken(formData, fieldName = "recaptchaToken") {
+  const token = formData.get(fieldName);
+  return typeof token === "string" ? token : null;
+}
+
+exports.getRecaptchaToken = getRecaptchaToken;
+exports.isRecaptchaEnabled = isRecaptchaEnabled;
+exports.validateRecaptcha = validateRecaptcha;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/constants/index.ts","../../src/server/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * reCAPTCHA Configuration Constants\n *\n * Default configuration values for reCAPTCHA v3 integration.\n *\n * @packageDocumentation\n */\n\nimport type { RecaptchaConfig } from \"../types\";\n\n/**\n * Default score threshold for validation\n * Scores below this value are considered suspicious\n * Range: 0.0 (bot) to 1.0 (human)\n */\nexport const DEFAULT_SCORE_THRESHOLD = 0.5;\n\n/**\n * Token refresh interval in milliseconds\n * reCAPTCHA tokens expire after 2 minutes, so we refresh at 90 seconds\n * to ensure tokens are always valid when forms are submitted\n */\nexport const DEFAULT_TOKEN_REFRESH_INTERVAL = 90000;\n\n/**\n * reCAPTCHA v3 configuration constants\n */\nexport const RECAPTCHA_CONFIG: RecaptchaConfig = {\n  /** Google reCAPTCHA verification endpoint */\n  verifyUrl: \"https://www.google.com/recaptcha/api/siteverify\",\n  /** Default score threshold for validation */\n  defaultScoreThreshold: DEFAULT_SCORE_THRESHOLD,\n  /** Default token refresh interval */\n  tokenRefreshInterval: DEFAULT_TOKEN_REFRESH_INTERVAL,\n} as const;\n","/**\n * reCAPTCHA v3 Server-Side Validation\n *\n * Functions for validating reCAPTCHA tokens in Next.js Server Actions.\n *\n * @see https://developers.google.com/recaptcha/docs/verify\n * @packageDocumentation\n */\n\nimport type {\n  RecaptchaValidationResult,\n  RecaptchaVerifyResponse,\n  RecaptchaValidationOptions,\n} from \"../types\";\nimport { RECAPTCHA_CONFIG, DEFAULT_SCORE_THRESHOLD } from \"../constants\";\n\n/**\n * Validate a reCAPTCHA token with Google's API\n *\n * @param token - The reCAPTCHA token from the client\n * @param expectedAction - The expected action name (optional, for extra security)\n * @param options - Additional validation options\n * @returns Validation result with success status and score\n *\n * @example Basic validation\n * ```ts\n * const result = await validateRecaptcha(token, \"contact_form\");\n * if (!result.success) {\n *   return { success: false, message: result.error };\n * }\n * ```\n *\n * @example Custom threshold for sensitive forms\n * ```ts\n * const result = await validateRecaptcha(token, \"payment_form\", {\n *   scoreThreshold: 0.7, // Higher threshold for payments\n *   secretKey: process.env.RECAPTCHA_SECRET_KEY,\n * });\n * ```\n *\n * @example Skip validation in development\n * ```ts\n * const result = await validateRecaptcha(token, \"test_form\", {\n *   debug: true, // Enable debug logging\n * });\n * // Returns { success: true, score: 1, skipped: true } if not configured\n * ```\n */\nexport async function validateRecaptcha(\n  token: string | null | undefined,\n  expectedAction?: string,\n  options: RecaptchaValidationOptions = {}\n): Promise<RecaptchaValidationResult> {\n  const {\n    scoreThreshold = DEFAULT_SCORE_THRESHOLD,\n    secretKey = process.env.RECAPTCHA_SECRET_KEY,\n    debug = process.env.NODE_ENV === \"development\",\n  } = options;\n\n  // Check if reCAPTCHA is configured\n  if (!secretKey) {\n    if (debug) {\n      console.warn(\n        \"[reCAPTCHA] Secret key not configured. Skipping validation.\"\n      );\n    }\n    return {\n      success: true,\n      score: 1,\n      skipped: true,\n    };\n  }\n\n  // Check if token is provided\n  if (!token) {\n    return {\n      success: false,\n      score: 0,\n      error: \"reCAPTCHA token is missing\",\n    };\n  }\n\n  try {\n    // Verify token with Google\n    const response = await fetch(RECAPTCHA_CONFIG.verifyUrl, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/x-www-form-urlencoded\",\n      },\n      body: new URLSearchParams({\n        secret: secretKey,\n        response: token,\n      }),\n    });\n\n    if (!response.ok) {\n      throw new Error(`HTTP error! status: ${response.status}`);\n    }\n\n    const data: RecaptchaVerifyResponse = await response.json();\n\n    if (debug) {\n      console.log(\"[reCAPTCHA] Verification response:\", {\n        success: data.success,\n        score: data.score,\n        action: data.action,\n        hostname: data.hostname,\n      });\n    }\n\n    // Check if verification failed\n    if (!data.success) {\n      return {\n        success: false,\n        score: 0,\n        error: `reCAPTCHA verification failed: ${data[\"error-codes\"]?.join(\", \") || \"Unknown error\"}`,\n        rawResponse: data,\n      };\n    }\n\n    // Check score threshold\n    if (data.score < scoreThreshold) {\n      return {\n        success: false,\n        score: data.score,\n        error: `reCAPTCHA score too low: ${data.score} (threshold: ${scoreThreshold})`,\n        rawResponse: data,\n      };\n    }\n\n    // Check action if provided\n    if (expectedAction && data.action !== expectedAction) {\n      return {\n        success: false,\n        score: data.score,\n        error: `reCAPTCHA action mismatch: expected \"${expectedAction}\", got \"${data.action}\"`,\n        rawResponse: data,\n      };\n    }\n\n    // Validation passed\n    return {\n      success: true,\n      score: data.score,\n      rawResponse: data,\n    };\n  } catch (error) {\n    console.error(\"[reCAPTCHA] Validation error:\", error);\n    return {\n      success: false,\n      score: 0,\n      error:\n        error instanceof Error\n          ? `reCAPTCHA validation error: ${error.message}`\n          : \"reCAPTCHA validation error\",\n    };\n  }\n}\n\n/**\n * Check if reCAPTCHA is enabled (secret key is configured)\n *\n * @param secretKey - Optional explicit secret key to check\n * @returns true if reCAPTCHA is configured\n *\n * @example\n * ```ts\n * if (isRecaptchaEnabled()) {\n *   // Require reCAPTCHA validation\n * } else {\n *   // Skip validation in development\n * }\n * ```\n */\nexport function isRecaptchaEnabled(secretKey?: string): boolean {\n  return !!(secretKey ?? process.env.RECAPTCHA_SECRET_KEY);\n}\n\n/**\n * Extract reCAPTCHA token from FormData\n *\n * @param formData - Form data containing the token\n * @param fieldName - Name of the token field (default: \"recaptchaToken\")\n * @returns The token string or null\n *\n * @example\n * ```ts\n * export async function submitForm(prevState: State, formData: FormData) {\n *   const token = getRecaptchaToken(formData);\n *   const result = await validateRecaptcha(token, \"contact_form\");\n *   // ...\n * }\n * ```\n */\nexport function getRecaptchaToken(\n  formData: FormData,\n  fieldName: string = \"recaptchaToken\"\n): string | null {\n  const token = formData.get(fieldName);\n  return typeof token === \"string\" ? token : null;\n}\n"]}

package/dist/server/index.mjs

@@ -0,0 +1,110 @@
+// src/constants/index.ts
+var DEFAULT_SCORE_THRESHOLD = 0.5;
+var DEFAULT_TOKEN_REFRESH_INTERVAL = 9e4;
+var RECAPTCHA_CONFIG = {
+  /** Google reCAPTCHA verification endpoint */
+  verifyUrl: "https://www.google.com/recaptcha/api/siteverify",
+  /** Default score threshold for validation */
+  defaultScoreThreshold: DEFAULT_SCORE_THRESHOLD,
+  /** Default token refresh interval */
+  tokenRefreshInterval: DEFAULT_TOKEN_REFRESH_INTERVAL
+};
+
+// src/server/index.ts
+async function validateRecaptcha(token, expectedAction, options = {}) {
+  const {
+    scoreThreshold = DEFAULT_SCORE_THRESHOLD,
+    secretKey = process.env.RECAPTCHA_SECRET_KEY,
+    debug = process.env.NODE_ENV === "development"
+  } = options;
+  if (!secretKey) {
+    if (debug) {
+      console.warn(
+        "[reCAPTCHA] Secret key not configured. Skipping validation."
+      );
+    }
+    return {
+      success: true,
+      score: 1,
+      skipped: true
+    };
+  }
+  if (!token) {
+    return {
+      success: false,
+      score: 0,
+      error: "reCAPTCHA token is missing"
+    };
+  }
+  try {
+    const response = await fetch(RECAPTCHA_CONFIG.verifyUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body: new URLSearchParams({
+        secret: secretKey,
+        response: token
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+    const data = await response.json();
+    if (debug) {
+      console.log("[reCAPTCHA] Verification response:", {
+        success: data.success,
+        score: data.score,
+        action: data.action,
+        hostname: data.hostname
+      });
+    }
+    if (!data.success) {
+      return {
+        success: false,
+        score: 0,
+        error: `reCAPTCHA verification failed: ${data["error-codes"]?.join(", ") || "Unknown error"}`,
+        rawResponse: data
+      };
+    }
+    if (data.score < scoreThreshold) {
+      return {
+        success: false,
+        score: data.score,
+        error: `reCAPTCHA score too low: ${data.score} (threshold: ${scoreThreshold})`,
+        rawResponse: data
+      };
+    }
+    if (expectedAction && data.action !== expectedAction) {
+      return {
+        success: false,
+        score: data.score,
+        error: `reCAPTCHA action mismatch: expected "${expectedAction}", got "${data.action}"`,
+        rawResponse: data
+      };
+    }
+    return {
+      success: true,
+      score: data.score,
+      rawResponse: data
+    };
+  } catch (error) {
+    console.error("[reCAPTCHA] Validation error:", error);
+    return {
+      success: false,
+      score: 0,
+      error: error instanceof Error ? `reCAPTCHA validation error: ${error.message}` : "reCAPTCHA validation error"
+    };
+  }
+}
+function isRecaptchaEnabled(secretKey) {
+  return !!(secretKey ?? process.env.RECAPTCHA_SECRET_KEY);
+}
+function getRecaptchaToken(formData, fieldName = "recaptchaToken") {
+  const token = formData.get(fieldName);
+  return typeof token === "string" ? token : null;
+}
+
+export { getRecaptchaToken, isRecaptchaEnabled, validateRecaptcha };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/server/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/constants/index.ts","../../src/server/index.ts"],"names":[],"mappings":";AAeO,IAAM,uBAAA,GAA0B,GAAA;AAOhC,IAAM,8BAAA,GAAiC,GAAA;AAKvC,IAAM,gBAAA,GAAoC;AAAA;AAAA,EAE/C,SAAA,EAAW,iDAAA;AAAA;AAAA,EAEX,qBAAA,EAAuB,uBAAA;AAAA;AAAA,EAEvB,oBAAA,EAAsB;AACxB,CAAA;;;ACcA,eAAsB,iBAAA,CACpB,KAAA,EACA,cAAA,EACA,OAAA,GAAsC,EAAC,EACH;AACpC,EAAA,MAAM;AAAA,IACJ,cAAA,GAAiB,uBAAA;AAAA,IACjB,SAAA,GAAY,QAAQ,GAAA,CAAI,oBAAA;AAAA,IACxB,KAAA,GAAQ,OAAA,CAAQ,GAAA,CAAI,QAAA,KAAa;AAAA,GACnC,GAAI,OAAA;AAGJ,EAAA,IAAI,CAAC,SAAA,EAAW;AACd,IAAA,IAAI,KAAA,EAAO;AACT,MAAA,OAAA,CAAQ,IAAA;AAAA,QACN;AAAA,OACF;AAAA,IACF;AACA,IAAA,OAAO;AAAA,MACL,OAAA,EAAS,IAAA;AAAA,MACT,KAAA,EAAO,CAAA;AAAA,MACP,OAAA,EAAS;AAAA,KACX;AAAA,EACF;AAGA,EAAA,IAAI,CAAC,KAAA,EAAO;AACV,IAAA,OAAO;AAAA,MACL,OAAA,EAAS,KAAA;AAAA,MACT,KAAA,EAAO,CAAA;AAAA,MACP,KAAA,EAAO;AAAA,KACT;AAAA,EACF;AAEA,EAAA,IAAI;AAEF,IAAA,MAAM,QAAA,GAAW,MAAM,KAAA,CAAM,gBAAA,CAAiB,SAAA,EAAW;AAAA,MACvD,MAAA,EAAQ,MAAA;AAAA,MACR,OAAA,EAAS;AAAA,QACP,cAAA,EAAgB;AAAA,OAClB;AAAA,MACA,IAAA,EAAM,IAAI,eAAA,CAAgB;AAAA,QACxB,MAAA,EAAQ,SAAA;AAAA,QACR,QAAA,EAAU;AAAA,OACX;AAAA,KACF,CAAA;AAED,IAAA,IAAI,CAAC,SAAS,EAAA,EAAI;AAChB,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,oBAAA,EAAuB,QAAA,CAAS,MAAM,CAAA,CAAE,CAAA;AAAA,IAC1D;AAEA,IAAA,MAAM,IAAA,GAAgC,MAAM,QAAA,CAAS,IAAA,EAAK;AAE1D,IAAA,IAAI,KAAA,EAAO;AACT,MAAA,OAAA,CAAQ,IAAI,oCAAA,EAAsC;AAAA,QAChD,SAAS,IAAA,CAAK,OAAA;AAAA,QACd,OAAO,IAAA,CAAK,KAAA;AAAA,QACZ,QAAQ,IAAA,CAAK,MAAA;AAAA,QACb,UAAU,IAAA,CAAK;AAAA,OAChB,CAAA;AAAA,IACH;AAGA,IAAA,IAAI,CAAC,KAAK,OAAA,EAAS;AACjB,MAAA,OAAO;AAAA,QACL,OAAA,EAAS,KAAA;AAAA,QACT,KAAA,EAAO,CAAA;AAAA,QACP,KAAA,EAAO,kCAAkC,IAAA,CAAK,aAAa,GAAG,IAAA,CAAK,IAAI,KAAK,eAAe,CAAA,CAAA;AAAA,QAC3F,WAAA,EAAa;AAAA,OACf;AAAA,IACF;AAGA,IAAA,IAAI,IAAA,CAAK,QAAQ,cAAA,EAAgB;AAC/B,MAAA,OAAO;AAAA,QACL,OAAA,EAAS,KAAA;AAAA,QACT,OAAO,IAAA,CAAK,KAAA;AAAA,QACZ,KAAA,EAAO,CAAA,yBAAA,EAA4B,IAAA,CAAK,KAAK,gBAAgB,cAAc,CAAA,CAAA,CAAA;AAAA,QAC3E,WAAA,EAAa;AAAA,OACf;AAAA,IACF;AAGA,IAAA,IAAI,cAAA,IAAkB,IAAA,CAAK,MAAA,KAAW,cAAA,EAAgB;AACpD,MAAA,OAAO;AAAA,QACL,OAAA,EAAS,KAAA;AAAA,QACT,OAAO,IAAA,CAAK,KAAA;AAAA,QACZ,KAAA,EAAO,CAAA,qCAAA,EAAwC,cAAc,CAAA,QAAA,EAAW,KAAK,MAAM,CAAA,CAAA,CAAA;AAAA,QACnF,WAAA,EAAa;AAAA,OACf;AAAA,IACF;AAGA,IAAA,OAAO;AAAA,MACL,OAAA,EAAS,IAAA;AAAA,MACT,OAAO,IAAA,CAAK,KAAA;AAAA,MACZ,WAAA,EAAa;AAAA,KACf;AAAA,EACF,SAAS,KAAA,EAAO;AACd,IAAA,OAAA,CAAQ,KAAA,CAAM,iCAAiC,KAAK,CAAA;AACpD,IAAA,OAAO;AAAA,MACL,OAAA,EAAS,KAAA;AAAA,MACT,KAAA,EAAO,CAAA;AAAA,MACP,OACE,KAAA,YAAiB,KAAA,GACb,CAAA,4BAAA,EAA+B,KAAA,CAAM,OAAO,CAAA,CAAA,GAC5C;AAAA,KACR;AAAA,EACF;AACF;AAiBO,SAAS,mBAAmB,SAAA,EAA6B;AAC9D,EAAA,OAAO,CAAC,EAAE,SAAA,IAAa,OAAA,CAAQ,GAAA,CAAI,oBAAA,CAAA;AACrC;AAkBO,SAAS,iBAAA,CACd,QAAA,EACA,SAAA,GAAoB,gBAAA,EACL;AACf,EAAA,MAAM,KAAA,GAAQ,QAAA,CAAS,GAAA,CAAI,SAAS,CAAA;AACpC,EAAA,OAAO,OAAO,KAAA,KAAU,QAAA,GAAW,KAAA,GAAQ,IAAA;AAC7C","file":"index.mjs","sourcesContent":["/**\n * reCAPTCHA Configuration Constants\n *\n * Default configuration values for reCAPTCHA v3 integration.\n *\n * @packageDocumentation\n */\n\nimport type { RecaptchaConfig } from \"../types\";\n\n/**\n * Default score threshold for validation\n * Scores below this value are considered suspicious\n * Range: 0.0 (bot) to 1.0 (human)\n */\nexport const DEFAULT_SCORE_THRESHOLD = 0.5;\n\n/**\n * Token refresh interval in milliseconds\n * reCAPTCHA tokens expire after 2 minutes, so we refresh at 90 seconds\n * to ensure tokens are always valid when forms are submitted\n */\nexport const DEFAULT_TOKEN_REFRESH_INTERVAL = 90000;\n\n/**\n * reCAPTCHA v3 configuration constants\n */\nexport const RECAPTCHA_CONFIG: RecaptchaConfig = {\n  /** Google reCAPTCHA verification endpoint */\n  verifyUrl: \"https://www.google.com/recaptcha/api/siteverify\",\n  /** Default score threshold for validation */\n  defaultScoreThreshold: DEFAULT_SCORE_THRESHOLD,\n  /** Default token refresh interval */\n  tokenRefreshInterval: DEFAULT_TOKEN_REFRESH_INTERVAL,\n} as const;\n","/**\n * reCAPTCHA v3 Server-Side Validation\n *\n * Functions for validating reCAPTCHA tokens in Next.js Server Actions.\n *\n * @see https://developers.google.com/recaptcha/docs/verify\n * @packageDocumentation\n */\n\nimport type {\n  RecaptchaValidationResult,\n  RecaptchaVerifyResponse,\n  RecaptchaValidationOptions,\n} from \"../types\";\nimport { RECAPTCHA_CONFIG, DEFAULT_SCORE_THRESHOLD } from \"../constants\";\n\n/**\n * Validate a reCAPTCHA token with Google's API\n *\n * @param token - The reCAPTCHA token from the client\n * @param expectedAction - The expected action name (optional, for extra security)\n * @param options - Additional validation options\n * @returns Validation result with success status and score\n *\n * @example Basic validation\n * ```ts\n * const result = await validateRecaptcha(token, \"contact_form\");\n * if (!result.success) {\n *   return { success: false, message: result.error };\n * }\n * ```\n *\n * @example Custom threshold for sensitive forms\n * ```ts\n * const result = await validateRecaptcha(token, \"payment_form\", {\n *   scoreThreshold: 0.7, // Higher threshold for payments\n *   secretKey: process.env.RECAPTCHA_SECRET_KEY,\n * });\n * ```\n *\n * @example Skip validation in development\n * ```ts\n * const result = await validateRecaptcha(token, \"test_form\", {\n *   debug: true, // Enable debug logging\n * });\n * // Returns { success: true, score: 1, skipped: true } if not configured\n * ```\n */\nexport async function validateRecaptcha(\n  token: string | null | undefined,\n  expectedAction?: string,\n  options: RecaptchaValidationOptions = {}\n): Promise<RecaptchaValidationResult> {\n  const {\n    scoreThreshold = DEFAULT_SCORE_THRESHOLD,\n    secretKey = process.env.RECAPTCHA_SECRET_KEY,\n    debug = process.env.NODE_ENV === \"development\",\n  } = options;\n\n  // Check if reCAPTCHA is configured\n  if (!secretKey) {\n    if (debug) {\n      console.warn(\n        \"[reCAPTCHA] Secret key not configured. Skipping validation.\"\n      );\n    }\n    return {\n      success: true,\n      score: 1,\n      skipped: true,\n    };\n  }\n\n  // Check if token is provided\n  if (!token) {\n    return {\n      success: false,\n      score: 0,\n      error: \"reCAPTCHA token is missing\",\n    };\n  }\n\n  try {\n    // Verify token with Google\n    const response = await fetch(RECAPTCHA_CONFIG.verifyUrl, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/x-www-form-urlencoded\",\n      },\n      body: new URLSearchParams({\n        secret: secretKey,\n        response: token,\n      }),\n    });\n\n    if (!response.ok) {\n      throw new Error(`HTTP error! status: ${response.status}`);\n    }\n\n    const data: RecaptchaVerifyResponse = await response.json();\n\n    if (debug) {\n      console.log(\"[reCAPTCHA] Verification response:\", {\n        success: data.success,\n        score: data.score,\n        action: data.action,\n        hostname: data.hostname,\n      });\n    }\n\n    // Check if verification failed\n    if (!data.success) {\n      return {\n        success: false,\n        score: 0,\n        error: `reCAPTCHA verification failed: ${data[\"error-codes\"]?.join(\", \") || \"Unknown error\"}`,\n        rawResponse: data,\n      };\n    }\n\n    // Check score threshold\n    if (data.score < scoreThreshold) {\n      return {\n        success: false,\n        score: data.score,\n        error: `reCAPTCHA score too low: ${data.score} (threshold: ${scoreThreshold})`,\n        rawResponse: data,\n      };\n    }\n\n    // Check action if provided\n    if (expectedAction && data.action !== expectedAction) {\n      return {\n        success: false,\n        score: data.score,\n        error: `reCAPTCHA action mismatch: expected \"${expectedAction}\", got \"${data.action}\"`,\n        rawResponse: data,\n      };\n    }\n\n    // Validation passed\n    return {\n      success: true,\n      score: data.score,\n      rawResponse: data,\n    };\n  } catch (error) {\n    console.error(\"[reCAPTCHA] Validation error:\", error);\n    return {\n      success: false,\n      score: 0,\n      error:\n        error instanceof Error\n          ? `reCAPTCHA validation error: ${error.message}`\n          : \"reCAPTCHA validation error\",\n    };\n  }\n}\n\n/**\n * Check if reCAPTCHA is enabled (secret key is configured)\n *\n * @param secretKey - Optional explicit secret key to check\n * @returns true if reCAPTCHA is configured\n *\n * @example\n * ```ts\n * if (isRecaptchaEnabled()) {\n *   // Require reCAPTCHA validation\n * } else {\n *   // Skip validation in development\n * }\n * ```\n */\nexport function isRecaptchaEnabled(secretKey?: string): boolean {\n  return !!(secretKey ?? process.env.RECAPTCHA_SECRET_KEY);\n}\n\n/**\n * Extract reCAPTCHA token from FormData\n *\n * @param formData - Form data containing the token\n * @param fieldName - Name of the token field (default: \"recaptchaToken\")\n * @returns The token string or null\n *\n * @example\n * ```ts\n * export async function submitForm(prevState: State, formData: FormData) {\n *   const token = getRecaptchaToken(formData);\n *   const result = await validateRecaptcha(token, \"contact_form\");\n *   // ...\n * }\n * ```\n */\nexport function getRecaptchaToken(\n  formData: FormData,\n  fieldName: string = \"recaptchaToken\"\n): string | null {\n  const token = formData.get(fieldName);\n  return typeof token === \"string\" ? token : null;\n}\n"]}