@workos/oagen-emitters 0.3.0 → 0.4.0

package/docs/sdk-architecture/dotnet.md

@@ -0,0 +1,336 @@
+# C# / .NET SDK Architecture
+
+Target: .NET 8.0 | Serialization: Newtonsoft.Json | Test: xUnit + Moq
+
+## Architecture Overview
+
+The SDK follows a service-per-domain pattern. A static `WorkOS` entry point holds a singleton `WorkOSClient`. Each service (e.g., `OrganizationsService`) inherits from a shared `Service` base class that lazily resolves the client. All IO is async with `CancellationToken` support.
+
+**Runtime files (hand-maintained, `@oagen-ignore-file`):**
+
+- `WorkOS.cs` — static entry point
+- `Client/WorkOSClient.cs` — HTTP execution, retry, error translation
+- `Client/_interfaces/WorkOSOptions.cs` — client config
+- `Client/_interfaces/WorkOSRequest.cs` — request DTO
+- `Client/Utilities/RequestUtilities.cs` — JSON/query serialization
+- `Services/Webhooks/WebhookService.cs` — webhook signature verification helper
+- `Services/Webhooks/Entities/Webhook.cs` — webhook event envelope used by the helper
+- `Services/Webhooks/Exceptions/WorkOSWebhookException.cs` — webhook verification exception
+- `Services/_common/Service.cs` — base service class
+- `Services/_common/_interfaces/BaseOptions.cs` — marker base for options
+- `Services/_common/_interfaces/ListOptions.cs` — pagination base options
+- `Services/_common/Entities/WorkOSList.cs` — pagination wrapper
+- `Services/_common/Entities/ListMetadata.cs` — cursor metadata
+- `Services/_common/Enums/PaginationOrder.cs` — asc/desc enum
+
+**Generated files (emitter output):**
+
+- `Services/{Mount}/Entities/*.cs` — model classes
+- `Services/{Mount}/Enums/*.cs` — enum types
+- `Services/{Mount}/{Mount}Service.cs` — service class with methods
+- `Services/{Mount}/_interfaces/*Options.cs` — request option classes
+- `test/WorkOSTests/Tests/*Test.cs` — generated service tests
+- `test/WorkOSTests/testdata/*.json` — generated fixtures
+- `test/WorkOSTests/xunit.runner.json` — generated xUnit runner config
+
+## Naming Conventions
+
+| IR Concept     | C# Convention                | Example                     |
+| -------------- | ---------------------------- | --------------------------- |
+| Model name     | PascalCase                   | `Organization`              |
+| Enum name      | PascalCase                   | `ConnectionState`           |
+| Field/property | PascalCase                   | `EmailVerified`             |
+| Method         | PascalCase (no Async suffix) | `GetOrganization`           |
+| File           | PascalCase.cs                | `Organization.cs`           |
+| Service class  | `{Mount}Service`             | `OrganizationsService`      |
+| Options class  | `{Action}{Entity}Options`    | `CreateOrganizationOptions` |
+| Namespace      | `WorkOS`                     | —                           |
+
+## Type Mapping
+
+| IR TypeRef                     | C# Type                 |
+| ------------------------------ | ----------------------- |
+| `primitive:string`             | `string`                |
+| `primitive:string` (date-time) | `string`                |
+| `primitive:string` (uuid)      | `string`                |
+| `primitive:string` (binary)    | `byte[]`                |
+| `primitive:integer`            | `int`                   |
+| `primitive:integer` (int64)    | `long`                  |
+| `primitive:number`             | `double`                |
+| `primitive:boolean`            | `bool`                  |
+| `primitive:unknown`            | `object`                |
+| `model:Foo`                    | `Foo` (reference type)  |
+| `enum:Foo`                     | `Foo` (value type)      |
+| `array`                        | `List<T>`               |
+| `map`                          | `Dictionary<string, T>` |
+| `nullable` (value type)        | `T?`                    |
+| `nullable` (reference type)    | `T`                     |
+| `union` (single)               | that type               |
+| `union` (multiple)             | `object`                |
+
+## Model Pattern
+
+```csharp
+namespace WorkOS
+{
+    using Newtonsoft.Json;
+
+    /// <summary>Represents an organization.</summary>
+    public class Organization
+    {
+        [JsonProperty("id")]
+        public string Id { get; set; }
+
+        [JsonProperty("name")]
+        public string Name { get; set; }
+
+        [JsonProperty("allow_profiles_outside_organization")]
+        public bool AllowProfilesOutsideOrganization { get; set; }
+
+        [JsonProperty("created_at")]
+        public string CreatedAt { get; set; }
+    }
+}
+```
+
+## Enum Pattern
+
+```csharp
+namespace WorkOS
+{
+    using System.Runtime.Serialization;
+    using Newtonsoft.Json;
+    using Newtonsoft.Json.Converters;
+
+    [JsonConverter(typeof(StringEnumConverter))]
+    public enum OrganizationDomainState
+    {
+        [EnumMember(Value = "failed")]
+        Failed,
+
+        [EnumMember(Value = "pending")]
+        Pending,
+
+        [EnumMember(Value = "verified")]
+        Verified,
+    }
+}
+```
+
+## Resource/Service Pattern
+
+```csharp
+namespace WorkOS
+{
+    using System.Net.Http;
+    using System.Threading;
+    using System.Threading.Tasks;
+
+    public class OrganizationsService : Service
+    {
+        public OrganizationsService() { }
+        public OrganizationsService(WorkOSClient client) : base(client) { }
+
+        public async Task<Organization> GetOrganization(
+            string id,
+            CancellationToken cancellationToken = default)
+        {
+            var request = new WorkOSRequest
+            {
+                Method = HttpMethod.Get,
+                Path = $"/organizations/{id}",
+            };
+            return await this.Client.MakeAPIRequest<Organization>(request, cancellationToken);
+        }
+
+        public async Task<WorkOSList<Organization>> ListOrganizations(
+            ListOrganizationsOptions options = null,
+            CancellationToken cancellationToken = default)
+        {
+            var request = new WorkOSRequest
+            {
+                Method = HttpMethod.Get,
+                Path = "/organizations",
+                Options = options,
+            };
+            return await this.Client.MakeAPIRequest<WorkOSList<Organization>>(request, cancellationToken);
+        }
+
+        public async Task<Organization> CreateOrganization(
+            CreateOrganizationOptions options,
+            CancellationToken cancellationToken = default)
+        {
+            var request = new WorkOSRequest
+            {
+                Method = HttpMethod.Post,
+                Path = "/organizations",
+                Options = options,
+            };
+            return await this.Client.MakeAPIRequest<Organization>(request, cancellationToken);
+        }
+
+        public async Task DeleteOrganization(
+            string id,
+            CancellationToken cancellationToken = default)
+        {
+            var request = new WorkOSRequest
+            {
+                Method = HttpMethod.Delete,
+                Path = $"/organizations/{id}",
+            };
+            await this.Client.MakeRawAPIRequest(request, cancellationToken);
+        }
+    }
+}
+```
+
+## Options Pattern
+
+```csharp
+namespace WorkOS
+{
+    using Newtonsoft.Json;
+
+    public class CreateOrganizationOptions : BaseOptions
+    {
+        [JsonProperty("name")]
+        public string Name { get; set; }
+
+        [JsonProperty("domain_data")]
+        public List<OrganizationDomainDataOptions> DomainData { get; set; }
+    }
+
+    public class ListOrganizationsOptions : ListOptions
+    {
+        [JsonProperty("domains")]
+        public string[] Domains { get; set; }
+    }
+}
+```
+
+## Pagination Pattern
+
+```csharp
+// Returned by list methods — NOT an iterator
+public class WorkOSList<T>
+{
+    [JsonProperty("data")]
+    public List<T> Data { get; set; }
+
+    [JsonProperty("list_metadata")]
+    public ListMetadata ListMetadata { get; set; }
+}
+```
+
+## Error Handling
+
+The runtime translates HTTP status codes to SDK-native exceptions:
+
+- `AuthenticationError` (401)
+- `NotFoundError` (404)
+- `UnprocessableEntityError` (422)
+- `RateLimitExceededError` (429)
+- `ServerError` (500+)
+
+These are hand-maintained in the runtime. The emitter generates error-handling _tests_, not the error classes themselves.
+
+## Hidden Parameter Injection
+
+For operations with defaults/inferFromClient, the service method sets properties on the options before making the request:
+
+```csharp
+public async Task<AuthenticationResponse> AuthenticateWithPassword(
+    AuthenticateWithPasswordOptions options,
+    CancellationToken cancellationToken = default)
+{
+    options.GrantType = "password";
+    options.ClientId = this.Client.ClientId;
+    options.ClientSecret = this.Client.ApiKey;
+    var request = new WorkOSRequest
+    {
+        Method = HttpMethod.Post,
+        Path = "/user_management/authenticate",
+        Options = options,
+    };
+    return await this.Client.MakeAPIRequest<AuthenticationResponse>(request, cancellationToken);
+}
+```
+
+## Testing Pattern
+
+xUnit + Moq with HttpMock utility:
+
+```csharp
+public class OrganizationsServiceTest
+{
+    private readonly HttpMock httpMock;
+    private readonly OrganizationsService service;
+
+    public OrganizationsServiceTest()
+    {
+        this.httpMock = new HttpMock();
+        var client = new WorkOSClient(new WorkOSOptions
+        {
+            ApiKey = "sk_test",
+            HttpClient = this.httpMock.HttpClient,
+        });
+        this.service = new OrganizationsService(client);
+    }
+
+    [Fact]
+    public async Task TestGetOrganization()
+    {
+        var fixture = File.ReadAllText("testdata/organization.json");
+        this.httpMock.MockResponse(HttpMethod.Get, "/organizations/org_01234", HttpStatusCode.OK, fixture);
+        var result = await this.service.GetOrganization("org_01234");
+        Assert.NotNull(result);
+        Assert.Equal("org_01234", result.Id);
+        this.httpMock.AssertRequestWasMade(HttpMethod.Get, "/organizations/org_01234");
+    }
+}
+```
+
+## Structural Guidelines
+
+| Category           | Choice                      |
+| ------------------ | --------------------------- |
+| Target Framework   | .NET 8.0                    |
+| HTTP Client        | System.Net.Http.HttpClient  |
+| JSON Parsing       | Newtonsoft.Json 13.x        |
+| Testing Framework  | xUnit 2.x                   |
+| HTTP Mocking       | Moq 4.x (HttpClientHandler) |
+| Linting/Formatting | StyleCop.Analyzers          |
+| Package Manager    | NuGet                       |
+| Build Tool         | dotnet CLI / MSBuild        |
+
+## Directory Structure
+
+```
+src/WorkOS.net/
+├── WorkOS.cs                          # @oagen-ignore-file
+├── Client/                            # @oagen-ignore-file (all)
+│   ├── WorkOSClient.cs
+│   ├── _interfaces/
+│   └── Utilities/
+├── Services/
+│   ├── _common/                       # @oagen-ignore-file (all)
+│   ├── Webhooks/                      # Mixed hand-written + generated
+│   │   ├── Entities/Webhook.cs        # @oagen-ignore-file
+│   │   ├── Exceptions/WorkOSWebhookException.cs
+│   │   ├── WebhookService.cs          # @oagen-ignore-file
+│   │   └── WebhooksService.cs         # Generated
+│   └── {ServiceName}/                 # Generated
+│       ├── {ServiceName}Service.cs
+│       ├── _interfaces/
+│       │   └── {Action}{Entity}Options.cs
+│       ├── Entities/
+│       │   └── {Entity}.cs
+│       └── Enums/
+│           └── {EnumName}.cs
+test/WorkOSTests/
+├── Utilities/HttpMock.cs              # @oagen-ignore-file
+├── Client/                            # @oagen-ignore-file
+├── Services/Webhooks/WebhookTests.cs  # @oagen-ignore-file
+├── Tests/{ServiceName}Test.cs         # Generated
+└── xunit.runner.json                  # Generated
+```

package/oagen.config.ts

@@ -4,6 +4,8 @@ import { nodeEmitter } from './src/node/index.js';
 import { pythonEmitter } from './src/python/index.js';
 import { phpEmitter } from './src/php/index.js';
 import { goEmitter } from './src/go/index.js';
+import { dotnetEmitter } from './src/dotnet/index.js';
+import { kotlinEmitter } from './src/kotlin/index.js';
 import { nodeExtractor } from './src/compat/extractors/node.js';
 import { rubyExtractor } from './src/compat/extractors/ruby.js';
 import { pythonExtractor } from './src/compat/extractors/python.js';
@@ -39,8 +41,9 @@ const operationHints: Record<string, OperationHint> = {
     name: 'get_authorization_url',
     defaults: { response_type: 'code' },
     inferFromClient: ['client_id'],
+    urlBuilder: true,
   },
-  'GET /sso/logout': { name: 'get_logout_url' },
+  'GET /sso/logout': { name: 'get_logout_url', urlBuilder: true },
   'GET /sso/profile': { name: 'get_profile' },
   'POST /sso/token': {
     name: 'get_profile_and_token',
@@ -56,8 +59,9 @@ const operationHints: Record<string, OperationHint> = {
     name: 'get_authorization_url',
     defaults: { response_type: 'code' },
     inferFromClient: ['client_id'],
+    urlBuilder: true,
   },
-  'GET /user_management/sessions/logout': { name: 'get_logout_url' },
+  'GET /user_management/sessions/logout': { name: 'get_logout_url', urlBuilder: true },
 
   // ── User Management — org membership actions ────────────────────────────
   'PUT /user_management/organization_memberships/{id}/deactivate': {
@@ -153,11 +157,22 @@ const operationHints: Record<string, OperationHint> = {
     name: 'remove_flag_target',
   },
 
+  // ── Organizations — audit log config (singular fetch, not a list) ───────
+  'GET /organizations/{id}/audit_log_configuration': {
+    name: 'get_audit_log_configuration',
+  },
+
   // ── Organizations — audit logs retention (mounted on AuditLogs) ─────────
-  'GET /organizations/{id}/audit_logs_retention': { mountOn: 'AuditLogs' },
+  'GET /organizations/{id}/audit_logs_retention': {
+    name: 'get_organization_audit_logs_retention',
+    mountOn: 'AuditLogs',
+  },
   'PUT /organizations/{id}/audit_logs_retention': { mountOn: 'AuditLogs' },
 
   // ── Union split: POST /user_management/authenticate (8 variants) ────────
+  // Common optional fields appended to every variant's exposedParams so the
+  // generated wrappers cover the full spec body shape (fraud/audit context the
+  // server consumes when present).
   'POST /user_management/authenticate': {
     split: [
       {
@@ -165,56 +180,71 @@ const operationHints: Record<string, OperationHint> = {
         targetVariant: 'PasswordSessionAuthenticateRequest',
         defaults: { grant_type: 'password' },
         inferFromClient: ['client_id', 'client_secret'],
-        exposedParams: ['email', 'password', 'invitation_token'],
+        exposedParams: ['email', 'password', 'invitation_token', 'ip_address', 'device_id', 'user_agent'],
+        optionalParams: ['invitation_token', 'ip_address', 'device_id', 'user_agent'],
       },
       {
         name: 'authenticate_with_code',
         targetVariant: 'CodeSessionAuthenticateRequest',
         defaults: { grant_type: 'authorization_code' },
         inferFromClient: ['client_id', 'client_secret'],
-        exposedParams: ['code'],
+        exposedParams: ['code', 'ip_address', 'device_id', 'user_agent'],
+        optionalParams: ['ip_address', 'device_id', 'user_agent'],
       },
       {
         name: 'authenticate_with_refresh_token',
         targetVariant: 'RefreshTokenSessionAuthenticateRequest',
         defaults: { grant_type: 'refresh_token' },
         inferFromClient: ['client_id', 'client_secret'],
-        exposedParams: ['refresh_token', 'organization_id'],
+        exposedParams: ['refresh_token', 'organization_id', 'ip_address', 'device_id', 'user_agent'],
+        optionalParams: ['organization_id', 'ip_address', 'device_id', 'user_agent'],
       },
       {
         name: 'authenticate_with_magic_auth',
         targetVariant: 'MagicAuthSessionAuthenticateRequest',
         defaults: { grant_type: 'urn:workos:oauth:grant-type:magic-auth:code' },
         inferFromClient: ['client_id', 'client_secret'],
-        exposedParams: ['code', 'email', 'invitation_token'],
+        exposedParams: ['code', 'email', 'invitation_token', 'ip_address', 'device_id', 'user_agent'],
+        optionalParams: ['invitation_token', 'ip_address', 'device_id', 'user_agent'],
       },
       {
         name: 'authenticate_with_email_verification',
         targetVariant: 'EmailVerificationSessionAuthenticateRequest',
         defaults: { grant_type: 'urn:workos:oauth:grant-type:email-verification:code' },
         inferFromClient: ['client_id', 'client_secret'],
-        exposedParams: ['code', 'pending_authentication_token'],
+        exposedParams: ['code', 'pending_authentication_token', 'ip_address', 'device_id', 'user_agent'],
+        optionalParams: ['pending_authentication_token', 'ip_address', 'device_id', 'user_agent'],
       },
       {
         name: 'authenticate_with_totp',
         targetVariant: 'TotpSessionAuthenticateRequest',
         defaults: { grant_type: 'urn:workos:oauth:grant-type:mfa-totp' },
         inferFromClient: ['client_id', 'client_secret'],
-        exposedParams: ['code', 'pending_authentication_token', 'authentication_challenge_id'],
+        exposedParams: [
+          'code',
+          'pending_authentication_token',
+          'authentication_challenge_id',
+          'ip_address',
+          'device_id',
+          'user_agent',
+        ],
+        optionalParams: ['ip_address', 'device_id', 'user_agent'],
       },
       {
         name: 'authenticate_with_organization_selection',
         targetVariant: 'OrganizationSelectionSessionAuthenticateRequest',
         defaults: { grant_type: 'urn:workos:oauth:grant-type:organization-selection' },
         inferFromClient: ['client_id', 'client_secret'],
-        exposedParams: ['pending_authentication_token', 'organization_id'],
+        exposedParams: ['pending_authentication_token', 'organization_id', 'ip_address', 'device_id', 'user_agent'],
+        optionalParams: ['ip_address', 'device_id', 'user_agent'],
       },
       {
         name: 'authenticate_with_device_code',
         targetVariant: 'DeviceCodeSessionAuthenticateRequest',
         defaults: { grant_type: 'urn:ietf:params:oauth:grant-type:device_code' },
         inferFromClient: ['client_id'],
-        exposedParams: ['device_code'],
+        exposedParams: ['device_code', 'ip_address', 'device_id', 'user_agent'],
+        optionalParams: ['ip_address', 'device_id', 'user_agent'],
       },
     ],
   },
@@ -299,7 +329,7 @@ const mountRules: Record<string, string> = {
 };
 
 const config: OagenConfig = {
-  emitters: [nodeEmitter, pythonEmitter, phpEmitter, goEmitter],
+  emitters: [nodeEmitter, pythonEmitter, phpEmitter, goEmitter, dotnetEmitter, kotlinEmitter],
   extractors: [
     nodeExtractor,
     rubyExtractor,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos/oagen-emitters",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "WorkOS' oagen emitters",
   "license": "MIT",
   "author": "WorkOS",
@@ -78,6 +78,6 @@
     "node": ">=24.10.0"
   },
   "dependencies": {
-    "@workos/oagen": "^0.5.0"
+    "@workos/oagen": "^0.6.0"
   }
 }

package/smoke/sdk-dotnet.ts

@@ -405,14 +405,33 @@ function buildBatchedCSharpScript(port: number, ns: string, calls: PlannedCall[]
 // ---------------------------------------------------------------------------
 
 /**
- * Find the .csproj file in the SDK directory. Returns the full resolved path.
+ * Find the .csproj file in the SDK directory. Searches the root first, then
+ * common subdirectory patterns (src/{Name}/) used by the generated SDK layout.
  */
 function findCsproj(sdkPath: string): string {
-  const files = readdirSync(sdkPath).filter((f) => f.endsWith('.csproj'));
-  if (files.length === 0) {
-    throw new Error(`No .csproj file found in ${sdkPath}`);
+  // Check root directory first
+  const rootFiles = readdirSync(sdkPath).filter((f) => f.endsWith('.csproj'));
+  if (rootFiles.length > 0) {
+    return resolve(sdkPath, rootFiles[0]);
   }
-  return resolve(sdkPath, files[0]);
+
+  // Check src/ subdirectories (generated SDK layout: src/WorkOS.net/WorkOS.net.csproj)
+  const srcDir = resolve(sdkPath, 'src');
+  if (existsSync(srcDir)) {
+    for (const subdir of readdirSync(srcDir)) {
+      const subdirPath = resolve(srcDir, subdir);
+      try {
+        const subFiles = readdirSync(subdirPath).filter((f) => f.endsWith('.csproj'));
+        if (subFiles.length > 0) {
+          return resolve(subdirPath, subFiles[0]);
+        }
+      } catch {
+        // Not a directory, skip
+      }
+    }
+  }
+
+  throw new Error(`No .csproj file found in ${sdkPath} or ${sdkPath}/src/*/`);
 }
 
 /**
@@ -429,6 +448,18 @@ function detectNamespace(sdkPath: string): string {
   return base.replace('.csproj', '');
 }
 
+/**
+ * Detect the assembly name from the .csproj file's AssemblyName property.
+ * Falls back to namespace if not found.
+ */
+function detectAssemblyName(sdkPath: string): string {
+  const csprojPath = findCsproj(sdkPath);
+  const content = readFileSync(csprojPath, 'utf-8');
+  const match = content.match(/<AssemblyName>([^<]+)<\/AssemblyName>/);
+  if (match) return match[1];
+  return detectNamespace(sdkPath);
+}
+
 // ---------------------------------------------------------------------------
 // .NET project generation
 // ---------------------------------------------------------------------------
@@ -590,9 +621,10 @@ async function main(): Promise<void> {
   const spec = await parseSpec(specPath);
   console.log(`Spec: ${spec.name} v${spec.version}`);
 
-  // Detect SDK namespace
+  // Detect SDK namespace and assembly name
   const ns = detectNamespace(sdkPath);
-  console.log(`SDK namespace: ${ns}`);
+  const assemblyName = detectAssemblyName(sdkPath);
+  console.log(`SDK namespace: ${ns}, assembly: ${assemblyName}`);
 
   // Load manifest
   const manifest = loadManifest(sdkPath);
@@ -620,10 +652,12 @@ async function main(): Promise<void> {
 
   // Step 1: Build the SDK project to a DLL
   const sdkCsprojPath = findCsproj(sdkPath);
+  const sdkCsprojDir = sdkCsprojPath.substring(0, sdkCsprojPath.lastIndexOf('/'));
+  const sdkDllDir = resolve(sdkPath, 'bin/Release');
   console.log('Building SDK...');
   try {
-    execSync(`dotnet build "${sdkCsprojPath}" -c Release -o "${resolve(sdkPath, 'bin/Release/net8.0')}"`, {
-      cwd: sdkPath,
+    execSync(`dotnet build "${sdkCsprojPath}" -c Release -o "${sdkDllDir}"`, {
+      cwd: sdkCsprojDir,
       timeout: 120000,
       stdio: ['pipe', 'pipe', 'pipe'],
       env: { ...process.env, DOTNET_NOLOGO: '1' },
@@ -635,9 +669,8 @@ async function main(): Promise<void> {
     process.exit(1);
   }
 
-  // Find the SDK DLL
-  const sdkDllDir = resolve(sdkPath, 'bin/Release/net8.0');
-  const sdkDll = resolve(sdkDllDir, `${ns}.dll`);
+  // Find the SDK DLL (use AssemblyName, not namespace)
+  const sdkDll = resolve(sdkDllDir, `${assemblyName}.dll`);
 
   // Step 2: Bootstrap the driver project referencing the built DLL
   mkdirSync(tmpDir, { recursive: true });

package/src/dotnet/client.ts

@@ -0,0 +1,89 @@
+import type { ApiSpec, EmitterContext, GeneratedFile, Service } from '@workos/oagen';
+import { toPascalCase, toSnakeCase } from '@workos/oagen';
+import { resolveResourceClassName } from './resources.js';
+import { className, serviceTypeName, humanize } from './naming.js';
+import { getMountTarget } from '../shared/resolved-ops.js';
+
+/**
+ * Generate the C# client file with service accessors.
+ * Produces: WorkOSClient.Generated.cs (partial class with service properties).
+ */
+export function generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+  return [generateClientFile(spec, ctx)];
+}
+
+/**
+ * Deduplicate services by mount target.
+ */
+function deduplicateByMount(services: Service[], ctx: EmitterContext): Service[] {
+  const byTarget = new Map<string, Service>();
+  for (const s of services) {
+    const target = getMountTarget(s, ctx);
+    const existing = byTarget.get(target);
+    if (!existing || toPascalCase(s.name) === target) {
+      byTarget.set(target, s);
+    }
+  }
+  return [...byTarget.values()];
+}
+
+/**
+ * Build map of service name -> accessor property name.
+ */
+export function buildServiceAccessPaths(services: Service[], ctx: EmitterContext): Map<string, string> {
+  const topLevel = deduplicateByMount(services, ctx);
+  const paths = new Map<string, string>();
+
+  for (const service of topLevel) {
+    const resolvedName = resolveResourceClassName(service, ctx);
+    const prop = toSnakeCase(resolvedName);
+    paths.set(service.name, prop);
+  }
+
+  // Also map mount targets
+  for (const service of services) {
+    const target = getMountTarget(service, ctx);
+    if (!paths.has(target)) {
+      const existing = paths.get(service.name);
+      if (existing) paths.set(target, existing);
+    }
+  }
+
+  return paths;
+}
+
+function generateClientFile(spec: ApiSpec, ctx: EmitterContext): GeneratedFile {
+  const topLevel = deduplicateByMount(spec.services, ctx);
+  const lines: string[] = [];
+
+  lines.push(`namespace ${ctx.namespacePascal}`);
+  lines.push('{');
+  lines.push('    /// <summary>');
+  lines.push('    /// Generated service accessors for WorkOSClient.');
+  lines.push('    /// </summary>');
+  lines.push('    public partial class WorkOSClient');
+  lines.push('    {');
+
+  // Service properties with lazy initialization
+  for (const service of topLevel) {
+    const resolvedName = resolveResourceClassName(service, ctx);
+    const propName = className(resolvedName);
+    const svcType = serviceTypeName(resolvedName);
+    const backingField = propName.charAt(0).toLowerCase() + propName.slice(1);
+    const human = humanize(resolvedName);
+    lines.push(`        private ${svcType} ${backingField};`);
+    lines.push('');
+    lines.push(`        /// <summary>Gets the <see cref="${svcType}"/> for ${human} API operations.</summary>`);
+    lines.push(`        public virtual ${svcType} ${propName} => this.${backingField} ??= new ${svcType}(this);`);
+    lines.push('');
+  }
+
+  lines.push('    }');
+  lines.push('}');
+
+  return {
+    path: 'Client/WorkOSClient.Generated.cs',
+    content: lines.join('\n'),
+    overwriteExisting: true,
+  };
+}