@workos/oagen-emitters 0.8.0 → 0.8.2

package/src/kotlin/wrappers.ts

@@ -1,5 +1,5 @@
 import type { EmitterContext, ResolvedOperation, ResolvedWrapper } from '@workos/oagen';
-import { className, propertyName, ktLiteral, clientFieldExpression, escapeReserved } from './naming.js';
+import { className, propertyName, ktLiteral, clientFieldExpression, escapeReserved, humanize } from './naming.js';
 import { mapTypeRef, mapTypeRefOptional } from './type-map.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
 import { sortPathParamsByTemplateOrder } from './resources.js';
@@ -35,7 +35,11 @@ function emitWrapperMethod(resolvedOp: ResolvedOperation, wrapper: ResolvedWrapp
 
   const lines: string[] = [];
 
-  // Build KDoc from operation description + @param docs for each wrapper param.
+  // Build KDoc: operation description + a `@param` line for *every* parameter
+  // (Dokka does not flag missing @param blocks, so coverage has to be enforced
+  // at emit time) + `@return` when there's a response model. Spec-provided
+  // descriptions are preferred; the fallback is templated from the parameter
+  // name so the SDK still compiles cleanly under failOnWarning.
   const kdocLines: string[] = [];
   const opDesc = (op.description ?? '').trim();
   const wrapperHumanName = method.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase();
@@ -45,29 +49,36 @@ function emitWrapperMethod(resolvedOp: ResolvedOperation, wrapper: ResolvedWrapp
     kdocLines.push(`${wrapperHumanName.charAt(0).toUpperCase()}${wrapperHumanName.slice(1)}.`);
   }
   const paramDocs: string[] = [];
+  const pushParamDoc = (kotlinName: string, sourceName: string, description: string | undefined) => {
+    const firstLine =
+      description
+        ?.split('\n')
+        .find((l) => l.trim())
+        ?.trim() ?? '';
+    const fallback = `the ${humanize(sourceName)} of the request.`;
+    const text = firstLine || fallback;
+    paramDocs.push(`@param ${kotlinName} ${escapeKdoc(text)}`);
+  };
   for (const pp of pathParams) {
-    if (pp.description?.trim()) {
-      paramDocs.push(`@param ${propertyName(pp.name)} ${escapeKdoc(pp.description.split('\n')[0].trim())}`);
-    }
+    pushParamDoc(propertyName(pp.name), pp.name, pp.description);
   }
   for (const rp of resolvedParams) {
-    const desc = rp.field?.description?.trim();
-    if (desc) {
-      paramDocs.push(`@param ${propertyName(rp.paramName)} ${escapeKdoc(desc.split('\n')[0])}`);
-    }
+    pushParamDoc(propertyName(rp.paramName), rp.paramName, rp.field?.description);
   }
+  // Trailing `requestOptions` parameter — stable canned phrasing.
+  pushParamDoc(
+    'requestOptions',
+    'request_options',
+    'per-request overrides (idempotency key, API key, headers, timeout)',
+  );
   if (responseClass) {
     paramDocs.push(`@return the ${responseClass}`);
   }
-  if (paramDocs.length > 0 || kdocLines.length > 0) {
-    lines.push('  /**');
-    for (const l of kdocLines) lines.push(`   * ${escapeKdoc(l)}`);
-    if (paramDocs.length > 0) {
-      lines.push('   *');
-      for (const p of paramDocs) lines.push(`   * ${p}`);
-    }
-    lines.push('   */');
-  }
+  lines.push('  /**');
+  for (const l of kdocLines) lines.push(`   * ${escapeKdoc(l)}`);
+  lines.push('   *');
+  for (const p of paramDocs) lines.push(`   * ${p}`);
+  lines.push('   */');
 
   lines.push('  @JvmOverloads');
 
@@ -101,6 +112,37 @@ function emitWrapperMethod(resolvedOp: ResolvedOperation, wrapper: ResolvedWrapp
     lines.push(`  )${returnClause} {`);
   }
 
+  // The /user_management/authenticate endpoint is union-split into one
+  // wrapper per grant_type. Every variant posts the same shape (caller
+  // params + grant_type + client_id + client_secret) to the same path with
+  // the same response model, so we route through a single `authenticate(...)`
+  // private helper instead of duplicating the request boilerplate per grant.
+  const inferred = wrapper.inferFromClient ?? [];
+  const usesStandardClientCreds = inferred.includes('client_id') && inferred.includes('client_secret');
+  if (
+    op.path === '/user_management/authenticate' &&
+    op.httpMethod.toUpperCase() === 'POST' &&
+    responseClass === 'AuthenticateResponse' &&
+    typeof wrapper.defaults?.grant_type === 'string' &&
+    usesStandardClientCreds
+  ) {
+    const grantType = wrapper.defaults.grant_type;
+    lines.push(`    return authenticate(`);
+    lines.push(`      grantType = ${ktLiteral(grantType)},`);
+    lines.push(`      requestOptions = requestOptions,`);
+    const entryLines = resolvedParams.map((rp) => {
+      const paramName = propertyName(rp.paramName);
+      return `      ${ktLiteral(rp.paramName)} to ${paramName}`;
+    });
+    for (let i = 0; i < entryLines.length; i++) {
+      const sep = i === entryLines.length - 1 ? '' : ',';
+      lines.push(`${entryLines[i]}${sep}`);
+    }
+    lines.push(`    )`);
+    lines.push('  }');
+    return lines;
+  }
+
   // Build body using bodyOf() — consistent with non-wrapper methods.
   // bodyOf() automatically drops null optional values.
   const bodyEntries: string[] = [];

package/src/python/client.ts

@@ -286,12 +286,10 @@ function generateServiceInits(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
       overwriteExisting: true,
     });
 
-    // Ensure models/__init__.py exists even if no models are assigned to this service
-    files.push({
-      path: `src/${ctx.namespace}/${dirName}/models/__init__.py`,
-      content: '',
-      skipIfExists: true,
-    });
+    // models/__init__.py is emitted unconditionally by `models.ts` — including
+    // an empty barrel for services with no models — so we don't need a safety
+    // net here. (A `skipIfExists` safety net previously caused stale imports
+    // to survive when the underlying module was pruned.)
   }
 
   return files;

package/src/python/models.ts

@@ -447,6 +447,24 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     serviceDirModelPaths.add(`src/${ctx.namespace}/${dirName}/models`);
   }
 
+  // Emit an empty barrel for every service-models dir that has no symbols of
+  // its own (e.g. a service whose models live in another package via
+  // cross-domain aliases). Otherwise the live SDK can keep a stale
+  // `__init__.py` from a previous spec revision — when the underlying module
+  // gets pruned the dangling re-export survives and breaks pyright. Done here
+  // (not in client.ts) so a subsequent emission for the same path with real
+  // content always wins last-write-wins.
+  for (const dirPath of serviceDirModelPaths) {
+    if (!symbolsByDir.has(dirPath)) {
+      files.push({
+        path: `${dirPath}/__init__.py`,
+        content: '',
+        integrateTarget: true,
+        overwriteExisting: true,
+      });
+    }
+  }
+
   for (const [dirPath, names] of symbolsByDir) {
     // Use `import X as X` syntax for explicit re-exports (required by pyright strict)
     const uniqueNames = [...new Set(names)].sort();
@@ -719,7 +737,12 @@ function deserializeField(ref: any, accessor: string, isRequired: boolean, walru
           const dispatchMap = entries.map(([value, modelName]) => `"${value}": ${className(modelName)}`).join(', ');
           const dataExpr = isRequired ? accessor : walrusVar;
           const dataCast = `cast(Dict[str, Any], ${dataExpr})`;
-          const lookupExpr = `{${dispatchMap}}.get(${dataCast}.get("${ref.discriminator.property}"))`;
+          // The dispatch dict has `str` keys, so pyright (strict) rejects the
+          // raw `Any | None` returned by `.get(prop)` even though `dict.get`
+          // accepts any hashable. Cast through `str` to satisfy the parameter
+          // type — runtime semantics are unchanged because a missing/`None`
+          // discriminator simply misses the dispatch and falls through.
+          const lookupExpr = `{${dispatchMap}}.get(cast(str, ${dataCast}.get("${ref.discriminator.property}")))`;
           const branch = `(_disc.from_dict(${dataCast}) if (_disc := ${lookupExpr}) is not None else ${dataExpr})`;
           if (isRequired) return branch;
           return `(${branch}) if (${walrusVar} := ${accessor}) is not None else None`;
@@ -760,6 +783,12 @@ function serializeField(ref: any, accessor: string): string {
       if (uniqueModels.length === 1) {
         return `${accessor}.to_dict()`;
       }
+      // Discriminated union: deserialize produced a dataclass instance for
+      // known discriminator values and the raw dict for unknowns. Round-trip
+      // both — call `.to_dict()` if it exists, otherwise pass through.
+      if (ref.discriminator && ref.discriminator.mapping && modelVariants.length > 0) {
+        return `${accessor}.to_dict() if hasattr(${accessor}, "to_dict") else ${accessor}`;
+      }
       return accessor;
     }
     default: