@bandada/reputation

Bandada reputation

Bandada library to validate users' reputation.

👥 Contributing   |   🤝 Code of conduct   |   🔎 Issues   |   🗣️ Chat & Support

This package provides a function to validate users' reputation by using a set of extendable validators.

🛠 Install

npm or yarn

Install the @bandada/reputation package with npm:

npm i @bandada/reputation

or yarn:

yarn add @bandada/reputation

📜 Usage

# validateReputation(reputationCriteria: ReputationCriteria, context: Context)

import { validateReputation, githubFollowers } from "@bandada/reputation"

validateReputation(
    {
        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 validater id. It must be unique and capitalized (snake case).
2. criteriaABI: The criteria ABI. It contains the structure of your reputation criteria with its types.
3. validate: The validator handler. It usually consists of three steps: criteria types check, user data retrieval and reputation validation.

import { Handler } from "@bandada/reputation"

// 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 reputation criteria
    // with its parameter types.
    criteriaABI: {
        minFollowers: "number"
    },

    /**
     * It checks if a user has more then 'minFollowers' followers.
     * @param criteria The reputation criteria used to check user's reputation.
     * @param context Utility functions and other context variables.
     * @returns True if the user meets the reputation criteria.
     */
    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 reputation criteria.
        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.

import {
    addValidator,
    testUtils,
    validateReputation
} from "@bandada/reputation"
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 validateReputation(
            {
                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.