GYP Headless Functions

Lucra Headless setup

Use these APIs to manage Games You Play (recreational) matchups without showing Lucra UI. All calls require LucraSDK.init to be completed and the user configured.

Create Recreational Game

const { matchupId } = await LucraSDK.createRecreationalGame(
  'GAME_TYPE_ID',
  {
    type: 'cash',
    amount: 10,
  },
  'groupvsgroup'
);

Parameters:

• gameTypeId (string): Lucra game type identifier.

• atStake (object): Reward payload. Supported shapes:

  • Cash: { type: 'cash', amount: number }

  • Tenant reward: { type: 'tenantreward', rewardId, title, descriptor, iconUrl, bannerIconUrl?, disclaimer?, metadata?: Record<string,string> }

• playStyle (string): 'groupvsgroup' or 'freeforall' (case-insensitive).

Returns: { matchupId: string }

Example response:

{
  "matchupId": "matchup-id-123"
}

Errors that can be thrown:

• invalidAtStake — Missing type or required fields for the given reward type (e.g., cash amount).

• invalidRewardType — type is not cash or tenantreward.

• invalidPlayStyle — Play style is not groupvsgroup or freeforall.

• insufficientFunds — User has insufficient funds.

• notAllowed — User is not allowed to perform such operation.

• notInitialized — User has not been initialized.

• unverified — User has not been verified.

• missingDemographicInformation — User has missing demographic information.

• locationError — Location restriction or geo/permission issue.

• apiError — Server/network error message from backend.

• unknown / unknownError — Unclassified failure from native SDK.

Handling example:

try {
  const { matchupId } = await LucraSDK.createRecreationalGame('GAME_TYPE_ID', { type: 'cash', amount: 10 }, 'groupvsgroup');
} catch (e: any) {
  switch (e.code) {
    case 'invalidAtStake':
    case 'invalidRewardType':
    case 'invalidPlayStyle':
      // fix request payload
      break;
    case 'insufficientFunds':
      await LucraSDK.present({ name: LucraSDK.FLOW.ADD_FUNDS });
      break;
    case 'unverified':
      await LucraSDK.present({ name: LucraSDK.FLOW.VERIFY_IDENTITY });
      break;
    case 'missingDemographicInformation':
      await LucraSDK.present({ name: LucraSDK.FLOW.DEMOGRAPHIC_COLLECTION });
      break;
    case 'locationError':
      // prompt user to enable/allow location
      break;
    default:
      // show generic error
      console.warn(e);
  }
}

Accept Versus Recreational Game

await LucraSDK.acceptVersusRecreationalGame('MATCHUP_ID', 'TEAM_ID');

Parameters:

• matchupId (string): Matchup to accept.

• teamId (string): Team side to join.

Errors that can be thrown:

• insufficientFunds

• notAllowed

• notInitialized

• unverified

• missingDemographicInformation

• locationError

• apiError

• unknown / unknownError

Accept Free-for-All Recreational Game

await LucraSDK.acceptFreeForAllRecreationalGame('MATCHUP_ID');

Parameters:

• matchupId (string): Matchup to accept.

Errors that can be thrown:

• insufficientFunds

• notAllowed

• notInitialized

• unverified

• missingDemographicInformation

• locationError

• apiError

• unknown / unknownError

Cancel Games Matchup

await LucraSDK.cancelGamesMatchup('MATCHUP_ID');

Parameters:

• matchupId (string): Matchup ID to cancel.

Errors that can be thrown:

• notAllowed

• notInitialized

• unverified

• missingDemographicInformation

• locationError

• apiError

• unknown / unknownError

Get Matchup

const matchup = await LucraSDK.getMatchup('MATCHUP_ID');

Parameters:

• matchupId (string): Lucra matchup identifier.

Returns: MatchupInfo (includes participants, teams, status, and recreationGameExtension with game/buy-in details where available).

Errors that can be thrown:

• locationError

• apiError

• unknown / unknownError

Example response:

{
  "id": "matchup-id",
  "status": "OPEN",
  "type": "GAMES",
  "subtype": "RECREATIONAL",
  "isPublic": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "creatorId": "user-123",
  "participantGroups": [
    {
      "id": "team-a",
      "createdAt": "2024-01-01T00:00:00Z",
      "outcome": "UNKNOWN",
      "participants": [
        {
          "wager": 5,
          "user": {
            "id": "user-123",
            "username": "alice",
            "avatarUrl": null,
            "socialConnectionId": null,
            "loyaltyPoints": 0
          },
          "reward": null,
          "tournamentLeaderboard": null
        }
      ]
    }
  ],
  "recreationGameExtension": {
    "gameId": "GAME_TYPE_ID",
    "buyInAmount": 10,
    "game": {
      "id": "GAME_TYPE_ID",
      "name": "Ping Pong",
      "description": "Friendly match",
      "iconUrl": "https://...",
      "imageUrl": "https://...",
      "imageBgUrl": "https://...",
      "categoryIds": ["indoor"],
      "groupTitle": "Games",
      "isFeatured": false,
      "howToWin": "Score 21 points",
      "moreInfoHowToWin": null,
      "moreInfoTrackResults": null
    }
  }
}