@workos/oagen-emitters 0.3.0 → 0.5.0

package/src/shared/naming-utils.ts

@@ -1,3 +1,50 @@
+// ---------------------------------------------------------------------------
+// Shared acronym fixes
+// ---------------------------------------------------------------------------
+
+/**
+ * Base set of acronym corrections applied after PascalCase conversion.
+ * These are domain-specific terms that `toPascalCase` produces as e.g.
+ * "Sso" but should be rendered as "SSO" in every SDK language.
+ *
+ * Language emitters can extend this with additional entries (e.g. Go adds
+ * API, URL, HTTP, JSON, etc. per Go naming conventions).
+ */
+export const BASE_ACRONYM_FIXES: readonly [RegExp, string][] = [
+  [/Workos/g, 'WorkOS'],
+  [/Sso/g, 'SSO'],
+  [/Mfa/g, 'MFA'],
+  [/Jwt/g, 'JWT'],
+  [/Cors/g, 'CORS'],
+  [/Saml/g, 'SAML'],
+  [/Scim/g, 'SCIM'],
+  [/Rbac/g, 'RBAC'],
+  [/Oauth/g, 'OAuth'],
+  [/Oidc/g, 'OIDC'],
+];
+
+/**
+ * Apply acronym corrections to a PascalCase string.
+ * Uses the base set by default; pass extra entries for language-specific
+ * conventions (e.g. Go's `[/Api(?=[A-Z]|$)/g, 'API']`).
+ */
+export function applyAcronymFixes(s: string, extra?: readonly [RegExp, string][]): string {
+  let result = s;
+  for (const [pattern, replacement] of BASE_ACRONYM_FIXES) {
+    result = result.replace(pattern, replacement);
+  }
+  if (extra) {
+    for (const [pattern, replacement] of extra) {
+      result = result.replace(pattern, replacement);
+    }
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// URN stripping
+// ---------------------------------------------------------------------------
+
 /** Strip URN OAuth grant-type prefixes from discriminator-derived schema names. */
 export function stripUrnPrefix(name: string): string {
   // Handles both OAuth and Oauth casing from different PascalCase implementations
@@ -78,10 +125,46 @@ function startsWithVerb(desc: string): boolean {
   return VERB_STARTERS.has(firstWord);
 }
 
+/**
+ * Words beginning with a vowel letter but a consonant /j/ or /w/ sound —
+ * take "a", not "an".
+ */
+const CONSONANT_SOUND_INITIAL_VOWEL = new Set([
+  'user',
+  'unit',
+  'unique',
+  'united',
+  'universal',
+  'university',
+  'european',
+  'one',
+  'once',
+  'useful',
+  'used',
+  'usable',
+  'ubiquitous',
+]);
+
+/**
+ * Words beginning with a consonant letter but a vowel sound (silent h) —
+ * take "an", not "a".
+ */
+const VOWEL_SOUND_INITIAL_CONSONANT = new Set(['hour', 'honest', 'honor', 'honorable', 'heir']);
+
 /**
  * Select the correct indefinite article ("a" or "an") for a word.
+ *
+ * Matches English phonetics, not orthography: "a user" (consonant /j/ sound
+ * despite leading 'u'), "an hour" (vowel sound despite leading 'h'). Falls
+ * back to a vowel-letter regex for words not in either exception set.
  */
 export function articleFor(word: string): string {
+  const firstWord = word
+    .split(/\s+/)[0]
+    .toLowerCase()
+    .replace(/[^a-z]/g, '');
+  if (CONSONANT_SOUND_INITIAL_VOWEL.has(firstWord)) return 'a';
+  if (VOWEL_SOUND_INITIAL_CONSONANT.has(firstWord)) return 'an';
   return /^[aeiou]/i.test(word) ? 'an' : 'a';
 }
 

package/src/shared/non-spec-services.ts

@@ -18,6 +18,17 @@ export interface NonSpecService {
    * someone reading this file understands what the service does.
    */
   description: string;
+
+  /**
+   * When true, the generated Client struct includes a cached field for this
+   * service and a public accessor method — identical to spec-driven services.
+   * The hand-written file must export the service type (e.g. PasswordlessService)
+   * but should NOT define its own Client accessor (the generated code handles that).
+   *
+   * Defaults to false — most non-spec modules are standalone helpers, not
+   * Client-mounted services.
+   */
+  hasClientAccessor?: boolean;
 }
 
 /**
@@ -29,10 +40,12 @@ export const NON_SPEC_SERVICES: readonly NonSpecService[] = [
   {
     id: 'passwordless',
     description: 'Passwordless (magic-link) session endpoints, not yet in the OpenAPI spec.',
+    hasClientAccessor: true,
   },
   {
     id: 'vault',
     description: 'Vault KV storage, key operations, and client-side AES-GCM encrypt/decrypt.',
+    hasClientAccessor: true,
   },
   {
     id: 'webhook_verification',

package/src/shared/resolved-ops.ts

@@ -1,11 +1,42 @@
-import type { Operation, EmitterContext, Service, ResolvedOperation } from '@workos/oagen';
+import type { Operation, EmitterContext, Service, ResolvedOperation, Model, TypeRef } from '@workos/oagen';
 import { toPascalCase } from '@workos/oagen';
 
+/**
+ * Fail fast when two distinct paths in the same mount resolve to the same SDK
+ * method name. Emitters can sometimes paper over this with per-language
+ * deduplication, but manifests and cross-language parity become inconsistent.
+ */
+export function assertUniqueResolvedMethods(ctx: EmitterContext): void {
+  const seen = new Map<string, { path: string; httpMethod: string }>();
+
+  for (const resolved of ctx.resolvedOperations ?? []) {
+    const key = `${resolved.mountOn}.${resolved.methodName}`;
+    const current = {
+      path: resolved.operation.path,
+      httpMethod: resolved.operation.httpMethod.toUpperCase(),
+    };
+    const existing = seen.get(key);
+
+    if (existing && existing.path !== current.path) {
+      throw new Error(
+        `Resolved operation name collision for ${key}: ` +
+          `${existing.httpMethod} ${existing.path} conflicts with ${current.httpMethod} ${current.path}`,
+      );
+    }
+
+    if (!existing) {
+      seen.set(key, current);
+    }
+  }
+}
+
 /**
  * Build a lookup map from "METHOD /path" to ResolvedOperation.
  * Used by emitters to find the resolved method name for any IR operation.
  */
 export function buildResolvedLookup(ctx: EmitterContext): Map<string, ResolvedOperation> {
+  assertUniqueResolvedMethods(ctx);
+
   const map = new Map<string, ResolvedOperation>();
   for (const r of ctx.resolvedOperations ?? []) {
     const key = `${r.operation.httpMethod.toUpperCase()} ${r.operation.path}`;
@@ -107,3 +138,46 @@ export function buildHiddenParams(resolvedOp?: ResolvedOperation): Set<string> {
 export function hasHiddenParams(resolvedOp?: ResolvedOperation): boolean {
   return Object.keys(getOpDefaults(resolvedOp)).length > 0 || getOpInferFromClient(resolvedOp).length > 0;
 }
+
+// ---------------------------------------------------------------------------
+// Parameter group helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Collect all parameter names that belong to any mutually-exclusive parameter group.
+ * These params are serialized via group-level dispatch (e.g. applyToQuery, isinstance,
+ * sealed-class when, etc.) instead of individual struct/class fields.
+ */
+export function collectGroupedParamNames(op: Operation): Set<string> {
+  const names = new Set<string>();
+  for (const group of op.parameterGroups ?? []) {
+    for (const variant of group.variants) {
+      for (const param of variant.parameters) {
+        names.add(param.name);
+      }
+    }
+  }
+  return names;
+}
+
+/**
+ * Build a fallback map from request-body wire field name to TypeRef.
+ *
+ * Some parameter-group variants lose array/object fidelity in the IR and fall
+ * back to primitive strings. Cross-referencing the request body model restores
+ * the actual field type when the grouped params belong to the body.
+ */
+export function collectBodyFieldTypes(op: Operation, models: Model[]): Map<string, TypeRef> {
+  const fieldTypes = new Map<string, TypeRef>();
+  const reqBody = op.requestBody;
+  if (reqBody?.kind !== 'model') return fieldTypes;
+
+  const bodyModel = models.find((model) => model.name === reqBody.name);
+  if (!bodyModel) return fieldTypes;
+
+  for (const field of bodyModel.fields) {
+    fieldTypes.set(field.name, field.type);
+  }
+
+  return fieldTypes;
+}

package/src/shared/wrapper-utils.ts

@@ -42,7 +42,18 @@ export function resolveWrapperParams(wrapper: ResolvedWrapper, ctx: EmitterConte
   return wrapper.exposedParams.map((paramName) => {
     const field =
       variantFields.find((f) => f.name === paramName || toSnakeCase(f.name) === toSnakeCase(paramName)) ?? null;
-    const isOptional = optionalSet.has(paramName) || !field?.required;
+    // Default to required: a wrapper exists to make a specific call shape work,
+    // and exposedParams is the contract for that shape. Mark optional only when
+    // (a) the wrapper hint explicitly says so, or (b) the IR variant model
+    // resolves and reports the field as not required.
+    let isOptional: boolean;
+    if (optionalSet.has(paramName)) {
+      isOptional = true;
+    } else if (field) {
+      isOptional = !field.required;
+    } else {
+      isOptional = false;
+    }
     return { paramName, field, isOptional };
   });
 }

package/test/dotnet/client.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect } from 'vitest';
+import { generateClient } from '../../src/dotnet/client.js';
+import type { EmitterContext, ApiSpec, Service, Model } from '@workos/oagen';
+import { defaultSdkBehavior } from '@workos/oagen';
+
+const models: Model[] = [
+  {
+    name: 'Organization',
+    fields: [
+      { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+      { name: 'name', type: { kind: 'primitive', type: 'string' }, required: true },
+    ],
+  },
+];
+
+const services: Service[] = [
+  {
+    name: 'Organizations',
+    operations: [
+      {
+        name: 'listOrganizations',
+        httpMethod: 'get',
+        path: '/organizations',
+        pathParams: [],
+        queryParams: [],
+        headerParams: [],
+        response: { kind: 'model', name: 'Organization' },
+        errors: [],
+        injectIdempotencyKey: false,
+      },
+    ],
+  },
+];
+
+const spec: ApiSpec = {
+  name: 'TestAPI',
+  version: '1.0.0',
+  baseUrl: 'https://api.workos.com',
+  services,
+  models,
+  enums: [],
+  sdk: defaultSdkBehavior(),
+};
+
+const ctx: EmitterContext = {
+  namespace: 'workos',
+  namespacePascal: 'WorkOS',
+  spec,
+};
+
+describe('dotnet/client', () => {
+  it('generates only WorkOSClient.Generated.cs', () => {
+    const files = generateClient(spec, ctx);
+    expect(files).toHaveLength(1);
+    expect(files[0].path).toBe('Client/WorkOSClient.Generated.cs');
+  });
+
+  it('generates partial class with service accessors', () => {
+    const files = generateClient(spec, ctx);
+    const content = files[0].content;
+
+    expect(content).toContain('namespace WorkOS');
+    expect(content).toContain('public partial class WorkOSClient');
+    // Lazy-initialized service property
+    expect(content).toContain('OrganizationsService');
+    expect(content).toContain('??= new OrganizationsService(this)');
+  });
+
+  it('does not contain static HTTP infrastructure', () => {
+    const files = generateClient(spec, ctx);
+    const content = files[0].content;
+
+    // These belong in the hand-maintained WorkOSClient.cs
+    expect(content).not.toContain('HttpClient');
+    expect(content).not.toContain('ApiKey');
+    expect(content).not.toContain('SendAsync');
+    expect(content).not.toContain('RequestAsync');
+    expect(content).not.toContain('ApiBaseURL');
+    expect(content).not.toContain('AuthenticationException');
+    expect(content).not.toContain('RateLimitExceededException');
+  });
+
+  it('deduplicates services by mount target', () => {
+    const multiSpec: ApiSpec = {
+      ...spec,
+      services: [
+        ...services,
+        {
+          name: 'OrganizationsApiKeys',
+          operations: [
+            {
+              name: 'listOrganizationApiKeys',
+              httpMethod: 'get',
+              path: '/organizations/api_keys',
+              pathParams: [],
+              queryParams: [],
+              headerParams: [],
+              response: { kind: 'model', name: 'Organization' },
+              errors: [],
+              injectIdempotencyKey: false,
+            },
+          ],
+        },
+      ],
+    };
+
+    const files = generateClient(multiSpec, { ...ctx, spec: multiSpec });
+    const content = files[0].content;
+
+    // Both services should appear since they have different mount targets
+    expect(content).toContain('OrganizationsService');
+  });
+
+  it('generates XML doc comments on service properties', () => {
+    const files = generateClient(spec, ctx);
+    const content = files[0].content;
+
+    expect(content).toContain('/// <summary>');
+    expect(content).toContain('OrganizationsService');
+  });
+});

package/test/dotnet/enums.test.ts

@@ -0,0 +1,193 @@
+import { describe, it, expect } from 'vitest';
+import { generateEnums } from '../../src/dotnet/enums.js';
+import type { EmitterContext, ApiSpec, Enum, Service } from '@workos/oagen';
+import { defaultSdkBehavior } from '@workos/oagen';
+
+const emptySpec: ApiSpec = {
+  name: 'Test',
+  version: '1.0.0',
+  baseUrl: '',
+  services: [],
+  models: [],
+  enums: [],
+  sdk: defaultSdkBehavior(),
+};
+
+const ctx: EmitterContext = {
+  namespace: 'workos',
+  namespacePascal: 'WorkOS',
+  spec: emptySpec,
+};
+
+describe('dotnet/enums', () => {
+  it('returns empty for no enums', () => {
+    expect(generateEnums([], ctx)).toEqual([]);
+  });
+
+  it('generates C# enum with EnumMember attributes', () => {
+    const enums: Enum[] = [
+      {
+        name: 'Status',
+        values: [
+          { name: 'ACTIVE', value: 'active' },
+          { name: 'INACTIVE', value: 'inactive' },
+          { name: 'PENDING', value: 'pending' },
+        ],
+      },
+    ];
+
+    const service: Service = {
+      name: 'Organizations',
+      operations: [
+        {
+          name: 'getOrganization',
+          httpMethod: 'get',
+          path: '/organizations/{id}',
+          pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+          queryParams: [{ name: 'status', type: { kind: 'enum', name: 'Status' }, required: false }],
+          headerParams: [],
+          response: { kind: 'model', name: 'Organization' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const files = generateEnums(enums, {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], enums },
+    });
+    expect(files.length).toBe(1);
+
+    const content = files[0].content;
+    expect(content).toContain('namespace WorkOS');
+    expect(content).toContain('public enum Status');
+    expect(content).toContain('[EnumMember(Value = "active")]');
+    expect(content).toContain('Active');
+    expect(content).toContain('[EnumMember(Value = "inactive")]');
+    expect(content).toContain('Inactive');
+    expect(content).toContain('[EnumMember(Value = "pending")]');
+    expect(content).toContain('Pending');
+    // Unknown sentinel for forward compatibility
+    expect(content).toContain('Unknown');
+  });
+
+  it('skips single-value enums (discriminator consts)', () => {
+    const enums: Enum[] = [
+      {
+        name: 'DiscriminatorType',
+        values: [{ name: 'ONLY_VALUE', value: 'only_value' }],
+      },
+    ];
+
+    const files = generateEnums(enums, {
+      ...ctx,
+      spec: { ...emptySpec, enums },
+    });
+    expect(files).toHaveLength(0);
+  });
+
+  it('deduplicates structurally identical enums', () => {
+    const enums: Enum[] = [
+      {
+        name: 'ConnectionType',
+        values: [
+          { name: 'SAML', value: 'saml' },
+          { name: 'OIDC', value: 'oidc' },
+        ],
+      },
+      {
+        name: 'ProfileConnectionType',
+        values: [
+          { name: 'SAML', value: 'saml' },
+          { name: 'OIDC', value: 'oidc' },
+        ],
+      },
+    ];
+
+    const service: Service = {
+      name: 'Test',
+      operations: [
+        {
+          name: 'test',
+          httpMethod: 'get',
+          path: '/test',
+          pathParams: [],
+          queryParams: [
+            { name: 'type', type: { kind: 'enum', name: 'ConnectionType' }, required: false },
+            { name: 'profile_type', type: { kind: 'enum', name: 'ProfileConnectionType' }, required: false },
+          ],
+          headerParams: [],
+          response: { kind: 'primitive', type: 'unknown' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const files = generateEnums(enums, {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], enums },
+    });
+    // Only one enum file should be generated (the canonical)
+    expect(files).toHaveLength(1);
+    expect(files[0].content).toContain('ConnectionType');
+  });
+
+  it('skips orphan enums not referenced by models or operations', () => {
+    const enums: Enum[] = [
+      {
+        name: 'OrphanEnum',
+        values: [
+          { name: 'A', value: 'a' },
+          { name: 'B', value: 'b' },
+        ],
+      },
+    ];
+
+    const files = generateEnums(enums, {
+      ...ctx,
+      spec: { ...emptySpec, enums },
+    });
+    expect(files).toHaveLength(0);
+  });
+
+  it('generates deprecated enum values with Obsolete attribute', () => {
+    const enums: Enum[] = [
+      {
+        name: 'Status',
+        values: [
+          { name: 'ACTIVE', value: 'active' },
+          { name: 'OLD_STATUS', value: 'old_status', deprecated: true, description: 'Use ACTIVE instead' },
+        ],
+      },
+    ];
+
+    const service: Service = {
+      name: 'Test',
+      operations: [
+        {
+          name: 'test',
+          httpMethod: 'get',
+          path: '/test',
+          pathParams: [],
+          queryParams: [{ name: 'status', type: { kind: 'enum', name: 'Status' }, required: false }],
+          headerParams: [],
+          response: { kind: 'primitive', type: 'unknown' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const files = generateEnums(enums, {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], enums },
+    });
+    expect(files).toHaveLength(1);
+    const content = files[0].content;
+
+    expect(content).toContain('[System.Obsolete');
+    expect(content).toContain('OldStatus');
+  });
+});

package/test/dotnet/errors.test.ts

@@ -0,0 +1,9 @@
+import { describe, it, expect } from 'vitest';
+import { dotnetEmitter } from '../../src/dotnet/index.js';
+
+describe('dotnet/errors', () => {
+  it('returns empty array (errors are hand-maintained in the target SDK)', () => {
+    const files = dotnetEmitter.generateErrors!({} as any);
+    expect(files).toHaveLength(0);
+  });
+});

package/test/dotnet/manifest.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest';
+import { generateManifest } from '../../src/dotnet/manifest.js';
+import type { ApiSpec, EmitterContext, Service, Model } from '@workos/oagen';
+import { defaultSdkBehavior } from '@workos/oagen';
+
+const models: Model[] = [
+  {
+    name: 'Organization',
+    fields: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+  },
+];
+
+const services: Service[] = [
+  {
+    name: 'Organizations',
+    operations: [
+      {
+        name: 'listOrganizations',
+        httpMethod: 'get',
+        path: '/organizations',
+        pathParams: [],
+        queryParams: [],
+        headerParams: [],
+        response: { kind: 'model', name: 'Organization' },
+        errors: [],
+        injectIdempotencyKey: false,
+      },
+    ],
+  },
+  {
+    name: 'OrganizationsApiKeys',
+    operations: [
+      {
+        name: 'listOrganizationApiKeys',
+        httpMethod: 'get',
+        path: '/organizations/api_keys',
+        pathParams: [],
+        queryParams: [],
+        headerParams: [],
+        response: { kind: 'model', name: 'Organization' },
+        errors: [],
+        injectIdempotencyKey: false,
+      },
+    ],
+  },
+];
+
+const spec: ApiSpec = {
+  name: 'TestAPI',
+  version: '1.0.0',
+  baseUrl: 'https://api.workos.com',
+  services,
+  models,
+  enums: [],
+  sdk: defaultSdkBehavior(),
+};
+
+const ctx: EmitterContext = {
+  namespace: 'workos',
+  namespacePascal: 'WorkOS',
+  spec,
+};
+
+describe('dotnet/manifest', () => {
+  it('generates smoke-manifest.json', () => {
+    const files = generateManifest(spec, ctx);
+    expect(files).toHaveLength(1);
+    expect(files[0].path).toBe('smoke-manifest.json');
+  });
+
+  it('maps HTTP operations to SDK method names and services', () => {
+    const files = generateManifest(spec, ctx);
+    const manifest = JSON.parse(files[0].content) as Record<string, { sdkMethod: string; service: string }>;
+
+    expect(manifest['GET /organizations']).toBeDefined();
+    expect(manifest['GET /organizations'].sdkMethod).toBeDefined();
+    expect(manifest['GET /organizations'].service).toBeDefined();
+
+    expect(manifest['GET /organizations/api_keys']).toBeDefined();
+    expect(manifest['GET /organizations/api_keys'].sdkMethod).toBeDefined();
+  });
+});