@workos/oagen-emitters 0.18.0 → 0.18.2

package/dist/plugin.mjs

@@ -1,2 +1,2 @@
-import { t as workosEmittersPlugin } from "./plugin-DAa-HsN5.mjs";
+import { t as workosEmittersPlugin } from "./plugin-bqfwowQ3.mjs";
 export { workosEmittersPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos/oagen-emitters",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "description": "WorkOS' oagen emitters",
   "license": "MIT",
   "author": "WorkOS",

package/src/node/client.ts

@@ -179,7 +179,7 @@ function exportedNamesForSource(ctx: EmitterContext, sourceFile: string): string
  */
 function generateServiceBarrels(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
   const files: GeneratedFile[] = [];
-  const { modelToService, resolveDir } = createServiceDirResolver(spec.models, spec.services, ctx);
+  const { modelToService, resolveDir, serviceNameMap } = createServiceDirResolver(spec.models, spec.services, ctx);
   const enumToService = assignEnumsToServices(spec.enums, spec.services, spec.models, ctx);
 
   // Group interface files by directory, tracking exported symbol names
@@ -190,7 +190,7 @@ function generateServiceBarrels(spec: ApiSpec, ctx: EmitterContext): GeneratedFi
   const dirSymbols = new Map<string, Set<string>>();
   const ownedDirNames = new Set<string>();
   for (const service of spec.services) {
-    if (isNodeOwnedService(ctx, service.name)) {
+    if (isNodeOwnedService(ctx, service.name, serviceNameMap.get(service.name))) {
       const dir = resolveDir(service.name);
       ownedDirNames.add(dir);
       // Ensure owned directories always get a barrel entry, even if no

package/src/node/enums.ts

@@ -186,5 +186,28 @@ export function assignEnumsToServices(
     }
   }
 
+  // A shared enum that already has a canonical declaration under `src/common/`
+  // must stay there. `common` is a shared module that owned-service
+  // regeneration never overwrites, so it is always the source of truth for
+  // these names. Without this, owning a service that references such an enum
+  // would emit a SECOND copy into the owned module's `interfaces/` dir (via the
+  // owned-service exception in `generateEnums`) while the `common` copy
+  // remains, and `src/index.ts` re-exports both barrels — a duplicate
+  // `export *` (TS2308). Unassigning the enum makes every consumer
+  // (`generateEnums`, model imports, barrels) resolve it to `common`.
+  if (ctx) {
+    const serviceNameMap = buildServiceNameMap(services, ctx);
+    const toUnassign: string[] = [];
+    for (const [name, service] of enumToService) {
+      if (!isNodeOwnedService(ctx, service, serviceNameMap.get(service))) continue;
+      const home =
+        (ctx.apiSurface?.enums?.[name] as any)?.sourceFile ??
+        (ctx.apiSurface?.typeAliases?.[name] as any)?.sourceFile ??
+        liveSurfaceInterfacePath(name);
+      if (home && home.startsWith('src/common/')) toUnassign.push(name);
+    }
+    for (const name of toUnassign) enumToService.delete(name);
+  }
+
   return enumToService;
 }

package/src/node/models.ts

@@ -11,6 +11,7 @@ import {
   wireInterfaceName,
   resolveMethodName,
   isAdoptedModelName,
+  buildServiceNameMap,
 } from './naming.js';
 import {
   collectFieldDependencies,
@@ -42,7 +43,7 @@ import {
   hasDateTimeConversion,
 } from './field-plan.js';
 import { liveSurfaceHasExistingSdk, liveSurfaceHasManagedFile, liveSurfaceInterfacePath } from './live-surface.js';
-import { isNodeOwnedService } from './options.js';
+import { isNodeOwnedService, isHandOwnedType } from './options.js';
 import { unwrapListModel } from './fixtures.js';
 import { groupByMount, buildResolvedLookup, lookupResolved } from '../shared/resolved-ops.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
@@ -244,6 +245,14 @@ export function generateModels(models: Model[], ctx: EmitterContext, shared?: Sh
     if (isListMetadataModel(model) && !listMetadataNeeded.has(model.name)) continue;
     if (isListWrapperModel(model) && !nonPaginatedRefs.has(model.name)) continue;
     if (discriminatedSkip?.has(model.name)) continue;
+    // Hand-owned types are declared in a hand-written file (e.g. generics the
+    // spec cannot express). Never generate an interface for them; references
+    // route to the existing declaration via its baseline source file.
+    if (
+      isHandOwnedType(ctx, model.name) ||
+      isHandOwnedType(ctx, resolveInterfaceName(model.name, ctx, { skipTypeAlias: true }))
+    )
+      continue;
     const service = modelToService.get(model.name);
     const isOwnedModel = isNodeOwnedService(ctx, service);
     if (!isOwnedModel && !modelHasNewFields(model, ctx) && !forceGenerate.has(model.name)) continue;
@@ -342,6 +351,10 @@ export function generateModels(models: Model[], ctx: EmitterContext, shared?: Sh
     const crossServiceImports = new Map<string, { name: string; relPath: string }>();
     const unresolvableNames = new Set<string>();
     const enumToService = assignEnumsToServices(ctx.spec.enums, ctx.spec.services, ctx.spec.models, ctx);
+    // Resolve mounted/owned service names (e.g. IR `Directories` -> `DirectorySync`)
+    // so owned-service enum-import planning matches `generateEnums`, which keys
+    // ownership off the resolved name (see enums.ts).
+    const serviceNameMap = buildServiceNameMap(ctx.spec.services, ctx);
     const resolvedEnumNames = new Map<string, string>();
     for (const e of ctx.spec.enums) {
       resolvedEnumNames.set(resolveInterfaceName(e.name, ctx), e.name);
@@ -375,7 +388,7 @@ export function generateModels(models: Model[], ctx: EmitterContext, shared?: Sh
             // even when the baseline declares the name elsewhere (usually in
             // the very file being overwritten), so import planning must
             // target the canonical path to agree with that emission.
-            const eEnumIsOwned = isNodeOwnedService(ctx, eService);
+            const eEnumIsOwned = isNodeOwnedService(ctx, eService, eService ? serviceNameMap.get(eService) : undefined);
             const bSrc = eEnumIsOwned ? undefined : ((bEnum as any)?.sourceFile ?? (bAlias as any)?.sourceFile);
             const gPath = `src/${eDir}/interfaces/${fileName(irEnumName)}.interface.ts`;
             const cPath = `src/${dirName}/interfaces/${fileName(model.name)}.interface.ts`;
@@ -453,7 +466,11 @@ export function generateModels(models: Model[], ctx: EmitterContext, shared?: Sh
       const baselineEnum = ctx.apiSurface?.enums?.[dep];
       const baselineAlias = ctx.apiSurface?.typeAliases?.[dep];
       const depService = enumToService.get(dep);
-      const depEnumIsOwned = isNodeOwnedService(ctx, depService);
+      const depEnumIsOwned = isNodeOwnedService(
+        ctx,
+        depService,
+        depService ? serviceNameMap.get(depService) : undefined,
+      );
       // Fall back to the live-surface declaration path: `generateEnums` skips
       // emission when the enum is already declared elsewhere in the SDK (same
       // fallback, see enums.ts), so the import must follow that declaration —
@@ -835,6 +852,12 @@ export function generateSerializers(
     if (isListMetadataModel(model) && !serializerListMetadataNeeded.has(model.name)) continue;
     if (isListWrapperModel(model) && !serializerNonPaginatedRefs.has(model.name)) continue;
     if (discriminatedSerializerSkip?.has(model.name)) continue;
+    // Hand-owned types keep their hand-written serializer (see generateModels).
+    if (
+      isHandOwnedType(ctx, model.name) ||
+      isHandOwnedType(ctx, resolveInterfaceName(model.name, ctx, { skipTypeAlias: true }))
+    )
+      continue;
     const service = modelToService.get(model.name);
     const isOwnedModel = isNodeOwnedService(ctx, service);
     if (!isOwnedModel && !modelHasNewFields(model, ctx) && !forceGenerateSerializer.has(model.name)) continue;
@@ -979,12 +1002,28 @@ export function generateSerializers(
   }
   const liveRootForBarrel = ctx.outputDir ?? ctx.targetDir;
   for (const [dir, stems] of serializersByDir) {
-    if (liveRootForBarrel && !isNodeOwnedService(ctx, dir)) {
+    if (liveRootForBarrel) {
+      const dirIsOwned = isNodeOwnedService(ctx, dir);
       const serializersDir = path.join(liveRootForBarrel, 'src', dir, 'serializers');
       try {
         for (const entry of fs.readdirSync(serializersDir)) {
           if (!entry.endsWith('.serializer.ts')) continue;
-          stems.add(entry.replace(/\.serializer\.ts$/, ''));
+          const stem = entry.replace(/\.serializer\.ts$/, '');
+          if (stems.has(stem)) continue;
+          // Owned directories are otherwise fully regenerated. Only preserve a
+          // hand-written serializer when it belongs to a hand-owned type (i.e.
+          // exports `(de)serialize<HandOwnedType>`); stale auto-generated files
+          // should be pruned and unrelated hand-written files must not collide
+          // with generated exports.
+          if (dirIsOwned) {
+            const content = fs.readFileSync(path.join(serializersDir, entry), 'utf-8');
+            if (/auto-generated by oagen/i.test(content.slice(0, 400))) continue;
+            const serializerFns = [
+              ...content.matchAll(/export\s+(?:const|function)\s+((?:de)?serialize[A-Za-z0-9_]+)/g),
+            ].map((m) => m[1].replace(/^(?:de)?serialize/, ''));
+            if (!serializerFns.some((typeName) => isHandOwnedType(ctx, typeName))) continue;
+          }
+          stems.add(stem);
         }
       } catch {
         // Directory doesn't exist yet — only this-pass serializers will appear.

package/src/node/options.ts

@@ -38,6 +38,17 @@ export interface NodeEmitterOptions {
    * without affecting other languages.
    */
   operationOverrides?: Record<string, OperationOverride>;
+  /**
+   * Type/model names whose hand-written declarations are authoritative even
+   * inside an owned service. The emitter will NOT generate an interface or
+   * serializer for these names; instead it treats them like a baseline type,
+   * routing imports and barrel exports to the existing hand-written file.
+   *
+   * Use this to keep hand-owned generics the OpenAPI spec cannot express
+   * (for example `DirectoryUserWithGroups<TCustomAttributes>`) while still
+   * letting oagen own the rest of the service.
+   */
+  handOwnedTypes?: string[];
 }
 
 export function nodeOptions(ctx: EmitterContext): NodeEmitterOptions {
@@ -67,3 +78,15 @@ export function isNodeOwnedService(ctx: EmitterContext, ...names: Array<string |
     name !== undefined ? ownedLookupNames(name).some((candidate) => owned.has(normalizeServiceName(candidate))) : false,
   );
 }
+
+/**
+ * True when `name` is a hand-owned type (see {@link NodeEmitterOptions.handOwnedTypes}).
+ * Hand-owned types are never generated; the emitter defers to the existing
+ * hand-written declaration and routes imports/barrel exports to it.
+ */
+export function isHandOwnedType(ctx: EmitterContext, name: string | undefined): boolean {
+  if (name === undefined) return false;
+  const configured = nodeOptions(ctx).handOwnedTypes;
+  if (!configured || configured.length === 0) return false;
+  return configured.includes(name);
+}

package/src/node/resources.ts

@@ -289,7 +289,34 @@ function optionsObjectInfo(
   resolvedOp?: ResolvedOperation,
 ): OptionsObjectParam | undefined {
   const baseline = optionsObjectParam(baselineMethod);
-  if (baseline) return baseline;
+  if (baseline) {
+    // A baseline param whose type is a pure inline object literal
+    // (e.g. `{ intent?: GenerateLinkIntent; organization: string; ... }`)
+    // cannot be referenced as a named import and routinely diverges from the
+    // spec-derived request interface that the generated serializer expects —
+    // field renames (`adminEmails` -> `itContactEmails`), widened enums
+    // (`string` vs `'GoogleSAML'`), differing optionality — which makes the
+    // generated `serialize${Model}(payload)` call fail to typecheck. When the
+    // operation owns a named request-body model, adopt that interface so the
+    // method signature, the serializer, and the request model all agree.
+    // Named baseline types (`CreateOrganizationApiKeyOptions`) and compound
+    // intersections (`X & { ... }`) are still preserved verbatim.
+    if (
+      baseline.type.trimStart().startsWith('{') &&
+      isNodeOwnedService(ctx, service.name, resolveResourceClassName(service, ctx))
+    ) {
+      const body = extractRequestBodyType(op, ctx);
+      if (body?.kind === 'model') {
+        return {
+          name: 'options',
+          type: resolveInterfaceName(body.name, ctx),
+          optional: optionsObjectShouldBeOptional(op, plan, resolvedOp),
+          generated: false,
+        };
+      }
+    }
+    return baseline;
+  }
 
   const overrideType = operationOverrideFor(ctx, op)?.optionsType;
   if (overrideType) {
@@ -303,9 +330,26 @@ function optionsObjectInfo(
 
   if (!operationHasOptionsInput(op, plan, resolvedOp)) return undefined;
 
+  const resolvedService = resolveResourceClassName(service, ctx);
+  let optionsType = methodOptionsName(method, resolvedService);
+  // A bare `${Method}Options` name (e.g. `GetGroupOptions`) can collide with a
+  // same-named baseline type owned by a DIFFERENT service (for example the
+  // Groups module's `GetGroupOptions`, shaped `{ organizationId, groupId }`).
+  // Reusing it by name would import a foreign shape. When the existing
+  // declaration lives in another service directory, qualify the name with the
+  // service (mirroring the `list` -> `${Service}ListOptions` rule) so this
+  // service generates and imports its own options type.
+  if (method !== 'list') {
+    const baselineFile = baselineTypeSourceFile(ctx, optionsType);
+    const baselineDir = baselineFile?.match(/^src\/([^/]+)\//)?.[1];
+    if (baselineDir && baselineDir !== resolveResourceDir(service, ctx)) {
+      optionsType = `${toPascalCase(resolvedService)}${toPascalCase(method)}Options`;
+    }
+  }
+
   return {
     name: 'options',
-    type: methodOptionsName(method, resolveResourceClassName(service, ctx)),
+    type: optionsType,
     optional: optionsObjectShouldBeOptional(op, plan, resolvedOp),
     generated: true,
   };
@@ -1194,7 +1238,10 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
     const baselineMethod = baselineMethodFor(service, method, ctx);
     const optionInfo = optionsObjectInfo(service, method, op, plan, ctx, baselineMethod, resolved);
     if (plan.isPaginated) {
-      const extraParams = op.queryParams.filter((p) => !PAGINATION_PARAM_NAMES.has(p.name));
+      // Skip deprecated query params: the typed options interface omits them
+      // (the curated baseline drops deprecated params), so the wire serializer
+      // must not reference a field that does not exist on the options type.
+      const extraParams = op.queryParams.filter((p) => !PAGINATION_PARAM_NAMES.has(p.name) && !p.deprecated);
       if (extraParams.length > 0) {
         const optionsName = optionInfo?.type ?? paginatedOptionsName(method, resolvedName);
 

package/src/node/tests.ts

@@ -670,9 +670,11 @@ function buildOptionsObjectTestArg(
   if (plan.isPaginated) {
     entries.push("order: 'desc'");
   }
-  const queryParams = plan.isPaginated
-    ? op.queryParams.filter((param) => !['limit', 'before', 'after', 'order'].includes(param.name))
-    : op.queryParams;
+  const queryParams = (
+    plan.isPaginated
+      ? op.queryParams.filter((param) => !['limit', 'before', 'after', 'order'].includes(param.name))
+      : op.queryParams
+  ).filter((param) => !param.deprecated);
   for (const param of queryParams) {
     const localName = fieldName(param.name);
     const value = queryParamTestValue(param, modelMap);

package/test/node/enums.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
-import type { EmitterContext, ApiSpec, Enum, Model } from '@workos/oagen';
+import type { EmitterContext, ApiSpec, Enum, Model, Service } from '@workos/oagen';
 import { defaultSdkBehavior } from '@workos/oagen';
-import { generateEnums } from '../../src/node/enums.js';
+import { generateEnums, assignEnumsToServices } from '../../src/node/enums.js';
 import { nodeEmitter } from '../../src/node/index.js';
 import { emptyLiveSurface, setActiveLiveSurface } from '../../src/node/live-surface.js';
 import * as fs from 'node:fs';
@@ -195,6 +195,142 @@ describe('assignEnumsToServices owned-service dependency reassignment', () => {
   });
 });
 
+describe('assignEnumsToServices common-home unassignment under ownership', () => {
+  // Inverse of the reassignment case above: an enum referenced by an OWNED
+  // service is first-reference-assigned into that service, but its canonical
+  // declaration already lives under `src/common/`. The unassignment guard
+  // must drop it back to `common` so the owned-service exception in
+  // `generateEnums` does not emit a SECOND copy alongside the existing
+  // `common` one (a duplicate `export *` / TS2308).
+  const connectionType: Enum = {
+    name: 'ConnectionType',
+    values: [
+      { name: 'GOOGLE_SAML', value: 'GoogleSAML' },
+      { name: 'OKTA_SAML', value: 'OktaSAML' },
+    ],
+  };
+  const ssoService: Service = {
+    name: 'SSO',
+    operations: [
+      {
+        name: 'listConnections',
+        httpMethod: 'get',
+        path: '/connections',
+        pathParams: [],
+        queryParams: [
+          {
+            name: 'connectionType',
+            type: { kind: 'enum', name: 'ConnectionType', values: ['GoogleSAML', 'OktaSAML'] },
+            required: false,
+          },
+        ],
+        headerParams: [],
+        response: { kind: 'primitive', type: 'unknown' },
+        errors: [],
+        injectIdempotencyKey: false,
+      },
+    ],
+  };
+
+  const makeCtx = (overrides: Partial<EmitterContext>): EmitterContext =>
+    ({
+      ...ctx,
+      spec: { ...emptySpec, enums: [connectionType], services: [ssoService] },
+      emitterOptions: { ownedServices: ['SSO'] },
+      ...overrides,
+    }) as EmitterContext;
+
+  it('unassigns an owned-service enum whose apiSurface sourceFile is under src/common/', () => {
+    const ctxOwned = makeCtx({
+      apiSurface: {
+        classes: {},
+        interfaces: {},
+        typeAliases: {},
+        exports: {},
+        enums: { ConnectionType: { sourceFile: 'src/common/interfaces/connection-type.interface.ts' } },
+      },
+    } as unknown as Partial<EmitterContext>);
+
+    const map = assignEnumsToServices([connectionType], [ssoService], [], ctxOwned);
+    // Unassigned → resolves to `common`, not the owned `SSO` directory.
+    expect(map.has('ConnectionType')).toBe(false);
+  });
+
+  it('unassigns via the typeAliases sourceFile lookup (literal-union baseline form)', () => {
+    const ctxOwned = makeCtx({
+      apiSurface: {
+        classes: {},
+        interfaces: {},
+        enums: {},
+        exports: {},
+        typeAliases: {
+          ConnectionType: {
+            value: "'GoogleSAML' | 'OktaSAML'",
+            sourceFile: 'src/common/interfaces/connection-type.interface.ts',
+          },
+        },
+      },
+    } as unknown as Partial<EmitterContext>);
+
+    const map = assignEnumsToServices([connectionType], [ssoService], [], ctxOwned);
+    expect(map.has('ConnectionType')).toBe(false);
+  });
+
+  it('falls back to the live-surface interface path when no apiSurface entry exists', () => {
+    // Guards the `liveSurfaceInterfacePath(name)` fallback: with no apiSurface,
+    // the canonical home is only discoverable through the scanned live surface.
+    const surface = emptyLiveSurface();
+    surface.files.add('src/workos.ts');
+    surface.interfaces.set('ConnectionType', {
+      filePath: 'src/common/interfaces/connection-type.interface.ts',
+      fields: new Set(),
+    });
+    setActiveLiveSurface(surface);
+    try {
+      const map = assignEnumsToServices([connectionType], [ssoService], [], makeCtx({}));
+      expect(map.has('ConnectionType')).toBe(false);
+    } finally {
+      setActiveLiveSurface(emptyLiveSurface());
+    }
+  });
+
+  it('keeps an owned-service enum whose canonical home is NOT under src/common/', () => {
+    // The guard is specific to `src/common/`: an enum that genuinely belongs to
+    // the owned service must stay assigned there.
+    const ctxOwned = makeCtx({
+      apiSurface: {
+        classes: {},
+        interfaces: {},
+        typeAliases: {},
+        exports: {},
+        enums: { ConnectionType: { sourceFile: 'src/sso/interfaces/connection-type.interface.ts' } },
+      },
+    } as unknown as Partial<EmitterContext>);
+
+    const map = assignEnumsToServices([connectionType], [ssoService], [], ctxOwned);
+    expect(map.get('ConnectionType')).toBe('SSO');
+  });
+
+  it('does not unassign for a non-owned service even when the home is under src/common/', () => {
+    // The unassignment only applies under ownership — a non-owned service keeps
+    // its first-reference assignment regardless of where the enum's home is.
+    const ctxNotOwned = {
+      ...ctx,
+      spec: { ...emptySpec, enums: [connectionType], services: [ssoService] },
+      apiSurface: {
+        classes: {},
+        interfaces: {},
+        typeAliases: {},
+        exports: {},
+        enums: { ConnectionType: { sourceFile: 'src/common/interfaces/connection-type.interface.ts' } },
+      },
+    } as unknown as EmitterContext;
+
+    const map = assignEnumsToServices([connectionType], [ssoService], [], ctxNotOwned);
+    expect(map.get('ConnectionType')).toBe('SSO');
+  });
+});
+
 describe('owned-service enum emission under the live-surface skip', () => {
   function ownedDomainSpec(enums: Enum[], models: Model[]): ApiSpec {
     return {

package/test/node/resources.test.ts

@@ -895,82 +895,118 @@ describe('paginated list methods and path params (AutoPaginatable typing)', () =
 describe('inline object-literal baseline parameter types', () => {
   // The hand-written workos-node AdminPortal method uses an inline object-literal
   // parameter TYPE (`generateLink({ ... }: { intent: GenerateLinkIntent; ... })`).
-  // When the baseline surface reports that literal text as the param "type name",
-  // the emitter must keep it inline in the signature and must NOT slugify it into
-  // an interface filename or emit a named import of a brace-expression.
-  it('keeps the literal type inline and never imports it', () => {
-    const literalType = '{ intent: GenerateLinkIntent; organization: string; returnUrl?: string }';
-    const service: Service = {
-      name: 'AdminPortal',
-      operations: [
-        {
-          name: 'generateLink',
-          httpMethod: 'post',
-          path: '/portal/generate_link',
-          pathParams: [],
-          queryParams: [],
-          headerParams: [],
-          requestBody: { kind: 'model', name: 'GenerateLinkBody' },
-          response: { kind: 'model', name: 'PortalLink' },
-          errors: [],
-          injectIdempotencyKey: false,
-        },
-      ],
-    };
-    const spec: ApiSpec = {
-      ...emptySpec,
-      services: [service],
-      models: [
-        {
-          name: 'GenerateLinkBody',
-          fields: [
-            { name: 'intent', type: { kind: 'primitive', type: 'string' }, required: true },
-            { name: 'organization', type: { kind: 'primitive', type: 'string' }, required: true },
-          ],
-        },
-        {
-          name: 'PortalLink',
-          fields: [{ name: 'link', type: { kind: 'primitive', type: 'string' }, required: true }],
-        },
-      ],
-    };
-    const ctxWithBaseline: EmitterContext = {
-      ...ctx,
-      spec,
-      emitterOptions: { ownedServices: ['AdminPortal'] },
-      apiSurface: {
-        classes: {
-          AdminPortal: {
-            constructorParams: [{ name: 'workos', type: 'WorkOS' }],
-            methods: {
-              generateLink: [
-                {
-                  name: 'generateLink',
-                  params: [{ name: 'options', type: literalType, passingStyle: 'options_object' }],
-                  returnType: 'Promise<{ link: string }>',
-                  async: true,
-                },
-              ],
-            },
+  // For an OWNED service, that inline literal frequently diverges from the
+  // spec-derived request interface the generated serializer expects (field
+  // renames, widened enums, differing optionality), so the emitter adopts the
+  // named request-body interface instead of preserving the literal — while
+  // still never slugifying the literal text into an interface filename or
+  // emitting a named import of a brace-expression.
+  const literalType = '{ intent: GenerateLinkIntent; organization: string; returnUrl?: string }';
+
+  const adminPortalService = (requestBody: any): Service => ({
+    name: 'AdminPortal',
+    operations: [
+      {
+        name: 'generateLink',
+        httpMethod: 'post',
+        path: '/portal/generate_link',
+        pathParams: [],
+        queryParams: [],
+        headerParams: [],
+        requestBody,
+        response: { kind: 'model', name: 'PortalLink' },
+        errors: [],
+        injectIdempotencyKey: false,
+      },
+    ],
+  });
+
+  const baselineCtx = (service: Service, models: any[]): EmitterContext => ({
+    ...ctx,
+    spec: { ...emptySpec, services: [service], models },
+    emitterOptions: { ownedServices: ['AdminPortal'] },
+    apiSurface: {
+      classes: {
+        AdminPortal: {
+          constructorParams: [{ name: 'workos', type: 'WorkOS' }],
+          methods: {
+            generateLink: [
+              {
+                name: 'generateLink',
+                params: [{ name: 'options', type: literalType, passingStyle: 'options_object' }],
+                returnType: 'Promise<{ link: string }>',
+                async: true,
+              },
+            ],
           },
         },
-      } as any,
-    };
+      },
+    } as any,
+  });
 
-    const result = generateResources([service], ctxWithBaseline);
+  it('adopts the named request-body interface instead of the inline literal', () => {
+    const service = adminPortalService({ kind: 'model', name: 'GenerateLinkBody' });
+    const models = [
+      {
+        name: 'GenerateLinkBody',
+        fields: [
+          { name: 'intent', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'organization', type: { kind: 'primitive', type: 'string' }, required: true },
+        ],
+      },
+      {
+        name: 'PortalLink',
+        fields: [{ name: 'link', type: { kind: 'primitive', type: 'string' }, required: true }],
+      },
+    ];
+
+    const result = generateResources([service], baselineCtx(service, models));
     const resourceFile = result.find((f) => f.path === 'src/admin-portal/admin-portal.ts');
     expect(resourceFile).toBeDefined();
     const content = resourceFile!.content;
 
-    // The literal type stays inline in the method signature.
-    expect(content).toContain(`async generateLink(options: ${literalType})`);
-    // No named import of a brace-expression…
+    // The named request interface replaces the inline literal in the signature,
+    // so the method param, the request model, and `serialize*` all agree.
+    expect(content).toContain('async generateLink(options: GenerateLinkBody)');
+    expect(content).toContain('serializeGenerateLinkBody(payload)');
+    // The inline literal is gone from the signature.
+    expect(content).not.toContain(`options: ${literalType}`);
+    // No named import of a brace-expression, and no import path / interface
+    // file derived from slugifying the literal type's text.
     expect(content).not.toContain('import type { {');
-    // …and no import path derived from slugifying the literal type's text.
     expect(content).not.toContain('intent-generate-link-intent');
-    // No interface file is emitted for the literal type either.
     expect(result.some((f) => f.path.includes('intent-generate-link-intent'))).toBe(false);
   });
+
+  it('keeps the literal inline when there is no single named request model', () => {
+    // A union request body has no single named interface to adopt, so the
+    // emitter must fall back to preserving the inline literal (and must still
+    // never slugify it into an import).
+    const service = adminPortalService({
+      kind: 'union',
+      variants: [
+        { kind: 'model', name: 'SsoLinkBody' },
+        { kind: 'model', name: 'DsyncLinkBody' },
+      ],
+    });
+    const models = [
+      {
+        name: 'SsoLinkBody',
+        fields: [{ name: 'organization', type: { kind: 'primitive', type: 'string' }, required: true }],
+      },
+      {
+        name: 'DsyncLinkBody',
+        fields: [{ name: 'organization', type: { kind: 'primitive', type: 'string' }, required: true }],
+      },
+      { name: 'PortalLink', fields: [{ name: 'link', type: { kind: 'primitive', type: 'string' }, required: true }] },
+    ];
+
+    const result = generateResources([service], baselineCtx(service, models));
+    const content = result.find((f) => f.path === 'src/admin-portal/admin-portal.ts')!.content;
+
+    expect(content).toContain(`async generateLink(options: ${literalType})`);
+    expect(content).not.toContain('import type { {');
+  });
 });
 
 describe('@oagen-ignore region method filtering', () => {