challenge API documentation

doc/mobile/create_game.md

@@ -53,3 +53,91 @@ Now you're waiting for someone to accept the seek. The response will come as a s
   "id": "abcdefgh1234"
 }
 ```
+
+## Challenge someone
+
+```sh
+http --form POST en.l.org/setup/friend variant=1 clock=false time=60 increment=60 color=random 'Accept:application/vnd.lichess.v1+json'
+```
+- color: white | black | random
+- variant: 1 (standard) | 2 (chess960) | 3 (from position) | 4 (KotH) | 5 (three-check)
+- fen: if variant is 3, any valid FEN string
+
+Response: `201 CREATED`
+```javascript
+{
+  // see document format in the play.md doc file
+}
+```
+
+Then, connect to the game websocket as a player (see Play documentation).
+Now you must send a message over the socket every 1,5 seconds to keep the challenge open:
+
+```javascript
+// send
+{t: 'challenge', d: 'userIdOfChallengedPlayer'}
+```
+
+### Cancel the challenge
+
+A challenge can be aborted before it is accepted, using a HTTP request:
+
+```sh
+http --form GET en.l.org/<fullGameId>/cancel 'Accept:application/vnd.lichess.v1+json'
+```
+
+### Accepted by the opponent
+
+When the challenge is accepted, you will receive a redirect message through the websocket:
+
+```javascript
+// receive
+{
+  "t": "redirect", // means we should move on to the game
+  "id": "abcdefgh1234"
+}
+```
+
+### Declined by the opponent
+
+When the challenge is decline, you will receive a message through the websocket:
+
+```javascript
+// receive
+{"t": "declined"}
+```
+
+## Receive a challenge
+
+Listen for this message on any websocket:
+
+```javascript
+// receive
+{
+  "t": "challengeReminder",
+  "id": "abcdefgh"
+}
+```
+
+You will receive this every 1,5 seconds aproximatively, until the challenge creator stops sending it.
+The challenge ID is also the game public ID.
+
+### Fetch game information
+
+The first time you see a challenge ID, use it to fetch information about the game:
+
+```sh
+http GET en.l.org/39b12Ikl 'Accept:application/vnd.lichess.v1+json'
+```
+
+Response: `200 OK`
+```javascript
+{
+  // see document format in the Play section
+}
+```
+
+Use this info to display the challenge.
+
+If you stop receiving the challenge message for some time (lichess web uses 3 seconds),
+you should stop displaying it.

modules/api/src/main/GameApi.scala

@@ -30,7 +30,7 @@ private[api] final class GameApi(
     G.rated -> rated.map(_.fold(JsBoolean(true), $exists(false))),
     G.analysed -> analysed.map(_.fold(JsBoolean(true), $exists(false))),
     G.variant -> check(token).option($nin(Game.unanalysableVariants.map(_.id)))
-  ).noNull) sort lila.game.Query.sortCreated, math.min(200, nb)) flatMap
+  ).noNull) sort lila.game.Query.sortCreated, math.min(200, nb | 10)) flatMap
     gamesJson(withAnalysis, token) map { games =>
       Json.obj("list" -> games)
     }

modules/setup/src/main/package.scala

@@ -14,10 +14,10 @@ package object setup extends PackageObject with WithPlay with WithSocket {
 
     private[setup] implicit lazy val filterConfigTube = FilterConfig.tube
 
-    private[setup] implicit lazy val userConfigTube = 
+    private[setup] implicit lazy val userConfigTube =
       UserConfig.tube inColl Env.current.userConfigColl
 
-    private[setup] implicit lazy val anonConfigTube = 
+    private[setup] implicit lazy val anonConfigTube =
       UserConfig.tube inColl Env.current.anonConfigColl
   }
 }