@workos/oagen-emitters 0.2.1 → 0.4.0

package/src/node/sdk-errors.ts

@@ -0,0 +1,41 @@
+import type { SdkBehavior } from '@workos/oagen';
+
+/**
+ * Node-specific overrides for exception kind names.
+ *
+ * The IR `statusCodeMap` uses canonical kind names (e.g. 'Authentication'),
+ * but the Node SDK historically uses different names for some status codes.
+ * This map translates the IR kind name to the Node-specific name before
+ * appending the 'Exception' suffix.
+ */
+const NODE_EXCEPTION_KIND_OVERRIDES: Record<string, string> = {
+  Authentication: 'Unauthorized',
+};
+
+/** Fallback status code map when no SDK behavior is provided. */
+const DEFAULT_STATUS_CODE_MAP: Record<string, string> = {
+  '400': 'BadRequest',
+  '401': 'Authentication',
+  '403': 'Authorization',
+  '404': 'NotFound',
+  '409': 'Conflict',
+  '422': 'UnprocessableEntity',
+  '429': 'RateLimitExceeded',
+};
+
+/**
+ * Build the status-code-to-exception-class-name map from SDK behavior,
+ * applying Node-specific naming overrides.
+ *
+ * Example: IR `401: 'Authentication'` becomes `401: 'UnauthorizedException'`
+ * because Node uses `UnauthorizedException` instead of `AuthenticationException`.
+ */
+export function buildNodeStatusExceptions(sdk?: SdkBehavior): Record<number, string> {
+  const statusCodeMap = sdk?.errors?.statusCodeMap ?? DEFAULT_STATUS_CODE_MAP;
+  return Object.fromEntries(
+    Object.entries(statusCodeMap).map(([code, kind]) => {
+      const nodeKind = NODE_EXCEPTION_KIND_OVERRIDES[kind] ?? kind;
+      return [Number(code), `${nodeKind}Exception`];
+    }),
+  );
+}

package/src/node/tests.ts

@@ -9,18 +9,19 @@ import {
   servicePropertyName,
   resolveMethodName,
   resolveInterfaceName,
+  wireInterfaceName,
 } from './naming.js';
 import { generateFixtures } from './fixtures.js';
 import { resolveResourceClassName } from './resources.js';
 import {
   assignModelsToServices,
   createServiceDirResolver,
-  isServiceCoveredByExisting,
   uncoveredOperations,
   relativeImport,
   isListMetadataModel,
   isListWrapperModel,
 } from './utils.js';
+import { groupByMount } from '../shared/resolved-ops.js';
 
 export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
   const files: GeneratedFile[] = [];
@@ -34,15 +35,32 @@ export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
   // Build model lookup for response field assertions
   const modelMap = new Map(spec.models.map((m) => [m.name, m]));
 
-  // Generate test files per service — skip services whose endpoints are fully
-  // covered by existing hand-written service classes. For partially covered
-  // services, generate tests only for uncovered operations.
-  for (const service of spec.services) {
-    if (isServiceCoveredByExisting(service, ctx)) continue;
-    const ops = uncoveredOperations(service, ctx);
+  // Generate test files per mount target — merges all sub-services into one
+  // test file. Skip operations already covered by existing hand-written classes.
+  const mountGroups = groupByMount(ctx);
+
+  // Build mount-target → property name map so tests use the same accessor
+  // as the generated client, even when the mount target name doesn't match
+  // any IR service name directly.
+  const mountAccessors = new Map<string, string>();
+  for (const r of ctx.resolvedOperations ?? []) {
+    if (!mountAccessors.has(r.mountOn)) {
+      mountAccessors.set(r.mountOn, servicePropertyName(r.mountOn));
+    }
+  }
+
+  const testEntries: Array<{ name: string; operations: Operation[] }> =
+    mountGroups.size > 0
+      ? [...mountGroups].map(([name, group]) => ({ name, operations: group.operations }))
+      : spec.services.map((s) => ({ name: resolveResourceClassName(s, ctx), operations: s.operations }));
+
+  for (const { name: mountName, operations } of testEntries) {
+    if (operations.length === 0) continue;
+    const mergedService: Service = { name: mountName, operations };
+    const ops = uncoveredOperations(mergedService, ctx);
     if (ops.length === 0) continue;
-    const testService = ops.length < service.operations.length ? { ...service, operations: ops } : service;
-    files.push(generateServiceTest(testService, spec, ctx, modelMap));
+    const testService = ops.length < operations.length ? { ...mergedService, operations: ops } : mergedService;
+    files.push(generateServiceTest(testService, spec, ctx, modelMap, mountAccessors));
   }
 
   // Generate serializer round-trip tests
@@ -59,11 +77,12 @@ function generateServiceTest(
   spec: ApiSpec,
   ctx: EmitterContext,
   modelMap: Map<string, Model>,
+  mountAccessors?: Map<string, string>,
 ): GeneratedFile {
   const resolvedName = resolveResourceClassName(service, ctx);
   const serviceDir = resolveServiceDir(resolvedName);
   const serviceClass = resolvedName;
-  const serviceProp = servicePropertyName(resolvedName);
+  const serviceProp = mountAccessors?.get(service.name) ?? servicePropertyName(resolvedName);
   const testPath = `src/${serviceDir}/${fileName(resolvedName)}.spec.ts`;
 
   const plans = service.operations.map((op) => ({
@@ -733,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);
@@ -771,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' : '{}';
@@ -826,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) {
@@ -833,17 +871,24 @@ 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)}';`,
       );
-      fixtureImports.push(`import ${toCamelCase(model.name)}Fixture from '${relativeImport(testPath, fixturePath)}';`);
+      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)}';`);
     }
 
     for (const imp of serializerImports) {
       lines.push(imp);
     }
+    for (const imp of interfaceImports) {
+      lines.push(imp);
+    }
     for (const imp of fixtureImports) {
       lines.push(imp);
     }
@@ -851,11 +896,17 @@ function generateSerializerTests(spec: ApiSpec, ctx: EmitterContext): GeneratedF
 
     for (const model of models) {
       const domainName = resolveInterfaceName(model.name, ctx);
-      const fixtureName = `${toCamelCase(model.name)}Fixture`;
+      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));');
@@ -868,7 +919,6 @@ function generateSerializerTests(spec: ApiSpec, ctx: EmitterContext): GeneratedF
       path: testPath,
       content: lines.join('\n'),
       skipIfExists: true,
-      integrateTarget: false,
     });
   }
 

package/src/node/type-map.ts

@@ -122,10 +122,12 @@ function mapWirePrimitive(ref: PrimitiveType): string {
  * allOf unions use `&` (intersection), oneOf/anyOf/unspecified use `|` (union).
  */
 function joinUnionVariants(ref: UnionType, variants: string[]): string {
+  const unique = [...new Set(variants)];
   if (ref.compositionKind === 'allOf') {
-    return variants.join(' & ');
+    return unique.join(' & ');
   }
-  return variants.join(' | ');
+  if (unique.length === 1) return unique[0];
+  return unique.join(' | ');
 }
 
 /** Wrap union/intersection types in parentheses when used as array item type. */

package/src/node/utils.ts

@@ -1,4 +1,4 @@
-import type { Model, EmitterContext, Service, Operation, Field } from '@workos/oagen';
+import type { Model, EmitterContext, Service, Operation } from '@workos/oagen';
 import { toPascalCase } from '@workos/oagen';
 export {
   collectModelRefs,
@@ -14,8 +14,8 @@ import {
   resolveServiceDir,
   resolveMethodName,
   buildServiceNameMap,
-  SERVICE_COVERED_BY,
 } from './naming.js';
+import { getMountTarget } from '../shared/resolved-ops.js';
 import { assignModelsToServices } from '@workos/oagen';
 
 /**
@@ -248,67 +248,8 @@ export function isBaselineGeneric(fields: Record<string, unknown>, knownNames: S
   return false;
 }
 
-/**
- * Detect whether a model matches the standard list-metadata shape:
- * exactly 2 fields named `before` and `after`, both nullable string.
- *
- * These models are redundant because the SDK already has a shared
- * `ListMetadata` type in `src/common/utils/pagination.ts`.
- */
-export function isListMetadataModel(model: Model): boolean {
-  if (model.fields.length !== 2) return false;
-
-  const fieldsByName = new Map(model.fields.map((f) => [f.name, f]));
-  const before = fieldsByName.get('before');
-  const after = fieldsByName.get('after');
-
-  if (!before || !after) return false;
-
-  return isNullableString(before) && isNullableString(after);
-}
-
-/**
- * Detect whether a model is a list wrapper — the standard paginated
- * list envelope with `data` (array), `list_metadata`, and `object: 'list'`.
- *
- * These models are redundant because the SDK already has `List<T>` and
- * `ListResponse<T>` in `src/common/utils/pagination.ts`, and the shared
- * `deserializeList` handles deserialization.
- */
-export function isListWrapperModel(model: Model): boolean {
-  const fieldsByName = new Map(model.fields.map((f) => [f.name, f]));
-
-  // Must have a `data` field that is an array type
-  const dataField = fieldsByName.get('data');
-  if (!dataField) return false;
-  if (dataField.type.kind !== 'array') return false;
-
-  // Must have a `list_metadata` field (the IR uses snake_case names)
-  const listMetadataField = fieldsByName.get('list_metadata');
-  if (!listMetadataField) return false;
-
-  // Optionally has an `object` field with literal value 'list'
-  const objectField = fieldsByName.get('object');
-  if (objectField) {
-    if (objectField.type.kind !== 'literal' || objectField.type.value !== 'list') {
-      return false;
-    }
-  }
-
-  return true;
-}
-
-/** Check if a field type is nullable string (nullable<string> or just string). */
-function isNullableString(field: Field): boolean {
-  const { type } = field;
-  if (type.kind === 'nullable') {
-    return type.inner.kind === 'primitive' && type.inner.type === 'string';
-  }
-  if (type.kind === 'primitive') {
-    return type.type === 'string';
-  }
-  return false;
-}
+// Re-export shared model detection utilities
+export { isListMetadataModel, isListWrapperModel } from '../shared/model-utils.js';
 
 /**
  * Compute a structural fingerprint for a model based on its fields.
@@ -392,8 +333,10 @@ export function buildDeduplicationMap(models: Model[], ctx?: EmitterContext): Ma
  * endpoints (e.g., `GET /connections`).
  */
 export function isServiceCoveredByExisting(service: Service, ctx: EmitterContext): boolean {
-  // Explicit override: services known to be covered by existing hand-written classes
-  if (SERVICE_COVERED_BY[toPascalCase(service.name)]) return true;
+  // A service is "covered" when its mountOn differs from its own name,
+  // meaning its operations are mounted on a different (existing) class.
+  const mountTarget = getMountTarget(service, ctx);
+  if (mountTarget !== toPascalCase(service.name)) return true;
 
   const overlay = ctx.overlayLookup?.methodByOperation;
   if (!overlay || overlay.size === 0) return false;
@@ -426,12 +369,11 @@ export function hasMethodsAbsentFromBaseline(service: Service, ctx: EmitterConte
   const baselineClasses = ctx.apiSurface?.classes;
   if (!baselineClasses) return false;
 
-  // For services explicitly mapped to an existing class via SERVICE_COVERED_BY,
-  // check each operation's resolved method name against the target class directly.
-  // This avoids the overlay gap where new endpoints are silently skipped.
-  const targetClassName = SERVICE_COVERED_BY[toPascalCase(service.name)];
-  if (targetClassName) {
-    const cls = baselineClasses[targetClassName];
+  // When a service mounts on a different class (via mount rules), check
+  // each operation's resolved method name against the target class directly.
+  const mountTarget = getMountTarget(service, ctx);
+  if (mountTarget !== toPascalCase(service.name)) {
+    const cls = baselineClasses[mountTarget];
     if (!cls) return true; // Target class missing from baseline — treat as absent
     for (const op of service.operations) {
       const method = resolveMethodName(op, service, ctx);

package/src/node/wrappers.ts

@@ -0,0 +1,151 @@
+import type { EmitterContext, ResolvedOperation, ResolvedWrapper } from '@workos/oagen';
+import { toCamelCase } from '@workos/oagen';
+import { fieldName, resolveInterfaceName, wireInterfaceName } from './naming.js';
+import { mapTypeRef } from './type-map.js';
+import { resolveWrapperParams, formatWrapperDescription } from '../shared/wrapper-utils.js';
+
+/**
+ * Generate TypeScript wrapper method lines for union split operations.
+ *
+ * Each wrapper is a typed convenience method that:
+ * - Accepts only the exposed params (not the full union body)
+ * - Injects constant defaults (e.g., grant_type)
+ * - Reads inferred fields from client config (e.g., clientId)
+ * - Delegates to the HTTP client with the constructed body
+ */
+export function generateWrapperMethods(resolvedOp: ResolvedOperation, ctx: EmitterContext): string[] {
+  if (!resolvedOp.wrappers || resolvedOp.wrappers.length === 0) return [];
+
+  const lines: string[] = [];
+
+  for (const wrapper of resolvedOp.wrappers) {
+    lines.push('');
+    emitWrapperMethod(lines, resolvedOp, wrapper, ctx);
+  }
+
+  return lines;
+}
+
+/**
+ * Collect response model names referenced by wrappers on a resolved operation.
+ * Used by the resource generator to ensure the correct imports are emitted.
+ */
+export function collectWrapperResponseModels(resolvedOp: ResolvedOperation): Set<string> {
+  const models = new Set<string>();
+  for (const wrapper of resolvedOp.wrappers ?? []) {
+    if (wrapper.responseModelName) {
+      models.add(wrapper.responseModelName);
+    }
+  }
+  return models;
+}
+
+function emitWrapperMethod(
+  lines: string[],
+  resolvedOp: ResolvedOperation,
+  wrapper: ResolvedWrapper,
+  ctx: EmitterContext,
+): void {
+  const op = resolvedOp.operation;
+  const method = toCamelCase(wrapper.name);
+  const wrapperParams = resolveWrapperParams(wrapper, ctx);
+
+  // Build parameter list: path params, then required exposed, then optional exposed
+  const paramParts: string[] = [];
+
+  for (const p of op.pathParams) {
+    paramParts.push(`${fieldName(p.name)}: string`);
+  }
+
+  for (const { paramName, field, isOptional } of wrapperParams) {
+    if (isOptional) continue;
+    const tsName = fieldName(paramName);
+    const tsType = field ? mapTypeRef(field.type) : 'string';
+    paramParts.push(`${tsName}: ${tsType}`);
+  }
+
+  for (const { paramName, field, isOptional } of wrapperParams) {
+    if (!isOptional) continue;
+    const tsName = fieldName(paramName);
+    const tsType = field ? mapTypeRef(field.type) : 'string';
+    paramParts.push(`${tsName}?: ${tsType}`);
+  }
+
+  // Response type
+  const responseTypeName = wrapper.responseModelName ? resolveInterfaceName(wrapper.responseModelName, ctx) : null;
+  const wireType = responseTypeName ? wireInterfaceName(responseTypeName) : null;
+  const returnType = responseTypeName ?? 'void';
+
+  // JSDoc
+  lines.push(`  /** ${formatWrapperDescription(wrapper.name)}. */`);
+
+  // Method signature
+  lines.push(`  async ${method}(${paramParts.join(', ')}): Promise<${returnType}> {`);
+
+  // Build body with wire-format (snake_case) keys
+  lines.push('    const body: Record<string, unknown> = {');
+
+  // Constant defaults
+  for (const [key, value] of Object.entries(wrapper.defaults)) {
+    lines.push(`      ${key}: ${tsLiteral(value)},`);
+  }
+
+  // Inferred fields from client config
+  for (const field of wrapper.inferFromClient) {
+    const expr = clientFieldExpression(field);
+    lines.push(`      ${field}: ${expr},`);
+  }
+
+  // Required exposed params (wire-format key, camelCase value)
+  for (const { paramName, isOptional } of wrapperParams) {
+    if (isOptional) continue;
+    lines.push(`      ${paramName}: ${fieldName(paramName)},`);
+  }
+
+  lines.push('    };');
+
+  // Optional exposed params — add conditionally
+  for (const { paramName, isOptional } of wrapperParams) {
+    if (!isOptional) continue;
+    const tsName = fieldName(paramName);
+    lines.push(`    if (${tsName} !== undefined) body.${paramName} = ${tsName};`);
+  }
+
+  // Build path expression
+  const pathStr = buildPathStr(op);
+
+  // Make the request
+  if (responseTypeName) {
+    lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(${pathStr}, body);`);
+    lines.push(`    return deserialize${responseTypeName}(data);`);
+  } else {
+    lines.push(`    await this.workos.${op.httpMethod}(${pathStr}, body);`);
+  }
+
+  lines.push('  }');
+}
+
+/** Build a path template string from an Operation. */
+function buildPathStr(op: { path: string; pathParams: Array<{ name: string }> }): string {
+  const interpolated = op.path.replace(/\{(\w+)\}/g, (_, p) => `\${${fieldName(p)}}`);
+  return interpolated.includes('${') ? `\`${interpolated}\`` : `'${op.path}'`;
+}
+
+/** Convert a JS value to a TypeScript literal. */
+function tsLiteral(value: string | number | boolean): string {
+  if (typeof value === 'string') return `'${value.replace(/'/g, "\\'")}'`;
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  return String(value);
+}
+
+/** Get the TypeScript expression for reading a client config field. */
+function clientFieldExpression(field: string): string {
+  switch (field) {
+    case 'client_id':
+      return 'this.workos.options.clientId';
+    case 'client_secret':
+      return 'this.workos.key';
+    default:
+      return `this.workos.${toCamelCase(field)}`;
+  }
+}

package/src/php/client.ts

@@ -0,0 +1,179 @@
+import type { ApiSpec, Service, EmitterContext, GeneratedFile } from '@workos/oagen';
+import { toPascalCase, toCamelCase } from '@workos/oagen';
+import { className, servicePropertyName } from './naming.js';
+import { getMountTarget } from '../shared/resolved-ops.js';
+import { NON_SPEC_SERVICES } from '../shared/non-spec-services.js';
+
+/**
+ * PHP-specific class-name overrides for non-spec services.
+ * If a service id isn't listed here, PascalCase(id) is used.
+ */
+const PHP_NON_SPEC_CLASS_NAMES: Record<string, string> = {
+  webhook_verification: 'WebhookVerification',
+  session_manager: 'SessionManager',
+  pkce: 'PKCEHelper',
+};
+
+/** Derive PHP class name + property name from a non-spec service id. */
+function phpNonSpecAccessor(id: string): { className: string; propName: string } {
+  return {
+    className: PHP_NON_SPEC_CLASS_NAMES[id] ?? toPascalCase(id),
+    propName:
+      id === 'webhook_verification'
+        ? 'webhookVerification'
+        : id === 'session_manager'
+          ? 'sessionManager'
+          : toCamelCase(id),
+  };
+}
+
+/**
+ * Generate the main PHP client class (service wiring only).
+ *
+ * Static infrastructure (HttpClient, PaginatedResponse, RequestOptions) is
+ * now hand-maintained in the target SDK with @oagen-ignore-file.
+ */
+export function generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+  const ns = ctx.namespacePascal;
+  const dedupedServices = deduplicateByMount(spec.services, ctx);
+
+  return [
+    {
+      path: `lib/${ns}.php`,
+      content: generateMainClient(spec, dedupedServices, ctx),
+      overwriteExisting: true,
+    },
+  ];
+}
+
+/**
+ * Build a map from IR service name to the client accessor property name.
+ */
+export function buildServiceAccessPaths(services: Service[], ctx: EmitterContext): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const service of services) {
+    const target = getMountTarget(service, ctx);
+    map.set(service.name, servicePropertyName(target));
+    map.set(target, servicePropertyName(target));
+  }
+  return map;
+}
+
+function deduplicateByMount(services: Service[], ctx: EmitterContext): { name: string; propName: string }[] {
+  const seen = new Map<string, { name: string; propName: string }>();
+  for (const service of services) {
+    const target = getMountTarget(service, ctx);
+    if (!seen.has(target)) {
+      seen.set(target, {
+        name: className(target),
+        propName: servicePropertyName(target),
+      });
+    }
+  }
+  return [...seen.values()];
+}
+
+function generateMainClient(
+  spec: ApiSpec,
+  services: { name: string; propName: string }[],
+  ctx: EmitterContext,
+): string {
+  const ns = ctx.namespacePascal;
+  const lines: string[] = [];
+
+  // No <?php here — the file header from fileHeader() provides it
+  lines.push(`namespace ${ns};`);
+  lines.push('');
+
+  // Use imports (sorted case-insensitively for PSR-12)
+  const nonSpecAccessors = NON_SPEC_SERVICES.map((s) => phpNonSpecAccessor(s.id));
+  const allImports: string[] = [];
+  for (const svc of services) {
+    allImports.push(`use ${ns}\\Service\\${svc.name};`);
+  }
+  allImports.sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+  for (const imp of allImports) {
+    lines.push(imp);
+  }
+  lines.push('');
+
+  lines.push(`class ${ns}`);
+  lines.push('{');
+  lines.push('    private static ?string $apiKey = null;');
+  lines.push('    private static ?string $clientId = null;');
+  lines.push('    private ?HttpClient $httpClient = null;');
+  lines.push('');
+  lines.push('    public static function getApiKey(): ?string');
+  lines.push('    {');
+  lines.push('        return self::$apiKey;');
+  lines.push('    }');
+  lines.push('');
+  lines.push('    public static function setApiKey(?string $key): void');
+  lines.push('    {');
+  lines.push('        self::$apiKey = $key;');
+  lines.push('    }');
+  lines.push('');
+  lines.push('    public static function getClientId(): ?string');
+  lines.push('    {');
+  lines.push('        return self::$clientId;');
+  lines.push('    }');
+  lines.push('');
+  lines.push('    public static function setClientId(?string $id): void');
+  lines.push('    {');
+  lines.push('        self::$clientId = $id;');
+  lines.push('    }');
+
+  // Nullable resource properties
+  for (const svc of services) {
+    lines.push(`    private ?Service\\${svc.name} $${svc.propName} = null;`);
+  }
+  // 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(');
+  lines.push('        ?string $apiKey = null,');
+  lines.push('        ?string $clientId = null,');
+  lines.push(`        string $baseUrl = '${spec.baseUrl}',`);
+  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, $userAgent);',
+  );
+  lines.push('    }');
+
+  // Resource accessors
+  for (const svc of services) {
+    lines.push('');
+    lines.push(`    public function ${svc.propName}(): ${svc.name}`);
+    lines.push('    {');
+    lines.push(`        return $this->${svc.propName} ??= new Service\\${svc.name}($this->httpClient);`);
+    lines.push('    }');
+  }
+
+  // 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}`);
+    lines.push('    {');
+    lines.push(`        return $this->${a.propName} ??= new ${a.className}($this->httpClient);`);
+    lines.push('    }');
+  }
+  lines.push('    // @oagen-ignore-end');
+
+  lines.push('}');
+  return lines.join('\n');
+}