@cactus-agents/gamification

SDK de gamificacao via Smartico. Expoe services para usuarios autenticados e visitantes, widget actions, eventos e geracao de hash server-side.

Diferente dos demais pacotes do SDK, nao usa HTTP/ApiClient — injeta diretamente window._smartico.api (autenticado) e window._smartico.vapi() (visitante).

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

Tipos exportados

Entidades

UserProfile, Level, LevelCurrent, Mission, MissionTask, RelatedGame, Ribbon, Tournament, TournamentDetailed, TournamentPlayer, TournamentPrize, StoreItem, StoreCategory, MiniGameTemplate, MiniGamePrize, MiniGamePrizeType, Bonus, JackpotDetails, JackpotFilter, JackpotWinner, Raffle, RaffleDraw, RaffleDrawRun, RaffleDrawDetailed, RaffleWinner, InboxMessage, InboxMessageBody, InboxMessageType, InboxParams, LeaderBoardDetails, LeaderBoardEntry, ActivityLogEntry, AchCategory, CustomSection

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)​

Tipos exportados​

Entidades​

Resultados​

Config​

Interfaces SDK​