@codingfactory/socialkit-vue 0.6.0 → 0.7.0

package/src/services/gamification.ts

@@ -0,0 +1,432 @@
+/**
+ * Configurable gamification service for SocialKit-powered frontends.
+ */
+
+import type { ApiService } from './api.js'
+import type {
+  Achievement,
+  GamificationNotification,
+  LeaderboardEntry,
+  PointTransaction,
+  Quest,
+  Reward,
+  UserStats,
+} from '../types/gamification.js'
+import type {
+  ReputationPrivilege,
+  ReputationSnapshot,
+  UserStreakStatus,
+} from '../types/reputation.js'
+
+type LeaderboardPeriodInput = 'daily' | 'weekly' | 'monthly' | 'all-time' | 'all_time'
+
+interface CursorCollectionResponse<TItem> {
+  data: TItem[]
+  next_cursor?: string
+}
+
+interface QuestCompletionResponse {
+  quest_id: string
+  completed_at: string
+  points_awarded: number
+}
+
+export interface GamificationWebSocketMessageEventLike {
+  data: unknown
+}
+
+export interface GamificationWebSocketLike {
+  readonly OPEN: number
+  readyState: number
+  onopen: ((event: unknown) => void) | null
+  onmessage: ((event: GamificationWebSocketMessageEventLike) => void) | null
+  onclose: ((event: unknown) => void) | null
+  onerror: ((event: unknown) => void) | null
+  close(): void
+}
+
+export type GamificationWebSocketFactory = (url: string) => GamificationWebSocketLike
+
+export interface GamificationServiceLogger {
+  debug: (...args: unknown[]) => void
+  error: (...args: unknown[]) => void
+}
+
+export interface GamificationServiceConfig {
+  client: ApiService
+  webSocketUrl?: string | null
+  webSocketFactory?: GamificationWebSocketFactory
+  reconnectIntervalMs?: number
+  logger?: GamificationServiceLogger
+  debug?: boolean
+}
+
+export interface GamificationServiceInstance {
+  getUserStats(userId?: string): Promise<UserStats>
+  getUserReputation(userId?: string): Promise<UserStats>
+  getUserStreak(): Promise<UserStreakStatus>
+  getTransactions(options?: { limit?: number; offset?: number }): Promise<PointTransaction[]>
+  getReputationSnapshots(options?: { period?: 'week' | 'month' | 'year' }): Promise<ReputationSnapshot[]>
+  getPrivilegesCatalog(): Promise<ReputationPrivilege[]>
+  getAchievements(options?: { status?: 'locked' | 'unlocked' | 'all'; page?: number }): Promise<CursorCollectionResponse<Achievement>>
+  claimAchievement(achievementId: string): Promise<Achievement>
+  getQuests(options?: { status?: 'available' | 'in_progress' | 'completed' | 'all'; page?: number }): Promise<CursorCollectionResponse<Quest>>
+  claimQuestReward(questId: string): Promise<QuestCompletionResponse>
+  abandonQuest(questId: string): Promise<void>
+  getLeaderboard(options?: {
+    period?: LeaderboardPeriodInput
+    limit?: number
+    offset?: number
+    spaceId?: string
+  }): Promise<LeaderboardEntry[]>
+  getUserRank(): Promise<{ rank: number; percentile: number }>
+  getRewards(options?: {
+    status?: 'available' | 'redeemed' | 'all'
+    page?: number
+  }): Promise<CursorCollectionResponse<Reward>>
+  redeemReward(rewardId: string): Promise<Reward>
+  connectWebSocket(): GamificationWebSocketLike | null
+  disconnectWebSocket(): void
+  subscribe(event: string, callback: (data: GamificationNotification) => void): void
+  unsubscribe(event: string, callback: (data: GamificationNotification) => void): void
+}
+
+const 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 createDefaultWebSocket(url: string): GamificationWebSocketLike {
+  if (typeof WebSocket === 'undefined') {
+    throw new Error('WebSocket is unavailable in this environment')
+  }
+
+  return new WebSocket(url) as unknown as GamificationWebSocketLike
+}
+
+class GamificationService implements GamificationServiceInstance {
+  private ws: GamificationWebSocketLike | null = null
+  private reconnectInterval: ReturnType<typeof setInterval> | null = null
+  private listeners: Map<string, Set<(data: GamificationNotification) => void>> = new Map()
+
+  public constructor(
+    private readonly client: ApiService,
+    private readonly webSocketUrl: string | null,
+    private readonly webSocketFactory: GamificationWebSocketFactory,
+    private readonly reconnectIntervalMs: number,
+    private readonly logger: GamificationServiceLogger,
+    private readonly debug: boolean,
+  ) {}
+
+  public async getUserStats(userId?: string): Promise<UserStats> {
+    const endpoint = userId
+      ? `/v1/gamification/users/${userId}/reputation`
+      : '/v1/gamification/users/me/reputation'
+    const response = await this.client.get<UserStats>(endpoint)
+    return response.data
+  }
+
+  public async getUserReputation(userId?: string): Promise<UserStats> {
+    return this.getUserStats(userId)
+  }
+
+  public async getUserStreak(): Promise<UserStreakStatus> {
+    const response = await this.client.get<UserStreakStatus>('/v1/gamification/users/me/streak')
+    return response.data
+  }
+
+  public async getTransactions(options?: {
+    limit?: number
+    offset?: number
+  }): Promise<PointTransaction[]> {
+    const params = new URLSearchParams()
+    if (options?.limit) {
+      params.append('limit', options.limit.toString())
+    }
+    if (options?.offset) {
+      params.append('offset', options.offset.toString())
+    }
+
+    const query = params.toString()
+    const url = query.length > 0
+      ? `/v1/gamification/users/me/transactions?${query}`
+      : '/v1/gamification/users/me/transactions'
+
+    const response = await this.client.get<PointTransaction[]>(url)
+    return response.data
+  }
+
+  public async getReputationSnapshots(options?: {
+    period?: 'week' | 'month' | 'year'
+  }): Promise<ReputationSnapshot[]> {
+    const params = new URLSearchParams()
+    if (options?.period) {
+      params.append('period', options.period)
+    }
+
+    const query = params.toString()
+    const url = query.length > 0
+      ? `/v1/gamification/users/me/reputation/snapshots?${query}`
+      : '/v1/gamification/users/me/reputation/snapshots'
+
+    const response = await this.client.get<ReputationSnapshot[]>(url)
+    return response.data
+  }
+
+  public async getPrivilegesCatalog(): Promise<ReputationPrivilege[]> {
+    const response = await this.client.get<ReputationPrivilege[]>('/v1/gamification/privileges')
+    return response.data
+  }
+
+  public async getAchievements(options?: {
+    status?: 'locked' | 'unlocked' | 'all'
+    page?: number
+  }): Promise<CursorCollectionResponse<Achievement>> {
+    const params = new URLSearchParams()
+    if (options?.status && options.status !== 'all') {
+      params.append('status', options.status)
+    }
+    if (options?.page) {
+      params.append('page', options.page.toString())
+    }
+
+    const response = await this.client.get<CursorCollectionResponse<Achievement>>(
+      `/v1/gamification/achievements?${params.toString()}`
+    )
+    return response.data
+  }
+
+  public async claimAchievement(achievementId: string): Promise<Achievement> {
+    const response = await this.client.post<Achievement>(`/v1/gamification/achievements/${achievementId}/claim`)
+    return response.data
+  }
+
+  public async getQuests(options?: {
+    status?: 'available' | 'in_progress' | 'completed' | 'all'
+    page?: number
+  }): Promise<CursorCollectionResponse<Quest>> {
+    const params = new URLSearchParams()
+    if (options?.status && options.status !== 'all') {
+      params.append('status', options.status)
+    }
+    if (options?.page) {
+      params.append('page', options.page.toString())
+    }
+
+    const endpoint = options?.status === 'available'
+      ? '/v1/gamification/quests/available'
+      : '/v1/gamification/quests/my-quests'
+    const response = await this.client.get<CursorCollectionResponse<Quest>>(`${endpoint}?${params.toString()}`)
+    return response.data
+  }
+
+  public async claimQuestReward(questId: string): Promise<QuestCompletionResponse> {
+    const idempotencyKey = createQuestCompletionIdempotencyKey(questId)
+    const response = await this.client.post<QuestCompletionResponse>(
+      `/v1/gamification/quests/${questId}/complete`,
+      undefined,
+      {
+        headers: {
+          'Idempotency-Key': idempotencyKey,
+        },
+      },
+    )
+    return response.data
+  }
+
+  public async abandonQuest(questId: string): Promise<void> {
+    await this.client.delete(`/v1/gamification/quests/${questId}/abandon`)
+  }
+
+  public async getLeaderboard(options?: {
+    period?: LeaderboardPeriodInput
+    limit?: number
+    offset?: number
+    spaceId?: string
+  }): Promise<LeaderboardEntry[]> {
+    const params = new URLSearchParams()
+    if (options?.period) {
+      const normalizedPeriod = options.period === 'all_time' ? 'all-time' : options.period
+      params.append('period', normalizedPeriod)
+    }
+    if (options?.limit) {
+      params.append('limit', options.limit.toString())
+    }
+    if (options?.offset) {
+      params.append('offset', options.offset.toString())
+    }
+    if (options?.spaceId) {
+      params.append('space_id', options.spaceId)
+    }
+
+    const query = params.toString()
+    const url = query.length > 0
+      ? `/v1/gamification/leaderboard?${query}`
+      : '/v1/gamification/leaderboard'
+
+    const response = await this.client.get<LeaderboardEntry[]>(url)
+    return response.data
+  }
+
+  public async getUserRank(): Promise<{ rank: number; percentile: number }> {
+    const response = await this.client.get<{ rank: number; percentile: number }>('/v1/gamification/users/me/rank')
+    return response.data
+  }
+
+  public async getRewards(options?: {
+    status?: 'available' | 'redeemed' | 'all'
+    page?: number
+  }): Promise<CursorCollectionResponse<Reward>> {
+    const params = new URLSearchParams()
+    if (options?.status && options.status !== 'all') {
+      params.append('status', options.status)
+    }
+    if (options?.page) {
+      params.append('page', options.page.toString())
+    }
+
+    const query = params.toString()
+    const endpoint = query.length > 0
+      ? `/v1/gamification/rewards?${query}`
+      : '/v1/gamification/rewards'
+
+    const response = await this.client.get<Reward[]>(endpoint)
+    return { data: response.data }
+  }
+
+  public async redeemReward(rewardId: string): Promise<Reward> {
+    const response = await this.client.post<Reward>(`/v1/gamification/rewards/${rewardId}/redeem`)
+    return response.data
+  }
+
+  public connectWebSocket(): GamificationWebSocketLike | null {
+    if (this.ws && this.ws.readyState === this.ws.OPEN) {
+      return this.ws
+    }
+
+    const socketUrl = typeof this.webSocketUrl === 'string' && this.webSocketUrl.length > 0
+      ? this.webSocketUrl
+      : null
+    if (socketUrl === null) {
+      return null
+    }
+
+    try {
+      this.ws = this.webSocketFactory(`${socketUrl}/gamification`)
+
+      this.ws.onopen = () => {
+        this.debugLog('Gamification WebSocket connected')
+        if (this.reconnectInterval) {
+          clearInterval(this.reconnectInterval)
+          this.reconnectInterval = null
+        }
+      }
+
+      this.ws.onmessage = (event) => {
+        try {
+          const payload = typeof event.data === 'string'
+            ? JSON.parse(event.data)
+            : event.data
+          this.handleWebSocketMessage(payload as GamificationNotification)
+        } catch (error) {
+          this.logger.error('Failed to parse WebSocket message:', error)
+        }
+      }
+
+      this.ws.onclose = () => {
+        this.debugLog('Gamification WebSocket disconnected')
+        this.attemptReconnect()
+      }
+
+      this.ws.onerror = (error) => {
+        this.logger.error('Gamification WebSocket error:', error)
+      }
+
+      return this.ws
+    } catch (error) {
+      this.logger.error('Failed to connect WebSocket:', error)
+      return null
+    }
+  }
+
+  public disconnectWebSocket(): void {
+    if (this.ws) {
+      this.ws.close()
+      this.ws = null
+    }
+    if (this.reconnectInterval) {
+      clearInterval(this.reconnectInterval)
+      this.reconnectInterval = null
+    }
+    this.listeners.clear()
+  }
+
+  public subscribe(event: string, callback: (data: GamificationNotification) => void): void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set())
+    }
+    this.listeners.get(event)?.add(callback)
+  }
+
+  public unsubscribe(event: string, callback: (data: GamificationNotification) => void): void {
+    this.listeners.get(event)?.delete(callback)
+  }
+
+  private debugLog(message: string, ...args: unknown[]): void {
+    if (!this.debug) {
+      return
+    }
+
+    this.logger.debug(message, ...args)
+  }
+
+  private attemptReconnect(): void {
+    if (this.reconnectInterval) {
+      return
+    }
+
+    this.reconnectInterval = setInterval(() => {
+      this.debugLog('Gamification WebSocket reconnect attempt')
+      this.connectWebSocket()
+    }, this.reconnectIntervalMs)
+  }
+
+  private handleWebSocketMessage(data: GamificationNotification): void {
+    const listeners = this.listeners.get(data.type)
+    if (listeners) {
+      listeners.forEach((listener) => {
+        listener(data)
+      })
+    }
+
+    const updateListeners = this.listeners.get('update')
+    if (updateListeners) {
+      updateListeners.forEach((listener) => {
+        listener(data)
+      })
+    }
+  }
+}
+
+export function createGamificationService(config: GamificationServiceConfig): GamificationServiceInstance {
+  const {
+    client,
+    webSocketUrl = null,
+    webSocketFactory = createDefaultWebSocket,
+    reconnectIntervalMs = 5000,
+    logger = console,
+    debug = false,
+  } = config
+
+  return new GamificationService(
+    client,
+    webSocketUrl,
+    webSocketFactory,
+    reconnectIntervalMs,
+    logger,
+    debug,
+  )
+}