release: 0.2.0

.config/dotnet-tools.json

@@ -3,11 +3,11 @@
   "isRoot": true,
   "tools": {
     "csharpier": {
-      "version": "1.0.1",
+      "version": "1.1.2",
       "commands": [
         "csharpier"
       ],
       "rollForward": false
     }
   }
-}
+}

.devcontainer/devcontainer.json

@@ -4,5 +4,9 @@
     "name": "C# (.NET)",
     "image": "mcr.microsoft.com/devcontainers/dotnet:1-9.0-noble",
     "postAttachCommand": "cat .vscode/extensions.json | jq -r .recommendations[] | xargs -n 1 code --install-extension",
-    "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}"
+    "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
+    "features": {
+        // For the Prism mock server.
+        "ghcr.io/devcontainers/features/node:1": {}
+    }
 }

.gitignore

@@ -1,2 +1,5 @@
+.prism.log
 bin/
 obj/
+.vs/
+.idea/

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.0"
+  ".": "0.2.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 29
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/arcade-ai%2Farcade-engine-8446c4e394ac1eeeab4eea23ba29649287af8cf410607dc8eea7ad6ec7d39861.yml
-openapi_spec_hash: 6127f3474724e78ea9875ee712cfb551
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/arcade-ai%2Farcade-engine-46ea61822976f3993310e2c139f133f450b489682d8df4c61b65c731edba8639.yml
+openapi_spec_hash: 8cd802f4d9cdfa000d35792175b3b203
 config_hash: 70cdb57c982c578d1961657c07b8b397

CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## 0.2.0 (2025-11-21)
+
+Full Changelog: [v0.1.0...v0.2.0](https://github.com/ArcadeAI/arcade-dotnet/compare/v0.1.0...v0.2.0)
+
+### ⚠ BREAKING CHANGES
+
+* **client:** improve names of some types
+* **client:** flatten service namespaces
+* **client:** interpret null as omitted in some properties
+* **client:** make models immutable
+
+### Features
+
+* **api:** api update ([97bf4ae](https://github.com/ArcadeAI/arcade-dotnet/commit/97bf4ae13656802a9b0524f388164b293d777fbc))
+* **client:** add `HttpResponse.ReadAsStream` method ([04be863](https://github.com/ArcadeAI/arcade-dotnet/commit/04be863a4959115675d0fc28b60d74a4626e40c6))
+* **client:** add cancellation token support ([810487b](https://github.com/ArcadeAI/arcade-dotnet/commit/810487b7c6c284468df0c6153089799d06e1d11e))
+* **client:** add response validation option ([e650190](https://github.com/ArcadeAI/arcade-dotnet/commit/e65019076d4661de8c22e927e833845f85131f03))
+* **client:** add retries support ([ce12fd4](https://github.com/ArcadeAI/arcade-dotnet/commit/ce12fd4e19e9079aedc5dc550ec731e0c5f496fd))
+* **client:** add support for option modification ([5e140ed](https://github.com/ArcadeAI/arcade-dotnet/commit/5e140ed731f05741ae5137269196121e11413823))
+* **client:** additional methods for positional params ([130c438](https://github.com/ArcadeAI/arcade-dotnet/commit/130c438b3ce0878d9f5b7683b1bfec2fc7cc4653))
+* **client:** make models immutable ([8e0a84d](https://github.com/ArcadeAI/arcade-dotnet/commit/8e0a84db0afebd88e1b06d5afed561a7105e6ba1))
+* **client:** send `User-Agent` header ([c0e3c14](https://github.com/ArcadeAI/arcade-dotnet/commit/c0e3c14a08292e723553357b1453a5d54ae6847e))
+* **client:** send `X-Stainless-Arch` header ([e0698da](https://github.com/ArcadeAI/arcade-dotnet/commit/e0698daf4efe355053be9064651f5a766b8e8618))
+* **client:** send `X-Stainless-Lang` and `X-Stainless-OS` headers ([4b74b43](https://github.com/ArcadeAI/arcade-dotnet/commit/4b74b439b0cc802039a3a0a6c60513631465efa3))
+* **client:** send `X-Stainless-Package-Version` headers ([e645cb6](https://github.com/ArcadeAI/arcade-dotnet/commit/e645cb6bd2ebf723984771fa4c63e9099ddca9a2))
+* **client:** send `X-Stainless-Runtime` and `X-Stainless-Runtime-Version` ([5e6b3bd](https://github.com/ArcadeAI/arcade-dotnet/commit/5e6b3bd4c007bde0989adce4701bc06f6446aca9))
+* **client:** send `X-Stainless-Timeout` header ([b59d0db](https://github.com/ArcadeAI/arcade-dotnet/commit/b59d0db698d881af35b2de470b64b8f4de3dee55))
+* **client:** support request timeout ([96b705e](https://github.com/ArcadeAI/arcade-dotnet/commit/96b705eb58dc2e617fd0cfd3b742e44d4ee4a448))
+
+
+### Bug Fixes
+
+* **client:** interpret null as omitted in some properties ([a58c5a8](https://github.com/ArcadeAI/arcade-dotnet/commit/a58c5a8333df53103cde71cbcc19b33a8436d8f2))
+
+
+### Performance Improvements
+
+* **client:** optimize header creation ([77ed083](https://github.com/ArcadeAI/arcade-dotnet/commit/77ed08308e0061269750185035e68c1a5accc50f))
+
+
+### Chores
+
+* **client:** change name of underlying properties for models and params ([c62ebd3](https://github.com/ArcadeAI/arcade-dotnet/commit/c62ebd3112ac2d8d1e006037617b174c8216a545))
+* **client:** deprecate some symbols ([bdcd9d0](https://github.com/ArcadeAI/arcade-dotnet/commit/bdcd9d0a55f91a9a73c653d8c8ac35cef0e81cac))
+* **client:** simplify field validations ([e650190](https://github.com/ArcadeAI/arcade-dotnet/commit/e65019076d4661de8c22e927e833845f85131f03))
+* **docs:** include more properties in examples ([0fd1311](https://github.com/ArcadeAI/arcade-dotnet/commit/0fd1311cd9c8ef95efd393c6d0e72fd70c048bdd))
+* **internal:** add prism log file to gitignore ([f4ac04b](https://github.com/ArcadeAI/arcade-dotnet/commit/f4ac04bc530260f0bd0817d616abf3da4e85b317))
+* **internal:** codegen related update ([0f18e7f](https://github.com/ArcadeAI/arcade-dotnet/commit/0f18e7fdd585319545336a161ff2de93f84f4be0))
+* **internal:** codegen related update ([349eebd](https://github.com/ArcadeAI/arcade-dotnet/commit/349eebdbac15e38c9cc1670e4ae6bcf071ba54c0))
+* **internal:** delete empty test files ([39cfcbe](https://github.com/ArcadeAI/arcade-dotnet/commit/39cfcbe19af6cb08ef818cfb2737aab09a34c9bd))
+* **internal:** extract `ClientOptions` struct ([01495b2](https://github.com/ArcadeAI/arcade-dotnet/commit/01495b2ce312bbdb634946f3bc046bacc77828f0))
+* **internal:** full qualify some references ([46bb02c](https://github.com/ArcadeAI/arcade-dotnet/commit/46bb02caf8591105fcbcfcb00095ebdc506203ee))
+* **internal:** improve devcontainer ([dc3815e](https://github.com/ArcadeAI/arcade-dotnet/commit/dc3815e9f426b54479743861934e6a0a1bb10f49))
+* **internal:** minor improvements to csproj and gitignore ([64e5236](https://github.com/ArcadeAI/arcade-dotnet/commit/64e52369527198000f34ea2ba1b4d70915282b7c))
+* **internal:** reduce import qualification ([7ca8392](https://github.com/ArcadeAI/arcade-dotnet/commit/7ca8392108a2c4ca51456ff06d9352895dc3d023))
+* **internal:** update release please config ([53d3c90](https://github.com/ArcadeAI/arcade-dotnet/commit/53d3c90d587b8958d7821df52ae89abb43b8c013))
+* **internal:** update release please config ([11a9d80](https://github.com/ArcadeAI/arcade-dotnet/commit/11a9d80ae219cfeb5406a6684b1b2f6d9369268a))
+
+
+### Documentation
+
+* **client:** document `WithOptions` ([b3db621](https://github.com/ArcadeAI/arcade-dotnet/commit/b3db6211ade5a2cde44506628c6d90e4a9607fd7))
+* **client:** document max retries ([aecc000](https://github.com/ArcadeAI/arcade-dotnet/commit/aecc000dcb8d5efd6ae9c269f046e8055520f6ae))
+* **client:** document response validation ([4cac330](https://github.com/ArcadeAI/arcade-dotnet/commit/4cac3308245a9006a8b11af36ce9e786b1a8d498))
+* **client:** document timeout option ([5d23f4f](https://github.com/ArcadeAI/arcade-dotnet/commit/5d23f4f618f1ca8ff95d1a5633b519b5ba1ac34b))
+* **client:** improve snippet formatting ([868be10](https://github.com/ArcadeAI/arcade-dotnet/commit/868be107c479e66a67da081f7f701bf71e6cb826))
+* **client:** separate comment content into paragraphs ([84fc132](https://github.com/ArcadeAI/arcade-dotnet/commit/84fc132681e14125d4e611b62c86a7443b9621aa))
+* **internal:** add warning about implementing interface ([beca41f](https://github.com/ArcadeAI/arcade-dotnet/commit/beca41f3e8c8f87f1f1e037ca167e49f078414ce))
+
+
+### Refactors
+
+* **client:** flatten service namespaces ([2de54d7](https://github.com/ArcadeAI/arcade-dotnet/commit/2de54d791d1a78fc159b5d88e34856fea8449166))
+* **client:** improve names of some types ([ae85584](https://github.com/ArcadeAI/arcade-dotnet/commit/ae85584db77f44bec76c9363f1364e4f8f6d656d))
+* **client:** move some defaults out of `ClientOptions` ([3274d75](https://github.com/ArcadeAI/arcade-dotnet/commit/3274d7579686acaeb9ebd6404b3de9c048ed25e8))
+* **client:** pass around `ClientOptions` instead of client ([b2442cf](https://github.com/ArcadeAI/arcade-dotnet/commit/b2442cfa369c54a178f89147bcb1cbf2e7bc124f))
+
 ## 0.1.0 (2025-10-29)
 
 Full Changelog: [v0.0.1...v0.1.0](https://github.com/ArcadeAI/arcade-dotnet/compare/v0.0.1...v0.1.0)

README.md

@@ -32,20 +32,29 @@ See the [`examples`](examples) directory for complete and runnable examples.
 
 ```csharp
 using System;
+using System.Collections.Generic;
+using System.Text.Json;
 using ArcadeDotnet;
 using ArcadeDotnet.Models.Tools;
 
-// Configured using the ARCADE_API_KEY and ARCADE_BASE_URL environment variables
 ArcadeClient client = new();
 
-ToolExecuteParams parameters = new() { ToolName = "Google.ListEmails" };
+ToolExecuteParams parameters = new()
+{
+    ToolName = "Google.ListEmails",
+    Input = new Dictionary<string, JsonElement>()
+    {
+        { "n_emails", JsonSerializer.SerializeToElement(10) }
+    },
+    UserID = "[email protected]",
+};
 
 var executeToolResponse = await client.Tools.Execute(parameters);
 
 Console.WriteLine(executeToolResponse);
 ```
 
-## Client Configuration
+## Client configuration
 
 Configure the client using environment variables:
 
@@ -73,6 +82,30 @@ See this table for the available options:
 | `APIKey`  | `ARCADE_API_KEY`     | true     | -                          |
 | `BaseUrl` | `ARCADE_BASE_URL`    | true     | `"https://api.arcade.dev"` |
 
+### Modifying configuration
+
+To temporarily use a modified client configuration, while reusing the same connection and thread pools, call `WithOptions` on any client or service:
+
+```csharp
+using System;
+
+var chatResponse = await client
+    .WithOptions(options =>
+        options with
+        {
+            BaseUrl = new("https://example.com"),
+            Timeout = TimeSpan.FromSeconds(42),
+        }
+    )
+    .Chat.Completions.Create(parameters);
+
+Console.WriteLine(chatResponse);
+```
+
+Using a [`with` expression](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/operators/with-expression) makes it easy to construct the modified options.
+
+The `WithOptions` method does not affect the original client or service.
+
 ## Requests and responses
 
 To send a request to the Arcade API, build an instance of some `Params` class and pass it to the corresponding client method. When the response is received, it will be deserialized into an instance of a C# class.
@@ -106,6 +139,110 @@ false
 
 - `ArcadeException`: Base class for all exceptions.
 
+## Network options
+
+### Retries
+
+The SDK automatically retries 2 times by default, with a short exponential backoff between requests.
+
+Only the following error types are retried:
+
+- Connection errors (for example, due to a network connectivity problem)
+- 408 Request Timeout
+- 409 Conflict
+- 429 Rate Limit
+- 5xx Internal
+
+The API may also explicitly instruct the SDK to retry or not retry a request.
+
+To set a custom number of retries, configure the client using the `MaxRetries` method:
+
+```csharp
+using ArcadeDotnet;
+
+ArcadeClient client = new() { MaxRetries = 3 };
+```
+
+Or configure a single method call using [`WithOptions`](#modifying-configuration):
+
+```csharp
+using System;
+
+var chatResponse = await client
+    .WithOptions(options =>
+        options with { MaxRetries = 3 }
+    )
+    .Chat.Completions.Create(parameters);
+
+Console.WriteLine(chatResponse);
+```
+
+### Timeouts
+
+Requests time out after 1 minute by default.
+
+To set a custom timeout, configure the client using the `Timeout` option:
+
+```csharp
+using System;
+using ArcadeDotnet;
+
+ArcadeClient client = new() { Timeout = TimeSpan.FromSeconds(42) };
+```
+
+Or configure a single method call using [`WithOptions`](#modifying-configuration):
+
+```csharp
+using System;
+
+var chatResponse = await client
+    .WithOptions(options =>
+        options with { Timeout = TimeSpan.FromSeconds(42) }
+    )
+    .Chat.Completions.Create(parameters);
+
+Console.WriteLine(chatResponse);
+```
+
+## Undocumented API functionality
+
+The SDK is typed for convenient usage of the documented API. However, it also supports working with undocumented or not yet supported parts of the API.
+
+### Response validation
+
+In rare cases, the API may return a response that doesn't match the expected type. For example, the SDK may expect a property to contain a `string`, but the API could return something else.
+
+By default, the SDK will not throw an exception in this case. It will throw `ArcadeInvalidDataException` only if you directly access the property.
+
+If you would prefer to check that the response is completely well-typed upfront, then either call `Validate`:
+
+```csharp
+var executeToolResponse = client.Tools.Execute(parameters);
+executeToolResponse.Validate();
+```
+
+Or configure the client using the `ResponseValidation` option:
+
+```csharp
+using ArcadeDotnet;
+
+ArcadeClient client = new() { ResponseValidation = true };
+```
+
+Or configure a single method call using [`WithOptions`](#modifying-configuration):
+
+```csharp
+using System;
+
+var executeToolResponse = await client
+    .WithOptions(options =>
+        options with { ResponseValidation = true }
+    )
+    .Tools.Execute(parameters);
+
+Console.WriteLine(executeToolResponse);
+```
+
 ## Semantic versioning
 
 This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:

release-please-config.json

@@ -61,11 +61,11 @@
   ],
   "release-type": "simple",
   "extra-files": [
-    "README.md",
     {
       "type": "xml",
-      "path": "src/ArcadeDotnet/ArcadeDotnet.csproj",
-      "xpath": "//Project/PropertyGroup/VersionPrefix"
+      "path": "**/*.csproj",
+      "xpath": "//Project/PropertyGroup/VersionPrefix",
+      "glob": true
     }
   ]
 }

src/ArcadeDotnet.Tests/ArcadeDotnet.Tests.csproj

@@ -1,11 +1,14 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
     <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
     <IsPackable>false</IsPackable>
     <IsTestProject>true</IsTestProject>
     <ImplicitUsings>disable</ImplicitUsings>
     <!-- Disable skipped tests warnings -->
     <NoWarn>$(NoWarn),xUnit1004</NoWarn>
+    <!-- Disable deprecation warnings since we may reference our own deprecated symbols -->
+    <NoWarn>$(NoWarn),0618</NoWarn>
   </PropertyGroup>
   <ItemGroup>
     <PackageReference Include="coverlet.collector" Version="6.0.0" />

src/ArcadeDotnet.Tests/Services/Admin/AuthProviders/AuthProviderServiceTest.cs → src/ArcadeDotnet.Tests/Services/Admin/AuthProviderServiceTest.cs

@@ -1,6 +1,6 @@
 using System.Threading.Tasks;
 
-namespace ArcadeDotnet.Tests.Services.Admin.AuthProviders;
+namespace ArcadeDotnet.Tests.Services.Admin;
 
 public class AuthProviderServiceTest : TestBase
 {
@@ -23,23 +23,21 @@ public async Task List_Works()
     [Fact]
     public async Task Delete_Works()
     {
-        var authProviderResponse = await this.client.Admin.AuthProviders.Delete(
-            new() { ID = "id" }
-        );
+        var authProviderResponse = await this.client.Admin.AuthProviders.Delete("id");
         authProviderResponse.Validate();
     }
 
     [Fact]
     public async Task Get_Works()
     {
-        var authProviderResponse = await this.client.Admin.AuthProviders.Get(new() { ID = "id" });
+        var authProviderResponse = await this.client.Admin.AuthProviders.Get("id");
         authProviderResponse.Validate();
     }
 
     [Fact]
     public async Task Patch_Works()
     {
-        var authProviderResponse = await this.client.Admin.AuthProviders.Patch(new() { ID = "id" });
+        var authProviderResponse = await this.client.Admin.AuthProviders.Patch("id");
         authProviderResponse.Validate();
     }
 }

src/ArcadeDotnet.Tests/Services/Admin/Secrets/SecretServiceTest.cs → src/ArcadeDotnet.Tests/Services/Admin/SecretServiceTest.cs

@@ -1,6 +1,6 @@
 using System.Threading.Tasks;
 
-namespace ArcadeDotnet.Tests.Services.Admin.Secrets;
+namespace ArcadeDotnet.Tests.Services.Admin;
 
 public class SecretServiceTest : TestBase
 {
@@ -14,6 +14,6 @@ public async Task List_Works()
     [Fact]
     public async Task Delete_Works()
     {
-        await this.client.Admin.Secrets.Delete(new() { SecretID = "secret_id" });
+        await this.client.Admin.Secrets.Delete("secret_id");
     }
 }