Tournament Headless Functions

Lucra Headless setup

Use these headless APIs to list, fetch, and join tournaments without showing Lucra UI. Requires LucraSDK.init and a configured user.

Get Recommended Tournaments

const tournaments = await LucraSDK.getRecomendedTournaments({
  includeClosed: true,
  limit: 50,
});

Example response:

[
  {
    "id": "tournament-1",
    "title": "Weekend Pool",
    "type": "POOL",
    "fee": 5,
    "buyInAmount": 5,
    "description": "Win by placing in the top 10",
    "participants": [
      { "id": "user-1", "username": "alice", "place": 1, "rewardValue": 20 },
      { "id": "user-2", "username": "bob", "place": 2, "rewardValue": 10 }
    ],
    "status": "OPEN",
    "metadata": null,
    "iconUrl": "https://...",
    "expiresAt": "2024-01-01T00:00:00Z",
    "potTotal": 100
  }
]

Parameters:

• includeClosed (boolean): Include completed tournaments.

• limit (number): Max number of tournaments.

Returns: Promise<PoolTournament[]>

Errors that can be thrown:

• apiError — Network/server failure.

• locationError — Geo restriction or location permission issue.

• insufficientFunds — User balance too low for entry fees.

• notAllowed — User not permitted (suspended/restricted).

• notInitialized — SDK/user session not ready.

• unverified — Identity verification required.

• missingDemographicInformation — Required profile fields missing.

• unknown / unknownError — Unclassified native SDK failure.

Get Tournament Matchup

const tournament = await LucraSDK.tournamentMatchup('TOURNAMENT_ID');

Parameters:

• tournamentId (string): Tournament ID to fetch.

Returns: Promise<PoolTournament>

Errors that can be thrown:

• apiError

• locationError

• insufficientFunds

• notAllowed

• notInitialized

• unverified

• missingDemographicInformation

• unknown / unknownError

Example response:

{
  "id": "tournament-1",
  "title": "Weekend Pool",
  "type": "POOL",
  "fee": 5,
  "buyInAmount": 5,
  "description": "Win by placing in the top 10",
  "participants": [
    { "id": "user-1", "username": "alice", "place": 1, "rewardValue": 20 },
    { "id": "user-2", "username": "bob", "place": 2, "rewardValue": 10 }
  ],
  "status": "OPEN",
  "metadata": null,
  "iconUrl": "https://...",
  "expiresAt": "2024-01-01T00:00:00Z",
  "potTotal": 100
}

Join Tournament

await LucraSDK.joinTournament('TOURNAMENT_ID');

Parameters:

• tournamentId (string): Tournament ID to join.

Returns: Promise<void>

Error handling example

import { LucraSDK, type LucraSDKError } from '@lucra-sports/lucra-react-native-sdk';

try {
  await LucraSDK.joinTournament('TOURNAMENT_ID');
} catch (error) {
  const e = error as LucraSDKError;
  switch (e.code) {
    case 'notInitialized':
      // Ensure SDK init + user config
      break;
    case 'unverified':
      await LucraSDK.present({ name: LucraSDK.FLOW.VERIFY_IDENTITY });
      break;
    case 'insufficientFunds':
      await LucraSDK.present({ name: LucraSDK.FLOW.ADD_FUNDS });
      break;
    case 'missingDemographicInformation':
      await LucraSDK.present({ name: LucraSDK.FLOW.DEMOGRAPHIC_COLLECTION });
      break;
    case 'notAllowed':
      // Show restriction message or support contact
      break;
    case 'locationError':
      // Prompt user to enable location / check state eligibility
      break;
    case 'apiError':
      // Retry or show generic failure
      break;
    default:
      console.warn('Unknown tournament error', e);
  }
}

Types

type PoolTournament = {
  id: string;
  title: string;
  type: string;
  fee: number;
  buyInAmount: number;
  description?: string;
  participants: PoolTournamentParticipant[];
  status: string;
  metadata?: string;
  iconUrl?: string;
  expiresAt?: string;
  potTotal: number;
};

type PoolTournamentParticipant = {
  id: string;
  username: string;
  place?: number;
  rewardValue?: number;
};

Event: Tournament Joined

const unsubscribe = LucraSDK.addContestListener({
  onTournamentJoined: (tournamentId: string) => {
    console.log(`User joined tournament: ${tournamentId}`);
  },
});

// Call this when you no longer need the listener (e.g., on unmount).
unsubscribe();

Usage examples

Join with demographic prompt fallback

try {
  await LucraSDK.joinTournament('<tournament-id>');
} catch (e: any) {
  if (e.code === 'missingDemographicInformation') {
    LucraSDK.present({ name: LucraSDK.FLOW.DEMOGRAPHIC_COLLECTION });
  } else {
    throw e;
  }
}

Launch demographic form directly

LucraSDK.present({ name: LucraSDK.FLOW.DEMOGRAPHIC_COLLECTION });

Check user demographics before calling join

const user = await LucraSDK.getUser();
const isMissingDemo = !user.email || !user.address?.zip;
if (isMissingDemo) {
  LucraSDK.present({ name: LucraSDK.FLOW.DEMOGRAPHIC_COLLECTION });
}