This version (v0.7) has not been published to npm yet.
Skip to content

Reference / @getenginex/sdk-igaming / BonusApi

BonusApi ​

Bonus campaigns and promo codes. Only listPublicOffers is public; the other methods require login.

Methods ​

claim() ​

claim(input, options?): Promise<CampaignParticipation>

Redeems the reward of a qualified participation (campaigns with player_claim). Idempotent, like BonusApi.optIn: repeat with the same idempotencyKey so as not to redeem twice. The response is always validated in strict mode.

Parameters ​

input ​
participationId ​

string

options? ​

CallOptions

Returns ​

Promise<CampaignParticipation>

Example ​

ts
const done = await igaming.bonus.claim({ participationId: participation.id }, { idempotencyKey: key })

Throws ​

BONUS_ALREADY_CLAIMED (409) if the reward was already redeemed; BONUS_EXPIRED outside the redemption window and BONUS_NOT_ELIGIBLE if it has not qualified yet (HTTP 500 on the gateway: identify by the code); FAILED_PRECONDITION/KYC_REQUIRED (422); BONUS_NOT_FOUND (404); INVALID_ARGUMENT (400) for an id that is not a UUID; KEY_IN_USE (409); PAYLOAD_MISMATCH (422); VALIDATION_ERROR if the response comes outside the format (the redemption may have happened: check getParticipation); UNAUTHENTICATED without a session.


getOffer() ​

getOffer(input, options?): Promise<CampaignOffer>

An offer available to the player.

Parameters ​

input ​
campaignId ​

string

options? ​

CallOptions

Returns ​

Promise<CampaignOffer>

Example ​

ts
const offer = await igaming.bonus.getOffer({ campaignId })

Throws ​

BONUS_NOT_FOUND (404) if the campaign does not exist or is not available; INVALID_ARGUMENT (400) if campaignId is not a UUID; UNAUTHENTICATED without a session.


getParticipation() ​

getParticipation(input, options?): Promise<CampaignParticipation>

One of the player's participations.

Parameters ​

input ​
participationId ​

string

options? ​

CallOptions

Returns ​

Promise<CampaignParticipation>

Example ​

ts
const p = await igaming.bonus.getParticipation({ participationId })

Throws ​

BONUS_NOT_FOUND (404) if it does not exist (or belongs to another player); INVALID_ARGUMENT (400) if the id is not a UUID; UNAUTHENTICATED without a session.


listOffers() ​

listOffers(input?, options?): Promise<CursorPage<CampaignOffer>>

Offers available to the logged-in player. Cursor-paginated.

Parameters ​

input? ​

CursorPageInput

options? ​

CallOptions

Returns ​

Promise<CursorPage<CampaignOffer>>

Example ​

ts
const { items } = await igaming.bonus.listOffers()
const optIns = items.filter((o) => o.entryPolicy?.code === 'opt_in')

Throws ​

INVALID_ARGUMENT (400) for an invalid pageSize; UNAUTHENTICATED without a session.


listParticipations() ​

listParticipations(input?, options?): Promise<CursorPage<CampaignParticipation>>

The player's participations. Cursor-paginated.

Parameters ​

input? ​

CursorPageInput

options? ​

CallOptions

Returns ​

Promise<CursorPage<CampaignParticipation>>

Example ​

ts
const { items } = await igaming.bonus.listParticipations()
const claimable = items.filter((p) => p.status === 'qualified')

Throws ​

INVALID_ARGUMENT (400) for an invalid pageSize; UNAUTHENTICATED without a session.


listPublicOffers() ​

listPublicOffers(input?, options?): Promise<CursorPage<CampaignOffer>>

Public catalog of offers (storefront, no login): it only describes the campaigns; eligibility, joining and participations require login. Cursor-paginated.

Parameters ​

input? ​

CursorPageInput

options? ​

CallOptions

Returns ​

Promise<CursorPage<CampaignOffer>>

Example ​

ts
const { items, nextCursor } = await igaming.bonus.listPublicOffers({ pageSize: 20 })

Throws ​

INVALID_ARGUMENT (400) for a pageSize that is not a positive integer; UNAUTHENTICATED (401) if the gateway does not resolve the operator by the domain.


optIn() ​

optIn(input, options?): Promise<CampaignParticipation>

Joins an opt_in campaign. Idempotent: it sends Idempotency-Key — generated on every call, or the one in options.idempotencyKey — and keeps it on the retry after renewing the session; to repeat after NETWORK_ERROR/TIMEOUT without joining twice, generate the key beforehand and pass the same one on both attempts. The response is always validated in strict mode.

Parameters ​

input ​

OptInInput

options? ​

CallOptions

Returns ​

Promise<CampaignParticipation>

Example ​

ts
const participation = await igaming.bonus.optIn(
  { campaignId: offer.campaignId, campaignVersionId: offer.campaignVersionId, termsAcceptance: { locale: 'pt-BR', termsRevision: text.termsRevision } },
  { idempotencyKey: key },
)

Throws ​

BONUS_NOT_ELIGIBLE if the player cannot join; BONUS_EXPIRED outside the entry window (the gateway still returns these two with HTTP 500: identify by the code); BONUS_NOT_FOUND (404); ALREADY_EXISTS/BONUS_ALREADY_CLAIMED (409) if the player already participates; KYC_REQUIRED/FAILED_PRECONDITION (422) for a precondition (e.g. KYC, terms); INVALID_ARGUMENT (400) for ids that are not UUIDs or a malformed idempotency key; KEY_IN_USE (409) with the same key still being processed; PAYLOAD_MISMATCH (422) if the key was already used with another body; VALIDATION_ERROR if the response comes outside the format (the entry may have happened: check listParticipations); UNAUTHENTICATED without a session.


redeemPromoCode() ​

redeemPromoCode(input, options?): Promise<CampaignParticipation>

Redeems a promo code: joins the code's campaign. Idempotent (the gateway requires the key): repeat with the same idempotencyKey so as not to redeem twice. The response is always validated in strict mode. The code goes only in the body.

Parameters ​

input ​
code ​

string

termsAcceptance? ​

CampaignTermsAcceptance

options? ​

CallOptions

Returns ​

Promise<CampaignParticipation>

Example ​

ts
const participation = await igaming.bonus.redeemPromoCode(
  { code: 'BEMVINDO', termsAcceptance: { locale: 'pt-BR', termsRevision: localizedContent.termsRevision } },
  { idempotencyKey: key },
)

Throws ​

BONUS_NOT_FOUND (404) for a nonexistent code; BONUS_ALREADY_CLAIMED (409) if the player already used the code; BONUS_EXPIRED/BONUS_NOT_ELIGIBLE (HTTP 500 on the gateway: identify by the code); KYC_REQUIRED/FAILED_PRECONDITION (422); RESOURCE_EXHAUSTED (429) due to the per-player promo code attempt limit, the same as resolvePromoCode (see e.retryAfter); UNAVAILABLE (503) if the gateway's limiter is down (the route fails closed for safety); INVALID_ARGUMENT (400) for a malformed idempotency key; VALIDATION_ERROR if the response comes outside the format (the redemption may have happened: check listParticipations); UNAUTHENTICATED without a session.


resolvePromoCode() ​

resolvePromoCode(input, options?): Promise<PromoCodeOffer>

Shows the offer of a promo code before redemption (name, description and terms in the requested language). It does not join the campaign. The code is a secret: it goes only in the body, never in the URL or the hooks.

Parameters ​

input ​
code ​

string

locale ​

string

options? ​

CallOptions

Returns ​

Promise<PromoCodeOffer>

Example ​

ts
const { offer, localizedContent } = await igaming.bonus.resolvePromoCode({ code: input.value, locale: 'pt-BR' })

Throws ​

BONUS_NOT_FOUND (404) for a nonexistent or inactive code; BONUS_EXPIRED/BONUS_NOT_ELIGIBLE (HTTP 500 on the gateway: identify by the code); RESOURCE_EXHAUSTED (429) due to the attempt limit (see e.retryAfter); UNAVAILABLE (503) if the gateway's limiter is down (the route fails closed for safety); UNAUTHENTICATED without a session.