fix: async transcribe prerecorded result (#111)

* Adding methods and return object for Prerecorded transcription with callback for completion.

* Tests pass

* Some cleanup, new tests pass, commenting interface.

* Fixing broken queryparam test.

* Fixing docs.
Marking all async tests as Tasks instead of voids.

* Changing test names to match project standard.

* Fixing casing error on intellisense summary comments for IPrerecordedTranscriptionClient.

* Making sure the tests use the urlSource instead of regenerating a callback url over and over.

* The same as last

* Adding support for actually using the old options.Callback parameter, as long as callbackUrl is sent as null/empty in async call.

* Adding check to make sure the correct method is called if async transcription is requested.

* Reverting breaking change when calling with GetTranscriptionResult with no callbackUrl argument but with Callback set in the options object.
Now works as previously.

* Fixing conflict and validating tests.

Deepgram.Tests/ClientTests/PrerecordedTranscriptionTests.cs

@@ -2,25 +2,32 @@
 using Deepgram.Models;
 using Deepgram.Request;
 using Deepgram.Tests.Fakes;
+using System.IO;
+using System.Threading.Tasks;
+using System;
+using Xunit;
 
 namespace Deepgram.Tests.ClientTests
 {
     public class PrerecordedTranscriptionTests
     {
-        PrerecordedTranscriptionOptions _prerecordedTranscriptionOptions;
-        UrlSource _urlSource;
+        private readonly PrerecordedTranscriptionOptions _prerecordedTranscriptionOptions;
+        private readonly UrlSource _urlSource;
+        private readonly Faker _faker = new();
+
         public PrerecordedTranscriptionTests()
         {
             _prerecordedTranscriptionOptions = new PrerecordedTranscriptionOptionsFaker().Generate();
             _urlSource = new UrlSource(new Faker().Internet.Url());
         }
 
         [Fact]
-        public async void GetTransaction_Should_Return_PrerecordedTranscription_When_UrlSource_Present()
+        public async Task GetTransaction_Should_Return_PrerecordedTranscription_When_UrlSource_Present()
         {
             //Arrange 
             var fakePrecordedTranscription = new AutoFaker<PrerecordedTranscription>().Generate();
             var SUT = GetDeepgramClient(fakePrecordedTranscription);
+            _prerecordedTranscriptionOptions.Callback = null;
 
             //Act
             var result = await SUT.Transcription.Prerecorded.GetTranscriptionAsync(_urlSource, _prerecordedTranscriptionOptions);
@@ -33,12 +40,13 @@ public async void GetTransaction_Should_Return_PrerecordedTranscription_When_Url
         }
 
         [Fact]
-        public async void GetTransaction_Should_Return_PrerecordedTranscription_When_StreamSource_Present()
+        public async Task GetTransaction_Should_Return_PrerecordedTranscription_When_StreamSource_Present()
         {
             //Arrange 
             var fakePrecordedTranscription = new AutoFaker<PrerecordedTranscription>().Generate();
             var SUT = GetDeepgramClient(fakePrecordedTranscription);
             var fakeStreamSource = new StreamSourceFaker().Generate();
+            _prerecordedTranscriptionOptions.Callback = null;
 
             //Act
             var result = await SUT.Transcription.Prerecorded.GetTranscriptionAsync(fakeStreamSource, _prerecordedTranscriptionOptions);
@@ -51,7 +59,7 @@ public async void GetTransaction_Should_Return_PrerecordedTranscription_When_Str
         }
 
         [Fact]
-        public async void Should_Return_A_Summary_Short_When_Summarize_Set_To_v2()
+        public async Task Should_Return_A_Summary_Short_When_Summarize_Set_To_v2()
         {
             //Arrange
             var responseObject = new AutoFaker<PrerecordedTranscription>().Generate();
@@ -74,25 +82,20 @@ public async void Should_Return_A_Summary_Short_When_Summarize_Set_To_v2()
 
         }
 
-
-
         [Theory]
         [InlineData(true)]
         [InlineData(false)]
-        public async void Should_Return_A_Summary_Short_When_Summarize_Set_To_bool(bool value)
+        public async Task Should_Return_A_Summary_Short_When_Summarize_Set_To_bool(bool value)
         {
             //Arrange
             var responseObject = new AutoFaker<PrerecordedTranscription>().Generate();
             var SUT = GetDeepgramClient(responseObject);
             responseObject.Results.Summary.Short = null;
-            var client = MockHttpClient.CreateHttpClientWithResult(responseObject);
             var fakeOptions = new PrerecordedTranscriptionOptions()
             {
                 Summarize = value
             };
 
-            SUT.Transcription.Prerecorded.ApiRequest = new ApiRequest(client);
-
             //Act
             var result = await SUT.Transcription.Prerecorded.GetTranscriptionAsync(_urlSource, fakeOptions);
 
@@ -103,6 +106,83 @@ public async void Should_Return_A_Summary_Short_When_Summarize_Set_To_bool(bool
 
         }
 
+        [Fact]
+        public async Task Should_Return_RequestId_When_Async_Transcription_From_Url_Requested()
+        {
+            //Arrange
+            var responseObject = new AutoFaker<PrerecordedTranscriptionCallbackResult>().Generate();
+            responseObject.RequestId = Guid.NewGuid();
+            _prerecordedTranscriptionOptions.Callback = null;
+
+            var SUT = GetDeepgramClient(responseObject);
+
+            // Act
+            var result = await SUT.Transcription.Prerecorded.GetTranscriptionAsync(_urlSource, _faker.Internet.Url(), _prerecordedTranscriptionOptions);
+
+            // Assert
+
+            Assert.Equal(responseObject.RequestId, result.RequestId);
+        }
+
+        [Fact]
+        public async Task Should_Throw_When_Async_Transcription_From_Url_Has_No_Callback()
+        {
+            // Arrange
+            var responseObject = new AutoFaker<string>().Generate();
+            _prerecordedTranscriptionOptions.Callback = null;
+
+            var SUT = GetDeepgramClient(responseObject);
+
+            var exception = await Assert.ThrowsAsync<ArgumentException>(async () =>
+                await SUT.Transcription.Prerecorded.GetTranscriptionAsync(_urlSource,
+                    null, _prerecordedTranscriptionOptions));
+
+            Assert.Matches("CallbackUrl is required for this call. Please set the callbackUrl parameter or the callbackUrl property in the options object.", exception.Message);
+        }
+
+        [Fact]
+        public async Task Should_Return_RequestId_When_Async_Transcription_From_Stream_Requested()
+        {
+            // Arrange
+            var responseObject = new AutoFaker<PrerecordedTranscriptionCallbackResult>().Generate();
+            responseObject.RequestId = Guid.NewGuid();
+            _prerecordedTranscriptionOptions.Callback = null;
+
+            var SUT = GetDeepgramClient(responseObject);
+
+            using var stream = new MemoryStream(_faker.Random.Bytes(100));
+
+            // Act
+            var result = await SUT.Transcription.Prerecorded.GetTranscriptionAsync(new StreamSource(stream, "audio/wav"),
+                               _faker.Internet.Url(), _prerecordedTranscriptionOptions);
+
+            // Assert
+            Assert.Equal(responseObject.RequestId, result.RequestId);
+        }
+
+        [Fact]
+        public async Task Should_Throw_When_Async_Transcription_From_Stream_Has_No_Callback()
+        {
+            // Arrange
+            var responseObject = new AutoFaker<PrerecordedTranscriptionCallbackResult>().Generate();
+            responseObject.RequestId = Guid.NewGuid();
+            _prerecordedTranscriptionOptions.Callback = null;
+
+            var httpClient = MockHttpClient.CreateHttpClientWithResult(responseObject);
+
+            var SUT = GetDeepgramClient(responseObject);
+            SUT.Transcription.Prerecorded.ApiRequest = new ApiRequest(httpClient);
+
+            using var stream = new MemoryStream(_faker.Random.Bytes(100));
+
+            // Act
+            var exception = await Assert.ThrowsAsync<ArgumentException>(async () =>
+                await SUT.Transcription.Prerecorded.GetTranscriptionAsync(_urlSource,
+                    null, _prerecordedTranscriptionOptions));
+
+            // Assert
+            Assert.Matches("CallbackUrl is required for this call. Please set the callbackUrl parameter or the callbackUrl property in the options object.", exception.Message);
+        }
 
         private static DeepgramClient GetDeepgramClient<T>(T returnObject)
         {

Deepgram.Tests/Fakers/PrerecordedTranscriptionOptionsFaker.cs

@@ -1,7 +1,8 @@
 using System.Linq;
 using AutoBogus;
-using Bogus.Extensions;
 using Deepgram.Models;
+using Bogus.Extensions;
+
 namespace Deepgram.Tests.Fakers
 {
     public class PrerecordedTranscriptionOptionsFaker : AutoFaker<PrerecordedTranscriptionOptions>

Deepgram.Tests/UtilitiesTests/QueryParameterUtilTests.cs

@@ -66,7 +66,7 @@ public void GetParameters_Should_Return_String_When_Passing_Decimal_Parameter()
 
             //Assert
             Assert.NotNull(result);
-            Assert.Contains($"utt_split={prerecordedTranscriptionOptions.UtteranceSplit}", result);
+            Assert.Contains($"utt_split={System.Web.HttpUtility.UrlEncode(prerecordedTranscriptionOptions.UtteranceSplit.ToString())}", result);
         }
 
         [Fact]

Deepgram/Clients/PrerecordedTranscriptionClient.cs

@@ -1,4 +1,5 @@
-using System.Net.Http;
+using System;
+using System.Net.Http;
 using System.Threading.Tasks;
 using Deepgram.Interfaces;
 using Deepgram.Models;
@@ -8,40 +9,78 @@ namespace Deepgram.Clients
     public class PrerecordedTranscriptionClient : BaseClient, IPrerecordedTranscriptionClient
     {
         public PrerecordedTranscriptionClient(Credentials credentials) : base(credentials) { }
-        /// <summary>
-        /// Submits a request to the Deepgram API to transcribe prerecorded audio
-        /// </summary>
-        /// <param name="source">Url source to send for transcription</param>
-        /// <param name="options">Feature options for the transcription</param>
-        /// <returns>Transcription of the provided audio</returns>
+        /// <inheritdoc />
         public async Task<PrerecordedTranscription> GetTranscriptionAsync(UrlSource source, PrerecordedTranscriptionOptions options)
         {
             var req = RequestMessageBuilder.CreateHttpRequestMessage(
                HttpMethod.Post,
-                "listen",
-                Credentials,
-                source,
-                options);
+               "listen",
+               Credentials,
+               source,
+               options);
 
             return await ApiRequest.SendHttpRequestAsync<PrerecordedTranscription>(req);
         }
 
-        /// <summary>
-        /// Submits a request to the Deepgram API to transcribe prerecorded audio
-        /// </summary>
-        /// <param name="source">Audio source to send for transcription</param>
-        /// <param name="options">Feature options for the transcription</param>
-        /// <returns>Transcription of the provided audio</returns>
+        /// <inheritdoc />
         public async Task<PrerecordedTranscription> GetTranscriptionAsync(StreamSource source, PrerecordedTranscriptionOptions options)
         {
             var req = RequestMessageBuilder.CreateStreamHttpRequestMessage(
              HttpMethod.Post,
-              "listen",
-              Credentials,
-              source,
-              options);
+             "listen",
+             Credentials,
+             source,
+             options);
 
             return await ApiRequest.SendHttpRequestAsync<PrerecordedTranscription>(req);
         }
+
+        /// <inheritdoc />
+        public async Task<PrerecordedTranscriptionCallbackResult> GetTranscriptionAsync(UrlSource source, string callbackUrl, PrerecordedTranscriptionOptions options)
+        {
+            if (!String.IsNullOrEmpty(options.Callback) && !String.IsNullOrEmpty(callbackUrl))
+            {
+                throw new System.ArgumentException("CallbackUrl is already set in the options object. Please use one or the other.");
+            }
+
+            if (!String.IsNullOrEmpty(callbackUrl))
+            {
+                options.Callback = callbackUrl;
+            }
+
+            _ = options.Callback ?? throw new System.ArgumentException("CallbackUrl is required for this call. Please set the callbackUrl parameter or the callbackUrl property in the options object.");
+
+            var req = RequestMessageBuilder.CreateHttpRequestMessage(
+             HttpMethod.Post,
+             "listen",
+             Credentials,
+             source,
+             options);
+            return await ApiRequest.SendHttpRequestAsync<PrerecordedTranscriptionCallbackResult>(req);
+        }
+
+        /// <inheritdoc />
+        public async Task<PrerecordedTranscriptionCallbackResult> GetTranscriptionAsync(StreamSource source, string callbackUrl, PrerecordedTranscriptionOptions options)
+        {
+            if (!String.IsNullOrEmpty(options.Callback) && !String.IsNullOrEmpty(callbackUrl))
+            {
+                throw new System.ArgumentException("CallbackUrl is already set in the options object. Please use one or the other.");
+            }
+
+            if( !String.IsNullOrEmpty(callbackUrl)) {
+                options.Callback = callbackUrl;
+            }
+
+            _ = options.Callback ?? throw new System.ArgumentException("CallbackUrl is required for this call. Please set the callbackUrl parameter or the callbackUrl property in the options object.");
+
+
+            var req = RequestMessageBuilder.CreateStreamHttpRequestMessage(
+             HttpMethod.Post,
+             "listen",
+             Credentials,
+             source,
+             options);
+            return await ApiRequest.SendHttpRequestAsync<PrerecordedTranscriptionCallbackResult>(req);
+        }
     }
 }

Deepgram/DeepgramClient.cs

@@ -19,7 +19,6 @@ public DeepgramClient() : this(null) { }
 
         public DeepgramClient(Credentials credentials)
         {
-
             Initialize(credentials);
         }
 

Deepgram/Interfaces/IPrerecordedTranscriptionClient.cs

@@ -20,5 +20,24 @@ public interface IPrerecordedTranscriptionClient : IBaseClient
         /// <param name="options">Feature options for the transcription</param>
         /// <returns>Transcription of the provided audio</returns>
         Task<PrerecordedTranscription> GetTranscriptionAsync(StreamSource source, PrerecordedTranscriptionOptions options);
+
+        /// <summary>
+        /// Asynchronously submits a request to the Deepgram API to transcribe prerecorded audio
+        /// </summary>
+        /// <param name="source">Url source to send for transcription</param>
+        /// <param name="callbackUrl">Url to send the transcription results to</param>
+        /// <param name="options">Feature options for the transcription</param>
+        /// <returns>Transcription of the provided audio</returns>
+        Task<PrerecordedTranscriptionCallbackResult> GetTranscriptionAsync(UrlSource source, string callbackUrl, PrerecordedTranscriptionOptions options);
+
+        /// <summary>
+        /// Asynchronously submits a request to the Deepgram API to transcribe prerecorded audio
+        /// </summary>
+        /// <param name="source">Audio source to send for transcription</param>
+        /// <param name="callbackUrl">Url to send the transcription results to</param>
+        /// <param name="options">Feature options for the transcription</param>
+        /// <returns>Transcription of the provided audio</returns>
+        Task<PrerecordedTranscriptionCallbackResult> GetTranscriptionAsync(StreamSource source, string callbackUrl, PrerecordedTranscriptionOptions options);
+
     }
 }

Deepgram/Models/PrerecordedTranscriptionCallbackResult.cs

@@ -0,0 +1,15 @@
+using System;
+using Newtonsoft.Json;
+
+namespace Deepgram.Models
+{
+    public class PrerecordedTranscriptionCallbackResult
+
+    {
+        /// <summary>
+        /// Id of the request.
+        /// </summary>
+        [JsonProperty("request_id")]
+        public Guid RequestId { get; set; }
+    }
+}

Deepgram/Models/PrerecordedTranscriptionOptions.cs

@@ -162,7 +162,7 @@ public class PrerecordedTranscriptionOptions
         /// Callback URL to provide if you would like your submitted audio to be processed asynchronously.
         /// When passed, Deepgram will immediately respond with a request_id. 
         /// </summary>
-        [JsonProperty("callback")]
+        [JsonProperty("callback"), Obsolete("This parameter has been replaced with the callback argument to GetTranscriptionAsync and may be removed at a later date")]
         public string Callback { get; set; } = null;
 
         /// <summary>