@workos/oagen-emitters 0.3.0 → 0.4.0

package/src/php/resources.ts

@@ -50,8 +50,11 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
     lines.push(`namespace ${ctx.namespacePascal}\\Service;`);
     lines.push('');
 
+    // Build resolved lookup early — used by both imports and method generation
+    const resolvedLookup = buildResolvedLookup(ctx);
+
     // Collect imports
-    const imports = collectImports(mergedService, ctx);
+    const imports = collectImports(mergedService, ctx, resolvedLookup);
     for (const imp of imports) {
       lines.push(`use ${imp};`);
     }
@@ -66,7 +69,6 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
 
     // Track emitted method names to avoid duplicates
     const emittedMethods = new Set<string>();
-    const resolvedLookup = buildResolvedLookup(ctx);
     for (const op of operations) {
       const method = resolveMethodName(op, mergedService, ctx);
       if (emittedMethods.has(method)) continue;
@@ -94,6 +96,29 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
   return files;
 }
 
+/**
+ * Check if an operation is a redirect endpoint that should construct a URL
+ * instead of making an HTTP request.
+ *
+ * Detection: GET endpoints with no response body (primitive unknown) and query
+ * params are redirect endpoints (e.g., SSO/OAuth authorize and logout flows).
+ * Also respects an explicit urlBuilder flag on the resolved operation and
+ * catches endpoints with 302 success responses.
+ */
+export function isRedirectEndpoint(op: Operation, resolvedOp?: ResolvedOperation): boolean {
+  if ((resolvedOp as any)?.urlBuilder) return true;
+  if ((op as any).successResponses?.some((r: any) => r.statusCode >= 300 && r.statusCode < 400)) return true;
+  if (
+    op.httpMethod === 'get' &&
+    op.response.kind === 'primitive' &&
+    (op.response as any).type === 'unknown' &&
+    op.queryParams.length > 0
+  ) {
+    return true;
+  }
+  return false;
+}
+
 function generateMethod(
   lines: string[],
   op: Operation,
@@ -112,8 +137,9 @@ function generateMethod(
     ...getOpInferFromClient(resolvedOp),
   ]);
 
+  const isRedirect = isRedirectEndpoint(op, resolvedOp);
   const params = buildMethodParams(op, plan, modelMap, ctx, hiddenParams);
-  const returnType = getReturnType(plan, ctx);
+  const returnType = isRedirect ? 'string' : getReturnType(plan, ctx);
 
   // PHPDoc block
   const docParts: string[] = [];
@@ -183,6 +209,16 @@ function generateMethod(
     docParts.push(`@return ${returnType}`);
   }
 
+  // @throws — scope to what the method actually calls
+  if (!isRedirect) {
+    // HTTP methods can throw any WorkOSException (config, transport, API response)
+    docParts.push(`@throws \\${ctx.namespacePascal}\\Exception\\WorkOSException`);
+  } else if (getOpInferFromClient(resolvedOp).length > 0) {
+    // Redirect endpoints that inject client fields can throw ConfigurationException
+    docParts.push(`@throws \\${ctx.namespacePascal}\\Exception\\ConfigurationException`);
+  }
+  // Redirect endpoints with no inferFromClient: buildUrl() is pure, no @throws
+
   if (op.deprecated) docParts.push('@deprecated');
   lines.push(...phpDocComment(docParts.join('\n'), 4));
 
@@ -198,7 +234,41 @@ function generateMethod(
   const httpMethod = op.httpMethod.toUpperCase();
   const path = buildPathString(op);
 
-  if (plan.isPaginated) {
+  if (isRedirect) {
+    // Redirect endpoint: construct URL client-side instead of making HTTP request
+    const queryLines = buildQueryArray(op, hiddenParams);
+    const hasDefaults = Object.keys(getOpDefaults(resolvedOp)).length > 0;
+    const hasInferred = getOpInferFromClient(resolvedOp).length > 0;
+    const needsQuery = queryLines.length > 0 || hasDefaults || hasInferred;
+
+    if (needsQuery) {
+      const hasOptionalQuery = op.queryParams.some((q) => !q.required && !hiddenParams.has(q.name));
+      if (hasOptionalQuery) {
+        lines.push('        $query = array_filter([');
+      } else {
+        lines.push('        $query = [');
+      }
+      for (const q of queryLines) {
+        lines.push(`            ${q}`);
+      }
+      // Inject constant defaults
+      for (const [key, value] of Object.entries(getOpDefaults(resolvedOp))) {
+        lines.push(`            '${key}' => ${phpLiteral(value)},`);
+      }
+      if (hasOptionalQuery) {
+        lines.push('        ], fn ($v) => $v !== null);');
+      } else {
+        lines.push('        ];');
+      }
+      // Inject fields from client config
+      for (const clientField of getOpInferFromClient(resolvedOp)) {
+        lines.push(`        $query['${clientField}'] = ${clientFieldExpression(clientField)};`);
+      }
+      lines.push(`        return $this->client->buildUrl(${path}, $query, $options);`);
+    } else {
+      lines.push(`        return $this->client->buildUrl(${path}, [], $options);`);
+    }
+  } else if (plan.isPaginated) {
     const queryLines = buildQueryArray(op);
     if (queryLines.length > 0) {
       lines.push('        $query = array_filter([');
@@ -534,13 +604,18 @@ function clientFieldExpression(field: string): string {
   }
 }
 
-function collectImports(service: Service, ctx: EmitterContext): string[] {
+function collectImports(
+  service: Service,
+  ctx: EmitterContext,
+  resolvedLookup?: Map<string, ResolvedOperation>,
+): string[] {
   const imports = new Set<string>();
   const ns = ctx.namespacePascal;
 
   for (const op of service.operations) {
     const plan = planOperation(op);
-    if (plan.responseModelName && !plan.isPaginated) {
+    const resolved = resolvedLookup ? lookupResolved(op, resolvedLookup) : undefined;
+    if (plan.responseModelName && !plan.isPaginated && !isRedirectEndpoint(op, resolved)) {
       imports.add(`${ns}\\Resource\\${className(plan.responseModelName)}`);
     }
     if (op.pagination?.itemType.kind === 'model') {

package/src/php/tests.ts

@@ -7,12 +7,19 @@ import type {
   Model,
   ResolvedOperation,
 } from '@workos/oagen';
-import { planOperation, toCamelCase } from '@workos/oagen';
+import { planOperation, toCamelCase, toPascalCase } from '@workos/oagen';
 import { className, enumClassName, resolveMethodName, snakeName, servicePropertyName } from './naming.js';
 import { isListWrapperModel } from './models.js';
 import { generateFixtures } from './fixtures.js';
-import { getMountTarget, groupByMount, buildHiddenParams } from '../shared/resolved-ops.js';
+import {
+  getMountTarget,
+  groupByMount,
+  buildHiddenParams,
+  getOpDefaults,
+  getOpInferFromClient,
+} from '../shared/resolved-ops.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
+import { isRedirectEndpoint } from './resources.js';
 
 /**
  * Generate PHPUnit test files and fixture JSON files.
@@ -20,16 +27,6 @@ import { resolveWrapperParams } from '../shared/wrapper-utils.js';
 export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
   const files: GeneratedFile[] = [];
 
-  // Generate fixture JSON files
-  const fixtures = generateFixtures(spec);
-  for (const fixture of fixtures) {
-    files.push({
-      path: fixture.path,
-      content: fixture.content,
-      headerPlacement: 'skip',
-    });
-  }
-
   // TestHelper is now hand-maintained in the target SDK (@oagen-ignore-file).
 
   // Collect all operations per mount target using resolved per-operation mounts.
@@ -72,6 +69,16 @@ export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
     overwriteExisting: true,
   });
 
+  // Generate fixture JSON files
+  const fixtures = generateFixtures(spec);
+  for (const fixture of fixtures) {
+    files.push({
+      path: fixture.path,
+      content: fixture.content,
+      headerPlacement: 'skip',
+    });
+  }
+
   return files;
 }
 
@@ -146,6 +153,17 @@ function generateMountGroupTest(
       lines.push(`        $this->assertStringEndsWith('${expectedPath}', $request->getUri()->getPath());`);
       // Query string serialization assertions
       emitQueryAssertions(lines, op, ctx, hidden);
+    } else if (isRedirectEndpoint(op, resolvedOp)) {
+      // Redirect endpoint: URL is built locally, no HTTP request made.
+      // Pass all params (including optional) to verify they appear in the URL.
+      lines.push('        $client = $this->createMockClient([]);');
+      lines.push(
+        `        $result = $client->${accessor}()->${method}(${buildTestArgs(op, ctx, { includeOptional: true, hidden })});`,
+      );
+      lines.push('        $this->assertIsString($result);');
+      lines.push(`        $this->assertStringContainsString('${expectedPath}', $result);`);
+      // Query param assertions for the generated URL
+      emitRedirectQueryAssertions(lines, op, ctx, hidden, resolvedOp);
     } else if (plan.responseModelName) {
       const modelName = className(plan.responseModelName);
       const fixtureName = `${snakeName(plan.responseModelName)}`;
@@ -363,11 +381,8 @@ function generateTestValue(ref: { kind: string; type?: string; name?: string },
         const e = ctx.spec.enums.find((en) => en.name === ref.name);
         if (e && e.values.length > 0) {
           const enumClass = enumClassName(ref.name);
-          const caseName = String(e.values[0].name)
-            .split(/[_\s-]+/)
-            .filter(Boolean)
-            .map((p) => p.charAt(0).toUpperCase() + p.slice(1).toLowerCase())
-            .join('');
+          // Must match the case-name logic in enums.ts
+          const caseName = toPascalCase(String(e.values[0].name).toLowerCase());
           return `\\WorkOS\\Resource\\${enumClass}::${caseName}`;
         }
       }
@@ -375,6 +390,13 @@ function generateTestValue(ref: { kind: string; type?: string; name?: string },
     }
     case 'array':
       return '[]';
+    case 'map':
+      return '[]';
+    case 'nullable':
+      return generateTestValue(
+        (ref as unknown as { inner: { kind: string; type?: string; name?: string } }).inner,
+        ctx,
+      );
     case 'model': {
       if (ref.name) {
         const modelClass = className(ref.name);
@@ -499,6 +521,60 @@ function emitQueryAssertions(lines: string[], op: Operation, ctx: EmitterContext
   }
 }
 
+/**
+ * Emit query param assertions for redirect endpoint URLs.
+ * Parses the query string from the built URL and asserts visible params,
+ * hidden defaults (e.g., response_type), and inferred client fields (e.g., client_id).
+ */
+function emitRedirectQueryAssertions(
+  lines: string[],
+  op: Operation,
+  ctx: EmitterContext,
+  hidden: Set<string>,
+  resolvedOp?: ResolvedOperation,
+): void {
+  const hasVisibleQueryParams = op.queryParams.some((q) => !hidden.has(q.name));
+  const defaults = getOpDefaults(resolvedOp);
+  const inferred = getOpInferFromClient(resolvedOp);
+  if (!hasVisibleQueryParams && Object.keys(defaults).length === 0 && inferred.length === 0) return;
+
+  lines.push("        parse_str(parse_url($result, PHP_URL_QUERY) ?? '', $query);");
+
+  // Assert visible query params (same logic as emitQueryAssertions but reading from $query parsed from URL)
+  for (const q of op.queryParams) {
+    if (hidden.has(q.name)) continue;
+    const innerType =
+      q.type.kind === 'nullable' ? (q.type as { inner: { kind: string; type?: string; name?: string } }).inner : q.type;
+    if (innerType.kind === 'enum' && innerType.name) {
+      const e = ctx.spec.enums.find((en) => en.name === innerType.name);
+      if (e && e.values.length > 0) {
+        lines.push(`        $this->assertSame('${e.values[0].value}', $query['${q.name}']);`);
+      }
+    } else if (innerType.kind === 'primitive') {
+      switch (innerType.type) {
+        case 'string':
+          lines.push(`        $this->assertSame('test_value', $query['${q.name}']);`);
+          break;
+        case 'integer':
+        case 'number':
+        case 'boolean':
+          lines.push(`        $this->assertArrayHasKey('${q.name}', $query);`);
+          break;
+      }
+    }
+  }
+
+  // Assert hidden defaults (e.g., response_type => 'code')
+  for (const [key, value] of Object.entries(defaults)) {
+    lines.push(`        $this->assertSame('${value}', $query['${key}']);`);
+  }
+
+  // Assert inferred client fields are present (e.g., client_id)
+  for (const key of inferred) {
+    lines.push(`        $this->assertArrayHasKey('${key}', $query);`);
+  }
+}
+
 /**
  * Emit body field assertions for POST/PUT/PATCH operations.
  * Only asserts primitive required fields (strings, numbers, booleans).

package/src/php/wrappers.ts

@@ -38,6 +38,7 @@ function emitWrapperMethod(
   const op2 = resolvedOp.operation;
   const returnDocType = op2.response.kind === 'model' ? `\\${ns}\\Resource\\${className(op2.response.name)}` : 'mixed';
   docParts.push(`@return ${returnDocType}`);
+  docParts.push(`@throws \\${ns}\\Exception\\WorkOSException`);
   lines.push(...phpDocComment(docParts.join('\n'), 4));
 
   lines.push(`    public function ${method}(`);

package/src/python/client.ts

@@ -7,17 +7,11 @@ import { NON_SPEC_SERVICES } from '../shared/non-spec-services.js';
 
 /** Python-specific wiring for each non-spec service. */
 interface PythonNonSpecWiring {
-  /** Python import line (e.g. "from .vault import Vault, AsyncVault") */
   importLine: string;
-  /** Property name on the client class */
   prop: string;
-  /** Sync class name */
   syncClass: string;
-  /** Async class name, or null if no async variant */
   asyncClass: string | null;
-  /** Constructor expression — 'self' if the class takes the client, '' if stateless */
   ctorArg: 'self' | '';
-  /** One-line docstring for the client property */
   docstring?: string;
 }
 
@@ -159,13 +153,25 @@ function generateWorkOSClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
     const resolvedName = resolveResourceClassName(service, ctx);
     const clsName = className(resolvedName);
     const dirName = serviceDirMap.get(service.name) ?? resolveServiceDir(resolvedName);
-    lines.push(`from .${dirToModule(dirName)}._resource import ${clsName}, Async${clsName}`);
+    const importLine = `from .${dirToModule(dirName)}._resource import ${clsName}, Async${clsName}`;
+    if (importLine.length > 88) {
+      lines.push(`from .${dirToModule(dirName)}._resource import (`);
+      lines.push(`    ${clsName},`);
+      lines.push(`    Async${clsName},`);
+      lines.push(')');
+    } else {
+      lines.push(importLine);
+    }
   }
-  // Non-spec service imports (driven by shared/non-spec-services.ts)
+  // Non-spec service imports — wrapped in ignore markers so the merger
+  // matches them positionally and doesn't displace them.
+  lines.push('');
+  lines.push('# @oagen-ignore-start — non-spec service imports (hand-maintained)');
   for (const s of NON_SPEC_SERVICES) {
     const w = PYTHON_NON_SPEC_WIRING[s.id];
     if (w) lines.push(w.importLine);
   }
+  lines.push('# @oagen-ignore-end');
   lines.push('');
   lines.push('');
 
@@ -188,7 +194,7 @@ function generateWorkOSClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
     generatedProps.add(prop);
   }
   emitCompatClientPropertyAliases(lines, generatedProps, false);
-  emitCompatClientAccessors(lines, false);
+  emitNonSpecClientAccessors(lines, false);
 
   lines.push('');
   lines.push('');
@@ -211,18 +217,38 @@ function generateWorkOSClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
     asyncGeneratedProps.add(prop);
   }
   emitCompatClientPropertyAliases(lines, asyncGeneratedProps, true);
-  emitCompatClientAccessors(lines, true);
+  emitNonSpecClientAccessors(lines, true);
 
   return [
     {
       path: `src/${ctx.namespace}/_client.py`,
       content: lines.join('\n'),
-      integrateTarget: true,
       overwriteExisting: true,
     },
   ];
 }
 
+function emitNonSpecClientAccessors(lines: string[], isAsync: boolean): void {
+  lines.push('');
+  lines.push('    # @oagen-ignore-start — non-spec service accessors (hand-maintained)');
+  for (const s of NON_SPEC_SERVICES) {
+    const w = PYTHON_NON_SPEC_WIRING[s.id];
+    if (!w) continue;
+    const typeName = isAsync ? (w.asyncClass ?? w.syncClass) : w.syncClass;
+    const arg = w.ctorArg === 'self' ? 'self' : '';
+
+    lines.push('');
+    lines.push('    @functools.cached_property');
+    lines.push(`    def ${w.prop}(self) -> ${typeName}:`);
+    if (w.docstring) {
+      lines.push(`        """${w.docstring}"""`);
+    }
+    lines.push(`        return ${typeName}(${arg})`);
+  }
+  lines.push('');
+  lines.push('    # @oagen-ignore-end');
+}
+
 function generateServiceInits(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
   const files: GeneratedFile[] = [];
   const topLevel = deduplicateByMount(spec.services, ctx);
@@ -274,24 +300,6 @@ function emitCompatClientPropertyAliases(lines: string[], generatedProps: Set<st
   }
 }
 
-function emitCompatClientAccessors(lines: string[], isAsync: boolean): void {
-  for (const s of NON_SPEC_SERVICES) {
-    const w = PYTHON_NON_SPEC_WIRING[s.id];
-    if (!w) continue;
-    // Skip async-only services when emitting the sync client, and vice versa
-    const typeName = isAsync ? (w.asyncClass ?? w.syncClass) : w.syncClass;
-    const arg = w.ctorArg === 'self' ? 'self' : '';
-
-    lines.push('');
-    lines.push('    @functools.cached_property');
-    lines.push(`    def ${w.prop}(self) -> ${typeName}:`);
-    if (w.docstring) {
-      lines.push(`        """${w.docstring}"""`);
-    }
-    lines.push(`        return ${typeName}(${arg})`);
-  }
-}
-
 /**
  * Generate types/<service>/__init__.py re-export barrels so that
  * `from workos.types.<service> import Model` continues to work.

package/src/python/enums.ts

@@ -42,7 +42,7 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
       const canonicalCls = className(canonicalName);
       const aliasCls = className(enumDef.name);
       const lines: string[] = [];
-      lines.push('from typing_extensions import TypeAlias');
+      lines.push('from typing import TypeAlias');
       // Use explicit __all__ to prevent ruff F401 from stripping the re-export
       // Always use direct file import to avoid barrel dependency on the canonical
       if (canonicalDir === dirName) {
@@ -71,7 +71,7 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
         files.push({
           path: `src/${ctx.namespace}/${dirName}/models/${fileName(aliasName)}.py`,
           content: [
-            'from typing_extensions import TypeAlias',
+            'from typing import TypeAlias',
             importLine,
             '',
             `${aliasName}: TypeAlias = ${canonicalCls}`,
@@ -96,7 +96,7 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
 
     if (enumDef.values.length === 0) {
       lines.push('from typing import Union');
-      lines.push('from typing_extensions import TypeAlias');
+      lines.push('from typing import TypeAlias');
       lines.push('');
       lines.push(`${cls}: TypeAlias = str`);
     } else {
@@ -118,7 +118,7 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
       if (allStrings) {
         lines.push('from enum import Enum');
         lines.push('from typing import Optional');
-        lines.push('from typing_extensions import Literal, TypeAlias');
+        lines.push('from typing import Literal, TypeAlias');
         lines.push('');
         lines.push('');
         lines.push(`class ${cls}(str, Enum):`);
@@ -126,7 +126,7 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
         lines.push('');
       } else if (allIntegers) {
         lines.push('from enum import IntEnum');
-        lines.push('from typing_extensions import Literal, TypeAlias');
+        lines.push('from typing import Literal, TypeAlias');
         lines.push('');
         lines.push('');
         lines.push(`class ${cls}(IntEnum):`);
@@ -135,7 +135,7 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
       } else {
         // Mixed types — fall back to Union[Literal[...], str]
         lines.push('from typing import Union');
-        lines.push('from typing_extensions import Literal, TypeAlias');
+        lines.push('from typing import Literal, TypeAlias');
         lines.push('');
         const literals = uniqueValues.map((v) => (typeof v.value === 'string' ? `"${v.value}"` : String(v.value)));
         lines.push(`${cls}: TypeAlias = Union[Literal[${literals.join(', ')}], str]`);
@@ -196,7 +196,7 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
       files.push({
         path: `src/${ctx.namespace}/${dirName}/models/${fileName(aliasName)}.py`,
         content: [
-          'from typing_extensions import TypeAlias',
+          'from typing import TypeAlias',
           `from .${fileName(enumDef.name)} import ${cls}`,
           '',
           `${aliasName}: TypeAlias = ${cls}`,

package/src/python/models.ts

@@ -62,7 +62,7 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
       const canonicalDir = resolveDir(canonicalService);
       const canonicalClassName = className(canonicalName);
       const lines: string[] = [];
-      lines.push('from typing_extensions import TypeAlias');
+      lines.push('from typing import TypeAlias');
       // Always use direct file import to avoid barrel dependency on the canonical
       if (canonicalDir === dirName) {
         lines.push(`from .${fileName(canonicalName)} import ${canonicalClassName}`);

package/src/python/naming.ts

@@ -1,24 +1,7 @@
 import type { Operation, Service, EmitterContext } from '@workos/oagen';
 import { toPascalCase, toSnakeCase } from '@workos/oagen';
 import { buildResolvedLookup, lookupMethodName, getMountTarget } from '../shared/resolved-ops.js';
-import { stripUrnPrefix } from '../shared/naming-utils.js';
-
-/**
- * Map of lowercase acronym forms to their correct casing.
- * Applied as a post-processing step after toPascalCase.
- */
-const ACRONYM_FIXES: [RegExp, string][] = [
-  [/Workos/g, 'WorkOS'],
-  [/Sso/g, 'SSO'],
-  [/Mfa/g, 'MFA'],
-  [/Jwt/g, 'JWT'],
-  [/Cors/g, 'CORS'],
-  [/Saml/g, 'SAML'],
-  [/Scim/g, 'SCIM'],
-  [/Rbac/g, 'RBAC'],
-  [/Oauth/g, 'OAuth'],
-  [/Oidc/g, 'OIDC'],
-];
+import { stripUrnPrefix, applyAcronymFixes } from '../shared/naming-utils.js';
 
 /**
  * Python class names that collide with builtins or typing imports.
@@ -41,10 +24,7 @@ const PYTHON_RESERVED_CLASS_NAMES = new Set([
 
 /** PascalCase class name with acronym preservation. */
 export function className(name: string): string {
-  let result = toPascalCase(stripUrnPrefix(name));
-  for (const [pattern, replacement] of ACRONYM_FIXES) {
-    result = result.replace(pattern, replacement);
-  }
+  let result = applyAcronymFixes(toPascalCase(stripUrnPrefix(name)));
   if (PYTHON_RESERVED_CLASS_NAMES.has(result)) {
     result += 'Model';
   }