Rewards Processor Module

The Rewards Processor Module provides functionality for managing player rewards, including claiming rewards, activating boosters, and retrieving information about active boosters and rewards in the Gamanza Engage Web Client SDK.

Accessing the Module

The RewardsProcessorModule is initialized internally by the SDK and should not be instantiated directly. It's accessible through the main SDK instance.

// Example of accessing the RewardsProcessorModule through the SDK
const { RewardsProcessor } = GamanzaEngageWebClientSDK.getInstance();

Methods

playerClaimRewardsByGroupId

Sends a request to claim player rewards by the reward group ID.

Signature:

playerClaimRewardsByGroupId(groupId: string): Promise<SimpleResponse<ClaimableRewardsType[]>>

Parameters:

Name	Type	Description
groupId	string	The unique identifier of the reward group to claim

Returns:

Type	Description
Promise<SimpleResponse<ClaimableRewardsType[]>>	A promise that resolves to a simple response containing an array of claimed rewards or an error

Example:

// Claim rewards by group ID
const groupId = "group-123";
const response = await sdk.RewardsProcessor.playerClaimRewardsByGroupId(groupId);

if (response.ok) {
  console.log('Successfully claimed rewards:', response.data);
} else {
  console.error('Failed to claim rewards:', response.error);
}

playerClaimMissionRewards

Sends a request to claim mission rewards for the current authenticated player.

Claims a reward originated from a completed mission.

⚠️ This method is part of the RewardsProcessor module, not the Missions module.

The parameters required (bundleStateId and missionStateId) must be extracted from the metadata of rewards where the source === "missions" returned by getPlayerRewards().

Signature:

playerClaimMissionRewards(playerBundleStateId: string, missionStateId: string): Promise<SimpleResponse<ClaimableRewardsType[]>>

Parameters:

Name	Type	Description
playerBundleStateId	string	The unique identifier of the player bundle state
missionStateId	string	The unique identifier of the mission state

Returns:

Type	Description
Promise<SimpleResponse<ClaimableRewardsType[]>>	A promise that resolves to a simple response containing an array of claimed rewards or an error

Example:

// Claim mission rewards
const playerBundleStateId = "bundle-state-123";
const missionStateId = "mission-state-456";

const response = await sdk.RewardsProcessor.playerClaimMissionRewards(
  playerBundleStateId,
  missionStateId
);

if (response.ok) {
  console.log('Successfully claimed mission rewards:', response.data);
} else {
  console.error('Failed to claim mission rewards:', response.error);
}

playerActivateBooster

Activates a booster granted to the current authenticated player.

Signature:

playerActivateBooster(rewardId: string, payload: ActivateBoosterRequest): Promise<SimpleResponse<PlayerRewardActive>>

Parameters:

Name	Type	Description
rewardId	string	The unique identifier of the reward to be activated
payload	ActivateBoosterRequest	Additional information required to activate the booster based on the type

Returns:

Type	Description
Promise<SimpleResponse<PlayerRewardActive>>	A promise that resolves to a simple response containing the activated reward or an error

Example:

// Activate a level booster
const rewardId = "reward-123";
const payload = {
  boosterType: "level",
  levelId: "level-456"
};

const response = await sdk.RewardsProcessor.playerActivateBooster(rewardId, payload);

if (response.ok) {
  console.log('Successfully activated booster:', response.data);
} else {
  console.error('Failed to activate booster:', response.error);
}

// Activate a mission booster
const missionBoosterPayload = {
  boosterType: "mission",
  missionId: "mission-789"
};

const missionResponse = await sdk.RewardsProcessor.playerActivateBooster(
  "reward-456", 
  missionBoosterPayload
);

getPlayerActiveLevelBooster

Returns the list of active level boosters for the current authenticated player.

Signature:

getPlayerActiveLevelBooster(): Promise<PlayerLevelBooster[]>

Returns:

Type	Description
Promise<PlayerLevelBooster[]>	A promise that resolves to an array of active level boosters

Example:

// Get active level boosters
const levelBoosters = await sdk.RewardsProcessor.getPlayerActiveLevelBooster();

console.log(`Found ${levelBoosters.length} active level boosters`);
levelBoosters.forEach(booster => {
  console.log(`Booster ID: ${booster.id}`);
  console.log(`Booster Rate: ${booster.boosterRate}`);
  console.log(`Active from ${booster.timeStart} to ${booster.timeEnd}`);
});

getPlayerActiveMissionBoosters

Returns the list of active mission boosters for the current authenticated player.

Signature:

getPlayerActiveMissionBoosters(): Promise<PlayerMissionsBooster[]>

Returns:

Type	Description
Promise<PlayerMissionsBooster[]>	A promise that resolves to an array of active mission boosters

Example:

// Get active mission boosters
const missionBoosters = await sdk.RewardsProcessor.getPlayerActiveMissionBoosters();

console.log(`Found ${missionBoosters.length} active mission boosters`);
missionBoosters.forEach(booster => {
  console.log(`Booster ID: ${booster._id}`);
  console.log(`Booster Rate: ${booster.boosterRate}`);
  console.log(`Active from ${booster.timeStart} to ${booster.timeEnd}`);
});

getPlayerActiveTokenBoosters

Returns the list of active token boosters for the current authenticated player.

Signature:

getPlayerActiveTokenBoosters(): Promise<PlayerTokensBooster[]>

Returns:

Type	Description
Promise<PlayerTokensBooster[]>	A promise that resolves to an array of active token boosters

Example:

// Get active token boosters
const tokenBoosters = await sdk.RewardsProcessor.getPlayerActiveTokenBoosters();

console.log(`Found ${tokenBoosters.length} active token boosters`);
tokenBoosters.forEach(booster => {
  console.log(`Booster ID: ${booster._id}`);
  console.log(`Booster Rate: ${booster.boosterRate}`);
  console.log(`Active from ${booster.timeStart} to ${booster.timeEnd}`);
});

getPlayerAllActiveBoostersByType

Returns the list of all active boosters by type for the current authenticated player.

Signature:

getPlayerAllActiveBoostersByType(): Promise<ActiveRewardsByType>

Returns:

Type	Description
Promise<ActiveRewardsByType>	A promise that resolves to an object containing arrays of different types of active boosters

Example:

// Get all active boosters by type
const allBoosters = await sdk.RewardsProcessor.getPlayerAllActiveBoostersByType();

console.log(`Level Boosters: ${allBoosters.levelBoosters.length}`);
console.log(`Mission Boosters: ${allBoosters.missionBoosters.length}`);
console.log(`Token Boosters: ${allBoosters.tokenBoosters.length}`);

// Access specific booster types
if (allBoosters.levelBoosters.length > 0) {
  const firstLevelBooster = allBoosters.levelBoosters[0];
  console.log(`First Level Booster Rate: ${firstLevelBooster.boosterRate}`);
}

getPlayerRewards

Returns the list of rewards for the current authenticated player. The response can be modified based on the request argument filters.

Signature:

getPlayerRewards(request: ListRewardsRequest): Promise<PaginationResponse<PlayerRewardActive[]>>

Parameters:

Name	Type	Description
request	ListRewardsRequest	Object containing filter parameters for the rewards list

Returns:

Type	Description
Promise<PaginationResponse<PlayerRewardActive[]>>	A promise that resolves to a paginated response containing an array of player rewards

Example:

// Get player rewards with filters
const request = {
  limit: 10,
  page: 1,
  status: ["active", "granted"],
  rewardType: ["tokens", "level_booster"]
};

const response = await sdk.RewardsProcessor.getPlayerRewards(request);

console.log(`Total rewards: ${response.totalDocs}`);
console.log(`Page ${response.page} of ${response.totalPages}`);

response.docs.forEach(reward => {
  console.log(`Reward ID: ${reward.id}`);
  console.log(`Status: ${reward.status}`);
  console.log(`Activation: ${reward.activation}`);
});

// Get next page
if (response.hasNextPage) {
  const nextPageRequest = {
    ...request,
    page: response.nextPage
  };
  const nextPageResponse = await sdk.RewardsProcessor.getPlayerRewards(nextPageRequest);
}

Related Interfaces

ActivateBoosterRequest

Interface for activating a booster.

interface ActivateBoosterRequest {
  boosterType: BoosterType;
  levelId?: string;
  missionId?: string;
}

Property	Type	Required	Description
boosterType	BoosterType	Yes	The type of booster to activate (level, mission, or tokens)
levelId	string	No	The level ID (required when boosterType is "level")
missionId	string	No	The mission ID (required when boosterType is "mission")

BoosterType

Enum for booster types.

enum BoosterType {
  LEVEL = 'level',
  MISSION = 'mission',
  TOKENS = 'tokens',
}

Value	Description
LEVEL	Level booster type
MISSION	Mission booster type
TOKENS	Tokens booster type

PlayerRewardActive

Interface for active player rewards.

interface PlayerRewardActive {
  id: string;
  status: RewardStatusEnum | ExternalRewardStatus;
  playerId: string;
  activation: ActivationType;
  playerCategoryId: string;
  earnedReward: Record<string, any>;
  metadata?: Record<string, any>;
  trigger?: string;
  expirationDate?: Date;
  countdown?: ActiveCountdownBoosterType;
  group?: RewardGroup;
  source?: string;
}

Property	Type	Required	Description
id	string	Yes	Unique identifier for the reward
status	RewardStatusEnum | ExternalRewardStatus	Yes	Current status of the reward
playerId	string	Yes	Identifier of the player who owns the reward
activation	ActivationType	Yes	How the reward is activated (automatic or by player)
playerCategoryId	string	Yes	Category identifier for the player
earnedReward	Record<string, any>	Yes	Details of the earned reward
metadata	Record<string, any>	No	Additional metadata for the reward
trigger	string	No	What triggered the reward
expirationDate	Date	No	When the reward expires
countdown	ActiveCountdownBoosterType	No	Countdown until expiration
group	RewardGroup	No	Group information for the reward
source	string	No	The source of the reward for example CRM, Missions, etc

PlayerLevelBooster

Interface for player level boosters.

interface PlayerLevelBooster {
  id: string;
  playerId: string;
  rewardId: string;
  boosterRate: number;
  timeStart: Date;
  timeEnd: Date;
  status: RewardStatusEnum.ACTIVE | RewardStatusEnum.INACTIVE;
  metadata?: Record<string, any>;
}

Property	Type	Required	Description
id	string	Yes	Unique identifier for the level booster
playerId	string	Yes	Identifier of the player who owns the booster
rewardId	string	Yes	Identifier of the associated reward
boosterRate	number	Yes	Rate at which the booster applies
timeStart	Date	Yes	When the booster starts
timeEnd	Date	Yes	When the booster ends
status	RewardStatusEnum.ACTIVE | RewardStatusEnum.INACTIVE	Yes	Current status of the booster
metadata	Record<string, any>	No	Additional metadata for the booster

PlayerMissionsBooster

Interface for player mission boosters.

interface PlayerMissionsBooster extends Omit<PlayerLevelBooster, 'id'> {
  _id: string;
}

Property	Type	Required	Description
_id	string	Yes	Unique identifier for the mission booster
playerId	string	Yes	Identifier of the player who owns the booster
rewardId	string	Yes	Identifier of the associated reward
boosterRate	number	Yes	Rate at which the booster applies
timeStart	Date	Yes	When the booster starts
timeEnd	Date	Yes	When the booster ends
status	RewardStatusEnum.ACTIVE | RewardStatusEnum.INACTIVE	Yes	Current status of the booster
metadata	Record<string, any>	No	Additional metadata for the booster

PlayerTokensBooster

Interface for player token boosters.

interface PlayerTokensBooster extends Omit<PlayerLevelBooster, 'id'> {
  _id: string;
}

Property	Type	Required	Description
_id	string	Yes	Unique identifier for the token booster
playerId	string	Yes	Identifier of the player who owns the booster
rewardId	string	Yes	Identifier of the associated reward
boosterRate	number	Yes	Rate at which the booster applies
timeStart	Date	Yes	When the booster starts
timeEnd	Date	Yes	When the booster ends
status	RewardStatusEnum.ACTIVE | RewardStatusEnum.INACTIVE	Yes	Current status of the booster
metadata	Record<string, any>	No	Additional metadata for the booster

ActiveRewardsByType

Interface for active rewards grouped by type.

interface ActiveRewardsByType {
  levelBoosters: PlayerLevelBooster[];
  missionBoosters: PlayerMissionsBooster[];
  tokenBoosters: PlayerTokensBooster[];
}

Property	Type	Required	Description
levelBoosters	PlayerLevelBooster[]	Yes	Array of active level boosters
missionBoosters	PlayerMissionsBooster[]	Yes	Array of active mission boosters
tokenBoosters	PlayerTokensBooster[]	Yes	Array of active token boosters

ListRewardsRequest

Interface for filtering player rewards.

interface ListRewardsRequest extends Omit<PaginationRequest, 'order'> {
  playerId?: string;
  status?: RewardStatusEnum;
  activation?: ActivationType;
  source?: string;
  rewardType?: RewardTypeEnum;
  startDate?: Date;
  endDate?: Date;
}

Property	Type	Required	Description
playerId	string	No	Filter by player ID
status	RewardStatusEnum[]	No	Filter by reward status
activation	ActivationType	No	Filter by activation type
source	string	No	Filter by source
rewardType	RewardTypeEnum[]	No	Filter by reward type
startDate	Date	No	Filter by start date
endDate	Date	No	Filter by end date
limit	number	No	Number of items per page (from PaginationRequest)
page	number	No	Page number (from PaginationRequest)

ClaimableRewardsType

Interface for claimable rewards.

type ClaimableRewardsType = {
  id: string;
  playerId: string;
  status: ClaimableRewardStatusEnum;
  activation: 'automatic' | 'by_player';
  playerCategoryId: string;
  earnedReward: unknown;
  metadata: Record<string, unknown>;
  trigger?: string;
  expirationDate: string;
  countdown: string;
};

Property	Type	Required	Description
id	string	Yes	Unique identifier for the reward
playerId	string	Yes	Identifier of the player who owns the reward
status	ClaimableRewardStatusEnum	Yes	Current status of the reward
activation	'automatic' | 'by_player'	Yes	How the reward is activated
playerCategoryId	string	Yes	Category identifier for the player
earnedReward	unknown	Yes	Details of the earned reward
metadata	Record<string, unknown>	Yes	Additional metadata for the reward
trigger	string	No	What triggered the reward
expirationDate	string	Yes	When the reward expires (ISO 8601 format)
countdown	string	Yes	Remaining time until expiration (e.g., "9d 17h 27m")

RewardStatusEnum

Enum for reward statuses.

enum RewardStatusEnum {
  ACTIVE = 'active',
  INACTIVE = 'inactive',
  GRANTED = 'granted',
  PENDING = 'pending',
  IN_PROGRESS = 'in_progress',
  COMPLETED = 'completed',
  FAILED = 'failed',
  CLAIMED = 'claimed',
  UNCLAIMED = 'unclaimed',
  DELETED = 'deleted',
  EXPIRED = 'expired',
}

Value	Description
ACTIVE	Reward is active
INACTIVE	Reward is inactive
GRANTED	Reward has been granted
PENDING	Reward is pending
IN_PROGRESS	Reward is in progress
COMPLETED	Reward is completed
FAILED	Reward has failed
CLAIMED	Reward has been claimed
UNCLAIMED	Reward is unclaimed
DELETED	Reward has been deleted
EXPIRED	Reward has expired

ClaimableRewardStatusEnum

export enum ClaimableRewardStatusEnum {
    CLAIMED = 'claimed',
    UNCLAIMED = 'unclaimed',
    GRANTED = 'granted',
    PENDING = 'pending',
    IN_PROGRESS = 'in_progress',
    COMPLETED = 'completed',
    FAILED = 'failed',
    DELETED = 'deleted',
    EXPIRED = 'expired',
    DECLINED = 'declined',
}

PaginationResponse

Generic interface for paginated responses.

interface PaginationResponse<T> {
  docs: T;
  totalDocs: number;
  limit: number;
  totalPages: number;
  page: number;
  pagingCounter: number;
  hasPrevPage: boolean;
  hasNextPage: boolean;
  prevPage: number | null;
  nextPage: number | null;
}

Property	Type	Required	Description
docs	T	Yes	Array of items for the current page
totalDocs	number	Yes	Total number of items across all pages
limit	number	Yes	Number of items per page
totalPages	number	Yes	Total number of pages
page	number	Yes	Current page number
pagingCounter	number	Yes	The starting index of the current page
hasPrevPage	boolean	Yes	Whether there is a previous page
hasNextPage	boolean	Yes	Whether there is a next page
prevPage	number | null	Yes	Previous page number or null if none
nextPage	number | null	Yes	Next page number or null if none

SimpleResponse

Generic interface for simple responses.

interface SimpleResponse<T> {
  ok: boolean;
  data: T | null;
  error?: {
    code: string;
    message: string;
  };
}

Property	Type	Required	Description
ok	boolean	Yes	Whether the operation was successful
data	T | null	Yes	Response data or null if the operation failed
error	{ code: string; message: string; }	No	Error information if the operation failed