Point system

A Javascript point system for websites

This point system stores points for individual users with which users are able to buy/unlock some items you provide. These items may be some parts of your website or just some decoration.
Please note that the data is not encrypted and that this library should not be used for securing important parts of your website!
For a live example take a look at this page

Installation

To add the library to your project run the following command in your terminal

npm install point-system

and import the script via the script tag

<script src="./node_modules/point-system/script.js"></script>

or use the import via unpkg

<script src="https://unpkg.com/point-system/script.js"></script>

After importing the script, you have access to the PTM Class and you can intialize it like so. The constructor awaits a array of items as the first argument.

const ptm = new PTM(items);

After initializing you can setup buttons for buying items like the following given that the name of the item you want to buy is 'javascript badge'

btnElement.addEventlistener("click", () => {
	ptm.buyItem("javascript badge"); // will add the item to user's items and charge the user accordingly, only possible if user's balance is sufficient
});

You can check the items owned by the user via the hasItem method and pass it the item name which will return a boolean indicating whether the item is owned by the user.

ptm.hasItem("javascript badge"); // true if the item is owned by the user

You can charge the user without buying an item by using the chargeUser method and pass the amount the should be added to the user's balance. For example, every ten minutes the user is on the website he earns 100 points.

ptm.chargeUser(100); // positive amount -> adding to user's balance

For displaying the user's balance you can use the balance read-only property.

ptm.balance; // returns the user's balance

Available Methods And Properties

Methods

| name | parameter | return value | description | | ---------- | --------- | ------------ | ------------------------------------------------------------------------------------------ | | hasItem | itemName | boolean | Returns a boolean indicating whether user has the specified item | | buyItem | itemName | this | Adds the item (if existing) to the user's items if the user has enough balance | | getItem | itemName | Item | Returns the data for a specified item from the item list | | chargeUser | amount | this | Charges the user with the given amount. Negative values will be subtracted, positive added | | sellItem | itemName | this | Removes the item from the user's items if the user previously bought the item |

Properties

| name | readable | writeable | type | description | | --------- | -------- | --------- | --------------------- | -------------------------------------------------- | | balance | [ x ] | | number | Current user's balance | | userItems | [ x ] | | Items[] | The items owned by the user | | items | [ x ] | [ x ] | Items[] | All available items | | user | [ x ] | | User | | | VERSION | [ x ] | | VERSION | The installed version | | options | | [ x ] | Options | Updates the options | | callback | | [ x ] | function(user, items) | Updates the callback called when user gets updated |

Customization

The PTM class provides a couple of options to customize the behavior. If you want to change the default options pass an object containing the changed options as the second parameter to the class constructor.

Available options

| option key | default | type | description | | ---------------------- | ------------ | ------------ | ---------------------------------------------------------------------------------------------------- | | startBalance | 100 | number | The start balance with which each new user starts | | storage | localStorage | Storage | The storage where the user data gets saved persistently | | storagePrefix | ptm- | string | The prefix for all data saved in the storage | | logLevel | 2 | LogLevel | Indicating which types of events get logged | | name | PTM | string | The name visible in the logs | | currencyName | pt | string | The currency appended to the item price in the logs | | removeUnavailableItems | false | boolean | Whether to remove items from the user if they are not present in the available items list | | removeInvalidItems | true | boolean | Whether to remove items from the user if they are not longer valid caused by validFrom or validUntil | | loggingTo | console | Logger | The logger used to log events | | itemIdentifierField | id | string | The field on the item object which is used to identify the item | | save | saveFunction | SaveFunction | The function used to save the user | | load | loadFunction | LoadFunction | The function used to load the user |

Refreshing the data

For the ease of refreshing data after a interaction with the PTM, you can pass a callback function as the third parameter to the constructor of the PTM Class, which will be called everytime the user changes.
The callback will be called with the user information as the first parameter, all the available items as the second parameter and the PTM instance as the third parameter.

Types

Type definitions for clarity about the types used in the documentation. The described fields are mandatory until stated otherwise, however any additional fields won't affect the PTM.

Item

| field | optional | type | description | | ---------- | -------- | ------------------ | ------------------------------------------------------------------------------- | | id | | any | Item id used to identifiy the item if option.itemIdentifierField wasn't changed | | name | | string | Name of the item | | price | | number | Negative amount if user has to pay, positive if the user gets points | | validFrom | [ x ] | Date as ISO String | The date and time from which the item can be bought | | validUntil | [ x ] | Date as ISO String | The date and time until which the item can be purchased |

Storage

Every storage object implementing the following methods can be used to store the data persistently (e.g. localStorage)

| field | type | description | | ------- | -------------------- | ------------------------------------------------------------------------------------------- | | setItem | function(key, value) | A function taking a key and a value as parameters and saves the value referenced by the key | | getItem | function(key) | A function taking a key and returning the value saved with it |

LogLevel

A number indicating which type of events get logged.

| level | events | | ----- | -------- | | 0 | nothing | | >= 1 | errors | | >= 2 | warnings | | >= 3 | infos | | >= 4 | logs |

User

| field | type | description | | ---------- | ------ | --------------------------------- | | balance | number | The current balance of the user | | ownedItems | item[] | All the items which the user owns |

Logger

Every logger implementing the following methods can be used to log the events

| field | type | description | | ----- | ----------------- | ---------------------------------------------------------------------------------------------- | | log | function(...args) | A function accepting a undefined number of arguments as input and logs them as a log entry | | info | function(...args) | A function accepting a undefined number of arguments as input and logs them as a info entry | | warn | function(...args) | A function accepting a undefined number of arguments as input and logs them as a warning entry | | error | function(...args) | A function accepting a undefined number of arguments as input and logs them as a error entry |

SaveFunction

The save function's this value is binded to the ptm instance. The only parameter passed to the save function is the user that should be saved.

LoadFunction

The load function's this value is binded to the ptm instance. The load function has to return the user object as defined in the User type and may not return a promise.