---
url: https://game-engine-io.github.io/enginex-frontend-sdk/igaming/missions.md
---
# Missions

Mission progress appears in the [Loyalty](/igaming/loyalty) demo (**Missions** scenario).

The `missions` namespace of [`@getenginex/sdk-igaming`](/igaming/) lists the operator's active missions
and the player's progress on them. Both methods require login. In tests, `withIgamingRoutes` already
answers both routes (see [Testing](#tests)).

## List and progress

```ts
// The operator's active missions (paginated, like the casino catalog).
const page = await igaming.missions.list({ page: 1, perPage: 20 })
page.items.forEach((m) => console.log(m.name, m.missionType, m.targetValue, m.validTo))

// The player's progress (not paginated).
const mine = await igaming.missions.listMine()
for (const m of mine) {
  console.log(m.missionName, `${m.progressPercentage}%`, m.status, m.completedAt)
}
```

`list` returns `Page<Mission>` (`items`, `page`, `perPage`, `totalItems`, `totalPages`; see
[Pagination](/concepts/pagination)): the gateway sends the pagination in the envelope's `meta` and the
SDK passes it along. `page` is an integer ≥ 1 and `perPage` an integer from 1 to 100; a value outside
that rejects with `CONFIGURATION_ERROR`, with no request.

* **`Mission`** (the rule): `id`, `name`, `description`, `missionType`, `objectiveType`, `targetValue`,
  `targetGameCategory`, `targetGames`, `rewardType`, `rewardValue`, `validFrom`, `validTo`.
  `targetGames` is `[]` when there is no game restriction; `targetGameCategory`, `validFrom` and
  `validTo` are `null` when the gateway sends empty or the epoch date (`1970-01-01T00:00:00Z`).
* **`UserMission`** (the progress): `id`, `missionId`, `missionName`, `currentProgress`, `targetValue`,
  `progressPercentage` (number, e.g. `37.5`), `status`, `rewardType`, `rewardValue`, `periodEnd` and
  `completedAt` (`null` when absent). To join it with the rule, match `missionId` with `Mission.id`.

### Types and statuses

`missionType`, `objectiveType`, `rewardType` and `status` are open unions in lowercase
(`| (string & {})`): the backend treats them as free text, so always handle the default case.

| Field | Known values |
| --- | --- |
| `missionType` | `daily`, `weekly`, `event`, `permanent` |
| `objectiveType` | `wager`, `bet_count`, `win_amount`, `play_game`, `deposit` |
| `rewardType` | `bonus`, `free_spins`, `points`, `free_bet` |
| `status` (`UserMission`) | `in_progress`, `completed`, `expired`, `claimed` |

A value the SDK does not know yet, under `validation: 'warn'`, arrives raw in the field and goes to
`onValidationIssue`; under `'strict'` the call rejects with `VALIDATION_ERROR` (see
[Validation](/concepts/validation)).

### Units of `targetValue` and `rewardValue`

Both are integers. **The bonus service contract (`bonus.proto`) does not state the unit**: its comments
only list the type values. The tables below are an **assumption**, not confirmed; validate with the
operator before showing values to the player.

| `objectiveType` | Assumed unit of `targetValue` and `currentProgress` |
| --- | --- |
| `wager`, `win_amount`, `deposit` | minor units of the currency (e.g. cents; use the core's `formatMoney`) |
| `bet_count` | number of bets |
| `play_game` | number of rounds in the games of `targetGames` / `targetGameCategory` |

| `rewardType` | Assumed unit of `rewardValue` |
| --- | --- |
| `bonus`, `free_bet` | minor units of the currency |
| `free_spins` | number of spins |
| `points` | loyalty points |

## Reward and refresh

There is no redemption method (`claim`): the reward of a completed mission is credited by the bonus
service, with no action from the player (inferred: the gateway exposes no redemption route).
`status: 'claimed'` is a value the service may return, but its meaning is not confirmed by the
contract (which only lists the value); do not rely on it to decide whether the reward was delivered.

There is no realtime for missions. To show updated progress, call `listMine()` again after events that
affect it, such as a completed bet or deposit (for example, when receiving the new balance through
[Live balance](/flows/live-balance)), instead of constant polling.

## Errors

| Code | When |
| --- | --- |
| `UNAUTHENTICATED` (401) | no session |
| `CONFIGURATION_ERROR` | `page`/`perPage` out of range (no request) or client already disposed |
| `VALIDATION_ERROR` | only under `validation: 'strict'`: a type or status value the SDK does not know |

## What the gateway does not offer yet

* **Redemption route**: does not exist; that is why the SDK has no `claim()`.
* **Filter by type**: the service accepts `mission_type_filter`, but the gateway does not pass it along.
  Filter in the app by `missionType` (the list carries only active missions).
* **Realtime progress**: no realtime topic; query again.
* **Paginated player missions**: `listMine` returns everything at once (only the active ones).

## Testing {#tests}

```ts
import { createEnginexClient } from '@getenginex/sdk'
import { createMockFetch } from '@getenginex/sdk/testing'
import { createIgaming } from '@getenginex/sdk-igaming'
import { withIgamingRoutes } from '@getenginex/sdk-igaming/testing'

const enginex = createEnginexClient({
  baseUrl: 'https://gateway.test', // in Node: absolute baseUrl + tenantHost (optional in the browser)
  tenantHost: 'casino.test',
  fetch: createMockFetch(withIgamingRoutes()),
})
const igaming = createIgaming(enginex)
await enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123' })

const { items, totalItems } = await igaming.missions.list({ perPage: 3 }) // 3 of 4 missions
const mine = await igaming.missions.listMine() // one in progress and one completed
```

The mock returns four fixed missions, in the gateway's formats (null `target_games`, epoch dates,
pagination in `meta`), and the progress of two of them.
