npm package: @funpodium/fp-captcha-client-react-sdk
Description: fpCaptcha client SDK for React
Author: Nelson Liu
Latest version: 0.11.20

# fpCaptcha Client React SDK

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

## install

1. Follow [this guide](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) to retrieve a GitLab personal access token.
2. Run these lines in shell to add the config to npm.

```shell
$ 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`.

```shell
npm install @funpodium/fp-captcha-client-react-sdk
# or use yarn
yarn add @funpodium/fp-captcha-client-react-sdk
```

## usage

### `<FpCaptcha />`

all-in-one React component that encapsulate the logic in a nice package.

```tsx
import { FpCaptcha } from "@funpodium/fp-captcha-client-react-sdk";

const App: React.FC = () => {
  const [visible, useVisible] = useState(false);
  const [challengeUuid, setChallengeUuid] = useState("");

  const startNewChallenge = () => {
    //TODO: get challengeId
  };

  const handlePassed = () => {
    //TODO: after pass
  };

  useEffect(() => {
    startNewChallenge();
  }, []);

  return (
    <FpCaptcha
      visible={visible}
      challengeId={challengeUuid}
      options={{
        window: global.window,
        dialogMode: true,
        config: {
          apiUrl: CAPTCHA_SERVICE_API_URL,
          applicationLocale: "zh",
          chunkSize: 10,
          dragThreshold: 20,
        },
      }}
      onClose={() => setVisible(false)}
      onPassed={handlePassed}
    />
  );
};
```

&nbsp;

### FpCaptcha Features

| Attribute   | Usage                                 | Type        |
| ----------- | ------------------------------------- | ----------- |
| visible     | showing the Fpcaptcha component       | Boolean     |
| challengeId | challengeUuid came form client server | String      |
| onClose     | triggered when closing                | ()=>void    |
| onPassed    | triggered when passing the judgement  | ()=>void    |
| options     | setting of captcha                    | OptionsType |

&nbsp;

### FpCaptcha-options

| Attribute  | Usage                                      | Type       |
| ---------- | ------------------------------------------ | ---------- |
| window     | window which the captcha object binding on | Window     |
| dialogMode | Fpcaptcha may appear in a dialog           | boolean    |
| config     | config of captcha                          | ConfigType |

&nbsp;

### FpCaptcha-options-config

| Attribute         | Usage                               | Type   |
| ----------------- | ----------------------------------- | ------ |
| apiUrl            | main captcha judgement services url | URL    |
| applicationLocale | Locale of captcha                   | string |
| dismissTime       | under developing!!                  | number |
| chunkSize         | chunk size for the decipher         | number |
| dragThreshold     | drag active area on the map         | number |

&nbsp;

### `useFpCaptcha` hook

a React hook that handles the dirty work for you while it allows you to trigger methods on your command.

```tsx
import { useFpCaptcha } from "@funpodium/fp-captcha-client-react-sdk";

const App: React.FC = () => {
  const canvasRef = useRef();
  const { build, refresh, result, fpCaptcha } = useFpCaptcha(canvasRef);

  useEffect(() => {
    build();
  }, [build]);

  return <canvas ref={canvasRef} />;
};
```

&nbsp;

### useFpCaptcha-Return type

| Attribute | Usage                                                                  | Type                                    |
| --------- | ---------------------------------------------------------------------- | --------------------------------------- |
| build     | build fpCaptcha component                                              | (challengeId: string) => Promise\<void> |
| refresh   | refresh fpCaptcha component                                            | () => Promise\<void>                    |
| judgement | judgement object return by server                                      | JudgementType                           |
| locale    | locale object return by server (setting of each product)               | LocaleType                              |
| fpCaptcha | fpCaptcha class object (not usually used / object from js-captcha-sdk) | FpCaptchaType                           |
| loading   | is loading                                                             | boolean                                 |

&nbsp;

### Type

&nbsp;

#### JudgementType

```ts
{
  challengeUuid: string;
  code: number;
  message: string;
  isPassed: boolean;
}
```

#### LocaleType

```ts
{
  fail: string;
  abnormal: string;
  provide: string;
  success: string;
  refresh: string;
  description: string;
  info: string;
}
```