feat(ClientApplication): add role connections (#9072)

* feat: add add role connections

* feat: add add role connections

* fix: export new class in the index

* Update typings/rawDataTypes.d.ts

Co-authored-by: Aura Román <kyradiscord@gmail.com>

* chore: invite scope

* docs(ApplicationRoleConnectionMetadata): add docstring for the class

* docs(Constants): fix ApplicationRoleConnectionMetadataTypes jsdoc syntax

---------

Co-authored-by: Aura Román <kyradiscord@gmail.com>
Co-authored-by: SpaceEEC <spaceeec@yahoo.com>

src/index.js

@@ -73,6 +73,8 @@ exports.Activity = require('./structures/Presence').Activity;
 exports.AnonymousGuild = require('./structures/AnonymousGuild');
 exports.Application = require('./structures/interfaces/Application');
 exports.ApplicationCommand = require('./structures/ApplicationCommand');
+exports.ApplicationRoleConnectionMetadata =
+  require('./structures/ApplicationRoleConnectionMetadata').ApplicationRoleConnectionMetadata;
 exports.AutocompleteInteraction = require('./structures/AutocompleteInteraction');
 exports.AutoModerationActionExecution = require('./structures/AutoModerationActionExecution');
 exports.AutoModerationRule = require('./structures/AutoModerationRule');

src/structures/ApplicationRoleConnectionMetadata.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const { ApplicationRoleConnectionMetadataTypes } = require('../util/Constants');
+
+/**
+ * Role connection metadata object for an application.
+ */
+class ApplicationRoleConnectionMetadata {
+  constructor(data) {
+    /**
+     * The name of this metadata field
+     * @type {string}
+     */
+    this.name = data.name;
+
+    /**
+     * The name localizations for this metadata field
+     * @type {?Object<Locale, string>}
+     */
+    this.nameLocalizations = data.name_localizations ?? null;
+
+    /**
+     * The description of this metadata field
+     * @type {string}
+     */
+    this.description = data.description;
+
+    /**
+     * The description localizations for this metadata field
+     * @type {?Object<Locale, string>}
+     */
+    this.descriptionLocalizations = data.description_localizations ?? null;
+
+    /**
+     * The dictionary key for this metadata field
+     * @type {string}
+     */
+    this.key = data.key;
+
+    /**
+     * The type of this metadata field
+     * @type {ApplicationRoleConnectionMetadataType}
+     */
+    this.type = typeof data.type === 'number' ? ApplicationRoleConnectionMetadataTypes[data.type] : data.type;
+  }
+}
+
+exports.ApplicationRoleConnectionMetadata = ApplicationRoleConnectionMetadata;

src/structures/ClientApplication.js

@@ -1,9 +1,11 @@
 'use strict';
 
+const { ApplicationRoleConnectionMetadata } = require('./ApplicationRoleConnectionMetadata');
 const Team = require('./Team');
 const Application = require('./interfaces/Application');
 const ApplicationCommandManager = require('../managers/ApplicationCommandManager');
 const ApplicationFlags = require('../util/ApplicationFlags');
+const { ApplicationRoleConnectionMetadataTypes } = require('../util/Constants');
 const Permissions = require('../util/Permissions');
 
 /**
@@ -136,6 +138,48 @@ class ClientApplication extends Application {
     this._patch(app);
     return this;
   }
+
+  /**
+   * Gets this application's role connection metadata records
+   * @returns {Promise<ApplicationRoleConnectionMetadata[]>}
+   */
+  async fetchRoleConnectionMetadataRecords() {
+    const metadata = await this.client.api.applications(this.client.user.id)('role-connections').metadata.get();
+    return metadata.map(data => new ApplicationRoleConnectionMetadata(data));
+  }
+
+  /**
+   * Data for creating or editing an application role connection metadata.
+   * @typedef {Object} ApplicationRoleConnectionMetadataEditOptions
+   * @property {string} name The name of the metadata field
+   * @property {?Object<Locale, string>} [nameLocalizations] The name localizations for the metadata field
+   * @property {string} description The description of the metadata field
+   * @property {?Object<Locale, string>} [descriptionLocalizations] The description localizations for the metadata field
+   * @property {string} key The dictionary key of the metadata field
+   * @property {ApplicationRoleConnectionMetadataType} type The type of the metadata field
+   */
+
+  /**
+   * Updates this application's role connection metadata records
+   * @param {ApplicationRoleConnectionMetadataEditOptions[]} records The new role connection metadata records
+   * @returns {Promise<ApplicationRoleConnectionMetadata[]>}
+   */
+  async editRoleConnectionMetadataRecords(records) {
+    const newRecords = await this.client.api
+      .applications(this.client.user.id)('role-connections')
+      .metadata.put({
+        data: records.map(record => ({
+          type: typeof record.type === 'string' ? ApplicationRoleConnectionMetadataTypes[record.type] : record.type,
+          key: record.key,
+          name: record.name,
+          name_localizations: record.nameLocalizations,
+          description: record.description,
+          description_localizations: record.descriptionLocalizations,
+        })),
+      });
+
+    return newRecords.map(data => new ApplicationRoleConnectionMetadata(data));
+  }
 }
 
 module.exports = ClientApplication;

src/structures/interfaces/Application.js

@@ -56,6 +56,16 @@ class Application extends Base {
     } else {
       this.icon ??= null;
     }
+
+    if ('role_connections_verification_url' in data) {
+      /**
+       * This application's role connection verification entry point URL
+       * @type {?string}
+       */
+      this.roleConnectionsVerificationURL = data.role_connections_verification_url;
+    } else {
+      this.roleConnectionsVerificationURL ??= null;
+    }
   }
 
   /**

src/util/Constants.js

@@ -499,6 +499,7 @@ exports.WSEvents = keyMirror([
  * * `guilds.join`: allows the bot to join the user to any guild it is in using Guild#addMember
  * * `gdm.join`: allows joining the user to a group dm
  * * `webhook.incoming`: generates a webhook to a channel
+ * * `role_connections.write`: allows your app to update a user's connection and metadata for the app
  * @typedef {string} InviteScope
  * @see {@link https://discord.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes}
  */
@@ -515,6 +516,7 @@ exports.InviteScopes = [
   'guilds.join',
   'gdm.join',
   'webhook.incoming',
+  'role_connections.write',
 ];
 
 // TODO: change Integration#expireBehavior to this and clean up Integration
@@ -1245,6 +1247,35 @@ exports.ApplicationCommandOptionTypes = createEnum([
  */
 exports.ApplicationCommandPermissionTypes = createEnum([null, 'ROLE', 'USER']);
 
+/**
+ * Each metadata type offers a comparison operation that allows
+ * guilds to configure role requirements based on metadata values stored by the bot.
+ * Bots specify a metadata value for each user and guilds specify
+ * the required guild's configured value within the guild role settings.
+ * All available channel types:
+ * * INTEGER_LESS_THAN_OR_EQUAL
+ * * INTEGER_GREATER_THAN_OR_EQUAL
+ * * INTEGER_EQUAL
+ * * INTEGER_NOT_EQUAL
+ * * DATATIME_LESS_THAN_OR_EQUAL
+ * * DATATIME_GREATER_THAN_OR_EQUAL
+ * * BOOLEAN_EQUAL
+ * * BOOLEAN_NOT_EQUAL
+ * @typedef {string} ApplicationRoleConnectionMetadataType
+ * @see{@link https://discord.com/developers/docs/resources/application-role-connection-metadata#application-role-connection-metadata-object-application-role-connection-metadata-type}
+ */
+exports.ApplicationRoleConnectionMetadataTypes = createEnum(
+  null,
+  'INTEGER_LESS_THAN_OR_EQUAL',
+  'INTEGER_GREATER_THAN_OR_EQUAL',
+  'INTEGER_EQUAL',
+  'INTEGER_NOT_EQUAL',
+  'DATATIME_LESS_THAN_OR_EQUAL',
+  'DATATIME_GREATER_THAN_OR_EQUAL',
+  'BOOLEAN_EQUAL',
+  'BOOLEAN_NOT_EQUAL',
+);
+
 /**
  * The type of an {@link AutoModerationRuleTriggerTypes} object:
  * * KEYWORD
@@ -1487,6 +1518,7 @@ function createEnum(keys) {
  * The type of an {@link ApplicationCommandPermissions} object.
  * @property {Object<ApplicationCommandType, number>} ApplicationCommandTypes
  * The type of an {@link ApplicationCommand} object.
+ * @property {Object<ApplicationRoleConnectionMetadataType, number>} ApplicationRoleConnectionMetadataTypes
  * @property {Object<AutoModerationRuleTriggerType, number>} AutoModerationRuleTriggerTypes Characterizes the type
  * of content which can trigger the rule.
  * @property {Object<AutoModerationActionType, number>} AutoModerationActionTypes