feat(backend): implement raffles REST controller and service (list, get by id)

Closes #108

## What was changed

- Added `raffles.service.spec.ts` with full unit test coverage for
  RafflesService: list(), getById() (merge, partial data, not-found),
  getBatchMetadata(), and upsertMetadata().

- Fixed `zod-validation.pipe.ts`: widened createZodPipe generic from
  `ZodSchema<T>` to `ZodSchema<Output, ZodTypeDef, Input>` so schemas
  that use .transform() (e.g. BatchMetadataQuerySchema) are accepted
  without a type error.

- Installed missing dependencies: `@nestjs/swagger`, `@fastify/helmet`,
  `firebase-admin`; added them to package.json.

- Fixed `main.ts`: cast app to `any` for SwaggerModule calls to resolve
  the NestFastifyApplication / INestApplication type mismatch.

- Fixed `push-notification.service.ts`: replaced removed
  `sendMulticast()` with `sendEachForMulticast()` (firebase-admin v12+
  API), and added explicit types to map/filter callbacks to eliminate
  implicit-any TS errors.

- Fixed `metadata.service.spec.ts`: aligned test with actual
  searchMetadata(query, limit, offset) signature (second arg is a
  number, not a category string).

- Fixed `search.controller.spec.ts`: removed stale tests that called
  controller.search() with the old two-arg signature; fixed unclosed
  describe block (syntax error); kept the correct DTO-based test.

## Why it was needed

The raffles list and detail endpoints (GET /raffles, GET /raffles/:id)
are core to the platform — list for discovery, detail for the raffle
page. The service merges contract state from the indexer with off-chain
metadata from Supabase. The controller, service, DTOs, Zod schemas, and
module registration were already scaffolded; this PR completes the work
by adding the service test suite and fixing all build/test blockers that
prevented CI from passing.

## Assumptions

- The existing controller/service/module structure is the intended
  implementation; no structural changes were needed.
- Pre-existing build errors in main.ts and bootstrap.ts (missing deps,
  type mismatches) were blocking the build and are fixed here as they
  are in the same package scope.

Author: abdegenius

backend/package.json

@@ -13,20 +13,23 @@
     "test:e2e": "jest --config ./test/jest-e2e.json"
   },
   "dependencies": {
+    "@fastify/helmet": "^13.0.2",
     "@fastify/multipart": "^9.0.0",
     "@nestjs/common": "^10.4.0",
     "@nestjs/config": "^4.0.3",
     "@nestjs/core": "^10.4.0",
     "@nestjs/jwt": "^10.2.0",
     "@nestjs/passport": "^10.0.3",
     "@nestjs/platform-fastify": "^11.1.17",
+    "@nestjs/swagger": "^11.4.1",
     "@nestjs/throttler": "^6.4.0",
     "@nestjs/typeorm": "^11.0.0",
     "@stellar/stellar-sdk": "^14.4.0",
     "@supabase/supabase-js": "^2.45.0",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.15.1",
     "fastify": "^5.0.0",
+    "firebase-admin": "^13.8.0",
     "passport": "^0.7.0",
     "passport-jwt": "^4.0.1",
     "pg": "^8.18.0",

backend/src/api/rest/raffles/pipes/zod-validation.pipe.ts

@@ -3,7 +3,7 @@ import {
   ArgumentMetadata,
   BadRequestException,
 } from "@nestjs/common";
-import { ZodSchema, ZodError } from "zod";
+import { ZodSchema, ZodTypeDef, ZodError } from "zod";
 
 /**
  * Creates a validation pipe using a Zod schema.
@@ -27,9 +27,9 @@ import { ZodSchema, ZodError } from "zod";
  * @returns PipeTransform class that validates and transforms data
  * @throws BadRequestException when validation fails
  */
-export function createZodPipe<T>(schema: ZodSchema<T>) {
+export function createZodPipe<Output, Input = Output>(schema: ZodSchema<Output, ZodTypeDef, Input>) {
   return class implements PipeTransform {
-    transform(value: unknown, _metadata: ArgumentMetadata): T {
+    transform(value: unknown, _metadata: ArgumentMetadata): Output {
       const result = schema.safeParse(value);
       if (!result.success) {
         const msg = result.error.errors.map((e) => e.message).join("; ");

backend/src/api/rest/raffles/raffles.service.spec.ts

@@ -0,0 +1,164 @@
+import { NotFoundException } from '@nestjs/common';
+import { RafflesService } from './raffles.service';
+import { IndexerService, IndexerRaffleData } from '../../../services/indexer.service';
+import { MetadataService, RaffleMetadata } from '../../../services/metadata.service';
+
+const mockRaffle: IndexerRaffleData = {
+  id: 1,
+  creator: 'GABC123',
+  status: 'open',
+  ticket_price: '10',
+  asset: 'XLM',
+  max_tickets: 100,
+  tickets_sold: 5,
+  end_time: '2026-12-31T00:00:00Z',
+  winner: null,
+  prize_amount: null,
+  created_ledger: 1000,
+  finalized_ledger: null,
+  metadata_cid: null,
+  created_at: '2026-01-01T00:00:00Z',
+};
+
+const mockMetadata: RaffleMetadata = {
+  raffle_id: 1,
+  title: 'Test Raffle',
+  description: 'A test raffle',
+  image_url: 'https://example.com/img.png',
+  category: 'art',
+  metadata_cid: 'ipfs://abc',
+  created_at: '2026-01-01T00:00:00Z',
+  updated_at: '2026-01-01T00:00:00Z',
+};
+
+describe('RafflesService', () => {
+  let service: RafflesService;
+  let indexerService: jest.Mocked<Pick<IndexerService, 'listRaffles' | 'getRaffle'>>;
+  let metadataService: jest.Mocked<Pick<MetadataService, 'getMetadata' | 'getBatchMetadata' | 'upsertMetadata'>>;
+
+  beforeEach(() => {
+    indexerService = {
+      listRaffles: jest.fn().mockResolvedValue({ raffles: [], total: 0 }),
+      getRaffle: jest.fn().mockResolvedValue(null),
+    };
+    metadataService = {
+      getMetadata: jest.fn().mockResolvedValue(null),
+      getBatchMetadata: jest.fn().mockResolvedValue(new Map()),
+      upsertMetadata: jest.fn(),
+    };
+
+    service = new RafflesService(
+      metadataService as unknown as MetadataService,
+      indexerService as unknown as IndexerService,
+    );
+  });
+
+  describe('list', () => {
+    it('delegates to indexerService.listRaffles with filters', async () => {
+      const filters = { status: 'open', limit: 10, offset: 0 };
+      indexerService.listRaffles.mockResolvedValue({ raffles: [mockRaffle], total: 1 });
+
+      const result = await service.list(filters);
+
+      expect(indexerService.listRaffles).toHaveBeenCalledWith(filters);
+      expect(result).toEqual({ raffles: [mockRaffle], total: 1 });
+    });
+
+    it('calls listRaffles with empty filters by default', async () => {
+      await service.list();
+
+      expect(indexerService.listRaffles).toHaveBeenCalledWith({});
+    });
+  });
+
+  describe('getById', () => {
+    it('merges indexer data and metadata into a single response', async () => {
+      indexerService.getRaffle.mockResolvedValue(mockRaffle);
+      metadataService.getMetadata.mockResolvedValue(mockMetadata);
+
+      const result = await service.getById(1);
+
+      expect(result).toMatchObject({
+        id: 1,
+        creator: 'GABC123',
+        status: 'open',
+        title: 'Test Raffle',
+        description: 'A test raffle',
+        image_url: 'https://example.com/img.png',
+        category: 'art',
+        metadata_cid: 'ipfs://abc',
+      });
+    });
+
+    it('returns indexer data when metadata is absent', async () => {
+      indexerService.getRaffle.mockResolvedValue(mockRaffle);
+      metadataService.getMetadata.mockResolvedValue(null);
+
+      const result = await service.getById(1);
+
+      expect(result.id).toBe(1);
+      expect(result.creator).toBe('GABC123');
+      expect(result.title).toBeUndefined();
+    });
+
+    it('returns metadata when indexer data is absent', async () => {
+      indexerService.getRaffle.mockResolvedValue(null);
+      metadataService.getMetadata.mockResolvedValue(mockMetadata);
+
+      const result = await service.getById(1);
+
+      expect(result.id).toBe(1);
+      expect(result.title).toBe('Test Raffle');
+      expect(result.creator).toBeUndefined();
+    });
+
+    it('throws NotFoundException when both indexer and metadata return null', async () => {
+      indexerService.getRaffle.mockResolvedValue(null);
+      metadataService.getMetadata.mockResolvedValue(null);
+
+      await expect(service.getById(99)).rejects.toThrow(NotFoundException);
+    });
+
+    it('prefers metadata_cid from contract when both sources have it', async () => {
+      const raffleWithCid = { ...mockRaffle, metadata_cid: 'ipfs://contract-cid' };
+      indexerService.getRaffle.mockResolvedValue(raffleWithCid);
+      metadataService.getMetadata.mockResolvedValue(mockMetadata);
+
+      const result = await service.getById(1);
+
+      expect(result.metadata_cid).toBe('ipfs://contract-cid');
+    });
+
+    it('falls back to metadata_cid from Supabase when contract has none', async () => {
+      indexerService.getRaffle.mockResolvedValue(mockRaffle); // metadata_cid: null
+      metadataService.getMetadata.mockResolvedValue(mockMetadata);
+
+      const result = await service.getById(1);
+
+      expect(result.metadata_cid).toBe('ipfs://abc');
+    });
+  });
+
+  describe('getBatchMetadata', () => {
+    it('returns array of metadata from the map', async () => {
+      const map = new Map([[1, mockMetadata]]);
+      metadataService.getBatchMetadata.mockResolvedValue(map);
+
+      const result = await service.getBatchMetadata([1]);
+
+      expect(result).toEqual([mockMetadata]);
+      expect(metadataService.getBatchMetadata).toHaveBeenCalledWith([1]);
+    });
+  });
+
+  describe('upsertMetadata', () => {
+    it('delegates to metadataService.upsertMetadata', async () => {
+      const payload = { title: 'New Title' };
+      metadataService.upsertMetadata.mockResolvedValue({ ...mockMetadata, title: 'New Title' });
+
+      await service.upsertMetadata(1, payload);
+
+      expect(metadataService.upsertMetadata).toHaveBeenCalledWith(1, payload);
+    });
+  });
+});

backend/src/api/rest/search/search.controller.spec.ts

@@ -2,34 +2,7 @@ import { SearchController } from './search.controller';
 import { SearchService } from '../../../services/search.service';
 
 describe('SearchController', () => {
-  let controller: SearchController;
-  let searchService: { search: jest.Mock };
-
-  beforeEach(() => {
-    searchService = {
-      search: jest.fn(),
-    };
-
-    controller = new SearchController(searchService as unknown as SearchService);
-  });
-
-  it('passes a trimmed category filter to the search service', async () => {
-    searchService.search.mockResolvedValue([]);
-
-    await controller.search('raffle', '  Art  ');
-
-    expect(searchService.search).toHaveBeenCalledWith('raffle', 'Art');
-  });
-
-  it('treats an empty category as no filter', async () => {
-    searchService.search.mockResolvedValue([]);
-
-    await controller.search('raffle', '   ');
-
-    expect(searchService.search).toHaveBeenCalledWith('raffle', undefined);
-
-describe('SearchController', () => {
-  it('forwards q, limit, and offset and returns the service total', async () => {
+  it('forwards q, limit, and offset and returns the service result', async () => {
     const searchService = {
       search: jest.fn().mockResolvedValue({
         raffles: [
@@ -45,7 +18,7 @@ describe('SearchController', () => {
       }),
     };
 
-    const controller = new SearchController(searchService as any);
+    const controller = new SearchController(searchService as unknown as SearchService);
 
     await expect(
       (controller as any).search({ q: 'rare', limit: 1, offset: 5 }),
@@ -64,4 +37,15 @@ describe('SearchController', () => {
 
     expect(searchService.search).toHaveBeenCalledWith('rare', 1, 5);
   });
+
+  it('returns empty result when query is too short', async () => {
+    const searchService = { search: jest.fn() };
+    const controller = new SearchController(searchService as unknown as SearchService);
+
+    await expect(
+      (controller as any).search({ q: 'a' }),
+    ).resolves.toEqual({ raffles: [], total: 0 });
+
+    expect(searchService.search).not.toHaveBeenCalled();
+  });
 });

backend/src/main.ts

@@ -25,8 +25,8 @@ async function bootstrap() {
     .addBearerAuth()
     .build();
 
-  const document = SwaggerModule.createDocument(app, config);
-  SwaggerModule.setup("docs", app, document);
+  const document = SwaggerModule.createDocument(app as any, config);
+  SwaggerModule.setup("docs", app as any, document);
   await configureSecurity(app);
 
   // Using 'as any' bypasses the type mismatch error between Fastify versions

backend/src/services/metadata.service.spec.ts

@@ -1,24 +1,27 @@
 import { MetadataService } from './metadata.service';
-import { SUPABASE_CLIENT } from './supabase.provider';
 
 describe('MetadataService', () => {
   let service: MetadataService;
   let queryBuilder: {
     select: jest.Mock;
     or: jest.Mock;
-    ilike: jest.Mock;
-    limit: jest.Mock;
+    range: jest.Mock;
+    eq: jest.Mock;
+    maybeSingle: jest.Mock;
     upsert: jest.Mock;
+    in: jest.Mock;
   };
   let client: { from: jest.Mock };
 
   beforeEach(() => {
     queryBuilder = {
       select: jest.fn().mockReturnThis(),
       or: jest.fn().mockReturnThis(),
-      ilike: jest.fn().mockReturnThis(),
-      limit: jest.fn(),
+      range: jest.fn().mockResolvedValue({ data: [], error: null, count: 0 }),
+      eq: jest.fn().mockReturnThis(),
+      maybeSingle: jest.fn().mockResolvedValue({ data: null, error: null }),
       upsert: jest.fn(),
+      in: jest.fn().mockReturnThis(),
     };
 
     client = {
@@ -28,12 +31,12 @@ describe('MetadataService', () => {
     service = new MetadataService(client as any);
   });
 
-  it('applies category filtering case-insensitively', async () => {
-    queryBuilder.limit.mockResolvedValue({ data: [], error: null });
+  it('searches metadata with ilike pattern', async () => {
+    await service.searchMetadata('raffle');
 
-    await service.searchMetadata('raffle', 'Art');
-
-    expect(queryBuilder.ilike).toHaveBeenCalledWith('category', 'Art');
+    expect(queryBuilder.or).toHaveBeenCalledWith(
+      expect.stringContaining('%raffle%'),
+    );
   });
 
   it('trims category values before upserting metadata', async () => {

backend/src/services/push-notification.service.ts

@@ -155,22 +155,22 @@ export class PushNotificationService {
       data: this.mapData(payload.data),
     };
 
-    let response;
+    let response: admin.messaging.BatchResponse;
     try {
-      response = await admin.messaging().sendMulticast(message);
+      response = await admin.messaging().sendEachForMulticast(message);
     } catch (error) {
-      this.logger.error('FCM sendMulticast failed', error);
+      this.logger.error('FCM sendEachForMulticast failed', error);
       throw new InternalServerErrorException('Failed to send push notification');
     }
 
     const invalidTokens = response.responses
-      .map((r, idx) => ({ result: r, token: tokens[idx] }))
-      .filter((entry) => !entry.result.success)
-      .filter((entry) => {
-        const code = (entry.result.error as any)?.code;
+      .map((r: admin.messaging.SendResponse, idx: number) => ({ result: r, token: tokens[idx] }))
+      .filter((entry: { result: admin.messaging.SendResponse; token: string }) => !entry.result.success)
+      .filter((entry: { result: admin.messaging.SendResponse; token: string }) => {
+        const code = (entry.result.error as admin.FirebaseError | undefined)?.code;
         return code === 'messaging/registration-token-not-registered' || code === 'messaging/invalid-registration-token';
       })
-      .map((entry) => entry.token);
+      .map((entry: { result: admin.messaging.SendResponse; token: string }) => entry.token);
 
     if (invalidTokens.length > 0) {
       await this.client