From eb987c2fce5da87aa4610220c7bd4721510c9655 Mon Sep 17 00:00:00 2001 From: zkldi Date: Wed, 21 Jul 2021 21:09:03 +0100 Subject: [PATCH 1/5] Add documentation for more user-gamept endpoints --- docs/docs/api/routes/user-gamept.md | 139 ++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) diff --git a/docs/docs/api/routes/user-gamept.md b/docs/docs/api/routes/user-gamept.md index 37354b5aa..c362c310b 100644 --- a/docs/docs/api/routes/user-gamept.md +++ b/docs/docs/api/routes/user-gamept.md @@ -600,4 +600,143 @@ GET /api/v1/users/zkldi/games/iidx/SP/sessions/highlighted highlight: true }, ] +``` + +***** + +## Get a user's most played charts. + +`GET /api/v1/users/:userID/games/:game/:playtype/most-played` + +### Parameters + +None. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `songs` | Array<SongDocument> | The array of songs related to the pbs. | +| `charts` | Array<ChartDocument> | The array of charts related to the pbs. | +| `pbs` | Array<(PBDocument & {__playcount: integer})> | An array of PB documents with the `__playcount` property attached. This property dictates how many times the user has played this chart. | + +### Example + +#### Request +``` +GET /api/v1/users/zkldi/games/iidx/SP/most-played +``` + +#### Response + +```js +{ + songs: [{ + id: 1, + title: "5.1.1.", + // ... + }, { + id: 2, + title: "GAMBOL", + // ... + }], + charts: [{ + songID: 1, + difficulty: "ANOTHER", + // ... + }, { + songID: 2, + difficulty: "LEGGENDARIA", + // ... + }, { + songID: 1, + difficulty: "HYPER", + }], + pbs: [{ + chartID: "something", + __playcount: 5, + // ... + }, { + chartID: "something_else", + __playcount: 2, + // ... + }, { + chartID: "something_more", + __playcount: 1, + // ... + }] +} +``` + +***** + +## Retrieve a leaderboard around a user. + +`GET /api/v1/users/:userID/games/:game/:playtype/leaderboard-adjacent` + +### Parameters + +| Property | Type | Description | +| :: | :: | :: | +| `alg` | String (Optional) | Optionally, you can provide an override algorithm to use for the leaderboards instead of the game+playtype default. | + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `above` | Array<UserGameStats> | Up to 5 users' game stats better than this user. | +| `below` | Array<UserGameStats> | Same as above, but below the user. | +| `users` | Array<UserDocument> | The user documents related to the above statistics. | +| `yourStats` | UserGameStats | The requested user's stats for this game. | + +### Example + +#### Request +``` +GET /api/v1/users/zkldi/games/iidx/SP/leaderboard-adjacent +``` + +#### Response + +```js +{ + above: [{ + userID: 2, + ratings: { + ktRating: 9 + }, + classes: { + dan: 10 + }, + // ... + }], + below: [{ + userID: 3, + ratings: { + ktRating: 1 + }, + classes: { + dan: 5 + }, + // ... + }], + users: [{ + userID: 2, + username: "sptmgtm", + // ... + }, { + userID: 3, + username: "neil.c", + // ... + }], + thisUsersStats: { + userID: 1, + ratings: { + ktRating: 5 + }, + classes: { + dan: 5 + } + } +} ``` \ No newline at end of file From c9e809f3168b03efc978a37ba50ec59ba841b704 Mon Sep 17 00:00:00 2001 From: zkldi Date: Thu, 22 Jul 2021 00:44:21 +0100 Subject: [PATCH 2/5] change some field names in leaderboards-adjacent --- docs/docs/api/routes/user-gamept.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/docs/api/routes/user-gamept.md b/docs/docs/api/routes/user-gamept.md index c362c310b..8f43d1ca0 100644 --- a/docs/docs/api/routes/user-gamept.md +++ b/docs/docs/api/routes/user-gamept.md @@ -687,7 +687,8 @@ GET /api/v1/users/zkldi/games/iidx/SP/most-played | `above` | Array<UserGameStats> | Up to 5 users' game stats better than this user. | | `below` | Array<UserGameStats> | Same as above, but below the user. | | `users` | Array<UserDocument> | The user documents related to the above statistics. | -| `yourStats` | UserGameStats | The requested user's stats for this game. | +| `thisUsersStats` | UserGameStats | The requested user's stats for this GPT. | +| `thisUsersRanking` | {outOf: integer, ranking: integer} | The requested user's ranking for this GPT. | ### Example @@ -737,6 +738,10 @@ GET /api/v1/users/zkldi/games/iidx/SP/leaderboard-adjacent classes: { dan: 5 } + }, + thisUsersRanking: { + ranking: 2, + outOf: 3 } } ``` \ No newline at end of file From 0d8f2f152ff24e155ed95cb97cae2186e8dde6f5 Mon Sep 17 00:00:00 2001 From: zkldi Date: Thu, 22 Jul 2021 00:46:09 +0100 Subject: [PATCH 3/5] add api notable terminology --- docs/docs/api/terminology.md | 12 ++++++++++++ docs/mkdocs.yml | 1 + 2 files changed, 13 insertions(+) create mode 100644 docs/docs/api/terminology.md diff --git a/docs/docs/api/terminology.md b/docs/docs/api/terminology.md new file mode 100644 index 000000000..ffbf2c849 --- /dev/null +++ b/docs/docs/api/terminology.md @@ -0,0 +1,12 @@ +# Notable Terminology + +Similar to the userland terminology document - Tachi has some internal terminology that you should +be familiar with. + +## GPT + +Refers to "Game + Playtype" - a combination of a game and its playtype. + +## UGPT + +Refers to "User on Game + Playtype" - A user's "something" on a game and that playtype. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 273e4e599..257e3b76a 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -43,6 +43,7 @@ nav: - API Reference: - "api/overview.md" - "api/auth.md" + - "api/terminology.md" - Endpoints: - "api/routes/example.md" From 7b6651e455d0235a72630dbc929d2d0a0dcfad15 Mon Sep 17 00:00:00 2001 From: zkldi Date: Wed, 11 Aug 2021 17:57:37 +0100 Subject: [PATCH 4/5] Create LICENSE --- docs/LICENSE | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 docs/LICENSE diff --git a/docs/LICENSE b/docs/LICENSE new file mode 100644 index 000000000..ae481f07a --- /dev/null +++ b/docs/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2021 zkldi + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. From f840c2cce940724a079c314929150479cb27d5fc Mon Sep 17 00:00:00 2001 From: zkldi Date: Thu, 12 Aug 2021 19:21:15 +0100 Subject: [PATCH 5/5] Add user integrations --- docs/docs/api/routes/user-integrations.md | 182 ++++++++++++++++++++++ docs/docs/api/routes/users.md | 2 +- docs/docs/user/rules.md | 14 +- docs/mkdocs.yml | 1 + 4 files changed, 191 insertions(+), 8 deletions(-) create mode 100644 docs/docs/api/routes/user-integrations.md diff --git a/docs/docs/api/routes/user-integrations.md b/docs/docs/api/routes/user-integrations.md new file mode 100644 index 000000000..df1f01617 --- /dev/null +++ b/docs/docs/api/routes/user-integrations.md @@ -0,0 +1,182 @@ +# User Integrations + +These endpoints are related to a users integrations with external services. + +***** + +## Retrieve whether this user is authenticated with this kaiType. + +`GET /api/v1/users/:userID/integrations/kai/:kaiType` + +**Kamaitachi Only** + +!!! note + A KaiType is either "flo", "min", or "eag". Since these three services + share backends, they all use the same authentication mechanisms, and share + endpoints like this. + +### Permissions + +- Self-key: This request must be made using Cookie authentication, which means it cannot be used with API keys. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `authStatus` | boolean | True if the user is authenticated with this kaiType, false if they are not. | + +### Example + +#### Request +``` +GET /api/v1/users/1/integrations/kai/flo +``` + +#### Response + +```js +{ + authStatus: false +} +``` + +***** + +## Update a user's access_token and refresh_token from an intermediate code. + +`POST /api/v1/users/:userID/integrations/kai/:kaiType/oauth2callback` + +!!! info + This is used as part of an [OAuth2 Flow](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2). + + The client controls the callback link after authentication with the service, and then POSTs the returned `code` to us. + This part of the flow actually updates the user. + +### Permissions + +- Self-key + +### Parameters + +| Property | Type | Description | +| :: | :: | :: | +| `code` | string | The intermediate code to use to get the access_token and refresh_token. | + +### Response + +Empty object for body. 200 on success, not 200 on failure - status code depending on error. + +### Example + +#### Request +```js +{ + code: "This_Is_An_1nT3rMeDIate_Code" +} +``` + +#### Response + +```js +{} +``` + +***** + +## Retrieve a users ARC integrations. + +`GET /api/v1/users/:userID/integrations/arc` + +**Kamaitachi Only** + +### Permissions + +- Self-Key + +### Parameters + +None. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `iidx` | ArcAuthDoc \| null | Whether this user is authenticated for `api/arc-iidx` or not. | +| `sdvx` | See above | See above, but for `api/arc-sdvx`. | + +### Example + +#### Request +``` +GET /api/v1/users/1/integrations/arc +``` + +#### Response + +```js +{ + iidx: { + userID: 1, + accountID: "arc_account_id_here", + forImportType: "api/arc-iidx" + }, + sdvx: null +} +``` + +***** + +## Update ARC Integrations + +`PATCH /api/v1/users/:userID/integrations/arc` + +### Permissions + +- Self-Key + +### Parameters + +| Property | Type | Description | +| :: | :: | :: | +| `iidx` | Optional, String or Null | Change your configured AccountID for ARC IIDX. If not present, change nothing. If null, remove link, if string, update accountID. | +| `sdvx` | Optional, String or Null | See above, but for SDVX | + + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `iidx` | ArcAuthDoc \| null | This user's current ArcAuthDoc (or null) for IIDX. | +| `sdvx` | ArcAuthDoc \| null | This user's current ArcAuthDoc (or null) for SDVX. | + +### Example + +#### Request +```js +PATCH /api/v1/users/1/integrations/arc + +--- +{ + iidx: "newAccountID", + sdvx: null, // remove this account ID. +} +``` + +#### Response +```js +{ + iidx: { + forImportType: "api/arc-iidx", + accountID: "newAccountID", + userID: 1 + }, + sdvx: null +} +``` + +!!! warn + This endpoint doesn't do any checking on the `accountID` parameter to check whether it actually + works with ARC. There is also no checking to see whether you're the owner of this account. + + Of course, this means you could trivially cheat by pointing your account at someone elses. + This would be a violation of R2, and result in an account ban. diff --git a/docs/docs/api/routes/users.md b/docs/docs/api/routes/users.md index f374fa543..0b06e09db 100644 --- a/docs/docs/api/routes/users.md +++ b/docs/docs/api/routes/users.md @@ -6,7 +6,7 @@ These endpoints are related to users in general. ## List Users -` /api/v1/users` +`/api/v1/users` ### Parameters diff --git a/docs/docs/user/rules.md b/docs/docs/user/rules.md index 4c9e2d08b..9d3d60687 100644 --- a/docs/docs/user/rules.md +++ b/docs/docs/user/rules.md @@ -4,7 +4,7 @@ To ensure that the score tracker stays accurate, and everyone has a nice time, Tachi enforces some rules. -## Be civil. +## R1: Be civil. In various places in Tachi you may write things, such as comments on your scores, or a profile about me. @@ -20,7 +20,7 @@ The punishment for this ranges from warnings to permanent bans, depending on the Generally, just be a nice person. Please! -## You **MUST NOT** deliberately fake score submissions to Tachi. +## R2: You **MUST NOT** deliberately fake score submissions to Tachi. The punishment for this is an instant, permanent IP ban. @@ -43,7 +43,7 @@ may be warned. You do not get a second chance. If you fake scores, you revoke all access to the tracker. -## You **MUST NOT** play on invalid input devices. +## R3: You **MUST NOT** play on invalid input devices. Games on Tachi have specific requirements for what kind of setups are 'legitimate'. That means that you **SHOULD NOT** @@ -78,7 +78,7 @@ The valid input devices are listed below. | BMS (14K) | any two IIDX Controllers | Keyboard play is **NOT** allowed for BMS 14K. | -## Do not harm other people in the community. +## R4: Do not harm other people in the community. This rule is depressing to write, but it has to be said. @@ -114,13 +114,13 @@ which includes, **but is not limited to**: stupid.) - Not liking another community member. -## You are only allowed one account. +## R5: You are only allowed one account. Do not make multiple accounts, we track account IPs and it lets us know. This is to keep the leaderboards fair and avoid one player from taking up multiple spaces. -## Do not set NSFW artwork as your avatar or banner. +## R6: Do not set NSFW artwork as your avatar or banner. Tachi does not allow you to set suggestive or NSFW artwork as your avatar or banner. Your avatar will be @@ -132,7 +132,7 @@ deleted and you will be warned. Uploading illegal (under international common or EU law) material will result in an immediate permanent ban. -## Use Common Sense. +## R7: Use Common Sense. This list of rules isn't exhaustive, and staff reserve the right to ban you at any time for any reason. You should use diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 257e3b76a..f544aaaee 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -52,6 +52,7 @@ nav: - "api/routes/auth.md" - "api/routes/users.md" - "api/routes/user-gamept.md" + - "api/routes/user-integrations.md" - "api/routes/sessions.md" - "api/routes/scores.md" - "api/routes/search.md"