@workos/oagen-emitters 0.2.1 → 0.4.0

package/src/dotnet/type-map.ts

@@ -0,0 +1,201 @@
+import type { TypeRef, PrimitiveType, UnionType } from '@workos/oagen';
+import { mapTypeRef as irMapTypeRef } from '@workos/oagen';
+import { className } from './naming.js';
+
+/** Known C# value types that need `?` for nullable. */
+const VALUE_TYPES = new Set(['int', 'long', 'double', 'bool', 'float', 'decimal', 'byte', 'short', 'DateTimeOffset']);
+
+/**
+ * Module-level alias map for structurally-identical enums. Populated by
+ * `setEnumAliases` from the current spec's enum list; consulted by
+ * `mapTypeRef` so that every reference to a duplicate enum resolves to the
+ * canonical name. C# has no first-class type alias for enums, so dedup must
+ * happen at reference-rewrite time rather than via a runtime alias.
+ */
+const enumAliases = new Map<string, string>();
+
+/**
+ * Names of enums that resolve to a single wire value and should therefore be
+ * mapped to C# `string` at reference sites (the owning property emits a
+ * const initializer). Populated by `setSingleValueEnumNames`.
+ */
+const singleValueEnumNames = new Set<string>();
+
+/** Replace the current enum-alias map. Safe to call more than once. */
+export function setEnumAliases(aliases: Map<string, string>): void {
+  enumAliases.clear();
+  for (const [k, v] of aliases) enumAliases.set(k, v);
+}
+
+/** Replace the set of enum names that are single-value discriminator stand-ins. */
+export function setSingleValueEnumNames(names: Iterable<string>): void {
+  singleValueEnumNames.clear();
+  for (const n of names) singleValueEnumNames.add(n);
+}
+
+/** Resolve an enum reference name to its canonical form. */
+export function resolveEnumTypeName(name: string): string {
+  return enumAliases.get(name) ?? name;
+}
+
+/**
+ * Map an IR TypeRef to a C# type string.
+ */
+export function mapTypeRef(ref: TypeRef): string {
+  return irMapTypeRef<string>(ref, {
+    primitive: mapPrimitive,
+    array: (_ref, items) => `List<${items}>`,
+    model: (r) => className(r.name),
+    enum: (r) => {
+      // Single-value enums (discriminator consts in disguise) map to `string`
+      // so the caller can't misuse a public one-member enum type. The
+      // owning property emits a const initializer separately.
+      if ((r.values?.length ?? 0) === 1) return 'string';
+      if (singleValueEnumNames.has(r.name)) return 'string';
+      return className(resolveEnumTypeName(r.name));
+    },
+    union: (_r, variants) => joinUnionVariants(_r, variants),
+    nullable: (_ref, inner) => {
+      // With <Nullable>enable</Nullable>, all nullable types need `?`
+      if (inner.endsWith('?')) return inner; // already nullable (e.g., nested nullable)
+      return `${inner}?`;
+    },
+    literal: (r) => {
+      if (r.value === null) return 'object';
+      if (typeof r.value === 'string') return 'string';
+      if (typeof r.value === 'number') return Number.isInteger(r.value) ? 'int' : 'double';
+      if (typeof r.value === 'boolean') return 'bool';
+      return 'object';
+    },
+    map: (_ref, value) => `Dictionary<string, ${value}>`,
+  });
+}
+
+/**
+ * Map an IR TypeRef to a C# type string, making optional fields nullable.
+ * For value types, appends `?`. For reference types, returns as-is.
+ */
+export function mapTypeRefOptional(ref: TypeRef): string {
+  const baseType = mapTypeRef(ref);
+  if (isValueType(baseType)) return `${baseType}?`;
+  return baseType;
+}
+
+/**
+ * Check if a C# type is a value type (needs ? for nullable).
+ */
+export function isValueType(csType: string): boolean {
+  // Strip trailing ? if present
+  const bare = csType.endsWith('?') ? csType.slice(0, -1) : csType;
+  if (VALUE_TYPES.has(bare)) return true;
+  // Enums are value types, but we can't detect them purely from the type string.
+  // The caller should handle enum nullability explicitly when needed.
+  return false;
+}
+
+/**
+ * Check if an IR TypeRef maps to a C# value type.
+ */
+export function isValueTypeRef(ref: TypeRef): boolean {
+  if (ref.kind === 'enum') return true;
+  if (ref.kind === 'primitive') {
+    // DateTimeOffset is a value type (struct)
+    if (ref.format === 'date-time') return true;
+    switch (ref.type) {
+      case 'integer':
+      case 'number':
+      case 'boolean':
+        return true;
+      default:
+        return false;
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether a TypeRef directly names an enum (no nullable wrapper).
+ * Used to detect required enum request fields that must not silently serialize
+ * their default Unknown sentinel.
+ */
+export function isEnumRef(ref: TypeRef): boolean {
+  return ref.kind === 'enum';
+}
+
+/**
+ * Emit JSON attributes for a request-side property. When `isRequiredEnum` is
+ * true, configure both serializers to skip the field when its value equals the
+ * enum default (0 = Unknown sentinel). This converts "unset required enum"
+ * from a silent `"unknown"` wire value into a clean omission so the API
+ * returns a clear `missing required field` error instead of a confusing 422.
+ */
+export function emitJsonPropertyAttributes(wireName: string, options: { isRequiredEnum?: boolean } = {}): string[] {
+  if (options.isRequiredEnum) {
+    return [
+      `        [JsonProperty("${wireName}", DefaultValueHandling = DefaultValueHandling.Ignore)]`,
+      `        [STJS.JsonPropertyName("${wireName}")]`,
+      `        [STJS.JsonIgnore(Condition = STJS.JsonIgnoreCondition.WhenWritingDefault)]`,
+    ];
+  }
+  return [`        [JsonProperty("${wireName}")]`, `        [STJS.JsonPropertyName("${wireName}")]`];
+}
+
+function mapPrimitive(ref: PrimitiveType): string {
+  if (ref.format === 'binary') return 'byte[]';
+  if (ref.format === 'int32') return 'int';
+  if (ref.format === 'int64') return 'long';
+  if (ref.format === 'date-time') return 'DateTimeOffset';
+  switch (ref.type) {
+    case 'string':
+      return 'string';
+    case 'integer':
+      return 'long';
+    case 'number':
+      return 'double';
+    case 'boolean':
+      return 'bool';
+    case 'unknown':
+      return 'object';
+  }
+}
+
+/**
+ * Track discriminated unions for downstream model generation.
+ * Key = generated base type name, Value = discriminator info.
+ */
+export const discriminatedUnions = new Map<
+  string,
+  { property: string; mapping: Record<string, string>; variantTypes: string[] }
+>();
+
+function joinUnionVariants(_ref: UnionType, variants: string[]): string {
+  if (_ref.compositionKind === 'allOf') {
+    return variants[0] ?? 'object';
+  }
+  const unique = [...new Set(variants)];
+  if (unique.length === 1) return unique[0];
+
+  // Discriminated union: register for converter generation and return first variant as base
+  if (_ref.discriminator && _ref.discriminator.mapping) {
+    const baseName = unique[0];
+    discriminatedUnions.set(baseName, {
+      property: _ref.discriminator.property,
+      mapping: _ref.discriminator.mapping,
+      variantTypes: unique,
+    });
+    // Use object with JsonConverter for discriminated unions since
+    // AnyOf<> doesn't support discriminator-based deserialization
+    return 'object';
+  }
+
+  if (unique.length >= 2 && unique.length <= 3) return `AnyOf<${unique.join(', ')}>`;
+  // AnyOf only supports arity 2 and 3. Higher-arity unions collapse to
+  // `object`, losing type information. Warn so the author knows the spec
+  // outgrew the runtime support instead of silently degrading.
+  if (unique.length >= 4) {
+    console.warn(
+      `[oagen:dotnet] Union with ${unique.length} variants exceeds AnyOf<T1,T2,T3> arity; falling back to object. Variants: ${unique.join(', ')}`,
+    );
+  }
+  return 'object';
+}

package/src/dotnet/wrappers.ts

@@ -0,0 +1,186 @@
+import type { EmitterContext, ResolvedOperation, ResolvedWrapper } from '@workos/oagen';
+import {
+  className as csClassName,
+  fieldName as csFieldName,
+  methodName as csMethodName,
+  localName,
+  csLiteral,
+  clientFieldExpression,
+  httpMethodHelperName,
+  escapeXml,
+  emitXmlDoc,
+  humanize,
+} from './naming.js';
+import { sortPathParamsByTemplateOrder } from './resources.js';
+import { resolveWrapperParams, formatWrapperDescription, type ResolvedWrapperParam } from '../shared/wrapper-utils.js';
+import { mapTypeRef, isValueTypeRef, isEnumRef, emitJsonPropertyAttributes } from './type-map.js';
+
+/**
+ * Generate C# wrapper method lines for union split operations.
+ */
+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('');
+    emitWrapperMethod(lines, resolvedOp, wrapper, wrapperParams, ctx);
+  }
+
+  return lines;
+}
+
+function emitWrapperMethod(
+  lines: string[],
+  resolvedOp: ResolvedOperation,
+  wrapper: ResolvedWrapper,
+  _wrapperParams: ResolvedWrapperParam[],
+  _ctx: EmitterContext,
+): void {
+  const op = resolvedOp.operation;
+  const method = csMethodName(wrapper.name);
+  const optionsClass = `${method}Options`;
+  const responseType = wrapper.responseModelName ? csClassName(wrapper.responseModelName) : null;
+
+  // XML doc
+  lines.push(`        /// <summary>${formatWrapperDescription(wrapper.name)}.</summary>`);
+  for (const p of sortPathParamsByTemplateOrder(op)) {
+    const paramDesc = p.description ? escapeXml(p.description) : `The ${humanize(p.name)}.`;
+    lines.push(`        /// <param name="${localName(p.name)}">${paramDesc}</param>`);
+  }
+  lines.push(`        /// <param name="options">Request options.</param>`);
+  lines.push(`        /// <param name="requestOptions">Per-request configuration overrides.</param>`);
+  lines.push(`        /// <param name="cancellationToken">Cancellation token.</param>`);
+  if (responseType) {
+    lines.push(`        /// <returns>The <see cref="${responseType}"/> result.</returns>`);
+  }
+
+  // Signature
+  const sigParams: string[] = [];
+  for (const p of sortPathParamsByTemplateOrder(op)) {
+    sigParams.push(`string ${localName(p.name)}`);
+  }
+  sigParams.push(`${optionsClass} options`);
+  sigParams.push('RequestOptions? requestOptions = null');
+  sigParams.push('CancellationToken cancellationToken = default');
+
+  const returnType = responseType ? `Task<${responseType}>` : 'Task';
+  lines.push(`        public async ${returnType} ${method}(${sigParams.join(', ')})`);
+  lines.push('        {');
+
+  // Set defaults on options
+  for (const [key, value] of Object.entries(wrapper.defaults)) {
+    lines.push(`            options.${csFieldName(key)} = ${csLiteral(value)};`);
+  }
+
+  // Set inferred fields from client. ClientId is required: fail loudly via RequireClientId()
+  // so that callers who forgot to configure it get a clear error instead of a 422 from the API.
+  for (const field of wrapper.inferFromClient) {
+    if (field === 'client_id') {
+      lines.push(`            options.${csFieldName(field)} = this.Client.RequireClientId();`);
+    } else {
+      lines.push(
+        `            options.${csFieldName(field)} = this.Client.${clientFieldExpression(field)} ?? string.Empty;`,
+      );
+    }
+  }
+
+  // Build path
+  let pathExpr: string;
+  if (op.pathParams.length > 0) {
+    let interpolated = op.path;
+    for (const p of sortPathParamsByTemplateOrder(op)) {
+      interpolated = interpolated.replace(`{${p.name}}`, `{${localName(p.name)}}`);
+    }
+    pathExpr = `$"${interpolated}"`;
+  } else {
+    pathExpr = `"${op.path}"`;
+  }
+
+  // Use the Service base-class helper so wrappers read as one-liners.
+  const helper = httpMethodHelperName(op.httpMethod);
+  if (responseType) {
+    lines.push(
+      `            return await this.${helper}<${responseType}>(${pathExpr}, options, requestOptions, cancellationToken);`,
+    );
+  } else if (helper === 'DeleteAsync') {
+    lines.push(`            await this.${helper}(${pathExpr}, options, requestOptions, cancellationToken);`);
+  } else {
+    lines.push(`            await this.${helper}<object>(${pathExpr}, options, requestOptions, cancellationToken);`);
+  }
+
+  lines.push('        }');
+}
+
+// NOTE: T26 (wrapper DRY) — the AuthenticateWith* wrappers share a small
+// SendAuthenticateAsync helper at runtime to avoid 8x copies of the same
+// MakeAPIRequest call. The helper itself lives in UserManagementService.cs as
+// a hand-maintained method (it can't easily be expressed as a generic because
+// the eight options classes don't share an interface). Keeping each generated
+// wrapper's body short is the practical part of the DRY win.
+
+/**
+ * Generate wrapper options classes. Called from resources.ts options generation.
+ */
+export function generateWrapperOptionsClasses(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);
+    const optionsClass = `${csMethodName(wrapper.name)}Options`;
+
+    lines.push('');
+    lines.push(`    public class ${optionsClass} : BaseOptions`);
+    lines.push('    {');
+
+    // Exposed params
+    for (const { paramName, field, isOptional } of wrapperParams) {
+      const csField = csFieldName(paramName);
+      const csType = field ? resolveSimpleCsType(field.type, isOptional) : isOptional ? 'string?' : 'string';
+      const needsDefault = !isOptional && !csType.endsWith('?') && !(field && isValueTypeRef(field.type));
+      const initializer = needsDefault ? ' = default!;' : '';
+
+      const isRequiredEnum = !isOptional && !!field && isEnumRef(field.type);
+      lines.push(...emitXmlDoc(field?.description, '        '));
+      lines.push(...emitJsonPropertyAttributes(paramName, { isRequiredEnum }));
+      lines.push(`        public ${csType} ${csField} { get; set; }${initializer}`);
+      lines.push('');
+    }
+
+    // Hidden fields (defaults + inferred)
+    for (const key of Object.keys(wrapper.defaults)) {
+      const csField = csFieldName(key);
+      lines.push(`        [JsonProperty("${key}")]`);
+      lines.push(`        [STJS.JsonPropertyName("${key}")]`);
+      lines.push(`        internal string ${csField} { get; set; } = default!;`);
+      lines.push('');
+    }
+    for (const key of wrapper.inferFromClient) {
+      const csField = csFieldName(key);
+      // Skip if already added as a default
+      if (Object.keys(wrapper.defaults).includes(key)) continue;
+      lines.push(`        [JsonProperty("${key}")]`);
+      lines.push(`        [STJS.JsonPropertyName("${key}")]`);
+      lines.push(`        internal string ${csField} { get; set; } = default!;`);
+      lines.push('');
+    }
+
+    lines.push('    }');
+  }
+
+  return lines;
+}
+
+function resolveSimpleCsType(ref: any, isOptional: boolean): string {
+  const base = mapTypeRef(ref);
+  if (isOptional && !base.endsWith('?')) return `${base}?`;
+  return base;
+}

package/src/go/client.ts

@@ -0,0 +1,141 @@
+import type { ApiSpec, EmitterContext, GeneratedFile, Service } from '@workos/oagen';
+import { toPascalCase, toSnakeCase } from '@workos/oagen';
+// naming utilities used indirectly via resolveResourceClassName
+import { resolveResourceClassName } from './resources.js';
+import { unexportedName } from './naming.js';
+import { getMountTarget } from '../shared/resolved-ops.js';
+
+/**
+ * Generate the Go client file with service accessors.
+ * Produces: workos.go (Client struct + constructor + service accessors).
+ * Static files (client.go, pagination.go, errors.go, go.mod, options.go)
+ * are hand-maintained in the target SDK with @oagen-ignore-file.
+ */
+export function generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+  return [generateWorkOSFile(spec, ctx)];
+}
+
+/**
+ * Deduplicate services by mount target.
+ */
+function deduplicateByMount(services: Service[], ctx: EmitterContext): Service[] {
+  const byTarget = new Map<string, Service>();
+  for (const s of services) {
+    const target = getMountTarget(s, ctx);
+    const existing = byTarget.get(target);
+    if (!existing || toPascalCase(s.name) === target) {
+      byTarget.set(target, s);
+    }
+  }
+  return [...byTarget.values()];
+}
+
+/**
+ * Build map of service name -> accessor property name.
+ */
+export function buildServiceAccessPaths(services: Service[], ctx: EmitterContext): Map<string, string> {
+  const topLevel = deduplicateByMount(services, ctx);
+  const paths = new Map<string, string>();
+
+  for (const service of topLevel) {
+    const resolvedName = resolveResourceClassName(service, ctx);
+    const prop = toSnakeCase(resolvedName);
+    paths.set(service.name, prop);
+  }
+
+  // Also map mount targets
+  for (const service of services) {
+    const target = getMountTarget(service, ctx);
+    if (!paths.has(target)) {
+      const existing = paths.get(service.name);
+      if (existing) paths.set(target, existing);
+    }
+  }
+
+  return paths;
+}
+
+function generateWorkOSFile(spec: ApiSpec, ctx: EmitterContext): GeneratedFile {
+  const topLevel = deduplicateByMount(spec.services, ctx);
+  const lines: string[] = [];
+
+  lines.push(`package ${ctx.namespace}`);
+  lines.push('');
+  lines.push('import "net/http"');
+  lines.push('');
+
+  // Client struct
+  lines.push('// Client is the WorkOS API client.');
+  lines.push('type Client struct {');
+  lines.push('\tapiKey       string');
+  lines.push('\tclientID     string');
+  lines.push('\tbaseURL      string');
+  lines.push('\thttpClient   *http.Client');
+  lines.push('\tmaxRetries   int');
+  lines.push('');
+  // Service fields
+  for (const service of topLevel) {
+    const resolvedName = resolveResourceClassName(service, ctx);
+    const fieldNameStr = unexportedName(resolvedName);
+    const serviceTypeName = serviceType(resolvedName);
+    lines.push(`\t${fieldNameStr} *${serviceTypeName}`);
+  }
+  lines.push('}');
+  lines.push('');
+
+  // NewClient constructor
+  lines.push('// NewClient creates a new WorkOS API client.');
+  lines.push('func NewClient(apiKey string, opts ...ClientOption) *Client {');
+  lines.push('\tc := &Client{');
+  lines.push('\t\tapiKey:     apiKey,');
+  lines.push('\t\tbaseURL:    defaultBaseURL,');
+  lines.push('\t\thttpClient: &http.Client{Timeout: defaultTimeout},');
+  lines.push('\t\tmaxRetries: defaultMaxRetries,');
+  lines.push('\t}');
+  lines.push('\tfor _, opt := range opts {');
+  lines.push('\t\topt(c)');
+  lines.push('\t}');
+  // Initialize services
+  for (const service of topLevel) {
+    const resolvedName = resolveResourceClassName(service, ctx);
+    const fieldNameStr = unexportedName(resolvedName);
+    const serviceTypeName = serviceType(resolvedName);
+    lines.push(`\tc.${fieldNameStr} = &${serviceTypeName}{client: c}`);
+  }
+  lines.push('\treturn c');
+  lines.push('}');
+  lines.push('');
+
+  // Service accessor methods
+  for (const service of topLevel) {
+    const resolvedName = resolveResourceClassName(service, ctx);
+    const accessorName = resolvedName;
+    const fieldNameStr = unexportedName(resolvedName);
+    const serviceTypeName = serviceType(resolvedName);
+    lines.push(`// ${accessorName} returns the ${resolvedName} service.`);
+    lines.push(`func (c *Client) ${accessorName}() *${serviceTypeName} {`);
+    lines.push(`\treturn c.${fieldNameStr}`);
+    lines.push('}');
+    lines.push('');
+  }
+
+  return {
+    path: `${ctx.namespace}.go`,
+    content: lines.join('\n'),
+    overwriteExisting: true,
+  };
+}
+
+function singularizePascal(name: string): string {
+  if (name.endsWith('ies')) {
+    return `${name.slice(0, -3)}y`;
+  }
+  if (name.endsWith('s') && !name.endsWith('ss')) {
+    return name.slice(0, -1);
+  }
+  return name;
+}
+
+function serviceType(name: string): string {
+  return `${unexportedName(singularizePascal(name))}Service`;
+}