@workos/oagen-emitters 0.2.1 → 0.3.0

package/src/node/fixtures.ts

@@ -48,6 +48,7 @@ export function generateFixtures(
   const enumMap = new Map(spec.enums.map((e) => [e.name, e]));
   const files: { path: string; content: string }[] = [];
 
+  const seenFixturePaths = new Set<string>();
   for (const model of spec.models) {
     // Skip redundant list-metadata and list-wrapper models (handled by shared types)
     if (isListMetadataModel(model)) continue;
@@ -55,10 +56,17 @@ export function generateFixtures(
 
     const service = modelToService.get(model.name);
     const dirName = resolveDir(service);
+    const fixturePath = `src/${dirName}/fixtures/${fileName(model.name)}.fixture.json`;
+
+    // After noise suffix stripping, multiple models may resolve to the same
+    // fixture path (e.g., OrganizationDto and Organization).  Skip duplicates.
+    if (seenFixturePaths.has(fixturePath)) continue;
+    seenFixturePaths.add(fixturePath);
+
     const fixture = generateModelFixture(model, modelMap, enumMap);
 
     files.push({
-      path: `src/${dirName}/fixtures/${fileName(model.name)}.fixture.json`,
+      path: fixturePath,
       content: JSON.stringify(fixture, null, 2),
     });
   }

package/src/node/index.ts

@@ -11,14 +11,11 @@ import type {
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-import { generateModels } from './models.js';
+import { generateModelsAndSerializers } from './models.js';
 import { generateEnums } from './enums.js';
-import { generateSerializers } from './serializers.js';
 import { generateResources } from './resources.js';
 import { generateClient } from './client.js';
 import { generateErrors } from './errors.js';
-import { generateConfig } from './config.js';
-import { generateCommon } from './common.js';
 import { generateTests } from './tests.js';
 import { generateManifest } from './manifest.js';
 
@@ -36,7 +33,7 @@ export const nodeEmitter: Emitter = {
   language: 'node',
 
   generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines([...generateModels(models, ctx), ...generateSerializers(models, ctx)]);
+    return ensureTrailingNewlines(generateModelsAndSerializers(models, ctx));
   },
 
   generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
@@ -55,10 +52,6 @@ export const nodeEmitter: Emitter = {
     return ensureTrailingNewlines(generateErrors(ctx));
   },
 
-  generateConfig(_ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines([...generateConfig(), ...generateCommon()]);
-  },
-
   generateTypeSignatures(_spec: ApiSpec, _ctx: EmitterContext): GeneratedFile[] {
     // TypeScript uses inline types — no separate type signature files needed
     return [];

package/src/node/models.ts

@@ -14,8 +14,16 @@ import {
   isListMetadataModel,
   isListWrapperModel,
   buildDeduplicationMap,
+  relativeImport,
 } from './utils.js';
 import { assignEnumsToServices } from './enums.js';
+import {
+  renderSerializerTypeParams,
+  buildSerializerImports,
+  buildSkipFormatFields,
+  shouldSkipSerializeForModel,
+  emitSerializerBody,
+} from './field-plan.js';
 
 /**
  * Detect baseline interfaces that are generic (have type parameters) even though
@@ -58,26 +66,21 @@ function enrichGenericDefaultsFromBaseline(
   }
 }
 
-export function generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
+export function generateModels(models: Model[], ctx: EmitterContext, shared?: SharedModelContext): GeneratedFile[] {
   if (models.length === 0) return [];
 
-  const { modelToService, resolveDir } = createServiceDirResolver(models, ctx.spec.services, ctx);
-  // Detect whether the existing SDK uses string dates (ISO 8601) rather than Date objects.
-  // When detected, newly generated models also use string to maintain consistency.
-  const useStringDates = detectStringDateConvention(models, ctx);
-  const genericDefaults = buildGenericModelDefaults(ctx.spec.models);
-  // Enrich genericDefaults from baseline interfaces that appear to be generic.
-  // The IR doesn't carry typeParams for models parsed from OpenAPI (which has no
-  // generics), but the existing SDK may have hand-written generic interfaces
-  // (e.g., Profile<CustomAttributesType>).  Detect these by checking if any
-  // field type contains a PascalCase name that isn't a known model, enum, or builtin.
-  enrichGenericDefaultsFromBaseline(genericDefaults, models, ctx, resolveDir, modelToService);
+  const {
+    modelToService,
+    resolveDir,
+    useStringDates,
+    dedup: sharedDedup,
+    genericDefaults: sharedDefaults,
+  } = shared ?? buildSharedContext(models, ctx);
+  const genericDefaults = sharedDefaults;
   const typeRefOpts = useStringDates ? { stringDates: true, genericDefaults } : { genericDefaults };
   const wireTypeRefOpts = { genericDefaults };
   const files: GeneratedFile[] = [];
-
-  // Detect structurally identical or same-name models — emit type aliases for duplicates
-  const dedup = buildDeduplicationMap(models, ctx);
+  const dedup = sharedDedup;
 
   for (const model of models) {
     // Fix #4: Skip per-domain ListMetadata interfaces — the shared ListMetadata type covers these
@@ -90,14 +93,28 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     // emit a type alias instead of a full interface.
     const canonicalName = dedup.get(model.name);
     if (canonicalName) {
-      const domainName = resolveInterfaceName(model.name, ctx);
-      const responseName = wireInterfaceName(domainName);
-      const canonDomainName = resolveInterfaceName(canonicalName, ctx);
-      const canonResponseName = wireInterfaceName(canonDomainName);
       const service = modelToService.get(model.name);
       const dirName = resolveDir(service);
+
+      // Skip typeAlias resolution for dedup models.  The canonical file may
+      // be preserved (skipIfExists) and still export its raw name, so the
+      // import names must match the raw exports, not resolved aliases.
+      const skipTA = { skipTypeAlias: true };
+      const domainName = resolveInterfaceName(model.name, ctx, skipTA);
+      const responseName = wireInterfaceName(domainName);
+      const canonDomainName = resolveInterfaceName(canonicalName, ctx, skipTA);
+      const canonResponseName = wireInterfaceName(canonDomainName);
+
       const canonService = modelToService.get(canonicalName);
       const canonDir = resolveDir(canonService);
+
+      // After noise suffix stripping (e.g., "OrganizationDto" → "Organization"),
+      // the alias and canonical may resolve to the same file path or the same
+      // type names.  Skip — the canonical file already provides the types.
+      const aliasPath = `src/${dirName}/interfaces/${fileName(model.name)}.interface.ts`;
+      const canonPath = `src/${canonDir}/interfaces/${fileName(canonicalName)}.interface.ts`;
+      if (aliasPath === canonPath) continue;
+      if (domainName === canonDomainName) continue;
       const canonRelPath =
         canonDir === dirName
           ? `./${fileName(canonicalName)}.interface`
@@ -109,7 +126,7 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
         `export type ${responseName} = ${canonResponseName};`,
       ];
       files.push({
-        path: `src/${dirName}/interfaces/${fileName(model.name)}.interface.ts`,
+        path: aliasPath,
         content: aliasLines.join('\n'),
         skipIfExists: true,
       });
@@ -118,7 +135,11 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
 
     const service = modelToService.get(model.name);
     const dirName = resolveDir(service);
-    const domainName = resolveInterfaceName(model.name, ctx);
+    // If this model is a dedup canonical (other models alias to it), skip
+    // typeAlias resolution so the file exports the raw name.  Dedup aliases
+    // import using the raw name to stay consistent with preserved files.
+    const isDedupCanonical = [...dedup.values()].includes(model.name);
+    const domainName = resolveInterfaceName(model.name, ctx, isDedupCanonical ? { skipTypeAlias: true } : undefined);
     const responseName = wireInterfaceName(domainName);
     const deps = collectFieldDependencies(model);
     const lines: string[] = [];
@@ -448,3 +469,139 @@ function renderTypeParams(model: Model, genericDefaults?: Map<string, string>):
   });
   return `<${params.join(', ')}>`;
 }
+
+// ---------------------------------------------------------------------------
+// Shared context — computed once and reused by interface + serializer passes
+// ---------------------------------------------------------------------------
+
+interface SharedModelContext {
+  modelToService: Map<string, string>;
+  resolveDir: (irService: string | undefined) => string;
+  useStringDates: boolean;
+  dedup: Map<string, string>;
+  genericDefaults: Map<string, string>;
+}
+
+function buildSharedContext(models: Model[], ctx: EmitterContext): SharedModelContext {
+  const { modelToService, resolveDir } = createServiceDirResolver(models, ctx.spec.services, ctx);
+  const useStringDates = detectStringDateConvention(models, ctx);
+  const genericDefaults = buildGenericModelDefaults(ctx.spec.models);
+  enrichGenericDefaultsFromBaseline(genericDefaults, models, ctx, resolveDir, modelToService);
+  const dedup = buildDeduplicationMap(models, ctx);
+  return { modelToService, resolveDir, useStringDates, dedup, genericDefaults };
+}
+
+// ---------------------------------------------------------------------------
+// Serializer file generation (moved from serializers.ts)
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate serializer files for all models.
+ * Can accept pre-computed shared context to avoid duplicating work
+ * when called alongside generateModels.
+ */
+export function generateSerializers(
+  models: Model[],
+  ctx: EmitterContext,
+  shared?: SharedModelContext,
+): GeneratedFile[] {
+  if (models.length === 0) return [];
+
+  const { modelToService, resolveDir, useStringDates, dedup } = shared ?? buildSharedContext(models, ctx);
+  const files: GeneratedFile[] = [];
+  const skippedSerializeModels = new Set<string>();
+
+  for (const model of models) {
+    if (isListMetadataModel(model)) continue;
+    if (isListWrapperModel(model)) continue;
+
+    // Deduplication: for structurally identical models, re-export the canonical serializer
+    const canonicalName = dedup.get(model.name);
+    if (canonicalName) {
+      const service = modelToService.get(model.name);
+      const dirName = resolveDir(service);
+      // Skip typeAlias resolution for dedup serializers (same reason as interfaces).
+      const skipTA = { skipTypeAlias: true };
+      const domainName = resolveInterfaceName(model.name, ctx, skipTA);
+      const canonDomainName = resolveInterfaceName(canonicalName, ctx, skipTA);
+
+      const canonService = modelToService.get(canonicalName);
+      const canonDir = resolveDir(canonService);
+      const serializerPath = `src/${dirName}/serializers/${fileName(model.name)}.serializer.ts`;
+      const canonSerializerPath = `src/${canonDir}/serializers/${fileName(canonicalName)}.serializer.ts`;
+
+      // After noise suffix stripping, alias and canonical may resolve to the
+      // same serializer path or the same function names.  Skip — the canonical
+      // serializer already provides the functions.
+      if (serializerPath === canonSerializerPath) continue;
+      if (domainName === canonDomainName) continue;
+      const rel = relativeImport(serializerPath, canonSerializerPath);
+      files.push({
+        path: serializerPath,
+        content: `export { deserialize${canonDomainName} as deserialize${domainName}, serialize${canonDomainName} as serialize${domainName} } from '${rel}';`,
+        overwriteExisting: true,
+      });
+      continue;
+    }
+
+    const service = modelToService.get(model.name);
+    const dirName = resolveDir(service);
+    const isDedupCanonical = [...dedup.values()].includes(model.name);
+    const domainName = resolveInterfaceName(model.name, ctx, isDedupCanonical ? { skipTypeAlias: true } : undefined);
+    const responseName = wireInterfaceName(domainName);
+    const serializerPath = `src/${dirName}/serializers/${fileName(model.name)}.serializer.ts`;
+    const typeParams = renderSerializerTypeParams(model, ctx);
+    const baselineResponse = ctx.apiSurface?.interfaces?.[responseName];
+    const baselineDomain = ctx.apiSurface?.interfaces?.[domainName];
+
+    const skipFormatFields = buildSkipFormatFields(model, useStringDates, baselineDomain);
+    const shouldSkipSerialize = shouldSkipSerializeForModel(
+      model,
+      baselineResponse,
+      baselineDomain,
+      dedup,
+      skippedSerializeModels,
+      ctx,
+    );
+    if (shouldSkipSerialize) {
+      skippedSerializeModels.add(model.name);
+    }
+
+    const sctx = { modelToService, resolveDir, useStringDates, dedup, skippedSerializeModels, ctx };
+    const lines = [
+      ...buildSerializerImports(model, serializerPath, dirName, domainName, responseName, sctx),
+      ...emitSerializerBody(
+        model,
+        domainName,
+        responseName,
+        typeParams,
+        baselineDomain,
+        baselineResponse,
+        skipFormatFields,
+        shouldSkipSerialize,
+        ctx,
+      ),
+    ];
+
+    files.push({
+      path: serializerPath,
+      content: pruneUnusedImports(lines).join('\n'),
+    });
+  }
+
+  return files;
+}
+
+// ---------------------------------------------------------------------------
+// Combined generation — single shared context, two output streams
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate both interface files and serializer files in a single pass
+ * with shared context computation.
+ */
+export function generateModelsAndSerializers(models: Model[], ctx: EmitterContext): GeneratedFile[] {
+  if (models.length === 0) return [];
+  const shared = buildSharedContext(models, ctx);
+  return [...generateModels(models, ctx, shared), ...generateSerializers(models, ctx, shared)];
+}

package/src/node/naming.ts

@@ -1,14 +1,21 @@
 import type { Operation, Service, EmitterContext } from '@workos/oagen';
 import { toPascalCase, toCamelCase, toKebabCase, toSnakeCase } from '@workos/oagen';
+import { buildResolvedLookup, lookupMethodName } from '../shared/resolved-ops.js';
+import { stripUrnPrefix } from '../shared/naming-utils.js';
+
+/** Strip spec-noise suffixes (e.g., "Dto") from an IR name. */
+export function stripNoiseSuffixes(name: string): string {
+  return name.replace(/Dto$/i, '');
+}
 
 /** PascalCase class/interface name. */
 export function className(name: string): string {
-  return toPascalCase(name);
+  return toPascalCase(stripUrnPrefix(name));
 }
 
 /** kebab-case file name (without extension). */
 export function fileName(name: string): string {
-  return toKebabCase(name);
+  return toKebabCase(stripUrnPrefix(name));
 }
 
 /** camelCase method name. */
@@ -67,134 +74,65 @@ export function buildServiceNameMap(services: Service[], ctx: EmitterContext): M
 }
 
 /**
- * Explicit method name overrides for operations where the spec's operationId
- * does not match the desired SDK method name and the spec cannot be changed.
- * Key: "HTTP_METHOD /path", Value: camelCase method name.
- */
-const METHOD_NAME_OVERRIDES: Record<string, string> = {
-  'POST /portal/generate_link': 'generatePortalLink',
-};
-
-/**
- * Explicit service directory overrides. Maps a resolved PascalCase service name
- * to a target directory (kebab-case). Use this when the spec's tag grouping
- * does not match the desired SDK directory layout and the spec cannot be changed.
- */
-const SERVICE_DIR_OVERRIDES: Record<string, string> = {
-  ApplicationClientSecrets: 'workos-connect',
-  Applications: 'workos-connect',
-  Connections: 'sso',
-  Directories: 'directory-sync',
-  DirectoryGroups: 'directory-sync',
-  DirectoryUsers: 'directory-sync',
-  FeatureFlagsTargets: 'feature-flags',
-  MultiFactorAuth: 'mfa',
-  MultiFactorAuthChallenges: 'mfa',
-  OrganizationsApiKeys: 'organizations',
-  WebhooksEndpoints: 'webhooks',
-  UserManagementAuthentication: 'user-management',
-  UserManagementCorsOrigins: 'user-management',
-  UserManagementDataProviders: 'user-management',
-  UserManagementInvitations: 'user-management',
-  UserManagementJWTTemplate: 'user-management',
-  UserManagementMagicAuth: 'user-management',
-  UserManagementMultiFactorAuthentication: 'user-management',
-  UserManagementOrganizationMembership: 'user-management',
-  UserManagementRedirectUris: 'user-management',
-  UserManagementSessionTokens: 'user-management',
-  UserManagementUsers: 'user-management',
-  UserManagementUsersAuthorizedApplications: 'user-management',
-  WorkOSConnect: 'workos-connect',
-};
-
-/**
- * Maps a service (by PascalCase name) to the existing hand-written class that
- * already covers its endpoints. When a service appears here:
- *   - `resolveClassName` returns the target class (so generated code merges in)
- *   - `isServiceCoveredByExisting` returns true
- *   - `hasMethodsAbsentFromBaseline` checks the target class for missing methods,
- *     so new endpoints are added to the existing class rather than silently dropped
- */
-export const SERVICE_COVERED_BY: Record<string, string> = {
-  Connections: 'SSO',
-  Directories: 'DirectorySync',
-  DirectoryGroups: 'DirectorySync',
-  DirectoryUsers: 'DirectorySync',
-  FeatureFlagsTargets: 'FeatureFlags',
-  MultiFactorAuth: 'Mfa',
-  MultiFactorAuthChallenges: 'Mfa',
-  OrganizationsApiKeys: 'Organizations',
-  UserManagementAuthentication: 'UserManagement',
-  UserManagementInvitations: 'UserManagement',
-  UserManagementMagicAuth: 'UserManagement',
-  UserManagementMultiFactorAuthentication: 'UserManagement',
-  UserManagementOrganizationMembership: 'UserManagement',
-  UserManagementUsers: 'UserManagement',
-};
-
-/**
- * Explicit class name overrides. Maps the default PascalCase service name
- * to the desired SDK class name when toPascalCase produces the wrong casing.
- */
-const CLASS_NAME_OVERRIDES: Record<string, string> = {
-  WorkosConnect: 'WorkOSConnect',
-};
-
-/**
- * Resolve the output directory for a service, checking overrides first.
- * Falls back to the standard kebab-case conversion.
+ * Resolve the output directory for a service.
+ * Mount rules already handle directory placement, so this is a simple kebab-case conversion.
  */
 export function resolveServiceDir(resolvedServiceName: string): string {
-  return SERVICE_DIR_OVERRIDES[resolvedServiceName] ?? serviceDirName(resolvedServiceName);
+  return serviceDirName(resolvedServiceName);
 }
 
-/** Resolve the SDK method name for an operation, checking overlay first. */
+/** Resolve the SDK method name for an operation, using resolved operations first. */
 export function resolveMethodName(op: Operation, _service: Service, ctx: EmitterContext): string {
+  const lookup = buildResolvedLookup(ctx);
+  const resolved = lookupMethodName(op, lookup);
+  if (resolved) return toCamelCase(resolved);
+  // Fallback to overlay, then spec-derived
   const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
-  const override = METHOD_NAME_OVERRIDES[httpKey];
-  if (override) return override;
   const existing = ctx.overlayLookup?.methodByOperation?.get(httpKey);
-  if (existing) {
-    // Fix: when the path ends with a path parameter (single-resource operation)
-    // and the overlay method name is plural, prefer the singular form.
-    // E.g., getUsers → getUser when path is /user_management/users/{id}
-    const isSingleResource = /\/\{[^}]+\}$/.test(op.path);
-    if (isSingleResource && existing.methodName.endsWith('s') && !existing.methodName.endsWith('ss')) {
-      const singular = existing.methodName.slice(0, -1);
-      // Only singularize if it looks like a typical pluralization (ends in 's')
-      // and the spec-derived name agrees it should be singular
-      const specDerived = toCamelCase(op.name);
-      if (specDerived === singular || specDerived.endsWith(singular.slice(singular.length - 4))) {
-        return singular;
-      }
-    }
-    return existing.methodName;
-  }
+  if (existing) return existing.methodName;
   return toCamelCase(op.name);
 }
 
-/** Resolve the SDK class name for a service, checking overlay for existing names. */
+/** Resolve the SDK class name for a service, using resolved ops mountOn as canonical. */
 export function resolveClassName(service: Service, ctx: EmitterContext): string {
-  // Explicit coverage: this service's endpoints belong to an existing class
-  const coveredBy = SERVICE_COVERED_BY[toPascalCase(service.name)];
-  if (coveredBy) return coveredBy;
-
-  // Check overlay's methodByOperation for any operation in this service
-  // to find the existing class name
+  // Use resolved ops mountOn as canonical class name
+  for (const r of ctx.resolvedOperations ?? []) {
+    if (r.service.name === service.name) return r.mountOn;
+  }
+  // Fallback to overlay
   if (ctx.overlayLookup?.methodByOperation) {
     for (const op of service.operations) {
       const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
       const existing = ctx.overlayLookup.methodByOperation.get(httpKey);
-      if (existing) return CLASS_NAME_OVERRIDES[existing.className] ?? existing.className;
+      if (existing) return existing.className;
     }
   }
-  const defaultName = toPascalCase(service.name);
-  return CLASS_NAME_OVERRIDES[defaultName] ?? defaultName;
+  return toPascalCase(service.name);
 }
 
-/** Resolve the interface name for a model, checking overlay first. */
-export function resolveInterfaceName(name: string, ctx: EmitterContext): string {
+/** Resolve the interface name for a model, checking overlay first.
+ *
+ * @param opts.skipTypeAlias - When true, skip apiSurface typeAlias resolution.
+ *   Use this for dedup models to ensure the file exports match the import
+ *   names (preserved files export the raw name, not the resolved alias).
+ */
+export function resolveInterfaceName(name: string, ctx: EmitterContext, opts?: { skipTypeAlias?: boolean }): string {
   const existing = ctx.overlayLookup?.interfaceByName?.get(name);
   if (existing) return existing;
-  return toPascalCase(name);
+
+  // If the model name is a type alias that points to a canonical interface,
+  // use the canonical name.  This prevents the merger from generating unused
+  // backward-compat aliases (e.g., `type FlagOwner = FeatureFlagOwner`).
+  if (!opts?.skipTypeAlias && ctx.apiSurface?.typeAliases) {
+    const alias = ctx.apiSurface.typeAliases[name] as { value?: string } | undefined;
+    if (alias?.value && ctx.apiSurface.interfaces?.[alias.value]) {
+      return alias.value;
+    }
+  }
+
+  // Strip spec-noise suffixes (e.g., "Dto") only for models without a
+  // baseline.  When an overlay exists (Scenario A), the overlay check above
+  // handles existing models.  New models (no overlay entry) get clean names.
+  const cleaned = ctx.apiSurface ? name : stripNoiseSuffixes(name);
+  return toPascalCase(stripUrnPrefix(cleaned));
 }