@workos/oagen-emitters 0.12.1 → 0.12.3

package/src/node/naming.ts

@@ -34,11 +34,69 @@ export function wireFieldName(name: string): string {
 }
 
 /**
- * Wire/response interface name. Uses "Wire" suffix when the domain name
- * already ends in "Response" to avoid stuttering (e.g., FooResponseResponse).
+ * Active set of `Serialized${Name}` interfaces in the live SDK, harvested
+ * from `ctx.apiSurface` once per generation run. When non-empty, the
+ * legacy wire-naming scheme wins so existing hand-written serializer files
+ * continue to compile.
+ *
+ * Set by `index.ts` immediately after `getSurface(ctx)` runs.
+ */
+let baselineSerializedNames: Set<string> = new Set();
+export function setBaselineSerializedNames(names: Set<string>): void {
+  baselineSerializedNames = names;
+}
+
+/**
+ * Set of every interface name present in the baseline live SDK, regardless
+ * of naming convention. Used to detect single-form baselines (where one
+ * `*Response`-suffixed interface stands for both the domain and wire shape)
+ * so we don't synthesize a non-existent `*Wire` variant.
+ */
+let baselineInterfaceNames: Set<string> = new Set();
+export function setBaselineInterfaceNames(names: Set<string>): void {
+  baselineInterfaceNames = names;
+}
+
+/**
+ * IR models that belong to newly-adopted services should not be renamed by
+ * structural baseline matches from unrelated hand-written services.
+ */
+let adoptedModelNames: Set<string> = new Set();
+export function setAdoptedModelNames(names: Set<string>): void {
+  adoptedModelNames = names;
+}
+export function isAdoptedModelName(name: string): boolean {
+  return adoptedModelNames.has(name);
+}
+
+/**
+ * Wire/response interface name.
+ *
+ * Resolution order:
+ *  1. `Serialized${domainName}` if it exists in the baseline (legacy
+ *     workos-node convention; lets hand-written serializer files keep
+ *     compiling).
+ *  2. `${domainName}Wire` when the domain ends in `Response` AND the
+ *     baseline actually has a `*Wire` interface (avoids
+ *     `FooResponseResponse` stutter).
+ *  3. The bare `domainName` itself when it already ends in `Response` and
+ *     no `*Wire` variant exists — this happens when the structural matcher
+ *     maps an IR model to a baseline-wire-shaped interface
+ *     (`AuditLogSchemaJson` → `AuditLogSchemaResponse`) and the baseline
+ *     has no separate domain/wire split.
+ *  4. `${domainName}Response` for the standard fresh-emit case.
  */
 export function wireInterfaceName(domainName: string): string {
-  return domainName.endsWith('Response') ? `${domainName}Wire` : `${domainName}Response`;
+  const serialized = `Serialized${domainName}`;
+  if (baselineSerializedNames.has(serialized)) return serialized;
+
+  if (domainName.endsWith('Response')) {
+    const wireForm = `${domainName}Wire`;
+    if (baselineInterfaceNames.has(wireForm)) return wireForm;
+    if (baselineInterfaceNames.has(domainName)) return domainName;
+    return wireForm;
+  }
+  return `${domainName}Response`;
 }
 
 /** kebab-case service directory name. */
@@ -53,17 +111,14 @@ export function servicePropertyName(name: string): string {
 
 /**
  * Resolve the effective service name, using the overlay-resolved class name
- * when available. This ensures directory names, file names, and property names
- * all derive from the same resolved name (e.g., "Mfa" instead of "MultiFactorAuth").
+ * when available.
  */
 export function resolveServiceName(service: Service, ctx: EmitterContext): string {
   return resolveClassName(service, ctx);
 }
 
 /**
- * Build a map from IR service name → resolved service name.
- * Used to translate modelToService/enumToService map values to overlay-resolved
- * directory names when the code only has the IR service name string.
+ * Build a map from IR service name -> resolved service name.
  */
 export function buildServiceNameMap(services: Service[], ctx: EmitterContext): Map<string, string> {
   const map = new Map<string, string>();
@@ -73,10 +128,7 @@ export function buildServiceNameMap(services: Service[], ctx: EmitterContext): M
   return map;
 }
 
-/**
- * Resolve the output directory for a service.
- * Mount rules already handle directory placement, so this is a simple kebab-case conversion.
- */
+/** Resolve the output directory for a service. */
 export function resolveServiceDir(resolvedServiceName: string): string {
   return serviceDirName(resolvedServiceName);
 }
@@ -86,7 +138,6 @@ export function resolveMethodName(op: Operation, _service: Service, ctx: Emitter
   const lookup = buildResolvedLookup(ctx);
   const resolved = lookupMethodName(op, lookup);
   if (resolved) return toCamelCase(resolved);
-  // Fallback to overlay, then spec-derived
   const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
   const existing = ctx.overlayLookup?.methodByOperation?.get(httpKey);
   if (existing) return existing.methodName;
@@ -95,11 +146,9 @@ export function resolveMethodName(op: Operation, _service: Service, ctx: Emitter
 
 /** Resolve the SDK class name for a service, using resolved ops mountOn as canonical. */
 export function resolveClassName(service: Service, ctx: EmitterContext): string {
-  // Use resolved ops mountOn as canonical class name
   for (const r of ctx.resolvedOperations ?? []) {
     if (r.service.name === service.name) return r.mountOn;
   }
-  // Fallback to overlay
   if (ctx.overlayLookup?.methodByOperation) {
     for (const op of service.operations) {
       const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
@@ -110,19 +159,48 @@ export function resolveClassName(service: Service, ctx: EmitterContext): string
   return toPascalCase(service.name);
 }
 
-/** Resolve the interface name for a model, checking overlay first.
+/**
+ * Resolve the interface name for a model, checking overlay first.
  *
- * @param opts.skipTypeAlias - When true, skip apiSurface typeAlias resolution.
- *   Use this for dedup models to ensure the file exports match the import
- *   names (preserved files export the raw name, not the resolved alias).
+ * Lookup order:
+ *  1. `overlayLookup.interfaceByName` — exact-name overrides from the live SDK.
+ *  2. `overlayLookup.modelNameByIR` — structurally-inferred matches (e.g., IR
+ *     `ValidateApiKey` with one field `value: string` → live SDK interface
+ *     `ValidateApiKeyOptions`).
+ *  3. Type-alias resolution (when an alias points to an interface).
+ *  4. Suffix-fallback heuristic for the workos-node `*Options` convention:
+ *     when the IR name `X` has no baseline match but `XOptions` does, use
+ *     `XOptions`. The convention is widely used for request-body interfaces
+ *     in workos-node (CreateOrganizationOptions, ListUsersOptions, etc.).
+ *  5. Default — clean and PascalCase the IR name.
  */
 export function resolveInterfaceName(name: string, ctx: EmitterContext, opts?: { skipTypeAlias?: boolean }): string {
   const existing = ctx.overlayLookup?.interfaceByName?.get(name);
   if (existing) return existing;
 
-  // If the model name is a type alias that points to a canonical interface,
-  // use the canonical name.  This prevents the merger from generating unused
-  // backward-compat aliases (e.g., `type FlagOwner = FeatureFlagOwner`).
+  let inferred = adoptedModelNames.has(name) ? undefined : ctx.overlayLookup?.modelNameByIR?.get(name);
+  if (inferred) {
+    if (inferred.startsWith('Serialized')) {
+      const stripped = inferred.slice('Serialized'.length);
+      if (stripped && ctx.apiSurface?.interfaces?.[stripped]) {
+        inferred = stripped;
+      }
+    }
+    // Structural matchers tend to lock onto the wire-shaped baseline
+    // interface (`AuditLogSchemaResponse`) because the IR carries
+    // snake_case fields. Prefer the corresponding domain name (without
+    // the `Response` suffix) when both exist in baseline — domain refs
+    // belong on the domain side, the wire/serialize path picks up the
+    // `*Response` variant via `wireInterfaceName`.
+    if (inferred.endsWith('Response') && ctx.apiSurface?.interfaces) {
+      const stripped = inferred.slice(0, -'Response'.length);
+      if (stripped && ctx.apiSurface.interfaces[stripped]) {
+        inferred = stripped;
+      }
+    }
+    return inferred;
+  }
+
   if (!opts?.skipTypeAlias && ctx.apiSurface?.typeAliases) {
     const alias = ctx.apiSurface.typeAliases[name] as { value?: string } | undefined;
     if (alias?.value && ctx.apiSurface.interfaces?.[alias.value]) {
@@ -130,9 +208,28 @@ export function resolveInterfaceName(name: string, ctx: EmitterContext, opts?: {
     }
   }
 
-  // Strip spec-noise suffixes (e.g., "Dto") only for models without a
-  // baseline.  When an overlay exists (Scenario A), the overlay check above
-  // handles existing models.  New models (no overlay entry) get clean names.
+  // Suffix-fallback for the workos-node `*Options` convention, restricted to
+  // the case where the baseline `${name}Options` interface lives in the file
+  // we'd compute from the IR name itself (e.g. `validate-api-key.interface.ts`
+  // exports `ValidateApiKeyOptions`). Without this restriction, we'd re-point
+  // every IR name with an `*Options` baseline to a different file (e.g.
+  // `CreateOrganizationApiKey` → `…Options` lives in
+  // `create-organization-api-key-options.interface.ts`, NOT
+  // `create-organization-api-key.interface.ts`).
+  if (ctx.apiSurface?.interfaces) {
+    const ifaces = ctx.apiSurface.interfaces;
+    if (!ifaces[name]) {
+      const optionsCandidate = `${name}Options`;
+      const optionsInfo = ifaces[optionsCandidate] as { sourceFile?: string } | undefined;
+      if (optionsInfo?.sourceFile) {
+        const expectedStem = toKebabCase(stripUrnPrefix(name));
+        if (optionsInfo.sourceFile.endsWith(`/${expectedStem}.interface.ts`)) {
+          return optionsCandidate;
+        }
+      }
+    }
+  }
+
   const cleaned = ctx.apiSurface ? name : stripNoiseSuffixes(name);
   return toPascalCase(stripUrnPrefix(cleaned));
 }

package/src/node/node-overrides.ts

@@ -0,0 +1,77 @@
+import type { EmitterContext, ResolvedOperation } from '@workos/oagen';
+
+type OperationOverride = {
+  methodName?: string;
+  mountOn?: string;
+};
+
+const OPERATION_OVERRIDES: Record<string, OperationOverride> = {
+  'POST /organizations/{organizationId}/groups': {
+    methodName: 'create_group',
+  },
+  'GET /organizations/{organizationId}/groups': {
+    methodName: 'list_groups',
+  },
+  'GET /organizations/{organizationId}/groups/{groupId}': {
+    methodName: 'get_group',
+  },
+  'PATCH /organizations/{organizationId}/groups/{groupId}': {
+    methodName: 'update_group',
+  },
+  'DELETE /organizations/{organizationId}/groups/{groupId}': {
+    methodName: 'delete_group',
+  },
+  'POST /organizations/{organizationId}/groups/{groupId}/organization-memberships': {
+    methodName: 'add_organization_membership',
+  },
+  'GET /organizations/{organizationId}/groups/{groupId}/organization-memberships': {
+    methodName: 'list_organization_memberships',
+  },
+  'DELETE /organizations/{organizationId}/groups/{groupId}/organization-memberships/{omId}': {
+    methodName: 'remove_organization_membership',
+  },
+  'GET /user_management/organization_memberships/{omId}/groups': {
+    methodName: 'list_groups_for_organization_membership',
+    mountOn: 'UserManagement',
+  },
+};
+
+const contextCache = new WeakMap<EmitterContext, EmitterContext>();
+
+function operationKey(resolved: ResolvedOperation): string {
+  return `${resolved.operation.httpMethod.toUpperCase()} ${resolved.operation.path}`;
+}
+
+export function withNodeOperationOverrides(ctx: EmitterContext): EmitterContext {
+  const cached = contextCache.get(ctx);
+  if (cached) return cached;
+
+  const resolvedOperations = ctx.resolvedOperations;
+  if (!resolvedOperations?.length) {
+    contextCache.set(ctx, ctx);
+    return ctx;
+  }
+
+  let changed = false;
+  const nextResolved = resolvedOperations.map((resolved) => {
+    const override = OPERATION_OVERRIDES[operationKey(resolved)];
+    if (!override) return resolved;
+
+    const methodName = override.methodName ?? resolved.methodName;
+    const mountOn = override.mountOn ?? resolved.mountOn;
+    if (methodName === resolved.methodName && mountOn === resolved.mountOn) {
+      return resolved;
+    }
+
+    changed = true;
+    return {
+      ...resolved,
+      methodName,
+      mountOn,
+    };
+  });
+
+  const next = changed ? { ...ctx, resolvedOperations: nextResolved } : ctx;
+  contextCache.set(ctx, next);
+  return next;
+}

package/src/node/options.ts

@@ -0,0 +1,41 @@
+import type { EmitterContext } from '@workos/oagen';
+
+export interface NodeEmitterOptions {
+  /**
+   * Existing SDK mode normally drops brand-new paths to avoid large accidental
+   * generations. When enabled, brand-new top-level service directories whose
+   * services are absent from the SDK are adopted from the spec.
+   */
+  adoptMissingServices?: boolean;
+  /**
+   * Existing tracked service directories to move under oagen ownership.
+   *
+   * Entries may be IR service names or resolved resource class names
+   * (for example, "Groups"). Owned service files are allowed to overwrite
+   * tracked, non-autogenerated files so the service can be migrated into the
+   * manifest one service at a time.
+   */
+  ownedServices?: string[];
+  /**
+   * Regenerate tests and fixtures for owned services. Non-owned service tests
+   * and fixtures remain hand-owned.
+   */
+  regenerateOwnedTests?: boolean;
+}
+
+export function nodeOptions(ctx: EmitterContext): NodeEmitterOptions {
+  return ((ctx as EmitterContext & { emitterOptions?: Record<string, unknown> }).emitterOptions ??
+    {}) as NodeEmitterOptions;
+}
+
+function normalizeServiceName(name: string): string {
+  return name.replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+}
+
+export function isNodeOwnedService(ctx: EmitterContext, ...names: Array<string | undefined>): boolean {
+  const configured = nodeOptions(ctx).ownedServices ?? [];
+  if (configured.length === 0) return false;
+
+  const owned = new Set(configured.map(normalizeServiceName));
+  return names.some((name) => name !== undefined && owned.has(normalizeServiceName(name)));
+}

package/src/node/path-expression.ts

@@ -14,8 +14,14 @@ import { fieldName } from './naming.js';
  *   "/orgs"            → `'orgs'`
  *   "/orgs/{id}"       → `` `orgs/${encodeURIComponent(id)}` ``
  *   "/orgs/{id}/foo"   → `` `orgs/${encodeURIComponent(id)}/foo` ``
+ *
+ * `paramNameMap` lets a caller override the local variable name used for a
+ * spec parameter — used by the options-object code path so the URL template
+ * references the SDK's public field name (e.g. `organizationMembershipId`)
+ * instead of the spec's path-param name (e.g. `omId`), avoiding a
+ * destructure rename in the method body.
  */
-export function buildNodePathExpression(rawPath: string): string {
+export function buildNodePathExpression(rawPath: string, paramNameMap?: Map<string, string>): string {
   const segments = parsePathTemplate(rawPath);
   if (!hasPathParams(segments)) {
     return `'${rawPath}'`;
@@ -23,15 +29,16 @@ export function buildNodePathExpression(rawPath: string): string {
 
   let body = '';
   for (const seg of segments) {
-    body += renderSegment(seg);
+    body += renderSegment(seg, paramNameMap);
   }
   return `\`${body}\``;
 }
 
-function renderSegment(seg: PathSegment): string {
+function renderSegment(seg: PathSegment, paramNameMap?: Map<string, string>): string {
   if (seg.kind === 'literal') {
     // Template-literal-safe escapes: backtick, backslash, ${
     return seg.value.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
   }
-  return `\${encodeURIComponent(${fieldName(seg.name)})}`;
+  const localName = paramNameMap?.get(seg.name) ?? fieldName(seg.name);
+  return `\${encodeURIComponent(${localName})}`;
 }