@workos/oagen-emitters 0.3.0 → 0.4.0

package/src/node/resources.ts

@@ -40,6 +40,7 @@ import {
   getOpInferFromClient,
 } from '../shared/resolved-ops.js';
 import { generateWrapperMethods, collectWrapperResponseModels } from './wrappers.js';
+import { resolveWrapperParams } from '../shared/wrapper-utils.js';
 
 /**
  * Check whether the baseline (hand-written) class has a constructor compatible
@@ -192,6 +193,62 @@ function deduplicateMethodNames(
   }
 }
 
+/**
+ * Emit one interface file per paginated list operation that has extension
+ * query params.  Placing the options interface under `interfaces/` lets the
+ * per-service barrel pick it up via `export * from './interfaces'`, which
+ * is what the root `src/index.ts` re-exports.  When the interface was
+ * declared inline in the resource file, it was unreachable from the barrel
+ * and callers couldn't import the type by name from the package root.
+ */
+function generatePaginatedOptionsInterfaces(
+  service: Service,
+  ctx: EmitterContext,
+  specEnumNames: Set<string>,
+): GeneratedFile[] {
+  const files: GeneratedFile[] = [];
+  const resolvedName = resolveResourceClassName(service, ctx);
+  const serviceDir = resolveServiceDir(resolvedName);
+
+  const plans = service.operations.map((op) => ({
+    op,
+    plan: planOperation(op),
+    method: resolveMethodName(op, service, ctx),
+  }));
+
+  for (const { op, plan, method } of plans) {
+    if (!plan.isPaginated) continue;
+    const extraParams = op.queryParams.filter((p) => !PAGINATION_PARAM_NAMES.has(p.name));
+    if (extraParams.length === 0) continue;
+
+    const optionsName = paginatedOptionsName(method, resolvedName);
+    const filePath = `src/${serviceDir}/interfaces/${fileName(optionsName)}.interface.ts`;
+
+    const lines: string[] = [];
+    lines.push("import type { PaginationOptions } from '../../common/interfaces/pagination-options.interface';");
+    lines.push('');
+    lines.push(`export interface ${optionsName} extends PaginationOptions {`);
+    for (const param of extraParams) {
+      const opt = !param.required ? '?' : '';
+      if (param.description || param.deprecated) {
+        const parts: string[] = [];
+        if (param.description) parts.push(param.description);
+        if (param.deprecated) parts.push('@deprecated');
+        lines.push(...docComment(parts.join('\n'), 2));
+      }
+      lines.push(`  ${fieldName(param.name)}${opt}: ${mapParamType(param.type, specEnumNames)};`);
+    }
+    lines.push('}');
+
+    files.push({
+      path: filePath,
+      content: lines.join('\n'),
+    });
+  }
+
+  return files;
+}
+
 export function generateResources(services: Service[], ctx: EmitterContext): GeneratedFile[] {
   if (services.length === 0) return [];
   const files: GeneratedFile[] = [];
@@ -202,6 +259,8 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
   const mergedServices: Service[] =
     mountGroups.size > 0 ? [...mountGroups].map(([name, group]) => ({ name, operations: group.operations })) : services;
 
+  const topLevelEnumNames = new Set(ctx.spec.enums.map((e) => e.name));
+
   for (const service of mergedServices) {
     if (isServiceCoveredByExisting(service, ctx)) {
       // Fully covered: generate with ALL operations so the merger's docstring
@@ -233,10 +292,24 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
       file.headerPlacement = 'skip';
       files.push(file);
     } else {
-      files.push(generateResourceClass(service, ctx));
+      // Purely oagen-managed: no baseline class exists, so the file is owned
+      // end-to-end by the emitter.  Remove skipIfExists so regeneration always
+      // overwrites — emitter improvements (serializer dispatch, JSDoc, etc.)
+      // must propagate without manual intervention.
+      const file = generateResourceClass(service, ctx);
+      delete file.skipIfExists;
+      files.push(file);
     }
   }
 
+  // Emit paginated list options interfaces AFTER the resource classes so
+  // tests and manifest ordering that index `files[0]` as the class stay
+  // stable.  Placing them under `interfaces/` lets the per-service barrel
+  // pick them up automatically.
+  for (const service of mergedServices) {
+    files.push(...generatePaginatedOptionsInterfaces(service, ctx, topLevelEnumNames));
+  }
+
   return files;
 }
 
@@ -367,6 +440,9 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
 
   // Collect response models from union split wrappers so their types and
   // deserializers are imported alongside the primary operation models.
+  // Also collect models referenced in wrapper param signatures (e.g.,
+  // `redirect_uris: RedirectUriInput[]`) — otherwise the wrapper emits a
+  // reference to a type it never imported.
   const resolvedLookup = buildResolvedLookup(ctx);
   for (const { op, method } of plans) {
     if (baselineMethodSet.has(method)) continue;
@@ -375,6 +451,11 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
       for (const name of collectWrapperResponseModels(resolved)) {
         responseModels.add(name);
       }
+      for (const wrapper of resolved.wrappers ?? []) {
+        for (const { field } of resolveWrapperParams(wrapper, ctx)) {
+          if (field) collectParamTypeRefs(field.type, paramEnums, paramModels);
+        }
+      }
     }
   }
 
@@ -390,6 +471,17 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
     lines.push("import { createPaginatedList } from '../common/utils/fetch-and-deserialize';");
   }
 
+  // Paginated list options live in their own interface files so they're
+  // picked up by the per-service barrel (and flow through to the root
+  // package barrel).  Import them here rather than declaring inline.
+  for (const { op, plan, method } of plans) {
+    if (!plan.isPaginated) continue;
+    const extraParams = op.queryParams.filter((p) => !PAGINATION_PARAM_NAMES.has(p.name));
+    if (extraParams.length === 0) continue;
+    const optionsName = paginatedOptionsName(method, resolvedName);
+    lines.push(`import type { ${optionsName} } from './interfaces/${fileName(optionsName)}.interface';`);
+  }
+
   // Check if any operation needs PostOptions (idempotent POST or custom encoding)
   const hasIdempotentPost = plans.some((p) => p.plan.isIdempotentPost);
   const hasCustomEncoding = plans.some(
@@ -493,32 +585,43 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
 
   lines.push('');
 
-  // Options interfaces for operations with query params.
-  // Paginated operations extend PaginationOptions; non-paginated operations get standalone interfaces.
+  // Per-operation helpers (wire-format option serializers etc.) emitted
+  // alongside the resource class.  The options interfaces themselves live
+  // in separate files under `interfaces/` so the per-service barrel can
+  // re-export them; see the earlier import block at the top of the file.
   for (const { op, plan, method } of plans) {
     if (plan.isPaginated) {
       const extraParams = op.queryParams.filter((p) => !PAGINATION_PARAM_NAMES.has(p.name));
       if (extraParams.length > 0) {
         const optionsName = paginatedOptionsName(method, resolvedName);
-        // Always generate the options interface locally in the resource file.
-        // Previously we skipped generation when a baseline interface with a matching
-        // name existed, but the baseline interface may live in a different module
-        // (e.g., `user-management/` vs `user-management-users/`) and would not be
-        // available without an import.  Generating locally is safe and avoids
-        // cross-module import resolution issues.
-        lines.push(`export interface ${optionsName} extends PaginationOptions {`);
-        for (const param of extraParams) {
-          const opt = !param.required ? '?' : '';
-          if (param.description || param.deprecated) {
-            const parts: string[] = [];
-            if (param.description) parts.push(param.description);
-            if (param.deprecated) parts.push('@deprecated');
-            lines.push(...docComment(parts.join('\n'), 2));
+
+        // When any extension param has a camelCase domain name that differs
+        // from its snake_case wire name, emit a serializer that translates
+        // the user-facing options into the wire query shape.  Without this,
+        // the query string uses camelCase keys (e.g. `organizationId=...`)
+        // that the API silently ignores — the filter becomes a no-op.
+        const needsWireSerializer = extraParams.some((p) => fieldName(p.name) !== wireFieldName(p.name));
+        if (needsWireSerializer) {
+          const serializerName = `serialize${optionsName}`;
+          lines.push(`const ${serializerName} = (options: ${optionsName}): PaginationOptions => {`);
+          // Pagination fields pass through unchanged (limit/before/after/order
+          // share spelling in both cases).  Spread first so that wire-named
+          // extension fields land on top and the camelCase keys don't also
+          // leak into the query string.
+          lines.push('  const wire: Record<string, unknown> = {');
+          for (const p of PAGINATION_PARAM_NAMES) {
+            lines.push(`    ${p}: options.${p},`);
           }
-          lines.push(`  ${fieldName(param.name)}${opt}: ${mapParamType(param.type, specEnumNames)};`);
+          lines.push('  };');
+          for (const param of extraParams) {
+            const camel = fieldName(param.name);
+            const snake = wireFieldName(param.name);
+            lines.push(`  if (options.${camel} !== undefined) wire.${snake} = options.${camel};`);
+          }
+          lines.push('  return wire as PaginationOptions;');
+          lines.push('};');
+          lines.push('');
         }
-        lines.push('}');
-        lines.push('');
       }
     } else if (!plan.isPaginated && !plan.hasBody && !plan.isDelete && op.queryParams.length > 0) {
       // Non-paginated GET or void methods with query params get a typed options interface
@@ -708,7 +811,8 @@ function renderMethod(
       const itemTypeName = resolveInterfaceName(itemRawName, ctx);
       docParts.push(`@returns {Promise<AutoPaginatable<${itemTypeName}>>}`);
     } else if (responseModel) {
-      docParts.push(`@returns {Promise<${responseModel}>}`);
+      const returnTypeDoc = plan.isArrayResponse ? `${responseModel}[]` : responseModel;
+      docParts.push(`@returns {Promise<${returnTypeDoc}>}`);
     } else {
       docParts.push('@returns {Promise<void>}');
     }
@@ -811,13 +915,18 @@ function renderPaginatedMethod(
 ): void {
   const extraParams = op.queryParams.filter((p) => !PAGINATION_PARAM_NAMES.has(p.name));
   const optionsType = extraParams.length > 0 ? paginatedOptionsName(method, resolvedServiceName) : 'PaginationOptions';
+  // When any extension param has a camelCase/snake_case divergence, the
+  // resource file emits a `serialize<OptionsName>` helper — pass it to
+  // createPaginatedList so the wire query uses snake_case keys.
+  const needsWireSerializer = extraParams.some((p) => fieldName(p.name) !== wireFieldName(p.name));
+  const serializerArg = needsWireSerializer ? `, serialize${optionsType}` : '';
 
   const pathParams = buildPathParams(op, specEnumNames);
   const allParams = pathParams ? `${pathParams}, options?: ${optionsType}` : `options?: ${optionsType}`;
 
   lines.push(`  async ${method}(${allParams}): Promise<AutoPaginatable<${itemType}, ${optionsType}>> {`);
   lines.push(
-    `    return createPaginatedList<${wireInterfaceName(itemType)}, ${itemType}, ${optionsType}>(this.workos, ${pathStr}, deserialize${itemType}, options);`,
+    `    return createPaginatedList<${wireInterfaceName(itemType)}, ${itemType}, ${optionsType}>(this.workos, ${pathStr}, deserialize${itemType}, options${serializerArg});`,
   );
   lines.push('  }');
 }
@@ -926,16 +1035,22 @@ function renderBodyMethod(
   const encodingOption = encoding && encoding !== 'json' ? `, encoding: '${encoding}' as const` : '';
   const hasCustomEncoding = encodingOption !== '';
 
-  lines.push(`  async ${method}(${paramsStr}): Promise<${responseModel}> {`);
+  const returnType = plan.isArrayResponse ? `${responseModel}[]` : responseModel;
+  const wireType = plan.isArrayResponse ? `${wireInterfaceName(responseModel)}[]` : wireInterfaceName(responseModel);
+  const returnExpr = plan.isArrayResponse
+    ? `data.map(deserialize${responseModel})`
+    : `deserialize${responseModel}(data)`;
+
+  lines.push(`  async ${method}(${paramsStr}): Promise<${returnType}> {`);
   if (plan.isIdempotentPost) {
     if (hasCustomEncoding) {
-      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(`);
+      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(`);
       lines.push(`      ${pathStr},`);
       lines.push(`      ${bodyExpr},`);
       lines.push(`      { ...requestOptions${encodingOption} },`);
       lines.push('    );');
     } else {
-      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(`);
+      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(`);
       lines.push(`      ${pathStr},`);
       lines.push(`      ${bodyExpr},`);
       lines.push('      requestOptions,');
@@ -943,19 +1058,19 @@ function renderBodyMethod(
     }
   } else {
     if (hasCustomEncoding) {
-      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(`);
+      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(`);
       lines.push(`      ${pathStr},`);
       lines.push(`      ${bodyExpr},`);
       lines.push(`      { ${encodingOption.slice(2)} },`);
       lines.push('    );');
     } else {
-      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(`);
+      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(`);
       lines.push(`      ${pathStr},`);
       lines.push(`      ${bodyExpr},`);
       lines.push('    );');
     }
   }
-  lines.push(`    return deserialize${responseModel}(data);`);
+  lines.push(`    return ${returnExpr};`);
   lines.push('  }');
 }
 
@@ -989,7 +1104,13 @@ function renderGetMethod(
       : `options?: ${optionsType}`
     : params;
 
-  lines.push(`  async ${method}(${allParams}): Promise<${responseModel}> {`);
+  const returnType = plan.isArrayResponse ? `${responseModel}[]` : responseModel;
+  const wireType = plan.isArrayResponse ? `${wireInterfaceName(responseModel)}[]` : wireInterfaceName(responseModel);
+  const returnExpr = plan.isArrayResponse
+    ? `data.map(deserialize${responseModel})`
+    : `deserialize${responseModel}(data)`;
+
+  lines.push(`  async ${method}(${allParams}): Promise<${returnType}> {`);
   if (hasQuery) {
     if (hasInjected) {
       // Build the query object with visible params, defaults, and inferred fields
@@ -1026,30 +1147,22 @@ function renderGetMethod(
         queryParts.push(`${field}: ${clientFieldExpression(field)}`);
       }
 
-      lines.push(
-        `    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(${pathStr}, {`,
-      );
+      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(${pathStr}, {`);
       lines.push(`      query: { ${queryParts.join(', ')} },`);
       lines.push('    });');
     } else {
       const queryExpr = renderQueryExpr(visibleQueryParams);
-      lines.push(
-        `    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(${pathStr}, {`,
-      );
+      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(${pathStr}, {`);
       lines.push(`      query: ${queryExpr},`);
       lines.push('    });');
     }
   } else if (httpMethodNeedsBody(op.httpMethod)) {
     // PUT/PATCH/POST require a body argument even when the spec has no request body
-    lines.push(
-      `    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(${pathStr}, {});`,
-    );
+    lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(${pathStr}, {});`);
   } else {
-    lines.push(
-      `    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(${pathStr});`,
-    );
+    lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(${pathStr});`);
   }
-  lines.push(`    return deserialize${responseModel}(data);`);
+  lines.push(`    return ${returnExpr};`);
   lines.push('  }');
 }
 
@@ -1263,9 +1376,16 @@ function renderUnionBodySerializer(
   const cases: string[] = [];
   for (const [value, modelName] of Object.entries(disc.mapping)) {
     const resolved = resolveInterfaceName(modelName, ctx);
-    cases.push(`case '${value}': return serialize${resolved}(payload as any)`);
+    // Switch on a typed discriminator narrows `payload` to the variant, so the
+    // serializer call type-checks without any casts.
+    cases.push(`case '${value}': return serialize${resolved}(payload)`);
   }
-  return `(() => { switch ((payload as any).${prop}) { ${cases.join('; ')}; default: return payload } })()`;
+  // Assign `payload` to `never` in the default branch to get a compile-time
+  // exhaustiveness check — if a new variant is added to the union but not to
+  // the switch, the build fails here.  At runtime, we still throw so an
+  // unknown discriminator slipping through via `as any` fails loudly rather
+  // than silently forwarding camelCase to the API.
+  return `(() => { switch (payload.${prop}) { ${cases.join('; ')}; default: { const _unknown: never = payload; throw new Error(\`Unknown ${prop}: \${(_unknown as { ${prop}?: unknown }).${prop}}\`) } } })()`;
 }
 
 /**

package/src/node/tests.ts

@@ -9,6 +9,7 @@ import {
   servicePropertyName,
   resolveMethodName,
   resolveInterfaceName,
+  wireInterfaceName,
 } from './naming.js';
 import { generateFixtures } from './fixtures.js';
 import { resolveResourceClassName } from './resources.js';
@@ -751,9 +752,21 @@ function buildTestPayload(
   op: Operation,
   modelMap: Map<string, Model>,
 ): { camelCaseObj: string; snakeCaseObj: string } | null {
-  if (!op.requestBody || op.requestBody.kind !== 'model') return null;
-
-  const model = modelMap.get(op.requestBody.name);
+  if (!op.requestBody) return null;
+
+  // For discriminated unions, build a payload from the first variant so the
+  // generated test produces a value that satisfies the union type.  Without
+  // this, emitted tests pass `{} as any` for union bodies — fine for older
+  // permissive runtimes, but the dispatch switch now throws on unknown
+  // discriminator values, so the tests would fail before hitting fetch.
+  let model: Model | undefined;
+  if (op.requestBody.kind === 'union') {
+    const firstVariant = op.requestBody.variants.find((v) => v.kind === 'model');
+    if (!firstVariant || firstVariant.kind !== 'model') return null;
+    model = modelMap.get(firstVariant.name);
+  } else if (op.requestBody.kind === 'model') {
+    model = modelMap.get(op.requestBody.name);
+  }
   if (!model) return null;
 
   const fields = model.fields.filter((f) => f.required);
@@ -789,8 +802,14 @@ function buildTestPayload(
  * fall back to `{} as any` to bypass type checking for complex required fields.
  */
 function fallbackBodyArg(op: Operation, modelMap: Map<string, Model>): string {
-  if (!op.requestBody || op.requestBody.kind !== 'model') return '{} as any';
-  const model = modelMap.get(op.requestBody.name);
+  if (!op.requestBody) return '{} as any';
+  let model: Model | undefined;
+  if (op.requestBody.kind === 'union') {
+    const firstVariant = op.requestBody.variants.find((v) => v.kind === 'model');
+    if (firstVariant && firstVariant.kind === 'model') model = modelMap.get(firstVariant.name);
+  } else if (op.requestBody.kind === 'model') {
+    model = modelMap.get(op.requestBody.name);
+  }
   if (!model) return '{} as any';
   const hasRequiredFields = model.fields.some((f) => f.required);
   return hasRequiredFields ? '{} as any' : '{}';
@@ -844,6 +863,7 @@ function generateSerializerTests(spec: ApiSpec, ctx: EmitterContext): GeneratedF
 
     // Collect imports
     const serializerImports: string[] = [];
+    const interfaceImports: string[] = [];
     const fixtureImports: string[] = [];
 
     for (const model of models) {
@@ -851,11 +871,14 @@ function generateSerializerTests(spec: ApiSpec, ctx: EmitterContext): GeneratedF
       const service = modelToService.get(model.name);
       const modelDir = resolveDir(service);
       const serializerPath = `src/${modelDir}/serializers/${fileName(model.name)}.serializer.ts`;
+      const interfacePath = `src/${modelDir}/interfaces/${fileName(model.name)}.interface.ts`;
       const fixturePath = `src/${modelDir}/fixtures/${fileName(model.name)}.fixture.json`;
 
       serializerImports.push(
         `import { deserialize${domainName}, serialize${domainName} } from '${relativeImport(testPath, serializerPath)}';`,
       );
+      const wireName = wireInterfaceName(domainName);
+      interfaceImports.push(`import type { ${wireName} } from '${relativeImport(testPath, interfacePath)}';`);
       const camelName = domainName.charAt(0).toLowerCase() + domainName.slice(1);
       fixtureImports.push(`import ${camelName}Fixture from '${relativeImport(testPath, fixturePath)}';`);
     }
@@ -863,6 +886,9 @@ function generateSerializerTests(spec: ApiSpec, ctx: EmitterContext): GeneratedF
     for (const imp of serializerImports) {
       lines.push(imp);
     }
+    for (const imp of interfaceImports) {
+      lines.push(imp);
+    }
     for (const imp of fixtureImports) {
       lines.push(imp);
     }
@@ -873,9 +899,14 @@ function generateSerializerTests(spec: ApiSpec, ctx: EmitterContext): GeneratedF
       const camelDomain = domainName.charAt(0).toLowerCase() + domainName.slice(1);
       const fixtureName = `${camelDomain}Fixture`;
 
+      const wireName = wireInterfaceName(domainName);
       lines.push(`describe('${domainName}Serializer', () => {`);
       lines.push("  it('round-trips through serialize/deserialize', () => {");
-      lines.push(`    const fixture = ${fixtureName};`);
+      // Cast the fixture to the wire-type interface — JSON imports are inferred
+      // with primitive types (e.g., `string`) that don't satisfy literal-typed
+      // response fields (e.g., `type: "enum"`), so the deserialize call needs
+      // the explicit cast to compile.
+      lines.push(`    const fixture = ${fixtureName} as ${wireName};`);
       lines.push(`    const deserialized = deserialize${domainName}(fixture);`);
       lines.push(`    const reserialized = serialize${domainName}(deserialized);`);
       lines.push('    expect(reserialized).toEqual(expect.objectContaining(fixture));');
@@ -888,7 +919,6 @@ function generateSerializerTests(spec: ApiSpec, ctx: EmitterContext): GeneratedF
       path: testPath,
       content: lines.join('\n'),
       skipIfExists: true,
-      integrateTarget: false,
     });
   }
 

package/src/php/client.ts

@@ -127,10 +127,13 @@ function generateMainClient(
   for (const svc of services) {
     lines.push(`    private ?Service\\${svc.name} $${svc.propName} = null;`);
   }
-  // Non-spec service properties (hand-maintained modules)
+  // Non-spec service properties — wrapped in ignore markers so the target
+  // SDK can hand-maintain the list. The emitter provides a positional anchor.
+  lines.push('    // @oagen-ignore-start — non-spec service properties (hand-maintained)');
   for (const a of nonSpecAccessors) {
     lines.push(`    private ?${a.className} $${a.propName} = null;`);
   }
+  lines.push('    // @oagen-ignore-end');
 
   lines.push('');
   lines.push('    public function __construct(');
@@ -140,11 +143,12 @@ function generateMainClient(
   lines.push('        int $timeout = 60,');
   lines.push('        int $maxRetries = 3,');
   lines.push('        ?\\GuzzleHttp\\HandlerStack $handler = null,');
+  lines.push('        ?string $userAgent = null,');
   lines.push('    ) {');
   lines.push("        $apiKey ??= getenv('WORKOS_API_KEY') ?: self::$apiKey ?? '';");
   lines.push("        $clientId ??= getenv('WORKOS_CLIENT_ID') ?: self::$clientId;");
   lines.push(
-    '        $this->httpClient = new HttpClient($apiKey, $clientId, $baseUrl, $timeout, $maxRetries, $handler);',
+    '        $this->httpClient = new HttpClient($apiKey, $clientId, $baseUrl, $timeout, $maxRetries, $handler, $userAgent);',
   );
   lines.push('    }');
 
@@ -157,7 +161,10 @@ function generateMainClient(
     lines.push('    }');
   }
 
-  // Non-spec service accessors (hand-maintained modules)
+  // Non-spec service accessors — wrapped in ignore markers so the target
+  // SDK can hand-maintain these. The emitter provides a positional anchor.
+  lines.push('');
+  lines.push('    // @oagen-ignore-start — non-spec service accessors (hand-maintained)');
   for (const a of nonSpecAccessors) {
     lines.push('');
     lines.push(`    public function ${a.propName}(): ${a.className}`);
@@ -165,6 +172,7 @@ function generateMainClient(
     lines.push(`        return $this->${a.propName} ??= new ${a.className}($this->httpClient);`);
     lines.push('    }');
   }
+  lines.push('    // @oagen-ignore-end');
 
   lines.push('}');
   return lines.join('\n');

package/src/php/naming.ts

@@ -1,7 +1,7 @@
 import type { Service, Operation, EmitterContext, Enum } from '@workos/oagen';
 import { toPascalCase, toCamelCase, toSnakeCase } from '@workos/oagen';
 import { buildResolvedLookup, lookupMethodName } from '../shared/resolved-ops.js';
-import { stripUrnPrefix } from '../shared/naming-utils.js';
+import { stripUrnPrefix, applyAcronymFixes } from '../shared/naming-utils.js';
 
 /** Namespace grouping result (shared with client.ts). */
 export interface NamespaceGroup {
@@ -16,22 +16,6 @@ export interface NamespaceGrouping {
   namespaces: NamespaceGroup[];
 }
 
-/**
- * Map of lowercase acronym forms to their correct casing.
- */
-const ACRONYM_FIXES: [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'],
-];
-
 /**
  * PHP reserved class names that would collide with builtins.
  */
@@ -99,10 +83,7 @@ export function enumClassName(name: string): string {
 
 /** PascalCase class name with acronym preservation. */
 export function className(name: string): string {
-  let result = toPascalCase(stripUrnPrefix(name));
-  for (const [pattern, replacement] of ACRONYM_FIXES) {
-    result = result.replace(pattern, replacement);
-  }
+  let result = applyAcronymFixes(toPascalCase(stripUrnPrefix(name)));
   if (PHP_RESERVED_CLASS_NAMES.has(result)) {
     result += 'Model';
   }