Bandada credentials
Bandada library to validate users' credentials.
| This package provides a function to validate users' credentials by using a set of extendable validators. |
| -------------------------------------------------------------------------------------------------------- |
## 🛠 Install
### npm or yarn
Install the `@bandada/credentials` package with npm:
```bash
npm i @bandada/credentials
```
or yarn:
```bash
yarn add @bandada/credentials
```
## 📜 Usage
\# **validateCredentials**(credentials: _Credentials_, context: _Context_)
```typescript
import { validateCredentials, githubFollowers } from "@bandada/credentials"
validateCredentials(
{
id: githubFollowers.id,
criteria: {
minFollowers: 100
}
},
{
accessToken: {
github: "token"
}
}
)
```
### Custom validators
The library has been built to allow external devs to add their own validators. A validator is a simple file that exports 3 JavaScript values:
1. `id`: The validator id. It must be unique and capitalized (snake case).
2. `criteriaABI`: The criteria ABI. It contains the structure of your criteria with its types.
3. `validate`: The validator handler. It usually consists of three steps: criteria types check, user data retrieval and credentials' validation.
```typescript
import { Handler } from "@bandada/credentials"
// Typescript type for the handler criteria.
// This will be mainly used by this handler.
export type Criteria = {
minFollowers: number
}
const validator: Validator = {
id: "GITHUB_FOLLOWERS",
// The criteria application binary interface. It contains
// the structure of this validator credentials
// with its parameter types.
criteriaABI: {
minFollowers: "number"
},
/**
* It checks if a user has more than 'minFollowers' followers.
* @param criteria The criteria used to check user's credentials.
* @param context Utility functions and other context variables.
* @returns True if the user meets the credentials.
*/
async validate(criteria: Criteria, { utils }) {
// Step 1: use the API to get the user's parameters.
const { followers } = await utils.api("user")
// Step 2: check if they meet the validator credentials.
return followers >= criteria.minFollowers
}
}
export default validator
```
Testing your validator is also important. If you use Jest you can use some test utilities to mock the API function easily.
```typescript
import {
addValidator,
testUtils,
validateCredentials
} from "@bandada/credentials"
import githubFollowers from "./index"
describe("GithubFollowers", () => {
beforeAll(() => {
addValidator(githubFollowers)
})
it("Should return true if a Github user has more than 100 followers", async () => {
testUtils.mockAPIOnce({
followers: 110
})
const result = await validateCredentials(
{
id: "GITHUB_FOLLOWERS",
criteria: {
minFollowers: 100
}
},
{
accessTokens: {
github: "token"
}
}
)
expect(result).toBeTruthy()
})
})
```
Once you create your own validator and publish your NPM package, you can open a PR to add your validator to the ones supported by Bandada (`validators.ts` file). You can also add a new provider to the `providers.ts` file.