@workos/oagen 0.3.0 → 0.4.0

package/dist/smoke.mjs

@@ -3,7 +3,7 @@ import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { BaseResolver, bundleDocument, createConfig, makeDocumentFromString } from "@redocly/openapi-core";
+import { BaseResolver, Oas3_1Types, bundleDocument, createConfig, makeDocumentFromString } from "@redocly/openapi-core";
 //#region src/utils/naming.ts
 /**
 * Known compound tokens that the regex-based splitter over-splits.
@@ -86,11 +86,7 @@ function toSnakeCase(s) {
 function toUpperSnakeCase(s) {
 	return splitWords(s).map((w) => w.toUpperCase()).join("_");
 }
-const BACKEND_SUFFIXES = [
-	"Dto",
-	"DTO",
-	"Controller"
-];
+const BACKEND_SUFFIXES = ["Controller"];
 function stripBackendSuffixes(name) {
 	for (const suffix of BACKEND_SUFFIXES) if (name.endsWith(suffix) && name.length > suffix.length) return name.slice(0, -suffix.length);
 	return name;
@@ -117,7 +113,9 @@ const SINGULAR_SAFE_LIST = new Set([
 	"Canvas",
 	"Alias",
 	"Basis",
-	"Bus"
+	"Bus",
+	"Species",
+	"Series"
 ]);
 /**
 * Conservative singularize for the leading PascalCase word.
@@ -145,6 +143,120 @@ function cleanSchemaName(name) {
 	return result;
 }
 //#endregion
+//#region src/ir/sdk-behavior.ts
+/**
+* Canonical SDK behavior defaults. These match the PHP emitter's current
+* implementation (the most complete). Per-language overrides can be applied
+* via `mergeSdkBehavior()` in each SDK's `oagen.config.ts`.
+*
+* - Retry: exponential backoff with jitter, retries on 429/5xx
+* - Errors: standard HTTP status → exception kind mapping
+* - Telemetry: enabled by default, tracks request ID + latency
+* - Pagination: no inter-page delay (Node overrides to 350ms)
+* - Idempotency: auto-generate UUID v4 for retryable POSTs
+* - Logging: all lifecycle events enabled
+* - User-Agent: SDK identifier + runtime version + app info + AI agent detection
+* - Request guards: detect misplaced RequestOptions keys in params
+* - Timeout: 60s default (Python overrides to 30s)
+*/
+function defaultSdkBehavior() {
+	return {
+		retry: {
+			retryableStatusCodes: [
+				429,
+				500,
+				502,
+				503,
+				504
+			],
+			maxRetries: 3,
+			retryOnConnectionError: true,
+			retryOnTimeout: true,
+			backoff: {
+				initialDelay: 1,
+				multiplier: 2,
+				maxDelay: 30,
+				jitterFactor: .5
+			}
+		},
+		errors: {
+			statusCodeMap: {
+				400: "BadRequest",
+				401: "Authentication",
+				403: "Authorization",
+				404: "NotFound",
+				409: "Conflict",
+				422: "UnprocessableEntity",
+				429: "RateLimitExceeded"
+			},
+			serverErrorKind: "Server",
+			clientErrorKind: "Api",
+			errorDocUrlTemplate: "https://workos.com/docs/errors/{code}"
+		},
+		telemetry: {
+			enabledByDefault: true,
+			headerName: "X-WorkOS-Client-Telemetry",
+			requestIdHeader: "X-Request-ID"
+		},
+		pagination: { autoPageDelayMs: 0 },
+		idempotency: {
+			headerName: "Idempotency-Key",
+			autoGenerateForPost: true
+		},
+		logging: {
+			enabled: true,
+			events: [
+				"request.start",
+				"request.success",
+				"request.retry",
+				"request.rate_limited",
+				"request.error",
+				"request.connection_error"
+			]
+		},
+		userAgent: {
+			sdkIdentifierTemplate: "{name} {lang}/{version}",
+			includeRuntimeVersion: true,
+			allowAppInfo: true,
+			aiAgentEnvVars: [
+				{
+					envVar: "CLAUDE_CODE",
+					agentName: "ClaudeCode"
+				},
+				{
+					envVar: "CURSOR_AGENT",
+					agentName: "Cursor"
+				},
+				{
+					envVar: "CLINE_ACTIVE",
+					agentName: "Cline"
+				},
+				{
+					envVar: "WINDSURF_ACTIVE",
+					agentName: "Windsurf"
+				},
+				{
+					envVar: "COPILOT_AGENT",
+					agentName: "Copilot"
+				}
+			]
+		},
+		requestGuard: { optionKeys: [
+			"api_key",
+			"apiKey",
+			"idempotency_key",
+			"idempotencyKey",
+			"extra_headers",
+			"extraHeaders",
+			"max_retries",
+			"maxRetries",
+			"base_url",
+			"baseUrl"
+		] },
+		timeout: { defaultTimeoutSeconds: 60 }
+	};
+}
+//#endregion
 //#region src/errors.ts
 /**
 * Structured error hierarchy for oagen.
@@ -173,13 +285,11 @@ var SpecParseError = class extends OagenError {
 //#region src/parser/refs.ts
 async function loadAndBundleSpec(specPath) {
 	const absolutePath = resolve(specPath);
-	const document = makeDocumentFromString(await readFile(absolutePath, "utf-8"), pathToFileURL(absolutePath).href);
-	const config = await createConfig({});
-	const resolver = new BaseResolver();
 	const result = await bundleDocument({
-		document,
-		config: config.styleguide,
-		externalRefResolver: resolver,
+		document: makeDocumentFromString(await readFile(absolutePath, "utf-8"), pathToFileURL(absolutePath).href),
+		config: await createConfig({}),
+		types: Oas3_1Types,
+		externalRefResolver: new BaseResolver(),
 		dereference: false
 	});
 	if (result.problems.some((p) => p.severity === "error")) throw new SpecParseError(`Failed to parse spec: ${result.problems.filter((p) => p.severity === "error").map((p) => p.message).join("\n")}`, `Check the OpenAPI spec at "${absolutePath}" for syntax errors. Run a linter such as \`npx @redocly/cli lint ${specPath}\` to identify issues.`);
@@ -321,15 +431,39 @@ function buildInlineModel(name, schema) {
 }
 //#endregion
 //#region src/parser/schemas.ts
-function extractSchemas(schemas) {
+/**
+* Module-level transform set during extractSchemas(). Used by schemaToTypeRef()
+* to apply the same name transform to $ref model/enum references.
+*/
+let activeSchemaNameTransform = null;
+/** Apply cleanSchemaName + the active transform (if any) to a raw schema name. */
+function resolveSchemaName(rawName) {
+	let name = cleanSchemaName(toPascalCase(rawName));
+	if (activeSchemaNameTransform) name = activeSchemaNameTransform(name);
+	return name;
+}
+function extractSchemas(schemas, options) {
 	const enums = [];
 	if (!schemas) return {
 		models: [],
 		enums
 	};
+	if (options?.schemaNameTransform) {
+		const transform = options.schemaNameTransform;
+		const cleanedNames = Object.keys(schemas).map((n) => cleanSchemaName(toPascalCase(n)));
+		const transformedToOriginals = /* @__PURE__ */ new Map();
+		for (const cleaned of cleanedNames) {
+			const transformed = transform(cleaned);
+			if (!transformedToOriginals.has(transformed)) transformedToOriginals.set(transformed, []);
+			transformedToOriginals.get(transformed).push(cleaned);
+		}
+		const unsafeToTransform = /* @__PURE__ */ new Set();
+		for (const [, originals] of transformedToOriginals) if (originals.length > 1) for (const n of originals) unsafeToTransform.add(n);
+		activeSchemaNameTransform = (name) => unsafeToTransform.has(name) ? name : transform(name);
+	} else activeSchemaNameTransform = null;
 	const modelsByCleanName = /* @__PURE__ */ new Map();
 	for (const [name, schema] of Object.entries(schemas)) {
-		const pascalName = cleanSchemaName(toPascalCase(name));
+		const pascalName = resolveSchemaName(name);
 		if (schema.enum) enums.push(extractEnum(pascalName, schema));
 		else {
 			const model = extractModel(pascalName, schema, schemas);
@@ -337,6 +471,12 @@ function extractSchemas(schemas) {
 			if (existing) {
 				if (model.fields.length > existing.fields.length) modelsByCleanName.set(pascalName, model);
 			} else modelsByCleanName.set(pascalName, model);
+			for (const inlineModel of extractDiscriminatedAllOfVariantModels(schema, pascalName)) {
+				const existingInline = modelsByCleanName.get(inlineModel.name);
+				if (existingInline) {
+					if (inlineModel.fields.length > existingInline.fields.length) modelsByCleanName.set(inlineModel.name, inlineModel);
+				} else modelsByCleanName.set(inlineModel.name, inlineModel);
+			}
 		}
 	}
 	const models = [...modelsByCleanName.values()];
@@ -352,6 +492,10 @@ function extractSchemas(schemas) {
 		enums
 	};
 }
+/** Clear the module-level schemaNameTransform. Called by parseSpec() after all extraction phases. */
+function clearSchemaNameTransform() {
+	activeSchemaNameTransform = null;
+}
 /**
 * Walk a single TypeRef and extract inline enum refs as top-level enum definitions.
 * Shared by both schemas.ts (field-level) and parse.ts (model-level) collection passes.
@@ -388,7 +532,7 @@ function collectInlineEnums(fields, enums) {
 function collectNestedInlineModels(ref, fieldName, parentModelName, schemas, models, modelNames, queue) {
 	walkTypeRef(ref, { model: (modelRef) => {
 		if (modelNames.has(modelRef.name)) return;
-		if (Object.keys(schemas).some((k) => cleanSchemaName(toPascalCase(k)) === modelRef.name)) return;
+		if (Object.keys(schemas).some((k) => resolveSchemaName(k) === modelRef.name)) return;
 		const parentSchema = findSchemaByName(parentModelName, schemas);
 		if (!parentSchema) return;
 		const fieldSchema = findNestedFieldSchema(fieldName, parentSchema, schemas);
@@ -403,7 +547,7 @@ function collectNestedInlineModels(ref, fieldName, parentModelName, schemas, mod
 }
 /** Find a component schema by PascalCase name. */
 function findSchemaByName(pascalName, schemas) {
-	for (const [k, v] of Object.entries(schemas)) if (cleanSchemaName(toPascalCase(k)) === pascalName) return v;
+	for (const [k, v] of Object.entries(schemas)) if (resolveSchemaName(k) === pascalName) return v;
 	return null;
 }
 /** Walk into a schema to find a field's sub-schema, resolving allOf. */
@@ -561,13 +705,88 @@ function extractAllOfModel(name, schema, schemas) {
 		fields
 	};
 }
+function extractDiscriminatedAllOfVariantModels(schema, fallbackName) {
+	const models = [];
+	const seenNames = /* @__PURE__ */ new Set();
+	for (const subSchema of schema.allOf ?? []) for (const variant of subSchema.oneOf ?? []) {
+		if (!variant.properties || variant.type !== void 0 && variant.type !== "object") continue;
+		const variantName = deriveDiscriminatedVariantName(variant, fallbackName);
+		for (const model of extractInlineModelDeep(variantName, variant)) {
+			if (seenNames.has(model.name)) continue;
+			seenNames.add(model.name);
+			models.push(model);
+		}
+	}
+	return models;
+}
+function deriveDiscriminatedVariantName(schema, fallbackName) {
+	if (!schema.properties) return fallbackName;
+	for (const name of [
+		"event",
+		"type",
+		"object"
+	]) {
+		const field = schema.properties[name];
+		if (!field) continue;
+		if (typeof field.const === "string") return toPascalCase(field.const);
+		if (field.enum && field.enum.length === 1 && typeof field.enum[0] === "string") return toPascalCase(field.enum[0]);
+	}
+	for (const field of Object.values(schema.properties)) {
+		if (!field) continue;
+		if (typeof field.const === "string") return toPascalCase(field.const);
+		if (field.enum && field.enum.length === 1 && typeof field.enum[0] === "string") return toPascalCase(field.enum[0]);
+	}
+	return fallbackName;
+}
+function extractInlineModelDeep(name, schema) {
+	const requiredSet = new Set(schema.required ?? []);
+	const fields = [];
+	const properties = schema.properties ?? {};
+	const nestedModels = [];
+	for (const [fieldName, fieldSchema] of Object.entries(properties)) {
+		if (!fieldSchema) continue;
+		fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, requiredSet));
+		if (fieldSchema.type === "object" && fieldSchema.properties) nestedModels.push(...extractInlineModelDeep(qualifyNestedInlineName(name, fieldName), fieldSchema));
+		if (fieldSchema.type === "array" && fieldSchema.items?.properties) nestedModels.push(...extractInlineModelDeep(qualifyNestedInlineName(name, fieldName), fieldSchema.items));
+		if (fieldSchema.allOf) {
+			const mergedProperties = {};
+			const mergedRequired = [];
+			for (const sub of fieldSchema.allOf) {
+				if (sub.properties) Object.assign(mergedProperties, sub.properties);
+				if (sub.required) mergedRequired.push(...sub.required);
+			}
+			if (Object.keys(mergedProperties).length > 0) nestedModels.push(...extractInlineModelDeep(qualifyNestedInlineName(name, fieldName), {
+				type: "object",
+				properties: mergedProperties,
+				required: mergedRequired
+			}));
+		}
+		if (fieldSchema.oneOf) {
+			const objectVariant = fieldSchema.oneOf.find((v) => v.properties && (v.type === "object" || !v.type));
+			if (objectVariant) nestedModels.push(...extractInlineModelDeep(qualifyNestedInlineName(name, fieldName), objectVariant));
+		}
+	}
+	return [{
+		name,
+		description: schema.description,
+		fields
+	}, ...nestedModels];
+}
+function qualifyNestedInlineName(parentName, fieldName) {
+	const pascalField = toPascalCase(fieldName);
+	if (pascalField.startsWith(parentName)) return pascalField;
+	const qualified = `${stripListItemMarkers(parentName)}${pascalField}`;
+	const match = qualified.match(/^(.+?)([A-Z][a-z]+s?)$/);
+	if (match && match[2]) return match[1] + singularize(match[2]);
+	return qualified;
+}
 function schemaToTypeRef(schema, contextName, parentModelName) {
 	if (schema.$ref) {
 		const segments = schema.$ref.split("/");
 		const rawName = segments[segments.length - 1];
 		return {
 			kind: "model",
-			name: cleanSchemaName(toPascalCase(rawName))
+			name: resolveSchemaName(rawName)
 		};
 	}
 	if (Array.isArray(schema.type)) {
@@ -831,6 +1050,7 @@ const KNOWN_DATA_PATHS = new Set([
 	"edges"
 ]);
 const PAGINATION_METADATA_PATTERNS = [
+	"meta",
 	"metadata",
 	"pagination",
 	"cursor",
@@ -862,11 +1082,12 @@ function detectListEnvelope(schema) {
 	}
 	if (arrayProps.length === 1 && nonArrayKeys.length >= 1) {
 		const arrayPropName = arrayProps[0];
-		if (KNOWN_DATA_PATHS.has(arrayPropName)) return {
+		const hasPaginationCompanion = nonArrayKeys.some((key) => PAGINATION_METADATA_PATTERNS.some((pattern) => key.toLowerCase().includes(pattern)));
+		if (KNOWN_DATA_PATHS.has(arrayPropName) && hasPaginationCompanion) return {
 			isEnvelope: true,
 			dataPath: arrayPropName
 		};
-		if (nonArrayKeys.some((key) => PAGINATION_METADATA_PATTERNS.some((pattern) => key.toLowerCase().includes(pattern)))) return {
+		if (hasPaginationCompanion) return {
 			isEnvelope: true,
 			dataPath: arrayPropName
 		};
@@ -1170,13 +1391,33 @@ function extractOperations(paths, operationIdTransform) {
 			const op = pathItem[method];
 			if (!op) continue;
 			const serviceName = inferServiceName(path, op.tags?.[0]);
-			const { operation, inlineModels: opModels } = buildOperation(method, path, op, pathLevelParams, operationIdTransform);
+			const { operation, inlineModels: opModels } = buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName);
 			inlineModels.push(...opModels);
 			const ops = serviceMap.get(serviceName) ?? [];
 			ops.push(operation);
 			serviceMap.set(serviceName, ops);
 		}
 	}
+	for (const [serviceName, operations] of serviceMap) {
+		const pathGroups = /* @__PURE__ */ new Map();
+		for (const op of operations) {
+			const firstSeg = op.path.split("/").filter(Boolean)[0] ?? "";
+			const groupKey = firstSeg.startsWith("{") ? serviceName : toPascalCase(firstSeg);
+			const group = pathGroups.get(groupKey) ?? [];
+			group.push(op);
+			pathGroups.set(groupKey, group);
+		}
+		if (pathGroups.size > 1) {
+			if ([...pathGroups.keys()].some((k) => k !== serviceName)) {
+				serviceMap.delete(serviceName);
+				for (const [groupName, groupOps] of pathGroups) {
+					const existing = serviceMap.get(groupName) ?? [];
+					existing.push(...groupOps);
+					serviceMap.set(groupName, existing);
+				}
+			}
+		}
+	}
 	for (const [, operations] of serviceMap) disambiguateOperationNames(operations);
 	return {
 		services: Array.from(serviceMap.entries()).map(([name, operations]) => ({
@@ -1292,13 +1533,14 @@ function inferDeeperContext(path) {
 	if (nonParams.length >= 3) return toPascalCase(nonParams.slice(1, -1).join("_"));
 	return null;
 }
-function buildOperation(method, path, op, pathLevelParams, operationIdTransform) {
+function buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName) {
 	const allParams = [...pathLevelParams, ...op.parameters ?? []];
 	const hasIdempotencyHeader = allParams.some((p) => p.in === "header" && p.name.toLowerCase() === "idempotency-key");
-	const pathParams = extractParams(allParams, "path");
-	const queryParams = extractParams(allParams, "query");
-	const headerParams = extractParams(allParams, "header").filter((p) => p.name.toLowerCase() !== "idempotency-key");
-	const cookieParams = extractParams(allParams, "cookie");
+	const opContext = serviceName;
+	const pathParams = extractParams(allParams, "path", opContext);
+	const queryParams = extractParams(allParams, "query", opContext);
+	const headerParams = extractParams(allParams, "header", opContext).filter((p) => p.name.toLowerCase() !== "idempotency-key");
+	const cookieParams = extractParams(allParams, "cookie", opContext);
 	const reqBodyModels = [];
 	const { body: requestBody, encoding: requestBodyEncoding } = extractRequestBody(op.requestBody, op, reqBodyModels);
 	const { response, successResponses, errors, inlineModels, isPaginated, dataPath: responseDataPath, itemType: responseItemType } = extractResponses(op.responses, op, path, method);
@@ -1315,6 +1557,7 @@ function buildOperation(method, path, op, pathLevelParams, operationIdTransform)
 			itemType
 		};
 	} else if (paginationFromParams) pagination = paginationFromParams;
+	const security = extractOperationSecurity(op.security);
 	return {
 		operation: {
 			name: inferOperationName(method, path, op.operationId, operationIdTransform),
@@ -1333,19 +1576,35 @@ function buildOperation(method, path, op, pathLevelParams, operationIdTransform)
 			pagination,
 			injectIdempotencyKey: hasIdempotencyHeader,
 			deprecated: op.deprecated || void 0,
-			async: op["x-oagen-async"]
+			async: op["x-oagen-async"],
+			security
 		},
 		inlineModels
 	};
 }
+/**
+* Extract per-operation security requirements from an OpenAPI security directive.
+* Returns undefined when the operation uses the spec-level default security.
+*
+* OpenAPI security format: `security: [{ schemeName: [scope1, scope2] }]`
+*/
+function extractOperationSecurity(security) {
+	if (!security || security.length === 0) return void 0;
+	const requirements = [];
+	for (const entry of security) for (const [schemeName, scopes] of Object.entries(entry)) requirements.push({
+		schemeName,
+		scopes: scopes ?? []
+	});
+	return requirements.length > 0 ? requirements : void 0;
+}
 function buildDescription(summary, description) {
 	if (summary && description && summary !== description) return `${summary}\n\n${description}`;
 	return description ?? summary;
 }
-function extractParams(params, location) {
+function extractParams(params, location, operationContext) {
 	return params.filter((p) => p.in === location).map((p) => ({
 		name: p.name,
-		type: p.schema ? schemaToTypeRef(p.schema, p.name) : {
+		type: p.schema ? schemaToTypeRef(p.schema, p.name, operationContext ? toPascalCase(operationContext) : void 0) : {
 			kind: "primitive",
 			type: "string"
 		},
@@ -1531,7 +1790,14 @@ function extractResponses(responses, op, path, method) {
 				statusCode: code,
 				type: extractedType
 			});
-		} else if (code >= 400) {
+		} else if (code >= 300 && code < 400) allSuccessResponses.push({
+			statusCode: code,
+			type: {
+				kind: "primitive",
+				type: "unknown"
+			}
+		});
+		else if (code >= 400) {
 			const jsonContent = resp.content?.["application/json"];
 			const type = jsonContent?.schema ? schemaToTypeRef(jsonContent.schema, `Error${code}`) : void 0;
 			errors.push({
@@ -1658,6 +1924,19 @@ function collectInlineEnumsFromModels(models, enums) {
 	const enumNames = new Set(enums.map((e) => e.name));
 	for (const model of models) for (const field of model.fields) collectInlineEnumFromRef(field.type, enums, enumNames);
 }
+/**
+* Collect inline enum definitions from operation parameters (query, path, header)
+* and promote them to top-level enums so emitters can generate typed enum files.
+*/
+function collectInlineEnumsFromOperations(services, enums) {
+	const enumNames = new Set(enums.map((e) => e.name));
+	for (const service of services) for (const op of service.operations) for (const param of [
+		...op.pathParams,
+		...op.queryParams,
+		...op.headerParams,
+		...op.cookieParams ?? []
+	]) collectInlineEnumFromRef(param.type, enums, enumNames);
+}
 //#endregion
 //#region src/parser/normalize-model-refs.ts
 function validateModelRefs(spec) {
@@ -1687,10 +1966,12 @@ async function parseSpec(specPath, options) {
 	const spec = parsed;
 	const version = spec.openapi ?? "";
 	if (!version.startsWith("3.")) throw new SpecParseError(`Unsupported OpenAPI version: ${version}. oagen requires OpenAPI 3.x`, `Update the spec to OpenAPI 3.0 or 3.1. If you are using Swagger 2.x, convert it first with \`npx swagger2openapi ${specPath}\`.`);
-	const { models, enums } = extractSchemas(spec.components?.schemas);
+	const { models, enums } = extractSchemas(spec.components?.schemas, { schemaNameTransform: options?.schemaNameTransform });
 	const { services, inlineModels } = extractOperations(spec.paths, options?.operationIdTransform);
+	clearSchemaNameTransform();
 	const finalModels = collapseJsonSuffixModels(mergeFieldInlineModels(mergeInlineResponseModels(models, inlineModels), extractInlineModelsFromSchemas(spec.components?.schemas)), services);
 	collectInlineEnumsFromModels(finalModels, enums);
+	collectInlineEnumsFromOperations(services, enums);
 	const auth = extractAuthSchemes(spec.components?.securitySchemes);
 	const serverEntries = (spec.servers ?? []).map((s) => ({
 		url: s.url ?? "",
@@ -1705,7 +1986,8 @@ async function parseSpec(specPath, options) {
 		services,
 		models: finalModels,
 		enums,
-		auth
+		auth,
+		sdk: defaultSdkBehavior()
 	};
 	validateModelRefs(result);
 	return result;