Eneza API Controllers

Controllers handle HTTP requests and delegate business logic to services. The API has 37 controllers organized by domain.

Controller Structure

All controllers follow a consistent pattern:

// Example controller structure
class ExampleController {
  static async methodName(req: Request, res: Response): Promise<void> {
    try {
      // 1. Extract data from request
      const { param } = req.params;
      const { field } = req.body;

      // 2. Validate input
      if (!field) {
        res.status(400).json({ error: 'Field is required' });
        return;
      }

      // 3. Call service
      const result = await ExampleService.doSomething(param, field);

      // 4. Return response
      res.status(200).json({ data: result });
    } catch (error) {
      logger.error('Error in methodName:', error);
      res.status(500).json({ error: 'Internal server error' });
    }
  }
}

User-Facing Controllers

UserController (userController.ts)

User profile and account management.

class UserController {
  // GET /users/profile - Get current user profile
  static async getProfile(req: CustomRequest, res: Response): Promise<void>

  // PUT /users/profile - Update profile
  static async updateProfile(req: CustomRequest, res: Response): Promise<void>

  // GET /users/balance - Get earnings balance
  static async getBalance(req: CustomRequest, res: Response): Promise<void>

  // GET /users/stats - Get user statistics
  static async getStats(req: CustomRequest, res: Response): Promise<void>

  // GET /users/referral-code - Get user's referral code
  static async getReferralCode(req: CustomRequest, res: Response): Promise<void>
}

UserAuthController (userAuthController.ts)

Phone-based authentication.

class UserAuthController {
  // POST /auth/request-otp - Request SMS OTP
  static async requestOtp(req: Request, res: Response): Promise<void>
  // Body: { phoneNumber: string, countryId: string }

  // POST /auth/verify-otp - Verify OTP and login
  static async verifyOtp(req: Request, res: Response): Promise<void>
  // Body: { phoneNumber: string, code: string }
  // Returns: { user: User, token: string }

  // POST /auth/logout - Invalidate token
  static async logout(req: CustomRequest, res: Response): Promise<void>
}

AdsController (adsController.ts)

Ad discovery for posters.

class AdsController {
  // GET /ads - List available ads for user
  static async getAds(req: CustomRequest, res: Response): Promise<void>
  // Query: { page, limit, categoryId, countryCode }

  // GET /ads/:id - Get ad details
  static async getAdById(req: CustomRequest, res: Response): Promise<void>

  // GET /ads/:id/stats - Get ad statistics
  static async getAdStats(req: CustomRequest, res: Response): Promise<void>

  // GET /ads/trending - Get trending ads
  static async getTrendingAds(req: CustomRequest, res: Response): Promise<void>
}

ScreenshotController (screenshotController.ts)

Screenshot submission and history.

class ScreenshotController {
  // POST /screenshots - Submit screenshot proof
  static async submitScreenshot(req: CustomRequest, res: Response): Promise<void>
  // Body: { subscriptionId: string, screenshotFile: File }
  // Triggers AI verification via Pub/Sub

  // GET /screenshots - User's screenshot history
  static async getScreenshots(req: CustomRequest, res: Response): Promise<void>
  // Query: { page, limit, status }

  // GET /screenshots/:id - Screenshot details
  static async getScreenshotById(req: CustomRequest, res: Response): Promise<void>

  // GET /screenshots/:id/status - Verification status
  static async getScreenshotStatus(req: CustomRequest, res: Response): Promise<void>
}

SubscriptionController (subscriptionController.ts)

Ad subscriptions (downloads).

class SubscriptionController {
  // POST /subscriptions - Subscribe to ad
  static async createSubscription(req: CustomRequest, res: Response): Promise<void>
  // Body: { adId: string, phoneInfo: object }
  // Returns: { subscription, videoUrl }

  // GET /subscriptions - User's subscriptions
  static async getSubscriptions(req: CustomRequest, res: Response): Promise<void>
  // Query: { page, limit, status }

  // GET /subscriptions/:id - Subscription details
  static async getSubscriptionById(req: CustomRequest, res: Response): Promise<void>

  // GET /subscriptions/:id/video - Get personalized video URL
  static async getVideoUrl(req: CustomRequest, res: Response): Promise<void>
}

TransactionController (transactionController.ts)

User transactions and withdrawals.

class TransactionController {
  // GET /transactions - Transaction history
  static async getTransactions(req: CustomRequest, res: Response): Promise<void>
  // Query: { page, limit, type, status }

  // GET /transactions/:code - Transaction by code
  static async getTransactionByCode(req: CustomRequest, res: Response): Promise<void>

  // POST /transactions/withdraw - Request withdrawal
  static async requestWithdrawal(req: CustomRequest, res: Response): Promise<void>
  // Body: { amount: number, paymentMethodId: string }

  // GET /transactions/pending-amount - Pending withdrawal amount
  static async getPendingAmount(req: CustomRequest, res: Response): Promise<void>
}

Advertiser Controllers

AdvertiserAuthController (advertiserAuthController.ts)

Advertiser authentication.

class AdvertiserAuthController {
  // POST /advertisers/signup - Create account
  static async signup(req: Request, res: Response): Promise<void>
  // Body: { email, password, companyName, countryCode }

  // POST /advertisers/login - Login
  static async login(req: Request, res: Response): Promise<void>
  // Body: { email, password }

  // POST /advertisers/forgot-password - Request reset
  static async forgotPassword(req: Request, res: Response): Promise<void>

  // POST /advertisers/reset-password - Reset password
  static async resetPassword(req: Request, res: Response): Promise<void>

  // POST /advertisers/verify-email - Verify email
  static async verifyEmail(req: Request, res: Response): Promise<void>
}

AdvertiserController (advertiserController.ts)

Advertiser profile and campaigns.

class AdvertiserController {
  // GET /advertisers/profile - Get profile
  static async getProfile(req: CustomRequest, res: Response): Promise<void>

  // PUT /advertisers/profile - Update profile
  static async updateProfile(req: CustomRequest, res: Response): Promise<void>

  // GET /advertisers/balance - Get USD balance
  static async getBalance(req: CustomRequest, res: Response): Promise<void>

  // GET /advertisers/campaigns - List campaigns
  static async getCampaigns(req: CustomRequest, res: Response): Promise<void>

  // POST /advertisers/campaigns - Create campaign
  static async createCampaign(req: CustomRequest, res: Response): Promise<void>
  // Body: { title, video, budgetUsd, countryCode, demographics }

  // GET /advertisers/campaigns/:id/stats - Campaign stats
  static async getCampaignStats(req: CustomRequest, res: Response): Promise<void>
}

CampaignPaymentController (campaignPaymentController.ts)

Stripe payment processing for campaigns.

class CampaignPaymentController {
  // POST /api/campaign-payments/create-checkout - Create Stripe session
  static async createCheckoutSession(req: CustomRequest, res: Response): Promise<void>
  // Body: { adId: string, successUrl, cancelUrl }

  // POST /api/campaign-payments/webhook - Stripe webhook
  static async handleWebhook(req: Request, res: Response): Promise<void>
  // Requires raw body for signature verification

  // GET /api/campaign-payments/:id - Payment status
  static async getPaymentStatus(req: CustomRequest, res: Response): Promise<void>
}

Admin Controllers

Admin User Management

// Admin User Controller (admin/userRoutes.ts)
class AdminUserController {
  // GET /admin/users - List users with filters
  static async listUsers(req: Request, res: Response): Promise<void>
  // Query: { page, limit, search, countryId, status, kycStatus }

  // GET /admin/users/:id - User details
  static async getUser(req: Request, res: Response): Promise<void>

  // PUT /admin/users/:id - Update user
  static async updateUser(req: Request, res: Response): Promise<void>

  // POST /admin/users/:id/ban - Ban user
  static async banUser(req: Request, res: Response): Promise<void>

  // POST /admin/users/:id/unban - Unban user
  static async unbanUser(req: Request, res: Response): Promise<void>

  // GET /admin/users/:id/transactions - User's transactions
  static async getUserTransactions(req: Request, res: Response): Promise<void>
}

Admin Ad Management

// Admin Ad Controller (admin/adRoutes.ts)
class AdminAdController {
  // GET /admin/ads - List ads with filters
  static async listAds(req: Request, res: Response): Promise<void>
  // Query: { status, advertiserId, countryId, page, limit }

  // GET /admin/ads/:id - Ad details
  static async getAd(req: Request, res: Response): Promise<void>

  // PUT /admin/ads/:id/approve - Approve ad
  static async approveAd(req: Request, res: Response): Promise<void>

  // PUT /admin/ads/:id/reject - Reject ad
  static async rejectAd(req: Request, res: Response): Promise<void>
  // Body: { reason: string }

  // PUT /admin/ads/:id/pause - Pause campaign
  static async pauseAd(req: Request, res: Response): Promise<void>

  // DELETE /admin/ads/:id - Soft delete ad
  static async deleteAd(req: Request, res: Response): Promise<void>
}

Admin Screenshot Review

// Admin Screenshot Controller (admin/screenshotRoutes.ts)
class AdminScreenshotController {
  // GET /admin/screenshots - Review queue
  static async listScreenshots(req: Request, res: Response): Promise<void>
  // Query: { status: 'pending'|'needs_review', adId, userId, page, limit }

  // GET /admin/screenshots/:id - Screenshot details
  static async getScreenshot(req: Request, res: Response): Promise<void>

  // POST /admin/screenshots/:id/approve - Manual approve
  static async approveScreenshot(req: Request, res: Response): Promise<void>

  // POST /admin/screenshots/:id/reject - Manual reject
  static async rejectScreenshot(req: Request, res: Response): Promise<void>
  // Body: { reason: string }

  // POST /admin/screenshots/bulk-approve - Bulk approve
  static async bulkApprove(req: Request, res: Response): Promise<void>
  // Body: { screenshotIds: string[] }
}

Admin Finance

// Admin Financial Controller (admin/financialRoutes.ts)
class AdminFinancialController {
  // GET /admin/finance/transactions - All transactions
  static async listTransactions(req: Request, res: Response): Promise<void>

  // GET /admin/finance/withdrawals - Pending withdrawals
  static async listPendingWithdrawals(req: Request, res: Response): Promise<void>

  // POST /admin/finance/withdrawals/:id/process - Process withdrawal
  static async processWithdrawal(req: Request, res: Response): Promise<void>
  // Body: { status: 'paid'|'cancelled', reference?: string }

  // GET /admin/finance/invoices - All invoices
  static async listInvoices(req: Request, res: Response): Promise<void>

  // GET /admin/finance/deposits - Advertiser deposits
  static async listDeposits(req: Request, res: Response): Promise<void>
}

Dashboard Controller

DashboardController (dashboard.controller.ts)

CEO dashboard metrics (used by website).

class DashboardController {
  // GET /api/dashboard/metrics - Public metrics
  static async getMetrics(req: Request, res: Response): Promise<void>
  // Requires X-API-Key header
  // Returns: { users, advertisers, totalEarnings, activeAds, ... }

  // GET /admin/analytics/overview - Admin analytics
  static async getOverview(req: Request, res: Response): Promise<void>
  // Returns: detailed analytics for admin dashboard
}

Support Controllers

SupportTicketsController (supportTicketsController.ts)

User support tickets.

class SupportTicketsController {
  // POST /support-tickets - Create ticket
  static async createTicket(req: CustomRequest, res: Response): Promise<void>
  // Body: { subject, category, message, screenshotUrl? }

  // GET /support-tickets - User's tickets
  static async getTickets(req: CustomRequest, res: Response): Promise<void>

  // GET /support-tickets/:id - Ticket details
  static async getTicket(req: CustomRequest, res: Response): Promise<void>

  // POST /support-tickets/:id/messages - Add message
  static async addMessage(req: CustomRequest, res: Response): Promise<void>
  // Body: { message: string }

  // POST /support-tickets/:id/close - Close ticket
  static async closeTicket(req: CustomRequest, res: Response): Promise<void>
}

Utility Controllers

CategoryController (categoryController.ts)

Ad categories.

class CategoryController {
  // GET /categories - List categories
  static async getCategories(req: Request, res: Response): Promise<void>

  // GET /categories/:id - Category details
  static async getCategoryById(req: Request, res: Response): Promise<void>
}

CountryController (countryController.ts)

Supported countries.

class CountryController {
  // GET /countries - List countries
  static async getCountries(req: Request, res: Response): Promise<void>

  // GET /countries/:code - Country by code
  static async getCountryByCode(req: Request, res: Response): Promise<void>

  // GET /countries/:id/cities - Cities in country
  static async getCitiesByCountry(req: Request, res: Response): Promise<void>
}

DeviceTokenController (deviceTokenController.ts)

Push notification token management.

class DeviceTokenController {
  // POST /device-token - Register token
  static async registerToken(req: CustomRequest, res: Response): Promise<void>
  // Body: { token: string, platform: 'android'|'ios' }

  // DELETE /device-token - Remove token
  static async removeToken(req: CustomRequest, res: Response): Promise<void>
}