@workos/oagen-emitters 0.0.1 → 0.2.0

package/src/node/client.ts

@@ -1,20 +1,21 @@
-import type { ApiSpec, EmitterContext, GeneratedFile, Service } from '@workos/oagen';
+import type { ApiSpec, AuthScheme, EmitterContext, GeneratedFile, Service } from '@workos/oagen';
+import { fileName, serviceDirName, servicePropertyName, resolveInterfaceName, wireInterfaceName } from './naming.js';
 import {
-  fileName,
-  serviceDirName,
-  servicePropertyName,
-  resolveInterfaceName,
-  resolveServiceName,
-  buildServiceNameMap,
-  wireInterfaceName,
-} from './naming.js';
-import { assignModelsToServices } from './utils.js';
+  docComment,
+  createServiceDirResolver,
+  isServiceCoveredByExisting,
+  isListMetadataModel,
+  isListWrapperModel,
+} from './utils.js';
+import { resolveResourceClassName } from './resources.js';
 
 export function generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
   const files: GeneratedFile[] = [];
 
   files.push(generateWorkOSClient(spec, ctx));
+  files.push(...generateServiceBarrels(spec, ctx));
   files.push(generateBarrel(spec, ctx));
+  files.push(generateWorkerBarrel(spec, ctx));
   files.push(generatePackageJson(ctx));
   files.push(generateTsConfig());
 
@@ -24,202 +25,261 @@ export function generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFil
 function generateWorkOSClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile {
   const lines: string[] = [];
 
-  // Service imports
+  // Only import WorkOSBase for fresh generation (no existing WorkOS class).
+  // When integrating into an existing SDK, the existing WorkOS already has its
+  // own base class and the WorkOSBase file may not exist.
+  const hasExistingWorkOS = !!ctx.apiSurface?.classes?.['WorkOS'];
+  if (!hasExistingWorkOS) {
+    lines.push("import { WorkOSBase } from './common/workos-base';");
+  }
+
+  // Filter out services whose endpoints are already covered by existing
+  // hand-written service classes (e.g., Connections covered by SSO).
+  const coveredServices = new Set<string>();
   for (const service of spec.services) {
-    const resolvedName = resolveServiceName(service, ctx);
+    if (isServiceCoveredByExisting(service, ctx)) {
+      coveredServices.add(service.name);
+    }
+  }
+
+  // Service imports — skip covered services
+  for (const service of spec.services) {
+    if (coveredServices.has(service.name)) continue;
+    const resolvedName = resolveResourceClassName(service, ctx);
     const serviceDir = serviceDirName(resolvedName);
     lines.push(`import { ${resolvedName} } from './${serviceDir}/${fileName(resolvedName)}';`);
   }
 
-  lines.push("import type { WorkOSOptions } from './common/interfaces/workos-options.interface';");
-  lines.push("import type { PostOptions } from './common/interfaces/post-options.interface';");
-  lines.push("import type { GetOptions } from './common/interfaces/get-options.interface';");
-  lines.push("import { NoApiKeyProvidedException } from './common/exceptions/no-api-key-provided.exception';");
-  lines.push("import { UnauthorizedException } from './common/exceptions/unauthorized.exception';");
-  lines.push("import { NotFoundException } from './common/exceptions/not-found.exception';");
-  lines.push("import { ConflictException } from './common/exceptions/conflict.exception';");
-  lines.push("import { UnprocessableEntityException } from './common/exceptions/unprocessable-entity.exception';");
-  lines.push("import { RateLimitExceededException } from './common/exceptions/rate-limit-exceeded.exception';");
-  lines.push("import { GenericServerException } from './common/exceptions/generic-server.exception';");
-  lines.push("import { BadRequestException } from './common/exceptions/bad-request.exception';");
-
-  lines.push('');
-  lines.push('export class WorkOS {');
-  lines.push('  readonly baseURL: string;');
-  lines.push('  readonly key: string;');
-  lines.push('  private readonly options: WorkOSOptions;');
   lines.push('');
+  if (spec.description) {
+    lines.push(...docComment(spec.description));
+  }
+  const extendsClause = hasExistingWorkOS ? '' : ' extends WorkOSBase';
+  lines.push(`export class WorkOS${extendsClause} {`);
+
+  // Server URL constants from spec.servers
+  if (spec.servers && spec.servers.length > 0) {
+    for (const server of spec.servers) {
+      const constName = serverConstName(server.description ?? server.url);
+      if (server.description) {
+        lines.push(...docComment(server.description, 2));
+      }
+      lines.push(`  static readonly ${constName} = '${server.url}';`);
+    }
+    lines.push('');
+  }
 
-  // Resource accessors
+  // Resource accessors — skip services whose property already exists
+  // in the baseline WorkOS class (e.g., `portal` covers AdminPortal,
+  // `mfa` covers MultiFactorAuth).
+  const existingProps = new Set<string>();
+  const baselineWorkOS = ctx.apiSurface?.classes?.['WorkOS'] ?? ctx.apiSurface?.classes?.['WorkOSNode'];
+  if (baselineWorkOS?.properties) {
+    for (const name of Object.keys(baselineWorkOS.properties)) {
+      existingProps.add(name);
+    }
+  }
+  // Resource accessors — skip services whose endpoints are fully covered
+  // by existing hand-written services.
   for (const service of spec.services) {
-    const resolvedName = resolveServiceName(service, ctx);
+    if (coveredServices.has(service.name)) continue;
+    const resolvedName = resolveResourceClassName(service, ctx);
     const propName = servicePropertyName(resolvedName);
+    if (existingProps.has(propName)) continue;
     lines.push(`  readonly ${propName} = new ${resolvedName}(this);`);
   }
 
-  lines.push('');
-  lines.push('  constructor(keyOrOptions?: string | WorkOSOptions, maybeOptions?: WorkOSOptions) {');
-  lines.push("    if (typeof keyOrOptions === 'object') {");
-  lines.push("      this.key = keyOrOptions.apiKey ?? '';");
-  lines.push('      this.options = keyOrOptions;');
-  lines.push('    } else {');
-  lines.push("      this.key = keyOrOptions ?? '';");
-  lines.push('      this.options = maybeOptions ?? {};');
-  lines.push('    }');
-  lines.push('');
-  lines.push('    if (!this.key) {');
-  lines.push("      const envKey = typeof process !== 'undefined' ? process.env?.WORKOS_API_KEY : undefined;");
-  lines.push('      if (envKey) this.key = envKey;');
-  lines.push('    }');
-  lines.push('');
-  lines.push("    const protocol = this.options.https === false ? 'http' : 'https';");
-  lines.push("    const hostname = this.options.apiHostname ?? 'api.workos.com';");
-  lines.push("    const port = this.options.port ? `:${this.options.port}` : '';");
-  lines.push('    this.baseURL = `${protocol}://${hostname}${port}`;');
-  lines.push('  }');
+  // Auth override — only emit when auth is non-default (not bearer)
+  if (needsAuthOverride(spec.auth)) {
+    lines.push('');
+    lines.push('  protected override setAuthHeaders(headers: Record<string, string>): void {');
+    renderAuthOverride(lines, spec.auth!);
+    lines.push('  }');
+  }
 
-  // HTTP methods
-  lines.push('');
-  lines.push('  async get<Result = any>(path: string, options: GetOptions = {}): Promise<{ data: Result }> {');
-  lines.push('    this.ensureApiKey(options);');
-  lines.push('    const url = this.buildUrl(path, options.query);');
-  lines.push('    const response = await fetch(url, {');
-  lines.push("      method: 'GET',");
-  lines.push('      headers: this.buildHeaders(options),');
-  lines.push('    });');
-  lines.push('    await this.handleHttpError(response, path);');
-  lines.push('    const data = await response.json() as Result;');
-  lines.push('    return { data };');
-  lines.push('  }');
+  lines.push('}');
 
-  lines.push('');
-  lines.push(
-    '  async post<Result = any, Entity = any>(path: string, entity: Entity, options: PostOptions = {}): Promise<{ data: Result }> {',
-  );
-  lines.push('    this.ensureApiKey(options);');
-  lines.push('    const url = this.buildUrl(path, options.query);');
-  lines.push('    const response = await fetch(url, {');
-  lines.push("      method: 'POST',");
-  lines.push('      headers: this.buildHeaders(options),');
-  lines.push('      body: JSON.stringify(entity),');
-  lines.push('    });');
-  lines.push('    await this.handleHttpError(response, path);');
-  lines.push('    const data = await response.json() as Result;');
-  lines.push('    return { data };');
-  lines.push('  }');
+  return { path: 'src/workos.ts', content: lines.join('\n'), skipIfExists: true };
+}
 
-  lines.push('');
-  lines.push(
-    '  async put<Result = any, Entity = any>(path: string, entity: Entity, options: PostOptions = {}): Promise<{ data: Result }> {',
-  );
-  lines.push('    this.ensureApiKey(options);');
-  lines.push('    const url = this.buildUrl(path, options.query);');
-  lines.push('    const response = await fetch(url, {');
-  lines.push("      method: 'PUT',");
-  lines.push('      headers: this.buildHeaders(options),');
-  lines.push('      body: JSON.stringify(entity),');
-  lines.push('    });');
-  lines.push('    await this.handleHttpError(response, path);');
-  lines.push('    const data = await response.json() as Result;');
-  lines.push('    return { data };');
-  lines.push('  }');
+/**
+ * Generate per-service barrel files (interfaces/index.ts) that re-export
+ * all interface and enum files for each service directory. This reduces
+ * the root barrel from ~200+ individual type exports to one wildcard
+ * re-export per service.
+ */
+function generateServiceBarrels(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+  const files: GeneratedFile[] = [];
+  const { modelToService, resolveDir } = createServiceDirResolver(spec.models, spec.services, ctx);
+
+  // Group interface files by directory, tracking exported symbol names
+  // to prevent TS2308 duplicate export errors when two files in the same
+  // directory export the same symbol (e.g., FooResponse as a wire type
+  // from one file and a domain type from another).
+  const dirExports = new Map<string, string[]>();
+  const dirSymbols = new Map<string, Set<string>>();
+
+  // Pre-seed dirSymbols with names already exported by existing interface files.
+  // When the existing SDK has an interface file in a directory that already
+  // exports a name (e.g., AuditLogSchema from create-audit-log-schema-options),
+  // the generated model with the same name must be skipped to prevent the
+  // merger from adding a duplicate `export *` that causes TS2308.
+  if (ctx.apiSurface?.interfaces) {
+    for (const [name, iface] of Object.entries(ctx.apiSurface.interfaces)) {
+      const sourceFile = (iface as any).sourceFile as string | undefined;
+      if (!sourceFile) continue;
+      // Match paths like "src/audit-logs/interfaces/foo.interface.ts" to directory "audit-logs"
+      const match = sourceFile.match(/^src\/([^/]+)\/interfaces\//);
+      if (match) {
+        const dirName = match[1];
+        if (!dirSymbols.has(dirName)) {
+          dirSymbols.set(dirName, new Set());
+        }
+        dirSymbols.get(dirName)!.add(name);
+      }
+    }
+  }
+  if (ctx.apiSurface?.enums) {
+    for (const [name, enumDef] of Object.entries(ctx.apiSurface.enums)) {
+      const sourceFile = (enumDef as any).sourceFile as string | undefined;
+      if (!sourceFile) continue;
+      const match = sourceFile.match(/^src\/([^/]+)\/interfaces\//);
+      if (match) {
+        const dirName = match[1];
+        if (!dirSymbols.has(dirName)) {
+          dirSymbols.set(dirName, new Set());
+        }
+        dirSymbols.get(dirName)!.add(name);
+      }
+    }
+  }
+  if (ctx.apiSurface?.typeAliases) {
+    for (const [name, alias] of Object.entries(ctx.apiSurface.typeAliases)) {
+      const sourceFile = (alias as any).sourceFile as string | undefined;
+      if (!sourceFile) continue;
+      const match = sourceFile.match(/^src\/([^/]+)\/interfaces\//);
+      if (match) {
+        const dirName = match[1];
+        if (!dirSymbols.has(dirName)) {
+          dirSymbols.set(dirName, new Set());
+        }
+        dirSymbols.get(dirName)!.add(name);
+      }
+    }
+  }
 
-  lines.push('');
-  lines.push(
-    '  async patch<Result = any, Entity = any>(path: string, entity: Entity, options: PostOptions = {}): Promise<{ data: Result }> {',
-  );
-  lines.push('    this.ensureApiKey(options);');
-  lines.push('    const url = this.buildUrl(path, options.query);');
-  lines.push('    const response = await fetch(url, {');
-  lines.push("      method: 'PATCH',");
-  lines.push('      headers: this.buildHeaders(options),');
-  lines.push('      body: JSON.stringify(entity),');
-  lines.push('    });');
-  lines.push('    await this.handleHttpError(response, path);');
-  lines.push('    const data = await response.json() as Result;');
-  lines.push('    return { data };');
-  lines.push('  }');
+  // Build a global set of all symbols across all directories for
+  // cross-directory deduplication.  This prevents adding a model to one
+  // directory's barrel when the same symbol already exists in another
+  // directory's barrel (e.g., Event in common vs events, DirectoryState
+  // in directory-sync vs common).
+  const globalExistingSymbols = new Set<string>();
+  for (const symbols of dirSymbols.values()) {
+    for (const sym of symbols) {
+      globalExistingSymbols.add(sym);
+    }
+  }
 
-  lines.push('');
-  lines.push('  async delete(path: string, options: GetOptions = {}): Promise<void> {');
-  lines.push('    this.ensureApiKey(options);');
-  lines.push('    const url = this.buildUrl(path);');
-  lines.push('    const response = await fetch(url, {');
-  lines.push("      method: 'DELETE',");
-  lines.push('      headers: this.buildHeaders(options),');
-  lines.push('    });');
-  lines.push('    await this.handleHttpError(response, path);');
-  lines.push('  }');
-
-  // Private helpers
-  lines.push('');
-  lines.push('  private buildUrl(path: string, query?: Record<string, any>): string {');
-  lines.push('    const url = new URL(path, this.baseURL);');
-  lines.push('    if (query) {');
-  lines.push('      for (const [key, value] of Object.entries(query)) {');
-  lines.push("        if (value !== null && value !== undefined && value !== '') {");
-  lines.push('          url.searchParams.set(key, String(value));');
-  lines.push('        }');
-  lines.push('      }');
-  lines.push('    }');
-  lines.push('    return url.toString();');
-  lines.push('  }');
+  // Models -> service directories
+  // Skip list wrapper and list metadata models — they use shared List<T>/ListMetadata
+  // from common utils, so no per-resource interface file is generated.
+  for (const model of spec.models) {
+    if (isListMetadataModel(model) || isListWrapperModel(model)) continue;
+    const service = modelToService.get(model.name);
+    const dirName = resolveDir(service);
+    if (!dirExports.has(dirName)) {
+      dirExports.set(dirName, []);
+      // Only initialize dirSymbols if not already pre-seeded from baseline
+      if (!dirSymbols.has(dirName)) {
+        dirSymbols.set(dirName, new Set());
+      }
+    }
 
-  lines.push('');
-  lines.push('  private buildHeaders(options: any = {}): Record<string, string> {');
-  lines.push('    const headers: Record<string, string> = {');
-  lines.push("      'Content-Type': 'application/json',");
-  lines.push(`      Authorization: \`Bearer \${this.key}\`,`);
-  lines.push('    };');
-  lines.push("    if (options.idempotencyKey) headers['Idempotency-Key'] = options.idempotencyKey;");
-  lines.push("    if (options.warrantToken) headers['Warrant-Token'] = options.warrantToken;");
-  lines.push('    return headers;');
-  lines.push('  }');
+    // Each model file exports a domain interface and a wire interface.
+    // Track these symbols to detect cross-file collisions.
+    const domainName = resolveInterfaceName(model.name, ctx);
+    const wireName = wireInterfaceName(domainName);
+    const symbols = dirSymbols.get(dirName)!;
 
-  lines.push('');
-  lines.push('  private ensureApiKey(options: any = {}): void {');
-  lines.push('    if (!this.key && !options.skipApiKeyCheck) {');
-  lines.push('      throw new NoApiKeyProvidedException();');
-  lines.push('    }');
-  lines.push('  }');
+    if (globalExistingSymbols.has(domainName) || globalExistingSymbols.has(wireName)) {
+      // Skip this model's export to avoid duplicate symbol in the barrel
+      // (checks across ALL directories, not just the target one)
+      continue;
+    }
 
-  lines.push('');
-  lines.push('  private async handleHttpError(response: Response, path: string): Promise<void> {');
-  lines.push('    if (response.ok) return;');
-  lines.push('');
-  lines.push("    const requestID = response.headers.get('x-request-id') ?? '';");
-  lines.push('    let data: any = {};');
-  lines.push('    try { data = await response.json(); } catch {}');
-  lines.push('    const { message, code, errors } = data;');
-  lines.push('');
-  lines.push('    switch (response.status) {');
-  lines.push('      case 400: throw new BadRequestException({ code, message, requestID });');
-  lines.push('      case 401: throw new UnauthorizedException(requestID);');
-  lines.push('      case 404: throw new NotFoundException({ code, message, path, requestID });');
-  lines.push('      case 409: throw new ConflictException({ message, requestID });');
-  lines.push('      case 422: throw new UnprocessableEntityException({ code, errors, message, requestID });');
-  lines.push('      case 429: {');
-  lines.push("        const retryAfter = Number(response.headers.get('retry-after')) || undefined;");
-  lines.push("        throw new RateLimitExceededException(message ?? 'Too many requests', requestID, retryAfter);");
-  lines.push('      }');
-  lines.push("      default: throw new GenericServerException(response.status, message ?? 'Server error', requestID);");
-  lines.push('    }');
-  lines.push('  }');
+    symbols.add(domainName);
+    symbols.add(wireName);
+    // Also track in the global set so subsequent models in other directories
+    // don't re-export the same symbol (intra-generation cross-directory dedup).
+    globalExistingSymbols.add(domainName);
+    globalExistingSymbols.add(wireName);
+    dirExports.get(dirName)!.push(`export * from './${fileName(model.name)}.interface';`);
+  }
 
-  lines.push('}');
+  // Enums -> service directories
+  for (const enumDef of spec.enums) {
+    const enumService = findEnumService(enumDef.name, spec.services);
+    const dirName = resolveDir(enumService);
+    if (!dirExports.has(dirName)) {
+      dirExports.set(dirName, []);
+      if (!dirSymbols.has(dirName)) {
+        dirSymbols.set(dirName, new Set());
+      }
+    }
 
-  return { path: 'src/workos.ts', content: lines.join('\n'), skipIfExists: true, integrateTarget: false };
-}
+    const symbols = dirSymbols.get(dirName)!;
+    if (globalExistingSymbols.has(enumDef.name)) continue;
+
+    symbols.add(enumDef.name);
+    globalExistingSymbols.add(enumDef.name);
+    dirExports.get(dirName)!.push(`export * from './${fileName(enumDef.name)}.interface';`);
+  }
+
+  for (const [dirName, exports] of dirExports) {
+    // Deduplicate (an enum and model could theoretically share a file name)
+    const uniqueExports = [...new Set(exports)];
+    uniqueExports.sort();
+    files.push({
+      path: `src/${dirName}/interfaces/index.ts`,
+      content: uniqueExports.join('\n'),
+      skipIfExists: true,
+    });
+  }
 
-// Names exported from common utilities that must not be re-exported from model interfaces
-const RESERVED_BARREL_NAMES = new Set(['List', 'ListResponse', 'ListMetadata', 'AutoPaginatable', 'PaginationOptions']);
+  return files;
+}
 
 function generateBarrel(spec: ApiSpec, ctx: EmitterContext): GeneratedFile {
   const lines: string[] = [];
-  const modelToService = assignModelsToServices(spec.models, spec.services);
-  const serviceNameMap = buildServiceNameMap(spec.services, ctx);
-  const resolveDir = (irService: string | undefined) =>
-    irService ? serviceDirName(serviceNameMap.get(irService) ?? irService) : 'common';
+  const { modelToService, resolveDir } = createServiceDirResolver(spec.models, spec.services, ctx);
+
+  // Track all exported names to prevent duplicates.
+  // Pre-seed with names already exported by the existing SDK to avoid generating
+  // duplicate exports that would conflict with existing `export *` statements.
+  const exportedNames = new Set<string>();
+  if (ctx.apiSurface?.interfaces) {
+    for (const name of Object.keys(ctx.apiSurface.interfaces)) {
+      exportedNames.add(name);
+    }
+  }
+  if (ctx.apiSurface?.classes) {
+    for (const name of Object.keys(ctx.apiSurface.classes)) {
+      exportedNames.add(name);
+    }
+  }
+
+  // Collect names already exported by the existing SDK (via export * or named exports).
+  // When an explicit `export type { Foo }` would shadow a wildcard re-export that
+  // already provides a hand-written version of Foo (e.g., a discriminated union),
+  // we must skip the explicit export so the wildcard wins.
+  const existingSdkExports = new Set<string>();
+  if (ctx.apiSurface?.exports) {
+    for (const names of Object.values(ctx.apiSurface.exports)) {
+      for (const name of names) {
+        existingSdkExports.add(name);
+      }
+    }
+  }
 
   // Common exports
   lines.push("export * from './common/exceptions';");
@@ -230,51 +290,178 @@ function generateBarrel(spec: ApiSpec, ctx: EmitterContext): GeneratedFile {
   lines.push("export type { PostOptions } from './common/interfaces/post-options.interface';");
   lines.push("export type { GetOptions } from './common/interfaces/get-options.interface';");
   lines.push('');
+  for (const name of [
+    'AutoPaginatable',
+    'List',
+    'ListMetadata',
+    'ListResponse',
+    'PaginationOptions',
+    'WorkOSOptions',
+    'PostOptions',
+    'GetOptions',
+  ]) {
+    exportedNames.add(name);
+  }
 
-  // Per-service exports: interfaces + resource class
+  // Identify services whose endpoints are fully covered by existing hand-written
+  // classes — their resource class should not be re-exported from the barrel.
+  const coveredServicesBarrel = new Set<string>();
   for (const service of spec.services) {
-    const resolvedName = resolveServiceName(service, ctx);
-    const serviceDir = serviceDirName(resolvedName);
+    if (isServiceCoveredByExisting(service, ctx)) {
+      coveredServicesBarrel.add(service.name);
+    }
+  }
 
-    // Collect models that belong to this service, skipping reserved names
-    const serviceModels = spec.models.filter((m) => modelToService.get(m.name) === service.name);
-    for (const model of serviceModels) {
-      const name = resolveInterfaceName(model.name, ctx);
-      const wireName = wireInterfaceName(name);
-      if (RESERVED_BARREL_NAMES.has(name) || RESERVED_BARREL_NAMES.has(wireName)) continue;
-      lines.push(
-        `export type { ${name}, ${wireName} } from './${serviceDir}/interfaces/${fileName(model.name)}.interface';`,
-      );
+  // Track directories that have already been wildcard-exported
+  const exportedDirs = new Set<string>();
+
+  // Per-service exports: service barrel + resource class
+  for (const service of spec.services) {
+    const resolvedName = resolveResourceClassName(service, ctx);
+    const serviceDir = serviceDirName(resolvedName);
+    // The interfaces directory may differ from the resource class directory when
+    // a service's class name is remapped (e.g., WebhooksEndpoints class lives in
+    // webhooks-endpoints/ but its model interfaces live in webhooks/).
+    const interfacesDir = resolveDir(service.name);
+
+    // Check if this service has any models or enums (i.e., a barrel was generated).
+    // Exclude list wrapper and list metadata models — these are skipped during
+    // interface generation (they use shared List<T>/ListMetadata), so they don't
+    // have corresponding .interface.ts files in the output.
+    const serviceModels = spec.models.filter((m) => {
+      if (modelToService.get(m.name) !== service.name) return false;
+      if (isListMetadataModel(m) || isListWrapperModel(m)) return false;
+      return true;
+    });
+    const serviceEnums = spec.enums.filter((e) => {
+      const enumService = findEnumService(e.name, spec.services);
+      return enumService === service.name;
+    });
+
+    // Check whether any model or enum in this service conflicts with existingSdkExports.
+    // If so, fall back to individual exports to avoid shadowing hand-written types.
+    const hasConflict =
+      serviceModels.some((m) => existingSdkExports.has(resolveInterfaceName(m.name, ctx))) ||
+      serviceEnums.some((e) => existingSdkExports.has(e.name));
+
+    if ((serviceModels.length > 0 || serviceEnums.length > 0) && !exportedDirs.has(interfacesDir) && !hasConflict) {
+      exportedDirs.add(interfacesDir);
+      lines.push(`export * from './${interfacesDir}/interfaces';`);
+      // Track the individual names so they don't get re-exported below
+      for (const model of serviceModels) {
+        exportedNames.add(resolveInterfaceName(model.name, ctx));
+        exportedNames.add(wireInterfaceName(resolveInterfaceName(model.name, ctx)));
+      }
+      for (const enumDef of serviceEnums) {
+        exportedNames.add(enumDef.name);
+      }
+    } else if (!hasConflict) {
+      // Fallback: emit individual model exports (e.g., when no models/enums exist)
+      for (const model of serviceModels) {
+        const name = resolveInterfaceName(model.name, ctx);
+        const wireName = wireInterfaceName(name);
+        if (exportedNames.has(name) || exportedNames.has(wireName)) continue;
+        if (existingSdkExports.has(name)) continue;
+        exportedNames.add(name);
+        exportedNames.add(wireName);
+        lines.push(
+          `export type { ${name}, ${wireName} } from './${interfacesDir}/interfaces/${fileName(model.name)}.interface';`,
+        );
+      }
     }
 
-    // Resource class
-    lines.push(`export { ${resolvedName} } from './${serviceDir}/${fileName(resolvedName)}';`);
+    // Resource class — skip if already exported or if service is fully covered
+    // by existing hand-written classes
+    if (coveredServicesBarrel.has(service.name)) {
+      // Emit a comment indicating this service is covered by an existing class
+      lines.push(`// ${resolvedName} is covered by an existing hand-written class — not re-exported.`);
+    } else if (!exportedNames.has(resolvedName)) {
+      exportedNames.add(resolvedName);
+      lines.push(`export { ${resolvedName} } from './${serviceDir}/${fileName(resolvedName)}';`);
+    }
     lines.push('');
   }
 
-  // Unassigned models (common), skipping reserved names
+  // Unassigned models (common) — use barrel if any exist
   const unassignedModels = spec.models.filter((m) => !modelToService.has(m.name));
-  for (const model of unassignedModels) {
-    const name = resolveInterfaceName(model.name, ctx);
-    const wireName = wireInterfaceName(name);
-    if (RESERVED_BARREL_NAMES.has(name) || RESERVED_BARREL_NAMES.has(wireName)) continue;
-    lines.push(`export type { ${name}, ${wireName} } from './common/interfaces/${fileName(model.name)}.interface';`);
+  const commonEnums = spec.enums.filter((e) => {
+    const enumService = findEnumService(e.name, spec.services);
+    return !enumService;
+  });
+
+  const commonHasConflict =
+    unassignedModels.some((m) => existingSdkExports.has(resolveInterfaceName(m.name, ctx))) ||
+    commonEnums.some((e) => existingSdkExports.has(e.name));
+
+  if ((unassignedModels.length > 0 || commonEnums.length > 0) && !exportedDirs.has('common') && !commonHasConflict) {
+    exportedDirs.add('common');
+    lines.push("export * from './common/interfaces';");
+    for (const model of unassignedModels) {
+      exportedNames.add(resolveInterfaceName(model.name, ctx));
+      exportedNames.add(wireInterfaceName(resolveInterfaceName(model.name, ctx)));
+    }
+    for (const enumDef of commonEnums) {
+      exportedNames.add(enumDef.name);
+    }
+  } else {
+    // Fallback: individual model exports
+    for (const model of unassignedModels) {
+      const name = resolveInterfaceName(model.name, ctx);
+      const wireName = wireInterfaceName(name);
+      if (exportedNames.has(name) || exportedNames.has(wireName)) continue;
+      if (existingSdkExports.has(name)) continue;
+      exportedNames.add(name);
+      exportedNames.add(wireName);
+      lines.push(`export type { ${name}, ${wireName} } from './common/interfaces/${fileName(model.name)}.interface';`);
+    }
   }
 
-  // Enum exports
+  // Enum exports — only for enums not already covered by a service/common barrel.
+  // Skip duplicates and names already covered by existing SDK wildcards.
+  // Use value export (`export { ... }`) for actual TS enums so consumers
+  // can use them as runtime values (e.g., ConnectionType.GoogleOAuth).
+  // Use type-only export (`export type { ... }`) for string literal unions.
   for (const enumDef of spec.enums) {
-    // Find which service directory the enum landed in
+    if (exportedNames.has(enumDef.name)) continue;
+    if (existingSdkExports.has(enumDef.name)) continue;
+    exportedNames.add(enumDef.name);
     const enumService = findEnumService(enumDef.name, spec.services);
     const dir = resolveDir(enumService);
-    lines.push(`export type { ${enumDef.name} } from './${dir}/interfaces/${fileName(enumDef.name)}.interface';`);
+    if (!exportedDirs.has(dir)) {
+      const baselineEnum = ctx.apiSurface?.enums?.[enumDef.name];
+      const exportKeyword = baselineEnum?.members ? 'export' : 'export type';
+      lines.push(
+        `${exportKeyword} { ${enumDef.name} } from './${dir}/interfaces/${fileName(enumDef.name)}.interface';`,
+      );
+    }
   }
 
   lines.push('');
-  lines.push("export { WorkOS } from './workos';");
+  // Only emit the WorkOS re-export for standalone generation (no existing SDK).
+  // When integrating into an existing SDK, the existing barrel already exports
+  // WorkOS (often as a subclass alias like `export { WorkOSNode as WorkOS }`),
+  // and adding a second export with the same name causes a duplicate identifier error.
+  if (!ctx.apiSurface && !exportedNames.has('WorkOS')) {
+    exportedNames.add('WorkOS');
+    lines.push("export { WorkOS } from './workos';");
+  }
 
   return { path: 'src/index.ts', content: lines.join('\n'), skipIfExists: true };
 }
 
+/**
+ * Generate a worker-compatible barrel file that re-exports everything from
+ * the main barrel. This keeps type exports in sync automatically.
+ */
+function generateWorkerBarrel(_spec: ApiSpec, _ctx: EmitterContext): GeneratedFile {
+  const lines: string[] = [];
+
+  // Re-export everything from the main index — keeps type exports in sync
+  lines.push("export * from './index';");
+
+  return { path: 'src/index.worker.ts', content: lines.join('\n'), skipIfExists: true };
+}
+
 function findEnumService(enumName: string, services: Service[]): string | undefined {
   for (const service of services) {
     for (const op of service.operations) {
@@ -297,6 +484,51 @@ function findEnumService(enumName: string, services: Service[]): string | undefi
   return undefined;
 }
 
+/**
+ * Determine whether the spec's auth scheme requires overriding the
+ * default bearer auth in WorkOSBase.setAuthHeaders().
+ */
+function needsAuthOverride(auth?: AuthScheme[]): boolean {
+  if (!auth || auth.length === 0) return false;
+  const scheme = auth[0];
+  // bearer and oauth2 match the base class default — no override needed
+  return scheme.kind === 'apiKey';
+}
+
+/**
+ * Render the body of a setAuthHeaders override for non-default auth schemes.
+ * Only called when needsAuthOverride() returns true.
+ */
+function renderAuthOverride(lines: string[], auth: AuthScheme[]): void {
+  const scheme = auth[0];
+  if (scheme.kind !== 'apiKey') return;
+  switch (scheme.in) {
+    case 'header':
+      lines.push(`    headers['${scheme.name}'] = this.key;`);
+      break;
+    case 'query':
+      lines.push(`    // Auth key sent as query parameter '${scheme.name}' (see buildUrl)`);
+      break;
+    case 'cookie':
+      lines.push(`    headers['Cookie'] = \`${scheme.name}=\${this.key}\`;`);
+      break;
+  }
+}
+
+/**
+ * Convert a server description or URL into a SCREAMING_SNAKE_CASE constant name.
+ */
+function serverConstName(description: string): string {
+  return (
+    'SERVER_' +
+    description
+      .replace(/https?:\/\//g, '')
+      .replace(/[^a-zA-Z0-9]+/g, '_')
+      .replace(/^_|_$/g, '')
+      .toUpperCase()
+  );
+}
+
 function generatePackageJson(ctx: EmitterContext): GeneratedFile {
   const pkg = {
     name: `@${ctx.namespace}/sdk`,
@@ -336,6 +568,7 @@ function generateTsConfig(): GeneratedFile {
       lib: ['ES2020'],
       declaration: true,
       strict: true,
+      exactOptionalPropertyTypes: true,
       esModuleInterop: true,
       skipLibCheck: true,
       forceConsistentCasingInFileNames: true,