@cactus-agents/gamification

SDK de gamificacao. Tem duas camadas independentes:

Smartico — services para usuario autenticado e visitante, widget actions, eventos e geracao de hash server-side. Essa camada nao usa HTTP/ApiClient: injeta diretamente window._smartico.api (autenticado) e window._smartico.vapi() (visitante).
Rewards (BFF) — service HTTP normal, com fetcher injection como o resto do SDK. Ver Rewards.

Alem disso o pacote exporta quatro familias de helpers de display puros (niveis, missoes, mini-games, torneios) — sao as regras que o base consome para nao reimplementar estado de UI. Ver Helpers de display.

Instalacao

pnpm add @cactus-agents/gamification

Uso basico

Usuario autenticado

import { createGamificationService } from '@cactus-agents/gamification';

const service = createGamificationService(window._smartico.api);

const missions = await service.getMissions();
const profile = await service.getUserProfile();
const tournaments = await service.getTournaments();

Visitante (nao autenticado)

import { createVisitorGamificationService } from '@cactus-agents/gamification';

const visitorService = createVisitorGamificationService(window._smartico.vapi());

const missions = await visitorService.getMissions();
const tournaments = await visitorService.getTournaments();

API — GamificationService (autenticado)

Profile

Metodo	Retorno	Descricao
`getUserProfile()`	`Promise<UserProfile>`	Perfil do usuario (avatar, nome, coins, nivel)

Missions

Metodo	Retorno	Descricao
`getMissions(opts?)`	`Promise<Mission[]>`	Lista missoes. `opts.onUpdate` recebe callback de atualizacao em tempo real
`getBadges()`	`Promise<Mission[]>`	Badges do usuario
`getAchCategories()`	`Promise<AchCategory[]>`	Categorias de conquistas
`optInMission(missionId: number)`	`Promise<MissionOptInResult>`	Opt-in em missao
`claimMissionReward(missionId: number, achCompletedId: number)`	`Promise<MissionClaimResult>`	Resgatar recompensa de missao. Requer `missionId` e `achCompletedId`

Tournaments

Metodo	Retorno	Descricao
`getTournaments(opts?)`	`Promise<Tournament[]>`	Lista torneios. `opts.onUpdate` recebe callback de atualizacao
`getTournamentDetails(instanceId: number)`	`Promise<TournamentDetailed>`	Detalhe do torneio (leaderboard, premios)
`registerInTournament(instanceId: number)`	`Promise<TournamentRegistrationResult>`	Registrar no torneio

Store

Metodo	Retorno	Descricao
`getStoreItems(opts?)`	`Promise<StoreItem[]>`	Itens da loja. `opts.onUpdate` recebe callback
`getStoreCategories()`	`Promise<StoreCategory[]>`	Categorias da loja
`getStorePurchasedItems(params?)`	`Promise<StoreItem[]>`	Itens comprados. `params`: `limit`, `offset`, `onUpdate`
`buyStoreItem(itemId: number)`	`Promise<BuyStoreItemResult>`	Comprar item

Mini-games

Metodo	Retorno	Descricao
`getMiniGames(opts?)`	`Promise<MiniGameTemplate[]>`	Templates de mini-games. `opts.onUpdate` recebe callback
`playMiniGame(templateId: number, opts?)`	`Promise<MiniGamePlayResult>`	Jogar mini-game. `opts.onUpdate` opcional
`playMiniGameBatch(templateId: number, spinCount: number, opts?)`	`Promise<MiniGamePlayBatchResult[]>`	Jogar batch. `opts.onUpdate` opcional
`acknowledgeMiniGameWin(requestId: string)`	`Promise<unknown>`	Confirmar premio recebido

Levels

Metodo	Retorno	Descricao
`getLevels()`	`Promise<Level[]>`	Todos os niveis
`getCurrentLevel()`	`Promise<LevelCurrent>`	Nivel atual + progresso

Bonuses

Metodo	Retorno	Descricao
`getBonuses(opts?)`	`Promise<Bonus[]>`	Bonus disponiveis. `opts.onUpdate` recebe callback
`claimBonus(bonusId: number)`	`Promise<ClaimBonusResult>`	Resgatar bonus

Jackpots

Metodo	Retorno	Descricao
`getJackpots(filter?)`	`Promise<JackpotDetails[]>`	Lista jackpots. `filter` opcional do tipo `JackpotFilter`
`jackpotOptIn(templateId: number)`	`Promise<JackpotOptinResponse>`	Opt-in por `templateId`
`jackpotOptOut(templateId: number)`	`Promise<JackpotOptoutResponse>`	Opt-out por `templateId`
`getJackpotWinners(params)`	`Promise<JackpotWinner[]>`	Ganhadores. `params`: `jp_template_id?`, `limit?`, `offset?`

Raffles

Metodo	Retorno	Descricao
`getRaffles(opts?)`	`Promise<Raffle[]>`	Lista raffles. `opts.onUpdate` recebe callback
`getRaffleDrawRun(params)`	`Promise<RaffleDrawDetailed>`	Sorteio detalhado. `params`: `raffle_id`, `run_id`, `winners_from?`, `winners_to?`
`getRaffleDrawRunsHistory(params)`	`Promise<RaffleDrawRun[]>`	Historico de sorteios. `params`: `raffle_id`, `draw_id?`
`requestRaffleOptin(params)`	`Promise<RaffleOptinResponse>`	Opt-in em raffle. `params`: `raffle_id`, `draw_id`, `raffle_run_id`
`claimRafflePrize(wonId: number)`	`Promise<RaffleClaimPrizeResponse>`	Resgatar premio de raffle

Inbox

Metodo	Retorno	Descricao
`getInboxMessages(params?)`	`Promise<InboxMessage[]>`	Mensagens. `params` do tipo `InboxParams`
`getInboxMessageBody(guid: string)`	`Promise<InboxMessageBody>`	Corpo da mensagem por `guid`
`getInboxUnreadCount(params?)`	`Promise<number>`	Contagem de nao lidas. `params.onUpdate` para realtime
`markInboxRead(guid: string)`	`Promise<InboxMarkAction>`	Marcar como lida
`markAllInboxRead()`	`Promise<InboxMarkAction>`	Marcar todas como lidas
`toggleInboxFavorite(guid: string, mark: boolean)`	`Promise<InboxMarkAction>`	Favoritar (`mark: true`) ou desfavoritar (`mark: false`)
`deleteInboxMessage(guid: string)`	`Promise<InboxMarkAction>`	Excluir mensagem
`deleteAllInboxMessages()`	`Promise<InboxMarkAction>`	Excluir todas

Leaderboard & Activity

Metodo	Retorno	Descricao
`getLeaderBoard(periodType: number, getPreviousPeriod?: boolean)`	`Promise<LeaderBoardDetails>`	Leaderboard por tipo de periodo. `getPreviousPeriod` retorna periodo anterior
`getActivityLog(params)`	`Promise<ActivityLogEntry[]>`	Log de atividades. `params`: `startTimeSeconds`, `endTimeSeconds`, `from`, `to`, `onUpdate?`

Outros

Metodo	Retorno	Descricao
`getCustomSections()`	`Promise<CustomSection[]>`	Secoes customizadas
`getTranslations(langCode: string)`	`Promise<Record<string, string>>`	Traducoes i18n Smartico por codigo de idioma

API — VisitorGamificationService

Subset read-only para usuarios nao autenticados (15 metodos). Mesmas assinaturas do service autenticado, sem metodos de escrita:

Metodo	Retorno
`getMissions(opts?)`	`Promise<Mission[]>`
`getTournaments(opts?)`	`Promise<Tournament[]>`
`getTournamentDetails(instanceId: number)`	`Promise<TournamentDetailed>`
`getStoreItems(opts?)`	`Promise<StoreItem[]>`
`getStoreCategories()`	`Promise<StoreCategory[]>`
`getMiniGames(opts?)`	`Promise<MiniGameTemplate[]>`
`getLevels()`	`Promise<Level[]>`
`getJackpots(filter?)`	`Promise<JackpotDetails[]>`
`getRaffles(opts?)`	`Promise<Raffle[]>`
`getRaffleDrawRun(params)`	`Promise<RaffleDrawDetailed>`
`getRaffleDrawRunsHistory(params)`	`Promise<RaffleDrawRun[]>`
`getLeaderBoard(periodType: number, getPreviousPeriod?: boolean)`	`Promise<LeaderBoardDetails>`
`getAchCategories()`	`Promise<AchCategory[]>`
`getCustomSections()`	`Promise<CustomSection[]>`
`getTranslations(langCode: string)`	`Promise<Record<string, string>>`

WidgetAction

Constantes para abrir widgets overlay do Smartico via window._smartico.dp(action):

import { WidgetAction } from '@cactus-agents/gamification';

window._smartico.dp(WidgetAction.MAIN);           // Tela principal
window._smartico.dp(WidgetAction.TOURNAMENTS);     // Torneios
window._smartico.dp(WidgetAction.MISSIONS);         // Missoes
window._smartico.dp(WidgetAction.STORE);            // Loja
window._smartico.dp(WidgetAction.CHANGE_AVATAR);    // Trocar avatar
window._smartico.dp(WidgetAction.CHANGE_NICKNAME);  // Trocar apelido
window._smartico.dp(WidgetAction.miniGame(123));     // Mini-game especifico
window._smartico.dp(WidgetAction.storeItem(456));    // Item da loja

SmarticoEvent

Eventos emitidos pelo SDK:

Evento	Valor	Descricao
`PROPS_CHANGE`	`'props_change'`	Propriedades do usuario mudaram
`GF_CLOSING`	`'gf_closing'`	Widget de gamificacao fechando
`TOURNAMENT_UPDATE`	`'tournament_update'`	Torneio atualizado
`TOURNAMENT_REGISTRATION`	`'tournament_registration'`	Registro em torneio
`MISSION_UPDATE`	`'mission_update'`	Missao atualizada
`MISSION_COMPLETED`	`'mission_completed'`	Missao completada

import { SmarticoEvent } from '@cactus-agents/gamification';

window._smartico.on(SmarticoEvent.MISSION_COMPLETED, (data) => {
  console.log('Missao completada:', data);
});

Hash de Usuario (server-side)

Gera o hash MD5 para identificacao do usuario no Smartico. Deve ser executado apenas no server.

import { generateUserHash } from '@cactus-agents/gamification';
import { createHash } from 'node:crypto';

const md5 = (input: string) => createHash('md5').update(input).digest('hex');

const hash = generateUserHash(userId, { saltKey }, md5);
// hash e passado ao client via loader

Rewards (BFF)

Modulo HTTP, separado da camada Smartico. Segue o padrao de fetcher injection.

import { createApiClient } from "@cactus-agents/api-client";
import { createRewardsFromClient, transformRewardsResponse } from "@cactus-agents/gamification";

const rewards = createRewardsFromClient(createApiClient({ baseUrl, tenant, language }));

const raw = await rewards.getRewards({ status: "available", type: "freespins", page: 1 });
const page = transformRewardsResponse(raw);

Metodo	Verbo	Endpoint
`getRewards(filter)`	GET	`/bff/gamification/rewards?status=…&page=…&per_page=…&type=…`
`redeemReward(rewardId)`	POST	`/bff/gamification/redeem` (body `{ reward_id }`)

interface RewardsFilter {
  status: RewardTab;          // obrigatorio
  type?: RewardFilterType;    // "all" é tratado como ausencia de filtro
  page?: number;              // default 1
  perPage?: number;           // default 8
}

Transforms: transformReward (item) e transformRewardsResponse (pagina + paginacao).

Tipos: Reward, RewardRaw, RewardStatus, RewardType, RewardTab, RewardFilterType, RewardsFilter, RewardsService, RewardsPaginatedResponse(+Raw), RewardsPagination, RedeemResponseRaw.

Helpers de display

Funcoes puras que traduzem entidade + tempo atual em estado de UI. É a fronteira "o core fornece as regras, o base monta o layout": não reimplemente essas condições no componente.

Niveis

Export	Descricao
`getLevelsState(...)`	Estado consolidado da trilha de niveis
Tipos	`LevelsState`, `LevelWithState`, `LevelTimelineState`

Missoes

Export	Descricao
`getMissionDisplayState(...)`	Estado de exibicao da missao
`getMissionClaimInfo(...)`	Se/como o premio pode ser resgatado
`getMissionRecurrenceInfo(...)`	Info de recorrencia (diaria/semanal/etc.)
`isMissionAvailableForCarousel(...)`	Elegibilidade para o carrossel
`isMissionExpiredOrMissed(...)` / `isMissionUpcoming(...)`	Predicados de janela temporal
Tipos	`MissionDisplayState`, `MissionClaimInfo`, `MissionRecurrenceInfo`

Mini-games

Export	Descricao
`getMiniGameDisplayState(...)`	Estado de exibicao
`getMiniGameAvailabilityMessage(...)`	Mensagem de indisponibilidade
`getMiniGameCooldownSeconds(...)`	Segundos restantes de cooldown
`isMiniGamePlayable(...)` / `isMiniGameVisibleInCarousel(...)`	Predicados
Tipo	`MiniGameDisplayState`

Torneios

Export	Descricao
`getTournamentDisplayState(...)`	Estado de exibicao
`getTournamentRibbon(...)` / `getTournamentStatusPill(...)`	Ribbon e pill de status
`getTournamentRegistrationStatus(...)` / `getTournamentRegistrationType(...)`	Estado e tipo de inscricao
`getTournamentHeroImage(...)`	Resolucao da imagem hero
`dedupeTournamentsByTemplate(...)`	Colapsa recorrencias do mesmo template
Tipos	`TournamentDisplayState`, `TournamentRibbon`, `TournamentRibbonPreset`, `TournamentRibbonDurationBucket`, `TournamentStatusPill`, `TournamentRegistrationStatus`, `TournamentRegistrationType`

Tipos exportados

Entidades

UserProfile, Level, LevelCurrent, Mission, MissionTask, RelatedGame, Ribbon, Tournament, TournamentDetailed, TournamentPlayer, TournamentPrize, StoreItem, StoreCategory, StoreItemType, StoreItemPurchaseType, MiniGameTemplate, MiniGamePrize, MiniGamePrizeType, Bonus, JackpotDetails, JackpotFilter, JackpotPot, JackpotPublicMeta, JackpotWinner, Raffle, RaffleDraw, RaffleDrawRun, RaffleDrawDetailed, RaffleDrawPublicMeta, RafflePrize, RafflePrizePublicMeta, RafflePrizeWinner, RaffleTicket, InboxMessage, InboxMessageBody, InboxMessageType, InboxParams, LeaderBoardDetails, LeaderBoardEntry, LeaderBoardReward, ActivityLogEntry, AchCategory, CustomSection

:::caution RaffleWinner não existe O tipo do ganhador de sorteio é RafflePrizeWinner. Não há export chamado RaffleWinner. :::

Enums

AchievementAvailabilityStatus, BonusStatus

Resultados

MissionOptInResult, MissionClaimResult, TournamentRegistrationResult, BuyStoreItemResult, MiniGamePlayResult, MiniGamePlayBatchResult, ClaimBonusResult, JackpotOptinResponse, JackpotOptoutResponse, RaffleOptinResponse, RaffleClaimPrizeResponse, InboxMarkAction

Config

GamificationConfig, GamificationModuleConfig, HashConfig

Interfaces SDK

SmarticoApi, SmarticoVisitorApi

Instalacao​

Uso basico​

Usuario autenticado​

Visitante (nao autenticado)​

API — GamificationService (autenticado)​

Profile​

Missions​

Tournaments​

Store​

Mini-games​

Levels​

Bonuses​

Jackpots​

Raffles​

Inbox​

Leaderboard & Activity​

Outros​

API — VisitorGamificationService​

WidgetAction​

SmarticoEvent​

Hash de Usuario (server-side)​

Rewards (BFF)​

Helpers de display​

Niveis​

Missoes​

Mini-games​

Torneios​

Tipos exportados​

Entidades​

Enums​

Resultados​

Config​

Interfaces SDK​

Instalacao

Uso basico

Usuario autenticado

Visitante (nao autenticado)

API — GamificationService (autenticado)

Profile

Missions

Tournaments

Store

Mini-games

Levels

Bonuses

Jackpots

Raffles

Inbox

Leaderboard & Activity

Outros

API — VisitorGamificationService

WidgetAction

SmarticoEvent

Hash de Usuario (server-side)

Rewards (BFF)

Helpers de display

Niveis

Missoes

Mini-games

Torneios

Tipos exportados

Entidades

Enums

Resultados

Config

Interfaces SDK