API — Przegląd

Lumos Islands udostępnia dwa zestawy endpointów:

Prefix	Konsument	Opis
/app/*	Aplikacja mobilna (Flutter)	Wszystkie operacje dziecka i rodzica
/api/*	Manager-Content (Web)	Integracje panelu zarządzania

Base URL

Produkcja:  https://api.lumos-islands.pl
Staging:    https://api-staging.lumos-islands.pl
Lokalne:    http://localhost:8080

Konwencje

Envelope odpowiedzi

Sukces:

{
  "data": { "id": "abc-123", "name": "Wyspy Odkrywców" }
}

Błąd:

{
  "error": {
    "code": "INVALID_PIN",
    "message": "PIN musi składać się z 4 cyfr."
  }
}

Kody błędów

HTTP	code	Opis
400	VALIDATION_ERROR	Nieprawidłowe dane wejściowe
401	UNAUTHORIZED	Brak lub wygasły token
403	FORBIDDEN	Brak uprawnień
404	NOT_FOUND	Zasób nie istnieje
409	CONFLICT	Duplikat lub konflikt stanu
429	RATE_LIMITED	Zbyt wiele żądań
500	INTERNAL_ERROR	Błąd serwera

Autentykacja

Wszystkie chronione endpointy wymagają nagłówka:

Authorization: Bearer <token>

Token JWT jest zwracany po rejestracji lub logowaniu.

Paginacja — aplikacja mobilna (/app/*)

Kursorowa — zapewnia stabilne stronicowanie nawet przy zmieniających się danych.

GET /app/worlds?cursor=eyJpZCI6NDJ9&limit=20

{
  "data": [
    { "id": "w1", "name": "Świat Liter" }
  ],
  "next_cursor": "eyJpZCI6NjJ9",
  "has_more": true
}

Parametr	Typ	Domyślnie	Opis
cursor	string	–	Kursor z poprzedniej odpowiedzi
limit	int	20	Maks. liczba elementów (1–100)

Nagłówki opcjonalne

Nagłówek	Wymagany	Opis
X-Timezone	nie	Strefa czasowa klienta (np. Europe/Warsaw). Używany do obliczania streaka dziennego. Domyślnie UTC.

Paginacja — panel web (/api/*, HTMX)

Offset-based — wygodna dla tabel z numeracją stron.

GET /api/content?page=2&per_page=20

Odpowiedź HTMX zawiera fragment HTML z nagłówkami:

X-Total-Count: 154
X-Page: 2
X-Per-Page: 20

Rate Limiting

Grupa endpointów	Limit	Okno
POST /app/auth/*	10 req	1 min
POST /api/auth/*	10 req	1 min
GET /app/*	100 req	1 min
POST /app/*	30 req	1 min
Upload (multipart)	5 req	1 min

Przy przekroczeniu limitu serwer zwraca 429 Too Many Requests.

Mapa endpointów

Autentykacja — szczegóły

Metoda	Endpoint	Opis
POST	/app/auth/register/child	Rejestracja profilu dziecka
POST	/app/auth/register/parent	Rejestracja rodzica (e-mail)
POST	/app/auth/verify-email	Weryfikacja kodu e-mail
POST	/app/auth/login/child	Logowanie dziecka (PIN)
POST	/app/auth/login/parent	Logowanie rodzica (e-mail)
POST	/app/auth/link/generate	Generuj kod łączenia
POST	/app/auth/link/redeem	Zrealizuj kod łączenia
POST	/app/auth/manager-code	Kod logowania do managera
GET	/app/auth/profiles	Lista profili na urządzeniu

Światy — szczegóły

Metoda	Endpoint	Opis
GET	/app/worlds	Lista światów (globus)
GET	/app/worlds/:id	Szczegóły świata
GET	/app/worlds/:id/locations	Lokacje na mapie

Planety — szczegóły

Metoda	Endpoint	Opis
GET	/app/planets/open	Otwarte planety
GET	/app/planets/mine	Moje planety
POST	/app/planets/:id/join	Dołącz do planety
POST	/app/planets/:id/leave	Opuść planetę

Lokacje — szczegóły

Metoda	Endpoint	Opis
GET	/app/locations/:id	Szczegóły lokacji + zadania

Zadania — szczegóły

Metoda	Endpoint	Opis
GET	/app/tasks/:id	Pełne dane zadania
POST	/app/tasks/:id/start	Rozpocznij zadanie
POST	/app/tasks/:id/complete	Ukończ zadanie
POST	/app/tasks/:id/submit-creative	Wyślij pracę kreatywną

Użytkownicy i Awatar — szczegóły

Metoda	Endpoint	Opis
GET	/app/users/me	Profil użytkownika
PATCH	/app/users/me	Aktualizuj profil
GET	/app/users/me/stats	Statystyki
GET	/app/users/me/badges	Zdobyte odznaki
GET	/app/avatar/items	Katalog przedmiotów awatara
PATCH	/app/avatar	Zmień wygląd awatara

Todo — szczegóły

Metoda	Endpoint	Opis
GET	/app/todos	Lista zadań do zrobienia
POST	/app/todos	Dodaj zadanie
PATCH	/app/todos/:id	Zmień status
DELETE	/app/todos/:id	Usuń zadanie

Poziomy, Ranking, Onboarding — szczegóły

Metoda	Endpoint	Opis
GET	/app/levels	Definicje poziomów
GET	/app/rankings	Tablica wyników
GET	/app/onboarding/status	Status onboardingu
POST	/app/onboarding/complete	Zakończ onboarding

Manager API (Web) — szczegóły

Metoda	Endpoint	Opis
POST	/api/auth/verify-code	Weryfikacja kodu logowania
POST	/api/auth/send-email-code	Wyślij kod e-mail

Web Routes (SSR) — szczegóły

Strony i fragmenty HTMX panelu Manager-Content.