chore: add docs and examples for a custom HTTP client

README.md

@@ -40,6 +40,47 @@ var res = await sdk.Addresses.ListAsync(
 ```
 <!-- End SDK Example Usage [usage] -->
 
+<!-- Start Custom HTTP Client [http-client] -->
+## Custom HTTP Client
+
+The following is taken from [Speakeasy's C# design](https://www.speakeasyapi.dev/docs/sdk-design/csharp/methodology-csharp#http-client):
+
+> By default the C# SDK will instantiate its own `SpeakeasyHttpClient`, which uses the
+`System.Net.HttpClient` under the hood. The default client can be overridden by passing
+a custom HTTP client when initializing the SDK:
+
+```csharp
+var sdk = new ShippoSDK(client: new CustomHttpClient());
+```
+
+> The provided HTTP Client must implement the `ISpeakeasyHttpClient` interface as defined
+in `Utils.SpeakeasyHttpClient.cs`: ...
+
+> This can be useful if you want to use a custom HTTP Client that supports a proxy or
+other custom configuration.
+
+> Below is an example of custom client that inherits from the internal
+`SpeakeasyHttpClient` class, which itself implements the `ISpekeasyHttpClient` interface.
+This client simply adds a header to all requests before sending them:
+
+```csharp
+using Shippo.Utils;
+
+public class CustomHttpClient : SpeakeasyHttpClient
+{
+    public CustomHttpClient() {}
+
+    public override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request)
+    {
+        request.Headers.Add("X-Custom-Header", "custom value");
+        return await base.SendAsync(request);
+    }
+}
+```
+
+A further example is included in the `ShippoTests` project in this repo.
+<!-- End Custom HTTP Client [http-client] -->
+
 <!-- Start Available Resources and Operations [operations] -->
 ## Available Resources and Operations
 

ShippoTests/Integration/Fixtures.cs

@@ -8,6 +8,8 @@ public SDKFixture()
     {
         SDK = new ShippoSDK(
             apiKeyHeader: Environment.GetEnvironmentVariable("SHIPPO_TOKEN"),
+            client: Environment.GetEnvironmentVariable("SHIPPO_TESTHTTPCLIENT") == "true"
+                ? new TestHttpClient() : null,
             serverUrl: Environment.GetEnvironmentVariable("SHIPPO_URL"),
             shippoApiVersion: Environment.GetEnvironmentVariable("SHIPPO_API_VERSION")
         );

ShippoTests/Integration/Helpers.cs

@@ -19,3 +19,72 @@ public class Helpers
         )).Results;
     }
 }
+
+public class TestHttpClient : SpeakeasyHttpClient
+{
+    public TestHttpClient() : base()
+    {
+    }
+
+    private JsonSerializerOptions serializerOptions = new JsonSerializerOptions()
+    {
+        WriteIndented = true
+    };
+
+    private string delimiter = new string('~', 79);
+
+    public override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request)
+    {
+        StringBuilder stringBuilder = new StringBuilder();
+
+        stringBuilder.AppendLine(delimiter);
+        stringBuilder.AppendLine("request:");
+        stringBuilder.AppendLine(request.ToString());
+        if ((request.Content != null) && (request.Content!.Headers.ContentLength > 0))
+        {
+            stringBuilder.AppendLine("content:");
+            string content = await request.Content.ReadAsStringAsync();
+            if (request.Content!.Headers.ContentType?.MediaType == "application/json")
+            {
+                try
+                {
+                    content = JsonSerializer.Serialize(
+                        JsonDocument.Parse(content), serializerOptions);
+                }
+                catch (JsonException e)
+                {
+                    stringBuilder.AppendLine($"-- ERROR: {e.Message}");
+                }
+            }
+            stringBuilder.AppendLine(content);
+        }
+
+        HttpResponseMessage response = await base.SendAsync(request);
+
+        stringBuilder.AppendLine("response:");
+        stringBuilder.AppendLine(response.ToString());
+        if ((response.Content != null) && (response.Content!.Headers.ContentLength > 0))
+        {
+            stringBuilder.AppendLine("content:");
+            string content = await response.Content.ReadAsStringAsync();
+            if (response.Content!.Headers.ContentType?.MediaType == "application/json")
+            {
+                try
+                {
+                    content = JsonSerializer.Serialize(
+                        JsonDocument.Parse(content), serializerOptions);
+                }
+                catch (JsonException e)
+                {
+                    stringBuilder.AppendLine($"-- ERROR: {e.Message}");
+                }
+            }
+            stringBuilder.AppendLine(content);
+        }
+
+        stringBuilder.AppendLine(delimiter);
+        Console.Write(stringBuilder.ToString());
+
+        return response;
+    }
+}

ShippoTests/ShippoTests.csproj

@@ -32,6 +32,9 @@
     <Using Include="Shippo.Hooks" />
     <Using Include="Shippo.Models.Components" />
     <Using Include="Shippo.Models.Requests" />
+    <Using Include="Shippo.Utils" />
+    <Using Include="System.Text" />
+    <Using Include="System.Text.Json" />
     <Using Include="Xunit" />
   </ItemGroup>