refactor(types): centralize API response types

docs/api-client.md

@@ -7,6 +7,55 @@ The shared HTTP client lives in `src/lib/apiClient.ts`.
 Requests are sent to `${getApiBase()}${path}` where `getApiBase()` reads
 `NEXT_PUBLIC_STABLEROUTE_API_BASE` (see `src/lib/config.ts`).
 
+## API Response Types
+
+All API response type definitions are centralized in `src/lib/types.ts` to
+maintain a single source of truth and prevent type drift between pages.
+
+### Available Types
+
+- **`Pair`** — Routing pair response: `{ source, destination }`
+- **`Quote`** — Quote response: `{ source_asset, dest_asset, amount, estimated_rate, route[] }`
+- **`AppEvent`** — Raw event from API: `{ id, ts, type, payload }`
+- **`DisplayEvent`** — Rendered event with serialized payloads: `{ id, ts, type, payloadPreview, fullPayload }`
+- **`ApiKey`** — API key metadata: `{ prefix, label, createdAt }`
+- **`CreateApiKeyResponse`** — API key creation response: `{ key, prefix? }`
+- **`Webhook`** — Webhook subscription: `{ id, url, events[], createdAt }`
+
+### Importing Types
+
+Types are exported directly from `src/lib/types.ts`:
+
+```ts
+import type { Quote, Pair, ApiKey } from '@/lib/types';
+```
+
+For backward compatibility, types are also re-exported from their validation/utility modules:
+
+```ts
+// Both work:
+import type { Quote } from '@/lib/types';
+import type { Quote } from '@/lib/quote';
+
+// Both work:
+import type { AppEvent, DisplayEvent } from '@/lib/types';
+import type { AppEvent, DisplayEvent } from '@/lib/events';
+
+// Both work:
+import type { Pair } from '@/lib/types';
+import { type Pair } from '@/app/pairs/pairsUtils';
+```
+
+### Validation Functions
+
+Validation logic remains in their respective modules:
+
+- `quote.ts` — `isValidAmount()`, `assetsDiffer()`, `normalizeAsset()`
+- `events.ts` — `parseEventsResponse()`, `escapeCsvCell()`, `buildEventsCsv()`
+- `webhookEvents.ts` — `isWebhookEventType()`
+
+These validators continue to use the centralized types, ensuring all validation is type-safe and consistent.
+
 ## Error shape
 
 Failed responses parse JSON bodies matching:

src/app/api-keys/Client.tsx

@@ -10,13 +10,14 @@ import { apiDelete, apiGet, apiPost } from '@/lib/apiClient';
 import { useList } from '@/lib/useList';
 import { writeToClipboard } from '@/lib/clipboard';
 import { useToast } from '@/components/ToastProvider';
-
-type Item = { prefix: string; label: string; createdAt: number };
+import type { ApiKey, CreateApiKeyResponse } from '@/lib/types';
 
 export default function ApiKeysClient() {
   const loadItems = useCallback(
     () =>
-      apiGet<{ items: Item[] }>('/api/v1/api-keys').then((body) => body.items),
+      apiGet<{ items: ApiKey[] }>('/api/v1/api-keys').then(
+        (body) => body.items
+      ),
     []
   );
   const itemsResult = useList(loadItems);
@@ -36,10 +37,9 @@ export default function ApiKeysClient() {
     event.preventDefault();
     setSubmitting(true);
     try {
-      const response = await apiPost<{ key: string; prefix?: string }>(
-        '/api/v1/api-keys',
-        { label }
-      );
+      const response = await apiPost<CreateApiKeyResponse>('/api/v1/api-keys', {
+        label,
+      });
       setCreated(response.key);
       setCopyFailed(false);
       setRecentPrefix(response.prefix ?? response.key.slice(0, 8));

src/app/pairs/Client.tsx

@@ -9,7 +9,8 @@ import { PageHeading } from '@/components/PageHeading';
 import { Spinner } from '@/components/Spinner';
 import { apiDelete } from '@/lib/apiClient';
 import { useApi } from '@/lib/useApi';
-import { filterPairs, groupBySource, type Pair } from './pairsUtils';
+import { filterPairs, groupBySource } from './pairsUtils';
+import { type Pair } from '@/lib/types';
 
 export default function PairsClient() {
   const api = useApi<{ pairs: Pair[] }>('/api/v1/pairs');

src/app/pairs/pairsUtils.ts

@@ -1,4 +1,4 @@
-export type Pair = { source: string; destination: string };
+import type { Pair } from '@/lib/types';
 
 /**
  * Filters pairs whose source or destination contains the query text

src/app/quote/Client.tsx

@@ -5,14 +5,7 @@ import { TextField } from '@/components/TextField';
 import { apiFetch, type ApiError } from '@/lib/apiClient';
 import { formatQuoteAmountDisplay, formatQuoteRateDisplay } from '@/lib/format';
 import { useLocalStorage } from '@/lib/useLocalStorage';
-
-type Quote = {
-  source_asset: string;
-  dest_asset: string;
-  amount: string;
-  estimated_rate: string;
-  route: string[];
-};
+import type { Quote } from '@/lib/types';
 
 type FieldErrors = {
   source?: string;

src/app/webhooks/Client.tsx

@@ -10,8 +10,7 @@ import { TimeAgo } from '@/components/TimeAgo';
 import { apiDelete, apiGet, apiPost } from '@/lib/apiClient';
 import { useList } from '@/lib/useList';
 import { WEBHOOK_EVENT_OPTIONS } from '@/lib/webhookEvents';
-
-type Hook = { id: string; url: string; events: string[]; createdAt: number };
+import type { Webhook } from '@/lib/types';
 
 function isHttpsUrl(value: string): boolean {
   try {
@@ -24,7 +23,9 @@ function isHttpsUrl(value: string): boolean {
 export default function WebhooksClient() {
   const loadHooks = useCallback(
     () =>
-      apiGet<{ items: Hook[] }>('/api/v1/webhooks').then((body) => body.items),
+      apiGet<{ items: Webhook[] }>('/api/v1/webhooks').then(
+        (body) => body.items
+      ),
     []
   );
   const hooks = useList(loadHooks);