Merge pull request #378 from Jessepriase/feat/indexer-rest-api

feat: implement internal REST API in indexer

Author: Otaiki1

indexer/src/api/api-key.guard.ts

@@ -0,0 +1,36 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  UnauthorizedException,
+} from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { Request } from "express";
+
+/**
+ * Optional internal-only API key guard.
+ * Activated when the INTERNAL_API_KEY env var is set.
+ * Clients must send:  x-api-key: <INTERNAL_API_KEY>
+ * When the env var is absent the guard is a no-op (open access).
+ */
+@Injectable()
+export class ApiKeyGuard implements CanActivate {
+  private readonly apiKey: string | undefined;
+
+  constructor(private readonly configService: ConfigService) {
+    this.apiKey = this.configService.get<string>("INTERNAL_API_KEY");
+  }
+
+  canActivate(context: ExecutionContext): boolean {
+    if (!this.apiKey) return true; // guard disabled — no key configured
+
+    const request = context.switchToHttp().getRequest<Request>();
+    const provided = request.headers["x-api-key"];
+
+    if (provided !== this.apiKey) {
+      throw new UnauthorizedException("Invalid or missing API key");
+    }
+
+    return true;
+  }
+}

indexer/src/api/api.module.ts

@@ -0,0 +1,26 @@
+import { Module } from "@nestjs/common";
+import { TypeOrmModule } from "@nestjs/typeorm";
+import { RafflesController } from "./controllers/raffles.controller";
+import { UsersController } from "./controllers/users.controller";
+import { StatsController } from "./controllers/stats.controller";
+import { ApiKeyGuard } from "./api-key.guard";
+import { RaffleEntity } from "../database/entities/raffle.entity";
+import { TicketEntity } from "../database/entities/ticket.entity";
+import { UserEntity } from "../database/entities/user.entity";
+import { PlatformStatEntity } from "../database/entities/platform-stat.entity";
+import { CacheModule } from "../cache/cache.module";
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([
+      RaffleEntity,
+      TicketEntity,
+      UserEntity,
+      PlatformStatEntity,
+    ]),
+    CacheModule,
+  ],
+  controllers: [RafflesController, UsersController, StatsController],
+  providers: [ApiKeyGuard],
+})
+export class ApiModule {}

indexer/src/api/controllers/raffles.controller.ts

@@ -0,0 +1,128 @@
+import {
+  Controller,
+  Get,
+  Param,
+  Query,
+  NotFoundException,
+  ParseIntPipe,
+  UseGuards,
+} from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { Repository } from "typeorm";
+import { CacheService } from "../../cache/cache.service";
+import { RaffleEntity } from "../../database/entities/raffle.entity";
+import { TicketEntity } from "../../database/entities/ticket.entity";
+import { ApiKeyGuard } from "../api-key.guard";
+
+export interface RaffleListQuery {
+  status?: string;
+  creator?: string;
+  asset?: string;
+  category?: string;
+  limit?: string;
+  offset?: string;
+}
+
+@UseGuards(ApiKeyGuard)
+@Controller("raffles")
+export class RafflesController {
+  constructor(
+    @InjectRepository(RaffleEntity)
+    private readonly raffleRepo: Repository<RaffleEntity>,
+    @InjectRepository(TicketEntity)
+    private readonly ticketRepo: Repository<TicketEntity>,
+    private readonly cacheService: CacheService,
+  ) {}
+
+  /**
+   * GET /raffles
+   * List raffles with optional filters and pagination.
+   * Uses cache for the active-raffle list; falls back to PostgreSQL.
+   */
+  @Get()
+  async list(@Query() query: RaffleListQuery) {
+    const limit = Math.min(parseInt(query.limit ?? "20", 10), 100);
+    const offset = parseInt(query.offset ?? "0", 10);
+
+    // Serve from cache when querying active raffles with no other filters
+    const isActiveOnlyQuery =
+      (!query.status || query.status === "open") &&
+      !query.creator &&
+      !query.asset &&
+      !query.category &&
+      offset === 0 &&
+      limit === 20;
+
+    if (isActiveOnlyQuery) {
+      const cached = await this.cacheService.getActiveRaffles();
+      if (cached) return cached;
+    }
+
+    const qb = this.raffleRepo
+      .createQueryBuilder("r")
+      .orderBy("r.createdAt", "DESC")
+      .limit(limit)
+      .offset(offset);
+
+    if (query.status) qb.andWhere("r.status = :status", { status: query.status });
+    if (query.creator) qb.andWhere("r.creator = :creator", { creator: query.creator });
+    if (query.asset) qb.andWhere("r.asset = :asset", { asset: query.asset });
+
+    const [items, total] = await qb.getManyAndCount();
+
+    const result = {
+      data: items.map(this.formatRaffle),
+      total,
+      limit,
+      offset,
+    };
+
+    if (isActiveOnlyQuery) {
+      await this.cacheService.setActiveRaffles(result);
+    }
+
+    return result;
+  }
+
+  /**
+   * GET /raffles/:id
+   * Raffle detail — cache-first, PostgreSQL fallback.
+   */
+  @Get(":id")
+  async detail(@Param("id", ParseIntPipe) id: number) {
+    const cached = await this.cacheService.getRaffleDetail(String(id));
+    if (cached) return cached;
+
+    const raffle = await this.raffleRepo.findOne({ where: { id } });
+    if (!raffle) throw new NotFoundException(`Raffle ${id} not found`);
+
+    const ticketCount = await this.ticketRepo.count({ where: { raffleId: id } });
+
+    const result = {
+      ...this.formatRaffle(raffle),
+      participant_count: ticketCount,
+    };
+
+    await this.cacheService.setRaffleDetail(String(id), result);
+    return result;
+  }
+
+  private formatRaffle(r: RaffleEntity) {
+    return {
+      id: r.id,
+      creator: r.creator,
+      status: r.status,
+      ticket_price: r.ticketPrice,
+      asset: r.asset,
+      max_tickets: r.maxTickets,
+      tickets_sold: r.ticketsSold,
+      end_time: r.endTime,
+      winner: r.winner,
+      prize_amount: r.prizeAmount,
+      created_ledger: r.createdLedger,
+      finalized_ledger: r.finalizedLedger,
+      metadata_cid: r.metadataCid,
+      created_at: r.createdAt,
+    };
+  }
+}

indexer/src/api/controllers/stats.controller.ts

@@ -0,0 +1,59 @@
+import { Controller, Get, UseGuards } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { Repository } from "typeorm";
+import { CacheService } from "../../cache/cache.service";
+import { PlatformStatEntity } from "../../database/entities/platform-stat.entity";
+import { RaffleEntity, RaffleStatus } from "../../database/entities/raffle.entity";
+import { UserEntity } from "../../database/entities/user.entity";
+import { ApiKeyGuard } from "../api-key.guard";
+
+@UseGuards(ApiKeyGuard)
+@Controller("stats")
+export class StatsController {
+  constructor(
+    @InjectRepository(PlatformStatEntity)
+    private readonly statRepo: Repository<PlatformStatEntity>,
+    @InjectRepository(RaffleEntity)
+    private readonly raffleRepo: Repository<RaffleEntity>,
+    @InjectRepository(UserEntity)
+    private readonly userRepo: Repository<UserEntity>,
+    private readonly cacheService: CacheService,
+  ) {}
+
+  /**
+   * GET /stats/platform
+   * Aggregated platform-wide stats — cache-first (5 min TTL), PostgreSQL fallback.
+   * Merges the latest daily roll-up row with live counts for active raffles.
+   */
+  @Get("platform")
+  async platform() {
+    const cached = await this.cacheService.getPlatformStats();
+    if (cached) return cached;
+
+    // Latest daily roll-up
+    const latest = await this.statRepo
+      .createQueryBuilder("s")
+      .orderBy("s.date", "DESC")
+      .getOne();
+
+    // Live counts that change frequently
+    const [activeRaffles, totalUsers] = await Promise.all([
+      this.raffleRepo.count({ where: { status: RaffleStatus.OPEN } }),
+      this.userRepo.count(),
+    ]);
+
+    const result = {
+      date: latest?.date ?? null,
+      total_raffles: latest?.totalRaffles ?? 0,
+      total_tickets: latest?.totalTickets ?? 0,
+      total_volume_xlm: latest?.totalVolumeXlm ?? "0",
+      unique_participants: latest?.uniqueParticipants ?? 0,
+      prizes_distributed_xlm: latest?.prizesDistributedXlm ?? "0",
+      active_raffles: activeRaffles,
+      total_users: totalUsers,
+    };
+
+    await this.cacheService.setPlatformStats(result);
+    return result;
+  }
+}