@workos/oagen 0.30.2 → 0.31.0

package/docs/cli.md

@@ -301,16 +301,16 @@ export default config;
 
 ### Options
 
-| Key                    | Type                                         | Description                                                                                                                                                                                                                                                                                                                                                                        |
-| ---------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `emitters`             | `Emitter[]`                                  | Language emitters to register. Each emitter implements the `Emitter` interface and generates SDK files for one target language.                                                                                                                                                                                                                                                    |
-| `extractors`           | `Extractor[]`                                | API surface extractors to register. Each extractor parses a live SDK and produces an `ApiSurface` JSON used for compat verification.                                                                                                                                                                                                                                               |
-| `emitterProject`       | `string`                                     | Path to the emitter project directory. Used by skills to scaffold new emitters, tests, and smoke runners in the correct location.                                                                                                                                                                                                                                                  |
-| `smokeRunners`         | `Record<string, string>`                     | Map from language key to custom smoke runner script path. Overrides the built-in `sdk-test.ts` for `oagen verify`. Can also be set per-invocation with `--smoke-runner`.                                                                                                                                                                                                           |
-| `operationIdTransform` | `(id: string) => string`                     | Custom transform for operation IDs. Receives the raw `operationId` from the spec; return the desired operation name. No additional casing conversion is applied. When omitted, `operationId` values are converted to `camelCase`.                                                                                                                                                  |
-| `schemaNameTransform`  | `(name: string) => string`                   | Custom transform for schema (model/enum) names. Applied after the built-in `cleanSchemaName` normalization. Receives the cleaned PascalCase name; return the desired name.                                                                                                                                                                                                         |
-| `transformSpec`        | `(spec: OpenApiDocument) => OpenApiDocument` | Pre-IR overlay applied to the bundled OpenAPI document before any IR extraction. Use to patch around upstream spec quirks that would otherwise emit a breaking SDK change. See [`transformSpec` — Pre-IR Spec Overlay](advanced/transform-spec.md).                                                                                                                                |
-| `docUrl`               | `string`                                     | Base URL for documentation links. When set, relative markdown paths in descriptions (e.g. `[User](/reference/users/user)`) are expanded to full URLs (e.g. `[User](https://docs.example.com/reference/users/user)`).                                                                                                                                                               |
-| `operationHints`       | `Record<string, OperationHint>`              | Per-operation overrides keyed by `"METHOD /path"`. Override derived method names, remount to a different service, or split union-body operations into typed wrappers. See [Operation Resolution](architecture/ir-types.md#operation-resolution).                                                                                                                                   |
-| `mountRules`           | `Record<string, string>`                     | Service-level remounting. Maps IR service name to target service/namespace (PascalCase). Keys may be exact names or trailing-`*` prefix patterns (e.g. `"UserManagement*"`); an exact key wins over any wildcard, and among wildcards the longest prefix wins. All operations in the source service are mounted on the target unless overridden per-operation in `operationHints`. |
-| `modelHints`           | `Record<string, string>`                     | Pin specific models to a specific IR service for placement. Maps IR model name (post-`cleanSchemaName`/`schemaNameTransform`) → IR service name (PascalCase). Overrides the default "first service to reference the model wins" assignment. Both names must exist in the parsed spec; unknown names throw at generation time.                                                      |
+| Key                    | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `emitters`             | `Emitter[]`                                       | Language emitters to register. Each emitter implements the `Emitter` interface and generates SDK files for one target language.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `extractors`           | `Extractor[]`                                     | API surface extractors to register. Each extractor parses a live SDK and produces an `ApiSurface` JSON used for compat verification.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `emitterProject`       | `string`                                          | Path to the emitter project directory. Used by skills to scaffold new emitters, tests, and smoke runners in the correct location.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `smokeRunners`         | `Record<string, string>`                          | Map from language key to custom smoke runner script path. Overrides the built-in `sdk-test.ts` for `oagen verify`. Can also be set per-invocation with `--smoke-runner`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `operationIdTransform` | `(id: string) => string`                          | Custom transform for operation IDs. Receives the raw `operationId` from the spec; return the desired operation name. No additional casing conversion is applied. When omitted, `operationId` values are converted to `camelCase`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `schemaNameTransform`  | `(name: string, originalName?: string) => string` | Custom transform for schema (model/enum) names. Applied after the built-in `cleanSchemaName` normalization. Receives the cleaned PascalCase name (`name`) and, for component schemas, the original name exactly as spelled in the document (`originalName`); return the desired name. Return `originalName` to opt a schema out of normalization, but only when its spelling is already a valid identifier: a bare `originalName ?? name` would also keep keys like `user-profile` or `Foo.Bar` that `cleanSchemaName` would otherwise have fixed. For example `(name, originalName) => (originalName && /^[A-Za-z_$][\w$]*$/.test(originalName) ? originalName : name)` keeps `HTTPConfig`, `URL`, and `Settings` instead of `HttpConfig`, `Url`, and `Setting`. `originalName` is `undefined` for any name oagen synthesises (inline enums, request-body variant models, title-derived names), so fall back to `name` for those. Collisions are detected automatically: if a transform would produce a duplicate name, the cleaned name is kept. |
+| `transformSpec`        | `(spec: OpenApiDocument) => OpenApiDocument`      | Pre-IR overlay applied to the bundled OpenAPI document before any IR extraction. Use to patch around upstream spec quirks that would otherwise emit a breaking SDK change. See [`transformSpec` — Pre-IR Spec Overlay](advanced/transform-spec.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `docUrl`               | `string`                                          | Base URL for documentation links. When set, relative markdown paths in descriptions (e.g. `[User](/reference/users/user)`) are expanded to full URLs (e.g. `[User](https://docs.example.com/reference/users/user)`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `operationHints`       | `Record<string, OperationHint>`                   | Per-operation overrides keyed by `"METHOD /path"`. Override derived method names, remount to a different service, or split union-body operations into typed wrappers. See [Operation Resolution](architecture/ir-types.md#operation-resolution).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `mountRules`           | `Record<string, string>`                          | Service-level remounting. Maps IR service name to target service/namespace (PascalCase). Keys may be exact names or trailing-`*` prefix patterns (e.g. `"UserManagement*"`); an exact key wins over any wildcard, and among wildcards the longest prefix wins. All operations in the source service are mounted on the target unless overridden per-operation in `operationHints`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `modelHints`           | `Record<string, string>`                          | Pin specific models to a specific IR service for placement. Maps IR model name (post-`cleanSchemaName`/`schemaNameTransform`) → IR service name (PascalCase). Overrides the default "first service to reference the model wins" assignment. Both names must exist in the parsed spec; unknown names throw at generation time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos/oagen",
-  "version": "0.30.2",
+  "version": "0.31.0",
   "description": "Framework for building OpenAPI SDK emitters",
   "author": "WorkOS",
   "license": "MIT",
@@ -96,10 +96,10 @@
     "@types/node": "^25.3.3",
     "@vitest/coverage-v8": "^4.1.2",
     "husky": "^9.1.7",
-    "oxfmt": "^0.36.0",
+    "oxfmt": "^0.72.0",
     "oxlint": "^1.51.0",
     "prettier": "^3.8.1",
-    "tsdown": "^0.21.5",
+    "tsdown": "^0.23.0",
     "vitest": "^4.1.2"
   }
 }

package/skills/check-emitter-parity/SKILL.md

@@ -80,6 +80,7 @@ A missing kind means an entire category of types won't generate correctly.
 #### ErrorResponse
 
 - `type` — Structured error type for typed exception/error classes
+- `headers` — Declared response headers (e.g. `Retry-After` on a 429) for typed error accessors
 
 ### Priority: MEDIUM (documentation — affects developer experience)
 
@@ -98,6 +99,7 @@ A missing kind means an entire category of types won't generate correctly.
 - `deprecated` — Deprecation marker on methods
 - `async` — Async operation marker
 - `successResponses` — Multiple 2xx response types
+- `responseHeaders` — Headers declared on the primary response (`Content-Disposition`, `Location`, `ETag`, rate limits)
 - `errors` — Error responses for exception/error documentation
 - `cookieParams` — Cookie parameter handling
 
@@ -107,11 +109,14 @@ A missing kind means an entire category of types won't generate correctly.
 - `deprecated` — Deprecated marker on params
 - `default` — Default value annotation
 - `example` — Example value annotation
+- `constraints` — Validation limits (min/max, length, pattern, item counts) for doc comments or argument checks
+- `examples` — Every example value (the list `example` is drawn from)
 
 #### Model
 
 - `description` — Model-level doc comment
 - `typeParams` — Generic type parameters
+- `constraints` — Object-level limits (`minProperties`, `maxProperties`, `dependentRequired`)
 
 #### Field
 
@@ -120,6 +125,9 @@ A missing kind means an entire category of types won't generate correctly.
 - `writeOnly` — Write-only annotation
 - `deprecated` — Deprecation marker on fields
 - `default` — Default value annotation
+- `example` — Example value annotation
+- `examples` — Every example value (the list `example` is drawn from)
+- `constraints` — Validation limits (min/max, length, pattern, item counts) for doc comments or value checks
 
 #### EnumValue
 
@@ -142,7 +150,7 @@ For each IR field from Step 2, search for references to the field name in the em
 - The field is used in conditional logic or output generation
 - The field is iterated over (e.g., `op.cookieParams`, `op.successResponses`)
 
-Use `Grep` with patterns like `\.description`, `\.readOnly`, `\.writeOnly`, `\.deprecated`, `\.default`, `\.example`, `\.async`, `\.cookieParams`, `\.successResponses`, `\.servers`, `\.typeParams`, `\.pagination`, `\.auth`, `\.requestBodyEncoding`, `\.injectIdempotencyKey`, `\.discriminator`, `\.compositionKind`, `\.format` scoped to the emitter source directory.
+Use `Grep` with patterns like `\.description`, `\.readOnly`, `\.writeOnly`, `\.deprecated`, `\.default`, `\.example`, `\.examples`, `\.async`, `\.cookieParams`, `\.successResponses`, `\.responseHeaders`, `\.servers`, `\.typeParams`, `\.pagination`, `\.auth`, `\.requestBodyEncoding`, `\.injectIdempotencyKey`, `\.discriminator`, `\.compositionKind`, `\.format`, `\.constraints` scoped to the emitter source directory.
 
 ### 3c: Intentional Skips
 
@@ -227,14 +235,20 @@ For each gap, provide a specific, actionable suggestion for what the emitter sho
 | `ApiSpec.servers`            | Server URL constants or configuration                                                                                                           |
 | `Operation.async`            | Mark method as async or add async behavior hints (e.g., `async` in TS/Rust, coroutine in Kotlin, `async def` in Python)                         |
 | `Operation.successResponses` | Document additional return types for each 2xx response                                                                                          |
+| `Operation.responseHeaders`  | Typed accessors for declared response headers (download filename, `Location`, `ETag`, rate limits)                                              |
 | `Operation.cookieParams`     | Document cookie parameters                                                                                                                      |
 | `Parameter.description`      | Document query/header/cookie params in method doc comments                                                                                      |
 | `Parameter.deprecated`       | Mark parameter as deprecated in docs                                                                                                            |
 | `Parameter.default`          | Document default value                                                                                                                          |
 | `Parameter.example`          | Document example value                                                                                                                          |
+| `Parameter.examples`         | Document every example value (e.g. one `@example` tag each)                                                                                     |
 | `Field.readOnly`             | Read-only annotation and language-appropriate modifier (`readonly` in TS, `attr_reader` in Ruby, `val` in Kotlin, `pub` without setter in Rust) |
 | `Field.writeOnly`            | Write-only annotation in doc comments                                                                                                           |
 | `Field.default`              | Document default value                                                                                                                          |
+| `Field.example`              | Document example value                                                                                                                          |
+| `Field.examples`             | Document every example value (e.g. one `@example` tag each)                                                                                     |
+| `Field.constraints`          | Document limits ("at most 100 characters") or validate before serializing                                                                       |
+| `Parameter.constraints`      | Document limits on method arguments or validate before sending                                                                                  |
 
 Include the specific file and approximate location where each fix should be applied.
 

package/dist/differ-nZSxhCfC.d.mts

@@ -1,123 +0,0 @@
-import { At as CompatSnapshot, Lt as LanguageId, Nt as CompatSymbol, St as LanguageHints, Vt as CompatPolicyHints, bt as DiffResult, nt as CompatChangeCategory, ot as CompatProvenance, rt as CompatChangeSeverity, t as ApiSpec, vt as ApiSurface } from "./types-BcbGLNkh.mjs";
-
-//#region src/compat/classify.d.ts
-/** A single classified compatibility change. */
-interface ClassifiedChange {
-  /** Specific change category. */
-  category: CompatChangeCategory;
-  /** Policy-aware severity (may differ from defaultSeverityForCategory). */
-  severity: CompatChangeSeverity;
-  /** Fully-qualified symbol path. */
-  symbol: string;
-  /** Deterministic ID for grouping related changes across languages. */
-  conceptualChangeId: string;
-  /** Where the drift originated. */
-  provenance: CompatProvenance;
-  /** Description of the old state. */
-  old: Record<string, string>;
-  /** Description of the new state. */
-  new: Record<string, string>;
-  /** Human-readable explanation. */
-  message: string;
-  /**
-   * Optional spec-level remediation hint. Set by post-classification rules
-   * (see `detectForkedSchemas` in differ.ts) when a change has a recognized
-   * upstream root cause that the spec author can fix. Surfaces in both the
-   * machine-readable report and the human-readable summary.
-   */
-  remediation?: string;
-}
-/** Result of classifying all changes between two snapshots. */
-interface ClassificationResult {
-  changes: ClassifiedChange[];
-  summary: {
-    breaking: number;
-    softRisk: number;
-    additive: number;
-  };
-}
-/**
- * Classify changes between a baseline and candidate symbol.
- * Returns one or more classified changes for the diff.
- */
-declare function classifySymbolChanges(baseline: CompatSymbol, candidate: CompatSymbol | undefined, policy: CompatPolicyHints, language?: LanguageId): ClassifiedChange[];
-/**
- * Classify a new symbol as additive.
- */
-declare function classifyAddedSymbol(symbol: CompatSymbol): ClassifiedChange;
-/** Summarize a list of classified changes by severity. */
-declare function summarizeChanges(changes: ClassifiedChange[]): ClassificationResult['summary'];
-//#endregion
-//#region src/compat/spec-filter.d.ts
-/**
- * Compute the set of symbol names that are derivable from the OpenAPI spec.
- * Only these names should be compared during compat verification — everything
- * else in the baseline is hand-written and out of scope for generation.
- */
-declare function specDerivedNames(spec: ApiSpec, hints: LanguageHints): Set<string>;
-/**
- * Compute a map of enum name → set of wire values that appear in the spec.
- * Used by filterSurface to exclude hand-added enum members that aren't in the spec.
- */
-declare function specDerivedEnumValues(spec: ApiSpec): Map<string, Set<string | number>>;
-/**
- * Compute the set of field paths (e.g., "Organization.name") that are defined
- * in the OpenAPI spec's model schemas. Used by filterSurface to exclude
- * hand-added SDK fields that reference spec-derived types.
- */
-declare function specDerivedFieldPaths(spec: ApiSpec, hints: LanguageHints): Set<string>;
-/**
- * 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.
- */
-declare function specDerivedMethodPaths(spec: ApiSpec): Set<string>;
-/**
- * Compute the set of HTTP operation keys (e.g., "GET /auth/authorize") that
- * exist in the spec. Used for overlay-based method matching.
- */
-declare function specDerivedHttpKeys(spec: ApiSpec): Set<string>;
-/**
- * Filter an ApiSurface to only include symbols whose names appear in the
- * allowed set. Symbols not in the set are dropped entirely — they won't
- * count toward the total or produce violations.
- *
- * For interfaces: when fieldPaths is provided, only keeps fields that appear
- * in the spec-derived field paths. This prevents false positives from hand-added
- * SDK fields that reference spec-derived types but aren't defined in the spec.
- *
- * 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., 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.
- */
-declare function filterSurface(surface: ApiSurface, allowedNames: Set<string>, opts?: {
-  fieldPaths?: Set<string>;
-  methodPaths?: Set<string>;
-  enumValues?: Map<string, Set<string | number>>;
-}): ApiSurface;
-//#endregion
-//#region src/compat/differ.d.ts
-/** Result of diffing two compat snapshots. */
-interface CompatDiffResult {
-  changes: ClassifiedChange[];
-  summary: ClassificationResult['summary'];
-}
-/**
- * Diff two compat snapshots, producing classified changes with
- * policy-aware severity.
- */
-declare function diffSnapshots(baseline: CompatSnapshot, candidate: CompatSnapshot, policy?: CompatPolicyHints): CompatDiffResult;
-/**
- * Compare two ApiSurface objects and return a DiffResult.
- *
- * This preserves the existing diffing behavior used by the overlay retry loop,
- * compat check, and all existing tests. The internal implementation uses the
- * same algorithms as before to maintain full backward compatibility with
- * overlay patching and verification workflows.
- */
-declare function diffSurfaces(baseline: ApiSurface, candidate: ApiSurface, hints: LanguageHints): DiffResult;
-//#endregion
-export { specDerivedEnumValues as a, specDerivedMethodPaths as c, ClassifiedChange as d, classifyAddedSymbol as f, filterSurface as i, specDerivedNames as l, summarizeChanges as m, diffSnapshots as n, specDerivedFieldPaths as o, classifySymbolChanges as p, diffSurfaces as r, specDerivedHttpKeys as s, CompatDiffResult as t, ClassificationResult as u };
-//# sourceMappingURL=differ-nZSxhCfC.d.mts.map

package/dist/differ-nZSxhCfC.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"differ-nZSxhCfC.d.mts","names":[],"sources":["../src/compat/classify.ts","../src/compat/spec-filter.ts","../src/compat/differ.ts"],"mappings":";;;;UAaiB,gBAAA;EAcJ;EAZX,QAAA,EAAU,oBAAA;EAAV;EAEA,QAAA,EAAU,oBAAA;EAAV;EAEA,MAAA;EAAA;EAEA,kBAAA;EAEA;EAAA,UAAA,EAAY,gBAAA;EAEZ;EAAA,GAAA,EAAK,MAAA;EAEL;EAAA,GAAA,EAAK,MAAA;EAEL;EAAA,OAAA;EAOW;;AAIb;;;;EAJE,WAAA;AAAA;;UAIe,oBAAA;EACf,OAAA,EAAS,gBAAA;EACT,OAAA;IACE,QAAA;IACA,QAAA;IACA,QAAA;EAAA;AAAA;;;;;iBAmMY,qBAAA,CACd,QAAA,EAAU,YAAA,EACV,SAAA,EAAW,YAAA,cACX,MAAA,EAAQ,iBAAA,EACR,QAAA,GAAW,UAAA,GACV,gBAAA;;;;iBAgYa,mBAAA,CAAoB,MAAA,EAAQ,YAAA,GAAe,gBAAA;;iBAc3C,gBAAA,CAAiB,OAAA,EAAS,gBAAA,KAAqB,oBAAA;;;;AAtnB/D;;;;iBCJgB,gBAAA,CAAiB,IAAA,EAAM,OAAA,EAAS,KAAA,EAAO,aAAA,GAAgB,GAAA;;;;;iBAgDvD,qBAAA,CAAsB,IAAA,EAAM,OAAA,GAAU,GAAA,SAAY,GAAA;;;;;;iBAalD,qBAAA,CAAsB,IAAA,EAAM,OAAA,EAAS,KAAA,EAAO,aAAA,GAAgB,GAAA;;;;;;iBAqB5D,sBAAA,CAAuB,IAAA,EAAM,OAAA,GAAU,GAAA;;;;;iBAcvC,mBAAA,CAAoB,IAAA,EAAM,OAAA,GAAU,GAAA;;;;;;;;;;;;ADuIpD;;;;iBCnFgB,aAAA,CACd,OAAA,EAAS,UAAA,EACT,YAAA,EAAc,GAAA,UACd,IAAA;EACE,UAAA,GAAa,GAAA;EACb,WAAA,GAAc,GAAA;EACd,UAAA,GAAa,GAAA,SAAY,GAAA;AAAA,IAE1B,UAAA;;;;UCtIc,gBAAA;EACf,OAAA,EAAS,gBAAA;EACT,OAAA,EAAS,oBAAA;AAAA;;;;;iBAOK,aAAA,CACd,QAAA,EAAU,cAAA,EACV,SAAA,EAAW,cAAA,EACX,MAAA,GAAS,iBAAA,GACR,gBAAA;;;;;;AFJH;;;iBEsqBgB,YAAA,CAAa,QAAA,EAAU,UAAA,EAAY,SAAA,EAAW,UAAA,EAAY,KAAA,EAAO,aAAA,GAAgB,UAAA"}