@workos/oagen 0.22.7 → 0.23.0

package/README.md

@@ -165,7 +165,7 @@ export default {
     retry: { backoff: { initialDelay: 0.5, maxDelay: 8.0 } },
     timeout: {
       defaultTimeoutSeconds: 30,
-      timeoutEnvVar: "WORKOS_REQUEST_TIMEOUT",
+      timeoutEnvVar: "SDK_REQUEST_TIMEOUT",
     },
     pagination: { autoPageDelayMs: 0 },
   },

package/dist/cli/index.mjs

@@ -14,9 +14,8 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, rea
 import { createHash } from "node:crypto";
 //#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`.
+* Canonical SDK behavior defaults. Per-language or per-project 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
@@ -59,12 +58,11 @@ function defaultSdkBehavior() {
 				429: "RateLimitExceeded"
 			},
 			serverErrorKind: "Server",
-			clientErrorKind: "Api",
-			errorDocUrlTemplate: "https://workos.com/docs/errors/{code}"
+			clientErrorKind: "Api"
 		},
 		telemetry: {
 			enabledByDefault: true,
-			headerName: "X-WorkOS-Client-Telemetry",
+			headerName: "X-Client-Telemetry",
 			requestIdHeader: "X-Request-ID"
 		},
 		pagination: { autoPageDelayMs: 0 },
@@ -2044,11 +2042,11 @@ function inferVerb(method, path) {
 * Uses the last non-param segment (the resource being operated on).
 *
 * Examples:
-*   /user_management/users → "Users"
-*   /user_management/users/{id} → "User" (singular for item operations)
-*   /user_management/users/{id}/auth_factors → "AuthFactors"
+*   /accounts/users → "Users"
+*   /accounts/users/{id} → "User" (singular for item operations)
+*   /accounts/users/{id}/auth_factors → "AuthFactors"
 *   /organizations/{id}/api_keys → "ApiKeys"
-*   /sso/authorize → "Authorize" (action endpoint)
+*   /auth/authorize → "Authorize" (action endpoint)
 */
 function inferResourceFromPath(path) {
 	const segments = path.split("/").filter(Boolean);
@@ -3330,12 +3328,12 @@ function extractKotlinClassMembers(classBody, source) {
 }
 /**
 * KDoc signature that identifies a generator-emitted service accessor inside
-* the WorkOS class. The Kotlin client emitter writes every accessor with this
+* a Kotlin client class. The Kotlin client emitter writes every accessor with this
 * exact doc preamble — when the existing file carries a member with this doc
 * but the regenerated content omits it, the member is stale (its mount target
 * was remapped or removed) and gets pruned.
 */
-const KOTLIN_MANAGED_ACCESSOR_DOC = /\/\*\*[\s\S]*?Lazily-constructed \[[^\]]+\] accessor for this \[WorkOS\] client\.[\s\S]*?\*\//;
+const KOTLIN_MANAGED_ACCESSOR_DOC = /\/\*\*[\s\S]*?Lazily-constructed \[[^\]]+\] accessor for this \[[^\]]+\] client\.[\s\S]*?\*\//;
 const kotlinMergeAdapter = {
 	language: "kotlin",
 	grammarModule: "tree-sitter-kotlin",
@@ -3588,7 +3586,6 @@ const nodeMergeAdapter = {
 		const newText = newMembers.map((m) => m.text).join("\n");
 		for (const match of newText.matchAll(/this\.(\w+)/g)) {
 			const propName = match[1];
-			if (propName === "workos") continue;
 			if (propName && !existingMemberKeys.has(propName)) return true;
 		}
 		return false;
@@ -5719,6 +5716,15 @@ function resolveResponseModelName(op) {
 //#endregion
 //#region src/engine/generate-files.ts
 function buildEmitterContext(spec, options) {
+	const resolvedOperations = resolveOperations(spec, options.operationHints, options.mountRules);
+	let scopedModelNames;
+	let scopedEnumNames;
+	if (options.scopedServices && options.scopedServices.size > 0) {
+		const selected = options.scopedServices;
+		const reachable = collectReferencedNames(spec.services.filter((s) => resolvedOperations.some((r) => r.service.name === s.name && selected.has(r.mountOn))), spec.models, { preserveAllDiscriminated: false });
+		scopedModelNames = reachable.models;
+		scopedEnumNames = reachable.enums;
+	}
 	return {
 		namespace: toSnakeCase(options.namespace),
 		namespacePascal: options.namespace,
@@ -5726,11 +5732,14 @@ function buildEmitterContext(spec, options) {
 		outputDir: options.outputDir,
 		apiSurface: options.apiSurface,
 		overlayLookup: options.overlayLookup,
-		resolvedOperations: resolveOperations(spec, options.operationHints, options.mountRules),
+		resolvedOperations,
 		modelHints: options.modelHints,
 		emitterOptions: options.emitterOptions,
 		targetDir: options.target,
-		priorTargetManifestPaths: options.priorTargetManifestPaths
+		priorTargetManifestPaths: options.priorTargetManifestPaths,
+		scopedServices: options.scopedServices,
+		scopedModelNames,
+		scopedEnumNames
 	};
 }
 /**
@@ -5738,7 +5747,8 @@ function buildEmitterContext(spec, options) {
 * Walks operation parameters, request bodies, responses, and pagination item
 * types, then chases model field references until the set stabilizes.
 */
-function collectReferencedNames(services, models) {
+function collectReferencedNames(services, models, opts = {}) {
+	const preserveAllDiscriminated = opts.preserveAllDiscriminated !== false;
 	const referencedModels = /* @__PURE__ */ new Set();
 	const referencedEnums = /* @__PURE__ */ new Set();
 	const collectFromTypeRef = (ref) => {
@@ -5760,7 +5770,7 @@ function collectReferencedNames(services, models) {
 		for (const err of op.errors) if (err.type) collectFromTypeRef(err.type);
 		if (op.successResponses) for (const sr of op.successResponses) collectFromTypeRef(sr.type);
 	}
-	for (const model of models) {
+	if (preserveAllDiscriminated) for (const model of models) {
 		if (isDiscriminatedModel(model)) referencedModels.add(model.name);
 		const disc = model.discriminator;
 		if (disc?.mapping) for (const variantName of Object.values(disc.mapping)) referencedModels.add(variantName);
@@ -5774,6 +5784,13 @@ function collectReferencedNames(services, models) {
 		visited.add(name);
 		const model = modelsByName.get(name);
 		if (!model) continue;
+		const disc = model.discriminator;
+		if (disc?.mapping) {
+			for (const variantName of Object.values(disc.mapping)) if (!referencedModels.has(variantName)) {
+				referencedModels.add(variantName);
+				queue.push(variantName);
+			}
+		}
 		for (const field of model.fields) {
 			collectFromTypeRef(field.type);
 			for (const m of referencedModels) if (!visited.has(m)) queue.push(m);
@@ -5787,7 +5804,16 @@ function collectReferencedNames(services, models) {
 function isDiscriminatedModel(model) {
 	return model.fields.some((field) => (field.name === "event" || field.name === "type" || field.name === "object") && field.type.kind === "literal");
 }
-/** Collect all generated files from an emitter (no headers, no path prefixes). */
+/**
+* Collect all generated files from an emitter (no headers, no path prefixes).
+*
+* In a scoped (`--services`) run the spec is NOT filtered: every generator runs
+* over the full spec so model placement, dedup, the root client, and all
+* aggregate/barrel files are byte-identical to a full run (and a brand-new
+* selected service is wired into the client automatically). The emitters
+* themselves consult `ctx.scopedServices` to emit only the selected services'
+* per-service resource/test files.
+*/
 function generateAllFiles(spec, emitter, ctx) {
 	const referenced = collectReferencedNames(spec.services, spec.models);
 	const reachableModels = spec.models.filter((m) => referenced.models.has(m.name));
@@ -5828,6 +5854,47 @@ function generateFiles(spec, emitter, options) {
 	};
 }
 //#endregion
+//#region src/engine/scoped-services.ts
+/**
+* Validate a `--services` selection and return it as a set of POST-MOUNT service
+* names for emitters to scope on.
+*
+* Scoped generation does NOT filter the IR: model placement, dedup/aliasing, and
+* shared-schema decisions are global computations over the full service/model set
+* (filtering them churns shared `common/` files). Instead the full spec flows to
+* the emitters unchanged and this set is passed as `ctx.scopedServices`; each
+* emitter gates only its per-service resource/test emission on it.
+*
+* Matching is on the POST-MOUNT name. Mount resolution never mutates
+* `spec.services` — the post-mount target lives on `ResolvedOperation.mountOn`
+* (`mountOn = hint?.mountOn ?? mountRules[service.name] ?? service.name`) — so the
+* post-mount name of a source service is derived here as
+* `mountRules[service.name] ?? service.name`. Selecting a target (e.g.
+* `DirectorySync`) is valid because every source tag that mounts into it
+* (`DirectoryUsers`, `DirectoryGroups`, …) shares that post-mount name, and the
+* emitters group resources by mount, so all siblings emit together.
+*
+* @param spec - The parsed API spec (never mutated; never filtered).
+* @param selected - Post-mount service names from `--services` (normalized/trimmed).
+* @param mountRules - Source-service-name → post-mount-target mappings.
+* @returns The validated selection as a `Set` of post-mount names.
+* @throws A `ConfigError` listing valid post-mount names when a selection is
+*   unknown — scoped generation never silently emits the wrong set.
+*/
+function resolveScopedServices(spec, selected, mountRules) {
+	const mounts = mountRules ?? {};
+	const postMountName = (name) => mounts[name] ?? name;
+	const validPostMount = new Set(spec.services.map((s) => postMountName(s.name)));
+	const selectedSet = new Set(selected);
+	const unknown = [...selectedSet].filter((s) => !validPostMount.has(s));
+	if (unknown.length > 0) {
+		const err = /* @__PURE__ */ new Error(`Unknown --services: ${unknown.sort().join(", ")}. Valid post-mount services: ${[...validPostMount].sort().join(", ")}`);
+		err.name = "ConfigError";
+		throw err;
+	}
+	return selectedSet;
+}
+//#endregion
 //#region src/engine/integrate.ts
 /**
 * Resolve a relative import path against a source file path to get the
@@ -5944,7 +6011,7 @@ function mapFilesForTargetIntegration(files, language) {
 * that would shadow an existing module file (e.g., `api_keys.py`), move the
 * module file's content into `_compat.py` inside the package and add a
 * re-export from `__init__.py`.  This preserves backward-compatible imports
-* (e.g., `from workos.api_keys import ApiKeysModule`) while the package directory
+* (e.g., `from acme.api_keys import ApiKeysModule`) while the package directory
 * provides the generated models and resource classes.
 */
 async function resolveFileToDirectoryConflicts(files, targetDir) {
@@ -6110,6 +6177,35 @@ function computeStalePaths(prev, currentPaths) {
 	return prev.files.filter((p) => !current.has(p)).sort();
 }
 /**
+* Merge a scoped run's emitted records into the prior manifest's records.
+*
+* A scoped (`--services`) run only emits files for the selected services, but it
+* must NOT discard the prior manifest's record of unselected services' files
+* records. The result unions prior + scoped file paths and shallow-merges the
+* operations maps, with scoped operations overriding prior entries for the same
+* "METHOD /path" key (a re-emission updates that operation's record).
+*
+* When `prev` is null (the first-ever run is scoped) there is nothing to
+* preserve, so the scoped subset is returned unchanged — matching the
+* first-adoption behavior of a full run.
+*/
+function mergeScopedManifestRecords(prev, scopedFiles, scopedOperations) {
+	const scopedFileList = [...scopedFiles];
+	if (!prev) return {
+		files: scopedFileList,
+		operations: scopedOperations
+	};
+	const files = [...new Set([...prev.files, ...scopedFileList])].sort();
+	const priorOps = prev.operations;
+	return {
+		files,
+		operations: priorOps || scopedOperations ? {
+			...priorOps,
+			...scopedOperations
+		} : void 0
+	};
+}
+/**
 * Delete stale files from `dir`.
 *
 * When `header` is provided, a file is only deleted if its contents start with
@@ -6178,12 +6274,17 @@ async function removeEmptyParents(startDir, stopDir) {
 //#endregion
 //#region src/engine/orchestrator.ts
 async function generate(spec, emitter, options) {
-	const outputPrevManifestForCtx = options.noPrune ? null : await readManifest(options.outputDir);
-	const targetManifestForCtx = options.target && !options.noPrune ? await readManifest(options.target) : null;
+	const scopedServices = options.services && options.services.length > 0 ? resolveScopedServices(spec, options.services, options.mountRules) : void 0;
+	const scoped = scopedServices !== void 0;
+	const noPrune = options.noPrune === true || scoped;
+	const skipManifestRead = options.noPrune === true && !scoped;
+	const outputPrevManifestForCtx = skipManifestRead ? null : await readManifest(options.outputDir);
+	const targetManifestForCtx = options.target && !skipManifestRead ? await readManifest(options.target) : null;
 	const priorTargetManifestPaths = targetManifestForCtx ? new Set(targetManifestForCtx.files) : outputPrevManifestForCtx ? new Set(outputPrevManifestForCtx.files) : void 0;
 	const { files: withHeaders, header, operations } = generateFiles(spec, emitter, {
 		...options,
-		priorTargetManifestPaths
+		priorTargetManifestPaths,
+		scopedServices
 	});
 	if (options.dryRun) {
 		if (options.target) {
@@ -6207,8 +6308,9 @@ async function generate(spec, emitter, options) {
 		currentPaths: outputEmittedPaths,
 		language: emitter.language,
 		header,
-		noPrune: options.noPrune,
-		operations
+		noPrune,
+		operations,
+		scoped
 	});
 	const allOutputFiles = [...writeResult.written, ...writeResult.merged];
 	if (allOutputFiles.length > 0) await formatTargetFiles(emitter, options.outputDir, allOutputFiles);
@@ -6230,8 +6332,9 @@ async function generate(spec, emitter, options) {
 			currentPaths: targetResult.emittedPaths,
 			language: emitter.language,
 			header,
-			noPrune: options.noPrune,
-			operations
+			noPrune,
+			operations,
+			scoped
 		});
 		const allTargetFiles = [
 			...targetResult.written,
@@ -6247,11 +6350,15 @@ async function generate(spec, emitter, options) {
 * then write the fresh manifest.  Safe on first adoption (no previous manifest).
 */
 async function applyManifestPrune(opts) {
-	const manifestOpts = {
-		language: opts.language,
+	const records = opts.scoped ? mergeScopedManifestRecords(opts.prevManifest, opts.currentPaths, opts.operations) : {
 		files: opts.currentPaths,
 		operations: opts.operations
 	};
+	const manifestOpts = {
+		language: opts.language,
+		files: records.files,
+		operations: records.operations
+	};
 	if (opts.noPrune) {
 		await writeManifest(opts.dir, manifestOpts);
 		return;
@@ -6891,7 +6998,7 @@ function loadOverlayContext(opts) {
 //#region src/utils/expand-doc-urls.ts
 /**
 * Walk all description fields in the IR and expand relative URL paths
-* (e.g. `/reference/authkit/user`) into full URLs using the given base.
+* (e.g. `/reference/users/user`) into full URLs using the given base.
 *
 * Matches markdown-style links: `[text](/path)` → `[text](https://example.com/path)`
 * and bare parenthetical refs: `(/path)` → `(https://example.com/path)`
@@ -6954,6 +7061,7 @@ async function generateCommand(opts) {
 	if (opts.docUrl) ir = expandDocUrls(ir, opts.docUrl);
 	const emitter = getEmitter(opts.lang);
 	const namespace = opts.namespace ?? ir.name;
+	const services = (Array.isArray(opts.services) ? opts.services : opts.services?.split(","))?.map((s) => s.trim()).filter(Boolean);
 	let apiSurface;
 	let overlayLookup;
 	if (opts.apiSurface && opts.compatCheck !== false) {
@@ -6977,7 +7085,8 @@ async function generateCommand(opts) {
 		mountRules: opts.mountRules,
 		modelHints: opts.modelHints,
 		emitterOptions: opts.emitterOptions,
-		noPrune: opts.prune === false
+		noPrune: opts.prune === false,
+		services: services && services.length > 0 ? services : void 0
 	});
 	if (opts.dryRun) for (const f of files) console.log(f.path);
 	else {
@@ -8240,7 +8349,7 @@ function specDerivedFieldPaths(spec, hints) {
 	return paths;
 }
 /**
-* Compute the set of method paths (e.g., "SSO.authorize") that are defined
+* Compute the set of method paths (e.g., "Auth.authorize") that are defined
 * as operations in the OpenAPI spec's services. Used by filterSurface to
 * exclude hand-written SDK methods that don't correspond to spec operations.
 */
@@ -8276,7 +8385,7 @@ function filterRecord(record, allowed) {
 *
 * For classes: when methodPaths is provided, only keeps methods whose names
 * appear in the spec-derived method paths. This prevents false positives from
-* hand-written SDK methods (e.g., SSO.authorization_url, Webhooks.construct_event)
+* hand-written SDK methods (e.g., Auth.authorization_url, Webhooks.construct_event)
 * that don't correspond to spec operations. Properties on service classes are
 * also filtered: only UPPER_CASE constants that are spec-derivable are kept.
 */
@@ -9955,7 +10064,7 @@ program.command("parse").description("Parse an OpenAPI spec and output IR as JSO
 		transformSpec: configTransformSpec
 	});
 });
-program.command("generate").description("Run a registered emitter against an OpenAPI spec").option("--spec <path>", "Path to OpenAPI spec file (or set OPENAPI_SPEC_PATH)").requiredOption("--lang <language>", "Target language").requiredOption("--output <dir>", "Output directory").option("--target <dir>", "Target directory for live SDK integration (merged output)").option("--namespace <name>", "SDK namespace/package name").option("--dry-run", "Preview files without writing").option("--api-surface <path>", "Path to baseline API surface JSON for compat overlay").option("--no-compat-check", "Skip compat overlay even if --api-surface is provided").option("--no-prune", "Skip deletion of stale files recorded in the previous .oagen-manifest.json").action((opts) => {
+program.command("generate").description("Run a registered emitter against an OpenAPI spec").option("--spec <path>", "Path to OpenAPI spec file (or set OPENAPI_SPEC_PATH)").requiredOption("--lang <language>", "Target language").requiredOption("--output <dir>", "Output directory").option("--target <dir>", "Target directory for live SDK integration (merged output)").option("--namespace <name>", "SDK namespace/package name").option("--dry-run", "Preview files without writing").option("--api-surface <path>", "Path to baseline API surface JSON for compat overlay").option("--no-compat-check", "Skip compat overlay even if --api-surface is provided").option("--no-prune", "Skip deletion of stale files recorded in the previous .oagen-manifest.json").option("--services <list>", "Comma-separated post-mount service names to generate (default: all)").action((opts) => {
 	opts.spec ??= process.env.OPENAPI_SPEC_PATH;
 	if (!opts.spec) {
 		console.error("error: --spec <path> or OPENAPI_SPEC_PATH env var is required");