refactor: Replace inline types with dedicated named types

Extract inline object types into properly named, reusable types across the
codebase to improve readability and enable safer refactoring.

Shared package:
- PaginationInfo: consolidates pagination fields from EncounterListResponse
  and CollectiveListResponse into packages/shared/src/pagination.ts
- CollectiveTypeSummary: type summary in collective list items
- RelationshipTypeSummary: relationship type metadata in preview items
- FriendPreview: friend object within upcoming dates
- CircleReorderItem: extracted from inline CircleReorderSchema

Auth types:
- UserWithPreferencesResponse: GET /api/auth/me response
- PreferencesResponse: PATCH /api/auth/preferences response
- ForgotPasswordResponse: POST /api/auth/forgot-password response
- HealthCheckResponse: GET /api/health response

Frontend:
- UpcomingDatesOptions: parameters for upcoming dates queries
- Replace duplicate PaginationState interfaces in encounters and
  collectives stores with shared PaginationInfo

Backend:
- Update auth routes to use shared response types
- Update health route to use HealthCheckResponse

Closes #126

https://claude.ai/code/session_01Ggmu9YzZBUq3ETBuiyXcXV

Author: claude

apps/backend/src/routes/auth.ts

@@ -1,13 +1,14 @@
 import {
   type AuthResponse,
   ForgotPasswordRequestSchema,
+  type ForgotPasswordResponse,
   LoginRequestSchema,
+  type PreferencesResponse,
   RefreshRequestSchema,
   RegisterRequestSchema,
   ResetPasswordRequestSchema,
   UpdatePreferencesRequestSchema,
-  type User,
-  type UserPreferences,
+  type UserWithPreferencesResponse,
 } from '@freundebuch/shared/index.js';
 import { type } from 'arktype';
 import { Hono } from 'hono';
@@ -229,7 +230,7 @@ app.post('/forgot-password', passwordResetRateLimitMiddleware, async (c) => {
   // Always return success to prevent user enumeration
   // Only include resetToken in non-production environments for testing
   const config = getConfig();
-  const response: { message: string; resetToken?: string } = {
+  const response: ForgotPasswordResponse = {
     message: 'If the email exists, a password reset link has been sent',
   };
 
@@ -285,7 +286,7 @@ app.get('/me', authMiddleware, async (c) => {
     throw new UserNotFoundError();
   }
 
-  const response: { user: User; preferences: UserPreferences } = {
+  const response: UserWithPreferencesResponse = {
     user: {
       externalId: userWithPrefs.externalId,
       email: userWithPrefs.email,
@@ -326,7 +327,7 @@ app.patch('/preferences', authMiddleware, async (c) => {
 
   logger.info({ userId: authUser.userId }, 'User preferences updated');
 
-  return c.json<{ preferences: UserPreferences }>({ preferences: updatedPreferences });
+  return c.json<PreferencesResponse>({ preferences: updatedPreferences });
 });
 
 export default app;

apps/backend/src/routes/health.ts

@@ -1,3 +1,4 @@
+import type { HealthCheckResponse } from '@freundebuch/shared/index.js';
 import { Hono } from 'hono';
 import type { AppContext } from '../types/context.js';
 import { toError } from '../utils/errors.js';
@@ -21,7 +22,7 @@ health.get('/', async (c) => {
     client.release();
   }
 
-  const health = {
+  const health: HealthCheckResponse = {
     status: dbHealthy ? 'healthy' : 'unhealthy',
     timestamp: new Date().toISOString(),
     uptime: process.uptime(),

apps/frontend/src/lib/api/friends.ts

@@ -325,13 +325,16 @@ export async function deleteDate(friendId: string, dateId: string): Promise<{ me
   });
 }
 
+/** Options for upcoming dates query */
+export interface UpcomingDatesOptions {
+  days?: number;
+  limit?: number;
+}
+
 /**
  * Get upcoming important dates across all friends
  */
-export async function getUpcomingDates(options?: {
-  days?: number;
-  limit?: number;
-}): Promise<UpcomingDate[]> {
+export async function getUpcomingDates(options?: UpcomingDatesOptions): Promise<UpcomingDate[]> {
   const searchParams = new URLSearchParams();
   if (options?.days) searchParams.set('days', options.days.toString());
   if (options?.limit) searchParams.set('limit', options.limit.toString());

apps/frontend/src/lib/stores/collectives.ts

@@ -8,6 +8,7 @@ import type {
   MembershipDeactivate,
   MembershipInput,
   MembershipUpdate,
+  PaginationInfo,
   RelationshipPreviewRequest,
   RelationshipPreviewResponse,
 } from '$shared';
@@ -16,13 +17,6 @@ import type { CollectiveListParams } from '../api/collectives.js';
 import * as collectivesApi from '../api/collectives.js';
 import { storeAction } from './storeAction.js';
 
-interface PaginationState {
-  page: number;
-  pageSize: number;
-  totalCount: number;
-  totalPages: number;
-}
-
 interface FilterState {
   typeId?: string;
   search?: string;
@@ -33,7 +27,7 @@ interface CollectivesState {
   collectives: CollectiveListItem[];
   currentCollective: Collective | null;
   collectiveTypes: CollectiveType[];
-  pagination: PaginationState;
+  pagination: PaginationInfo;
   filters: FilterState;
   isLoading: boolean;
   isLoadingTypes: boolean;

apps/frontend/src/lib/stores/encounters.ts

@@ -5,18 +5,12 @@ import type {
   EncounterListItem,
   EncounterUpdate,
   LastEncounterSummary,
+  PaginationInfo,
 } from '$shared';
 import type { EncounterListParams } from '../api/encounters.js';
 import * as encountersApi from '../api/encounters.js';
 import { storeAction } from './storeAction.js';
 
-interface PaginationState {
-  page: number;
-  pageSize: number;
-  totalCount: number;
-  totalPages: number;
-}
-
 interface FilterState {
   friendId?: string;
   fromDate?: string;
@@ -27,7 +21,7 @@ interface FilterState {
 interface EncountersState {
   encounters: EncounterListItem[];
   currentEncounter: Encounter | null;
-  pagination: PaginationState;
+  pagination: PaginationInfo;
   filters: FilterState;
   isLoading: boolean;
   error: string | null;

packages/shared/src/auth.ts

@@ -108,6 +108,35 @@ export const ResetPasswordRequestSchema = type({
 
 export type ResetPasswordRequest = typeof ResetPasswordRequestSchema.infer;
 
+// ============================================================================
+// Endpoint Response Types
+// ============================================================================
+
+/** Response from GET /api/auth/me */
+export interface UserWithPreferencesResponse {
+  user: User;
+  preferences: UserPreferences;
+}
+
+/** Response from PATCH /api/auth/preferences */
+export interface PreferencesResponse {
+  preferences: UserPreferences;
+}
+
+/** Response from POST /api/auth/forgot-password */
+export interface ForgotPasswordResponse {
+  message: string;
+  resetToken?: string;
+}
+
+/** Response from GET /api/health */
+export interface HealthCheckResponse {
+  status: 'healthy' | 'unhealthy';
+  timestamp: string;
+  uptime: number;
+  database: 'connected' | 'disconnected';
+}
+
 // Error response
 export interface ErrorResponse {
   error: string;

packages/shared/src/circles.ts

@@ -43,12 +43,16 @@ export const CircleInputSchema = type({
 });
 export type CircleInput = typeof CircleInputSchema.infer;
 
+/** Single item in a circle reorder request */
+export const CircleReorderItemSchema = type({
+  id: 'string > 0', // external_id
+  sort_order: 'number >= 0',
+});
+export type CircleReorderItem = typeof CircleReorderItemSchema.infer;
+
 /** Schema for reordering circles */
 export const CircleReorderSchema = type({
-  circles: type({
-    id: 'string > 0', // external_id
-    sort_order: 'number >= 0',
-  }).array(),
+  circles: CircleReorderItemSchema.array(),
 });
 export type CircleReorderInput = typeof CircleReorderSchema.infer;
 

packages/shared/src/collectives.ts

@@ -1,4 +1,5 @@
 import { type } from 'arktype';
+import type { PaginationInfo } from './pagination.js';
 
 /**
  * Collective types and validation schemas for Epic 12: Collectives
@@ -236,14 +237,17 @@ export interface Collective {
   deletedAt: string | null;
 }
 
+/** Type summary for collective list items */
+export interface CollectiveTypeSummary {
+  id: string;
+  name: string;
+}
+
 /** Collective in list responses (fewer details) */
 export interface CollectiveListItem {
   id: string; // external_id
   name: string;
-  type: {
-    id: string;
-    name: string;
-  };
+  type: CollectiveTypeSummary;
   photoUrl: string | null;
   photoThumbnailUrl: string | null;
   memberCount: number;
@@ -256,23 +260,21 @@ export interface CollectiveListItem {
 /** Paginated collective list response */
 export interface CollectiveListResponse {
   collectives: CollectiveListItem[];
-  pagination: {
-    page: number;
-    pageSize: number;
-    totalCount: number;
-    totalPages: number;
-  };
+  pagination: PaginationInfo;
+}
+
+/** Relationship type summary for preview items */
+export interface RelationshipTypeSummary {
+  id: string;
+  label: string;
+  category: string;
 }
 
 /** Preview of a relationship that will be created */
 export interface RelationshipPreviewItem {
   fromContact: CollectiveMemberContact;
   toContact: CollectiveMemberContact;
-  relationshipType: {
-    id: string;
-    label: string;
-    category: string;
-  };
+  relationshipType: RelationshipTypeSummary;
   alreadyExists: boolean; // If true, this relationship already exists
 }
 

packages/shared/src/encounters.ts

@@ -1,4 +1,5 @@
 import { type } from 'arktype';
+import type { PaginationInfo } from './pagination.js';
 
 /**
  * Encounter types and validation schemas for Epic 2: Encounter Management
@@ -127,12 +128,7 @@ export interface EncounterListItem {
 /** Paginated encounter list response */
 export interface EncounterListResponse {
   encounters: EncounterListItem[];
-  pagination: {
-    page: number;
-    pageSize: number;
-    totalCount: number;
-    totalPages: number;
-  };
+  pagination: PaginationInfo;
 }
 
 /** Last encounter summary for friend detail page */

packages/shared/src/friends.ts

@@ -366,6 +366,13 @@ export interface FriendDate {
   createdAt: string;
 }
 
+/** Friend preview for embedding in dashboard and summary views */
+export interface FriendPreview {
+  id: string;
+  displayName: string;
+  photoThumbnailUrl?: string;
+}
+
 /** Upcoming date with friend info for dashboard */
 export interface UpcomingDate {
   id: string;
@@ -374,11 +381,7 @@ export interface UpcomingDate {
   dateType: DateType;
   label?: string;
   daysUntil: number;
-  friend: {
-    id: string;
-    displayName: string;
-    photoThumbnailUrl?: string;
-  };
+  friend: FriendPreview;
 }
 
 /** Met information in API responses */