// Current approach
let schools = try await supabase
    .from("schools")
    .select("*")
    .order("match_score", ascending: false)
    .limit(20)
    .execute()

// Future API approach
let recommendations = try await api.getRecommendations(
    compressed: true,
    includeImages: .thumbnail
)

// Sync local changes when online
let syncResult = try await api.syncOfflineActions(
    swipes: localSwipes,
    messages: localDrafts
)

// Get everything needed for home screen in one call
let homeData = try await api.getHomeScreen()
// Returns: recommendations, unread messages, new matches, etc.

POST /student/auth/apple
POST /student/auth/google
POST /student/auth/refresh
GET  /student/profile
POST /student/profile
PATCH /student/profile
POST /student/profile/avatar

GET  /student/recommendations
POST /student/swipe
GET  /student/schools/:id
POST /student/schools/:id/save
GET  /student/matches
GET  /student/match/:schoolId/details

GET  /student/conversations
GET  /student/conversations/:id
POST /student/messages
PATCH /student/messages/:id/read
GET  /student/notifications

GET  /student/friends
POST /student/friends/add
POST /student/friends/share-profile
GET  /student/friends/:id/schools
POST /student/compare-schools

GET  /student/scholarships
GET  /student/scholarships/saved
POST /student/scholarships/:id/save
GET  /student/scholarships/:id

// Full response
interface School {
  id: string;
  name: string;
  location: { city: string; state: string; };
  stats: { /* 20+ fields */ };
  images: string[];
}

// Compressed for lists
interface SchoolCompressed {
  i: string;    // id
  n: string;    // name
  l: string;    // location "City, ST"
  m: number;    // matchScore
  img: string;  // thumbnail
}

// Initial load - minimal data
GET /student/recommendations?fields=minimal

// User shows interest - load details
GET /student/schools/:id?fields=full

// Background sync - preload next batch
GET /student/recommendations/preload

// Immediate response with pending status
POST /student/swipe
Response: { status: 'pending', tempId: 'tmp_123' }

// Confirm via websocket or polling
WS: { event: 'swipe.confirmed', tempId: 'tmp_123', id: 'swipe_456' }

// Cache headers for different resources
interface CachePolicy {
  schools: 'max-age=3600',           // 1 hour
  profile: 'max-age=300',            // 5 minutes  
  recommendations: 'private, max-age=1800', // 30 minutes
  messages: 'no-cache'               // Always fresh
}

// Batch multiple operations
POST /student/batch
{
  operations: [
    { method: 'POST', path: '/swipe', body: {...} },
    { method: 'GET', path: '/recommendations' },
    { method: 'PATCH', path: '/messages/123/read' }
  ]
}

// Only get changes since last sync
GET /student/sync?since=2024-01-15T10:00:00Z
Response: {
  newMessages: [...],
  updatedSchools: [...],
  deletedItems: [...]
}

// Register for notifications
POST /student/devices
{
  token: "APNS_TOKEN",
  platform: "ios",
  preferences: {
    messages: true,
    matches: true,
    reminders: true
  }
}

// Notification payload
{
  aps: {
    alert: "MIT liked you back! 🎉",
    badge: 1,
    sound: "match.caf"
  },
  findu: {
    type: "match",
    schoolId: "mit_123",
    deepLink: "findu://school/mit_123"
  }
}

// Clean SDK interface
class FindUAPI {
    func getRecommendations() async throws -> [School]
    func recordSwipe(_ direction: SwipeDirection, for school: School) async throws
    func sendMessage(_ text: String, to conversation: Conversation) async throws
}

// With offline support
class FindUOfflineAPI: FindUAPI {
    private let cache: CacheManager
    private let queue: OfflineQueue
    
    override func recordSwipe(...) async throws {
        try queue.enqueue(.swipe(direction, school))
        try await syncIfOnline()
    }
}

enum FindUError: LocalizedError {
    case offline
    case invalidProfile(missing: [String])
    case rateLimited(retryAfter: TimeInterval)
    case schoolNotFound
    
    var errorDescription: String? {
        switch self {
        case .offline:
            return "You're offline. Changes will sync when connected."
        case .invalidProfile(let fields):
            return "Complete your profile: \(fields.joined(separator: ", "))"
        case .rateLimited(let retry):
            return "Too many requests. Try again in \(Int(retry)) seconds."
        case .schoolNotFound:
            return "This school is no longer available."
        }
    }
}