@workos/oagen-emitters 0.2.0 → 0.2.1

package/src/node/index.ts

@@ -1,4 +1,15 @@
-import type { Emitter, EmitterContext, GeneratedFile, ApiSpec, Model, Enum, Service } from '@workos/oagen';
+import type {
+  Emitter,
+  EmitterContext,
+  FormatCommand,
+  GeneratedFile,
+  ApiSpec,
+  Model,
+  Enum,
+  Service,
+} from '@workos/oagen';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 
 import { generateModels } from './models.js';
 import { generateEnums } from './enums.js';
@@ -11,31 +22,41 @@ import { generateCommon } from './common.js';
 import { generateTests } from './tests.js';
 import { generateManifest } from './manifest.js';
 
+/** Ensure every generated file's content ends with a trailing newline. */
+function ensureTrailingNewlines(files: GeneratedFile[]): GeneratedFile[] {
+  for (const f of files) {
+    if (f.content && !f.content.endsWith('\n')) {
+      f.content += '\n';
+    }
+  }
+  return files;
+}
+
 export const nodeEmitter: Emitter = {
   language: 'node',
 
   generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
-    return [...generateModels(models, ctx), ...generateSerializers(models, ctx)];
+    return ensureTrailingNewlines([...generateModels(models, ctx), ...generateSerializers(models, ctx)]);
   },
 
   generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
-    return generateEnums(enums, ctx);
+    return ensureTrailingNewlines(generateEnums(enums, ctx));
   },
 
   generateResources(services: Service[], ctx: EmitterContext): GeneratedFile[] {
-    return generateResources(services, ctx);
+    return ensureTrailingNewlines(generateResources(services, ctx));
   },
 
   generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
-    return generateClient(spec, ctx);
+    return ensureTrailingNewlines(generateClient(spec, ctx));
   },
 
   generateErrors(ctx: EmitterContext): GeneratedFile[] {
-    return generateErrors(ctx);
+    return ensureTrailingNewlines(generateErrors(ctx));
   },
 
   generateConfig(_ctx: EmitterContext): GeneratedFile[] {
-    return [...generateConfig(), ...generateCommon()];
+    return ensureTrailingNewlines([...generateConfig(), ...generateCommon()]);
   },
 
   generateTypeSignatures(_spec: ApiSpec, _ctx: EmitterContext): GeneratedFile[] {
@@ -44,14 +65,49 @@ export const nodeEmitter: Emitter = {
   },
 
   generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
-    return generateTests(spec, ctx);
+    return ensureTrailingNewlines(generateTests(spec, ctx));
   },
 
   generateManifest(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
-    return generateManifest(spec, ctx);
+    return ensureTrailingNewlines(generateManifest(spec, ctx));
   },
 
   fileHeader(): string {
     return '// This file is auto-generated by oagen. Do not edit.';
   },
+
+  formatCommand(targetDir: string): FormatCommand | null {
+    const hasPrettier = fs.existsSync(path.join(targetDir, '.prettierrc'));
+    const hasEslint =
+      fs.existsSync(path.join(targetDir, 'eslint.config.mjs')) ||
+      fs.existsSync(path.join(targetDir, 'eslint.config.js')) ||
+      fs.existsSync(path.join(targetDir, '.eslintrc.json')) ||
+      fs.existsSync(path.join(targetDir, '.eslintrc.js'));
+
+    if (hasPrettier && hasEslint) {
+      // Chain ESLint autofix (e.g. unused-import removal) then prettier.
+      // ESLint errors are suppressed so formatting still runs on lint failure.
+      return {
+        cmd: 'bash',
+        args: [
+          '-c',
+          'npx eslint --fix --no-error-on-unmatched-pattern "$@" 2>/dev/null; npx prettier --write --log-level silent "$@"',
+          '--',
+        ],
+      };
+    }
+    if (hasPrettier) {
+      return {
+        cmd: 'npx',
+        args: ['prettier', '--write', '--log-level', 'silent'],
+      };
+    }
+    if (hasEslint) {
+      return {
+        cmd: 'npx',
+        args: ['eslint', '--fix', '--no-error-on-unmatched-pattern'],
+      };
+    }
+    return null;
+  },
 };

package/src/node/models.ts

@@ -252,87 +252,98 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     if (model.description) {
       lines.push(...docComment(model.description));
     }
-    lines.push(`export interface ${domainName}${typeParams} {`);
-    for (const field of model.fields) {
-      const domainFieldName = fieldName(field.name);
-      if (seenDomainFields.has(domainFieldName)) continue;
-      seenDomainFields.add(domainFieldName);
-      if (field.description || field.deprecated || field.readOnly || field.writeOnly || field.default !== undefined) {
-        const parts: string[] = [];
-        if (field.description) parts.push(field.description);
-        if (field.readOnly) parts.push('@readonly');
-        if (field.writeOnly) parts.push('@writeonly');
-        if (field.default !== undefined) parts.push(`@default ${JSON.stringify(field.default)}`);
-        if (field.deprecated) parts.push('@deprecated');
-        lines.push(...docComment(parts.join('\n'), 2));
-      }
-      const baselineField = baselineDomain?.fields?.[domainFieldName];
-      // For the domain interface, also check that the response baseline's optionality
-      // is compatible — the serializer reads from the response type and assigns to the domain type.
-      // If the domain baseline says required but the response baseline says optional,
-      // the serializer would produce T | undefined for a field expecting T.
-      const domainWireField = wireFieldName(field.name);
-      const responseBaselineField = baselineResponse?.fields?.[domainWireField];
-      const domainResponseOptionalMismatch =
-        baselineField && !baselineField.optional && responseBaselineField && responseBaselineField.optional;
-      const readonlyPrefix = field.readOnly ? 'readonly ' : '';
-      if (
-        baselineField &&
-        !domainResponseOptionalMismatch &&
-        baselineTypeResolvable(baselineField.type, importableNames) &&
-        baselineFieldCompatible(baselineField, field)
-      ) {
-        const opt = baselineField.optional ? '?' : '';
-        lines.push(`  ${readonlyPrefix}${domainFieldName}${opt}: ${baselineField.type};`);
-      } else {
-        // When a baseline exists for this model, new fields (not present in the
-        // baseline) are generated as optional.  The merger can deep-merge new
-        // fields into existing interfaces, but it cannot update existing
-        // deserializer function bodies.  Making the field optional prevents a
-        // type error where the interface requires a field that the preserved
-        // deserializer never populates.
-        const isNewFieldOnExistingModel = baselineDomain && !baselineField;
-        // Also make the field optional when the response baseline has it as optional
-        // but the domain baseline has it as required — the deserializer reads from
-        // the response type, so if the response field is optional, the domain value
-        // may be undefined.
-        // Additionally, when a baseline exists for the RESPONSE interface but NOT the
-        // domain interface, fields that are new on the response baseline become optional
-        // in the wire type. The domain type must also be optional to match, otherwise
-        // the deserializer produces T | undefined for a field typed as T.
-        const isNewFieldOnExistingResponse = !baselineDomain && baselineResponse && !responseBaselineField;
-        const opt =
-          !field.required || isNewFieldOnExistingModel || domainResponseOptionalMismatch || isNewFieldOnExistingResponse
-            ? '?'
-            : '';
-        lines.push(`  ${readonlyPrefix}${domainFieldName}${opt}: ${mapTypeRef(field.type, modelTypeRefOpts)};`);
+    if (model.fields.length === 0) {
+      lines.push(`export type ${domainName}${typeParams} = object;`);
+    } else {
+      lines.push(`export interface ${domainName}${typeParams} {`);
+      for (const field of model.fields) {
+        const domainFieldName = fieldName(field.name);
+        if (seenDomainFields.has(domainFieldName)) continue;
+        seenDomainFields.add(domainFieldName);
+        if (field.description || field.deprecated || field.readOnly || field.writeOnly || field.default !== undefined) {
+          const parts: string[] = [];
+          if (field.description) parts.push(field.description);
+          if (field.readOnly) parts.push('@readonly');
+          if (field.writeOnly) parts.push('@writeonly');
+          if (field.default !== undefined) parts.push(`@default ${JSON.stringify(field.default)}`);
+          if (field.deprecated) parts.push('@deprecated');
+          lines.push(...docComment(parts.join('\n'), 2));
+        }
+        const baselineField = baselineDomain?.fields?.[domainFieldName];
+        // For the domain interface, also check that the response baseline's optionality
+        // is compatible — the serializer reads from the response type and assigns to the domain type.
+        // If the domain baseline says required but the response baseline says optional,
+        // the serializer would produce T | undefined for a field expecting T.
+        const domainWireField = wireFieldName(field.name);
+        const responseBaselineField = baselineResponse?.fields?.[domainWireField];
+        const domainResponseOptionalMismatch =
+          baselineField && !baselineField.optional && responseBaselineField && responseBaselineField.optional;
+        const readonlyPrefix = field.readOnly ? 'readonly ' : '';
+        if (
+          baselineField &&
+          !domainResponseOptionalMismatch &&
+          baselineTypeResolvable(baselineField.type, importableNames) &&
+          baselineFieldCompatible(baselineField, field)
+        ) {
+          const opt = baselineField.optional ? '?' : '';
+          lines.push(`  ${readonlyPrefix}${domainFieldName}${opt}: ${baselineField.type};`);
+        } else {
+          // When a baseline exists for this model, new fields (not present in the
+          // baseline) are generated as optional.  The merger can deep-merge new
+          // fields into existing interfaces, but it cannot update existing
+          // deserializer function bodies.  Making the field optional prevents a
+          // type error where the interface requires a field that the preserved
+          // deserializer never populates.
+          const isNewFieldOnExistingModel = baselineDomain && !baselineField;
+          // Also make the field optional when the response baseline has it as optional
+          // but the domain baseline has it as required — the deserializer reads from
+          // the response type, so if the response field is optional, the domain value
+          // may be undefined.
+          // Additionally, when a baseline exists for the RESPONSE interface but NOT the
+          // domain interface, fields that are new on the response baseline become optional
+          // in the wire type. The domain type must also be optional to match, otherwise
+          // the deserializer produces T | undefined for a field typed as T.
+          const isNewFieldOnExistingResponse = !baselineDomain && baselineResponse && !responseBaselineField;
+          const opt =
+            !field.required ||
+            isNewFieldOnExistingModel ||
+            domainResponseOptionalMismatch ||
+            isNewFieldOnExistingResponse
+              ? '?'
+              : '';
+          lines.push(`  ${readonlyPrefix}${domainFieldName}${opt}: ${mapTypeRef(field.type, modelTypeRefOpts)};`);
+        }
       }
-    }
-    lines.push('}');
+      lines.push('}');
+    } // close else for non-empty domain interface
     lines.push('');
 
     // Wire/response interface (snake_case fields) — deduplicate by snake_case name
     const seenWireFields = new Set<string>();
-    lines.push(`export interface ${responseName}${typeParams} {`);
-    for (const field of model.fields) {
-      const wireField = wireFieldName(field.name);
-      if (seenWireFields.has(wireField)) continue;
-      seenWireFields.add(wireField);
-      const baselineField = baselineResponse?.fields?.[wireField];
-      if (
-        baselineField &&
-        baselineTypeResolvable(baselineField.type, importableNames) &&
-        baselineFieldCompatible(baselineField, field)
-      ) {
-        const opt = baselineField.optional ? '?' : '';
-        lines.push(`  ${wireField}${opt}: ${baselineField.type};`);
-      } else {
-        const isNewFieldOnExistingModel = baselineResponse && !baselineField;
-        const opt = !field.required || isNewFieldOnExistingModel ? '?' : '';
-        lines.push(`  ${wireField}${opt}: ${mapWireTypeRef(field.type, modelWireTypeRefOpts)};`);
+    if (model.fields.length === 0) {
+      lines.push(`export type ${responseName}${typeParams} = object;`);
+    } else {
+      lines.push(`export interface ${responseName}${typeParams} {`);
+      for (const field of model.fields) {
+        const wireField = wireFieldName(field.name);
+        if (seenWireFields.has(wireField)) continue;
+        seenWireFields.add(wireField);
+        const baselineField = baselineResponse?.fields?.[wireField];
+        if (
+          baselineField &&
+          baselineTypeResolvable(baselineField.type, importableNames) &&
+          baselineFieldCompatible(baselineField, field)
+        ) {
+          const opt = baselineField.optional ? '?' : '';
+          lines.push(`  ${wireField}${opt}: ${baselineField.type};`);
+        } else {
+          const isNewFieldOnExistingModel = baselineResponse && !baselineField;
+          const opt = !field.required || isNewFieldOnExistingModel ? '?' : '';
+          lines.push(`  ${wireField}${opt}: ${mapWireTypeRef(field.type, modelWireTypeRefOpts)};`);
+        }
       }
-    }
-    lines.push('}');
+      lines.push('}');
+    } // close else for non-empty wire interface
 
     files.push({
       path: `src/${dirName}/interfaces/${fileName(model.name)}.interface.ts`,

package/src/node/naming.ts

@@ -66,9 +66,93 @@ export function buildServiceNameMap(services: Service[], ctx: EmitterContext): M
   return map;
 }
 
+/**
+ * Explicit method name overrides for operations where the spec's operationId
+ * does not match the desired SDK method name and the spec cannot be changed.
+ * Key: "HTTP_METHOD /path", Value: camelCase method name.
+ */
+const METHOD_NAME_OVERRIDES: Record<string, string> = {
+  'POST /portal/generate_link': 'generatePortalLink',
+};
+
+/**
+ * Explicit service directory overrides. Maps a resolved PascalCase service name
+ * to a target directory (kebab-case). Use this when the spec's tag grouping
+ * does not match the desired SDK directory layout and the spec cannot be changed.
+ */
+const SERVICE_DIR_OVERRIDES: Record<string, string> = {
+  ApplicationClientSecrets: 'workos-connect',
+  Applications: 'workos-connect',
+  Connections: 'sso',
+  Directories: 'directory-sync',
+  DirectoryGroups: 'directory-sync',
+  DirectoryUsers: 'directory-sync',
+  FeatureFlagsTargets: 'feature-flags',
+  MultiFactorAuth: 'mfa',
+  MultiFactorAuthChallenges: 'mfa',
+  OrganizationsApiKeys: 'organizations',
+  WebhooksEndpoints: 'webhooks',
+  UserManagementAuthentication: 'user-management',
+  UserManagementCorsOrigins: 'user-management',
+  UserManagementDataProviders: 'user-management',
+  UserManagementInvitations: 'user-management',
+  UserManagementJWTTemplate: 'user-management',
+  UserManagementMagicAuth: 'user-management',
+  UserManagementMultiFactorAuthentication: 'user-management',
+  UserManagementOrganizationMembership: 'user-management',
+  UserManagementRedirectUris: 'user-management',
+  UserManagementSessionTokens: 'user-management',
+  UserManagementUsers: 'user-management',
+  UserManagementUsersAuthorizedApplications: 'user-management',
+  WorkOSConnect: 'workos-connect',
+};
+
+/**
+ * Maps a service (by PascalCase name) to the existing hand-written class that
+ * already covers its endpoints. When a service appears here:
+ *   - `resolveClassName` returns the target class (so generated code merges in)
+ *   - `isServiceCoveredByExisting` returns true
+ *   - `hasMethodsAbsentFromBaseline` checks the target class for missing methods,
+ *     so new endpoints are added to the existing class rather than silently dropped
+ */
+export const SERVICE_COVERED_BY: Record<string, string> = {
+  Connections: 'SSO',
+  Directories: 'DirectorySync',
+  DirectoryGroups: 'DirectorySync',
+  DirectoryUsers: 'DirectorySync',
+  FeatureFlagsTargets: 'FeatureFlags',
+  MultiFactorAuth: 'Mfa',
+  MultiFactorAuthChallenges: 'Mfa',
+  OrganizationsApiKeys: 'Organizations',
+  UserManagementAuthentication: 'UserManagement',
+  UserManagementInvitations: 'UserManagement',
+  UserManagementMagicAuth: 'UserManagement',
+  UserManagementMultiFactorAuthentication: 'UserManagement',
+  UserManagementOrganizationMembership: 'UserManagement',
+  UserManagementUsers: 'UserManagement',
+};
+
+/**
+ * Explicit class name overrides. Maps the default PascalCase service name
+ * to the desired SDK class name when toPascalCase produces the wrong casing.
+ */
+const CLASS_NAME_OVERRIDES: Record<string, string> = {
+  WorkosConnect: 'WorkOSConnect',
+};
+
+/**
+ * Resolve the output directory for a service, checking overrides first.
+ * Falls back to the standard kebab-case conversion.
+ */
+export function resolveServiceDir(resolvedServiceName: string): string {
+  return SERVICE_DIR_OVERRIDES[resolvedServiceName] ?? serviceDirName(resolvedServiceName);
+}
+
 /** Resolve the SDK method name for an operation, checking overlay first. */
 export function resolveMethodName(op: Operation, _service: Service, ctx: EmitterContext): string {
   const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
+  const override = METHOD_NAME_OVERRIDES[httpKey];
+  if (override) return override;
   const existing = ctx.overlayLookup?.methodByOperation?.get(httpKey);
   if (existing) {
     // Fix: when the path ends with a path parameter (single-resource operation)
@@ -91,16 +175,21 @@ export function resolveMethodName(op: Operation, _service: Service, ctx: Emitter
 
 /** Resolve the SDK class name for a service, checking overlay for existing names. */
 export function resolveClassName(service: Service, ctx: EmitterContext): string {
+  // Explicit coverage: this service's endpoints belong to an existing class
+  const coveredBy = SERVICE_COVERED_BY[toPascalCase(service.name)];
+  if (coveredBy) return coveredBy;
+
   // Check overlay's methodByOperation for any operation in this service
   // to find the existing class name
   if (ctx.overlayLookup?.methodByOperation) {
     for (const op of service.operations) {
       const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
       const existing = ctx.overlayLookup.methodByOperation.get(httpKey);
-      if (existing) return existing.className;
+      if (existing) return CLASS_NAME_OVERRIDES[existing.className] ?? existing.className;
     }
   }
-  return toPascalCase(service.name);
+  const defaultName = toPascalCase(service.name);
+  return CLASS_NAME_OVERRIDES[defaultName] ?? defaultName;
 }
 
 /** Resolve the interface name for a model, checking overlay first. */