API — Światy

Endpointy do pobierania światów i ich lokacji. Światy wyświetlane są na interaktywnym globusie w aplikacji.

Wszystkie endpointy wymagają Authorization: Bearer <token>.

GET /app/worlds

Lista wszystkich światów dostępnych na globusie.

Query params:

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

Response 200:

{
  "data": [
    {
      "id": "world_letters",
      "name": "Świat Liter",
      "description": "Poznaj litery i naucz się czytać!",
      "icon_url": "https://cdn.lumos-islands.pl/worlds/letters.png",
      "color": "#4A90D9",
      "globe_position": { "lat": 35.2, "lng": -12.8 },
      "locations_count": 12,
      "completed_locations": 4,
      "progress_percent": 33,
      "status": "in_progress"
    },
    {
      "id": "world_numbers",
      "name": "Świat Liczb",
      "description": "Odkryj magię matematyki!",
      "icon_url": "https://cdn.lumos-islands.pl/worlds/numbers.png",
      "color": "#E8A838",
      "globe_position": { "lat": -15.0, "lng": 45.3 },
      "locations_count": 8,
      "completed_locations": 0,
      "progress_percent": 0,
      "status": "locked"
    }
  ],
  "next_cursor": "eyJpZCI6IndvcmxkX251bWJlcnMifQ",
  "has_more": false
}

Pole status:

• locked — wymaga ukończenia poprzedniego świata
• available — odblokowany, ale nie rozpoczęty
• in_progress — w trakcie
• completed — ukończony

GET /app/worlds/:id

Szczegóły pojedynczego świata.

Response 200:

{
  "data": {
    "id": "world_letters",
    "name": "Świat Liter",
    "description": "Poznaj litery i naucz się czytać!",
    "long_description": "W Świecie Liter czekają na Ciebie przygody z alfabetem...",
    "icon_url": "https://cdn.lumos-islands.pl/worlds/letters.png",
    "banner_url": "https://cdn.lumos-islands.pl/worlds/letters_banner.png",
    "color": "#4A90D9",
    "globe_position": { "lat": 35.2, "lng": -12.8 },
    "locations_count": 12,
    "completed_locations": 4,
    "progress_percent": 33,
    "status": "in_progress",
    "reward_badge_id": "badge_letter_master",
    "prerequisite_world_id": null
  }
}

GET /app/worlds/:id/locations

Lista lokacji (punktów na mapie świata) z ich statusem.

Query params:

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

Response 200:

{
  "data": [
    {
      "id": "loc_a_vowels",
      "name": "Wyspa Samogłosek",
      "description": "A, E, I, O, U — poznaj samogłoski!",
      "icon_url": "https://cdn.lumos-islands.pl/locations/vowels.png",
      "map_position": { "x": 0.25, "y": 0.40 },
      "tasks_count": 5,
      "completed_tasks": 3,
      "status": "in_progress",
      "order": 1
    },
    {
      "id": "loc_b_consonants",
      "name": "Góra Spółgłosek",
      "description": "Wspinaj się po literach!",
      "icon_url": "https://cdn.lumos-islands.pl/locations/consonants.png",
      "map_position": { "x": 0.55, "y": 0.30 },
      "tasks_count": 6,
      "completed_tasks": 0,
      "status": "locked",
      "order": 2
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Pole status lokacji:

• locked — wymaga ukończenia poprzedniej lokacji
• available — odblokowana
• in_progress — rozpoczęta
• completed — wszystkie zadania ukończone