Mobiili-API

Koko mobiili-API kulkee oman domainin kautta osoitteessa api.meidankesken.app. Reitit ovat JSON-pohjaisia ja tukevat CORS:ia – erillistä API-avainta ei tarvita.

Yhteys

BASE_URL = https://api.meidankesken.app/api/public

const res = await fetch(BASE_URL + "/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email, password }),
});
const { access_token } = await res.json();

await fetch(BASE_URL + "/catalog");                       // julkinen
await fetch(BASE_URL + "/game/session", {                 // vaatii tokenin
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + access_token,
  },
  body: JSON.stringify({ player_names: ["Anna"], deck_slug: "syvat-vedet" }),
});

Kirjautumista vaativissa reiteissä lähetetään otsake Authorization: Bearer <access_token>.

Autentikointi

Rekisteröinti, kirjautuminen ja tokenin uusiminen saman domainin kautta.

POST /auth/signup

Julkinen

Rekisteröi uusi pelaaja sähköpostilla ja salasanalla.

Kutsu

{ "email": "pelaaja@example.com", "password": "salasana123" }

Vastaus

{ "id": "uuid", "email": "pelaaja@example.com", "…": "…" }

POST /auth/login

Julkinen

Kirjautuminen. Palauttaa access- ja refresh-tokenin.

Kutsu

{ "email": "pelaaja@example.com", "password": "salasana123" }

Vastaus

{ "access_token": "…", "refresh_token": "…", "expires_in": 3600, "user": { "id": "uuid" } }

POST /auth/refresh

Julkinen

Uusi access token vanhentuneen tilalle.

Kutsu

{ "refresh_token": "…" }

Vastaus

{ "access_token": "…", "refresh_token": "…" }

POST /auth/logout

Token vaaditaan

Kirjaa käyttäjän ulos ja mitätöi istunnon.

Kutsu

{}

Vastaus

204 No Content

Sisältö

Julkiset reitit – eivät vaadi kirjautumista.

GET /catalog

Julkinen

Kaikki julkaistut kategoriat ja niiden korttipakat.

Vastaus

{
  "categories": [
    {
      "id": "uuid", "slug": "parisuhde", "name": "Parisuhde",
      "description": "…", "icon": "heart", "color": "#b4674d", "sort_order": 1,
      "decks": [
        { "id": "uuid", "slug": "syvat-vedet", "name": "Syvät vedet",
          "theme": "läheisyys", "difficulty": 3, "default_timer_seconds": 60 }
      ]
    }
  ]
}

GET /deck/{slug}

Julkinen

Yksittäinen korttipakka ja sen kortit.

Kutsu

GET https://api.meidankesken.app/api/public/deck/syvat-vedet

Vastaus

{
  "deck": { "id": "uuid", "slug": "syvat-vedet", "name": "Syvät vedet", "default_timer_seconds": 60 },
  "cards": [
    { "id": "uuid", "content": "Mistä hetkestä muistat…",
      "type": "question", "hint": null, "sort_order": 1 }
  ]
}

Peli

Vaativat kirjautuneen käyttäjän bearer-tokenin. Data rajautuu omiin peleihin.

POST /game/session

Token vaaditaan

Luo pelisession, sekoittaa kortit ja arpoo vuorojärjestyksen (ei kahta vuoroa peräkkäin samalle pelaajalle).

Kutsu

{
  "player_names": ["Anna", "Mikko", "Sara"],
  "deck_slug": "syvat-vedet",   // tai deck_id
  "timer_seconds": 45,          // null = pakan oletus
  "shuffle": true
}

Vastaus

{
  "session": { "id": "uuid", "started_at": "…", "timer_seconds": 45,
               "player_names": ["Anna", "Mikko", "Sara"] },
  "deck": { "id": "uuid", "name": "Syvät vedet" },
  "cards": [ { "id": "uuid", "content": "…", "type": "question",
               "sort_order": 3, "turn_player": "Mikko" } ],
  "turn_order": ["Mikko", "Anna", "Sara", "…"]
}

POST /game/play

Token vaaditaan

Kirjaa pelatun tai ohitetun kortin. Kutsutaan jokaisen swipen jälkeen.

Kutsu

{ "session_id": "uuid", "card_id": "uuid",
  "player_name": "Mikko", "skipped": false }

Vastaus

{ "ok": true, "played_count": 7 }

POST /game/complete

Token vaaditaan

Päättää session ja palauttaa yhteenvedon.

Kutsu

{ "session_id": "uuid" }

Vastaus

{
  "session": { "id": "uuid", "completed_at": "…" },
  "summary": { "played": 12, "skipped": 2, "answered": 10 }
}

GET /game/session

Token vaaditaan

Pelihistoria: 50 viimeisintä omaa sessiota.

Vastaus

[ { "id": "uuid", "player_names": ["Anna", "Mikko"],
    "started_at": "…", "completed_at": "…",
    "decks": { "name": "Syvät vedet", "slug": "syvat-vedet" } } ]

AI-pelinjärjestäjä

Striimaava keskustelu samalta domainilta. Vaatii tokenin.

POST /chat

Token vaaditaan

Striimaava keskustelu. mode: "host" = pakan valinta, "narrator" = kortin luku ja vuoron osoitus.

Kutsu

fetch("https://api.meidankesken.app/api/public/chat", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ message: "Meitä on kolme, jotain kevyttä.", mode: "host" })
})

Vastaus

data: {"delta":"Kuulostaa"}
data: {"delta":" hyvältä"}
data: [DONE]

Virhekoodit

400	Virheellinen pyyntörunko
401	Puuttuva tai vanhentunut token
403	AI-pelinjärjestäjä pois käytöstä
22023	Virheellinen syöte (pelaajamäärä tai pakan tunniste)
P0002	Resurssia ei löydy (pakka tai sessio)
P0003	Pakassa ei ole julkaistuja kortteja
P0004	Sessio on jo päättynyt