@workos/oagen-emitters 0.3.0 → 0.4.0

package/src/shared/model-utils.ts

@@ -1,4 +1,4 @@
-import type { Model, Field, TypeRef } from '@workos/oagen';
+import type { Model, Field, TypeRef, Enum } from '@workos/oagen';
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 // @ts-ignore -- js-yaml has no type declarations in this project
@@ -103,13 +103,80 @@ function lookupRawSchema(name: string): Record<string, any> | null {
   return spec?.components?.schemas?.[name] ?? null;
 }
 
-/** Convert a raw OpenAPI type+format to an IR TypeRef. */
-function rawSchemaToTypeRef(schema: Record<string, any>): TypeRef {
+// ---------------------------------------------------------------------------
+// Synthetic model / enum collection
+// ---------------------------------------------------------------------------
+
+/**
+ * Accumulator for synthetic models and enums generated from inline
+ * definitions encountered during oneOf flattening.
+ */
+interface SyntheticCollector {
+  models: Model[];
+  enums: Array<{ name: string; values: Array<{ value: string; description?: string }> }>;
+  /** Track names already used to avoid duplicates. */
+  usedNames: Set<string>;
+}
+
+function createCollector(): SyntheticCollector {
+  return { models: [], enums: [], usedNames: new Set() };
+}
+
+/**
+ * Singularize a snake_case name for use as an array-item model name.
+ * `redirect_uris` -> `redirect_uri`, `scopes` -> `scope`.
+ */
+function singularizeSnake(name: string): string {
+  if (name.endsWith('ies') && name.length > 3) {
+    return `${name.slice(0, -3)}y`;
+  }
+  if (name.endsWith('s') && !name.endsWith('ss')) {
+    return name.slice(0, -1);
+  }
+  return name;
+}
+
+// ---------------------------------------------------------------------------
+// rawSchemaToTypeRef  -- with synthetic model/enum generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a raw OpenAPI type+format to an IR TypeRef.
+ *
+ * When `parentModelName` and `fieldName` are provided, inline objects and
+ * enums generate synthetic models/enums instead of degrading to `unknown`
+ * or `string`.
+ */
+function rawSchemaToTypeRef(
+  schema: Record<string, any>,
+  parentModelName?: string,
+  fName?: string,
+  collector?: SyntheticCollector,
+): TypeRef {
   if (schema.const !== undefined) {
     return { kind: 'literal', value: schema.const };
   }
+  if (schema.enum && collector && parentModelName && fName) {
+    // Generate a synthetic enum
+    const syntheticName = `${parentModelName}_${fName}`;
+    if (!collector.usedNames.has(syntheticName)) {
+      collector.usedNames.add(syntheticName);
+      collector.enums.push({
+        name: syntheticName,
+        values: (schema.enum as string[]).map((v: string) => ({
+          value: v,
+          description: undefined,
+        })),
+      });
+    }
+    return {
+      kind: 'enum',
+      name: syntheticName,
+      values: schema.enum as string[],
+    } as TypeRef;
+  }
   if (schema.enum) {
-    // Simple string enum -- represent as primitive string
+    // Simple string enum -- represent as primitive string (no collector)
     return { kind: 'primitive', type: 'string' } as TypeRef;
   }
   if (schema.$ref) {
@@ -127,11 +194,39 @@ function rawSchemaToTypeRef(schema: Record<string, any>): TypeRef {
   }
 
   let ref: TypeRef;
-  if (baseType === 'object' && schema.properties) {
-    // Inline object -- treat as unknown
+  if (baseType === 'object' && schema.properties && collector && parentModelName && fName) {
+    // Inline object -- generate a synthetic model
+    const syntheticName = `${parentModelName}_${fName}`;
+    if (!collector.usedNames.has(syntheticName)) {
+      collector.usedNames.add(syntheticName);
+      const fields: Field[] = [];
+      const requiredSet = new Set<string>(schema.required ?? []);
+      for (const [propName, propSchema] of Object.entries(schema.properties) as [string, Record<string, any>][]) {
+        fields.push({
+          name: propName,
+          type: rawSchemaToTypeRef(propSchema, syntheticName, propName, collector),
+          required: requiredSet.has(propName),
+          description: propSchema.description,
+          deprecated: propSchema.deprecated,
+        });
+      }
+      collector.models.push({
+        name: syntheticName,
+        fields,
+        description: schema.description,
+      } as Model);
+    }
+    ref = { kind: 'model', name: syntheticName } as TypeRef;
+  } else if (baseType === 'object' && schema.properties) {
+    // Inline object -- treat as unknown (no collector)
     ref = { kind: 'primitive', type: 'unknown' } as TypeRef;
   } else if (baseType === 'array' && schema.items) {
-    ref = { kind: 'array', items: rawSchemaToTypeRef(schema.items) } as TypeRef;
+    // For array items that are inline objects, use the singular field name
+    const itemFieldName = fName ? singularizeSnake(fName) : undefined;
+    ref = {
+      kind: 'array',
+      items: rawSchemaToTypeRef(schema.items, parentModelName, itemFieldName, collector),
+    } as TypeRef;
   } else if (baseType === 'boolean') {
     ref = { kind: 'primitive', type: 'boolean' } as TypeRef;
   } else if (baseType === 'integer' || baseType === 'number') {
@@ -151,13 +246,17 @@ function rawSchemaToTypeRef(schema: Record<string, any>): TypeRef {
  * All fields are returned as optional (not required) since they come from
  * oneOf variants where only one variant is active at a time.
  */
-function extractFieldsFromRawSchema(schema: Record<string, any>): Field[] {
+function extractFieldsFromRawSchema(
+  schema: Record<string, any>,
+  parentModelName?: string,
+  collector?: SyntheticCollector,
+): Field[] {
   const fields: Field[] = [];
   const props = schema.properties ?? {};
   for (const [name, propSchema] of Object.entries(props) as [string, Record<string, any>][]) {
     fields.push({
       name,
-      type: rawSchemaToTypeRef(propSchema),
+      type: rawSchemaToTypeRef(propSchema, parentModelName, name, collector),
       required: false, // All oneOf variant fields are optional
       description: propSchema.description,
       deprecated: propSchema.deprecated,
@@ -170,14 +269,18 @@ function extractFieldsFromRawSchema(schema: Record<string, any>): Field[] {
  * Recursively collect all fields from a oneOf schema, flattening nested
  * allOf+oneOf compositions. All fields are marked optional.
  */
-function collectOneOfFields(schema: Record<string, any>): Field[] {
+function collectOneOfFields(
+  schema: Record<string, any>,
+  parentModelName?: string,
+  collector?: SyntheticCollector,
+): Field[] {
   const allFields: Field[] = [];
   const seenFieldNames = new Set<string>();
 
   function walkSchema(s: Record<string, any>): void {
     // Direct properties
     if (s.properties) {
-      for (const f of extractFieldsFromRawSchema(s)) {
+      for (const f of extractFieldsFromRawSchema(s, parentModelName, collector)) {
         if (!seenFieldNames.has(f.name)) {
           seenFieldNames.add(f.name);
           allFields.push(f);
@@ -208,6 +311,83 @@ function collectOneOfFields(schema: Record<string, any>): Field[] {
   return allFields;
 }
 
+// ---------------------------------------------------------------------------
+// Array-item type upgrade
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if a TypeRef is `unknown` (the degraded type for inline objects).
+ */
+function isUnknownType(ref: TypeRef): boolean {
+  return ref.kind === 'primitive' && (ref as any).type === 'unknown';
+}
+
+/**
+ * If a field is an `array<unknown>` (or `nullable<array<unknown>>`) and the
+ * raw spec defines inline object/enum items, replace the item type with a
+ * synthetic model/enum. Returns the original field unchanged when no upgrade
+ * is needed.
+ */
+function upgradeArrayItemType(
+  field: Field,
+  rawSchema: Record<string, any>,
+  parentModelName: string,
+  collector: SyntheticCollector,
+): Field {
+  // Unwrap nullable to find the array
+  let arrayRef: TypeRef | null = null;
+  let isNullableWrapper = false;
+  if (field.type.kind === 'array') {
+    arrayRef = field.type;
+  } else if (field.type.kind === 'nullable' && field.type.inner.kind === 'array') {
+    arrayRef = field.type.inner;
+    isNullableWrapper = true;
+  }
+  if (!arrayRef || arrayRef.kind !== 'array') return field;
+  if (!isUnknownType(arrayRef.items)) return field;
+
+  // Look up the raw spec for this field
+  const rawProp = rawSchema.properties?.[field.name];
+  if (!rawProp) return field;
+
+  // Handle the case where the raw property is inside a nullable type array
+  let rawArraySchema = rawProp;
+  if (Array.isArray(rawProp.type)) {
+    const nonNull = rawProp.type.filter((t: string) => t !== 'null');
+    if (nonNull[0] === 'array') {
+      rawArraySchema = rawProp;
+    }
+  }
+  if (rawArraySchema.type !== 'array' && !(Array.isArray(rawArraySchema.type) && rawArraySchema.type.includes('array')))
+    return field;
+  if (!rawArraySchema.items) return field;
+
+  // Generate a proper TypeRef from the raw items schema
+  const itemFieldName = singularizeSnake(field.name);
+  const newItemRef = rawSchemaToTypeRef(rawArraySchema.items, parentModelName, itemFieldName, collector);
+  if (isUnknownType(newItemRef)) return field;
+
+  const newArrayRef: TypeRef = { kind: 'array', items: newItemRef } as TypeRef;
+  const newType: TypeRef = isNullableWrapper ? ({ kind: 'nullable', inner: newArrayRef } as TypeRef) : newArrayRef;
+
+  return { ...field, type: newType };
+}
+
+// ---------------------------------------------------------------------------
+// Module-level store for synthetic enums produced during enrichment.
+// Consumed by `getSyntheticEnums()` after `enrichModelsFromSpec` runs.
+// ---------------------------------------------------------------------------
+let _lastSyntheticEnums: Enum[] = [];
+
+/**
+ * Return the synthetic enums generated during the last call to
+ * `enrichModelsFromSpec`. Call this after enrichment to merge them into the
+ * enum generation phase.
+ */
+export function getSyntheticEnums(): Enum[] {
+  return _lastSyntheticEnums;
+}
+
 /**
  * Enrich IR models by flattening oneOf/allOf+oneOf variant fields from the raw spec.
  *
@@ -217,13 +397,24 @@ function collectOneOfFields(schema: Record<string, any>): Field[] {
  * For models whose raw spec schema has allOf containing a oneOf:
  *   - Collect the missing variant fields and add them as optional.
  *
+ * Inline objects and enums in oneOf branches are promoted to synthetic
+ * models/enums instead of degrading to `object` / `string`.
+ *
  * Returns a new array of enriched models (original models are not mutated).
+ * Synthetic enums are stored internally; retrieve them via `getSyntheticEnums()`.
  */
 export function enrichModelsFromSpec(models: Model[]): Model[] {
   const spec = loadRawSpec();
-  if (!spec) return models;
+  if (!spec) {
+    _lastSyntheticEnums = [];
+    return models;
+  }
 
-  return models.map((model) => {
+  const collector = createCollector();
+  // Avoid name collisions with existing models
+  for (const m of models) collector.usedNames.add(m.name);
+
+  const enriched = models.map((model) => {
     const rawSchema = lookupRawSchema(model.name);
     if (!rawSchema) return model;
 
@@ -237,8 +428,9 @@ export function enrichModelsFromSpec(models: Model[]): Model[] {
       rawSchema.allOf?.some((s: any) => s.discriminator || s.oneOf?.some((v: any) => v.discriminator));
     if (hasDiscriminator) return model;
 
-    // Collect all variant fields from the raw schema
-    const variantFields = collectOneOfFields(rawSchema);
+    // Collect all variant fields from the raw schema, generating synthetic
+    // models/enums for inline definitions along the way.
+    const variantFields = collectOneOfFields(rawSchema, model.name, collector);
     if (variantFields.length === 0) return model;
 
     // Merge variant fields into the existing model, skipping duplicates
@@ -252,4 +444,29 @@ export function enrichModelsFromSpec(models: Model[]): Model[] {
       fields: [...model.fields, ...newFields],
     };
   });
+
+  // Second pass: fix array fields whose items degraded to `unknown` in the
+  // IR but are actually inline objects or enums in the raw spec.
+  const enriched2 = enriched.map((model) => {
+    const rawSchema = lookupRawSchema(model.name);
+    if (!rawSchema?.properties) return model;
+
+    let modified = false;
+    const newFields = model.fields.map((field) => {
+      const upgraded = upgradeArrayItemType(field, rawSchema, model.name, collector);
+      if (upgraded !== field) modified = true;
+      return upgraded;
+    });
+
+    return modified ? { ...model, fields: newFields } : model;
+  });
+
+  // Convert synthetic enum collector entries to proper Enum objects
+  _lastSyntheticEnums = collector.enums.map((e) => ({
+    name: e.name,
+    values: e.values.map((v) => ({ value: v.value, description: v.description })),
+  })) as Enum[];
+
+  // Append synthetic models to the output
+  return [...enriched2, ...collector.models];
 }

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

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('AuthenticationError');
+    expect(content).not.toContain('RateLimitExceededError');
+  });
+
+  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');
+  });
+});