node-recaptcha-v3

A powerful and easy-to-use Node.js library for Google reCAPTCHA v3 verification, designed to protect your web applications from spam and abuse.


Features

- Simple and intuitive API
- Secure token verification
- Express.js middleware support
- Configurable score thresholds
- TypeScript support
- Flexible token handling (headers or body)

> Check out our complete example here

Table of Contents

- Installation
- Quick Start
- Configuration
- API Reference
- Best Practices
- Frequently Asked Questions
- Contributing
- License
- Support
- Acknowledgments

Installation

``bash
npm install node-recaptcha-v3
`

Quick Start

$3

`typescript
import express from 'express'
import ReCaptchaV3 from 'node-recaptcha-v3'

const app = express()
app.use(express.json())

// Initialize reCAPTCHA with your secret key
const reCaptcha = new ReCaptchaV3({ secretKey: 'YOUR_SECRET_KEY' })

// Add verification middleware to your routes
app.post('/api/submit', reCaptcha.verify(0.5), (req, res) => {
// Access the verification score
const score = req.reCaptchaV3Score
console.log(reCAPTCHA score: ${score})

res.json({
success: true,
score,
message: 'Verification successful!'
})
})
`

$3

`html




`

Configuration

$3

`typescript
interface ReCaptchaV3Configuration {
secretKey: string
statusCode?: number
message?: string
threshold?: number
apiEndPoint?: string
}
`

$3

`typescript
// Basic usage with default threshold (0.5)
app.post('/api/basic', reCaptcha.verify(), handler)

// Custom threshold
app.post('/api/strict', reCaptcha.verify(0.7), handler)

// Custom error handling
app.post(
'/api/custom',
reCaptcha.verify(0.5),
(err, req, res, next) => {
if (err.name === 'ReCaptchaError') {
return res.status(400).json({ error: err.message })
}
next(err)
},
handler
)
`

API Reference

$3

`typescript
class ReCaptchaV3 {
constructor(config: ReCaptchaV3Config)
verify(threshold?: number): RequestHandler
}
`

Best Practices

1. Score Thresholds
- Use higher thresholds (0.7+) for sensitive actions
- Use lower thresholds (0.3-0.5) for less critical actions

2. Security
- Keep your secret key secure
- Use environment variables
- Implement rate limiting
- Use HTTPS

3. Error Handling
- Always handle verification failures gracefully
- Provide clear user feedback
- Log suspicious activities

Frequently Asked Questions

$3

reCAPTCHA v3 returns a score (1.0 is very likely a good interaction, 0.0 is very likely a bot):

- 1.0 - 0.8: Very likely human
- 0.8 - 0.5: Probably human
- 0.5 - 0.3: Suspicious
- 0.3 - 0.0: Likely bot

$3

- Simple integration
- Type safety with TypeScript
- Express.js middleware
- Customizable configuration
- Active maintenance
- Comprehensive documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature`)
5. Open a Pull Request

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support

- Create an issue on GitHub
- Contact the maintainer: vdhuyme

Acknowledgments

- Thanks to all contributors who have helped with code, bug reports, and suggestions