Merge pull request #1 from steve-lebleu/feature/doc-errors-mgt

feat: errors management, more flexibility on args, documentation

.github/workflows/build.yml

@@ -18,10 +18,15 @@ jobs:
           node-version: '20.9.0'
       - name: Install local dependencies
         run:  npm i
+      - name: Create .env file
+        run: |
+          touch .env
+          echo GG_RECAPTCHA_SCORE = "${{ vars.GG_RECAPTCHA_SCORE }}" >> .env
+          echo GG_RECAPTCHA_SECRET = "${{ secrets.GG_RECAPTCHA_SECRET }}" >> .env
       - name: Execute tests suites
         run: npm run ci:test
       - name: Publish to coveralls.io
-        uses: coverallsapp/github-action@v1.1.2
+        uses: coverallsapp/github-action@v2
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           path-to-lcov: ./coverage/lcov.info

.github/workflows/release.yml

@@ -19,10 +19,15 @@ jobs:
           node-version: '20.9.0'
       - name: Install local dependencies
         run:  npm i
+      - name: Create .env file
+        run: |
+          touch .env
+          echo GG_RECAPTCHA_SCORE = "${{ vars.GG_RECAPTCHA_SCORE }}" >> .env
+          echo GG_RECAPTCHA_SECRET = "${{ secrets.GG_RECAPTCHA_SECRET }}" >> .env
       - name: Execute tests suites
         run: npm run ci:test
       - name: Publish to coveralls.io
-        uses: coverallsapp/github-action@v1.1.2
+        uses: coverallsapp/github-action@v2
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           path-to-lcov: ./coverage/lcov.info

.gitignore

@@ -1,4 +1,5 @@
 node_modules
 coverage
 reports
-.nyc_output
+.nyc_output
+.env

README.md

@@ -8,16 +8,17 @@
 
 Endpoint protection using express validation midlleware.
 
+:link: [Official documentation](https://developers.google.com/recaptcha/docs/verify)
+
 ![Middleware illustration](https://cdn.konfer.be/images/packages/express-gg-recaptcha-middleware.png)
 
 ## Prerequisites
 
-- Project should be created in https://www.google.com/recaptcha/admin/.
-- Domain name of the consummer application must be whitelisted in https://www.google.com/recaptcha/admin/. 
-- Front-end client must integrate Google recaptcha srcripts in order to call your backend, who's call the Google API.
-- An environment variable named *GG_RECAPTCHA_URL*: url to attack to verify the token.
-- An environment variable name *GG_RECAPTCHA_SCORE*: minimal score required to succeed (between 0 and 1).
-- An environment secret named *GG_RECAPTCHA_SECRET*: Google recaptcha secret associated to the site key.
+- A project entry in https://www.google.com/recaptcha/admin/.
+- A domain name whitelisted in https://www.google.com/recaptcha/admin/. 
+- A Google recaptcha front-end integration in order to call your backend, who's call the Google API.
+- An environment secret *GG_RECAPTCHA_SECRET*: Google recaptcha secret associated to the site key.
+- An environment variable *GG_RECAPTCHA_SCORE*: minimal score required to succeed (between 0 and 1).
 
 ## How to ?
 
@@ -27,13 +28,29 @@ Endpoint protection using express validation midlleware.
 const { verifyRecaptchaV3 } = require('express-gg-recaptcha/gg-recaptcha.middleware');
 ```
 
-#### 2. Plug re-captcha middleware on the endpoint to protect
+#### 2. Plug re-captcha middleware generator on the endpoint to protect
 
 ```javascript
-app.use('/api', verifyRecaptchaV3(logger), controllerAction);
+app.use('/api', verifyRecaptchaV3(process.env.GG_RECAPTCHA_SECRET, process.env.GG_RECAPTCHA_SCORE, logger), controllerAction);
 ```
 
-The function take one optional parameter - the local logger, and returns the middleware. This one returns a 401 if the verification fails, and next to your endpoint if the check is OK.
+The function takes one required and two optional parameters:
+
+- Google recaptcha secret - Required
+- Minimal score to consider as valid, between 0 and 1 - Optional - Default: 0.7
+- A local logger who's can be useful to debug - Optional - Default on process.stdout
+
+Practically, it returns next a middleware, so this is how your endpoint looks like after the function is executed:
+
+```javascript
+app.use('/api', (req, res, next => { /* Here we do the job */ }), controllerAction);
+```
+
+The middleware expects the token to verify plugged on the body of the request - so on req.body.token.
+
+- It returns a 400 if the token is not present or not valid.
+- It returns a 401 if the verification fails.
+- It next to your endpoint if the check is OK.
 
 ## Tests