dev → uat: GRO-2153 abstracted geocoding service #168

Merged

Flea Flicker merged 3 commits from dev-to-uat-gro-2153 into uat 2026-06-08 10:51:18 +00:00

Conversation 1 Commits 3 Files Changed 2

+732

Flea Flicker commented 2026-06-08 10:03:14 +00:00

Member

Copy Link

Copy Source

Promotion: dev → uat — GRO-2153 geocoding service

Promotes the abstracted geocoding service layer (GRO-2153) from dev to uat for QA. Merged to dev as #167; this train carries only the geocoding work (GRO-2187 + GRO-2152 already promoted via #166).

Delivered (exactly the GRO-2153 spec)

• GeocodingProvider interface + GeocodeResult type
• NominatimGeocodingProvider — internal RateLimiter enforces the 1 req/sec Nominatim policy
• GoogleGeocodingProvider — optional fallback, keyed by encrypted businessSettings.googleMapsApiKey (decryptSecret) / GOOGLE_MAPS_API_KEY env
• resolveGeocodingProvider() — selects on businessSettings.routeOptimizationProvider, safe Nominatim fallback
• geocodeBatch() — throttled batch utility with per-item error capture + progress callback
• 20 unit tests (src/__tests__/geocoding.test.ts) — both providers, selection, throttle spacing, batch

Files: src/services/geocoding.ts, src/__tests__/geocoding.test.ts.

QA focus

• Pure internal service layer — no HTTP routes and no user-facing behaviour yet (geocoding endpoints land in GRO-2154). No UAT_PLAYBOOK.md change required this PR.
• Verify CI pull_request Lint/Typecheck + Test are green; confirm the geocoding unit suite runs.

Local verification (from #167)

tsc --noEmit ✓ · eslint (new files) ✓ · pnpm build ✓ · full vitest run → 602 passed.

## Promotion: dev → uat — GRO-2153 geocoding service Promotes the abstracted geocoding service layer ([GRO-2153](/GRO/issues/GRO-2153)) from `dev` to `uat` for QA. Merged to `dev` as #167; this train carries only the geocoding work (GRO-2187 + GRO-2152 already promoted via #166). ### Delivered (exactly the GRO-2153 spec) - `GeocodingProvider` interface + `GeocodeResult` type - `NominatimGeocodingProvider` — internal `RateLimiter` enforces the **1 req/sec** Nominatim policy - `GoogleGeocodingProvider` — optional fallback, keyed by encrypted `businessSettings.googleMapsApiKey` (`decryptSecret`) / `GOOGLE_MAPS_API_KEY` env - `resolveGeocodingProvider()` — selects on `businessSettings.routeOptimizationProvider`, safe Nominatim fallback - `geocodeBatch()` — throttled batch utility with per-item error capture + progress callback - 20 unit tests (`src/__tests__/geocoding.test.ts`) — both providers, selection, throttle spacing, batch Files: `src/services/geocoding.ts`, `src/__tests__/geocoding.test.ts`. ### QA focus - Pure internal service layer — **no HTTP routes** and **no user-facing behaviour** yet (geocoding endpoints land in [GRO-2154](/GRO/issues/GRO-2154)). No `UAT_PLAYBOOK.md` change required this PR. - Verify CI `pull_request` Lint/Typecheck + Test are green; confirm the geocoding unit suite runs. ### Local verification (from #167) `tsc --noEmit` ✓ · `eslint` (new files) ✓ · `pnpm build` ✓ · full `vitest run` → 602 passed.

Flea Flicker added 3 commits 2026-06-08 10:03:15 +00:00

feat(GRO-2153): abstracted geocoding service (Nominatim + Google) ... 2fa6e3d87b

Phase 1.2 of Route Optimization. Adds a provider-agnostic geocoding
service layer in the deployed src/ tree:

- GeocodingProvider interface + GeocodeResult type
- NominatimGeocodingProvider (default, free, self-hostable) with an
  internal rate limiter enforcing the 1 req/sec Nominatim usage policy
- GoogleGeocodingProvider (optional fallback) keyed by the encrypted
  businessSettings.googleMapsApiKey (decrypted via decryptSecret) or
  GOOGLE_MAPS_API_KEY env fallback
- resolveGeocodingProvider() selecting on businessSettings.routeOptimizationProvider,
  with safe fallback to Nominatim when google is configured but no usable key
- geocodeBatch() throttled batch utility (honors provider rate limit,
  captures per-item errors, optional progress callback)
- 20 unit tests covering both providers, selection, throttle spacing, and batch

Co-Authored-By: Paperclip <noreply@paperclip.ing>

ci: retrigger build (registry layer-pull hang on prior run) ... 21fb1b30d2

Co-Authored-By: Paperclip <noreply@paperclip.ing>

Merge pull request 'feat(GRO-2153): abstracted geocoding service (Nominatim + Google)' (#167) from feat/gro-2153-geocoding-service-dev into dev 04b235c861

Lint Roller approved these changes 2026-06-08 10:12:40 +00:00

Lint Roller left a comment

Member

Copy Link

Copy Source

QA approved. All pull_request CI checks pass (Lint/Typecheck, Test 20/20, Build). Code reviewed: provider interface, RateLimiter, both concrete providers, resolveGeocodingProvider, geocodeBatch — implementation is correct and tests are thorough. No user-facing behaviour / no UAT_PLAYBOOK.md change required.

QA approved. All pull_request CI checks pass (Lint/Typecheck, Test 20/20, Build). Code reviewed: provider interface, RateLimiter, both concrete providers, resolveGeocodingProvider, geocodeBatch — implementation is correct and tests are thorough. No user-facing behaviour / no UAT_PLAYBOOK.md change required.

Flea Flicker merged commit 027e012a58 into uat 2026-06-08 10:51:18 +00:00

Sign in to join this conversation.

Reviewers

No Reviewers

Lint Roller

Labels

Clear labels

bug

Something isn't working

documentation

Improvements or additions to documentation

duplicate

This issue or pull request already exists

enhancement

New feature or request

good first issue

Good for newcomers

help wanted

Extra attention is needed

invalid

This doesn't seem right

question

Further information is requested

wontfix

This will not be worked on

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

ai-review (AI Review) gb_barkley (Barkley Trimsworth) cpfarhood (Chris Farhood) ci (Continuous Integration [bot]) gb_flea (Flea Flicker) flux (Flux CD) admin (Gitea Admin) gb_lint (Lint Roller) renovate (Mend Renovate) gb_pawla (Pawla Abdul) gb_scrubs (Scrubs McBarkley) gb_shedward (Shedward Scissorhands) gb_dogfather (The Dogfather)

No Assignees

2 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: groombook/api#168