fpCaptcha Client JS SDK

🚧 This is still a WIP project, do not use this in production. 🚧

install

1. Follow this guide to retrieve a GitLab personal access token.
2. Run these lines in shell to add the config to npm.

$ npm config set @funpodium:registry https://gitlab.com/api/v4/packages/npm/
$ npm config set -- '//gitlab.com/api/v4/packages/npm/:_authToken' "<your_personal_access_token>"

3. Run one of these lines to add it to the project's package.json.

npm install @funpodium/fp-captcha-client-js-sdk
# or use yarn
yarn add @funpodium/fp-captcha-client-js-sdk

usage

FpCaptcha

all-in-one class that encapsulate the instructions of setting up the captcha interface.

import { FpCaptcha } from "@funpodium/fp-captcha-client-js-sdk";

const captcha = new FpCaptcha(canvasElement, options);

returns

FpCaptcha(instance)

arguments

| Position | Key | Type | Remark | | -------- | ------------- | ----------------- | ---------------------------------- | | 1 | canvasElement | HTMLCanvasElement | the canvas element | | 2 | options | FpCaptchaOptions | options to setup FpCaptcha service |

options

| Key | Type | Remark | | ------ | ------------------- | ---------------------------------- | | window | Window | A window containing a DOM document | | config | FpCaptchaConfigType | |

config (FpCaptchaConfigType)

| Key | Type | Remark | | ----------------- | ------ | ---------------------------------------- | | apiUrl | string | API endpoint to the fpCaptcha service | | chunkSize | number | chunk size for the decipher | | dragThreshold | number | drag active area on the map | | dismissTime | number | available for dragging after dismissTime | | applicationLocale | string | Locale of captcha |

methods

| Method name | Usage | | ----------------- | -------------------------------------------- | | build | to make challenge request and draw on canvas | | refresh | to re-request for another challenge | | teardown | to remove all listeners | | addResultListener | to add listeners after judgement |

method details

build

| Position | Key | Type | Remark | | -------- | ------------- | ------- | ------------------------------------------------------------------------------------ | | 1 | challengeUuid | string | challenge uuid | | 2 | isRefresh | boolean | default: false, if true => refresh only chart; if false => refresh the whole captcha |

teardown | Position | Key | Type | Remark | | -------- | --------------- | ------- | ------------------------------------------------------------------------------------ | | 1 | isRefresh | boolean | default: false, if true => refresh only chart; if false => refresh the whole captcha |

addResultListener | Position | Key | Type | Remark | | -------- | --------------- | ------- | ------------------------------------------------------------------------------------ | | 1 | callback | (judgement: FpCaptchaJudgement)=> void | callback after judgement |

FpCaptchaView

all-in-one class that encapsulate the captcha view.

import { FpCaptchaView } from "@funpodium/fp-captcha-client-js-sdk";

const captcha = new FpCaptchaView(config);

returns

FpCaptchaView(instance)

arguments

| Position | Key | Type | Remark | | -------- | -------- | ------------------- | --------------------------------- | | 1 | config | FpCaptchaConfigType | config to setup FpCaptcha service |

methods

| Method name | Usage | | ---------------- | -------------------------------------------- | | mount | to create elements onto document | | unmount | to remove all elements from document | | build | to make challenge request and draw on canvas | | addEventListener | to add listeners to various events |

method details

build | Position | Key | Type | Remark | | -------- | --------------- | ------- | ------------------------------------------------------------------------------------ | | 1 | challengeUuid | string | challenge uuid |

addEventListener | Position | Key | Type | Remark | | -------- | --------------- | ------- | ------------------------------------------------------------------------------------ | | 1 | eventType | 'open' | 'passed'| 'failed' | 'close' | event listener typ | | 2 | callback | (args: unknown)=> void | callback after specific type of event happened|