API — Planety

Planety to przestrzenie społecznościowe, w których dzieci mogą współpracować. Dziecko może dołączyć do otwartych planet lub opuścić te, w których już uczestniczy.

Wszystkie endpointy wymagają Authorization: Bearer <token>.

GET /app/planets/open

Lista otwartych planet (visibility: "open"), do których dziecko może dołączyć. Paginacja kursorowa.

Uwaga: Ten endpoint nigdy nie zwraca planet zamkniętych (visibility: "closed"). Planety zamknięte są dostępne wyłącznie przez GET /app/planets/mine dla użytkowników jawnie dodanych do assigned_users.

Query params:

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

Response 200:

{
  "data": [
    {
      "id": "planet_explorers",
      "name": "Planeta Odkrywców",
      "description": "Wspólnie poznajemy świat!",
      "icon_url": "https://cdn.lumos-islands.pl/planets/explorers.png",
      "members_count": 24,
      "max_members": 30,
      "category": "science",
      "created_at": "2026-01-15T10:00:00Z"
    },
    {
      "id": "planet_artists",
      "name": "Planeta Artystów",
      "description": "Tu tworzymy i rysujemy!",
      "icon_url": "https://cdn.lumos-islands.pl/planets/artists.png",
      "members_count": 12,
      "max_members": 30,
      "category": "art",
      "created_at": "2026-02-01T08:30:00Z"
    }
  ],
  "next_cursor": "eyJpZCI6InBsYW5ldF9hcnRpc3RzIn0",
  "has_more": true
}

GET /app/planets/mine

Lista planet, do których dziecko należy. Paginacja kursorowa.

Obejmuje zarówno planety otwarte (do których dziecko dołączyło), jak i planety zamknięte — ale tylko te, w których dziecko znajduje się w tablicy assigned_users. Planety zamknięte, do których dziecko nie jest przypisane, nie pojawiają się w wynikach.

Query params:

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

Response 200:

{
  "data": [
    {
      "id": "planet_explorers",
      "name": "Planeta Odkrywców",
      "description": "Wspólnie poznajemy świat!",
      "icon_url": "https://cdn.lumos-islands.pl/planets/explorers.png",
      "members_count": 24,
      "max_members": 30,
      "category": "science",
      "joined_at": "2026-02-10T14:22:00Z",
      "my_xp_in_planet": 320
    }
  ],
  "next_cursor": null,
  "has_more": false
}

POST /app/planets/:id/join

Dołącz do planety.

Request: pusty body

Response 200:

{
  "data": {
    "planet_id": "planet_explorers",
    "joined_at": "2026-03-08T09:15:00Z",
    "members_count": 25
  }
}

Błędy:

HTTP	code	Kiedy
409	ALREADY_MEMBER	Dziecko już należy do tej planety
409	PLANET_FULL	Planeta osiągnęła limit członków

POST /app/planets/:id/leave

Opuść planetę.

Request: pusty body

Response 200:

{
  "data": {
    "planet_id": "planet_explorers",
    "left_at": "2026-03-08T09:30:00Z",
    "members_count": 24
  }
}

Błędy:

HTTP	code	Kiedy
404	NOT_MEMBER	Dziecko nie należy do tej planety