Merge pull request Vonage#167 from Nexmo/refactor

Adding type-safe webhooks and NCCOs. Adding application_id and has_application to Numbers API

Nexmo.Api/Nexmo.Api.nuspec

@@ -2,7 +2,7 @@
 <package>
   <metadata>
     <id>Nexmo.Csharp.Client</id>
-    <version>4.1.2</version>
+    <version>4.2.0</version>
     <title>Nexmo API Client</title>
     <authors>Nexmo</authors>
     <owners>Nexmo</owners>
@@ -12,10 +12,11 @@
     <requireLicenseAcceptance>false</requireLicenseAcceptance>
     <description>Official C#/.NET wrapper for the Nexmo API</description>
     <releaseNotes>
-      * Adding SMS Signing and Signing Validation support to SDK
-      * SMS Inbound message_timestamp changed from DateTime to String
-      * SMS Inbound property 'sig' added - only applicable when receiving Signed SMSs
-      * Introducing SMSSignatureGenrator for generating SMS Signatures - also has an Enum Method for signing Method (md5hash, md5, sha1, sha256, sha512)
+      * The NCCO component within the CallCommand object can now be a strongly typed Ncco rather than a JArray,
+      for the sake of backwards compatibility Ncco is left as a JArray but there is now an option to set a strongly typed Ncco object NccoObj instead
+      see https://developer.nexmo.com/voice/voice-api/code-snippets/make-an-outbound-call-with-ncco for a sample
+      * Adding type safety for NCCOs and webhook events
+      * Adding application_id and has_application to Numbers API
     </releaseNotes>
     <copyright>© Nexmo 2018</copyright>
     <tags>SMS voice telephony phone nexmo</tags>

Nexmo.Api/Number.cs

@@ -37,6 +37,17 @@ public class SearchRequest
             /// Optional. Page size (max 100, default 10). Ex: 25
             /// </summary>
             public string size { get; set; }
+
+            /// <summary>
+            /// Set this optional field to true to restrict your results to numbers associated with an application (any application).
+            /// Set to false to find all numbers not associated with any application. Omit the field to avoid filtering on whether or not the number is assigned to an application.
+            /// </summary>
+            public bool has_application { get; set; }
+
+            /// <summary>
+            /// The application that you want to return the numbers for
+            /// </summary>
+            public string application_id { get; set; }
         }
 
         public class NumberUpdateCommand

Nexmo.Api/Properties/AssemblyInfo.cs

@@ -34,5 +34,5 @@
 // You can specify all the values or you can default the Build and Revision Numbers 
 // by using the '*' as shown below:
 // [assembly: AssemblyVersion("1.0.*")]
-[assembly: AssemblyVersion("4.1.2.0")]
-[assembly: AssemblyFileVersion("4.1.2.0")]
+[assembly: AssemblyVersion("4.2.0.0")]
+[assembly: AssemblyFileVersion("4.2.0.0")]

Nexmo.Api/Voice/AnswerWebhooks/Answer.cs

@@ -0,0 +1,20 @@
+using Newtonsoft.Json;
+
+namespace Nexmo.Api.Voice.AnswerWebhooks
+{
+    public class Answer
+    {
+        [JsonProperty("to")]
+        public string To { get; set; }
+
+        [JsonProperty("from")]
+        public string From { get; set; }
+
+        [JsonProperty("uuid")]
+        public string Uuid { get; set; }
+
+        [JsonProperty("conversation_uuid")]
+        public string ConversationUuid { get; set; }
+
+    }
+}

Nexmo.Api/Voice/Call.cs

@@ -6,6 +6,7 @@
 using Newtonsoft.Json.Linq;
 using Nexmo.Api.Helpers;
 using Nexmo.Api.Request;
+using Nexmo.Api.Voice.Nccos;
 
 namespace Nexmo.Api.Voice
 {
@@ -52,6 +53,7 @@ public class Endpoint
             public string headers { get; set; }
         }
 
+        [JsonConverter(typeof(CallCommandConverter))]
         public class CallCommand
         {
             /// <summary>
@@ -70,7 +72,13 @@ public class CallCommand
             /// </summary>
             [RequiredIfAttribute("answer_url", null, ErrorMessage = "You must provide an NCCO object or an answer url")]
             [JsonProperty("ncco")]
-            public JArray Ncco { get; set; }
+            [Obsolete("this property will soon be deprecated - we recommend you use the strongly typed NccoObj field instead")]
+            public JArray Ncco { get; set; } //TODO on next major release remove this JArray
+
+            /// <summary>
+            /// This will convert to ncco as per the CallCommandConverter - it is preferable to use this over the JArray Ncco
+            /// </summary>
+            public Ncco NccoObj { get; set; }
             /// <summary>
             /// The webhook endpoint where you provide the Nexmo Call Control Object that governs this call. As soon as your user answers a call, Platform requests this NCCO from answer_url. Use answer_method to manage the HTTP method.
             /// </summary>
@@ -143,16 +151,21 @@ public class CallEditCommand
             /// <summary>
             /// Optional. A JSON object pointing to a replacement NCCO, when action is transfer.
             /// </summary>
+            [RequiredIf("Action", "transfer", ErrorMessage ="Desitnation required if transfering call")]
             [JsonProperty("destination")]
             public Destination Destination { get; set; }
         }
 
         public class Destination
         {
             [JsonProperty("type")]
-            public string Type { get; set; }
+            public string Type { get; set; } = "ncco";
+
             [JsonProperty("url")]
             public string[] Url { get; set; }
+
+            [JsonProperty("ncco")]
+            public Ncco Ncco { get; set; }
         }
 
         public class SearchFilter

Nexmo.Api/Voice/CallCommandConverter.cs

@@ -0,0 +1,56 @@
+using Newtonsoft.Json;
+using System;
+using System.Reflection;
+
+namespace Nexmo.Api.Voice
+{
+    public class CallCommandConverter : JsonConverter
+    {
+        public override bool CanWrite => true;
+        public override bool CanConvert(Type objectType)
+        {
+            return objectType == typeof(Call.CallCommand);
+        }
+
+        public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)
+        {
+            throw new NotImplementedException();
+        }
+
+        public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer)
+        {
+            const string NCCO = "ncco";
+            const string NCCO_OBJ = "NccoObj";
+            writer.WriteStartObject();
+            var nccoUsed = false;
+            foreach(var property in value.GetType().GetProperties(BindingFlags.Instance | BindingFlags.Public))
+            {
+                if(property.GetValue(value) == null || property.GetValue(value) is decimal && (decimal)property.GetValue(value) == (decimal)0.0)
+                {
+                    continue;
+                }
+                var propertyName = property.Name;
+                foreach(CustomAttributeData att in property.CustomAttributes)
+                {
+                    if(att.AttributeType.Name == "JsonPropertyAttribute")
+                    {
+                        propertyName = att.ConstructorArguments[0].Value.ToString();
+                        break;
+                    }
+                }
+                if ((propertyName == NCCO  || propertyName == NCCO_OBJ) && nccoUsed)
+                {
+                    continue;
+                }
+                else if(propertyName == NCCO || propertyName == NCCO_OBJ)
+                {
+                    nccoUsed = true;
+                    propertyName = "ncco";
+                }
+                writer.WritePropertyName(propertyName);
+                serializer.Serialize(writer, property.GetValue(value));
+            }
+            writer.WriteEndObject();
+        }
+    }
+}

Nexmo.Api/Voice/EventWebhooks/Answered.cs

@@ -0,0 +1,17 @@
+using Newtonsoft.Json;
+using System;
+
+namespace Nexmo.Api.Voice.EventWebhooks
+{
+    public class Answered : CallStatusEvent
+    {
+        [JsonProperty("start_time")]
+        public DateTime StartTime { get; set; }
+
+        [JsonProperty("rate")]
+        public string Rate { get; set; }
+
+        [JsonProperty("network")]
+        public string Network { get; set; }
+    }
+}

Nexmo.Api/Voice/EventWebhooks/Busy.cs

@@ -0,0 +1,7 @@
+namespace Nexmo.Api.Voice.EventWebhooks
+{
+    public class Busy : CallStatusEvent
+    {
+
+    }
+}

Nexmo.Api/Voice/EventWebhooks/CallStatusEvent.cs

@@ -0,0 +1,24 @@
+using Newtonsoft.Json;
+using Newtonsoft.Json.Converters;
+
+namespace Nexmo.Api.Voice.EventWebhooks
+{
+    public abstract class CallStatusEvent : Event
+    {
+        [JsonProperty("to")]
+        public string To { get; set; }
+
+        [JsonProperty("from")]
+        public string From { get; set; }
+
+        [JsonProperty("conversation_uuid")]
+        public string ConversationUuid { get; set; }
+
+        [JsonProperty("status")]
+        public string Status { get; set; }
+
+        [JsonProperty("direction")]
+        [JsonConverter(typeof(StringEnumConverter))]
+        public Direction Direction { get; set; }
+    }
+}

Nexmo.Api/Voice/EventWebhooks/Cancelled.cs

@@ -0,0 +1,6 @@
+namespace Nexmo.Api.Voice.EventWebhooks
+{
+    public class Cancelled : CallStatusEvent
+    {
+    }
+}

Nexmo.Api/Voice/EventWebhooks/Completed.cs

@@ -0,0 +1,30 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+using Newtonsoft.Json;
+
+namespace Nexmo.Api.Voice.EventWebhooks
+{
+    public class Completed : CallStatusEvent
+    {
+        [JsonProperty("end_time")]
+        public DateTime EndTime { get; set; }
+
+        [JsonProperty("network")]
+        public string Network { get; set; }
+
+        [JsonProperty("duration")]
+        public string Duration { get; set; }
+
+        [JsonProperty("start_time")]
+        public DateTime StartTime { get; set; }
+
+        [JsonProperty("rate")]
+        public string Rate { get; set; }
+
+        [JsonProperty("price")]
+        public string Price { get; set; }
+    }
+}

Nexmo.Api/Voice/EventWebhooks/Direction.cs

@@ -0,0 +1,8 @@
+namespace Nexmo.Api.Voice.EventWebhooks
+{
+    public enum Direction
+    {
+        inbound = 1,
+        outbound = 2
+    }
+}

Nexmo.Api/Voice/EventWebhooks/Error.cs

@@ -0,0 +1,13 @@
+using Newtonsoft.Json;
+
+namespace Nexmo.Api.Voice.EventWebhooks
+{
+    public class Error : EventBase
+    {
+        [JsonProperty("reason")]
+        public string Reason { get; set; }
+
+        [JsonProperty("conversation_uuid")]
+        public string ConversationUuid { get; set; }
+    }
+}

Nexmo.Api/Voice/EventWebhooks/Event.cs

@@ -0,0 +1,10 @@
+using Newtonsoft.Json;
+
+namespace Nexmo.Api.Voice.EventWebhooks
+{
+    public abstract class Event : EventBase
+    {
+        [JsonProperty("uuid")]
+        public virtual string Uuid { get; set; }
+    }
+}