@codingfactory/socialkit-vue 0.6.0 → 0.7.0

package/src/stores/gamification.ts

@@ -0,0 +1,1565 @@
+/**
+ * Generic gamification store factory for SocialKit-powered frontends.
+ */
+
+import { defineStore } from 'pinia'
+import { computed, onScopeDispose, ref } from 'vue'
+import type { AxiosInstance } from 'axios'
+import type {
+  Achievement,
+  AchievementShareCard,
+  AchievementUnlockNotification,
+  ClaimedReward,
+  LeaderboardEntry,
+  LeaderboardPeriod,
+  Quest,
+  QuestFilter,
+  QuestObjective,
+  Reward,
+  RewardTransaction,
+  UserStats,
+} from '../types/gamification.js'
+import type { ConnectionStatus } from '../types/realtime.js'
+
+export type {
+  Achievement,
+  AchievementShareCard,
+  AchievementUnlockNotification,
+  ClaimedReward,
+  LeaderboardEntry,
+  LeaderboardPeriod,
+  Quest,
+  QuestFilter,
+  QuestObjective,
+  Reward,
+  RewardTransaction,
+  UserStats,
+}
+
+export interface GamificationStoreCurrentUser {
+  id: string
+  tenant_id?: string | null
+  tenantId?: string | null
+}
+
+export interface GamificationRealtimeChannelLike {
+  listen(event: string, callback: (data: unknown) => void): GamificationRealtimeChannelLike
+  stopListening(event: string): GamificationRealtimeChannelLike
+}
+
+export interface GamificationRealtimeClientLike {
+  private(channel: string): GamificationRealtimeChannelLike
+  leave(channel: string): void
+}
+
+export interface GamificationStoreLogger {
+  debug: (...args: unknown[]) => void
+  error: (...args: unknown[]) => void
+}
+
+export interface GamificationStoreConfig {
+  client: AxiosInstance
+  getCurrentUser: () => GamificationStoreCurrentUser | null
+  getEcho: () => GamificationRealtimeClientLike | null
+  onConnectionStatusChange: (callback: (status: ConnectionStatus) => void) => (() => void) | void
+  logger?: GamificationStoreLogger
+  debug?: boolean
+  storeId?: string
+}
+
+interface LeaderboardQueryContext {
+  period: LeaderboardPeriod
+  limit: number
+}
+
+interface BackendRewardRecord {
+  id: string
+  name: string
+  description: string
+  reward_type: BackendRewardType
+  cost_points: number
+  reward_data?: unknown
+  stock_quantity?: number | null
+  max_per_user?: number
+  can_redeem?: boolean
+  user_points?: number
+  points_needed?: number
+  user_redemptions?: number
+  stock_remaining?: number | null
+  availability_status?: Reward['availability_status']
+}
+
+interface BackendAchievementRecord {
+  id: string
+  name: string
+  description: string
+  icon: string
+  rarity?: unknown
+  is_unlocked?: boolean
+  is_claimed?: boolean
+  can_claim?: boolean
+  unlocked_at?: string | null
+  claimed_at?: string | null
+  progress_percentage?: number
+  progress_current?: number
+  progress_target?: number
+  reward_data?: unknown
+  share_card?: AchievementShareCard
+}
+
+interface BackendQuestRecord {
+  id: string
+  name?: string
+  title?: string
+  description: string
+  quest_type?: string
+  type?: string
+  objectives: QuestObjective[]
+  rewards?: Quest['rewards']
+  reward_points: number
+  reward_data?: unknown
+  duration_hours?: number
+  max_completions?: number
+  status?: Quest['status']
+  is_active?: boolean
+  is_accepted?: boolean
+  starts_at?: string
+  ends_at?: string | null
+  expires_at?: string | null
+  completed_at?: string | null
+  accepted_at?: string | null
+  progress_percentage?: number
+  created_at?: string
+  updated_at?: string
+  progress?: Quest['progress']
+  category?: string
+}
+
+interface CompleteQuestResponsePayload {
+  quest_id: string
+  completed_at: string
+  points_awarded: number
+}
+
+interface AchievementUnlockedEvent {
+  achievement_id: string
+  unlocked_at: string
+  achievement?: {
+    id?: string
+    name?: string
+    description?: string
+    icon?: string
+    reward_points?: number
+  }
+  user_stats?: UserStats
+}
+
+interface QuestCompletedEvent {
+  quest_id: string
+  completed_at: string
+  user_stats?: UserStats
+}
+
+interface QuestAcceptedEvent {
+  userId: string
+  quest: {
+    id: string
+    name: string
+    description: string
+    quest_type: string
+    reward_points: number
+  }
+  message: string
+  timestamp: string
+}
+
+interface QuestProgressUpdatedEvent {
+  userId: string
+  questId: string
+  progress: Record<string, unknown>
+  timestamp: string
+}
+
+interface LevelUpEvent {
+  new_level: number
+  level_details: {
+    level_number: number
+    name: string
+    badge_color: string
+    badge_icon: string
+    benefits: string[]
+    min_points?: number
+  }
+  next_level_details: {
+    level_number: number
+    name: string
+    badge_color: string
+    badge_icon: string
+    benefits: string[]
+    min_points?: number
+  } | null
+}
+
+interface PointsAwardedEvent {
+  points: number
+  total_points?: number
+  lifetime_points?: number
+  level_progress?: number
+  points_this_week?: number
+  points_this_month?: number
+}
+
+interface RewardClaimedEvent {
+  reward_id?: string
+  reward?: Reward
+  claimed_reward?: ClaimedReward
+  user_stats?: UserStats
+}
+
+interface LeaderboardPositionChangedEvent {
+  userId: string
+  newRank: number
+  totalPoints: number
+  previousRank: number
+  rankImprovement: number
+  timestamp: string
+}
+
+type BackendRewardType = 'badge' | 'title' | 'cosmetic' | 'boost' | 'feature'
+
+const QUEST_FILTER_VALUES: readonly QuestFilter[] = ['active', 'daily', 'weekly', 'completed'] as const
+
+function isAxiosError(error: unknown): error is { response?: { status?: number; data?: { message?: string } } } {
+  return error !== null
+    && typeof error === 'object'
+    && 'response' in error
+}
+
+function isQuestFilter(value: string): value is QuestFilter {
+  return QUEST_FILTER_VALUES.includes(value as QuestFilter)
+}
+
+function createQuestCompletionIdempotencyKey(questId: string): string {
+  const randomPart = typeof globalThis.crypto?.randomUUID === 'function'
+    ? globalThis.crypto.randomUUID()
+    : Math.random().toString(36).slice(2)
+
+  return `quest-complete:${questId}:${randomPart}`
+}
+
+function isAchievementRarity(value: unknown): value is NonNullable<Achievement['rarity']> {
+  return value === 'common'
+    || value === 'uncommon'
+    || value === 'rare'
+    || value === 'epic'
+    || value === 'legendary'
+}
+
+function toRewardDataRecord(value: unknown): Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return {}
+  }
+
+  return value as Record<string, unknown>
+}
+
+function normalizeAchievementRewardData(value: unknown): Achievement['reward_data'] | undefined {
+  const rewardData = toRewardDataRecord(value)
+  const normalized: NonNullable<Achievement['reward_data']> = {}
+
+  if (typeof rewardData.badge_color === 'string') {
+    normalized.badge_color = rewardData.badge_color
+  }
+  if (typeof rewardData.badge_text === 'string') {
+    normalized.badge_text = rewardData.badge_text
+  }
+  if (Array.isArray(rewardData.special_privileges)) {
+    normalized.special_privileges = rewardData.special_privileges.filter(
+      (entry): entry is string => typeof entry === 'string'
+    )
+  }
+  if (typeof rewardData.unlocks_feature === 'string') {
+    normalized.unlocks_feature = rewardData.unlocks_feature
+  }
+
+  return Object.keys(normalized).length > 0 ? normalized : undefined
+}
+
+function resolveAchievementRarity(achievement: BackendAchievementRecord): NonNullable<Achievement['rarity']> {
+  if (isAchievementRarity(achievement.rarity)) {
+    return achievement.rarity
+  }
+
+  const rewardData = toRewardDataRecord(achievement.reward_data)
+  const badgeRarity = rewardData.badge_rarity
+  if (isAchievementRarity(badgeRarity)) {
+    return badgeRarity
+  }
+
+  return 'common'
+}
+
+function isBackendRewardType(value: unknown): value is BackendRewardType {
+  return value === 'badge'
+    || value === 'title'
+    || value === 'cosmetic'
+    || value === 'boost'
+    || value === 'feature'
+}
+
+function isBackendRewardRecord(value: unknown): value is BackendRewardRecord {
+  if (value === null || typeof value !== 'object') {
+    return false
+  }
+
+  const candidate = value as Record<string, unknown>
+
+  return typeof candidate.id === 'string'
+    && typeof candidate.name === 'string'
+    && typeof candidate.description === 'string'
+    && typeof candidate.cost_points === 'number'
+    && isBackendRewardType(candidate.reward_type)
+}
+
+function extractBackendRewardRecords(value: unknown): BackendRewardRecord[] {
+  if (value === null || typeof value !== 'object') {
+    return []
+  }
+
+  const payload = value as { data?: unknown }
+  if (!Array.isArray(payload.data)) {
+    return []
+  }
+
+  return payload.data.filter(isBackendRewardRecord)
+}
+
+function mapRewardType(rewardType: BackendRewardType): NonNullable<Reward['type']> {
+  switch (rewardType) {
+    case 'badge':
+      return 'item'
+    case 'cosmetic':
+      return 'cosmetic'
+    case 'boost':
+      return 'boost'
+    case 'title':
+    case 'feature':
+      return 'privilege'
+  }
+}
+
+function mapRewardCategory(rewardType: BackendRewardType): NonNullable<Reward['category']> {
+  switch (rewardType) {
+    case 'badge':
+      return 'badge'
+    case 'cosmetic':
+      return 'cosmetic'
+    case 'title':
+    case 'feature':
+      return 'privilege'
+    case 'boost':
+      return 'bonus'
+  }
+}
+
+function mapRewardIcon(rewardType: BackendRewardType, rewardData: Record<string, unknown>): string {
+  const preferredIcon = rewardData.badge_icon ?? rewardData.icon
+  if (typeof preferredIcon === 'string' && preferredIcon.length > 0) {
+    return preferredIcon
+  }
+
+  switch (rewardType) {
+    case 'badge':
+      return 'badge'
+    case 'cosmetic':
+      return 'palette'
+    case 'boost':
+      return 'flash'
+    case 'title':
+    case 'feature':
+      return 'settings'
+  }
+}
+
+function mapRewardPreviewImage(rewardData: Record<string, unknown>): string | undefined {
+  const previewUrl = rewardData.preview_url
+  if (typeof previewUrl === 'string' && previewUrl.length > 0) {
+    return previewUrl
+  }
+
+  return undefined
+}
+
+function isBackendAchievementRecord(value: unknown): value is BackendAchievementRecord {
+  if (value === null || typeof value !== 'object') {
+    return false
+  }
+
+  const candidate = value as Record<string, unknown>
+
+  return typeof candidate.id === 'string'
+    && typeof candidate.name === 'string'
+    && typeof candidate.description === 'string'
+    && typeof candidate.icon === 'string'
+}
+
+function isAchievementShareCard(value: unknown): value is AchievementShareCard {
+  if (value === null || typeof value !== 'object') {
+    return false
+  }
+
+  const candidate = value as Record<string, unknown>
+
+  return typeof candidate.title === 'string'
+    && typeof candidate.badge_label === 'string'
+    && typeof candidate.description === 'string'
+    && typeof candidate.image_url === 'string'
+    && typeof candidate.share_url === 'string'
+    && typeof candidate.share_text === 'string'
+}
+
+function toSameOriginRequestPath(sourceUrl: string): string {
+  if (sourceUrl.startsWith('/')) {
+    return sourceUrl
+  }
+
+  if (typeof window === 'undefined') {
+    return sourceUrl
+  }
+
+  try {
+    const parsedUrl = new URL(sourceUrl, window.location.origin)
+    const requestPath = `${parsedUrl.pathname}${parsedUrl.search}`
+    if (requestPath.startsWith('/api/')) {
+      return requestPath.slice(4)
+    }
+
+    return requestPath
+  } catch {
+    return sourceUrl
+  }
+}
+
+function normalizeAchievement(achievement: BackendAchievementRecord): Achievement {
+  const unlockedAt = achievement.unlocked_at ?? null
+  const claimedAt = achievement.claimed_at ?? unlockedAt
+  const isUnlocked = achievement.is_unlocked === true || unlockedAt !== null
+  const progressPercentage = typeof achievement.progress_percentage === 'number'
+    ? achievement.progress_percentage
+    : 0
+  const canClaim = achievement.can_claim === true || (!isUnlocked && progressPercentage >= 100)
+  const rarity = resolveAchievementRarity(achievement)
+  const rewardData = normalizeAchievementRewardData(achievement.reward_data)
+
+  const normalized: Achievement = {
+    id: achievement.id,
+    name: achievement.name,
+    description: achievement.description,
+    icon: achievement.icon,
+    rarity,
+    is_unlocked: isUnlocked,
+    is_claimed: achievement.is_claimed ?? isUnlocked,
+    can_claim: canClaim,
+    unlocked_at: unlockedAt,
+    claimed_at: claimedAt,
+  }
+
+  if (typeof achievement.progress_percentage === 'number') {
+    normalized.progress_percentage = achievement.progress_percentage
+  }
+  if (typeof achievement.progress_current === 'number') {
+    normalized.progress_current = achievement.progress_current
+  }
+  if (typeof achievement.progress_target === 'number') {
+    normalized.progress_target = achievement.progress_target
+  }
+  if (rewardData) {
+    normalized.reward_data = rewardData
+  }
+
+  if (isAchievementShareCard(achievement.share_card)) {
+    normalized.share_card = achievement.share_card
+  }
+
+  return normalized
+}
+
+function normalizeReward(reward: BackendRewardRecord): Reward {
+  const rewardData = toRewardDataRecord(reward.reward_data)
+  const maxPerUser = reward.max_per_user ?? 0
+  const userRedemptions = reward.user_redemptions ?? 0
+  const stockQuantity = reward.stock_quantity ?? null
+  const stockRemaining = reward.stock_remaining ?? null
+  const previewImage = mapRewardPreviewImage(rewardData)
+
+  const normalizedReward: Reward = {
+    id: reward.id,
+    name: reward.name,
+    description: reward.description,
+    cost_points: reward.cost_points,
+    reward_type: reward.reward_type,
+    type: mapRewardType(reward.reward_type),
+    category: mapRewardCategory(reward.reward_type),
+    icon: mapRewardIcon(reward.reward_type, rewardData),
+    reward_data: rewardData,
+    stock_quantity: stockQuantity,
+    stock_remaining: stockRemaining,
+    max_per_user: maxPerUser,
+    can_redeem: reward.can_redeem ?? false,
+    user_points: reward.user_points ?? 0,
+    points_needed: reward.points_needed ?? 0,
+    user_redemptions: userRedemptions,
+    availability_status: reward.availability_status ?? 'available',
+    limited_quantity: stockQuantity,
+    remaining_quantity: stockRemaining,
+    is_available: reward.can_redeem ?? false,
+    is_claimed: maxPerUser > 0 && userRedemptions >= maxPerUser,
+  }
+
+  if (previewImage !== undefined) {
+    normalizedReward.preview_image = previewImage
+  }
+
+  return normalizedReward
+}
+
+function normalizeQuest(raw: BackendQuestRecord): Quest {
+  const questType = (raw.quest_type ?? raw.type ?? 'daily') as Quest['type']
+  const title = raw.title ?? raw.name ?? 'Untitled Quest'
+
+  let acceptedAt = raw.accepted_at ?? null
+  if (acceptedAt === null && raw.is_accepted === true) {
+    acceptedAt = new Date().toISOString()
+  }
+
+  const quest: Quest = {
+    id: raw.id,
+    title,
+    description: raw.description,
+    type: questType,
+    objectives: raw.objectives,
+    reward_points: raw.reward_points,
+    expires_at: raw.expires_at ?? null,
+    completed_at: raw.completed_at ?? null,
+    accepted_at: acceptedAt,
+  }
+
+  if (raw.name !== undefined) {
+    quest.name = raw.name
+  }
+  if (raw.rewards !== undefined) {
+    quest.rewards = raw.rewards
+  }
+  if (raw.status !== undefined) {
+    quest.status = raw.status
+  }
+  if (raw.is_active !== undefined) {
+    quest.is_active = raw.is_active
+  }
+  if (raw.starts_at !== undefined) {
+    quest.starts_at = raw.starts_at
+  }
+  if (raw.progress !== undefined) {
+    quest.progress = raw.progress
+  }
+  if (raw.progress_percentage !== undefined) {
+    quest.progress_percentage = raw.progress_percentage
+  }
+  if (raw.category !== undefined) {
+    quest.category = raw.category
+  }
+
+  return quest
+}
+
+export type GamificationStoreReturn = ReturnType<ReturnType<typeof createGamificationStoreDefinition>>
+
+export function createGamificationStoreDefinition(config: GamificationStoreConfig) {
+  const {
+    client,
+    getCurrentUser,
+    getEcho,
+    onConnectionStatusChange,
+    logger = console,
+    debug = false,
+    storeId = 'gamification',
+  } = config
+
+  const debugLog = (message: string, ...args: unknown[]): void => {
+    if (!debug) {
+      return
+    }
+
+    logger.debug(message, ...args)
+  }
+
+  return defineStore(storeId, () => {
+    const achievements = ref<Achievement[]>([])
+    const quests = ref<Quest[]>([])
+    const dailyQuests = ref<Quest[]>([])
+    const completedQuestsData = ref<Quest[]>([])
+    const questFilter = ref<QuestFilter>('active')
+    const rewards = ref<Reward[]>([])
+    const claimedRewards = ref<ClaimedReward[]>([])
+    const rewardTransactions = ref<RewardTransaction[]>([])
+    const leaderboard = ref<LeaderboardEntry[]>([])
+    const activeLeaderboardContext = ref<LeaderboardQueryContext>({
+      period: 'all-time',
+      limit: 50,
+    })
+    const userStats = ref<UserStats | null>(null)
+    const lastAchievementUnlockedEvent = ref<AchievementUnlockNotification | null>(null)
+
+    const loadingAchievements = ref(false)
+    const loadingQuests = ref(false)
+    const loadingRewards = ref(false)
+    const loadingLeaderboard = ref(false)
+    const loadingStats = ref(false)
+    const claiming = ref(false)
+
+    const lastAchievementsUpdate = ref<Date | null>(null)
+    const lastQuestsUpdate = ref<Date | null>(null)
+    const lastRewardsUpdate = ref<Date | null>(null)
+    const lastLeaderboardUpdate = ref<Date | null>(null)
+    const lastStatsUpdate = ref<Date | null>(null)
+
+    const ACHIEVEMENTS_CACHE_TTL = 5 * 60 * 1000
+    const QUESTS_CACHE_TTL = 2 * 60 * 1000
+    const REWARDS_CACHE_TTL = 10 * 60 * 1000
+    const LEADERBOARD_CACHE_TTL = 5 * 60 * 1000
+    const STATS_CACHE_TTL = 2 * 60 * 1000
+
+    const isAchievementsStale = computed(() => {
+      if (!lastAchievementsUpdate.value) {
+        return true
+      }
+      return Date.now() - lastAchievementsUpdate.value.getTime() > ACHIEVEMENTS_CACHE_TTL
+    })
+
+    const isQuestsStale = computed(() => {
+      if (!lastQuestsUpdate.value) {
+        return true
+      }
+      return Date.now() - lastQuestsUpdate.value.getTime() > QUESTS_CACHE_TTL
+    })
+
+    const isRewardsStale = computed(() => {
+      if (!lastRewardsUpdate.value) {
+        return true
+      }
+      return Date.now() - lastRewardsUpdate.value.getTime() > REWARDS_CACHE_TTL
+    })
+
+    const isLeaderboardStale = computed(() => {
+      if (!lastLeaderboardUpdate.value) {
+        return true
+      }
+      return Date.now() - lastLeaderboardUpdate.value.getTime() > LEADERBOARD_CACHE_TTL
+    })
+
+    const isStatsStale = computed(() => {
+      if (!lastStatsUpdate.value) {
+        return true
+      }
+      return Date.now() - lastStatsUpdate.value.getTime() > STATS_CACHE_TTL
+    })
+
+    const unlockedAchievements = computed(() => (
+      achievements.value.filter((achievement) => achievement.unlocked_at !== null && achievement.unlocked_at !== undefined)
+    ))
+
+    const availableAchievements = computed(() => (
+      achievements.value.filter((achievement) => (
+        (achievement.unlocked_at === null || achievement.unlocked_at === undefined) && achievement.is_visible
+      ))
+    ))
+
+    const activeQuests = computed(() => quests.value.filter((quest) => !quest.completed_at && quest.accepted_at))
+    const completedQuests = computed(() => completedQuestsData.value)
+    const rewardBalance = computed(() => userStats.value?.total_points || 0)
+    const currentXP = computed(() => userStats.value?.lifetime_points || 0)
+    const currentLevel = computed(() => userStats.value?.current_level || 1)
+    const nextLevel = computed(() => userStats.value?.next_level)
+    const levelProgress = computed(() => userStats.value?.level_progress || 0)
+    const recentXPGain = computed(() => userStats.value?.points_this_week || 0)
+
+    function setQuestFilter(nextFilter: string): void {
+      if (!isQuestFilter(nextFilter)) {
+        return
+      }
+
+      questFilter.value = nextFilter
+    }
+
+    async function loadAchievements(useCache = true): Promise<Achievement[]> {
+      if (loadingAchievements.value) {
+        return achievements.value
+      }
+
+      if (useCache && !isAchievementsStale.value && achievements.value.length > 0) {
+        return achievements.value
+      }
+
+      loadingAchievements.value = true
+
+      try {
+        const response = await client.get('/v1/gamification/achievements')
+        const responseData = response.data as { data?: unknown }
+        const records = Array.isArray(responseData.data)
+          ? responseData.data.filter(isBackendAchievementRecord)
+          : []
+        achievements.value = records.map(normalizeAchievement)
+        lastAchievementsUpdate.value = new Date()
+        return achievements.value
+      } catch (error) {
+        logger.error('Failed to load achievements:', error)
+
+        if (isAxiosError(error) && error.response?.status === 404) {
+          achievements.value = []
+          return achievements.value
+        }
+
+        throw error
+      } finally {
+        loadingAchievements.value = false
+      }
+    }
+
+    async function loadQuests(useCache = true): Promise<Quest[]> {
+      if (loadingQuests.value) {
+        return quests.value
+      }
+
+      if (useCache && !isQuestsStale.value && quests.value.length > 0) {
+        return quests.value
+      }
+
+      loadingQuests.value = true
+
+      try {
+        const [availableResponse, myQuestsResponse] = await Promise.all([
+          client.get('/v1/gamification/quests/available'),
+          client.get('/v1/gamification/quests/my-quests'),
+        ])
+
+        const availableRaw = (availableResponse.data as { data?: unknown }).data ?? []
+        const myQuestsRaw = (myQuestsResponse.data as { data?: unknown }).data ?? []
+
+        const normalizedAvailable = Array.isArray(availableRaw)
+          ? availableRaw.map((quest) => normalizeQuest(quest as BackendQuestRecord))
+          : []
+        const normalizedMyQuests = Array.isArray(myQuestsRaw)
+          ? myQuestsRaw.map((quest) => normalizeQuest(quest as BackendQuestRecord))
+          : []
+
+        const myQuestIds = new Set(normalizedMyQuests.map((quest) => quest.id))
+        quests.value = [
+          ...normalizedMyQuests,
+          ...normalizedAvailable.filter((quest) => !myQuestIds.has(quest.id)),
+        ]
+        dailyQuests.value = quests.value.filter((quest) => quest.type === 'daily')
+
+        lastQuestsUpdate.value = new Date()
+        return quests.value
+      } catch (error) {
+        logger.error('Failed to load quests:', error)
+
+        if (isAxiosError(error) && error.response?.status === 404) {
+          quests.value = []
+          dailyQuests.value = []
+          return quests.value
+        }
+
+        throw error
+      } finally {
+        loadingQuests.value = false
+      }
+    }
+
+    async function loadCompletedQuests(useCache = true): Promise<Quest[]> {
+      if (loadingQuests.value) {
+        return completedQuestsData.value
+      }
+
+      if (useCache && completedQuestsData.value.length > 0) {
+        return completedQuestsData.value
+      }
+
+      loadingQuests.value = true
+
+      try {
+        const response = await client.get('/v1/gamification/quests/completed')
+        const completedRaw = ((response.data as { data?: unknown }).data ?? []) as BackendQuestRecord[]
+        completedQuestsData.value = completedRaw.map(normalizeQuest)
+        return completedQuestsData.value
+      } catch (error) {
+        logger.error('Failed to load completed quests:', error)
+
+        if (isAxiosError(error) && error.response?.status === 404) {
+          completedQuestsData.value = []
+          return completedQuestsData.value
+        }
+
+        throw error
+      } finally {
+        loadingQuests.value = false
+      }
+    }
+
+    async function loadRewards(useCache = true): Promise<Reward[]> {
+      if (loadingRewards.value) {
+        return rewards.value
+      }
+
+      if (useCache && !isRewardsStale.value && rewards.value.length > 0) {
+        return rewards.value
+      }
+
+      loadingRewards.value = true
+
+      try {
+        const response = await client.get('/v1/gamification/rewards')
+        const rewardRecords = extractBackendRewardRecords(response.data)
+        rewards.value = rewardRecords.map(normalizeReward)
+        lastRewardsUpdate.value = new Date()
+        return rewards.value
+      } catch (error) {
+        logger.error('Failed to load rewards:', error)
+        throw error
+      } finally {
+        loadingRewards.value = false
+      }
+    }
+
+    async function loadLeaderboard(period: LeaderboardPeriod = 'all-time', limit = 50): Promise<LeaderboardEntry[]> {
+      loadingLeaderboard.value = true
+
+      try {
+        activeLeaderboardContext.value = { period, limit }
+        const response = await client.get('/v1/gamification/leaderboard', {
+          params: { period, limit },
+        })
+        const responseData = response.data as { data?: LeaderboardEntry[] }
+        leaderboard.value = responseData.data ?? []
+        lastLeaderboardUpdate.value = new Date()
+        return leaderboard.value
+      } catch (error) {
+        logger.error('Failed to load leaderboard:', error)
+        throw error
+      } finally {
+        loadingLeaderboard.value = false
+      }
+    }
+
+    async function loadUserStats(useCache = true): Promise<UserStats> {
+      if (loadingStats.value) {
+        if (userStats.value) {
+          return userStats.value
+        }
+
+        return new Promise((resolve, reject) => {
+          const checkInterval = setInterval(() => {
+            if (!loadingStats.value) {
+              clearInterval(checkInterval)
+              if (userStats.value) {
+                resolve(userStats.value)
+              } else {
+                reject(new Error('Failed to load user stats'))
+              }
+            }
+          }, 100)
+
+          setTimeout(() => {
+            clearInterval(checkInterval)
+            reject(new Error('Timeout loading user stats'))
+          }, 10000)
+        })
+      }
+
+      if (useCache && !isStatsStale.value && userStats.value) {
+        return userStats.value
+      }
+
+      loadingStats.value = true
+
+      try {
+        const response = await client.get('/v1/gamification/users/me/reputation')
+        const responseData = response.data as { data?: UserStats }
+        if (!responseData.data) {
+          throw new Error('Failed to load user stats')
+        }
+        userStats.value = responseData.data
+        lastStatsUpdate.value = new Date()
+        return userStats.value
+      } catch (error) {
+        logger.error('Failed to load user stats:', error)
+
+        if (isAxiosError(error) && error.response?.status === 404) {
+          const defaultStats = {
+            id: 'guest',
+            user_id: 'guest',
+            total_points: 0,
+            coin_balance: 0,
+            lifetime_points: 0,
+            current_level: 1,
+            points_this_week: 0,
+            points_this_month: 0,
+            points_this_year: 0,
+            level_progress: 0,
+            points_to_next_level: 100,
+            level: {
+              level_number: 1,
+              name: 'Beginner',
+              badge_color: 'gray',
+              badge_icon: 'star',
+              benefits: [],
+            },
+            next_level: null,
+            privileges: [],
+            stats: {},
+          } as unknown as UserStats
+
+          userStats.value = defaultStats
+          return defaultStats
+        }
+
+        throw error
+      } finally {
+        loadingStats.value = false
+      }
+    }
+
+    async function loadAchievementById(achievementId: string): Promise<Achievement> {
+      const response = await client.get(`/v1/gamification/achievements/${achievementId}`)
+      const payload = response.data as { data?: unknown }
+
+      if (!isBackendAchievementRecord(payload.data)) {
+        throw new Error('Failed to load achievement details')
+      }
+
+      const normalized = normalizeAchievement(payload.data)
+      const existingIndex = achievements.value.findIndex((achievement) => achievement.id === achievementId)
+      if (existingIndex >= 0) {
+        achievements.value[existingIndex] = normalized
+      } else {
+        achievements.value.unshift(normalized)
+      }
+
+      return normalized
+    }
+
+    async function getAchievementShareCard(achievementId: string): Promise<AchievementShareCard> {
+      const existing = achievements.value.find((achievement) => achievement.id === achievementId)
+      if (existing?.share_card) {
+        return existing.share_card
+      }
+
+      const refreshedAchievement = await loadAchievementById(achievementId)
+      if (!refreshedAchievement.share_card) {
+        throw new Error('Share card metadata is unavailable')
+      }
+
+      return refreshedAchievement.share_card
+    }
+
+    async function fetchAchievementShareCardAsset(achievementId: string): Promise<string> {
+      const shareCard = await getAchievementShareCard(achievementId)
+      const shareCardAssetPath = toSameOriginRequestPath(shareCard.image_url)
+      const response = await client.get<string>(shareCardAssetPath, { responseType: 'text' })
+
+      if (typeof response.data !== 'string' || !response.data.includes('<svg')) {
+        throw new Error('Share card image could not be generated')
+      }
+
+      return response.data
+    }
+
+    async function claimAchievement(achievementId: string): Promise<void> {
+      if (claiming.value) {
+        return
+      }
+
+      claiming.value = true
+
+      try {
+        const response = await client.post(`/v1/gamification/achievements/${achievementId}/claim`)
+        const payload = response.data as {
+          data?: {
+            unlocked_at?: string
+            achievement?: BackendAchievementRecord
+            user_stats?: UserStats
+          }
+          meta?: {
+            new_total_points?: number
+          }
+        }
+
+        const achievement = achievements.value.find((entry) => entry.id === achievementId)
+        if (achievement) {
+          const unlockedAt = payload.data?.unlocked_at
+
+          if (payload.data?.achievement && isBackendAchievementRecord(payload.data.achievement)) {
+            const normalized = normalizeAchievement({
+              ...payload.data.achievement,
+              unlocked_at: payload.data.achievement.unlocked_at ?? unlockedAt ?? null,
+              claimed_at: payload.data.achievement.claimed_at ?? unlockedAt ?? null,
+              is_unlocked: true,
+              is_claimed: true,
+              can_claim: false,
+            })
+            Object.assign(achievement, normalized)
+          } else {
+            const claimedTimestamp = unlockedAt ?? new Date().toISOString()
+            achievement.is_unlocked = true
+            achievement.is_claimed = true
+            achievement.can_claim = false
+            achievement.unlocked_at = claimedTimestamp
+            achievement.claimed_at = claimedTimestamp
+            achievement.progress_percentage = 100
+          }
+        }
+
+        if (payload.data?.user_stats) {
+          userStats.value = payload.data.user_stats
+        } else if (typeof payload.meta?.new_total_points === 'number' && userStats.value) {
+          userStats.value.total_points = payload.meta.new_total_points
+        }
+      } catch (error) {
+        logger.error('Failed to claim achievement:', error)
+        throw error
+      } finally {
+        claiming.value = false
+      }
+    }
+
+    async function acceptQuest(questId: string): Promise<void> {
+      try {
+        const response = await client.post(`/v1/gamification/quests/${questId}/accept`)
+        const normalized = normalizeQuest((response.data as { data: BackendQuestRecord }).data)
+        const index = quests.value.findIndex((quest) => quest.id === questId)
+        if (index !== -1) {
+          quests.value.splice(index, 1, normalized)
+        }
+      } catch (error) {
+        logger.error('Failed to accept quest:', error)
+        throw error
+      }
+    }
+
+    async function completeQuest(questId: string): Promise<void> {
+      try {
+        const quest = quests.value.find((item) => item.id === questId)
+        const idempotencyKey = createQuestCompletionIdempotencyKey(questId)
+
+        const progressData = quest?.objectives.map((objective) => ({
+          current: objective.current_value ?? objective.current,
+          completed: objective.completed ?? objective.is_completed ?? false,
+        }))
+
+        const requestPayload = progressData !== undefined && progressData.length > 0
+          ? { progress_data: progressData }
+          : {}
+
+        const response = await client.post(
+          `/v1/gamification/quests/${questId}/complete`,
+          requestPayload,
+          {
+            headers: {
+              'Idempotency-Key': idempotencyKey,
+            },
+          },
+        )
+        const payload = (response.data as { data: CompleteQuestResponsePayload }).data
+
+        const index = quests.value.findIndex((item) => item.id === questId)
+        if (index !== -1 && quest) {
+          const updated: Quest = {
+            ...quest,
+            completed_at: payload.completed_at,
+            progress_percentage: 100,
+            objectives: quest.objectives.map((objective) => ({
+              ...objective,
+              completed: true,
+            })),
+          }
+          quests.value.splice(index, 1, updated)
+        }
+      } catch (error) {
+        logger.error('Failed to complete quest:', error)
+        throw error
+      }
+    }
+
+    async function abandonQuest(questId: string): Promise<void> {
+      try {
+        await client.delete(`/v1/gamification/quests/${questId}/abandon`)
+        await loadQuests(false)
+      } catch (error) {
+        logger.error('Failed to abandon quest:', error)
+        throw error
+      }
+    }
+
+    async function redeemReward(rewardId: string): Promise<void> {
+      if (claiming.value) {
+        return
+      }
+
+      claiming.value = true
+
+      try {
+        const response = await client.post(`/v1/gamification/rewards/${rewardId}/redeem`)
+        const responseData = response.data as {
+          data?: {
+            reward?: Reward
+            claimed_reward?: ClaimedReward
+            user_stats?: UserStats
+          }
+        }
+
+        const reward = rewards.value.find((entry) => entry.id === rewardId)
+        if (reward && responseData.data?.reward) {
+          Object.assign(reward, responseData.data.reward)
+        }
+
+        if (responseData.data?.claimed_reward) {
+          claimedRewards.value.unshift(responseData.data.claimed_reward)
+        }
+
+        if (responseData.data?.user_stats) {
+          userStats.value = responseData.data.user_stats
+        }
+      } catch (error) {
+        logger.error('Failed to redeem reward:', error)
+        throw error
+      } finally {
+        claiming.value = false
+      }
+    }
+
+    let subscribedGamificationChannel: string | null = null
+    let subscribedLeaderboardChannel: string | null = null
+    let shouldMaintainRealtimeSubscription = false
+
+    function subscribeToGamificationUpdates(): void {
+      const currentUser = getCurrentUser()
+      if (!currentUser?.id) {
+        return
+      }
+
+      shouldMaintainRealtimeSubscription = true
+      const channelName = `gamification.${currentUser.id}`
+
+      const echo = getEcho()
+      if (!echo) {
+        debugLog(`Gamification: Echo unavailable; waiting to subscribe to ${channelName}`)
+        return
+      }
+
+      const tenantScopeValue = currentUser.tenant_id ?? currentUser.tenantId
+      const tenantScope = typeof tenantScopeValue === 'string' && tenantScopeValue.length > 0
+        ? tenantScopeValue
+        : 'global'
+      const leaderboardChannelName = `leaderboard.${tenantScope}`
+
+      if (
+        subscribedGamificationChannel === channelName
+        && subscribedLeaderboardChannel === leaderboardChannelName
+      ) {
+        return
+      }
+
+      if (subscribedGamificationChannel && subscribedGamificationChannel !== channelName) {
+        const staleChannel = echo.private(subscribedGamificationChannel)
+        staleChannel.stopListening('.achievement.unlocked')
+        staleChannel.stopListening('.quest.completed')
+        staleChannel.stopListening('.quest.accepted')
+        staleChannel.stopListening('.quest.progress-updated')
+        staleChannel.stopListening('.level.up')
+        staleChannel.stopListening('.points.awarded')
+        staleChannel.stopListening('.reward.redeemed')
+      }
+
+      if (subscribedLeaderboardChannel) {
+        echo.leave(subscribedLeaderboardChannel)
+      }
+
+      debugLog(`Gamification: Subscribing to ${channelName}`)
+
+      const privateChannel = echo.private(channelName)
+      privateChannel.listen('.achievement.unlocked', (event) => {
+        handleAchievementUnlocked(event as AchievementUnlockedEvent)
+      })
+      privateChannel.listen('.quest.completed', (event) => {
+        handleQuestCompleted(event as QuestCompletedEvent)
+      })
+      privateChannel.listen('.quest.accepted', (event) => {
+        handleQuestAccepted(event as QuestAcceptedEvent)
+      })
+      privateChannel.listen('.quest.progress-updated', (event) => {
+        handleQuestProgressUpdated(event as QuestProgressUpdatedEvent)
+      })
+      privateChannel.listen('.level.up', (event) => {
+        handleLevelUp(event as LevelUpEvent)
+      })
+      privateChannel.listen('.points.awarded', (event) => {
+        handlePointsAwarded(event as PointsAwardedEvent)
+      })
+      privateChannel.listen('.reward.redeemed', (event) => {
+        handleRewardClaimed(event as RewardClaimedEvent)
+      })
+      subscribedGamificationChannel = channelName
+
+      const leaderboardChannel = echo.private(leaderboardChannelName)
+      leaderboardChannel.listen('.leaderboard.position-changed', (event) => {
+        handleLeaderboardUpdated(event as LeaderboardPositionChangedEvent)
+      })
+      subscribedLeaderboardChannel = leaderboardChannelName
+    }
+
+    function unsubscribeFromGamificationUpdates(): void {
+      shouldMaintainRealtimeSubscription = false
+
+      if (!subscribedGamificationChannel && !subscribedLeaderboardChannel) {
+        return
+      }
+
+      const echo = getEcho()
+      if (echo) {
+        debugLog('Gamification: Unsubscribing from all channels')
+
+        if (subscribedGamificationChannel) {
+          const channel = echo.private(subscribedGamificationChannel)
+          channel.stopListening('.achievement.unlocked')
+          channel.stopListening('.quest.completed')
+          channel.stopListening('.quest.accepted')
+          channel.stopListening('.quest.progress-updated')
+          channel.stopListening('.level.up')
+          channel.stopListening('.points.awarded')
+          channel.stopListening('.reward.redeemed')
+        }
+
+        if (subscribedLeaderboardChannel) {
+          echo.leave(subscribedLeaderboardChannel)
+        }
+      }
+
+      subscribedGamificationChannel = null
+      subscribedLeaderboardChannel = null
+    }
+
+    const stopListeningToConnectionStatus = onConnectionStatusChange((status) => {
+      if (status !== 'connected') {
+        return
+      }
+
+      if (!shouldMaintainRealtimeSubscription) {
+        return
+      }
+
+      subscribedGamificationChannel = null
+      subscribedLeaderboardChannel = null
+      subscribeToGamificationUpdates()
+    })
+
+    if (typeof stopListeningToConnectionStatus === 'function') {
+      onScopeDispose(() => {
+        stopListeningToConnectionStatus()
+      })
+    }
+
+    function handleAchievementUnlocked(event: AchievementUnlockedEvent): void {
+      debugLog('Gamification: Achievement unlocked event', event)
+
+      const achievement = achievements.value.find((entry) => entry.id === event.achievement_id)
+      if (achievement) {
+        achievement.unlocked_at = event.unlocked_at
+        delete achievement.progress
+      }
+
+      if (event.user_stats) {
+        userStats.value = event.user_stats
+      }
+
+      const payload = event.achievement
+      const title = typeof payload?.name === 'string' && payload.name.length > 0
+        ? payload.name
+        : achievement?.name ?? 'Achievement Unlocked'
+      const description = typeof payload?.description === 'string' && payload.description.length > 0
+        ? payload.description
+        : achievement?.description ?? 'You unlocked a new achievement.'
+      const icon = typeof payload?.icon === 'string' && payload.icon.length > 0
+        ? payload.icon
+        : achievement?.icon ?? 'trophy'
+
+      const notification: AchievementUnlockNotification = {
+        achievementId: event.achievement_id,
+        title,
+        description,
+        icon,
+        unlockedAt: event.unlocked_at,
+      }
+
+      if (typeof payload?.reward_points === 'number') {
+        notification.points = payload.reward_points
+      } else if (typeof achievement?.reward_points === 'number') {
+        notification.points = achievement.reward_points
+      } else if (typeof achievement?.points_awarded === 'number') {
+        notification.points = achievement.points_awarded
+      }
+
+      lastAchievementUnlockedEvent.value = notification
+    }
+
+    function clearLastAchievementUnlockedEvent(): void {
+      lastAchievementUnlockedEvent.value = null
+    }
+
+    function handleQuestCompleted(event: QuestCompletedEvent): void {
+      debugLog('Gamification: Quest completed event', event)
+
+      const quest = quests.value.find((entry) => entry.id === event.quest_id)
+      if (quest) {
+        quest.completed_at = event.completed_at
+        quest.progress_percentage = 100
+      }
+
+      if (event.user_stats) {
+        userStats.value = event.user_stats
+      }
+    }
+
+    function handleQuestAccepted(event: QuestAcceptedEvent): void {
+      debugLog('Gamification: Quest accepted event', event)
+
+      const quest = quests.value.find((entry) => entry.id === event.quest.id)
+      if (quest) {
+        quest.accepted_at = event.timestamp
+      }
+    }
+
+    function handleQuestProgressUpdated(event: QuestProgressUpdatedEvent): void {
+      debugLog('Gamification: Quest progress updated event', event)
+
+      const quest = quests.value.find((entry) => entry.id === event.questId)
+      if (quest && event.progress) {
+        const progressPct = event.progress.percentage
+        if (typeof progressPct === 'number') {
+          quest.progress_percentage = progressPct
+        }
+      }
+    }
+
+    function handleLevelUp(event: LevelUpEvent): void {
+      debugLog('Gamification: Level up event', event)
+
+      if (userStats.value) {
+        userStats.value.current_level = event.new_level
+        userStats.value.level_progress = 0
+      }
+    }
+
+    function handlePointsAwarded(event: PointsAwardedEvent): void {
+      debugLog('Gamification: Points awarded event', event)
+
+      if (userStats.value) {
+        if (event.lifetime_points !== undefined) {
+          userStats.value.lifetime_points = event.lifetime_points
+        } else {
+          userStats.value.lifetime_points += event.points
+        }
+
+        userStats.value.level_progress = event.level_progress ?? userStats.value.level_progress
+
+        if (event.points_this_week !== undefined) {
+          userStats.value.points_this_week = event.points_this_week
+        }
+        if (event.points_this_month !== undefined) {
+          userStats.value.points_this_month = event.points_this_month
+        }
+      }
+
+      const currentUserId = getCurrentUser()?.id
+      if (currentUserId && leaderboard.value.length > 0) {
+        const entryIndex = leaderboard.value.findIndex((entry) => entry.user_id === currentUserId)
+        if (entryIndex !== -1) {
+          const entry = leaderboard.value[entryIndex]
+          if (entry) {
+            if (event.total_points !== undefined) {
+              entry.total_points = event.total_points
+            } else {
+              entry.total_points += event.points
+            }
+            lastLeaderboardUpdate.value = new Date()
+          }
+        }
+      }
+    }
+
+    function handleRewardClaimed(event: RewardClaimedEvent): void {
+      debugLog('Gamification: Reward claimed event', event)
+
+      if (event.reward_id && event.reward) {
+        const reward = rewards.value.find((entry) => entry.id === event.reward_id)
+        if (reward) {
+          Object.assign(reward, event.reward)
+        }
+      }
+
+      if (event.claimed_reward) {
+        claimedRewards.value.unshift(event.claimed_reward)
+      }
+
+      if (event.user_stats) {
+        userStats.value = event.user_stats
+      }
+    }
+
+    function handleLeaderboardUpdated(event: LeaderboardPositionChangedEvent): void {
+      debugLog('Gamification: Leaderboard position changed event', event)
+
+      if (activeLeaderboardContext.value.period !== 'all-time') {
+        const { period, limit } = activeLeaderboardContext.value
+        void loadLeaderboard(period, limit).catch((error: unknown) => {
+          logger.error('Failed to refresh period leaderboard after realtime update:', error)
+        })
+        return
+      }
+
+      const existingIndex = leaderboard.value.findIndex((entry) => entry.user_id === event.userId)
+
+      if (existingIndex !== -1) {
+        const entry = leaderboard.value[existingIndex]
+        if (entry) {
+          entry.rank = event.newRank
+          entry.total_points = event.totalPoints
+        }
+      }
+
+      leaderboard.value.sort((left, right) => {
+        if (right.total_points !== left.total_points) {
+          return right.total_points - left.total_points
+        }
+
+        if (left.rank !== right.rank) {
+          return left.rank - right.rank
+        }
+
+        return left.user_id.localeCompare(right.user_id)
+      })
+      leaderboard.value.forEach((entry, index) => {
+        entry.rank = index + 1
+      })
+      lastLeaderboardUpdate.value = new Date()
+    }
+
+    async function loadAllData(): Promise<void> {
+      try {
+        await Promise.all([
+          loadUserStats(),
+          loadAchievements(),
+          loadQuests(),
+          loadRewards(),
+          loadLeaderboard(),
+        ])
+      } catch (error) {
+        logger.error('Failed to load gamification data:', error)
+        throw error
+      }
+    }
+
+    function $reset(): void {
+      achievements.value = []
+      quests.value = []
+      dailyQuests.value = []
+      questFilter.value = 'active'
+      rewards.value = []
+      claimedRewards.value = []
+      rewardTransactions.value = []
+      leaderboard.value = []
+      activeLeaderboardContext.value = {
+        period: 'all-time',
+        limit: 50,
+      }
+      userStats.value = null
+      lastAchievementUnlockedEvent.value = null
+
+      loadingAchievements.value = false
+      loadingQuests.value = false
+      loadingRewards.value = false
+      loadingLeaderboard.value = false
+      loadingStats.value = false
+      claiming.value = false
+
+      lastAchievementsUpdate.value = null
+      lastQuestsUpdate.value = null
+      lastRewardsUpdate.value = null
+      lastLeaderboardUpdate.value = null
+      lastStatsUpdate.value = null
+    }
+
+    return {
+      achievements,
+      quests,
+      dailyQuests,
+      questFilter,
+      rewards,
+      claimedRewards,
+      rewardTransactions,
+      leaderboard,
+      activeLeaderboardContext,
+      userStats,
+      lastAchievementUnlockedEvent,
+
+      loadingAchievements,
+      loadingQuests,
+      loadingRewards,
+      loadingLeaderboard,
+      loadingStats,
+      claiming,
+
+      lastAchievementsUpdate,
+      lastQuestsUpdate,
+      lastRewardsUpdate,
+      lastLeaderboardUpdate,
+      lastStatsUpdate,
+
+      isAchievementsStale,
+      isQuestsStale,
+      isRewardsStale,
+      isLeaderboardStale,
+      isStatsStale,
+      unlockedAchievements,
+      availableAchievements,
+      activeQuests,
+      completedQuests,
+      rewardBalance,
+      currentXP,
+      currentLevel,
+      nextLevel,
+      levelProgress,
+      recentXPGain,
+
+      loadAchievements,
+      loadQuests,
+      loadCompletedQuests,
+      loadRewards,
+      loadLeaderboard,
+      loadUserStats,
+      loadAchievementById,
+      setQuestFilter,
+      getAchievementShareCard,
+      fetchAchievementShareCardAsset,
+      claimAchievement,
+      acceptQuest,
+      completeQuest,
+      abandonQuest,
+      redeemReward,
+      subscribeToGamificationUpdates,
+      unsubscribeFromGamificationUpdates,
+      clearLastAchievementUnlockedEvent,
+      loadAllData,
+      $reset,
+    }
+  })
+}