Add notes about secret records and leaderboard timestamps

docs/core/records/account-records-v2.md

@@ -29,6 +29,7 @@ Gets records for the currently authenticated account.
 - This endpoint only works for the currently authenticated account, requesting others' records will result in error `403`. This feature is not supported when using a dedicated server account's token.
 - This endpoint is limited to the most recent 1,000 records driven by the currently authenticated account. Retrieving all historical records is not supported.
 - To retrieve records driven on Stunt maps (with the map type `TrackMania\TM_Stunt`), set the `gameMode` query parameter to `"Stunt"`.
+- If the map author has set a secret threshold score for their map, this endpoint will not return any actual `time` values for some entries. Instead, those leaderboard entries will contain `4294967295` in the `time` field. Additionally, the `url` link will result in a `403` error when requested.
 
 ---
 

docs/core/records/map-record.md

@@ -20,16 +20,20 @@ Gets a single map record using its primary identifier.
 ---
 
 **Remarks**:
+
 - This endpoint only accepts a `mapRecordId` - to retrieve it, you can use the [map records endpoint](/core/records/map-records).
+- If the map author has set a secret threshold score for their map, this endpoint will not return an actual `time` value. Instead, the response will contain `4294967295` in the `time` field. Additionally, the `url` link will result in a `403` error when requested.
 
 ---
 
 **Example request**:
+
 ```plain
 GET https://prod.trackmania.core.nadeo.online/mapRecords/ade1de4c-dd53-4a65-9d9b-89c5b1b9fa44
 ```
 
 **Example response**:
+
 ```json
 {
   "accountId": "04dd686d-0d2e-4c4c-bd37-81d57ae47656",

docs/core/records/map-records-v2.md

@@ -38,6 +38,7 @@ Gets map records for a set of accounts on a given map.
 - This endpoint has no intrinsic limit on the number of accounts requested, but it will return a 414 error if the request URI length is 8220 characters or more (e.g. corresponding to one map and just above 200 accounts, depending on how you encode the URI).
 - The `seasonId` parameter does not accept the value `"Personal_Best"`- to retrieve records on the PB leaderboards, simply omit the `seasonId` parameter from the URL.
 - Stunt and Platform maps (with the map type `TrackMania\TM_Stunt`/`Trackmania\TM_Platform`) require the `gameMode` parameter to be set to `"Stunt"`/`"Platform"`, otherwise the response will contain a "Not found" error.
+- If the map author has set a secret threshold score for their map, this endpoint will not return any actual `time` values for some entries. Instead, those leaderboard entries will contain `4294967295` in the `time` field. Additionally, the `url` link will result in a `403` error when requested.
 
 ---
 

docs/live/leaderboards/surround.md

@@ -53,6 +53,7 @@ Gets surrounding records for a score on a map's leaderboard.
 - This endpoint's response always includes the requested score as a fake record (using the requester's account information for the `accountId` and zone data) between the surrounding ones. This is because in-game this endpoint is used to determine surrounding records for your own PB (that might not have fully uploaded to the leaderboards yet), so it supports an arbitrary score value that the game sets based on your PB.
 - If the authenticated account has a record on the requested map, no scores lower than that record can be requested - it's recommended to use this endpoint with an account that does not have any records.
 - When using a Ubisoft account, the `score` parameter may be omitted to retrieve the player's PB leaderboard position and its surrounding data. When the authenticated player doesn't have a PB on the requested map (or when using a dedicated server account), any request without a `score` parameter will return an empty object (`{}`).
+- If the map author has set a secret threshold score for their map, this endpoint will not return any actual `score` values for some entries. Instead, those leaderboard entries will contain `-1` in the `score` field.
 
 ---
 

docs/live/leaderboards/top-club.md

@@ -44,6 +44,7 @@ Gets records from a map's leaderboard for members of a club.
 - The `groupUid` `"Personal_Best"` can be used to get the global leaderboard.
 - This endpoint only allows you to read a leaderboard's first 10,000 records. The rest of the leaderboard is not available at this level of detail.
 - If a `length` higher than `100` is requested, the API will successfully return only the first 100 records.
+- If the map author has set a secret threshold score for their map, this endpoint will not return any actual `score` values for some entries. Instead, those leaderboard entries will contain `-1` in the `score` field.
 
 ---
 

docs/live/leaderboards/top.md

@@ -40,19 +40,24 @@ Gets records from a map's leaderboard.
 ---
 
 **Remarks**:
+
 - The `groupUid` `"Personal_Best"` can be used to get the global leaderboard.
 - `onlyWorld=true` is required to retrieve more than the first five records. Without it, `length` and `offset` will have no effect.
 - This endpoint only allows you to read a leaderboard's first 10,000 records. The rest of the leaderboard is not available at this level of detail.
 - If a `length` higher than `100` is requested, the API will successfully return only the first 100 records.
+- As of December 11th 2024, this endpoint's response also contains a `timestamp` for each leaderboard entry, which corresponds to the time the relevant record was set.
+- If the map author has set a secret threshold score for their map, this endpoint will not return any actual `score` values for some entries. Instead, those leaderboard entries will contain `-1` in the `score` field.
 
 ---
 
 **Example request**:
+
 ```plain
 GET https://live-services.trackmania.nadeo.live/api/token/leaderboard/group/Personal_Best/map/ZJw6_4CItmVlRMPgELl4Q37Utw2/top?onlyWorld=true&length=10&offset=50
 ```
 
 **Example response**:
+
 ```json
 {
   "groupUid": "Personal_Best",
@@ -63,19 +68,21 @@ GET https://live-services.trackmania.nadeo.live/api/token/leaderboard/group/Pers
       "zoneName": "World",
       "top": [
         {
-          "accountId": "70febe5b-c279-4e1f-936f-0b02a0c6e757",
-          "zoneId": "3020a27d-7e13-11e8-8060-e284abfd2bc4",
-          "zoneName": "Norway",
+          "accountId": "6ec3711d-a722-4bc3-b952-96e80410b7ff",
+          "zoneId": "301fbe37-7e13-11e8-8060-e284abfd2bc4",
+          "zoneName": "Corrèze",
           "position": 51,
-          "score": 53156
+          "score": 53145,
+          "timestamp": 1658783398
         },
         ...
         {
-          "accountId": "21029447-5895-4e1e-829c-14dedb4af788",
-          "zoneId": "301f4e76-7e13-11e8-8060-e284abfd2bc4",
-          "zoneName": "Olomoucký kraj",
+          "accountId": "aa4e375f-d23e-4915-8d53-8b3307e06764",
+          "zoneId": "301ffccb-7e13-11e8-8060-e284abfd2bc4",
+          "zoneName": "Nürnberg",
           "position": 60,
-          "score": 53181
+          "score": 53158,
+          "timestamp": 1658772554
         }
       ]
     }