Class StatusPointsModule

This class allows you to interact with the StatusPoints module. The StatusPoints module allows to distribute Status Points to users to reward engagement.

Methods

getBalance getPerformedActions getStatusPointsForAction giveStatusPointsOnAction undoAction

Methods

getBalance

  • getBalance(userId): Promise<number>

  • Returns the total number of Status Points the user has collected.

    Parameters

    • userId: string

      the id of the user.

    Returns Promise<number>

    an object containing the total amount of Status Points the user has collected.

    Throws

    RequestError if the user does not exist (unknownUserError).

getPerformedActions

  • getPerformedActions(userId, limit?, earlierThan?): Promise<{
        actionCategory: string;
        actionId: string;
        amount: number;
        date: string;
        description: string;
        partnerId: string;
        title: string;
        userId: string;
    }[]>

  • Returns all Status Points actions of the given user.

    If limit is given, at most limit actions will be returned. If earlierThan is given, only actions that happened before this action will be returned. Combine both parameters to paginate the results.

    Parameters

    • userId: string

      the id of the user

    • Optionallimit: number

      the maximum number of actions to return

    • OptionalearlierThan: Date

      if given, actions before this date will be returned

    Returns Promise<{
        actionCategory: string;
        actionId: string;
        amount: number;
        date: string;
        description: string;
        partnerId: string;
        title: string;
        userId: string;
    }[]>

    an list of the actions sorted by date.

    Throws

    RequestError if the user does not exist (unknownUserError).

getStatusPointsForAction

  • getStatusPointsForAction(actionCategory, specificPartnerId?): Promise<number>

  • Returns the amount of Status Points the user would receive for the given action.

    This allows you to check how many Status Points a user would receive for a given action. It does not actually distribute the Status Points. Use giveStatusPointsOnAction to distribute Status Points.

    Parameters

    • actionCategory: string

      the action to check

    • OptionalspecificPartnerId: string

      the id of the specific partner if multiple partners are configured

    Returns Promise<number>

    an object containing the amount of Status Points the user would receive.

    Throws

    RequestError if the action category does not exist (invalidActionCategoryError).

giveStatusPointsOnAction

  • giveStatusPointsOnAction(userId, actionCategory, title, description, customActionId?, specificPartnerId?): Promise<{
        actionCategory: string;
        actionId: string;
        amount: number;
        date: string;
        description: string;
        partnerId: string;
        title: string;
        userId: string;
    }>

  • Distributes Status Points to a user. This allows users to earn Status Points to reward them for engaging with the given partner.

    Every distribution is connected to an action and a partner. The actual number of Status Points the user receives depends on the action and the partner and can be accessed using the getStatusPointsForAction method and can be set in the FanPoints backend.

    The title and description can be used to add human readable information on the action that could be used to display to the user.

    A custom action id can be given in order to link the action to a specific event on your side. This operation is idempotent w.r.t. the custom action id. This means that if you call this method twice with the same custom action id, the second call will not have any effect and an error will be thrown.

    Parameters

    • userId: string

      the id of the user

    • actionCategory: string

      the category of the action performed

    • title: string

      the title of the action

    • description: string

      the description of the action

    • OptionalcustomActionId: string

      the id of the custom action to link it to an event on your side

    • OptionalspecificPartnerId: string

      the id of the specific partner if multiple partners are configured

    Returns Promise<{
        actionCategory: string;
        actionId: string;
        amount: number;
        date: string;
        description: string;
        partnerId: string;
        title: string;
        userId: string;
    }>

    an list containing the performed Status Points transactions.

    Throws

    RequestError if the user does not exist (unknownUserError), if the custom action id is not valid (invalidTransactionIdError), if a transaction with the given custom action id already exists (alreadyExecutedError), or if the action category does not exist (invalidActionCategoryError).

undoAction

  • undoAction(userId, actionId, specificPartnerId?): Promise<{
        actionCategory: string;
        actionId: string;
        amount: number;
        date: string;
        description: string;
        partnerId: string;
        title: string;
        userId: string;
    }>

  • Undoes an action.

    This will reverse the effect of giving Status Points to the user.

    Undoing an action corresponds to creating a new action with a negative number of Status Points. This operation is idempotent w.r.t. the action id. This means that if you call this method twice with the same arguments, the second call will not have any effect and an error is thrown.

    If you configured multiple partners, you can use the specificPartnerId parameter to specify the partner where the action happened. If you configured multiple partners and don't provide a specificPartnerId, the default partner will be used.

    Parameters

    • userId: string

      the id of the user that performed the action

    • actionId: string

      the id of the action to undo

    • OptionalspecificPartnerId: string

      the id of the partner where the action happened if multiple partners are configured

    Returns Promise<{
        actionCategory: string;
        actionId: string;
        amount: number;
        date: string;
        description: string;
        partnerId: string;
        title: string;
        userId: string;
    }>

    the performed undo actions.

    Throws

    RequestError if the action does not exist (transactionNotFoundError), or if the action has already been undone (alreadyExecutedError).

Settings

Member Visibility

On This Page

Methods