Publish SDK resolution policy as @workos/openapi-spec/policy#28
Merged
Conversation
Extracts the consumer-owned policy (operationHints, mountRules, modelHints,
schemaNameTransform, transformSpec, nestjsOperationIdTransform) out of the
monolithic oagen.config.ts into a publishable module so downstream
consumers — the WorkOS docs build's snippet generators, partner tooling,
and any future spec-driven code generation — can pin to the same naming
policy the SDKs use.
Why this matters: the docs build currently can't produce SDK code samples
that match real SDK method names without vendoring or re-deriving the
policy. Publishing it solves that with a single import:
import {
operationHints, mountRules, modelHints,
nestjsOperationIdTransform, schemaNameTransform, transformSpec,
} from '@workos/openapi-spec/policy';
Changes:
- src/policy.ts (new) — moved policy bits out of oagen.config.ts. Type
defs for OperationHint / SplitHint / OpenApiDocument are vendored
inline so the published .d.mts is fully self-contained (TypeScript
consumers get autocomplete without needing to install @workos/oagen
for typings). Runtime imports `toCamelCase` from @workos/oagen, which
the published package declares as a regular dependency for transitive
install.
- oagen.config.ts — now a thin shim that combines workosEmittersPlugin
with the policy module. Zero behavior change (verified via
`npx oagen resolve --format json` diff: 0 lines).
- tsdown.config.ts (new) — builds src/policy.ts → dist/policy.mjs +
dist/policy.d.mts. Runtime is 15 KB; types are 2 KB.
- package.json — adds `build:policy` script and tsdown devDependency.
- tsconfig.json — includes src/ in the type-check globs.
- .github/workflows/release.yml — extends the existing publish workflow:
- triggers on src/policy.ts and operationOverrides.node.json changes
- runs `npm ci` + `npm run build:policy` before assembly
- resolves @workos/oagen version from devDeps to pin in published deps
- adds policy.mjs, policy.d.mts, operationOverrides.node.json to the
published files and exports
- adds new exports: `./policy` and `./operation-overrides/node`
Dry-run verified by packing locally and installing into a test consumer:
all 67 operation hints, 26 mount rules, 3 model hints, and all three
transform functions resolve correctly with full TypeScript autocomplete.
Three changes to README.md aligning the docs with the policy-module split: - SDK Generation opener now describes src/policy.ts as the canonical home for hints/rules/transforms and oagen.config.ts as a thin shim, with a forward reference to the published @workos/openapi-spec/policy export so docs and partner tooling know where to consume it. - Typical workflow step 2 points contributors at src/policy.ts for hints/mount-rules/schema-renames/transforms and reserves oagen.config.ts edits for emitter-wiring changes. - 'Grabbing from npm' / Usage section adds an exports table covering all four export paths (default types, /spec, /policy, /operation-overrides/node) plus a runnable example showing how to apply the published policy alongside @workos/oagen to reproduce the same resolution the SDKs use.
These two dependencies were unused npm-squat / lookalike packages that
nobody imports:
- package-lock.json@1.0.0 — a one-version stub with an empty 'files' array
(`{"name": "package-lock.json", "version": "1.0.0", "files": []}`).
- package.json@2.0.1 — an unrelated 'read package.json content' library
by IonicaBizau, with zero call sites in this repo.
Verified safe to remove: `grep` across the repo finds no require/import
of either name, the build still produces dist/policy.{mjs,d.mts}
identically, and `npm run sdk:check` still passes. Drops ~815 lines
from package-lock.json by pruning their transitive trees too.
The single ~500-line src/policy.ts is harder to navigate than necessary
since the operation hints (~280 lines) dwarf everything else. Splits the
module by concern so each policy edit lands in a small, focused file:
src/policy/
types.ts — vendored OperationHint / SplitHint / OpenApiDocument
operation-hints.ts — operationHints object (the bulk of the policy)
mount-rules.ts — mountRules
model-hints.ts — modelHints
transforms.ts — nestjsOperationIdTransform, schemaNameTransform,
transformSpec
index.ts — barrel re-exporting the whole policy surface
oagen.config.ts now imports from ./src/policy/index.js; tsdown builds
from src/policy/index.ts as the entry. The published artifacts at
dist/policy.{mjs,d.mts} stay at the same paths, so consumers using
`@workos/openapi-spec/policy` see no change.
Verified:
- `npm run sdk:check` still passes
- `npx oagen resolve --format json` produces 0-line diff vs the previous
monolithic policy.ts (semantically identical)
- `npm run build:policy` succeeds; policy.mjs 16 KB / policy.d.mts 3.9 KB
(small barrel overhead vs the prior 15.4 KB / 2.2 KB)
Release workflow trigger path widened from `src/policy.ts` to
`src/policy/**` so edits to any sub-file still fire a new release.
README updated to point at the new file layout.
The release workflow previously constructed a throwaway package.json in dist/. Now the real root package.json carries the publish metadata (name, version, exports, files) and npm publishes from root using files: ["dist/"]. The workflow bumps version via npm version, publishes, then commits the bump back to main. workflow_dispatch now accepts a bump type (major/minor/patch) so releases are no longer hardcoded to minor increments. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
oagen.config.tsinto a standalonesrc/policy.tsmodule, published as@workos/openapi-spec/policytsdown.config.tsbuild producingdist/policy.mjs+dist/policy.d.mts(15 KB runtime, 2 KB types)src/policy.tschanges, build the policy module, and publish new./policyand./operation-overrides/nodeexportspackage-lock.jsonandpackage.jsonnpm dependencies from rootTest plan
npm run build:policyproducesdist/policy.mjsanddist/policy.d.mtsnpx oagen resolve --format jsonoutput is identical before and after the splitnpm run sdk:checkpasses