From f840c2cce940724a079c314929150479cb27d5fc Mon Sep 17 00:00:00 2001 From: zkldi Date: Thu, 12 Aug 2021 19:21:15 +0100 Subject: [PATCH] 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"