dubs-server 1.0.0

package/services/promoService.js

@@ -0,0 +1,757 @@
+/**
+ * 🎟️ Promo Code Service
+ *
+ * Handles promo code management for the Risk-Free First Bet incentive system.
+ *
+ * How it works:
+ *   - Promo codes are generated in batches (e.g., 2 daily for Twitter giveaways)
+ *   - Each code is worth a fixed amount (default: 0.1 SOL)
+ *   - User enters code during onboarding → code is reserved for them
+ *   - When user joins a game, treasury wallet pays on their behalf
+ *   - If they win → real SOL winnings
+ *   - If they lose → winner takes pot (treasury's money)
+ *   - If tie/refund → treasury gets auto-refund (not user)
+ */
+
+const { pool } = require('./db');
+
+// Configuration
+const DEFAULT_PROMO_AMOUNT_LAMPORTS = 100_000_000; // 0.1 SOL
+const LAMPORTS_PER_SOL = 1_000_000_000;
+const CODE_RESERVATION_TIMEOUT_MINUTES = 30;
+
+/**
+ * Generate a unique promo code
+ * Format: DUBS-XXXX-XXXX (easy to type, share on Twitter)
+ */
+function generatePromoCode() {
+  const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'; // Excludes confusing chars (0,O,1,I)
+  const segment = () => Array(4).fill(0).map(() => chars[Math.floor(Math.random() * chars.length)]).join('');
+  return `DUBS-${segment()}-${segment()}`;
+}
+
+/**
+ * Create promo codes table if it doesn't exist
+ * Call this once during server startup
+ */
+async function ensureTablesExist() {
+  try {
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS promo_codes (
+        id SERIAL PRIMARY KEY,
+        code VARCHAR(50) UNIQUE NOT NULL,
+        amount_lamports BIGINT NOT NULL DEFAULT ${DEFAULT_PROMO_AMOUNT_LAMPORTS},
+
+        -- Status: available → reserved → used OR expired
+        status VARCHAR(20) DEFAULT 'available',
+
+        -- Reservation tracking (when user enters code during onboarding)
+        reserved_by VARCHAR(255),           -- Wallet address
+        reserved_at TIMESTAMP,
+        reservation_expires_at TIMESTAMP,
+
+        -- Usage tracking (when user actually joins a game)
+        used_by VARCHAR(255),               -- Wallet address (should match reserved_by)
+        used_at TIMESTAMP,
+        used_in_game VARCHAR(255),          -- Game ID
+
+        -- Outcome tracking (after game resolves)
+        game_outcome VARCHAR(20),           -- won, lost, refunded
+        outcome_recorded_at TIMESTAMP,
+
+        -- Metadata
+        created_at TIMESTAMP DEFAULT NOW(),
+        expires_at TIMESTAMP,               -- Hard expiration (e.g., end of promo campaign)
+        batch_id VARCHAR(100),              -- For tracking Twitter giveaway batches
+        notes TEXT
+      );
+
+      -- Indexes for common queries
+      CREATE INDEX IF NOT EXISTS idx_promo_codes_code ON promo_codes(code);
+      CREATE INDEX IF NOT EXISTS idx_promo_codes_status ON promo_codes(status);
+      CREATE INDEX IF NOT EXISTS idx_promo_codes_reserved_by ON promo_codes(reserved_by);
+      CREATE INDEX IF NOT EXISTS idx_promo_codes_used_by ON promo_codes(used_by);
+      CREATE INDEX IF NOT EXISTS idx_promo_codes_batch_id ON promo_codes(batch_id);
+
+      -- Add banner_dismissed column if it doesn't exist (for migration)
+      ALTER TABLE promo_codes ADD COLUMN IF NOT EXISTS banner_dismissed BOOLEAN DEFAULT FALSE;
+    `);
+
+    console.log('[PromoService] ✅ promo_codes table ready');
+  } catch (error) {
+    console.error('[PromoService] ❌ Error creating tables:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Generate a batch of promo codes
+ * @param {number} count - Number of codes to generate
+ * @param {Object} options - Generation options
+ * @returns {Array} - Generated codes
+ */
+async function generateBatch(count, options = {}) {
+  const {
+    amountLamports = DEFAULT_PROMO_AMOUNT_LAMPORTS,
+    expiresAt = null,
+    batchId = `batch-${Date.now()}`,
+    notes = null
+  } = options;
+
+  console.log(`[PromoService] 🎟️ Generating ${count} promo codes (batch: ${batchId})`);
+  console.log(`[PromoService]    Amount per code: ${amountLamports / LAMPORTS_PER_SOL} SOL`);
+
+  const codes = [];
+  const maxAttempts = count * 3; // Prevent infinite loop on collision
+  let attempts = 0;
+
+  while (codes.length < count && attempts < maxAttempts) {
+    attempts++;
+    const code = generatePromoCode();
+
+    try {
+      const result = await pool.query(`
+        INSERT INTO promo_codes (code, amount_lamports, expires_at, batch_id, notes)
+        VALUES ($1, $2, $3, $4, $5)
+        ON CONFLICT (code) DO NOTHING
+        RETURNING id, code, amount_lamports
+      `, [code, amountLamports, expiresAt, batchId, notes]);
+
+      if (result.rows.length > 0) {
+        codes.push({
+          id: result.rows[0].id,
+          code: result.rows[0].code,
+          amountLamports: parseInt(result.rows[0].amount_lamports),
+          amountSOL: parseInt(result.rows[0].amount_lamports) / LAMPORTS_PER_SOL
+        });
+      }
+    } catch (error) {
+      console.error(`[PromoService] Error inserting code:`, error.message);
+    }
+  }
+
+  console.log(`[PromoService] ✅ Generated ${codes.length} codes in ${attempts} attempts`);
+  return codes;
+}
+
+/**
+ * Validate a promo code (check if it exists and is available)
+ * Does NOT reserve it - just checks validity
+ * @param {string} code - The promo code to validate
+ * @returns {Object} - Validation result
+ */
+async function validateCode(code) {
+  try {
+    const normalizedCode = code.trim().toUpperCase();
+
+    const result = await pool.query(`
+      SELECT
+        id, code, amount_lamports, status,
+        reserved_by, reserved_at, reservation_expires_at,
+        expires_at
+      FROM promo_codes
+      WHERE code = $1
+    `, [normalizedCode]);
+
+    if (result.rows.length === 0) {
+      return { valid: false, error: 'Invalid promo code' };
+    }
+
+    const promo = result.rows[0];
+
+    // Check if code has hard expired
+    if (promo.expires_at && new Date(promo.expires_at) < new Date()) {
+      return { valid: false, error: 'Promo code has expired' };
+    }
+
+    // Check status
+    if (promo.status === 'used') {
+      return { valid: false, error: 'Promo code has already been used' };
+    }
+
+    if (promo.status === 'expired') {
+      return { valid: false, error: 'Promo code has expired' };
+    }
+
+    // If reserved, check if reservation has expired
+    if (promo.status === 'reserved') {
+      const reservationExpired = promo.reservation_expires_at &&
+        new Date(promo.reservation_expires_at) < new Date();
+
+      if (!reservationExpired) {
+        return {
+          valid: false,
+          error: 'This promo code is already claimed',
+          code: 'ALREADY_CLAIMED'
+        };
+      }
+      // Reservation expired, code is available again
+    }
+
+    return {
+      valid: true,
+      code: promo.code,
+      amountLamports: parseInt(promo.amount_lamports),
+      amountSOL: parseInt(promo.amount_lamports) / LAMPORTS_PER_SOL
+    };
+
+  } catch (error) {
+    console.error('[PromoService] Error validating code:', error.message);
+    return { valid: false, error: 'Error validating promo code' };
+  }
+}
+
+/**
+ * Reserve a promo code for a user during onboarding
+ * Reserves for CODE_RESERVATION_TIMEOUT_MINUTES before expiring
+ * @param {string} code - The promo code
+ * @param {string} walletAddress - User's wallet address
+ * @returns {Object} - Reservation result
+ */
+async function reserveCode(code, walletAddress) {
+  try {
+    const normalizedCode = code.trim().toUpperCase();
+
+    console.log(`[PromoService] 🎯 Reserving code ${normalizedCode} for ${walletAddress.slice(0, 8)}...`);
+
+    // First validate
+    const validation = await validateCode(normalizedCode);
+    if (!validation.valid) {
+      return validation;
+    }
+
+    // Check if user already has a reserved/unused code
+    const existingReservation = await pool.query(`
+      SELECT code FROM promo_codes
+      WHERE reserved_by = $1 AND status = 'reserved'
+      AND (reservation_expires_at IS NULL OR reservation_expires_at > NOW())
+    `, [walletAddress]);
+
+    if (existingReservation.rows.length > 0) {
+      return {
+        valid: false,
+        error: 'You already have a promo code reserved',
+        existingCode: existingReservation.rows[0].code
+      };
+    }
+
+    // Reserve the code
+    const expiresAt = new Date(Date.now() + CODE_RESERVATION_TIMEOUT_MINUTES * 60 * 1000);
+
+    const result = await pool.query(`
+      UPDATE promo_codes
+      SET
+        status = 'reserved',
+        reserved_by = $2,
+        reserved_at = NOW(),
+        reservation_expires_at = $3
+      WHERE code = $1
+        AND (status = 'available' OR (status = 'reserved' AND reservation_expires_at < NOW()))
+      RETURNING id, code, amount_lamports
+    `, [normalizedCode, walletAddress, expiresAt]);
+
+    if (result.rows.length === 0) {
+      return { valid: false, error: 'Could not reserve code - it may have just been claimed' };
+    }
+
+    console.log(`[PromoService] ✅ Code reserved until ${expiresAt.toISOString()}`);
+
+    return {
+      success: true,
+      code: result.rows[0].code,
+      amountLamports: parseInt(result.rows[0].amount_lamports),
+      amountSOL: parseInt(result.rows[0].amount_lamports) / LAMPORTS_PER_SOL,
+      expiresAt
+    };
+
+  } catch (error) {
+    console.error('[PromoService] Error reserving code:', error.message);
+    return { valid: false, error: 'Error reserving promo code' };
+  }
+}
+
+/**
+ * Get user's active promo code (reserved but not yet used)
+ * @param {string} walletAddress - User's wallet address
+ * @returns {Object|null} - Active promo code or null
+ */
+async function getActivePromoForUser(walletAddress) {
+  try {
+    const result = await pool.query(`
+      SELECT id, code, amount_lamports, reserved_at, reservation_expires_at
+      FROM promo_codes
+      WHERE reserved_by = $1
+        AND status = 'reserved'
+        AND (reservation_expires_at IS NULL OR reservation_expires_at > NOW())
+    `, [walletAddress]);
+
+    if (result.rows.length === 0) {
+      return null;
+    }
+
+    const promo = result.rows[0];
+    return {
+      id: promo.id,
+      code: promo.code,
+      amountLamports: parseInt(promo.amount_lamports),
+      amountSOL: parseInt(promo.amount_lamports) / LAMPORTS_PER_SOL,
+      reservedAt: promo.reserved_at,
+      expiresAt: promo.reservation_expires_at
+    };
+
+  } catch (error) {
+    console.error('[PromoService] Error getting active promo:', error.message);
+    return null;
+  }
+}
+
+/**
+ * Mark a promo code as used (called after successful sponsored join)
+ * @param {string} code - The promo code
+ * @param {string} walletAddress - User's wallet address
+ * @param {string} gameId - Game ID they joined
+ * @returns {Object} - Result
+ */
+async function markCodeAsUsed(code, walletAddress, gameId) {
+  try {
+    const normalizedCode = code.trim().toUpperCase();
+
+    console.log(`[PromoService] 📝 Marking code ${normalizedCode} as used in game ${gameId}`);
+
+    const result = await pool.query(`
+      UPDATE promo_codes
+      SET
+        status = 'used',
+        used_by = $2,
+        used_at = NOW(),
+        used_in_game = $3
+      WHERE code = $1
+        AND reserved_by = $2
+        AND status = 'reserved'
+      RETURNING id, code
+    `, [normalizedCode, walletAddress, gameId]);
+
+    if (result.rows.length === 0) {
+      return { success: false, error: 'Code not found or not reserved by this user' };
+    }
+
+    console.log(`[PromoService] ✅ Code marked as used`);
+    return { success: true, code: normalizedCode };
+
+  } catch (error) {
+    console.error('[PromoService] Error marking code as used:', error.message);
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Record the outcome of a promo game (won, lost, refunded)
+ * Called by oracle after game resolution
+ * @param {string} gameId - The game ID
+ * @param {string} outcome - 'won', 'lost', or 'refunded'
+ * @returns {Object} - Result
+ */
+async function recordGameOutcome(gameId, outcome) {
+  try {
+    console.log(`[PromoService] 📊 Recording outcome for game ${gameId}: ${outcome}`);
+
+    const result = await pool.query(`
+      UPDATE promo_codes
+      SET
+        game_outcome = $2,
+        outcome_recorded_at = NOW()
+      WHERE used_in_game = $1
+      RETURNING id, code, used_by
+    `, [gameId, outcome]);
+
+    if (result.rows.length === 0) {
+      // No promo code was used in this game - that's fine
+      return { success: true, promoUsed: false };
+    }
+
+    console.log(`[PromoService] ✅ Outcome recorded for code ${result.rows[0].code}`);
+    return {
+      success: true,
+      promoUsed: true,
+      code: result.rows[0].code,
+      userWallet: result.rows[0].used_by
+    };
+
+  } catch (error) {
+    console.error('[PromoService] Error recording outcome:', error.message);
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Get promo code statistics
+ * @returns {Object} - Stats
+ */
+async function getStats() {
+  try {
+    const result = await pool.query(`
+      SELECT
+        COUNT(*) as total_codes,
+        COUNT(*) FILTER (WHERE status = 'available') as available,
+        COUNT(*) FILTER (WHERE status = 'reserved') as reserved,
+        COUNT(*) FILTER (WHERE status = 'used') as used,
+        COUNT(*) FILTER (WHERE status = 'expired') as expired,
+        COUNT(*) FILTER (WHERE game_outcome = 'won') as won_games,
+        COUNT(*) FILTER (WHERE game_outcome = 'lost') as lost_games,
+        COUNT(*) FILTER (WHERE game_outcome = 'refunded') as refunded_games,
+        COALESCE(SUM(amount_lamports) FILTER (WHERE status = 'used'), 0) as total_used_lamports
+      FROM promo_codes
+    `);
+
+    const stats = result.rows[0];
+    return {
+      totalCodes: parseInt(stats.total_codes),
+      available: parseInt(stats.available),
+      reserved: parseInt(stats.reserved),
+      used: parseInt(stats.used),
+      expired: parseInt(stats.expired),
+      outcomes: {
+        won: parseInt(stats.won_games),
+        lost: parseInt(stats.lost_games),
+        refunded: parseInt(stats.refunded_games)
+      },
+      totalUsedLamports: parseInt(stats.total_used_lamports),
+      totalUsedSOL: parseInt(stats.total_used_lamports) / LAMPORTS_PER_SOL
+    };
+
+  } catch (error) {
+    console.error('[PromoService] Error getting stats:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Expire stale reservations (run periodically)
+ * @returns {number} - Number of codes expired
+ */
+async function expireStaleReservations() {
+  try {
+    const result = await pool.query(`
+      UPDATE promo_codes
+      SET
+        status = 'available',
+        reserved_by = NULL,
+        reserved_at = NULL,
+        reservation_expires_at = NULL
+      WHERE status = 'reserved'
+        AND reservation_expires_at < NOW()
+      RETURNING id
+    `);
+
+    if (result.rows.length > 0) {
+      console.log(`[PromoService] 🧹 Expired ${result.rows.length} stale reservations`);
+    }
+
+    return result.rows.length;
+
+  } catch (error) {
+    console.error('[PromoService] Error expiring reservations:', error.message);
+    return 0;
+  }
+}
+
+/**
+ * Get all promo codes (for admin dashboard)
+ * @returns {Array} - All codes
+ */
+async function getAllCodes() {
+  try {
+    const result = await pool.query(`
+      SELECT
+        id, code, amount_lamports, status,
+        reserved_by, reserved_at, reservation_expires_at,
+        used_by, used_at, used_in_game, game_outcome,
+        created_at, expires_at, batch_id
+      FROM promo_codes
+      ORDER BY
+        CASE
+          WHEN status = 'reserved' THEN 1
+          WHEN status = 'available' THEN 2
+          WHEN status = 'used' THEN 3
+          ELSE 4
+        END,
+        created_at DESC
+    `);
+
+    return result.rows.map(row => ({
+      id: row.id,
+      code: row.code,
+      amountLamports: parseInt(row.amount_lamports),
+      amountSOL: parseInt(row.amount_lamports) / LAMPORTS_PER_SOL,
+      status: row.status,
+      reservedBy: row.reserved_by,
+      reservedAt: row.reserved_at,
+      reservationExpiresAt: row.reservation_expires_at,
+      usedBy: row.used_by,
+      usedAt: row.used_at,
+      usedInGame: row.used_in_game,
+      gameOutcome: row.game_outcome,
+      createdAt: row.created_at,
+      expiresAt: row.expires_at,
+      batchId: row.batch_id
+    }));
+
+  } catch (error) {
+    console.error('[PromoService] Error getting all codes:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Get promo codes by batch (for admin/tracking)
+ * @param {string} batchId - Batch ID
+ * @returns {Array} - Codes in batch
+ */
+async function getCodesByBatch(batchId) {
+  try {
+    const result = await pool.query(`
+      SELECT
+        id, code, amount_lamports, status,
+        reserved_by, reserved_at,
+        used_by, used_at, used_in_game, game_outcome,
+        created_at, expires_at
+      FROM promo_codes
+      WHERE batch_id = $1
+      ORDER BY created_at DESC
+    `, [batchId]);
+
+    return result.rows.map(row => ({
+      id: row.id,
+      code: row.code,
+      amountLamports: parseInt(row.amount_lamports),
+      amountSOL: parseInt(row.amount_lamports) / LAMPORTS_PER_SOL,
+      status: row.status,
+      reservedBy: row.reserved_by,
+      reservedAt: row.reserved_at,
+      usedBy: row.used_by,
+      usedAt: row.used_at,
+      usedInGame: row.used_in_game,
+      gameOutcome: row.game_outcome,
+      createdAt: row.created_at,
+      expiresAt: row.expires_at
+    }));
+
+  } catch (error) {
+    console.error('[PromoService] Error getting batch codes:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Get user's promo status for the in-app banner and profile page
+ * Returns info about their reserved or used promo code
+ * @param {string} walletAddress - User's wallet address
+ * @returns {Object} - Promo status
+ */
+async function getUserPromoStatus(walletAddress) {
+  try {
+    console.log('[PromoService] getUserPromoStatus for wallet:', walletAddress);
+
+    // Fetch ALL promo codes for this wallet (reserved + used), joined with games for title
+    const result = await pool.query(`
+      SELECT
+        p.code, p.amount_lamports, p.status,
+        p.game_outcome, p.banner_dismissed,
+        p.used_in_game, p.used_at,
+        g.title AS game_title
+      FROM promo_codes p
+      LEFT JOIN games g ON g.game_id = p.used_in_game
+      WHERE (p.reserved_by = $1 OR p.used_by = $1)
+        AND p.status IN ('reserved', 'used')
+        AND (
+          p.status = 'used'
+          OR (p.status = 'reserved' AND (p.reservation_expires_at IS NULL OR p.reservation_expires_at > NOW()))
+        )
+      ORDER BY
+        CASE WHEN p.status = 'reserved' THEN 1 ELSE 2 END,
+        p.reserved_at DESC NULLS LAST
+    `, [walletAddress]);
+
+    console.log('[PromoService] Query result rows:', result.rows.length);
+
+    if (result.rows.length === 0) {
+      console.log('[PromoService] No promo found for wallet:', walletAddress);
+      return {
+        hasActivePromo: false,
+        code: null,
+        amountSOL: 0,
+        status: null,
+        gameOutcome: null,
+        gameId: null,
+        gameTitle: null,
+        usedAt: null,
+        bannerDismissed: false,
+        promoHistory: []
+      };
+    }
+
+    // Build full history
+    const promoHistory = result.rows.map(row => ({
+      code: row.code,
+      amountSOL: parseInt(row.amount_lamports) / LAMPORTS_PER_SOL,
+      status: row.status,
+      gameOutcome: row.game_outcome,
+      gameId: row.used_in_game,
+      gameTitle: row.game_title || null,
+      usedAt: row.used_at,
+    }));
+
+    // The "active" promo is the first one (reserved takes priority, then most recent)
+    const active = result.rows[0];
+    return {
+      hasActivePromo: true,
+      code: active.code,
+      amountSOL: parseInt(active.amount_lamports) / LAMPORTS_PER_SOL,
+      status: active.status,
+      gameOutcome: active.game_outcome,
+      gameId: active.used_in_game,
+      gameTitle: active.game_title || null,
+      usedAt: active.used_at,
+      bannerDismissed: active.banner_dismissed || false,
+      promoHistory
+    };
+
+  } catch (error) {
+    console.error('[PromoService] Error getting user promo status:', error.message);
+    return {
+      hasActivePromo: false,
+      code: null,
+      amountSOL: 0,
+      status: null,
+      gameOutcome: null,
+      gameId: null,
+      gameTitle: null,
+      usedAt: null,
+      bannerDismissed: false,
+      promoHistory: []
+    };
+  }
+}
+
+/**
+ * Confirm a promo code reservation after user completes registration
+ * This removes the expiration time so the code won't be released
+ * @param {string} walletAddress - User's wallet address
+ * @returns {Object} - Result
+ */
+async function confirmReservation(walletAddress) {
+  try {
+    const result = await pool.query(`
+      UPDATE promo_codes
+      SET reservation_expires_at = NULL
+      WHERE reserved_by = $1
+        AND status = 'reserved'
+      RETURNING id, code
+    `, [walletAddress]);
+
+    if (result.rows.length === 0) {
+      return { success: false, error: 'No reservation found' };
+    }
+
+    console.log(`[PromoService] ✅ Reservation confirmed for ${walletAddress.slice(0, 8)}... (expiration removed)`);
+    return { success: true, code: result.rows[0].code };
+
+  } catch (error) {
+    console.error('[PromoService] Error confirming reservation:', error.message);
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Dismiss the promo banner for a user
+ * @param {string} walletAddress - User's wallet address
+ * @returns {Object} - Result
+ */
+async function dismissBanner(walletAddress) {
+  try {
+    const result = await pool.query(`
+      UPDATE promo_codes
+      SET banner_dismissed = TRUE
+      WHERE (reserved_by = $1 OR used_by = $1)
+        AND status IN ('reserved', 'used')
+      RETURNING id, code
+    `, [walletAddress]);
+
+    if (result.rows.length === 0) {
+      return { success: false, error: 'No active promo code found' };
+    }
+
+    console.log(`[PromoService] ✅ Banner dismissed for ${walletAddress.slice(0, 8)}...`);
+    return { success: true };
+
+  } catch (error) {
+    console.error('[PromoService] Error dismissing banner:', error.message);
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Release a specific promo code back to available status (admin function)
+ * @param {string} code - The promo code to release
+ * @returns {Object} - Result
+ */
+async function releaseCode(code) {
+  try {
+    const normalizedCode = code.trim().toUpperCase();
+
+    const result = await pool.query(`
+      UPDATE promo_codes
+      SET
+        status = 'available',
+        reserved_by = NULL,
+        reserved_at = NULL,
+        reservation_expires_at = NULL
+      WHERE code = $1
+        AND status = 'reserved'
+      RETURNING id, code
+    `, [normalizedCode]);
+
+    if (result.rows.length === 0) {
+      return { success: false, error: 'Code not found or not in reserved status' };
+    }
+
+    console.log(`[PromoService] 🔓 Released code ${normalizedCode} back to available`);
+    return { success: true, code: normalizedCode };
+
+  } catch (error) {
+    console.error('[PromoService] Error releasing code:', error.message);
+    return { success: false, error: error.message };
+  }
+}
+
+module.exports = {
+  // Configuration
+  DEFAULT_PROMO_AMOUNT_LAMPORTS,
+  LAMPORTS_PER_SOL,
+  CODE_RESERVATION_TIMEOUT_MINUTES,
+
+  // Setup
+  ensureTablesExist,
+
+  // Code generation
+  generateBatch,
+
+  // User-facing
+  validateCode,
+  reserveCode,
+  confirmReservation,
+  getActivePromoForUser,
+  markCodeAsUsed,
+  getUserPromoStatus,
+  dismissBanner,
+
+  // Oracle/game resolution
+  recordGameOutcome,
+
+  // Admin/stats
+  getStats,
+  getAllCodes,
+  getCodesByBatch,
+  expireStaleReservations,
+  releaseCode
+};