feat: zendesk generated client

Author: winromulus

.config/dotnet-tools.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "microsoft.openapi.kiota": {
+      "version": "1.32.5",
+      "commands": [
+        "kiota"
+      ]
+    }
+  }
+}

.github/workflows/pipeline.yaml

@@ -71,13 +71,15 @@ jobs:
               - '*.slnx'
               - '*.props'
               - 'src/**'
+              - '.config/dotnet-tools.json'
             build:
               - '*.sln'
               - '*.slnx'
               - '*.props'
               - 'src/**'
               - 'tests/**'
               - 'playground/**'
+              - '.config/dotnet-tools.json'
 
       - name: evaluate - build
         id: evaluate_build
@@ -131,6 +133,12 @@ jobs:
       - name: dotnet - restore
         run: dotnet restore
 
+      - name: dotnet - tools - restore
+        # The ES.FX.Zendesk build regenerates its git-ignored Kiota clients via the pinned `kiota`
+        # local tool (see eng/zendesk/README.md); restore it before build. pwsh is preinstalled on
+        # ubuntu-latest runners.
+        run: dotnet tool restore
+
       - name: dotnet - build
         run: dotnet build --no-restore --configuration ${{ env.build_configuration }} /p:Version=${{ env.gitVersion_SemVer }} /p:AssemblyVersion=${{env.gitVersion_AssemblySemFileVer}} /p:NuGetVersion=${{env.gitVersion_SemVer}}
 

.gitignore

@@ -62,6 +62,11 @@ project.lock.json
 project.fragment.lock.json
 artifacts/
 
+# Kiota-generated Zendesk API clients — produced at build time (see src/ES.FX.Zendesk/OpenApi/README.md), not committed.
+# The .editorconfig is kept: it silences analyzers for the generated code and is not itself generated.
+/src/ES.FX.Zendesk/Generated/*
+!/src/ES.FX.Zendesk/Generated/.editorconfig
+
 # ASP.NET Scaffolding
 ScaffoldingReadMe.txt
 

CLAUDE.md

@@ -84,7 +84,7 @@ registration, health checks, OpenTelemetry) and follows a fixed shape — study
 A newer Zendesk vertical spans the layers: `ES.FX.Zendesk` (typed Zendesk API client,
 [`docs/libraries/zendesk-client.md`](docs/libraries/zendesk-client.md)), `ES.FX.Ignite.Zendesk` (its Spark,
 [`docs/ignite/sparks/zendesk.md`](docs/ignite/sparks/zendesk.md)), and `ES.FX.Zendesk.MCP.Host` (the
-deployable MCP server app exposing the client as 168 read/write MCP tools,
+deployable MCP server app exposing the client as 172 read/write MCP tools,
 [`docs/libraries/zendesk-mcp-server.md`](docs/libraries/zendesk-mcp-server.md); its MCP wiring is
 host-inline — there is no MCP Spark package).
 

Directory.Packages.props

@@ -48,6 +48,8 @@
 		<PackageVersion Include="Microsoft.Extensions.Identity.Core" Version="10.0.9" />
 		<PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.9" />
 		<PackageVersion Include="Microsoft.Extensions.TimeProvider.Testing" Version="10.7.0" />
+		<PackageVersion Include="Microsoft.Kiota.Abstractions" Version="2.0.0" />
+		<PackageVersion Include="Microsoft.Kiota.Bundle" Version="2.0.0" />
 		<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.7.0" />
 		<PackageVersion Include="Microsoft.VisualStudio.Azure.Containers.Tools.Targets" Version="1.23.0" />
 		<PackageVersion Include="Microting.EntityFrameworkCore.MySql" Version="10.0.9" />

docs/ignite/sparks/index.md

@@ -95,7 +95,7 @@ Every Spark, grouped by function.
 | Spark | Purpose |
 | --- | --- |
 | [Hermes Agent](./hermes-agent.md) | Registers the [ES.FX.NousResearch.HermesAgent](../../libraries/hermes-agent-client.md) typed `IHermesAgentClient` (static bearer key) with a live health check and tracing. |
-| [Zendesk](./zendesk.md) | Registers the [ES.FX.Zendesk](../../libraries/zendesk-client.md) typed `IZendeskClient` (OAuth `client_credentials`) with a live health check and tracing. |
+| [Zendesk](./zendesk.md) | Registers the [ES.FX.Zendesk](../../libraries/zendesk-client.md) Kiota-generated `ZendeskSupportApiClient` and `ZendeskHelpCenterApiClient` (OAuth `client_credentials`) with a live health check and tracing. |
 
 ### API & documentation
 

docs/ignite/sparks/zendesk.md

@@ -1,30 +1,34 @@
 ---
 title: Zendesk client integration
-description: Register the ES.FX.Zendesk typed client with Ignite, including OAuth configuration binding, a live health check, and OpenTelemetry tracing.
+description: Register the Kiota-generated ES.FX.Zendesk Support and Help Center clients with Ignite, including OAuth configuration binding, a live health check, and OpenTelemetry tracing.
 ---
 
 ## Overview
 
-The Zendesk Spark registers the [ES.FX.Zendesk typed client](../../libraries/zendesk-client.md)
-(`IZendeskClient`, OAuth `client_credentials`) into dependency injection, with configuration binding,
-startup validation, a live health check, and OpenTelemetry tracing already wired up. Call
-`builder.IgniteZendeskClient()` once and inject `IZendeskClient` anywhere in your app.
+The Zendesk Spark registers the [ES.FX.Zendesk clients](../../libraries/zendesk-client.md) — the
+Kiota-generated `ZendeskSupportApiClient` and `ZendeskHelpCenterApiClient` (OAuth
+`client_credentials`) — into dependency injection, with configuration binding, startup validation, a
+live health check, and OpenTelemetry tracing already wired up. Call `builder.IgniteZendeskClient()`
+once and inject the clients anywhere in your app.
 
 Under the hood the Spark:
 
 - Binds `ZendeskClientOptions` (subdomain + OAuth credentials) from the `Ignite:Zendesk` configuration
   section with `ValidateOnStart()`, so a bad configuration fails at startup instead of on first use.
 - Binds a `ZendeskClientSparkSettings` (observability toggles) from the `Ignite:Zendesk:Settings`
   sub-section.
-- Registers the client via the library's `AddZendeskClient()` (typed `HttpClient`, keyed-capable, OAuth
-  token provider with cached, single-flight refresh).
-- Adds a **live** health check that calls `GET /api/v2/users/me.json` with the configured credentials.
-- Adds the client's `ES.FX.Zendesk` `ActivitySource` to the Ignite OpenTelemetry pipeline.
+- Registers the clients via the library's `AddZendeskClient()` — the generated Support and Help Center
+  clients, the shared Kiota `IRequestAdapter`, and the `ZendeskAttachmentContentFetcher`, all on a
+  typed `HttpClient` with a keyed-capable OAuth token provider (cached, single-flight refresh).
+- Adds a **live** health check that calls `GET /api/v2/users/me` (via the generated Support client)
+  with the configured credentials.
+- Adds **both** Zendesk tracing sources (`ES.FX.Zendesk` and the Kiota adapter's
+  `Microsoft.Kiota.Http.HttpClientLibrary`) to the Ignite OpenTelemetry pipeline.
 
 > [!NOTE]
-> The client surface, OAuth behavior, error model (`ZendeskApiException`, `RetryAfter`), and the
-> resource-area operations are documented on the [Zendesk API client](../../libraries/zendesk-client.md)
-> page. This page covers the Ignite wiring.
+> The client surface, OAuth behavior, error model (`ZendeskApiException`, Kiota `ApiException`), and
+> the raw-JSON escape hatches are documented on the
+> [Zendesk API client](../../libraries/zendesk-client.md) page. This page covers the Ignite wiring.
 
 ## Install the client
 
@@ -75,19 +79,26 @@ It returns the underlying `IHttpClientBuilder`, for further customization of the
 
 | Service | Lifetime | Notes |
 | --- | --- | --- |
-| `IZendeskClient` | Transient | The typed client. Keyed when `serviceKey` is set. |
+| `ZendeskSupportApiClient` | Transient | The generated Support API client. Keyed when `serviceKey` is set. |
+| `ZendeskHelpCenterApiClient` | Transient | The generated Help Center API client. Keyed when `serviceKey` is set. |
+| `IRequestAdapter` | Transient (keyed) | The Kiota adapter behind both clients — the escape hatch for raw/wire-true requests. |
+| `ZendeskAttachmentContentFetcher` | Transient (keyed) | Authenticated attachment-content downloads. |
 | `IZendeskAccessTokenProvider` | Singleton (keyed) | The OAuth token cache for the instance. |
 | `ZendeskClientSparkSettings` | Singleton (keyed) | The resolved observability settings. |
 | Health check `ZendeskClient` | — | Live credential check. See [Health checks](#health-checks). |
-| OpenTelemetry `ActivitySource` | — | `ES.FX.Zendesk`. See [Tracing](#tracing). |
+| OpenTelemetry `ActivitySource`s | — | `ES.FX.Zendesk` + `Microsoft.Kiota.Http.HttpClientLibrary`. See [Tracing](#tracing). |
 
 ### Consume the client
 
 ```csharp
-public sealed class TicketLookup(IZendeskClient zendesk)
+public sealed class TicketLookup(ZendeskSupportApiClient zendesk)
 {
-    public Task<ZendeskTicket> GetAsync(long id, CancellationToken cancellationToken) =>
-        zendesk.Tickets.GetByIdAsync(id, cancellationToken);
+    public async Task<TicketObject?> GetAsync(long id, CancellationToken cancellationToken)
+    {
+        // GET /api/v2/tickets/{ticket_id}
+        var response = await zendesk.Api.V2.Tickets[id].GetAsync(cancellationToken: cancellationToken);
+        return response?.Ticket;
+    }
 }
 ```
 
@@ -108,9 +119,10 @@ builder.IgniteZendeskClient(name: "sales", serviceKey: "sales");
 
 - **`name`** selects the configuration sub-section: `name: "support"` reads from
   `Ignite:Zendesk:support` instead of `Ignite:Zendesk`. It does not affect DI.
-- **`serviceKey`** registers `IZendeskClient` as a **keyed** service. Resolve it with
-  `[FromKeyedServices("…")]`. When `serviceKey` is `null`, the client is the default (unkeyed)
-  registration.
+- **`serviceKey`** registers the clients (`ZendeskSupportApiClient`, `ZendeskHelpCenterApiClient`,
+  `IRequestAdapter`, `ZendeskAttachmentContentFetcher`) as **keyed** services. Resolve them with
+  `[FromKeyedServices("…")]`. When `serviceKey` is `null`, the clients are the default (unkeyed)
+  registrations.
 
 ```json
 {
@@ -156,7 +168,7 @@ clear message.
 | `HealthChecks.Timeout` | `TimeSpan?` | none | Timeout applied to the health check. |
 | `HealthChecks.FailureStatus` | `HealthStatus?` | `Unhealthy` | Reported status when the check fails. |
 | `HealthChecks.Tags` | `string[]` | `[]` | Extra tags added alongside the built-in `Zendesk` tag. |
-| `Tracing.Enabled` | `bool` | `true` | Adds the `ES.FX.Zendesk` tracing source. |
+| `Tracing.Enabled` | `bool` | `true` | Adds both Zendesk tracing sources (curated + Kiota adapter). |
 
 > [!NOTE]
 > The Zendesk Spark exposes no `Metrics` setting — HTTP-level metrics come from .NET's built-in
@@ -215,9 +227,10 @@ The final `configurationSectionPath` parameter overrides the root section. It de
 
 The Spark registers a health check named **`ZendeskClient`** by default (`HealthChecks.Enabled` is
 `true`). For a keyed registration the name carries the key suffix — e.g. `ZendeskClient[support]`. The
-check is **live**: it calls `GET /api/v2/users/me.json`, which verifies DNS, TLS, the OAuth token flow,
-and the credentials in one probe. A healthy result reports the authenticated user id and role — never
-the email, since health output can surface on an unauthenticated `/health` endpoint.
+check is **live**: it calls `GET /api/v2/users/me` through the generated Support client, which verifies
+DNS, TLS, the OAuth token flow, and the credentials in one probe. A healthy result reports the
+authenticated user id and role — never the email, since health output can surface on an
+unauthenticated `/health` endpoint.
 
 The check is tagged `Zendesk`, plus any tags you add via `HealthChecks.Tags`. It surfaces at the health
 endpoints mapped by `app.Ignite()`.
@@ -251,10 +264,14 @@ builder.IgniteZendeskClient(configureSettings: settings =>
 
 ### Tracing
 
-Tracing is enabled by default (`Tracing.Enabled` is `true`). The Spark adds the client's
-`ES.FX.Zendesk` `ActivitySource` to the Ignite OpenTelemetry pipeline, so every Zendesk operation
-appears as a `Zendesk.{Area}.{Operation}` client span — with the underlying HTTP span from Ignite's
-`HttpClient` instrumentation as its child.
+Tracing is enabled by default (`Tracing.Enabled` is `true`). The Spark subscribes **both** Zendesk
+`ActivitySource`s to the Ignite OpenTelemetry pipeline:
+
+- `ES.FX.Zendesk` (`ZendeskClientInstrumentation.ActivitySourceName`) — the client's own source, for
+  spans from the curated rim.
+- `Microsoft.Kiota.Http.HttpClientLibrary` (`ZendeskClientInstrumentation.KiotaActivitySourceName`) —
+  the Kiota request adapter's fixed source, which emits a span per generated-client request, with the
+  underlying HTTP span from Ignite's `HttpClient` instrumentation as its child.
 
 Disable it via configuration (`Ignite:Zendesk:Settings:Tracing:Enabled = false`) or the
 `configureSettings` delegate.
@@ -263,18 +280,21 @@ Disable it via configuration (`Ignite:Zendesk:Settings:Tracing:Enabled = false`)
 
 Ignite applies the standard resilience handler to **every** `HttpClient` by default
 (`Ignite:Settings:HttpClient:StandardResilienceHandlerEnabled`), including this one — transient failures and
-`429 Too Many Requests` are retried honoring `Retry-After`, with no Spark-specific wiring. When
-retries are exhausted, the thrown `ZendeskApiException` still carries the last `RetryAfter` hint.
+`429 Too Many Requests` are retried honoring `Retry-After`, with no Spark-specific wiring.
+Non-retryable 4xx failures throw the typed `ZendeskApiException`; when retries on `408`/`429`/`5xx`
+are exhausted, the failure surfaces as Kiota's `ApiException` with the response headers (including
+`Retry-After`) preserved — see
+[error handling](../../libraries/zendesk-client.md#error-handling).
 
 ### Logging
 
 The client logs through the app's configured logging pipeline — including
-[Serilog](./serilog.md) when you enable it — with no extra wiring: `Debug` on success, `Warning` with
-the status code on failure. Response bodies are never logged.
+[Serilog](./serilog.md) when you enable it — with no extra wiring (for example token acquisition at
+`Debug`). Response bodies are never logged.
 
 ## See also
 
-- [Zendesk API client](../../libraries/zendesk-client.md) — the client surface, OAuth model, and error handling.
+- [Zendesk API client](../../libraries/zendesk-client.md) — the generated clients, OAuth model, and error handling.
 - [Zendesk MCP server](../../libraries/zendesk-mcp-server.md) — a deployable MCP host built on this Spark.
 - [Ignite overview](../index.md)
 - [Sparks catalog](./index.md)

docs/libraries/index.md

@@ -14,7 +14,7 @@ into Ignite when you want it to.
 | --- | --- | --- |
 | [**Transactional Outbox**](./transactional-outbox.md) | `ES.FX.TransactionalOutbox` (+ `.EntityFrameworkCore`, provider packages, `.MassTransit`) | Reliable message dispatch tied to your EF Core transaction — enqueue a message in the same `SaveChanges` that writes your data, then a hosted service delivers it. |
 | [**Migrations**](./migrations.md) | `ES.FX.Migrations` (+ `ES.FX.Ignite.Migrations`) | A DI-driven migration runner: implement `IMigrationsTask`, register it, and a hosted service applies every task at startup. |
-| [**Zendesk API client**](./zendesk-client.md) | `ES.FX.Zendesk` (+ `ES.FX.Ignite.Zendesk` Spark) | A typed, OAuth-authenticated client for the Zendesk Support REST API — resource-grouped operations, typed errors with `Retry-After`, and OpenTelemetry tracing. |
+| [**Zendesk API client**](./zendesk-client.md) | `ES.FX.Zendesk` (+ `ES.FX.Ignite.Zendesk` Spark) | Kiota-generated clients covering the complete Zendesk Support and Help Center REST APIs — typed request builders, OAuth `client_credentials`, typed errors with `Retry-After`, and OpenTelemetry tracing. |
 | [**Hermes Agent API client**](./hermes-agent-client.md) | `ES.FX.NousResearch.HermesAgent` (+ `ES.FX.Ignite.NousResearch.HermesAgent` Spark) | A typed client for the Nous Research Hermes Agent API server — chat completions, Responses API, asynchronous runs, scheduled jobs, sessions and discovery, with `await foreach` streaming, typed errors, and OpenTelemetry tracing. |
 
 Each library is independently consumable and has its own page below with the full end-to-end walkthrough.
@@ -57,24 +57,27 @@ runner from the Ignite Spark angle.
 
 ## Zendesk API client
 
-The [Zendesk API client](./zendesk-client.md) is a typed client for the Zendesk Support REST API and
-Help Center, built on `IHttpClientFactory`. Register it with `AddZendeskClient()` and inject
-`IZendeskClient` — seventeen resource-grouped areas (`Tickets`, `Users`, `Organizations`, `Groups`,
-`Search`, `Views`, `Articles`, `TicketFields`, `Macros`, `Forms`, `Brands`, `CustomStatuses`,
-`JobStatuses`, `Tags`, `SuspendedTickets`, `Uploads`, `Attachments`) covering reads **and** writes that
-mirror the Zendesk API, with offset **and** cursor pagination, OAuth `client_credentials`
-authentication (cached, single-flight token refresh), a typed `ZendeskApiException` (status, body,
-`Retry-After`), and OpenTelemetry tracing.
+The [Zendesk API client](./zendesk-client.md) ships two
+[Kiota](https://learn.microsoft.com/en-us/openapi/kiota/)-generated clients covering the complete
+Zendesk REST API, built on `IHttpClientFactory`: `ZendeskSupportApiClient` (the full Support API — 614
+operations) and `ZendeskHelpCenterApiClient` (the full Help Center API — 177 operations). Register them
+with `AddZendeskClient()` and navigate the typed request builders, which mirror the API's URL structure
+(`zendesk.Api.V2.Tickets[id].GetAsync(…)`). A curated rim adds what the generator cannot: OAuth
+`client_credentials` authentication (cached, single-flight token refresh), a typed
+`ZendeskApiException` (status, body, `Retry-After`), authenticated attachment-content downloads, and
+OpenTelemetry tracing.
 
 See the [Zendesk API client](./zendesk-client.md) page for the full walkthrough: registration and keyed
-multi-tenant instances, the resource areas, configuration and secret hygiene, the OAuth model, error
-handling and rate limits, and observability. The [Zendesk Spark](../ignite/sparks/zendesk.md) page
-covers the Ignite integration (config binding, startup validation, live health check, tracing).
+multi-tenant instances, request-builder usage, the raw-JSON escape hatch and the re-serialization
+hazard, configuration and secret hygiene, the OAuth model, error handling and rate limits, and
+observability. The [Zendesk Spark](../ignite/sparks/zendesk.md) page covers the Ignite integration
+(config binding, startup validation, live health check, tracing).
 
 For exposing Zendesk to an AI agent, the [Zendesk MCP server](./zendesk-mcp-server.md) is a deployable
-[Model Context Protocol](https://modelcontextprotocol.io) host — built on this client and Ignite — that
-publishes the full client surface as 168 read and write MCP tools, with execution-mode gating and Origin
-validation. It is an application, not a package.
+[Model Context Protocol](https://modelcontextprotocol.io) host — built on the generated clients and
+Ignite — that publishes 172 read and write MCP tools with lean-first responses (summary rows by
+default, full records on request), execution-mode gating, and Origin validation. It is an application,
+not a package.
 
 ---