Implement role connections API endpoints and objects

Backend/Remora.Discord.API.Abstractions/API/Objects/Applications/ApplicationRoleConnectionMetadataType.cs

@@ -0,0 +1,72 @@
+//
+//  ApplicationRoleConnectionMetadataType.cs
+//
+//  Author:
+//       Jarl Gullberg <jarl.gullberg@gmail.com>
+//
+//  Copyright (c) Jarl Gullberg
+//
+//  This program is free software: you can redistribute it and/or modify
+//  it under the terms of the GNU Lesser General Public License as published by
+//  the Free Software Foundation, either version 3 of the License, or
+//  (at your option) any later version.
+//
+//  This program is distributed in the hope that it will be useful,
+//  but WITHOUT ANY WARRANTY; without even the implied warranty of
+//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//  GNU Lesser General Public License for more details.
+//
+//  You should have received a copy of the GNU Lesser General Public License
+//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+//
+
+using JetBrains.Annotations;
+
+namespace Remora.Discord.API.Abstractions.Objects;
+
+/// <summary>
+/// Enumerates various application role connection metadata types.
+/// </summary>
+[PublicAPI]
+public enum ApplicationRoleConnectionMetadataType
+{
+    /// <summary>
+    /// The metadata value (integer) is less than or equal to the guild's configured value (integer).
+    /// </summary>
+    IntegerLessThanOrEqual = 1,
+
+    /// <summary>
+    /// The metadata value (integer) is greater than or equal to the guild's configured value (integer).
+    /// </summary>
+    IntegerGreaterThanOrEqual = 2,
+
+    /// <summary>
+    /// The metadata value (integer) is equal to the guild's configured value (integer).
+    /// </summary>
+    IntegerEqual = 3,
+
+    /// <summary>
+    /// The metadata value (integer) is not equal to the guild's configured value (integer).
+    /// </summary>
+    IntegerNotEqual = 4,
+
+    /// <summary>
+    /// The metadata value (ISO8601 string) is less than or equal to the guild's configured value (integer; days before current date).
+    /// </summary>
+    DateTimeLessThanOrEqual = 5,
+
+    /// <summary>
+    /// The metadata value (ISO8601 string) is greater than or equal to the guild's configured value (integer; days before current date).
+    /// </summary>
+    DateTimeGreaterThanOrEqual = 6,
+
+    /// <summary>
+    /// The metadata value (integer) is equal to the guild's configured value (integer; 1).
+    /// </summary>
+    BooleanEqual = 7,
+
+    /// <summary>
+    /// The metadata value (integer) is not equal to the guild's configured value (integer; 1).
+    /// </summary>
+    BooleanNotEqual = 8,
+}

Backend/Remora.Discord.API.Abstractions/API/Objects/Applications/IApplication.cs

@@ -133,6 +133,13 @@ public interface IApplication : IPartialApplication
     /// </summary>
     new Optional<Uri> CustomInstallUrl { get; }
 
+    /// <summary>
+    /// Gets the application's role connection verification entry point,
+    /// which when configured will render the app as a verification method
+    /// in the guild role verification configuration.
+    /// </summary>
+    new Optional<Uri> RoleConnectionsVerificationUrl { get; }
+
     /// <inheritdoc/>
     Optional<Snowflake> IPartialApplication.ID => this.ID;
 
@@ -185,11 +192,14 @@ public interface IApplication : IPartialApplication
     Optional<ApplicationFlags> IPartialApplication.Flags => this.Flags;
 
     /// <inheritdoc/>
-    Optional<IReadOnlyList<string>> IPartialApplication.Tags => throw new NotImplementedException();
+    Optional<IReadOnlyList<string>> IPartialApplication.Tags => this.Tags;
+
+    /// <inheritdoc/>
+    Optional<IApplicationInstallParameters> IPartialApplication.InstallParams => this.InstallParams;
 
     /// <inheritdoc/>
-    Optional<IApplicationInstallParameters> IPartialApplication.InstallParams => throw new NotImplementedException();
+    Optional<Uri> IPartialApplication.CustomInstallUrl => this.CustomInstallUrl;
 
     /// <inheritdoc/>
-    Optional<Uri> IPartialApplication.CustomInstallUrl => throw new NotImplementedException();
+    Optional<Uri> IPartialApplication.RoleConnectionsVerificationUrl => this.RoleConnectionsVerificationUrl;
 }

Backend/Remora.Discord.API.Abstractions/API/Objects/Applications/IApplicationRoleConnectionMetadata.cs

@@ -0,0 +1,67 @@
+//
+//  IApplicationRoleConnectionMetadata.cs
+//
+//  Author:
+//       Jarl Gullberg <jarl.gullberg@gmail.com>
+//
+//  Copyright (c) Jarl Gullberg
+//
+//  This program is free software: you can redistribute it and/or modify
+//  it under the terms of the GNU Lesser General Public License as published by
+//  the Free Software Foundation, either version 3 of the License, or
+//  (at your option) any later version.
+//
+//  This program is distributed in the hope that it will be useful,
+//  but WITHOUT ANY WARRANTY; without even the implied warranty of
+//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//  GNU Lesser General Public License for more details.
+//
+//  You should have received a copy of the GNU Lesser General Public License
+//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+//
+
+using System.Collections.Generic;
+using JetBrains.Annotations;
+using Remora.Rest.Core;
+
+namespace Remora.Discord.API.Abstractions.Objects;
+
+/// <summary>
+/// Represents an application role connection metadata field.
+/// </summary>
+[PublicAPI]
+public interface IApplicationRoleConnectionMetadata
+{
+    /// <summary>
+    /// Gets the type of metadata value.
+    /// </summary>
+    ApplicationRoleConnectionMetadataType Type { get; }
+
+    /// <summary>
+    /// Gets the dictionary key for the metadata field.
+    /// </summary>
+    /// <remarks>The key must only consist of a-z, 0-9 or _ and must have a length of max. 50 characters.</remarks>
+    string Key { get; }
+
+    /// <summary>
+    /// Gets the name of the metadata field.
+    /// </summary>
+    /// <remarks>The length of the name must be max. 100 characters.</remarks>
+    string Name { get; }
+
+    /// <summary>
+    /// Gets the localized names of the metadata field.
+    /// </summary>
+    Optional<IReadOnlyDictionary<string, string>> NameLocalizations { get; }
+
+    /// <summary>
+    /// Gets the description of the metadata field.
+    /// </summary>
+    /// <remarks>The length of the description must be max. 200 characters.</remarks>
+    string Description { get; }
+
+    /// <summary>
+    /// Gets the localized descriptions of the metadata field.
+    /// </summary>
+    Optional<IReadOnlyDictionary<string, string>> DescriptionLocalizations { get; }
+}

Backend/Remora.Discord.API.Abstractions/API/Objects/Applications/IPartialApplication.cs

@@ -92,4 +92,7 @@ public interface IPartialApplication
 
     /// <inheritdoc cref="IApplication.CustomInstallUrl" />
     Optional<Uri> CustomInstallUrl { get; }
+
+    /// <inheritdoc cref="IApplication.RoleConnectionsVerificationUrl" />
+    Optional<Uri> RoleConnectionsVerificationUrl { get; }
 }

Backend/Remora.Discord.API.Abstractions/API/Objects/Users/IApplicationRoleConnection.cs

@@ -0,0 +1,52 @@
+//
+//  IApplicationRoleConnection.cs
+//
+//  Author:
+//       Jarl Gullberg <jarl.gullberg@gmail.com>
+//
+//  Copyright (c) Jarl Gullberg
+//
+//  This program is free software: you can redistribute it and/or modify
+//  it under the terms of the GNU Lesser General Public License as published by
+//  the Free Software Foundation, either version 3 of the License, or
+//  (at your option) any later version.
+//
+//  This program is distributed in the hope that it will be useful,
+//  but WITHOUT ANY WARRANTY; without even the implied warranty of
+//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//  GNU Lesser General Public License for more details.
+//
+//  You should have received a copy of the GNU Lesser General Public License
+//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+//
+
+using System.Collections.Generic;
+using JetBrains.Annotations;
+
+namespace Remora.Discord.API.Abstractions.Objects;
+
+/// <summary>
+/// Represents a role connection that an application has attached to an user.
+/// </summary>
+[PublicAPI]
+public interface IApplicationRoleConnection
+{
+    /// <summary>
+    /// Gets the vanity name of the platform a bot has connected.
+    /// </summary>
+    /// <remarks>The length of the platform username must be max. 50 characters.</remarks>
+    string? PlatformName { get; }
+
+    /// <summary>
+    /// Gets the username on the platform a bot has connected.
+    /// </summary>
+    /// <remarks>The length of the platform username must be max. 100 characters.</remarks>
+    string? PlatformUsername { get; }
+
+    /// <summary>
+    /// Gets the object mapping of <see cref="IApplicationRoleConnectionMetadata.Key"/> to their stringified value
+    /// for the user on the platform a bot has connected.
+    /// </summary>
+    /// <remarks>The length of the stringified value must max. 100 characters.</remarks>
+    IReadOnlyDictionary<string, string> Metadata { get; }
+}

Backend/Remora.Discord.API.Abstractions/API/Rest/IDiscordRestApplicationAPI.cs

@@ -331,4 +331,33 @@ Task<Result<IGuildApplicationCommandPermissions>> EditApplicationCommandPermissi
         IReadOnlyList<IApplicationCommandPermissions> permissions,
         CancellationToken ct = default
     );
+
+    /// <summary>
+    /// Gets the application role connection metadata records for the given application..
+    /// </summary>
+    /// <param name="applicationID">The ID of the bot application.</param>
+    /// <param name="ct">The cancellation token for this operation.</param>
+    /// <returns>A retrieval result which may or may not have succeeded.</returns>
+    Task<Result<IReadOnlyList<IApplicationRoleConnectionMetadata>>> GetApplicationRoleConnectionMetadataRecordsAsync
+    (
+        Snowflake applicationID,
+        CancellationToken ct = default
+    );
+
+    /// <summary>
+    /// Updates the application role connection metadata records for the given application..
+    /// </summary>
+    /// <remarks>
+    /// An application can have a maximum of 5 metadata records.
+    /// </remarks>
+    /// <param name="applicationID">The ID of the bot application.</param>
+    /// <param name="records">The metadata records to overwrite the existing ones.</param>
+    /// <param name="ct">The cancellation token for this operation.</param>
+    /// <returns>An update result which may or may not have succeeded.</returns>
+    Task<Result<IReadOnlyList<IApplicationRoleConnectionMetadata>>> UpdateApplicationRoleConnectionMetadataRecordsAsync
+    (
+        Snowflake applicationID,
+        IReadOnlyList<IApplicationRoleConnectionMetadata> records,
+        CancellationToken ct = default
+    );
 }

Backend/Remora.Discord.API.Abstractions/API/Rest/IDiscordRestUserAPI.cs

@@ -130,10 +130,52 @@ Task<Result<IChannel>> CreateDMAsync
     /// <summary>
     /// Gets a list of connection objects.
     /// </summary>
+    /// <remarks>
+    /// Requires the "connections" OAuth" scope.
+    /// </remarks>
     /// <param name="ct">The cancellation token for this operation.</param>
     /// <returns>A retrieval result which may or may not have succeeded.</returns>
     Task<Result<IReadOnlyList<IConnection>>> GetUserConnectionsAsync
     (
         CancellationToken ct = default
     );
+
+    /// <summary>
+    /// Gets the application role connection for the user.
+    /// </summary>
+    /// <remarks>
+    /// Requires an OAuth2 access token with role_connections.write scope for the specified <paramref name="applicationID"/>.
+    /// </remarks>
+    /// <param name="applicationID">The ID of the application.</param>
+    /// <param name="ct">The cancellation token for this operation.</param>
+    /// <returns>A retrieval result which may or may not have succeeded.</returns>
+    Task<Result<IApplicationRoleConnection>> GetUserApplicationRoleConnectionAsync
+    (
+        Snowflake applicationID,
+        CancellationToken ct = default
+    );
+
+    /// <summary>
+    /// Updates and returns the application role connection for the user.
+    /// </summary>
+    /// <remarks>
+    /// Requires an OAuth2 access token with role_connections.write scope for the specified <paramref name="applicationID"/>.
+    /// </remarks>
+    /// <param name="applicationID">The ID of the application.</param>
+    /// <param name="platformName">The vanity name of the platform a bot has connected (max 50 characters).</param>
+    /// <param name="platformUsername">The username on the platform a bot has connected (max 100 characters).</param>
+    /// <param name="metadata">
+    /// The object mapping application role connection metadata keys to their stringified value (max 100 characters) for
+    /// the user on the platform a bot has connected.
+    /// </param>
+    /// <param name="ct">The cancellation token for this operation.</param>
+    /// <returns>A retrieval result which may or may not have succeeded.</returns>
+    Task<Result<IApplicationRoleConnection>> UpdateUserApplicationRoleConnectionAsync
+    (
+        Snowflake applicationID,
+        Optional<string> platformName = default,
+        Optional<string> platformUsername = default,
+        Optional<IReadOnlyDictionary<string, string>> metadata = default,
+        CancellationToken ct = default
+    );
 }

Backend/Remora.Discord.API/API/Objects/Applications/Application.cs

@@ -53,5 +53,6 @@ public record Application
     Optional<ApplicationFlags> Flags = default,
     Optional<IReadOnlyList<string>> Tags = default,
     Optional<IApplicationInstallParameters> InstallParams = default,
-    Optional<Uri> CustomInstallUrl = default
+    Optional<Uri> CustomInstallUrl = default,
+    Optional<Uri> RoleConnectionsVerificationUrl = default
 ) : IApplication;

Backend/Remora.Discord.API/API/Objects/Applications/ApplicationRoleConnectionMetadata.cs

@@ -0,0 +1,40 @@
+//
+//  ApplicationRoleConnectionMetadata.cs
+//
+//  Author:
+//       Jarl Gullberg <jarl.gullberg@gmail.com>
+//
+//  Copyright (c) Jarl Gullberg
+//
+//  This program is free software: you can redistribute it and/or modify
+//  it under the terms of the GNU Lesser General Public License as published by
+//  the Free Software Foundation, either version 3 of the License, or
+//  (at your option) any later version.
+//
+//  This program is distributed in the hope that it will be useful,
+//  but WITHOUT ANY WARRANTY; without even the implied warranty of
+//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//  GNU Lesser General Public License for more details.
+//
+//  You should have received a copy of the GNU Lesser General Public License
+//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+//
+
+using System.Collections.Generic;
+using JetBrains.Annotations;
+using Remora.Discord.API.Abstractions.Objects;
+using Remora.Rest.Core;
+
+namespace Remora.Discord.API.Objects;
+
+/// <inheritdoc cref="IApplicationRoleConnectionMetadata"/>
+[PublicAPI]
+public record ApplicationRoleConnectionMetadata
+(
+    string Key,
+    string Name,
+    string Description,
+    ApplicationRoleConnectionMetadataType Type,
+    Optional<IReadOnlyDictionary<string, string>> NameLocalizations = default,
+    Optional<IReadOnlyDictionary<string, string>> DescriptionLocalizations = default
+) : IApplicationRoleConnectionMetadata;

Backend/Remora.Discord.API/API/Objects/Applications/PartialApplication.cs

@@ -53,5 +53,6 @@ public record PartialApplication
     Optional<ApplicationFlags> Flags = default,
     Optional<IReadOnlyList<string>> Tags = default,
     Optional<IApplicationInstallParameters> InstallParams = default,
-    Optional<Uri> CustomInstallUrl = default
+    Optional<Uri> CustomInstallUrl = default,
+    Optional<Uri> RoleConnectionsVerificationUrl = default
 ) : IPartialApplication;