docs
iOS App

Networking

Core/APIClient.swift — every backend call the app makes.

One enum API, one URLSession, one Envelope<T> { status, data } wrapper matching the backend's ApiResponse<T> exactly.

enum API {
    static func product(barcode: String) async throws -> Product
    static func search(_ q: String, limit: Int) async throws -> [ProductCard]
    static func trending(limit: Int) async throws -> [ProductCard]
    static func alternatives(barcode:, country:, sortBy:, limit:) async throws -> [ProductCard]
    static func needsVerification(limit: Int) async throws -> [Candidate]
    static func verify(barcode: String) async throws -> Product

    static func registerDevice() async throws -> DeviceRegistration   // the only unauthenticated call

    static func profile() async throws -> Profile
    static func updateProfile(country:, dietaryPreferences:, displayName:) async throws -> Profile
    static func stats() async throws -> ContributionStats
    static func subscription() async throws -> Subscription
    static func activatePlus() async throws -> Subscription
    static func cancelPlus() async throws -> Subscription
    static func linkApple(identityToken:, displayName:) async throws -> Profile
    static func unlinkApple() async throws -> Profile
    static func deleteAccount() async throws

    static func submitLabel(_ submission: LabelSubmission) async throws -> OcrResult
}

Every endpoint here corresponds 1:1 to an entry in the API Reference — if you're adding a new backend route, add the matching API case here in the same pass.

Auth

Every call except registerDevice() sends Authorization: Bearer <token>. The token comes from DeviceAuth.shared.token() — an actor, single-flighted so concurrent callers don't trigger two registrations, backed by real Keychain storage (kSecClassGenericPassword, service fun.truelabel.device, kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly). On a 401, the request layer calls DeviceAuth.shared.forget() and retries once with a freshly registered token.

Error mapping

ConditionError
Transport failure (no connection, timeout).offline
401 (after the one retry).unauthorized
404.notFound
429.rateLimited
Other non-2xx.server(code)
Decode failure.invalid

Each case has a user-facing errorDescription — screens show these directly rather than a generic "something went wrong."

Pointing at a different backend

Core/APIEnvironment.swift reads API_BASE_URL from the process environment if set (configure this on the Xcode scheme), otherwise defaults to http://localhost:8080 in debug builds and the production API in release.

On this page