API — Poziomy, Ranking, Onboarding

Endpointy pomocnicze: definicje poziomów, tablica wyników i onboarding nowego użytkownika.

Wszystkie endpointy wymagają Authorization: Bearer <token>.

GET /app/levels

Definicje wszystkich poziomów z progami XP. Dane statyczne — nie wymagają paginacji.

Response 200:

{
  "data": [
    {
      "level": 1,
      "name": "Nowicjusz",
      "xp_required": 0,
      "xp_to_next": 100,
      "icon_url": "https://cdn.lumos-islands.pl/levels/1.png",
      "unlocked_items": []
    },
    {
      "level": 2,
      "name": "Uczeń",
      "xp_required": 100,
      "xp_to_next": 200,
      "icon_url": "https://cdn.lumos-islands.pl/levels/2.png",
      "unlocked_items": ["shirt_green_tee"]
    },
    {
      "level": 3,
      "name": "Podróżnik",
      "xp_required": 300,
      "xp_to_next": 200,
      "icon_url": "https://cdn.lumos-islands.pl/levels/3.png",
      "unlocked_items": ["hair_spiky"]
    },
    {
      "level": 4,
      "name": "Odkrywca",
      "xp_required": 500,
      "xp_to_next": 300,
      "icon_url": "https://cdn.lumos-islands.pl/levels/4.png",
      "unlocked_items": ["hat_explorer"]
    },
    {
      "level": 5,
      "name": "Mistrz",
      "xp_required": 800,
      "xp_to_next": null,
      "icon_url": "https://cdn.lumos-islands.pl/levels/5.png",
      "unlocked_items": ["accessory_cape"]
    }
  ]
}

GET /app/rankings

Tablica wyników (leaderboard). Paginacja kursorowa.

Query params:

Param	Typ	Domyślnie	Opis
cursor	string	–	Kursor paginacji
limit	int	20	Liczba wyników (1–100)
scope	string	global	Zakres: global, planet
planet_id	string	–	Wymagane gdy scope=planet

Response 200:

{
  "data": [
    {
      "rank": 1,
      "profile_id": "prof_x1y2z3",
      "display_name": "Kosmonauta",
      "avatar_url": "https://cdn.lumos-islands.pl/avatars/prof_x1y2z3.png",
      "level": 5,
      "xp_total": 920,
      "is_me": false
    },
    {
      "rank": 2,
      "profile_id": "prof_a1b2c3",
      "display_name": "Odkrywca",
      "avatar_url": "https://cdn.lumos-islands.pl/avatars/prof_a1b2c3.png",
      "level": 3,
      "xp_total": 340,
      "is_me": true
    },
    {
      "rank": 3,
      "profile_id": "prof_m4n5o6",
      "display_name": "Artystka",
      "avatar_url": "https://cdn.lumos-islands.pl/avatars/prof_m4n5o6.png",
      "level": 3,
      "xp_total": 310,
      "is_me": false
    }
  ],
  "next_cursor": "eyJyYW5rIjozfQ",
  "has_more": true
}

Pole is_me wskazuje profil aktualnie zalogowanego użytkownika.

GET /app/onboarding/status

Sprawdza, które kroki onboardingu zostały ukończone.

Response 200:

{
  "data": {
    "completed": false,
    "steps": {
      "avatar_created": true,
      "first_world_visited": true,
      "first_task_completed": false,
      "todo_created": false
    },
    "current_step": "first_task_completed"
  }
}

POST /app/onboarding/complete

Oznacza onboarding jako zakończony. Wywoływane po przejściu wszystkich kroków lub po ich pominięciu.

Request: pusty body

Response 200:

{
  "data": {
    "completed": true,
    "completed_at": "2026-03-08T10:30:00Z",
    "reward": {
      "xp_earned": 50,
      "badge": {
        "id": "badge_welcome",
        "name": "Witaj na Wyspach!",
        "icon_url": "https://cdn.lumos-islands.pl/badges/welcome.png"
      }
    }
  }
}

Błędy:

HTTP	code	Kiedy
409	ALREADY_COMPLETED	Onboarding już ukończony