feat: Add Permissions API support (#578)

Author: philrowan

.editorconfig

@@ -0,0 +1,4 @@
+[*.cs]
+
+# IDE1006: Naming Styles
+dotnet_diagnostic.IDE1006.severity = none

SendGrid.sln

@@ -23,6 +23,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SendGrid.Extensions.Depende
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{CADBDC30-FD3E-4FBA-B8F0-D3B6A1874FB9}"
 	ProjectSection(SolutionItems) = preProject
+		.editorconfig = .editorconfig
 		.env_sample = .env_sample
 		.gitignore = .gitignore
 		.travis.yml = .travis.yml

USE_CASES.md

@@ -25,6 +25,7 @@ This document provides examples for specific use cases. Please [open an issue](h
 - [How to transform HTML into plain text](#how-to-transform-html-into-plain-text)
 - [Send an Email With Twilio Email (Pilot)](#send-an-email-with-twilio-email-pilot)
 - [Send an SMS Message](#send-an-sms-message)
+- [Working With Permissions](#working-with-permissions)
 
 <a name="attachments"></a>
 # Attachments
@@ -1000,3 +1001,90 @@ namespace TwilioTest
     }
 }
 ```
+
+<a name="working-with-permissions" ></a>
+# Working with permissions
+
+The permissions builder is a convenient way to manipulate API key permissions when creating new API keys or managing existing API keys. 
+
+You can use the enums named according to the various [permissions](https://sendgrid.api-docs.io/v3.0/api-key-permissions) to add the scopes required for those permissions. 
+
+By default, all scopes for a given permission are added; however, You can filter out certain scopes by passing a ScopeOptions parameter or adding some filtering functions.
+
+For example, to create an API key for all *Alerts* scopes and read only *Marketing Campaigns*:
+
+```
+var apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY");
+var client = new SendGridClient(apiKey);
+var builder = new SendGridPermissionsBuilder();
+builder.AddPermissionsFor(SendGridPermission.Alerts);
+builder.AddPermissionsFor(SendGridPermission.MarketingCampaigns, ScopeOptions.ReadOnly);
+
+/*
+The above builder will emit the following scopes:
+
+alerts.create
+alerts.delete
+alerts.read
+alerts.update
+marketing_campaigns.read
+*/
+
+// now use the provided extension method to create an API key
+
+await client.CreateApiKey(builder, "Alerts & Read-Only Marketing Campaigns API Key");
+```
+
+There are also some methods to easily create API keys for various common use cases.
+
+For example, to create a Mail Send API key scoped for sending email:
+
+```
+var apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY");
+var client = new SendGridClient(apiKey);
+var builder = new SendGridPermissionsBuilder();
+builder.AddPermissionsFor(SendGridPermission.Mail);
+
+/*
+The above builder will emit the following scope:
+
+mail.batch.create
+mail.batch.delete
+mail.batch.read
+mail.batch.update
+mail.send
+*/
+
+await client.CreateApiKey(builder, "Mail Send API Key");
+```
+
+The builder filters out duplicate scopes by default but you can also add filters to the builder so that your application will never create keys with certain scopes.
+
+For example, you may want to allow an API key to do just about anything EXCEPT create more API keys.
+
+```
+var apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY");
+var client = new SendGridClient(apiKey);
+var builder = new SendGridPermissionsBuilder();
+builder.Exclude(scope => scope.StartsWith("api_keys"));
+builder.AddPermissionsFor(SendGridPermission.Admin);
+
+await client.CreateApiKey(builder, "Admin API Key that cannot manage other API keys");
+```
+
+The builder can also include individual scopes without having to use the AddPermissionsFor method.
+```
+var apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY");
+var client = new SendGridClient(apiKey);
+var builder = new SendGridPermissionsBuilder();
+/// use the method overload that accepts an IEnumerable<string>
+var myScopes = new []{
+    "mail.send", "alerts.read"
+}
+builder.Include(myScopes);
+
+/// or use the method overload that accepts a params string[]
+builder.Include("newsletter.read");
+
+await client.CreateApiKey(builder, "Mail send, Alerts & Newletter read");
+```

src/SendGrid/Permissions/ScopeOptions.cs

@@ -0,0 +1,19 @@
+namespace SendGrid.Permissions
+{
+    /// <summary>
+    /// Represents a set of possible scope options
+    /// </summary>
+    /// <seealso cref="string" />
+    public enum ScopeOptions
+    {
+        /// <summary>
+        /// All scopes. When filtering scopes no scopes will be exluded
+        /// </summary>
+        All,
+
+        /// <summary>
+        /// Read-only scopes. When fitlering scopes this will include only those that end with ".read"
+        /// </summary>
+        ReadOnly       
+    }
+}

src/SendGrid/Permissions/SendGridClientExtensions.cs

@@ -0,0 +1,50 @@
+using System.Linq;
+using System.Threading.Tasks;
+using Newtonsoft.Json;
+using Newtonsoft.Json.Linq;
+
+namespace SendGrid.Permissions
+{
+    /// <summary>
+    /// Utility extension methods that bridge the gap between the <see cref="ISendGridClient"/> and the <see cref="SendGridPermissionsBuilder"/>.
+    /// </summary>
+    public static class SendGridClientExtensions
+    {
+        /// <summary>
+        /// Create a permissions builder instance that masks the emitted scopes to exclude any scopes not
+        /// contained in the list of scopes already granted for the given API Key the <paramref name="client"/> was initialized with.
+        /// </summary>
+        /// <param name="client">The SendGrid client.</param>
+        /// <returns>A <see cref="SendGridPermissionsBuilder"/> instance.</returns>
+        public static async Task<SendGridPermissionsBuilder> CreateMaskedPermissionsBuilderForClient(this ISendGridClient client)
+        {
+            var response = await client.RequestAsync(method: SendGridClient.Method.GET, urlPath: "scopes");
+            var body = await response.DeserializeResponseBodyAsync(response.Body);
+            var userScopesJArray = (body["scopes"] as JArray);
+            var includedScopes = userScopesJArray.Values<string>().ToArray();
+            var builder = new SendGridPermissionsBuilder();
+            builder.Exclude(scope => !includedScopes.Contains(scope));
+            return builder;
+        }
+
+        /// <summary>
+        /// Create a new API key for the scopes contained in the <paramref name="permissions"/>.
+        /// </summary>
+        /// <param name="client">The SendGrid client.</param>
+        /// <param name="permissions">The permissions builder.</param>
+        /// <param name="name">The API key name.</param>
+        /// <returns>The <see cref="Response"/> from the SendGrid API call.</returns>
+        public static async Task<Response> CreateApiKey(this ISendGridClient client, SendGridPermissionsBuilder permissions, string name)
+        {
+            var scopes = permissions.Build();
+            var payload = new
+            {
+                name,
+                scopes
+            };
+            var data = JsonConvert.SerializeObject(payload);
+            var response = await client.RequestAsync(method: SendGridClient.Method.POST, urlPath: "api_keys", requestBody: data);
+            return response;
+        }
+    }
+}

src/SendGrid/Permissions/SendGridPermission.cs

@@ -0,0 +1,38 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace SendGrid.Permissions
+{
+#pragma warning disable CS1591 // Missing XML comment for publicly visible type or member
+    public enum SendGridPermission
+
+    {
+        Admin,
+        Alerts,
+        ApiKeys,
+        ASMGroups,
+        Billing,
+        Categories,
+        Clients,
+        Credentials,
+        DomainAuthentication,
+        IPs,
+        Mail,
+        MailSettings,
+        MarketingCampaigns,
+        Newsletter,
+        PartnerSettings,
+        ReverseDNS,
+        ScheduledSends,
+        Stats,
+        Subusers,
+        Suppressions,
+        Teammates,
+        Templates,
+        Tracking,
+        UserSettings,
+        Webhook
+    }
+#pragma warning restore CS1591 // Missing XML comment for publicly visible type or member
+}