API — Użytkownicy i Awatar

Endpointy profilu użytkownika, statystyk, odznak oraz personalizacji awatara.

Wszystkie endpointy wymagają Authorization: Bearer <token>.

GET /app/users/me

Zwraca profil aktualnie zalogowanego użytkownika.

Response 200:

{
  "data": {
    "id": "prof_a1b2c3",
    "display_name": "Odkrywca",
    "birth_year": 2018,
    "language": "pl",
    "role": "child",
    "avatar_url": "https://cdn.lumos-islands.pl/avatars/prof_a1b2c3.png",
    "avatar": {
      "skin": "light",
      "hair": "brown_short",
      "hat": null,
      "shirt": "blue_tee",
      "accessory": null
    },
    "linked_parent_email": "anna@example.com",
    "created_at": "2026-01-10T08:00:00Z"
  }
}

PATCH /app/users/me

Aktualizuje dane profilu.

Request:

{
  "display_name": "Super Odkrywca",
  "language": "en"
}

Response 200:

{
  "data": {
    "id": "prof_a1b2c3",
    "display_name": "Super Odkrywca",
    "birth_year": 2018,
    "language": "en",
    "role": "child",
    "avatar_url": "https://cdn.lumos-islands.pl/avatars/prof_a1b2c3.png",
    "avatar": {
      "skin": "light",
      "hair": "brown_short",
      "hat": null,
      "shirt": "blue_tee",
      "accessory": null
    },
    "linked_parent_email": "anna@example.com",
    "created_at": "2026-01-10T08:00:00Z"
  }
}

GET /app/users/me/stats

Statystyki użytkownika — XP, poziom, ukończone zadania itp.

Response 200:

{
  "data": {
    "xp_total": 340,
    "level": 3,
    "level_name": "Podróżnik",
    "xp_to_next_level": 160,
    "xp_in_current_level": 40,
    "tasks_completed": 18,
    "tasks_in_progress": 1,
    "worlds_completed": 0,
    "locations_completed": 3,
    "badges_count": 5,
    "current_streak_days": 4,
    "longest_streak_days": 7,
    "total_time_minutes": 245
  }
}

GET /app/users/me/badges

Lista wszystkich zdobytych odznak.

Query params:

Param	Typ	Domyślnie	Opis
cursor	string	–	Kursor paginacji
limit	int	20	Liczba wyników (1–100)

Response 200:

{
  "data": [
    {
      "id": "badge_first_task",
      "name": "Pierwszy Krok",
      "description": "Ukończ swoje pierwsze zadanie.",
      "icon_url": "https://cdn.lumos-islands.pl/badges/first_task.png",
      "rarity": "common",
      "earned_at": "2026-01-10T09:15:00Z"
    },
    {
      "id": "badge_streak_7",
      "name": "Tygodniowa Seria",
      "description": "Ucz się 7 dni z rzędu.",
      "icon_url": "https://cdn.lumos-islands.pl/badges/streak_7.png",
      "rarity": "rare",
      "earned_at": "2026-02-20T18:00:00Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Pole rarity: common, rare, epic, legendary.

GET /app/avatar/items

Katalog przedmiotów do personalizacji awatara. Zawiera informację, które elementy są odblokowane.

Query params:

Param	Typ	Domyślnie	Opis
category	string	–	Filtruj po kategorii: hat, hair, shirt, accessory, skin

Response 200:

{
  "data": [
    {
      "id": "hat_explorer",
      "category": "hat",
      "name": "Kapelusz Odkrywcy",
      "preview_url": "https://cdn.lumos-islands.pl/avatar/items/hat_explorer.png",
      "unlocked": true,
      "unlock_condition": "Osiągnij poziom 4",
      "required_level": 4
    },
    {
      "id": "hat_wizard",
      "category": "hat",
      "name": "Czapka Czarodzieja",
      "preview_url": "https://cdn.lumos-islands.pl/avatar/items/hat_wizard.png",
      "unlocked": false,
      "unlock_condition": "Ukończ Świat Liczb",
      "required_level": null
    },
    {
      "id": "shirt_red_tee",
      "category": "shirt",
      "name": "Czerwona Koszulka",
      "preview_url": "https://cdn.lumos-islands.pl/avatar/items/shirt_red_tee.png",
      "unlocked": true,
      "unlock_condition": null,
      "required_level": null
    }
  ]
}

PATCH /app/avatar

Zmienia wygląd awatara. Wysyłaj tylko pola do zmiany.

Request:

{
  "hat": "hat_explorer",
  "shirt": "shirt_red_tee"
}

Response 200:

{
  "data": {
    "avatar_url": "https://cdn.lumos-islands.pl/avatars/prof_a1b2c3.png?v=1709892000",
    "avatar": {
      "skin": "light",
      "hair": "brown_short",
      "hat": "hat_explorer",
      "shirt": "shirt_red_tee",
      "accessory": null
    }
  }
}

Błędy:

HTTP	code	Kiedy
403	ITEM_LOCKED	Przedmiot nie jest odblokowany
404	ITEM_NOT_FOUND	Przedmiot nie istnieje