Progression Hooks

usePoints

const points = usePoints({ engagementId: 'YOUR_UUID' });

points.balance          // number — current balance
points.totalEarned      // number — lifetime earned
points.currentTier      // { tier_name, tier_level, color } | null
points.transactions     // PointsTransaction[] — recent history
points.isLoading        // boolean
points.refresh()        // Manual refresh

// Auto-refreshes when:
// - points:awarded event fires
// - tier:changed event fires

useTier

const tier = useTier({ engagementId: 'YOUR_UUID' });

tier.currentTier        // CurrentTier | null
tier.tierName           // string | null (e.g. "Gold")
tier.tierLevel          // number (e.g. 3)
tier.tierColor          // string | null (hex color)
tier.pointsToNext       // number | null (points needed for next tier)
tier.nextTierName       // string | null
tier.isLoading          // boolean
tier.refresh()          // Manual refresh

useBadgesHeadless

const badges = useBadgesHeadless({
  engagementId: 'YOUR_UUID',
  badgeCodes: ['first_quiz', 'streak_7', 'top_scorer'], // optional filter
  refreshInterval: 30000, // ms, default 30s
});

badges.badges           // BadgeStatusEntry[] — all badges
badges.earned           // BadgeStatusEntry[] — earned only
badges.unearned         // BadgeStatusEntry[] — not yet earned
badges.isLoading        // boolean
badges.refresh()        // Manual refresh
badges.isEarned('code') // Check if a specific badge is earned

// Each badge: { code, name, description, icon, rarity, earned, earnedAt }
// Auto-refreshes every 30s + instantly on badge:unlocked events

useChallenge

Full challenge lifecycle — load, enroll, track progress, and display leaderboard.

const challenge = useChallenge({
  engagementId: 'YOUR_UUID',
  autoEnroll: true,       // Auto-enroll on load (default: false)
  refreshInterval: 30000, // ms
});

// Challenge definition
challenge.challenge           // ChallengeDetail | null
challenge.objectives          // ChallengeObjective[]
challenge.milestones          // ChallengeMilestone[]

// Enrollment
challenge.isEnrolled          // boolean
challenge.enroll()            // Manual enroll action

// Progress
challenge.progress            // ChallengeProgress | null
challenge.progressPercentage  // number (0-100)
challenge.objectiveProgress   // ObjectiveProgress[]
challenge.completedObjectives // number
challenge.totalObjectives     // number

// Leaderboard
challenge.leaderboard         // LeaderboardEntry[]
challenge.myRank              // number | null

// State
challenge.isLoading           // boolean
challenge.error               // Error | null
challenge.refresh()           // Manual refresh

// Auto-refreshes on activity:completed events

useLeaderboard

Supports both progression leaderboards (by code) and challenge leaderboards.

// Progression leaderboard (by code)
const lb = useLeaderboard({
  code: 'main_leaderboard',
  engagementId: 'YOUR_UUID',
  limit: 20,
  refreshInterval: 30000,
});

// Or challenge leaderboard (by challengeId)
const lb = useLeaderboard({
  challengeId: 'CHALLENGE_UUID',
  engagementId: 'YOUR_UUID',
  limit: 10,
});

lb.entries              // LeaderboardEntry[] — { rank, name, score, userId, change }
lb.myRank               // number | null
lb.totalParticipants    // number
lb.isLoading            // boolean
lb.refresh()            // Manual refresh

useRewardsHeadless

const rewards = useRewardsHeadless({ engagementId: 'YOUR_UUID' });

rewards.rewards         // ClaimedReward[] — all claimed rewards
rewards.totalClaimed    // number
rewards.isLoading       // boolean
rewards.refresh()       // Manual refresh

// Each reward: { id, rewardName, rewardType, codeValue, value, claimedAt, expiresAt }
// Auto-refreshes instantly on reward:claimed events