@workos/oagen-emitters 0.2.1 → 0.3.0

package/src/go/type-map.ts

@@ -0,0 +1,82 @@
+import type { TypeRef, PrimitiveType, UnionType } from '@workos/oagen';
+import { mapTypeRef as irMapTypeRef } from '@workos/oagen';
+import { className } from './naming.js';
+
+/**
+ * Map an IR TypeRef to a Go type string.
+ */
+export function mapTypeRef(ref: TypeRef, asPointer = false): string {
+  const base = irMapTypeRef<string>(ref, {
+    primitive: mapPrimitive,
+    array: (_ref, items) => `[]${items}`,
+    model: (r) => `*${className(r.name)}`,
+    enum: (r) => className(r.name),
+    union: (_r, variants) => joinUnionVariants(_r, variants),
+    nullable: (_ref, inner) => {
+      // If inner is already a pointer type (model), don't double-pointer
+      if (inner.startsWith('*')) return inner;
+      return `*${inner}`;
+    },
+    literal: (r) => {
+      if (r.value === null) return 'interface{}';
+      if (typeof r.value === 'string') return 'string';
+      if (typeof r.value === 'number') return Number.isInteger(r.value) ? 'int' : 'float64';
+      if (typeof r.value === 'boolean') return 'bool';
+      return 'interface{}';
+    },
+    map: (_ref, value) => `map[string]${value}`,
+  });
+  if (asPointer && !base.startsWith('*') && !base.startsWith('[]') && !base.startsWith('map[')) {
+    return `*${base}`;
+  }
+  return base;
+}
+
+/**
+ * Map an IR TypeRef to a Go type string without pointer wrapping for models.
+ * Used for response type references where we don't want a double pointer.
+ */
+export function mapTypeRefValue(ref: TypeRef): string {
+  return irMapTypeRef<string>(ref, {
+    primitive: mapPrimitive,
+    array: (_ref, items) => `[]${items}`,
+    model: (r) => className(r.name),
+    enum: (r) => className(r.name),
+    union: (_r, variants) => joinUnionVariants(_r, variants),
+    nullable: (_ref, inner) => `*${inner}`,
+    literal: (r) => {
+      if (r.value === null) return 'interface{}';
+      if (typeof r.value === 'string') return 'string';
+      if (typeof r.value === 'number') return Number.isInteger(r.value) ? 'int' : 'float64';
+      if (typeof r.value === 'boolean') return 'bool';
+      return 'interface{}';
+    },
+    map: (_ref, value) => `map[string]${value}`,
+  });
+}
+
+function mapPrimitive(ref: PrimitiveType): string {
+  if (ref.format === 'binary') return '[]byte';
+  switch (ref.type) {
+    case 'string':
+      return 'string';
+    case 'integer':
+      return 'int';
+    case 'number':
+      return 'float64';
+    case 'boolean':
+      return 'bool';
+    case 'unknown':
+      return 'interface{}';
+  }
+}
+
+function joinUnionVariants(_ref: UnionType, variants: string[]): string {
+  if (_ref.compositionKind === 'allOf') {
+    return variants[0] ?? 'interface{}';
+  }
+  const unique = [...new Set(variants)];
+  if (unique.length === 1) return unique[0];
+  // Go doesn't have union types; use interface{}
+  return 'interface{}';
+}

package/src/go/wrappers.ts

@@ -0,0 +1,261 @@
+import type { EmitterContext, ResolvedOperation, ResolvedWrapper } from '@workos/oagen';
+import {
+  className as goClassName,
+  fieldName as goFieldName,
+  methodName as goMethodName,
+  unexportedName,
+} from './naming.js';
+import { sortPathParamsByTemplateOrder } from './resources.js';
+import { resolveWrapperParams, formatWrapperDescription, type ResolvedWrapperParam } from '../shared/wrapper-utils.js';
+import { lowerFirstForDoc, fieldDocComment } from '../shared/naming-utils.js';
+
+/**
+ * Generate Go 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., client_id)
+ * - Delegates to the HTTP client with the constructed body
+ */
+export function generateWrapperMethods(
+  serviceType: string,
+  resolvedOp: ResolvedOperation,
+  ctx: EmitterContext,
+): string[] {
+  if (!resolvedOp.wrappers || resolvedOp.wrappers.length === 0) return [];
+
+  const lines: string[] = [];
+
+  for (const wrapper of resolvedOp.wrappers) {
+    const wrapperParams = resolveWrapperParams(wrapper, ctx);
+    lines.push('');
+    emitWrapperParamsStruct(lines, wrapper, wrapperParams);
+    lines.push('');
+    emitWrapperMethod(lines, serviceType, resolvedOp, wrapper, wrapperParams);
+  }
+
+  return lines;
+}
+
+function emitWrapperParamsStruct(
+  lines: string[],
+  wrapper: ResolvedWrapper,
+  wrapperParams: ResolvedWrapperParam[],
+): void {
+  const structName = `${goMethodName(wrapper.name)}Params`;
+
+  lines.push(`// ${structName} contains the parameters for ${goMethodName(wrapper.name)}.`);
+  lines.push(`type ${structName} struct {`);
+
+  for (const { paramName, field, isOptional } of wrapperParams) {
+    const goField = goFieldName(paramName);
+    const goType = field ? resolveSimpleGoType(field.type) : 'string';
+
+    if (field?.description) {
+      const fdLines = field.description.split('\n').filter((l: string) => l.trim());
+      lines.push(`\t// ${fieldDocComment(goField, fdLines[0])}`);
+      for (let i = 1; i < fdLines.length; i++) {
+        lines.push(`\t// ${fdLines[i].trim()}`);
+      }
+    }
+    if (isOptional) {
+      const optType = goType.startsWith('*') || goType.startsWith('[]') ? goType : `*${goType}`;
+      lines.push(`\t${goField} ${optType} \`json:"${paramName},omitempty"\``);
+    } else {
+      lines.push(`\t${goField} ${goType} \`json:"${paramName}"\``);
+    }
+  }
+
+  lines.push('}');
+}
+
+function emitWrapperMethod(
+  lines: string[],
+  serviceType: string,
+  resolvedOp: ResolvedOperation,
+  wrapper: ResolvedWrapper,
+  wrapperParams: ResolvedWrapperParam[],
+): void {
+  const op = resolvedOp.operation;
+  const method = goMethodName(wrapper.name);
+  const paramsStruct = `${method}Params`;
+
+  // Return type
+  const responseType = wrapper.responseModelName ? goClassName(wrapper.responseModelName) : null;
+
+  // GoDoc
+  lines.push(`// ${method} ${formatWrapperDescription(wrapper.name)}.`);
+
+  // Signature
+  const sigParams: string[] = ['ctx context.Context'];
+
+  // Path params as positional args (sorted by template order)
+  for (const p of sortPathParamsByTemplateOrder(op)) {
+    sigParams.push(`${lowerFirstSafe(goFieldName(p.name))} ${resolveSimpleGoType(p.type)}`);
+  }
+
+  sigParams.push(`params *${paramsStruct}`);
+  sigParams.push('opts ...RequestOption');
+
+  if (responseType) {
+    lines.push(`func (s *${serviceType}) ${method}(${sigParams.join(', ')}) (*${responseType}, error) {`);
+  } else {
+    lines.push(`func (s *${serviceType}) ${method}(${sigParams.join(', ')}) error {`);
+  }
+
+  // Build body map with defaults + exposed params
+  lines.push('\tbody := map[string]interface{}{');
+
+  // Constant defaults (e.g., grant_type)
+  for (const [key, value] of Object.entries(wrapper.defaults)) {
+    lines.push(`\t\t"${key}": ${goLiteral(value)},`);
+  }
+
+  // Required exposed params
+  for (const { paramName, isOptional } of wrapperParams) {
+    if (isOptional) continue;
+    const goField = goFieldName(paramName);
+    lines.push(`\t\t"${paramName}": params.${goField},`);
+  }
+
+  lines.push('\t}');
+
+  // Inferred fields from client config
+  for (const field of wrapper.inferFromClient) {
+    const expr = clientFieldExpression(field);
+    lines.push(`\tif ${expr} != "" {`);
+    lines.push(`\t\tbody["${field}"] = ${expr}`);
+    lines.push('\t}');
+  }
+
+  // Optional exposed params
+  for (const { paramName, isOptional } of wrapperParams) {
+    if (!isOptional) continue;
+    const goField = goFieldName(paramName);
+    lines.push(`\tif params.${goField} != nil {`);
+    lines.push(`\t\tbody["${paramName}"] = *params.${goField}`);
+    lines.push('\t}');
+  }
+
+  // Build path expression
+  let pathExpr: string;
+  if (op.pathParams.length > 0) {
+    let fmtStr = op.path;
+    const fmtArgs: string[] = [];
+    for (const p of sortPathParamsByTemplateOrder(op)) {
+      fmtStr = fmtStr.replace(`{${p.name}}`, '%s');
+      fmtArgs.push(lowerFirstSafe(goFieldName(p.name)));
+    }
+    pathExpr = `fmt.Sprintf("${fmtStr}", ${fmtArgs.join(', ')})`;
+  } else {
+    pathExpr = `"${op.path}"`;
+  }
+
+  // Make the request
+  if (responseType) {
+    lines.push(`\tvar result ${responseType}`);
+    lines.push(
+      `\t_, err := s.client.request(ctx, "${op.httpMethod.toUpperCase()}", ${pathExpr}, nil, body, &result, opts)`,
+    );
+    lines.push('\tif err != nil {');
+    lines.push('\t\treturn nil, err');
+    lines.push('\t}');
+    lines.push('\treturn &result, nil');
+  } else {
+    lines.push(
+      `\t_, err := s.client.request(ctx, "${op.httpMethod.toUpperCase()}", ${pathExpr}, nil, body, nil, opts)`,
+    );
+    lines.push('\treturn err');
+  }
+
+  lines.push('}');
+}
+
+/** Convert a value to a Go literal. */
+function goLiteral(value: string | number | boolean): string {
+  if (typeof value === 'string') return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  return String(value);
+}
+
+/** Get the Go expression for reading a client config field. */
+function clientFieldExpression(field: string): string {
+  switch (field) {
+    case 'client_id':
+      return 's.client.clientID';
+    case 'client_secret':
+      return 's.client.apiKey';
+    default:
+      return `s.client.${lowerFirstSafe(goFieldName(field))}`;
+  }
+}
+
+/** Resolve a TypeRef to a simple Go type string. */
+function resolveSimpleGoType(ref: any): string {
+  if (ref.kind === 'primitive') {
+    switch (ref.type) {
+      case 'string':
+        return 'string';
+      case 'integer':
+        return 'int';
+      case 'number':
+        return 'float64';
+      case 'boolean':
+        return 'bool';
+      default:
+        return 'interface{}';
+    }
+  }
+  if (ref.kind === 'nullable') return `*${resolveSimpleGoType(ref.inner)}`;
+  if (ref.kind === 'array') return `[]${resolveSimpleGoType(ref.items)}`;
+  if (ref.kind === 'model') return `*${goClassName(ref.name)}`;
+  if (ref.kind === 'enum') return goClassName(ref.name);
+  if (ref.kind === 'union') {
+    // For oneOf with a single non-null variant, use that variant's type
+    const nonNull = ref.variants.filter((v: any) => v.kind !== 'literal' || v.value !== null);
+    if (nonNull.length === 1) return resolveSimpleGoType(nonNull[0]);
+    return 'interface{}';
+  }
+  return 'interface{}';
+}
+
+/** Go reserved words set. */
+const GO_RESERVED = new Set([
+  'break',
+  'case',
+  'chan',
+  'const',
+  'continue',
+  'default',
+  'defer',
+  'else',
+  'fallthrough',
+  'for',
+  'func',
+  'go',
+  'goto',
+  'if',
+  'import',
+  'interface',
+  'map',
+  'package',
+  'range',
+  'return',
+  'select',
+  'struct',
+  'switch',
+  'type',
+  'var',
+]);
+
+function lowerFirstSafe(s: string): string {
+  if (!s) return s;
+  const result = unexportedName(s);
+  if (GO_RESERVED.has(result)) return `${result}Param`;
+  return result;
+}
+
+function _lowerFirstField(s: string): string {
+  return lowerFirstForDoc(s);
+}

package/src/index.ts

@@ -1 +1,4 @@
 export { nodeEmitter } from './node/index.js';
+export { pythonEmitter } from './python/index.js';
+export { phpEmitter } from './php/index.js';
+export { goEmitter } from './go/index.js';

package/src/node/client.ts

@@ -1,4 +1,5 @@
 import type { ApiSpec, AuthScheme, EmitterContext, GeneratedFile, Service } from '@workos/oagen';
+import { collectReferencedNames } from '@workos/oagen';
 import { fileName, resolveServiceDir, servicePropertyName, resolveInterfaceName, wireInterfaceName } from './naming.js';
 import {
   docComment,
@@ -15,9 +16,7 @@ export function generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFil
   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());
+  // worker barrel, package.json, tsconfig.json are now hand-maintained in the target SDK
 
   return files;
 }
@@ -128,47 +127,36 @@ function generateServiceBarrels(spec: ApiSpec, ctx: EmitterContext): GeneratedFi
   // 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.
+  //
+  // Also track baseline file stems per directory so we can detect when the
+  // barrel needs updating with new export lines (see hasNewExports below).
+  const dirSymbolsFromBaseline = new Map<string, Set<string>>();
+  const seedFromBaseline = (sourceFile: string, name: string) => {
+    const match = sourceFile.match(/^src\/([^/]+)\/interfaces\/(.+)\.ts$/);
+    if (!match) return;
+    const dirName = match[1];
+    const fileStem = match[2];
+    if (!dirSymbols.has(dirName)) dirSymbols.set(dirName, new Set());
+    dirSymbols.get(dirName)!.add(name);
+    if (!dirSymbolsFromBaseline.has(dirName)) dirSymbolsFromBaseline.set(dirName, new Set());
+    dirSymbolsFromBaseline.get(dirName)!.add(fileStem);
+  };
   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 (sourceFile) seedFromBaseline(sourceFile, 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 (sourceFile) seedFromBaseline(sourceFile, 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);
-      }
+      if (sourceFile) seedFromBaseline(sourceFile, name);
     }
   }
 
@@ -187,8 +175,12 @@ function generateServiceBarrels(spec: ApiSpec, ctx: EmitterContext): GeneratedFi
   // 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.
+  // Also skip unreachable models — oagen only passes service-referenced models
+  // to generateModels, so unreachable models have no interface file to export.
+  const barrelReachable = collectReferencedNames(spec.services, spec.models);
   for (const model of spec.models) {
     if (isListMetadataModel(model) || isListWrapperModel(model)) continue;
+    if (!barrelReachable.models.has(model.name)) continue;
     const service = modelToService.get(model.name);
     const dirName = resolveDir(service);
     if (!dirExports.has(dirName)) {
@@ -240,14 +232,57 @@ function generateServiceBarrels(spec: ApiSpec, ctx: EmitterContext): GeneratedFi
   }
 
   for (const [dirName, exports] of dirExports) {
-    // Deduplicate (an enum and model could theoretically share a file name)
-    const uniqueExports = [...new Set(exports)];
+    const exportSet = new Set(exports);
+
+    // When integrating into an existing SDK, include baseline exports from
+    // the api-surface so the barrel is comprehensive.  This ensures stale
+    // entries (e.g., renamed files from previous generations) are removed
+    // when overwriteExisting replaces the barrel.
+    if (ctx.apiSurface) {
+      const addBaselineExports = (items: Record<string, any> | undefined) => {
+        if (!items) return;
+        for (const item of Object.values(items)) {
+          const sourceFile = (item as any).sourceFile as string | undefined;
+          if (!sourceFile) continue;
+          const match = sourceFile.match(/^src\/([^/]+)\/interfaces\/(.+)\.ts$/);
+          if (match && match[1] === dirName) {
+            exportSet.add(`export * from './${match[2].replace(/\.ts$/, '')}';`);
+          }
+        }
+      };
+      addBaselineExports(ctx.apiSurface.interfaces);
+      addBaselineExports(ctx.apiSurface.typeAliases);
+      addBaselineExports(ctx.apiSurface.enums);
+    }
+
+    // Deduplicate and sort
+    const uniqueExports = [...exportSet];
     uniqueExports.sort();
-    files.push({
-      path: `src/${dirName}/interfaces/index.ts`,
-      content: uniqueExports.join('\n'),
-      skipIfExists: true,
-    });
+
+    if (ctx.apiSurface) {
+      // Integration mode: overwrite the barrel so stale entries are removed.
+      files.push({
+        path: `src/${dirName}/interfaces/index.ts`,
+        content: uniqueExports.join('\n'),
+        overwriteExisting: true,
+      });
+    } else {
+      // Standalone generation: only update if there are new exports.
+      const baselineSymbols = dirSymbolsFromBaseline.get(dirName);
+      const hasNewExports = baselineSymbols
+        ? uniqueExports.some((exp) => {
+            const match = exp.match(/from '\.\/(.*?)'/);
+            if (!match) return false;
+            return !baselineSymbols.has(match[1]);
+          })
+        : false;
+
+      files.push({
+        path: `src/${dirName}/interfaces/index.ts`,
+        content: uniqueExports.join('\n'),
+        skipIfExists: !hasNewExports,
+      });
+    }
   }
 
   return files;
@@ -457,7 +492,11 @@ function generateBarrel(spec: ApiSpec, ctx: EmitterContext): GeneratedFile {
   }
 
   // Unassigned models (common) — use barrel if any exist
-  const unassignedModels = spec.models.filter((m) => !modelToService.has(m.name));
+  // Filter to reachable models only: oagen's generateAllFiles passes only
+  // service-referenced models to generateModels, so unreachable models
+  // never get interface files.  Exporting them here would create broken imports.
+  const reachable = collectReferencedNames(spec.services, spec.models);
+  const unassignedModels = spec.models.filter((m) => !modelToService.has(m.name) && reachable.models.has(m.name));
   const commonEnums = spec.enums.filter((e) => {
     const enumService = findEnumService(e.name, spec.services);
     return !enumService;
@@ -527,23 +566,6 @@ function generateBarrel(spec: ApiSpec, ctx: EmitterContext): GeneratedFile {
   };
 }
 
-/**
- * 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) {
@@ -610,62 +632,3 @@ function serverConstName(description: string): string {
       .toUpperCase()
   );
 }
-
-function generatePackageJson(ctx: EmitterContext): GeneratedFile {
-  const pkg = {
-    name: `@${ctx.namespace}/sdk`,
-    version: '0.0.0',
-    type: 'module',
-    main: 'src/index.ts',
-    types: 'src/index.ts',
-    exports: {
-      '.': './src/index.ts',
-    },
-    scripts: {
-      test: 'jest',
-      build: 'tsc',
-    },
-    devDependencies: {
-      typescript: '^5.0.0',
-      jest: '^29.0.0',
-      'jest-fetch-mock': '^3.0.0',
-      '@types/jest': '^29.0.0',
-      'ts-jest': '^29.0.0',
-    },
-  };
-
-  return {
-    path: 'package.json',
-    content: JSON.stringify(pkg, null, 2),
-    skipIfExists: true,
-    integrateTarget: false,
-  };
-}
-
-function generateTsConfig(): GeneratedFile {
-  const config = {
-    compilerOptions: {
-      target: 'ES2020',
-      module: 'CommonJS',
-      lib: ['ES2020'],
-      declaration: true,
-      strict: true,
-      exactOptionalPropertyTypes: true,
-      esModuleInterop: true,
-      skipLibCheck: true,
-      forceConsistentCasingInFileNames: true,
-      resolveJsonModule: true,
-      outDir: './lib',
-      rootDir: './src',
-    },
-    include: ['src/**/*'],
-    exclude: ['node_modules', 'lib', '**/*.spec.ts'],
-  };
-
-  return {
-    path: 'tsconfig.json',
-    content: JSON.stringify(config, null, 2),
-    skipIfExists: true,
-    integrateTarget: false,
-  };
-}

package/src/node/enums.ts

@@ -19,6 +19,15 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
     // Check baseline surface for representation and values
     const baselineEnum = ctx.apiSurface?.enums?.[enumDef.name];
     const baselineAlias = ctx.apiSurface?.typeAliases?.[enumDef.name];
+    const generatedPath = `src/${dirName}/interfaces/${fileName(enumDef.name)}.interface.ts`;
+
+    // If the baseline already provides this enum from a different file (e.g., `.enum.ts`),
+    // skip generation to avoid duplicate exports from the same barrel.
+    const baselineSourceFile = (baselineEnum as any)?.sourceFile ?? (baselineAlias as any)?.sourceFile;
+    if (baselineSourceFile && baselineSourceFile !== generatedPath) {
+      continue;
+    }
+
     const lines: string[] = [];
 
     // Track whether the generated content has new values not in the baseline.