Skip to content

CLAUDE.md

Latest commit

 

History

History
77 lines (53 loc) · 4.07 KB

CLAUDE.md

File metadata and controls

77 lines (53 loc) · 4.07 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Test Commands

make                # Regenerate Kiota files from OpenAPI specs + build (requires GODESCOPE env var)
make dotnet-build   # Build without regenerating Kiota files (faster, no side effects, recommended if you don't need to generate Kiota files)
make test-quick     # Run unit tests on net8.0 only (recommended during development)
make test           # Run unit tests across all frameworks (net6.0, net8.0, net9.0, net10.0)
make cover          # Run tests with coverage report (net8.0)
make clean          # Clean build artifacts

To build without regenerating Kiota files: cd Descope && dotnet build

To run a single test: cd Descope.Test && dotnet test --framework net8.0 --filter "FullyQualifiedName~TestClassName.TestMethodName"

Architecture

This is the Descope .NET SDK — a Kiota-generated API client for Descope's authentication and management APIs, published as the Descope NuGet package. It targets netstandard2.0, net6.0, net8.0, net9.0, and net10.0.

Projects

  • Descope/ — The SDK library
  • Descope.Test/ — xUnit tests (Moq + FluentAssertions)
  • Descope.Example.WebApp/ — ASP.NET OIDC example app

Generated vs Hand-Written Code

  • Descope/Generated/Mgmt/ and Descope/Generated/Auth/ — Auto-generated by Kiota. Never edit manually. Regenerated by make generate.
  • Descope/Sdk/ — Hand-written SDK code (client wrappers, extensions, middleware, factories).

Client Structure

IDescopeClient / DescopeClient wraps two Kiota-generated clients:

  • client.Mgmt.V1 / client.Mgmt.V2 — Management API (wraps DescopeMgmtKiotaClient)
  • client.Auth.V1 — Auth API (wraps DescopeAuthKiotaClient)
  • client.Auth.ValidateSessionAsync() / RefreshSessionAsync() — JWT token operations

Two creation paths: DescopeManagementClientFactory.Create(options) (instance-based) or services.AddDescopeClient(options) (DI).

Extension Methods Pattern

Extension methods in AuthExtensions.cs and MgmtExtensions.cs wrap Kiota-generated methods with cleaner APIs:

  • PostWithJwtAsync / GetWithJwtAsync — Auth operations requiring a refresh JWT
  • PostWithKeyAsync — Operations requiring an access key
  • GetWithIdAsync / GetWithTenantIdAsync / GetWithIdentifierAsync — Management lookups
  • PostWithSettingsResponseAsync / PostWithJsonOutputAsync — Typed response helpers

When adding extension methods:

  1. Make implicit requirements (JWTs, IDs) explicit in method signatures
  2. Validate parameters and throw DescopeException
  3. Include XML docs with examples
  4. Always add an entry to Obsolete.csv to mark the wrapped generated method as obsolete (format: RelativeFilePath,Method,Replacement)

HTTP Middleware

Custom DelegatingHandler implementations in Descope/Sdk/Internal/Middleware/:

  • CookieToBodyHandler — Extracts JWTs from Set-Cookie headers (DS/DSR) into the response body for "Manage in cookies" mode
  • FixRootResponseBodyHandler — Corrects OpenAPI response body nesting inconsistencies
  • FgaCacheUrlHandler — Routes specific FGA POST operations to an alternate cache URL
  • DescopeErrorResponseHandler — Error response handling

When adding middleware, register it in both DescopeClientFactory.cs and DescopeServiceCollectionExtensions.cs.

Testing

  • Descope.Test/UnitTests/ — Fast tests using MockRequestAdapter and Moq
  • Descope.Test/IntegrationTests/ — Tests against real Descope APIs (require appsettingsTest.json with ProjectId, ManagementKey, BaseURL)
  • Integration tests use RetryUntilSuccessAsync from RateLimitedIntegrationTest for eventual consistency
  • Integration tests are rate-limited — see Descope.Test/IntegrationTests/RATE_LIMITING.md

Commit Conventions

Uses Conventional Commits (feat:, fix:, chore:, etc.) for automatic changelog generation and version bumping via release-please.