From 33e290e5a9e573169c90ee102e14f4bf2694c280 Mon Sep 17 00:00:00 2001
From: MarkusRost <37275477+Markus-Rost@users.noreply.github.com>
Date: Fri, 19 Jul 2024 14:16:44 +0200
Subject: [PATCH] Add application role connections

---
 README.md    | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 index.d.ts   | 18 ++++++++++++
 lib/oauth.js | 52 ++++++++++++++++++++++++++++++++
 3 files changed, 153 insertions(+)

diff --git a/README.md b/README.md
index 7703863..b5b93aa 100644
--- a/README.md
+++ b/README.md
@@ -228,6 +228,89 @@ oauth.getUserConnections(access_token).then(console.log);
 */
 ```
 
+### `getUserRoleConnection(access_token, client_id)`
+
+`access_token`: The user's access token.
+
+`client_id`: Your application's client id. Can be omitted if provided on the client constructor.
+
+Requires the `role_connections.write` OAuth2 scope.
+
+Returns the [application role connection](https://discord.com/developers/docs/resources/user#application-role-connection-object) object for the user.
+
+```js
+const DiscordOauth2 = require("discord-oauth2");
+const oauth = new DiscordOauth2({
+	clientId: "332269999912132097",
+});
+
+const access_token = "6qrZcUqja7812RVdnEKjpzOL4CvHBFG";
+
+oauth.getUserRoleConnection(access_token).then(console.log);
+/*
+	{
+		platform_name: 'Example Linked Role Discord Bot',
+		platform_username: null,
+		metadata: {
+			cookieseaten: '1483',
+			allergictonuts: '0',
+			firstcookiebaked: '2003-12-20'
+		}
+	}
+*/
+```
+
+### `updateUserRoleConnection(object)`
+
+Update the application role connection for the user.
+
+Takes an object with the following properties (required):
+
+`accessToken`: The user access token.
+
+Optional:
+
+`platformName`: The vanity name of the platform the bot has connected.
+
+`platformUsername`: The username on the platform the bot has connected.
+
+`metadata`: Object mapping [application role connection metadata](https://discord.com/developers/docs/resources/application-role-connection-metadata#application-role-connection-metadata-object) keys to their string-ified value for the user on the platform the bot has connected.
+
+`clientId`: Your application's client id. Can be omitted if provided on the client constructor.
+
+Requires the `role_connections.write` OAuth2 scope.
+
+Returns the [application role connection](https://discord.com/developers/docs/resources/user#application-role-connection-object) object for the user.
+
+```js
+const DiscordOauth2 = require("discord-oauth2");
+const oauth = new DiscordOauth2({
+	clientId: "332269999912132097",
+});
+
+oauth.updateUserRoleConnection({
+	accessToken: "6qrZcUqja7812RVdnEKjpzOL4CvHBFG",
+	platformName: "Example Linked Role Discord Bot",
+	platformUsername: "Example Username",
+	metadata: {
+		cookieseaten: "1483",
+		allergictonuts: "0",
+		firstcookiebaked: "2003-12-20",
+	},
+}).then(console.log);
+/*
+	{
+		platform_name: 'Example Linked Role Discord Bot',
+		platform_username: 'Example Username',
+		metadata: {
+			cookieseaten: '1483',
+			allergictonuts: '0',
+			firstcookiebaked: '2003-12-20'
+		}
+	}
+*/
+```
+
 ### `addMember(object)`
 
 Force join a user to a guild.
diff --git a/index.d.ts b/index.d.ts
index da0b518..019d6d1 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -75,6 +75,14 @@ declare namespace OAuth {
 		bot?: User;
 	}
 
+	export interface RoleConnection {
+		platform_name: string | null;
+		platform_username: string | null;
+		metadata: {
+			[key: string]: string;
+		};
+	}
+
 	export interface TokenRequestResult {
 		access_token: string;
 		token_type: string;
@@ -175,6 +183,16 @@ declare class OAuth extends EventEmitter {
 		withCounts?: boolean;
 	}): Promise<OAuth.PartialGuild[]>;
 	getUserConnections(access_token: string): Promise<OAuth.Connection[]>;
+	getUserRoleConnection(access_token: string, client_id?: string): Promise<OAuth.RoleConnection>;
+	updateUserRoleConnection(opts: {
+		platformName?: string;
+		platformUsername?: string;
+		metadata?: {
+			[key: string]: string;
+		};
+		accessToken: string;
+		clientId?: string;
+	}): Promise<OAuth.RoleConnection>;
 	addMember(opts: {
 		deaf?: boolean;
 		mute?: boolean;
diff --git a/lib/oauth.js b/lib/oauth.js
index d9fe47f..6538193 100644
--- a/lib/oauth.js
+++ b/lib/oauth.js
@@ -198,6 +198,58 @@ class OAuth extends RequestHandler {
 		});
 	}
 
+	/**
+	 * Request the application role connection for the user
+	 * Requires the `role_connections.write` scope
+	 * @arg {String} access_token The user access token
+	 * @arg {String} [client_id] Your application's client id
+	 * @returns {Promise<Object>}
+	 */
+	getUserRoleConnection(access_token, client_id) {
+		client_id = client_id || this.clientId;
+		return this.request(
+			"GET",
+			`/users/@me/applications/${client_id}/role-connection`,
+			undefined,
+			{
+				auth: {
+					type: "Bearer",
+					creds: access_token,
+				},
+			},
+		);
+	}
+
+	/**
+	 * Update the application role connection for the user
+	 * Requires the `role_connections.write` scope
+	 * @arg {Object} options
+	 * @arg {String?} options.platformName The name of the platform
+	 * @arg {String?} options.platformUsername The username on the platform
+	 * @arg {Object?} options.metadata The metadata keys mapped to their stringified values
+	 * @arg {String} options.accessToken The user access token
+	 * @arg {String?} options.clientId Your application's client id
+	 * @returns {Promise<Object>}
+	 */
+	updateUserRoleConnection(options) {
+		const client_id = options.clientId || this.clientId;
+		return this.request(
+			"PUT",
+			`/users/@me/applications/${client_id}/role-connection`,
+			{
+				platform_name: options.platformName,
+				platform_username: options.platformUsername,
+				metadata: options.metadata,
+			},
+			{
+				auth: {
+					type: "Bearer",
+					creds: access_token,
+				},
+			},
+		);
+	}
+
 	/**
 	 * Force a user to join a guild
 	 * Requires the `guilds.join` scope