feat(api): reverse-geocode endpoint for the map picker

GET /geocode/reverse?lat&lng -> { label } via the TomTom provider's reverseGeocode
(already existed, just needed a route). Any-authenticated, throttled 30/min
(billed TomTom call), validates coords -> 400. api-client.reverseGeocode(). Backs
the "drop a pin -> show its address" map picker. 26 geocode tests; curl-verified.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Banyel3

apps/api/src/common/route-roles.spec.ts

@@ -93,6 +93,7 @@ describe('route role matrix', () => {
   it('geocode is any-authenticated (non-sensitive utility, no @Roles)', () => {
     expect(rolesOf(GeocodeController.prototype, 'geocode')).toBeUndefined();
     expect(rolesOf(GeocodeController.prototype, 'search')).toBeUndefined();
+    expect(rolesOf(GeocodeController.prototype, 'reverse')).toBeUndefined();
   });
 
   it('the shops catalog is any-authenticated (non-sensitive, no @Roles)', () => {

apps/api/src/maps/geocode.controller.spec.ts

@@ -16,7 +16,7 @@ describe('GeocodeController', () => {
       name: 'stub',
       geocode: jest.fn().mockResolvedValue(result),
       search: jest.fn().mockResolvedValue([result]),
-      reverseGeocode: jest.fn(),
+      reverseGeocode: jest.fn().mockResolvedValue('Tetuan, Zamboanga City'),
       route: jest.fn(),
     };
     ctrl = new GeocodeController(maps);
@@ -57,4 +57,16 @@ describe('GeocodeController', () => {
       expect(maps.search).toHaveBeenNthCalledWith(2, 'Tetuan', 5);
     });
   });
+
+  describe('reverse', () => {
+    it('reverse-geocodes a valid point to a label', async () => {
+      const out = await ctrl.reverse('6.92', '122.08');
+      expect(maps.reverseGeocode).toHaveBeenCalledWith({ lat: 6.92, lng: 122.08 });
+      expect(out).toEqual({ label: 'Tetuan, Zamboanga City' });
+    });
+
+    it('rejects non-numeric coordinates', async () => {
+      await expect(ctrl.reverse('x', '122')).rejects.toBeInstanceOf(BadRequestException);
+    });
+  });
 });

apps/api/src/maps/geocode.controller.ts

@@ -10,6 +10,7 @@ import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
 import { Throttle } from '@nestjs/throttler';
 import type { GeocodeResult, MapsProvider } from '@wash-and-go/maps';
 import { RolesGuard } from '../common/guards/roles.guard';
+import { parseFiniteNumber } from '../common/parse-num';
 import { MAPS_PROVIDER } from './maps.constants';
 
 /*
@@ -53,4 +54,20 @@ export class GeocodeController {
     const n = Number(limit);
     return this.maps.search(query, Number.isFinite(n) && n > 0 ? n : 5);
   }
+
+  // Coordinates → a human-readable address for the map picker (label the pin the
+  // user dropped). Billed TomTom call → throttled. { label: null } when unknown.
+  @Throttle({ default: { limit: 30, ttl: 60_000 } })
+  @Get('reverse')
+  @ApiOperation({ summary: 'Reverse geocode a pinned point → address label' })
+  async reverse(
+    @Query('lat') lat: string,
+    @Query('lng') lng: string,
+  ): Promise<{ label: string | null }> {
+    const point = {
+      lat: parseFiniteNumber(lat, 'lat'),
+      lng: parseFiniteNumber(lng, 'lng'),
+    };
+    return { label: await this.maps.reverseGeocode(point) };
+  }
 }

packages/api-client/src/client.ts

@@ -322,6 +322,11 @@ export class ApiClient {
     );
   }
 
+  // Coordinates → address label (map picker: label the dropped pin).
+  reverseGeocode(lat: number, lng: number): Promise<{ label: string | null }> {
+    return this.request('GET', `/geocode/reverse?lat=${lat}&lng=${lng}`);
+  }
+
   // --- Admin: rider cash reconciliation ---
 
   getRiderCashSummary(): Promise<RiderCashBalance[]> {