External APIs & Services — Index

Status: Reference

Status: Active

This index lists every third-party service TwoMore integrates with. Each entry links to a dedicated guide covering credentials, quotas, cost, error handling, and hex-arch wiring.

---

Services

Service	Role	Status	Guide
Supabase	Backend (DB, Auth, Storage, Realtime)	Active	api-supabase.md
Authentication (Kakao, Google, Apple)	OAuth via Supabase Auth	Active	authentication.md
Naver Local Search (API Hub)	Venue identity — discovery + private-court ingest	Active	api-naver-search.md
Kakao Local	Venue identity + phone (ingest corroboration)	Active	uses KAKAO_REST_API_KEY · dapi.kakao.com/v2/local
Naver Maps	Deep links to map app	Active	api-naver-maps.md
Expo Push Notifications	Member/event alerts	Active	api-expo-notifications.md
Sentry	Crash reporting + sourcemap symbolication	Active	credentials.md

---

Environment variables

All credentials live in .env.local (gitignored). Never commit this file. Copy .env.example to .env.local and fill in values from each service's console.

For the complete variable reference — including EAS visibility levels, build-time vs runtime distinction, and rotation procedures — see credentials.md.

---

Adding a new external service

1. Port → src/ports/services/{name}.service.port.ts — TypeScript interface only, zero framework imports
2. Adapter → packages/app/src/adapters/{vendor}/{name}.{vendor}.ts — reads credentials from process.env
3. Registry → add to Registry interface + wire in registry.ts
4. Env vars → add to .env.local.example and document in the service's guide
5. Docs → create docs/guides/api-{name}.md and add a row to this index
6. Tests → use inline jest.fn() / port-shaped stubs in the test file; never recreate a mock adapter directory (test data is seeded in Supabase via supabase/seed.sql)

---

Cross-cutting rules

Failing gracefully

All external calls must return safe defaults on error — never throw to the UI layer.

try {
  return await externalService.call();
} catch (err) {
  console.error('[ServiceName] failed:', err);
  return []; // or null / empty object
}

Rate limit defence

Layer	Mechanism
UI inputs	400ms debounce before triggering calls
Adapter	Return [] on 429/503, never re-throw
TanStack Query	staleTime prevents redundant background refetches
Mock mode	Zero real API calls during development

Korean error messages

Never surface raw API error strings. All user-visible errors go through src/config/i18n/ko.ts.