Headless Functionality (iOS)

Headless Functionality (iOS)

Lucra’s headless APIs allow your app to drive contest logic directly using Swift async/await, without presenting Lucra UI flows. This is ideal when you want a fully custom UI but still rely on Lucra’s contest engine, rules, compliance, and backend.

Headless functions live on:

lucraClient.api

---

🎯 When to Use Headless APIs

Use headless mode when:

• You want a custom GYP or SYW lobby

• You want a custom tournament list

• You need to embed contest details in your own UI

• You want to pre-check eligibility before presenting a flow

• You want to combine your navigation with Lucra’s regulation logic

Use Lucra Flows (full screen) for:

• KYC (Verify Identity)

• Onboarding

• Add Funds / Withdraw

• Regulated UI and error-handling flows

---

✅ Requirements

In order to use the headless functionality, Lucra will require the use of the user's Location data. Please be sure to request this permission beforehand for the most seamless experience before invoking any of the headless methods.

🧩 Error Handling Pattern

Most headless calls now use Result types instead of throwing errors. This provides better type safety and clearer error handling:

let result = await lucraClient.api.createRecreationalGame(
    gameTypeId: "DARTS",
    atStake: .init(cashReward: wagerAmount),
    playStyle: .groupVsGroup
)

switch result {
case .success(let matchupId):
    print("Created matchup: \(matchupId)")
case .failure(let error):
    switch error {
    case .user(let userError):
        switch userError {
        case .notInitialized:
            currentFlow = .onboarding
        case .unverified:
            currentFlow = .verifyIdentity
        case .insufficientFunds:
            currentFlow = .addFunds
        case .demographicInformationMissing:
            currentFlow = .demographicCollection
        case .notAllowed:
            print("User not allowed")
        }
    case .location(let locationError):
        switch locationError {
        case .unauthorized:
            // Route user to settings to enable location
            break
        case .unableToDetermineLocation(let error):
            print("Unable to determine location: \(error)")
        case .clError(let clError):
            print("CoreLocation error: \(clError)")
        }
    case .customError(let message):
        print("Custom error: \(message)")
    case .unknown:
        print("Unknown error occurred")
    }
}

For Tournaments, the error handling follows the same pattern with TournamentError:

let result = await lucraClient.api.joinTournament(matchupId: "tournament_123")

switch result {
case .success:
    print("Successfully joined tournament!")
case .failure(let error):
    switch error {
    case .user(let userError):
        switch userError {
        case .notInitialized:
            currentFlow = .onboarding
        case .unverified:
            currentFlow = .verifyIdentity
        case .notAllowed:
            print("User blocked or suspended")
        case .insufficientFunds:
            currentFlow = .addFunds
        case .demographicInformationMissing:
            currentFlow = .demographicCollection
        }
    case .location(let locationError):
        switch locationError {
        case .unauthorized:
            // Route user to settings to enable location
            break
        case .unableToDetermineLocation(let error):
            print("Unable to determine location: \(error)")
        case .clError(let clError):
            print("CoreLocation error: \(clError)")
        }
    case .customError(let message):
        print("Custom error: \(message)")
    case .unknown:
        print("Unknown error occurred")
    }
}

Lucra ensures errors map to the correct flow when needed.

---

🧠 Common Headless Operations

✔️ Shared Methods

// Stream version (for live updates)
let stream = lucraClient.api.matchup(for: "matchup123")

// Single fetch version
let matchupResult = await lucraClient.api.matchup(for: "matchup123")

✔️ Games You Play (GYP)

// Stream version (for live updates)
let stream = lucraClient.api.getRecreationalGamesMatchup(matchupId: "matchup123")

// Single fetch version
let matchupResult = await lucraClient.api.getRecreationalGamesMatchup(matchupId: "matchup123")

// Create game
let createResult = await lucraClient.api.createRecreationalGame(
    gameTypeId: "FOOSBALL",
    atStake: .cash(5),
    playStyle: .versus
)

// Accept versus game
let acceptVersusResult = await lucraClient.api.acceptVersusRecreationalGame(
    matchupId: "matchup123",
    groupId: "team456"
)

// Accept free-for-all game
let acceptFFAResult = await lucraClient.api.acceptFreeForAllRecreationalGame(matchupId: "matchup123")

// Cancel game
let cancelResult = await lucraClient.api.cancelRecreationalGame(matchupId: "matchup123")

✔️ Tournaments

// Get recommended tournaments
let tournamentsResult = await lucraClient.api.getRecommendedTournaments(includeClosed: false, limit: 50)

// Get tournament matchup
let tournamentResult = await lucraClient.api.tournamentsMatchup(for: "tournament789")

// Join tournament
let joinResult = await lucraClient.api.joinTournament(matchupId: "tournamentID", joinCode: nil)

// Submit user score
let scoreResult = await lucraClient.api.submitUserScore(
    42,
    tournamentID: "tournamentID",
    metadata: ["round": "1"],
    isFinal: false
)

---

🔄 Combining Headless + Flows

A common hybrid:

1. Build a custom lobby using headless data

2. When a user taps a matchup:

   • Use Lucra Flow for details

3. When a user creates a matchup:

   • Use headless API to do it inline

4. On API error:

   • Use the Result failure case to extract the error and route to the appropriate flow for validation. e.g.: Handling the .user(.insufficientFunds) case should indicate that the user should be routed to .addFunds.

This gives you the best of both worlds.

---

🛰 Location Errors

Some matchups require location validation:

...
case .failure(let failure):
    switch failure {
        case .location(let error):
            print(error.localizedDescription)
        ...
    }
    ...
}

Ensure your app provides proper location permissions when required.

---

📡 API Call Requirements

To use headless APIs correctly:

• User must be onboarded

• User must be verified for monetary matchups

• User must have funds for at-stake matchups

• User must be in an allowed jurisdiction

Lucra will enforce all compliance rules automatically.

---

📊 Recommended App Architecture

1. A shared LucraClient instance

Stored in an environment object or shared singleton.

2. A view model that calls headless functions

Use Swift async/await and automatically surface Lucra flows based on errors.

3. Presentation logic hooked to LucraFlow enum

Full-screen Lucra UI for complex or regulated experiences.

4. Event listener

Use lucraClient.$event to react to contest changes.

---

✔️ Integration Checklist

• Headless APIs called using async/await

• UserStateError mapped to Lucra flows

• Location errors handled

• Custom UI built where appropriate

• Event listener implemented for updates

• Hybrid flow + headless routing tested

Your headless integration is now complete.

❌ Error Handling

Here are the list of possible errors returned in Result types as well as recommended steps for handling them.

Error Types

Headless functions return specific error types:

• GYP Functions: GamesMatchupError

• SYW Functions: MatchupError

• Tournament Functions: TournamentError

All error types follow the same structure:

GamesMatchupError / MatchupError / TournamentError

• .user(UserStateError) — Wraps user state errors

• .location(LocationError) — Wraps location errors

• .customError(message: String) — Custom error message

• .unknown — Unknown error

UserStateError

• .notInitialized

  • Route the user to .onboarding Flow.

• .unverified

  • Route the user to .verifyIdentity Flow.

• .notAllowed

  • Display an error indicating this action is not allowed.

• .insufficientFunds

  • Route the user to .addFunds flow.

• .demographicInformationMissing

  • Route the user to .demographicCollection.

LocationError

• .unauthorized

  • Location services have not been authorized for the app, route the user to iOS Settings to enable Location Permissions.

• .unableToDetermineLocation(error)

  • Location services are enabled but location cannot be verified, please have the user try again.

• .clError(clError)

  • Location services are unavailable, please have the user try again.

Error Handling Example

let result = await lucraClient.api.createRecreationalGame(
    gameTypeId: "DARTS",
    atStake: .cash(10),
    playStyle: .versus
)

switch result {
case .success(let matchupId):
    print("Created matchup: \(matchupId)")
case .failure(let error):
    switch error {
    case .user(let userError):
        switch userError {
        case .notInitialized:
            currentFlow = .onboarding
        case .unverified:
            currentFlow = .verifyIdentity
        case .insufficientFunds:
            currentFlow = .addFunds
        case .demographicInformationMissing:
            currentFlow = .demographicCollection
        case .notAllowed:
            showError("User not allowed to perform this action")
        }
    case .location(let locationError):
        switch locationError {
        case .unauthorized:
            showLocationSettingsAlert()
        case .unableToDetermineLocation(let error):
            showError("Unable to determine location: \(error.localizedDescription)")
        case .clError(let clError):
            showError("Location services error: \(clError.localizedDescription)")
        }
    case .customError(let message):
        showError(message)
    case .unknown:
        showError("An unknown error occurred")
    }
}

---