DEV Community: Guillaume Faas

Supabase .NET DevLog #5

Guillaume Faas — Mon, 10 Aug 2026 14:37:07 +0000

Welcome to our weekly log for the Supabase .NET SDK! 🎉

Last week marks a milestone for the SDK: the migration to a monorepo is now done!

Achievement Unlocked!

Everything can be found under the main repository supabase-csharp. Every package has its own project under packages/.
Nothing changes for you (yet): same packages, same public API.

Prior to that, I had to merge/fix all the open PRs for every package, as these couldn't get carried over, and transferred all the open issues too.

This is now the single place to contribute and fill issues, as other repositories have been archived.

Now that this has been dealt with, I'm focusing on the upcoming v8.0.0 and all the breaking changes that come with it. Wish me luck! 😅

Have a great day, and keep coding!

Supabase .NET DevLog #4

Guillaume Faas — Mon, 03 Aug 2026 13:36:31 +0000

Welcome to our weekly log for the Supabase .NET SDK! 🎉

I briefly mentioned I was working on the test suite in our previous entry. Well, I've got great news!
I made substantial progress on that: a small bump in code coverage (+11% average across packages), but mostly a significant bump on mutation score (+41% average across packages). If you never heard about mutation testing, the tldr is it represents how much you can trust your test suite, with a number: the mutation score. I digress, but let me know if you want to hear more about that.
This will help me build momentum on the SDK moving forward.

I also updated our SDK Reference, which hasn't been updated for more than two years, and made sure we exposed a C# snippet for every product in our docs.
The only caveat is nothing is automated on that front... I'll tackle that when we reach the monorepo.

Aside from those updates, I also closed a couple of PRs from contributors, and published a couple of releases.
I have to say the community have been responding so positively so far, it's just awesome 😎

We're getting closer to the monorepo migration. I'm currently planning this and getting together with other teams. My goal is to land this in the first half of August, and then the priority will be to work towards the new major version (hopefully soon).

Have a great day, and keep coding!

Supabase .NET DevLog #3

Guillaume Faas — Mon, 27 Jul 2026 12:29:46 +0000

Welcome to our weekly log for the Supabase .NET SDK! 🎉

Last week, I closed all the remaining critical fixes (P0s), which represented a total of 16 GitHub issues affecting developers.

Aside from the usual fixes, I also shipped OpenTelemetry which is a huge step forward for the SDK's transparency compared to the old debug logging.

We also got more releases this week as well:

Supabase v1.4.0
Supabase.Functions v2.2.0
Supabase.Gotrue v6.2.0
Supabase.Postgrest v4.4.0
Supabase.Realtime v7.3.0
Supabase.Storage v2.5.0
Supabase.Core v1.2.0

Remember folks: always keep your dependencies up-to-date, just sayin'

With the team, we also discussed the new versioning structure once we move to a monorepo: lockstep versioning, meaning all packages share the same version number.
One caveat is we'll have to start fresh at v8.0.0, so a +7 bump on the main package because of the odd version distribution we currently have. This will give us an opportunity to ship breaking changes at the same time to improve the DevEx.

I'm currently working on improving the overall test-suite, and I'll probably share metrics about that next week. This is a mandatory step for the SDK's future: we (the community, me included) need a test-suite we can trust, otherwise we can't safely add/update features.

This is probably the last step before the monorepo's transition.

Have a great day, and keep coding!

Supabase .NET DevLog #2

Guillaume Faas — Mon, 20 Jul 2026 06:00:37 +0000

Welcome to our weekly log for the Supabase .NET SDK! 🎉

Last week, I continued building our momentum on improving the overall experience with the SDK.
I released other critical fixes, as well as some improvements:

[Global] Fixing automated releases: The release process wasn't uniform across packages, and was also broken at places (especially on the umbrella package).
[Global] Fixed the telemetry: The telemetry is now consistent across packages but also more detailed. This will give us more details about who our users are and how they use our products.
[Global] Make Newtonsoft.Json 13.0.2 the ground version: We had to reduce the ground version of this dependency because of Unity 6 LTS. Indeed, Unity 6 ships with 13.0.2 and that version can't be bumped. This was locking out customers.
[GoTrue] Add missing OAuth2 state: We exposed a server-side state value, strengthening CSRF protection.
[Postgrest] Reference fields incorrectly included in UPDATE and DELETE queries: The behavior was only correct for INSERT, but failing for others. All we had to do was to cover Patch and Delete.
[Postgrest] Fixed enums serialised as integers: To avoid breaking existing data, this is something users must opt-in with ClientOptions.SerializeEnumsAsStrings.

I also did a lot of triage on all the repositories. Between the fixes/improvements and clearing outdated issues, 14 issues were solved/removed.

And all of this is now accessible for customers! 🎉 I published new versions for our entire SDK suite, the first one since a little while (addressing the dependency issues we mentioned in the previous post):

Supabase v1.2.0
Supabase.Functions v2.1.1
Supabase.Gotrue v6.1.0
Supabase.Postgrest v4.2.0
Supabase.Realtime v7.2.1
Supabase.Storage v2.4.2
Supabase.Core v1.1.0 That being said, the current release process is quite painful. I can't wait to move to a monorepo, with a single Release button 😅 It's a mandatory move if I want to speed up the pace of releases.

This week will follow the same trajectory: fixing existing issues, release them to customers, and keep sanitizing repositories before moving towards a monorepo.

Have a a great day, and keep coding!

Supabase .NET DevLog #1

Guillaume Faas — Mon, 13 Jul 2026 07:07:26 +0000

Welcome to the first entry of our weekly log for the Supabase .NET SDK! 🎉

Being still a new joiner in the company, I' still ramping up. I've been working on a plan to set up the direction of the SDK and prioritise what needs to be done first. I'm far from my full velocity, but there's a lot to catch up on.

I started with critical fixes, as the SDK was broken in some places:

[GoTrue] Auth kept dead sessions alive: when a refresh token got rejected, the client only cleared the session in one specific case.
[GoTrue] Email OTP sign-in and password reset were broken: SignInWithOtp and ResetPasswordForEmail had the PKCE verifier and challenge swapped (the SHA-256 hash was sent as the raw value, and vice-versa).
[PostgREST] Negation dropped in predicates: a silent issue where conditions like x => !(x.Name == "foo") were dropping the negation on Where, Update, and Delete. *** [PostgREST] Truncated DateTime:** reading dropped sub-second precision and UTC offset. Any round-trip was failing.
[PostgREST] Where improvements: ids.Contains(x.Id) now translates into an in filter rather than throwing, boolean columns (ex: x.IsActive) can be used directly, and comparing two columns to each other throws a clear error explaining why PostgREST can't do that.

It's worth to note that all of these changes are yet unreleased.

I will ship more critical fixes, and an improvement on the SDK's telemetry, before releasing a clean version this week. This will be a good opportunity to align dependencies, as the SDK doesn't reference all the latest versions of its sub-packages at the moment.

Once we stabilize the usage, the first milestone will be to migrate to a monorepo. Hopefully, soon.

Have a great day, and keep coding!

Supabase .NET DevLog #0

Guillaume Faas — Thu, 09 Jul 2026 11:50:56 +0000

Quick context if you haven't seen the latest news: I recently joined Supabase as .NET SDK Engineer.

Their .NET SDK is moving from community maintenance to official support, and I'm the main contributor moving forward 🎉

Especially with SDKs, I've always liked being engaged with developers: keeping them in the loop, but also collecting feedback.

So, I'm starting a weekly log!

Every week, I'll publish a short post about what happened on the SDK and where it's heading. Nothing fancy: just a few bullet points, some context when a decision deserves an explanation. That's it.

Fair warning: what I plan for a week won't always get delivered... because Life happens. Priorities move, issues show up, unexpected stuff, etc. So, don't take the plan for a promise.

If you're building with Supabase on .NET, this is also for you: tell me what's broken, what's missing, what's annoying. I have my own thoughts on that, but real pain points are better than assumptions.

Stay tuned and Happy coding ✌️

How I Removed 1,500 Lines of Boilerplate with a Source Generator

Guillaume Faas — Tue, 08 Jul 2025 08:53:41 +0000

In my previous blog post, I explained why I rely so heavily on the Builder pattern. It facilitates the creation of my requests, guiding developers when creating objects.

This wasn't just a personal preference. I ended up there because Builders ticked all the boxes:

Predictable object creation
Control over validation failure
Support for both mandatory and optional parameters
A way to guide users with a Fluent API

But implementing those builders came with a heavy cost: boilerplate code. Each builder added 50+ lines of code on average; for simple/repetitive ones, and much more for complex ones.
That doesn't scale well: multiply this by 30+ use cases, and you get a lot of code that you have to write and maintain.

Let's address that particular problem.

What do we need?

The problem is not the builder itself. It's how much (repetitive) code it takes to get there, especially when a lot of them are very similar.

What we want is a way to:

Declare which requests require a builder
Declare mandatory and optional properties
Add validation rules
Return a Result upon creation, that will represent either a Request or a failure

In short, we want the same benefits, but with zero boilerplate.

Of course, we will not be able to apply this everywhere; some builders are quite specific, with internal behaviors. The goal is to remove the basic ones, the majority of them.

What are source generators?

Source Generators let you write code that runs at compile-time and generates other code.

In our case, we can write a class to make the generator:

Detect specific attributes
Create a builder dynamically
Generate a .g.cs file with all the code

For us, it means fewer files to maintain, less code to write. We also keep a consistent pattern across the codebase.
Also, adding a new builder is completely transparent; all we have to do is to create a new class with the rightattributes, and "voilà".

The Basics

If you want to build something similar, here are the foundational steps you'll need to follow:

Create a new Class Library project for the Generator
Create a Generator class that implements IIncrementalGenerator
Use Roslyn's syntax/semantic model to detect classes and their attributes
Generate new .cs file using SourceProductionContext

Here's a minimal example of what the setup looks like:

[Generator]
public class BuilderGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        var structDeclarations = IdentifyBuilders(context);
        context.RegisterSourceOutput(structDeclarations,
            (productionContext, structSymbols) =>
            {
                structSymbols.ToList().ForEach(symbol => GenerateSourceCode(symbol, productionContext));
            });
    }

    private static void GenerateSourceCode(INamedTypeSymbol structSymbol, SourceProductionContext productionContext)
    {
        var generatedCode = ... // Generate the builder's code
        var fileName = $"{structSymbol.Name}Builder.g.cs";
        productionContext.AddSource(fileName, SourceText.From(generatedCode, Encoding.UTF8));
    }
}

We'll walk you through the building blocks in the next section.

Under the Hood

Here's how I structured the generator.

I have four attributes:

"Builder" which will decorate a struct, marking them as requiring builder.
"Mandatory" which will decorate a property, marking it as mandatory.
"Optional" which will decorate a property, marking it as optional.
"Validation" which will decorate a method, used to validate the request.

The generator will find all structs marked with Builder...

private static bool HasBuilderAttribute(SyntaxNode node) =>
    node is StructDeclarationSyntax declaration && declaration.AttributeLists
        .SelectMany(syntax => syntax.Attributes)
        .Any(syntax => syntax.Name.ToString() == BuilderAttribute);

private static IncrementalValueProvider<ImmutableArray<INamedTypeSymbol>> IdentifyBuilders(
    IncrementalGeneratorInitializationContext context) =>
    context.SyntaxProvider
        .CreateSyntaxProvider(
            static (node, _) => HasBuilderAttribute(node),
            static (context, _) => GetStructSymbol(context)
        )
        .Where(symbol => symbol is not null)
        .Select((symbol, _) => symbol)
        .Collect();

And fetch properties marked as Mandatory or Optional.

private static IEnumerable<MandatoryProperty> GetMandatoryProperties(INamedTypeSymbol structSymbol) =>
    GetMembersForAttribute(structSymbol, MandatoryProperty.AttributeName).Select(MandatoryProperty.FromMember);

private static IEnumerable<IPropertySymbol> GetMembersForAttribute(INamedTypeSymbol structSymbol,
    string attributeName) =>
    structSymbol.GetMembers().OfType<IPropertySymbol>()
        .Where(member =>
            member.GetAttributes().Any(attribute => attribute.AttributeClass?.Name == attributeName));

When all the data is gathered, we proceed to create our Builder, line by line:

Our using statements
The namespace
Interface declarations
Our builder
etc...

We're essentially creating the entire file ourselves, as a string:

public string GenerateCode()
{
    var code = string.Concat(this.GenerateUsingStatements(),
        this.GenerateNamespace(),
        this.GenerateInterfaceDeclarations(),
        this.ExtendTypeWithPartial(),
        this.GenerateBuilder()
    );
    return FormatCode(code);
}

private string GenerateUsingStatements()
{
    var builder = new StringBuilder();
    builder.AppendLine("using Vonage.Common.Client;");
    builder.AppendLine("using Vonage.Common.Monads;");
    builder.AppendLine("using Vonage.Common.Validation;");
    var parameters = type.GetAttributes()
        .First(attr => attr.AttributeClass!.Name == "BuilderAttribute")
        .ConstructorArguments;
    if (parameters.Any())
    {
        parameters.First().Values.Select(value => value.Value?.ToString()).ToList()
            .ForEach(value => builder.AppendLine($"using {value};"));
    }

    return builder.ToString();
}

private string GenerateNamespace() =>
    string.IsNullOrEmpty(type.ContainingNamespace?.ToDisplayString())
        ? string.Empty
        : $"namespace {type.ContainingNamespace.ToDisplayString()};\n\n";

private string GenerateInterfaceDeclarations() =>
    string.Concat(this.GetBuilderInterfaces().Select(builderInterface => builderInterface.BuildDeclaration()));

// ...

Example: from Request to Builder

You'll find below an example: VerifyCodeRequest, which allows us to verify a 2FA code with our [Verify (https://developer.vonage.com/en/verify/overview) API.

This is the code from my initial request:

namespace Vonage.VerifyV2.VerifyCode;

[Builder] // This request requires a builder
public readonly partial struct VerifyCodeRequest : IVonageRequest
{
    [Mandatory(1)] // Code is mandatory, and second property to set
    public string Code { get; internal init; }

    [JsonIgnore]
    [Mandatory(0)] // RequestId is mandatory, and first property to set
    public Guid RequestId { get; internal init; }

    ...

    [ValidationRule] // ValidationRule for our builder
    internal static Result<VerifyCodeRequest> VerifyCodeNotEmpty(
        VerifyCodeRequest request) =>
        InputValidation
            .VerifyNotEmpty(request, request.Code, nameof(request.Code));

    [ValidationRule] // ValidationRule for our builder
    internal static Result<VerifyCodeRequest> VerifyRequestIdNotEmpty(
        VerifyCodeRequest request) =>
        InputValidation.VerifyNotEmpty(request, request.RequestId, nameof(request.RequestId));
}

And this is the builder (VerifyCodeRequestBuilder.g.cs), generated by our source generator:

using Vonage.Common.Client;
using Vonage.Common.Monads;
using Vonage.Common.Validation;

namespace Vonage.VerifyV2.VerifyCode;
public interface IBuilderForRequestId
{
    IBuilderForCode WithRequestId(System.Guid value);
}

public interface IBuilderForCode
{
    IBuilderForOptional WithCode(string value);
}

public interface IBuilderForOptional : IVonageRequestBuilder<VerifyCodeRequest>
{
}

public partial struct VerifyCodeRequest
{
    public static IBuilderForRequestId Build() => new VerifyCodeRequestBuilder();
}

internal struct VerifyCodeRequestBuilder : IBuilderForRequestId, IBuilderForCode, IBuilderForOptional
{
    private System.Guid requestid;
    private string code;
    public VerifyCodeRequestBuilder()
    {
        this.requestid = default;
        this.code = default;
    }

    public IBuilderForCode WithRequestId(System.Guid value) => this with
    {
        requestid = value
    };
    public IBuilderForOptional WithCode(string value) => this with
    {
        code = value
    };
    public Result<VerifyCodeRequest> Create() => Result<VerifyCodeRequest>.FromSuccess(new VerifyCodeRequest { RequestId = this.requestid, Code = this.code, }).Map(InputEvaluation<VerifyCodeRequest>.Evaluate).Bind(evaluation => evaluation.WithRules(VerifyCodeRequest.VerifyCodeNotEmpty, VerifyCodeRequest.VerifyRequestIdNotEmpty));
}

You probably noticed a couple of other things:

Our builder is in the same namespace as our request (Vonage.VerifyV2.VerifyCode), making it transparent for people who uses our code. They don't know, and they don't need to know, that the builder has been automatically generated.
We also extend our partial Request to add a static method Build() to initialize the builder with Request.Build()

Finally, here's a usage example:

var request = VerifyCodeRequest.Build()
    .WithRequestId(Guid.Parse("68c2b32e-55ba-4a8e-b3fa-43b3ae6cd1fb"))
    .WithCode("123456789")
    .Create()

In my case, my builders were already thoroughly tested before I introduced source generators. I used my test suite to guarantee that no builder's public api changed in the process, making sure that not a single breaking change was introduced.

Testing

Talking about testing, it's relatively straightforward.

You need to initialize your source generator (BuilderGenerator is the generator we created earlier), run the generation and compare the result with your expectation:

private static string GenerateCode(string inputCode)
{
    var compilation = CSharpCompilation.Create(TestNamespace, [CSharpSyntaxTree.ParseText(inputCode)],
        [MetadataReference.CreateFromFile(typeof(object).Assembly.Location)],
        new CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary)
    );
    var driver = CSharpGeneratorDriver.Create(new AttributesGenerator(), new BuilderGenerator());
    driver.RunGeneratorsAndUpdateCompilation(compilation, out var outputCompilation, out _);
    return outputCompilation.SyntaxTrees.Last().ToString().Trim();
}

[Theory]
[InlineData("...")]
[InlineData("...")]
[InlineData("...")]
[InlineData("...")]
[InlineData("...")]
public void VerifyCodeGeneration(string sample)
{
    var inputCode = File.ReadAllText($"Files/{sample}_Input.txt").Trim();
    var expectedGeneratedCode = File.ReadAllText($"Files/{sample}_Expected.txt").Trim();
    Assert.Equal(NormalizeLineBreaks(expectedGeneratedCode), NormalizeLineBreaks(GenerateCode(inputCode)));
}

Each test data focuses on a specific feature.
For example, here's my input file when testing a mandatory property with a validation rule:

namespace Vonage.TestProduct.TestRequest;
using Vonage.Common.Validation;

[Builder]
public readonly partial struct MyRequest : IVonageRequest
{
    [Mandatory(0)]
    public string Name { get; internal init; }

    [ValidationRule]
    internal static Result<MyRequest> VerifyName(MyRequest request) =>
        InputValidation.VerifyNotEmpty(request, request.Name, nameof(request.Name));
}

And here's the expected output that I will compare to the generator's output:

using Vonage.Common.Client;
using Vonage.Common.Monads;
using Vonage.Common.Validation;

namespace Vonage.TestProduct.TestRequest;
public interface IBuilderForName
{
    IBuilderForOptional WithName(string value);
}

public interface IBuilderForOptional : IVonageRequestBuilder<MyRequest>
{
}

public partial struct MyRequest
{
    public static IBuilderForName Build() => new MyRequestBuilder();
}

internal struct MyRequestBuilder : IBuilderForName, IBuilderForOptional
{
    private string name;
    public MyRequestBuilder()
    {
        this.name = default;
    }

    public IBuilderForOptional WithName(string value) => this with
    {
        name = value
    };
    public Result<MyRequest> Create() => Result<MyRequest>.FromSuccess(new MyRequest { Name = this.name, }).Map(InputEvaluation<MyRequest>.Evaluate).Bind(evaluation => evaluation.WithRules(MyRequest.VerifyName));
}

Resources

Everything I shared above is publicly available.

Whether you'd like to verify I'm not lying, see the entire implementation or take some code, please yourself; it's all open-source code.

SourceGenerator project: https://github.com/Vonage/vonage-dotnet-sdk/tree/main/Vonage.SourceGenerator
SourceGenerator test project: https://github.com/Vonage/vonage-dotnet-sdk/tree/main/Vonage.SourceGenerator.Test
VerifyCodeRequest: https://github.com/Vonage/vonage-dotnet-sdk/blob/main/Vonage/VerifyV2/VerifyCode/VerifyCodeRequest.cs
VerifyCodeRequest tests: https://github.com/Vonage/vonage-dotnet-sdk/blob/main/Vonage.Test/VerifyV2/VerifyCode/RequestBuilderTest.cs

Wrapping up

With source generators, I was (so far) able to remove roughly 1'500 lines of repetitive code without making compromises on functionalities, nor any change in my builder's public api. It is also much easier to add new builders now: a couple attributes on a request, and we're ready to roll.

The next step is to iterate on my source generator to support more advanced use cases.I already handle more specific use cases that I didn't detailed above, like

Optional Booleans which defines a default value and exposes an explicit method to change the state, like default is true, and "Disable" sets the value to false. This improves the experience overall by making the intent explicit, instead of relying on true/false values.
Optional values with default which allows setting default values for Optional properties.

For sure, I won't be able to replace all my builders; but being able to substitute standard ones is already a big win.

I hope you learned something today.
Happy coding, and see you soon!

During presentations of "Throw exceptions... away from your codebase", I've been asked a lot "Why I use so much on the Builder pattern?". So, I just wrote a post about it. On the menu: Immutability, Parsing, Validation, and Fluent APIs.

Guillaume Faas — Mon, 17 Feb 2025 06:11:05 +0000

Guillaume Faas

Feb 13 '25

Why I use (and abuse) the Builder pattern

#dotnet #monads #design #programming

7 min read

Why I use (and abuse) the Builder pattern

Guillaume Faas — Thu, 13 Feb 2025 06:22:31 +0000

When presenting my talk about Monads, one question kept coming up: "Why do you rely so much on the Builder pattern?".

I didn't implement that pattern just because it looks cool. I've observed recurring problems, and solving them led me to that particular solution.

So, when people see one of my builders, they often don't see what led to this particular implementation.

Let's answer that one today.

Disclaimer: This post is highly personal and opinionated. It's based on my experience, observations and preferences. It's not a one-size-fits-all solution, nor the only way to solve the problems I'm going to present. It's just the way I do it.

How we got here

We've all, at some point, instantiated an object like this:

public class Food
{
    public string Name { get; set; }
    public DateTime ExpirationDate { get; set; }
    public string Description { get; set; }
}

var apple = new Food
{
    Name = "Apple",
    ExpirationDate = DateTime.Now.AddDays(7),
    Description = "An apple",
};

It's simple, clean, efficient and works... except, I see a multitude of issues. I won't even talk about Food being an anemic model (pure DTO style) without any proper behavior and absolutely no encapsulation. This is for another time.

Problem #1: Mutability

Our Food class is mutable - we can change its properties anytime:

var apple = new Food
{
    Name = "Apple",
    ExpirationDate = DateTime.Now.AddDays(7),
    Description = "An apple",
};
apple.ExpirationDate = DateTime.Now.AddDays(14);

Mutability seems useful, but it's a ticking bomb. Changing an object's state introduces complexity, and you'll find yourself constantly evaluating the state of such object.

Immutability, on the other hand, ensures an object cannot be changed after its creation, leading to benefits like data integrity, thread safety, and a limitation of side effects.

We have options to make our Food class immutable, such as using readonly/init-only properties or transforming it into a record.

// Init-only properties
public class Food
{
    public string Name { get; init; }
    public DateTime ExpirationDate { get; init; }
    public string Description { get; init; }
}

// Record
public record Food(string Name, DateTime ExpirationDate, string Description);

A question often arises at this stage: "What if we need to change the state of an immutable object?". Simple, you don't - you create a new object with a new state:

var freshApple = apple with { ExpirationDate = DateTime.Now.AddDays(14) };

Happy yet? Not really. We fixed one problem, but others remain.

Problem #2: Parsing

Making our class immutable already simplifies validation: since the object can’t change, validation occurs only once.

I follow the "Parse, don't Validate" approach which ensures only valid objects can be created. Parsing is about transforming a less structured input into a more structured output - in our case, turning {string, DateTime, string} into a Food object.

However, validation with auto-properties is tricky. One option is to define the validation as a lambda inside each init property with an explicit backing fields - but that feels clunky, especially since properties aren't mandatory, meaning you can't enforce required field. So... you'll have to validate post-creation, and we're back to square one. Another option is to enforce the use of a constructor, which record types already do.

For example, we don't want a Food instance to be created with past expiration dates:

var apple = new Food("Apple", DateTime.Now.AddDays(-10), string.Empty };

public record Food(string Name, DateTime ExpirationDate, string Description)
{
     // Validation logic...
}

But here's the problem: A valid input will produce a valid Food object - what will an invalid input produce?

With constructors, we have no control over the return type - the constructor must return a Food instance. This leaves two possible options:

Returning null - a dangerous option, it's called the "billion-dollar mistake" by Tony Hoare for a reason.
Throwing an exception - terrible choice for a predictable validation failure.

Neither is great.

A better approach is to rely on a static factory method as the single point of entry to create a Food object, giving us control over the return type.

var apple = Food.Create("Apple", DateTime.Now.AddDays(-10), string.Empty);

public static Food Create(string name, DateTime expirationDate, string description)
{
    // Validation logic.
}

One important thing to note: we have to rule out the record type. Even with a private constructor, with expressions can bypass our single point of entry.

I put code transparency and predictability quite high in my priorities, which is why I would favor Monads for this (see my "The Monad Invasion" series).

var apple = Food.Create("Apple", DateTime.Now.AddDays(-10), string.Empty);

public record Error(string Reason);
public static Either<Error, Food> Create(string name, DateTime expirationDate, string description)
{
    if (string.IsNullOrEmpty(name))
    {
        return new Error("Name cannot be empty");
    }

    if (expirationDate < DateTime.Now)
    {
        return new Error("Expiration date cannot be in the past");
    }

    return new Food(name, expirationDate, description);
}

The intent is clear, and the outcome is transparent: creating a Food instance can fail.

Problem #3: Too many parameters

Our Food class currently has three properties. What if it had 15? 20? 50?

public static Food Create(string name, 
    DateTime expirationDate, 
    string description,
    string category,
    decimal weight,
    decimal price,
    ...)
{
    // ...
}

Our static factory method solved a problem, but it struggles as the number of parameters grows. IDEs often provide warnings against constructors with more than 5 parameters, and for good reason. Methods with many parameters or multiple overloads are a nightmare to maintain.

We need a better way to create complex objects while keeping the benefits we've gained so far.

This is where the Builder pattern offers an interesting solution.

var apple = Food.Builder()
    .WithName("Apple")
    .WithExpirationDate(DateTime.Now.AddDays(7))
    .WithDescription("An apple")
    .Build();

Each method takes one parameter, and Build handles validation before creating the object.

The Builder ticks all the boxes

Immutability - the builder acts as a factory, and is able to create immutable objects.
Validation - the builder can validate the object when we want to create it.
Control over validation failure - the builder is able to return a predictable result when validation fails.
Scalability - the builder handles a large number of parameters without becoming a mess.

A well-designed Builder pattern also helps guide users. By chaining methods, developers naturally discover what fields are required and what comes next - your IDE will show it for you.

For example, our API ensures Name and ExpirationDate are mandatory, while Description is optional (can be null or empty).

var apple = Food.Builder()
    // Only option is .WithName
    .WithName("Apple")
    // Only option is .WithExpirationDate
    .WithExpirationDate(DateTime.Now.AddDays(7))
    // User has two options:
    // Optional properties like .WithDescription
    // Or .Build() to create the object
    .WithDescription("An apple")
    // User has two options:
    // Other optional properties
    // Or .Build() to create the object
    .Build();

In open-source software, making code self-explanatory is a game-changer.

Downsides

If Builders were free, everybody would use them. Sadly, they're not and require a fair amount of boilerplate. Your builder needs a class, a method for each property, and interfaces to guide the user - not to mention that you should also test your code.

Overall, we're talking about 50+ extra lines of code for an object like Food. This is one. simple. object.

Libraries like FluentBuilder generate builders via SourceGenerators, helping a lot with the boilerplate, but we're losing the flexibility for custom scenarios.

While Builders solve many problems, they aren't always the best choice. If your object is simple and rarely changes, a factory method might be sufficient. On my end, I prefer to start with a factory method and switch to a Builder when the object becomes more complex.

Another downside is that validation gets separated from the object itself - data is on the object, while validation is on the Buidler. This can potentially lead to encapsulation issues (See Tell, Don't Ask). My advice: keep them close to maintain strong cohesion and use the internal keyword to expose only what's necessary. That being said, I've never encountered a scenario where it was a critical problem.

Example

Here's an actual implementation from my current codebase, the Vonage .NET SDK.

This is the initial object we're willing to create.

public readonly struct CheckRequest : IVonageRequest
{
    // Immutable properties
    public PhoneNumber PhoneNumber { get; internal init; }
    public int Period { get; internal init; }
    // The static Build() method exposes the builder
    public static IBuilderForPhoneNumber Build() => new CheckRequestBuilder();
}

Source: CheckRequest

This is the builder itself. We're using interfaces to direct what the user can do: the phone number is mandatory, the period is optional (with a default value).

There are two possible paths here:

PhoneNumber (mandatory) -> Build
PhoneNumber (mandatory) -> Period (optional) -> Build

internal struct CheckRequestBuilder : IBuilderForPhoneNumber, IBuilderForOptional
{
    private const int DefaultPeriod = 240;
    private const int MaximumPeriod = 2400;
    private const int MinimumPeriod = 1;
    private int period = DefaultPeriod;
    private string number = default;

    public Result<CheckRequest> Create() =>
        Result<CheckRequest>.FromSuccess(new CheckRequest
            {
                Period = this.period,
            }).Merge(PhoneNumber.Parse(this.number), (request, validNumber) => request with {PhoneNumber = validNumber})
            .Map(InputEvaluation<CheckRequest>.Evaluate)
            .Bind(evaluation => evaluation.WithRules(VerifyAgeMinimumPeriod, VerifyMaximumPeriod));

    // Assign value on the builder
    public IVonageRequestBuilder<CheckRequest> WithPeriod(int value) => this with {period = value};
    // Assign value on the builder
    public IBuilderForOptional WithPhoneNumber(string value) => this with {number = value};

    // Validation
    private static Result<CheckRequest> VerifyAgeMinimumPeriod(CheckRequest request) =>
        InputValidation.VerifyHigherOrEqualThan(request, request.Period, MinimumPeriod, nameof(request.Period));
    // Validation
    private static Result<CheckRequest> VerifyMaximumPeriod(CheckRequest request) =>
        InputValidation.VerifyLowerOrEqualThan(request, request.Period, MaximumPeriod, nameof(request.Period));
}

public interface IBuilderForPhoneNumber
{
    // Will return the next step in the builder, for optional values or to build the object
    IBuilderForOptional WithPhoneNumber(string value);
}

public interface IBuilderForOptional : IVonageRequestBuilder<CheckRequest>
{
    // Will return the final step in the builder to build the object
    IVonageRequestBuilder<CheckRequest> WithPeriod(int value);
}

Source: CheckRequestBuilder

This is a usage example, from the test suite.

[Trait("Category", "Request")]
public class RequestBuilderTest
{
    [Theory]
    [InlineData("")]
    [InlineData(" ")]
    [InlineData(null)]
    public void Build_ShouldReturnFailure_GivenNumberIsNullOrWhitespace(string value) =>
        CheckRequest.Build()
            .WithPhoneNumber(value)
            .Create()
            .Should()
            .BeFailure(ResultFailure.FromErrorMessage("Number cannot be null or whitespace."));

    // ...

    [Theory]
    [InlineData(1)]
    [InlineData(2400)]
    public void Build_ShouldSetPeriod(int value) =>
        CheckRequest.Build()
            .WithPhoneNumber("1234567")
            .WithPeriod(value)
            .Create()
            .Map(number => number.Period)
            .Should()
            .BeSuccess(value);

    // ...
}

Source: RequestBuilderTest

Wrapping Up

Each problem I solved narrowed down the pool of possible solutions, and I landed on Builders because they address issues I consider important. You may disagree, and that's totally fine.

I hope you learned something during that post, and I'm curious to know your thoughts on the subject.

Until next time, cheers!

The Monad Invasion - Part 3: Railway-Oriented Programming

Guillaume Faas — Fri, 15 Nov 2024 12:09:01 +0000

Hello friends,

Our previous post, "The Monad Invasion - Part 2: Monads in action!", introduced a set of various Monads and how they can fit in real-world scenarios.

Today, we will focus on Railway-Oriented Programming (ROP), a functional approach to error handling.

Spoiler: If you've read our previous posts, you observed ROP without actually being aware of it.

Quick Recap

We used our Two-Factor Authentication (2FA) as a real example. This two-steps workflow requires initiating a verification first and then verifying the code sent to the user.

var myPhoneNumber = ...
var result = await StartVerificationRequest.Build()
    .WithBrand("Monads Inc.")
    .WithWorkflow(SmsWorkflow.Parse(myPhoneNumber))
    .Create() // Build the authentication request
    .BindAsync(request => verifyClient.StartVerificationAsync(request)) // Process the authentication request
    .BindAsync(VerifyCodeAsync) // Start the second step if it's a success
    .Match(AuthenticationSuccessful, AuthenticationFailed);

private async Task<Result<Unit>> VerifyCodeAsync(StartVerificationResponse response)
{
    var myCode = ... // Receive verification code based on the specified workflow
    return await response
        .BuildVerificationRequest(myCode) // Build the verification request
        .BindAsync(request => verifyClient.VerifyCodeAsync(request)); // Process the verification request
}

As suggested previously, this snippet already applies ROP. You probably have a lot of questions right now. What is ROP? How does it work? Why is it useful?

Let's start from the beginning, shall we?

Failure Is Expected

It is strictly impossible to build software without handling errors. In the real world, failure can occur at any point during the execution, and we cannot ignore them.

What if we had the same workflow, written in an imperative style?

var myPhoneNumber = ...
var request = await StartVerificationRequest.Build().WithBrand("Monads Inc.").WithWorkflow(SmsWorkflow.Parse(myPhoneNumber)).Create();  
var response = verifyClient.StartVerificationAsync(request);
var myCode = ... // Receive verification code based on the specified workflow
var verificationRequest = response.BuildVerificationRequest(myCode)
var result = verifyClient.VerifyCodeAsync(verificationRequest);    
this.AuthenticationSuccessful();

It looks similar but something important is missing - error handling. Indeed, this snippet only shows the happy path, where everything goes as expected.

Of course, this is not enough - we aim for feature parity between these snippets. In its current state, any failure would cause our system to crash. As we previously mentioned, this flow can fail at various locations:

When building the authentication request
When processing the authentication request
When building the verification request
When processing the verification request

What's the difference if we decide to handle errors then?

var myPhoneNumber = ...
var request = await StartVerificationRequest.Build().WithBrand("Monads Inc.").WithWorkflow(SmsWorkflow.Parse(myPhoneNumber)).Create();
if (request.IsFailure)
{
    // Can fail when Brand is invalid
    // Can fail when PhoneNumber is invalid
    return this.AuthenticationFailed(new Failure("Invalid input."));
}

var response = verifyClient.StartVerificationAsync(request);
if (response.IsFailure)
{
     // Can fail when process can't be initiated
     return this.AuthenticationFailed(new Failure("Cannot initiate verification process."));
}

var myCode = ... // Receive verification code based on the specified workflow
var verificationRequest = response.BuildVerificationRequest(myCode)
if (response.IsFailure)
{
    // Can fail when the code input is invalid
    return this.AuthenticationFailed(new Failure("Invalid code."));
}

var result = verifyClient.VerifyCodeAsync(verificationRequest);    
if (result.IsFailure)
{
    // Can fail when the verification fails
    return this.AuthenticationFailed(new Failure("Verification failed."));
}

return this.AuthenticationSuccessful();

We need to add an important boilerplate code to deal with potential failure. This code is dense and hard to read. We now have more code to handle failures than the happy path itself, which is not a coincidence. We only have a single happy path but multiple reasons to fail.

There's something important to observe here:

This snippet offers the same behaviour as the one from the Quick Recap section, except it takes roughly three times more code to do it.
The cyclomatic complexity also increases significantly, from 1 to 6, in a blink of an eye.

Have I piqued your interest yet? It's time to introduce Railway-Oriented Programming.

Railway-Oriented Programming

Note: This section shares resources from the
talk "Railway-Oriented Programming — error handling in a functional way"
by Scott Wlaschin.
More details are available on F#ForFunAndProfit.

Railway-Oriented Programming is a functional approach to error handling. The main idea is to consider the "Happy Path" (Green) as the main track, providing our expected behaviour.

In the example above, our workflow is composed of three steps:

Validate an input.
Update a record - if the input is valid.
Send a notification - if the record update is successful.

Here's what it looks like in an imperative fashion:

if (this.Validate(input))
{
    try
    {
        var record = this.Update(input);
        this.SendNotification(record);
    }
    catch (Exception)
    {
        ...        
    }
}

We consider our workflow successful only if these three steps are successful.

We remain on that "Happy Path" until we face an error, which leads us to a "Failure Path" (Red). When this happens, we carry the failure until the end of the flow. It's crucial that we stick to the main path, as it's the only way to ensure the full execution of our workflow.

In the example above, we skip the update step when the validation fails. This is only possible because our functions return multiple possible states: a Success or a Failure.

Does it ring a bell? What a coincidence, we use Monads for that! You didn't see that one coming - or did you?

In our previous post, we saw how to change the status of a Monad from one state to another using the .Bind() method. This fundamental concept allows us to create this branching between tracks.

There's no magic here. The branching didn't disappear with a magic wand or anything like that. The branching is now internal to our Monad.

Have a look at how Bind is implemented on our custom Monad:

return this.IsFailure ? Result<TB>.FromFailure(this.failure) : bind(this.success);

Our decision mechanism - a ternary operator - verifies if the current state is a failure or a success.

If it is a failure, we return the current failure; nothing happens.
If it is a success, we call the bind function to continue the flow.

As such, we can chain our operations together, and the flow will automatically switch to the failure path if any of the operations fail.

Here's the same workflow as before, but this time using ROP:

var result = input.Bind(Validate).Bind(Update).Bind(SendNotification);

Impressive, right? We reduced our code to a single line while covering the same features.

Let's Play a Little Game

Here's a code sample from our .NET SDK that allows us to authenticate for one of our Network APIs.

Can you find out what the railway tracks look like? Where can our workflow fail?

You don't need to know what's happening here; there's no logic. Focus on the flow.

public Task<Result<AuthenticateResponse>> AuthenticateAsync(Result<AuthenticateRequest> request) =>
    request.Map(BuildAuthorizeRequest)
        .BindAsync(this.SendAuthorizeRequest)
        .Map(BuildGetTokenRequest)
        .BindAsync(this.SendGetTokenRequest)
        .Map(BuildAuthenticateResponse);

The answer is quite simple - our railway contains two points of branching:

When sending the authorize request.
When sending the get token request.

This is explicit because we rely on the Bind method for those operations.

For another comparison, here's the same code written in an imperative style:

public async Task<Result<AuthenticateResponse>> AuthenticateAsync(AuthenticateRequest request)
{
    var authorizeRequest = BuildAuthorizeRequest(request);
    var authorizeResponse = await this.SendAuthorizeRequest(authorizeRequest);
    if (authorizeResponse.IsFailure)
    {
        return Result<AuthenticateResponse>.FromFailure(authorizeResponse.Failure);
    }

    var getTokenRequest = BuildGetTokenRequest(authorizeResponse.Success);
    var getTokenResponse = await this.SendGetTokenRequest(getTokenRequest);
    if (getTokenResponse.IsFailure)
    {
        return Result<AuthenticateResponse>.FromFailure(getTokenResponse.Failure);
    }

    return BuildAuthenticateResponse(getTokenResponse.Success);
}

As you can see, reading and understanding the flow is much easier than in the imperative style, and the function is smaller.
We achieved that by reducing the cognitive load of our method — reducing the required quantity of technical information (branching,
logic, variables, etc.) helps to make the code "fit in your head" (
see "Code that fits in your head" by Mark Seemann).

Processes Fail For Multiple Reasons

Looking at our previous example, our workflow can fail at two points - this could be a problem for us.

Our failure path carries what we define as a Failure state. We implemented our Monad so that it can carry either a Success or a Failure value using generics. We can picture it as a Result<TFailure, TSuccess.

See where I'm going?

Because of how generics work in C#, an instance of Result must always carry the same type of failure. In other terms, all our failures must have the same type - that's a problem as you may decide to treat a parsing failure differently than an API failure.

We cannot blame Monads or ROP for this issue - it is a language limitation. In comparison, this is where a language like F# shines, as it allows us to define a discriminated union type that can carry multiple types of failures. Still, hope is possible - discriminated unions will eventually come to C#.

While we can't ignore this limitation, it doesn't mean we're entirely stuck. One way to group different failures under
the same generic type is to use a base class or an interface.

In the .NET SDK, I implemented an IResultFailure interface that all failures must implement. It allows us to group different failures (or reasons to fail - parsing, authentication, etc.) on the same failure path and define dedicated behaviours using the Type property.

public interface IResultFailure
{
    /// <summary>
    ///     The type of failure.
    /// </summary>
    Type Type { get; }

    /// <summary>
    ///     Returns the error message defined in the failure.
    /// </summary>
    /// <returns>The error message.</returns>
    string GetFailureMessage();

    /// <summary>
    ///     Converts the failure to an exception.
    /// </summary>
    /// <returns>The exception.</returns>
    Exception ToException();

    /// <summary>
    ///     Converts the failure to a Result with a Failure state.
    /// </summary>
    /// <typeparam name="T">The underlying type of Result.</typeparam>
    /// <returns>A Result with a Failure state.</returns>
    Result<T> ToResult<T>();
}

This is not a perfect solution and probably not the most elegant one. But this is similar to handling different types of exceptions, like the following example:

try { ... }
catch (ExceptionA) { ... }
catch (ExceptionB) { ... }
catch (ExceptionC) { ... }

// ---

switch (failure)
{
    case HttpFailure httpFailure:
        DoSomethingWithHttpFailure(httpFailure);
        break;
    case ResultFailure resultFailure:
        DoSomethingWithResultFailure(resultFailure);
        break;
    default:
        DoSomethingWithFailure(failure);
        break;
}

As you can see, ROP allows us to use the same functionalities as exceptions - it's not a replacement, just an alternative to error handling which looks a bit different.

Conclusion

And there we have it — our third post in "The Monads Invasion" series. This time, we focused on Railway-Oriented Programming (ROP) to show how you can use Monads even further to handle errors.

The key takeaway? There's no loss when using Monads for error handling compared to a standard exception-based approach; everything you do using exceptions can be done with Monads. You'll likely find your code cleaner, easier to read, and more explicit about its intent.

Now, the real question: are you ready to try it?

I suggest starting small and easing into it. There's a learning curve like anything new, but stick with it, and you'll see the benefits.

If you have any questions or want to chat, feel free to hit me up on my LinkedIn, share your feedback on the .NET SDK repository or join us on
the Vonage Developer Slack. You can also message us on @VonageDev on X. We're all in this together, and your voice matters.

Happy coding, and I'll catch you later!

How I Became a Millionaire with Vonage APIs

Guillaume Faas — Wed, 13 Nov 2024 07:28:12 +0000

Spoiler: I'm not actually a millionaire.

We’ve all dreamt about it — sitting in the hot seat on 'Who Wants to Be a Millionaire', staring down that final question, the host waiting for your answer.
But what if, in a world of multiverses and alternate realities, I walked away with a fat check in hand?

What if I told you that I figured out a way to win. Every. Single. Time.

In this post, we'll be stepping into this alternate universe for a moment — where Vonage’s APIs made me a millionaire, and no one suspected a thing.

The Perfect Heist

In this universe, I'm not just a contestant on a game show - I'm the mastermind behind the perfect heist.
One final questions separates me from the grand prize.
I have carefully saved my last lifeline, "Call a friend", for this exact moment.
The stakes couldn't be higher, but I'm cool.
I'm in control.

Why? Because this isn't your ordinary phone call.

I've got an ace up my sleeve - a friend who knows everything.
Instead of calling an actual person, I've set up something a little... unconventional.
The number I gave the show is a virtual phone number I purchased from Vonage.

The second the host dials the number, my meticulous planned operation kicks into action.
No one in the audience, not even the host, has any idea what's happening behind the scenes.
A chain of automated processes, all powered by Vonage APIs, springs to life to provide me the right answer.

The perfect heist isn't just about getting away with it - it's about pulling it off so smoothly that no one even realizes anything unusual happened.

Let me guide you through how I pulled it off.

Insert 'Evil Laugh' here

Step 1: We Need A Number

Every heist starts with the right tools, and in this case, we need a number — a virtual one.
Why a virtual number?
Because it’s the key to controlling the flow of information, giving us the ability to intercept the call and manipulate it on our terms.
It supports both inbound and outbound for calls and messages.
No device required, no manual intervention — just a virtual number and a webhook.

A virtual number allows you to receive calls and route them anywhere — even to an automated system.
In this case, the call will trigger a series of interactions without anyone realizing it’s anything other than a normal phone call.
You can read more about virtual numbers here.

More specifically with Vonage, the process is relatively straightforward.
You can get started with the Vonage Voice API to purchase a number and configure it to point to a webhook of your choice — in this case, the webhook that will handle the call.

Once the host dials the number, the call will automatically be routed to our webhook.
From there, the real fun begins.

Step 2: Our Inside Man

When the host dials the number, someone has to pick up the phone, right?
But it’s not just anyone on the other end of the line.
No, this is where we introduce our inside man: Adam.
He’s a very knowledgeable 40-year-old friend, living in London, ready to help with the toughest questions.

But here’s the twist — Adam doesn’t actually exist.
He’s completely synthetic, brought to life by Text-to-Speech (TTS) feature.
When the host calls, Adam’s voice is generated in real-time, and it’s so smooth and convincing that no one would ever suspect they're not talking to a real person.

He has the full package: a relaxed, natural-sounding voice and a proper London accent, making him the perfect accomplice.

// Our webhook
[HttpPost("answer")]
public IActionResult Answer()
{
    // Creating a Talk action with Adam's greeting message
    var talkAction = VoiceAdapter.MakeAdamTalk(GreetingsMessage);
    ...
    // Return a call control object to define the call flow 
    return this.Ok(new Ncco(talkAction, ...));
}

public static TalkAction MakeAdamTalk(string text) =>
    new TalkAction
    {
        Text = text,
        Language = "en-GB",
        Style = 6, 
        Premium = true, // Provides a more natural voice    
    };

private const string GreetingsMessage = "Adam here. What can I do for you?";

As shown in the code snippet, we return a Call Control Object (NCCO) with a Talk action to make Adam speak.
When the call comes through, he will greet the host with a message, ensuring the conversation feels real from the very first word.

Step 3: Text transcription

We've been welcomed by our inside man; it's time to share our final question with him.
The next step in our heist is critical: converting my spoken question into text.
For this, we'll use the Speech-to-Text functionality of Vonage Voice API.

In our webhook, after Adam's greeting, we need to add a Speech input action to capture my question.

[HttpPost("answer")]
public IActionResult Answer()
{
    var talkAction = VoiceAdapter.MakeAdamTalk(GreetingsMessage);
    var inputAction = new MultiInputAction
    {
        Type = [NccoInputType.Speech],
        // Url where the transcription will be sent
        EventUrl = apiUrl + "/Webhooks/asr"],
        Speech = new SpeechSettings
        {
            Language = "en-GB",
            MaxDuration = 20,
            EndOnSilence = 2,
        },
    };
    return this.Ok(new Ncco(talkAction, inputAction));
}

// Webhook that will receive the text transcription
[HttpPost("asr")]
public async Task<IActionResult> Speech(MultiInput speechResponse) 
{
    ...
}

Our Call Control Object now contains two actions that will execute in sequence: Adam will greet the host, and then the system will listen for my question.
Once the system detects that my speech has ended, either by a period of silence or reaching the maximum duration, the transcription will be sent to the webhook we’ve set up.

Here's the transcription of my question:

Hey Adam! Look, I'm currently in the game "Who wants to be a millionaire" with Jeremy Clarkson, and I'm calling you as part of my last joker "Call a friend".
I need your help with the final question. Here it is: "During the Cold War, the US government built a bunker to house Congress under what golf resort?"
A: The Breakers  B: The Greenbrier C: Pinehurst D: The Broadmoor

This step is absolutely essential. Text is data — and in this heist, data is everything. It can be manipulated, analyzed, and, most importantly, passed along to the next phase of our plan.

Step 4: The Oracle

Now that we have the text transcription of the question, it’s time to consult our all-knowing entity: GPT4.
In this heist, it is our oracle — the one who holds all the answers.

Once the transcription reaches our webhook, we send the text, along with a custom prompt, to GPT4.
This prompt ensures that the AI delivers the accurate response we need to win, as Adam.

Context: 
We're in the game "Who wants to be a millionaire", and I'm calling you as part of my last joker "Call a friend".
You are Adam, a 40 year old male using en-UK language. 
You answer must look like you genuinely picked up the phone to give me an answer, and pretend to think about the answer.
You answer will be transcribed through text-to-speech so avoid anything a person wouldn't say. 
No need for greetings, and wish me luch for the game at the end of your reply.

[HttpPost("asr")]
public async Task<IActionResult> Speech(MultiInput speechResponse) =>
    await FetchQuestion(speechResponse.Speech.SpeechResults)
        .MapAsync(aiAdapter.AskAsync)
        .Map(VoiceAdapter.MakeAdamTalk)
        .Map(this.Ok)
        .IfNone(this.Ok(VoiceAdapter.MakeAdamTalk(FailedToUnderstandQuestion)));

private static Maybe<string> FetchQuestion(SpeechRecognitionResult[] results) =>
    results.Length != 0 ? results.First().Text : Maybe<string>.None;

public Task<string> AskAsync(string question)
{
    var client = new ChatGpt(
        configuration["openai-key"] ?? throw new InvalidOperationException("Missing OpenAI key."),
        new ChatGptOptions { Model = "gpt-4-turbo" });
    return client.Ask(configuration["prompt"] + "\n" + question);
}

Thanks to our custom prompt, the Oracle will generate a text response where Adam appears to be thoughtfully considering the answer.
Whether it’s a complex historical fact or a tricky bit of trivia, it will produce the perfect response, ready to be delivered in Adam’s voice.

Here's the response we get from my question:

Hmm... that’s a tough one. Let me think... 
I remember reading about this a while ago. 
I don’t think it’s The Breakers or Pinehurst, those don’t seem right. 
I’m leaning towards The Greenbrier, if I’m not mistaken. 
Yeah, I’m pretty sure it’s B: The Greenbrier. 
That’s the one they used for Congress during the Cold War.

Good luck, hope you nail it!

However, there’s one caveat: these things don’t happen as fast as snapping your fingers.
Let’s consider our scenario:

I deliver my question.
After two seconds of silence, the voice feed is transcribed into text.
The question is sent to GPT, which generates the answer.

We’re looking at potential latency — anywhere from five to ten seconds before we receive the answer.
That’s precious time ticking away, and it could jeopardize my whole plan.

A potential technical solution would be to rely on OpenAI's Realtime API, which was recently released.
But unfortunately, that's a luxury of time I don't have.

Instead, I’ve thought of a clever workaround: small talk.
I know Jeremy Clarkson loves his Ford GT40, and if I casually bring it up, I can get him talking.
His enthusiasm for cars will buy me the few extra seconds I need for the AI to generate the answer.

And once it’s ready?
We send a Talk action with the response as a response to our endpoint, and Adam will confidently deliver the correct answer to the host.

Step 5: The Win

With the answer in hand, I repeat Adam’s response — "B: The Greenbrier" — back to the host, calm as ever.
And just like that, I’ve won!

From the outside, no one suspects a thing. To the audience, it looks like I’ve called a living, breathing human who just happens to know every answer. Little do they know, it was all powered by Vonage APIs, a bit of AI, and — most importantly — creativity.

The perfect heist wasn’t about the tools, but about how I used them.

Wrapping Up

Back to reality, I’m obviously not a millionaire — nor a criminal mastermind.

In truth, my plan has plenty of holes.
For one, I’d have to make sure the host doesn’t ask Adam any follow-up questions, or worse, call the number before the final moment.
The workflow I’ve set up is also pretty rigid: Greeting → Question → Answer.
If we deviate from that, the entire plan falls apart.

And, of course, there’s the small matter of making it to the final question!
I don’t have the knowledge to answer 14 questions on "Who Wants to Be a Millionaire" — maybe one of my multiverse variants does, but certainly not me.

On the technical side, Speech-to-text and Text-to-speech may not be new technologies, but they remain incredibly useful.
However, the real takeaway from this post comes from automation - plugging platforms together like Vonage and OpenAI to create specific workflow.
It's not just about using cutting-edge tools, but how you combine them to create something unique.

As usual, feel free to hit me up on my LinkedIn or join us on the Vonage Developer Slack.
You can also message us on @VonageDev on X.

Happy coding, and I'll catch you later!

Migration Guide for .NET SDK v7.0.0

Guillaume Faas — Tue, 09 Apr 2024 11:26:51 +0000

Hello friends,

Our .NET SDK welcomed a new major release
recently - v7.0.0 is now available!

Being a major release, you might encounter side effects while updating to this version.
This is what this blog post is about: helping you identify and fix those problems.

The overall purpose of this release is to support new features which required a breaking change and start de-cluttering
the codebase.

Prerequisites

This migration guide applies when migrating from v6.X.X - If you're still on v5.X.X, we highly recommend upgrading
to v6.16.0 first, using the
dedicated migration guide.

Migration Steps

Everything Flagged With an 'Obsolete' Annotation Has Been Removed

When upgrading to a newer release, you may have noticed a warning indicating you're using an obsolete method.
Indeed, we flagged these changes with an Obsolete tag.

Please note that there's always a substitute when we decommission something.

Synchronous Methods

So far, many features are available with both synchronous/asynchronous implementation.
All synchronous methods have been removed in v7.0.0.
If you are still required to call a Vonage API in a synchronous context, you will have to call the asynchronous version
with
either .Result or .Wait() to wait for the result synchronously.

// Using v6.X.X
applicationClient.DeleteApplication(applicationId);

// Using v7.X.X and above
await applicationClient.DeleteApplicationAsync(applicationId);
// Or
applicationClient.DeleteApplicationAsync(applicationId).Wait();

SubAccounts Features on 'AccountClient'

SubAccounts features were initially implemented by a contributor on the AccountClient while the product was still in
beta.
With the GA release, all SubAccounts features are available on the SubAccountsClient, which makes previous features
obsolete.

// Using v6.X.X
var subAccount = await vonageClient.AccountClient.RetrieveSubAccountAsync(subAccountKey);
// Using v7.X.X and above
var request = GetSubAccountRequest.Parse(subAccountKey);
var subAccount = await vonageClient.SubAccountClient.GetSubAccountAsync(request);

'CreateApplicaitonAsync' on 'ApplicationClient'

The current method contains a typo.

// Using v6.X.X
var application = await applicationClient.CreateApplicaitonAsync(request);

// Using v7.X.X and above
var application = await applicationClient.CreateApplicationAsync(request);

'CreateCall' on 'VoiceClient'

This method offers three different signatures.
Only the one with a CallCommand parameter will remain to avoid Primitive Obsession and rely on a proper
ValueObject.

// Using v6.X.X
var callResponse = voiceClient.CreateCallAsync(toNumber, fromNumber, ncco);
var callResponse = voiceClient.CreateCallAsync(toEndpoint, fromNumber, ncco);
var callResponse = voiceClient.CreateCallAsync(callCommand);


// Using v7.X.X and above
var callResponse = voiceClient.CreateCallAsync(callCommand);

Constructors on 'Credentials'

Creating a Credentials instance should be done using a factory method or from a Configuration instance.
Constructors will be hidden, and the object will remain immutable.

We highly recommend you use
our extension methods to dynamically
initialize Credentials from your appsettings.json file.

// Using v6.X.X
var credentials = new Credentials()
{
    ApiKey = apiKey,
};
var credentials = new Credentials(apiKey, apiSecret);
var credentials = Credentials.FromApiKeyAndSecret(apiKey, apiSecret);
var credentials = Credentials.FromAppIdAndPrivateKey(apiKey, apiSecret);


// Using v7.X.X and above
var credentials = Credentials.FromApiKeyAndSecret(apiKey, apiSecret);
var credentials = Credentials.FromAppIdAndPrivateKey(apiKey, apiSecret);
var credentials = configuration.BuildCredentials();
// Recommended
var credentials = serviceCollection.GetRequiredService<Credentials>();

Access to Vonage URLs

All URLs have been moved to a nested object (VonageUrls) to simplify the Configuration class and allow
multi-region URLs.

// Using v6.X.X
var url = configuration.NexmoApiUrl;
var url = configuration.RestApiUrl;
var url = configuration.VideoApiUrl;
var url = configuration.EuropeApiUrl;

// Using v7.X.X and above
var url = configuration.VonageUrls.Nexmo;
var url = configuration.VonageUrls.Rest;
var url = configuration.VonageUrls.Video;
var url = configuration.VonageUrls.Get(VonageUrls.Region.EMEA);

Remove 'Input' Webhook Object

This item has been rendered obsolete due to the new multi-input functionality. Please add the Dtmf arguments to your
input action and use the MultiInput object, as recommended in
our documentation.

Remove 'Portuguese" Language in Meetings API

This language has been removed in favor of 'Portuguese-Brazilian'.

// Using v6.X.X
var language = UserInterfaceLanguage.Pt;


// Using v7.X.X and above
var language = UserInterfaceLanguage.PtBr;

Remove 'VoiceName' From 'TalkCommand' and 'TalkAction' in Voice

This parameter has been made obsolete
by the language and style fields.

Add New Timeouts on Voice Webhooks in Application API

Adding new timeouts requested (connection_timeout, socket_timeout) on Voice Webhooks.
Creating a specific structure, different from other webhooks, required to break the Capability inheritance.

Rename Settings Key From 'appSettings' to 'vonage'

In order to make the settings more explicit and reduce the chances of conflict with other libraries, the base key has
been
updated.

Also, "Vonage." has been removed from every key to de-clutter the section. Finally, a few keys have been completely
renamed:

Old Key	New Key
Vonage.Vonage_key	Api.Key
Vonage.Vonage_secret	Api.Secret
Vonage.Vonage.Url.Api.Europe	Url.Api.EMEA
N/A	Url.Api.AMER
N/A	Url.Api.APAC

Using v6.X.X

{
  "appSettings": {
    "Vonage.UserAgent": "...",
    "Vonage.Url.Rest": "...",
    "Vonage.Url.Api": "...",
    "Vonage.Url.Api.Europe": "...",
    "Vonage.Url.Api.Video": "...",
    "Vonage.Vonage_key": "...",
    "Vonage.Vonage_secret": "...",
    "Vonage.Application.Id": "...",
    "Vonage.Application.Key": "...",
    "Vonage.Security_secret": "...",
    "Vonage.Signing_method": "...",
    "Vonage.RequestsPerSecond": "...",
    "Vonage.RequestTimeout": "..."
  }
}

Using v7.X.X and above

{
  "vonage": {
    "UserAgent": "...",
    "Url.Rest": "...",
    "Url.Api": "...",
    "Url.Api.EMEA": "...",
    "Url.Api.AMER": "...", 
    "Url.Api.APAC": "...",
    "Url.Api.Video": "...",
    "Api.Key": "...",
    "Api.Secret": "...",
    "Application.Id": "...",
    "Application.Key": "...",
    "Security_secret": "...",
    "Signing_method": "...",
    "RequestsPerSecond": "...",
    "RequestTimeout": "..."
  }
}

Make StartTime Nullable on Answered Webhook

As defined in the specs, the StartTime
is now nullable.

Remove 'EventUrl' and 'EventMethod' From 'ConversationAction'

As defined in the specs,
the Conversation action doesn't have an EventUrl or an EventMethod.

Make 'From' Mandatory in VerifyV2 WhatsApp Workflow

The From property used to be optional - it is now mandatory.

// Using v6.X.X
var workflow =  WhatsAppWorkflow.Parse(ValidToNumber);
var workflow =  WhatsAppWorkflow.Parse(ValidToNumber, ValidFromNumber);

// Using v7.X.X and above
var workflow =  WhatsAppWorkflow.Parse(ValidToNumber, ValidFromNumber);

Conclusion

The migration guide is also available on
our GitHub repository.

Don't hesitate to report any issue on GitHub or join us on
the Vonage Developer Slack, and we will get back to you.
You can also follow us on X to stay up-to-date with our latest news.

Happy coding, and see you soon!