@workos/oagen-emitters 0.2.0 → 0.3.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

@@ -5,7 +5,7 @@ import {
   fieldName,
   wireFieldName,
   fileName,
-  serviceDirName,
+  resolveServiceDir,
   servicePropertyName,
   resolveMethodName,
   resolveInterfaceName,
@@ -15,12 +15,12 @@ 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[] = [];
@@ -28,21 +28,38 @@ export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
   // Generate fixture JSON files
   const fixtures = generateFixtures(spec, ctx);
   for (const f of fixtures) {
-    files.push({ path: f.path, content: f.content, headerPlacement: 'skip' });
+    files.push({ path: f.path, content: f.content, headerPlacement: 'skip', integrateTarget: false });
   }
 
   // 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 +76,12 @@ function generateServiceTest(
   spec: ApiSpec,
   ctx: EmitterContext,
   modelMap: Map<string, Model>,
+  mountAccessors?: Map<string, string>,
 ): GeneratedFile {
   const resolvedName = resolveResourceClassName(service, ctx);
-  const serviceDir = serviceDirName(resolvedName);
+  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) => ({
@@ -510,8 +528,9 @@ function buildCallArgs(op: Operation, plan: any, modelMap: Map<string, Model>):
 
   if (isPaginated) return pathArgs || '';
   if (hasBody) {
-    const fb = fallbackBodyArg(op, modelMap);
-    return pathArgs ? `${pathArgs}, ${fb}` : fb;
+    const payload = buildTestPayload(op, modelMap);
+    const bodyArg = payload ? payload.camelCaseObj : fallbackBodyArg(op, modelMap);
+    return pathArgs ? `${pathArgs}, ${bodyArg}` : bodyArg;
   }
   return pathArgs || '';
 }
@@ -626,10 +645,18 @@ function buildFieldAssertions(model: Model, accessor: string, modelMap?: Map<str
 }
 
 /**
- * Return a JS literal string for the expected fixture value of a primitive field.
- * Returns null for non-primitive or complex types (arrays, models, etc.).
+ * Return a JS literal string for the expected fixture value of a field.
+ * Returns null for types that cannot be deterministically generated.
+ * When a modelMap is provided, recursively builds object literals for nested model types.
+ * When wire is true, uses snake_case keys for nested model objects (wire format).
  */
-function fixtureValueForType(ref: TypeRef, name: string, modelName: string): string | null {
+function fixtureValueForType(
+  ref: TypeRef,
+  name: string,
+  modelName: string,
+  modelMap?: Map<string, Model>,
+  wire?: boolean,
+): string | null {
   switch (ref.kind) {
     case 'primitive':
       return fixtureValueForPrimitive(ref.type, ref.format, name, modelName);
@@ -646,10 +673,24 @@ function fixtureValueForType(ref: TypeRef, name: string, modelName: string): str
       // For arrays of primitives/enums, generate a single-element array assertion.
       // For arrays of models/complex types, return null to skip the assertion —
       // the fixture will have populated items that we can't predict here.
-      const itemValue = fixtureValueForType(ref.items, name, modelName);
+      const itemValue = fixtureValueForType(ref.items, name, modelName, modelMap, wire);
       if (itemValue !== null) return `[${itemValue}]`;
       return null;
     }
+    case 'model': {
+      if (!modelMap) return null;
+      const nested = modelMap.get(ref.name);
+      if (!nested) return null;
+      const requiredFields = nested.fields.filter((f) => f.required);
+      const entries: string[] = [];
+      for (const field of requiredFields) {
+        const value = fixtureValueForType(field.type, field.name, nested.name, modelMap, wire);
+        if (value === null) return null; // Can't build a complete object
+        const key = wire ? wireFieldName(field.name) : fieldName(field.name);
+        entries.push(`${key}: ${value}`);
+      }
+      return `{ ${entries.join(', ')} }`;
+    }
     default:
       return null;
   }
@@ -716,8 +757,8 @@ function buildTestPayload(
   if (!model) return null;
 
   const fields = model.fields.filter((f) => f.required);
-  // Only use primitive/literal/enum/array fields that we can generate deterministic values for
-  const usableFields = fields.filter((f) => fixtureValueForType(f.type, f.name, model.name) !== null);
+  // Only use fields that we can generate deterministic values for (primitives, enums, and nested models)
+  const usableFields = fields.filter((f) => fixtureValueForType(f.type, f.name, model.name, modelMap) !== null);
 
   // Only generate a typed payload when ALL required fields have fixture values.
   // A partial payload missing required fields would fail TypeScript type checking.
@@ -727,11 +768,12 @@ function buildTestPayload(
   const snakeEntries: string[] = [];
 
   for (const field of usableFields) {
-    const value = fixtureValueForType(field.type, field.name, model.name)!;
+    const camelValue = fixtureValueForType(field.type, field.name, model.name, modelMap)!;
+    const wireValue = fixtureValueForType(field.type, field.name, model.name, modelMap, true)!;
     const camelKey = fieldName(field.name);
     const snakeKey = wireFieldName(field.name);
-    camelEntries.push(`${camelKey}: ${value}`);
-    snakeEntries.push(`${snakeKey}: ${value}`);
+    camelEntries.push(`${camelKey}: ${camelValue}`);
+    snakeEntries.push(`${snakeKey}: ${wireValue}`);
   }
 
   return {
@@ -775,7 +817,7 @@ function generateSerializerTests(spec: ApiSpec, ctx: EmitterContext): GeneratedF
     serviceNameMap.set(service.name, resolveResourceClassName(service, ctx));
   }
   const resolveDir = (irService: string | undefined) =>
-    irService ? serviceDirName(serviceNameMap.get(irService) ?? irService) : 'common';
+    irService ? resolveServiceDir(serviceNameMap.get(irService) ?? irService) : 'common';
 
   // Only generate round-trip tests for models with fields that have serializers generated.
   // Skip list metadata and list wrapper models since their serializers are not emitted.
@@ -814,7 +856,8 @@ function generateSerializerTests(spec: ApiSpec, ctx: EmitterContext): GeneratedF
       serializerImports.push(
         `import { deserialize${domainName}, serialize${domainName} } from '${relativeImport(testPath, serializerPath)}';`,
       );
-      fixtureImports.push(`import ${toCamelCase(model.name)}Fixture from '${relativeImport(testPath, fixturePath)}';`);
+      const camelName = domainName.charAt(0).toLowerCase() + domainName.slice(1);
+      fixtureImports.push(`import ${camelName}Fixture from '${relativeImport(testPath, fixturePath)}';`);
     }
 
     for (const imp of serializerImports) {
@@ -827,7 +870,8 @@ 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`;
 
       lines.push(`describe('${domainName}Serializer', () => {`);
       lines.push("  it('round-trips through serialize/deserialize', () => {");

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,5 @@
-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,
   collectEnumRefs,
@@ -7,7 +8,14 @@ export {
   collectRequestBodyModels,
 } from '@workos/oagen';
 import { mapTypeRef } from './type-map.js';
-import { resolveInterfaceName, fieldName, serviceDirName, buildServiceNameMap } from './naming.js';
+import {
+  resolveInterfaceName,
+  fieldName,
+  resolveServiceDir,
+  resolveMethodName,
+  buildServiceNameMap,
+} from './naming.js';
+import { getMountTarget } from '../shared/resolved-ops.js';
 import { assignModelsToServices } from '@workos/oagen';
 
 /**
@@ -218,7 +226,7 @@ export function createServiceDirResolver(
   const modelToService = assignModelsToServices(models, services);
   const serviceNameMap = buildServiceNameMap(services, ctx);
   const resolveDir = (irService: string | undefined) =>
-    irService ? serviceDirName(serviceNameMap.get(irService) ?? irService) : 'common';
+    irService ? resolveServiceDir(serviceNameMap.get(irService) ?? irService) : 'common';
   return { modelToService, serviceNameMap, resolveDir };
 }
 
@@ -240,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.
@@ -384,6 +333,11 @@ export function buildDeduplicationMap(models: Model[], ctx?: EmitterContext): Ma
  * endpoints (e.g., `GET /connections`).
  */
 export function isServiceCoveredByExisting(service: Service, ctx: EmitterContext): boolean {
+  // 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;
   if (service.operations.length === 0) return false;
@@ -405,6 +359,44 @@ export function isServiceCoveredByExisting(service: Service, ctx: EmitterContext
   });
 }
 
+/**
+ * Check whether a fully-covered service has operations whose overlay-mapped
+ * methods are missing from the baseline class.  Returns true when at least
+ * one operation maps to a method name that the baseline class does not have,
+ * meaning the merger needs to add new methods (skipIfExists must be removed).
+ */
+export function hasMethodsAbsentFromBaseline(service: Service, ctx: EmitterContext): boolean {
+  const baselineClasses = ctx.apiSurface?.classes;
+  if (!baselineClasses) return false;
+
+  // 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);
+      if (!cls.methods?.[method]) return true;
+    }
+    return false;
+  }
+
+  // Default overlay-based detection
+  const overlay = ctx.overlayLookup?.methodByOperation;
+  if (!overlay) return false;
+
+  for (const op of service.operations) {
+    const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
+    const match = overlay.get(httpKey);
+    if (!match) continue;
+    const cls = baselineClasses[match.className];
+    if (!cls) continue;
+    if (!cls.methods?.[match.methodName]) return true;
+  }
+  return false;
+}
+
 /**
  * Return operations in a service that are NOT covered by existing hand-written
  * service classes. For fully uncovered services, returns all operations.

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)}`;
+  }
+}