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; getUserConnections(access_token: string): Promise; + getUserRoleConnection(access_token: string, client_id?: string): Promise; + updateUserRoleConnection(opts: { + platformName?: string; + platformUsername?: string; + metadata?: { + [key: string]: string; + }; + accessToken: string; + clientId?: string; + }): Promise; 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} + */ + 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} + */ + 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