Implement TTS and Other REST Refactor

[davidvonthenen]

Addresses issue: #244
Partially addresses: #234

Major changes include:

• Implements TTS with an Example
• All REST functions now include the ability for custom QueryParameters

There are TODOs for logging (and comments) which I will get back to when I have a logging mechanism with verbosity levels worked. Existing issues for Comments #210 and Logging #219 already exist as a reminder.

Summary by CodeRabbit

• New Features

  • Introduced the "Speak" project, enhancing the solution with audio transcription and text-to-speech capabilities.
  • Added support for optional addons parameters across various client methods, enabling extended functionality in speech processing tasks.
  • Provided examples demonstrating interaction with the Deepgram API for speech processing.

• Bug Fixes

  • Improved code quality by removing unnecessary whitespace and line breaks.

• Refactor

  • Updated method signatures to enhance flexibility and maintainability.
  • Streamlined query parameter handling with the introduction of new utility methods.

• Documentation

  • Updated descriptions and added documentation for new classes and methods related to the Speak API.

[coderabbitai]

Walkthrough

This update introduces a significant expansion and refinement to the .NET SDK for Deepgram, focusing on enhancing functionality around speech processing. Key additions include the introduction of a new Speak project, improvements to HTTP client configurations for better customization and thread safety, and the introduction of addons parameters across various client methods for extended functionality. The changes aim to provide more flexible and powerful tools for developers working with the Deepgram API for audio transcription and speech processing tasks.

Changes

Files	Change Summary
Deepgram.Dev.sln	Added "Speak" project
Deepgram.Tests/Fakes/MockHttpClient.cs	Removed an empty line
Deepgram.Tests/Fakes/MockHttpMessageHandler.cs	Added generic type parameter; removed line break
Deepgram.Tests/.../SpeakClientTests.cs	Added unit tests for SpeakClient
Deepgram/Abstractions/AbstractRestClient.cs	Added using directives; modified and added methods with addons parameter
Deepgram/Clients/Analyze/v1/Client.cs Deepgram/Clients/Live/v1/Client.cs Deepgram/Clients/Manage/v1/Client.cs Deepgram/Clients/PreRecorded/v1/Client.cs	Updated methods to include addons parameter
Deepgram/Clients/Speak/v1/...	Implemented SpeakClient and related classes for audio transcription
Deepgram/Models/...	Updated and introduced models for Speak API
Deepgram/Utilities/QueryParameterUtil.cs	Updated and added methods for query parameter handling
examples/speak/...	Added examples demonstrating Speak API usage

Related issues

• Issue Further HTTP/REST Refactoing #234: The enhancements made to HTTP/REST clients in this PR, especially around thread safety and the introduction of addons parameters, could potentially address the concerns raised about thread safety and the need for further HTTP/REST client refactoring.

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

Share

• X
• Mastodon
• Reddit
• LinkedIn

---

Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>.
  • Generate unit-tests for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit tests for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai generate interesting stats about this repository and render them as a table.
  • @coderabbitai show all the console.log statements in this repository.
  • @coderabbitai read src/utils.ts and generate unit tests.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (invoked as PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger a review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai help to get help.

Additionally, you can add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.

CodeRabbit Configration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• The JSON schema for the configuration file is available here.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/coderabbit-overrides.v2.json

CodeRabbit Discord Community

Join our Discord Community to get help, request features, and share feedback.

[coderabbitai]

Review Status

Actionable comments generated: 8

Configuration used: CodeRabbit UI

Commits

Files that changed from the base of the PR and between d4fd4e5 and 26a5c3f.

Files selected for processing (21)

• Deepgram.Dev.sln (2 hunks)
• Deepgram.Tests/Fakes/MockHttpClient.cs (1 hunks)
• Deepgram.Tests/Fakes/MockHttpMessageHandler.cs (2 hunks)
• Deepgram.Tests/UnitTests/ClientTests/SpeakClientTests.cs (1 hunks)
• Deepgram/Abstractions/AbstractRestClient.cs (7 hunks)
• Deepgram/Clients/Analyze/v1/Client.cs (6 hunks)
• Deepgram/Clients/Live/v1/Client.cs (3 hunks)
• Deepgram/Clients/Manage/v1/Client.cs (12 hunks)
• Deepgram/Clients/PreRecorded/v1/Client.cs (6 hunks)
• Deepgram/Clients/Speak/v1/Client.cs (1 hunks)
• Deepgram/Clients/Speak/v1/Constants.cs (1 hunks)
• Deepgram/Clients/Speak/v1/UriSegments.cs (1 hunks)
• Deepgram/Models/Analyze/v1/UrlSource.cs (1 hunks)
• Deepgram/Models/Speak/v1/AsyncResponse.cs (1 hunks)
• Deepgram/Models/Speak/v1/SpeakSchema.cs (1 hunks)
• Deepgram/Models/Speak/v1/SyncResponse.cs (1 hunks)
• Deepgram/Models/Speak/v1/TextSource.cs (1 hunks)
• Deepgram/SpeakClient.cs (1 hunks)
• Deepgram/Utilities/QueryParameterUtil.cs (3 hunks)
• examples/speak/Program.cs (1 hunks)
• examples/speak/Speak.csproj (1 hunks)

Files skipped from review due to trivial changes (5)

• Deepgram.Tests/Fakes/MockHttpClient.cs
• Deepgram/Clients/Speak/v1/Constants.cs
• Deepgram/Clients/Speak/v1/UriSegments.cs
• Deepgram/Models/Analyze/v1/UrlSource.cs
• Deepgram/SpeakClient.cs

Additional comments: 26

examples/speak/Speak.csproj (3)

• 3-7: The project settings for the Speak example are well-configured, adhering to modern .NET best practices by enabling ImplicitUsings and Nullable.
• 11-11: The inclusion of Microsoft.Extensions.Http is appropriate for HTTP operations within the Speak example.
• 15-15: The project reference to Deepgram.csproj is correctly included, allowing the Speak example to utilize the SDK.

Deepgram/Models/Speak/v1/AsyncResponse.cs (1)

• 7-14: The AsyncResponse record is well-defined and appropriately uses the record syntax for immutable data modeling. The documentation for the RequestId property is clear and informative.

Deepgram.Tests/Fakes/MockHttpMessageHandler.cs (1)

• 6-6: The introduction of a generic type parameter T to the MockHttpMessageHandler class enhances its flexibility and utility for testing by allowing it to mock responses of any type. This is a valuable improvement for unit testing.

Deepgram.Dev.sln (1)

• 14-15: The addition of the "Speak" project to the solution file is correctly implemented, ensuring that the new TTS example is properly included in the solution structure.

Deepgram/Utilities/QueryParameterUtil.cs (1)

• 13-22: The modifications to GetParameters to include an optional addons parameter enhance the method's flexibility without introducing any apparent issues. Good use of null checks and URL encoding for security.

Deepgram/Clients/Speak/v1/Client.cs (3)

• 27-85: The addition of the addons parameter in ToStream enhances the method's flexibility. The secure construction of the query string using QueryParameterUtil.GetParameters is commendable. However, consider abstracting the response header parsing into a separate method for improved maintainability and readability.
• 88-102: The ToFile method correctly utilizes the ToStream method to obtain the TTS response and then saves it to a file using BinaryWriter. This approach is efficient and correctly implemented.
• 127-152: The callback validation methods VerifyNoCallBack and VerifyOneCallBackSet are correctly implemented, ensuring proper handling of callback URLs. Consider abstracting the repeated validation logic to adhere to the DRY principle, enhancing code maintainability.

Deepgram/Clients/Analyze/v1/Client.cs (3)

• 25-29: The addition of the addons parameter in AnalyzeUrl enhances the method's flexibility. The secure construction of the query string using QueryParameterUtil.GetParameters is commendable.
• 40-43: The refactoring of AnalyzeFile to include an addons parameter and to call another overload for handling a MemoryStream is a good practice, promoting code reuse and maintainability.
• 90-102: > 📝 NOTE

This review was outside the diff hunks and was mapped to the diff hunk with the greatest overlap. Original lines [72-118]

The callback methods AnalyzeFileCallBack and AnalyzeUrlCallBack are well-implemented, securely handling the addons parameter and callback URL. The consistent approach across the SDK enhances maintainability.

Deepgram.Tests/UnitTests/ClientTests/SpeakClientTests.cs (1)

• 55-164: The unit tests introduced for the Speak client are comprehensive and correctly verify the behavior of callback URL handling and the addons parameter. The use of mocking and assertions is appropriate, ensuring the reliability of the TTS functionalities.

Deepgram/Clients/PreRecorded/v1/Client.cs (3)

• 26-30: The addition of the addons parameter in TranscribeUrl enhances the method's flexibility. The secure construction of the query string using QueryParameterUtil.GetParameters is commendable.
• 41-44: The refactoring of TranscribeFile to include an addons parameter and to call another overload for handling a MemoryStream is a good practice, promoting code reuse and maintainability.
• 91-103: > 📝 NOTE

This review was outside the diff hunks and was mapped to the diff hunk with the greatest overlap. Original lines [73-120]

The callback methods TranscribeFileCallBack and TranscribeUrlCallBack are well-implemented, securely handling the addons parameter and callback URL. The consistent approach across the SDK enhances maintainability.

Deepgram/Abstractions/AbstractRestClient.cs (6)

• 42-46: The addition of the addons parameter in GetAsync method enhances the flexibility of API requests by allowing custom query parameters. However, ensure that the QueryParameterUtil.AppendQueryParameters method properly encodes the parameters to avoid potential security issues like injection attacks.
• 132-136: The new PostAsync method with the addons parameter is a good addition for supporting custom query parameters in POST requests. This aligns with the overall goal of enhancing REST functions in the SDK. Ensure that the content passed to this method is properly validated or sanitized to prevent security vulnerabilities such as injection attacks.
• 156-160: The DeleteAsync method's modification to include an addons parameter is consistent with the enhancements made to other HTTP methods in this class. This consistency in design is beneficial for the SDK's usability. As with other methods, ensure that the addons are properly encoded to prevent security issues.
• 177-181: The addition of an overload for the DeleteAsync method that returns a type T is a useful enhancement, providing more flexibility in handling responses from DELETE requests. This change is consistent with the approach taken for other HTTP methods in this class.
• 201-210: The PatchAsync method's update to include an addons parameter is a welcome addition for supporting custom query parameters. The use of conditional compilation to support different HTTP methods based on the target framework is a good practice for ensuring compatibility. Ensure that the content and addons are properly handled to prevent security vulnerabilities.
• 232-236: The new PutAsync method with the addons parameter aligns with the enhancements made to other HTTP methods in this class, providing a consistent and flexible way to include custom query parameters in PUT requests. As always, ensure proper encoding and validation of the parameters to maintain security.

Deepgram/Clients/Live/v1/Client.cs (2)

• 63-69: > 📝 NOTE

This review was outside the diff hunks and was mapped to the diff hunk with the greatest overlap. Original lines [66-85]

The addition of the addons parameter in the Connect method is a good enhancement, allowing for more customizable WebSocket connections. Ensure that the addons are properly encoded and validated when constructing the URI to prevent potential security issues.

• 289-292: The GetUri method now accepts an addons parameter, which is used to append custom query parameters to the URI. This change is consistent with the overall goal of enhancing flexibility in the SDK. Ensure that the QueryParameterUtil.GetParameters method properly encodes the parameters to avoid potential security issues.

Deepgram/Clients/Manage/v1/Client.cs (1)

• 23-24: The addition of the addons parameter across various methods, starting with GetProjects, enhances the flexibility and customizability of API requests by allowing custom query parameters. This is a significant improvement in line with the PR objectives. Ensure that the addons are properly encoded and validated to prevent security vulnerabilities.

[coderabbitai]

Review Status

Actionable comments generated: 1

Configuration used: CodeRabbit UI

Commits

Files that changed from the base of the PR and between d4fd4e5 and c8c0606.

Files selected for processing (21)

• Deepgram.Dev.sln (2 hunks)
• Deepgram.Tests/Fakes/MockHttpClient.cs (1 hunks)
• Deepgram.Tests/Fakes/MockHttpMessageHandler.cs (2 hunks)
• Deepgram.Tests/UnitTests/ClientTests/SpeakClientTests.cs (1 hunks)
• Deepgram/Abstractions/AbstractRestClient.cs (6 hunks)
• Deepgram/Clients/Analyze/v1/Client.cs (6 hunks)
• Deepgram/Clients/Live/v1/Client.cs (3 hunks)
• Deepgram/Clients/Manage/v1/Client.cs (12 hunks)
• Deepgram/Clients/PreRecorded/v1/Client.cs (6 hunks)
• Deepgram/Clients/Speak/v1/Client.cs (1 hunks)
• Deepgram/Clients/Speak/v1/Constants.cs (1 hunks)
• Deepgram/Clients/Speak/v1/UriSegments.cs (1 hunks)
• Deepgram/Models/Analyze/v1/UrlSource.cs (1 hunks)
• Deepgram/Models/Speak/v1/AsyncResponse.cs (1 hunks)
• Deepgram/Models/Speak/v1/SpeakSchema.cs (1 hunks)
• Deepgram/Models/Speak/v1/SyncResponse.cs (1 hunks)
• Deepgram/Models/Speak/v1/TextSource.cs (1 hunks)
• Deepgram/SpeakClient.cs (1 hunks)
• Deepgram/Utilities/QueryParameterUtil.cs (3 hunks)
• examples/speak/Program.cs (1 hunks)
• examples/speak/Speak.csproj (1 hunks)

Files skipped from review as they are similar to previous changes (18)

• Deepgram.Dev.sln
• Deepgram.Tests/Fakes/MockHttpClient.cs
• Deepgram.Tests/Fakes/MockHttpMessageHandler.cs
• Deepgram/Clients/Analyze/v1/Client.cs
• Deepgram/Clients/Live/v1/Client.cs
• Deepgram/Clients/Manage/v1/Client.cs
• Deepgram/Clients/PreRecorded/v1/Client.cs
• Deepgram/Clients/Speak/v1/Client.cs
• Deepgram/Clients/Speak/v1/Constants.cs
• Deepgram/Clients/Speak/v1/UriSegments.cs
• Deepgram/Models/Analyze/v1/UrlSource.cs
• Deepgram/Models/Speak/v1/AsyncResponse.cs
• Deepgram/Models/Speak/v1/SpeakSchema.cs
• Deepgram/Models/Speak/v1/SyncResponse.cs
• Deepgram/Models/Speak/v1/TextSource.cs
• Deepgram/SpeakClient.cs
• examples/speak/Program.cs
• examples/speak/Speak.csproj

Additional comments: 11

Deepgram/Utilities/QueryParameterUtil.cs (2)

• 25-44: The implementation of AppendQueryParameters method looks good. It correctly handles null checks and efficiently appends query parameters to the URI.
• 13-22: The modification to include an optional addons parameter in the GetParameters method enhances its flexibility and aligns with the PR's objectives.

Deepgram.Tests/UnitTests/ClientTests/SpeakClientTests.cs (4)

• 55-81: The test StreamCallBack_With_CallBack_Property_Should_Call_PostAsync_Returning_SyncResponse is well-structured and correctly verifies the functionality.
• 83-114: The test StreamCallBack_With_CallBack_Parameter_Should_Call_PostAsync_Returning_SyncResponse effectively verifies the functionality with the CallBack parameter set.
• 118-140: The test StreamCallBack_Throw_ArgumentException_With_CallBack_Property_And_CallBack_Parameter_Set correctly verifies that an ArgumentException is thrown when both the property and parameter are set.
• 142-164: The test StreamCallBack_Should_Throw_ArgumentException_With_No_CallBack_Set effectively ensures that an ArgumentException is thrown when no CallBack is provided, which is crucial for the method's correctness.

Deepgram/Abstractions/AbstractRestClient.cs (5)

• 39-43: The modification to include an optional addons parameter in the GetAsync method aligns with the PR's objectives and is correctly implemented.
• 129-133: The addition of the new PostAsync method with an addons parameter is a valuable enhancement, providing flexibility for making POST requests with custom query parameters.
• 153-157: The modifications to include an addons parameter in the DeleteAsync method and the addition of a new DeleteAsync method returning a type T enhance flexibility and align with the PR's objectives.
• 198-203: The modification to include an addons parameter in the PatchAsync method enhances its flexibility for PATCH requests and is correctly implemented.
• 229-233: The addition of the new PutAsync method with an addons parameter is a valuable enhancement, providing flexibility for making PUT requests with custom query parameters.