@workos/openapi-spec 0.4.0 → 0.5.0

package/README.md

@@ -22,7 +22,9 @@ The WorkOS API provides a comprehensive platform for enterprise-ready features i
 
 ## SDK Generation
 
-This repository is the canonical source for SDK generation. The consumer config at `oagen.config.ts` defines spec interpretation policy (operation hints, mount rules, transforms) and imports the plugin bundle from `@workos/oagen-emitters`.
+This repository is the canonical source for SDK generation. The consumer policy lives under [`src/policy/`](src/policy/) — split into focused modules ([`operation-hints.ts`](src/policy/operation-hints.ts), [`mount-rules.ts`](src/policy/mount-rules.ts), [`model-hints.ts`](src/policy/model-hints.ts), [`transforms.ts`](src/policy/transforms.ts) for the NestJS `operationId` transform / schema-name transform / pre-IR spec overlay, and [`types.ts`](src/policy/types.ts) for vendored type definitions). The barrel [`src/policy/index.ts`](src/policy/index.ts) re-exports the whole thing and is published as `@workos/openapi-spec/policy` so downstream consumers (the WorkOS docs build's snippet generators, partner tooling) can apply the exact same naming conventions the SDKs use.
+
+`oagen.config.ts` at the repo root is a thin shim that combines that policy with the `workosEmittersPlugin` bundle from `@workos/oagen-emitters` and feeds the whole thing to `npx oagen generate`.
 
 ### Orchestration scripts
 
@@ -122,11 +124,13 @@ node scripts/sdk-compat-pr-comment.mjs \
 ### Typical workflow
 
 1. Edit `spec/open-api-spec.yaml`
-2. Update `oagen.config.ts` if the change needs new hints, mount rules, or transforms
+2. Update the relevant file under [`src/policy/`](src/policy/) if the change needs new operation hints, mount rules, model hints, schema renames, or pre-IR transforms (only touch `oagen.config.ts` for changes that affect emitter wiring, e.g. `emitterOptions`)
 3. `npm run sdk:resolve` to inspect naming
 4. `npm run sdk:generate -- --lang <lang> --output .oagen/<lang>/sdk` to generate
 5. `npm run sdk:verify -- --lang <lang> --output .oagen/<lang>/sdk` to verify
 
+Changes to any file under `src/policy/` (or to `operationOverrides.node.json` or `tsdown.config.ts`) trigger a new release of `@workos/openapi-spec` the same way changes to the spec YAML do — see the publish workflow at `.github/workflows/release.yml`.
+
 ## Grabbing from npm
 
 The spec is published to npm as [`@workos/openapi-spec`](https://www.npmjs.com/package/@workos/openapi-spec).
@@ -137,7 +141,14 @@ npm install @workos/openapi-spec
 
 ### Usage
 
-The package ships TypeScript types generated from the spec, plus the raw `open-api-spec.yaml` file.
+The package ships TypeScript types generated from the spec, the raw `open-api-spec.yaml` file, the SDK resolution policy module, and the Node-specific operation overrides.
+
+| Export                                | What it gives you                                                                              |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `@workos/openapi-spec`                | Generated TypeScript `paths` / `components` / `operations` types (default), spec YAML as file. |
+| `@workos/openapi-spec/spec`           | Path to the bundled `open-api-spec.yaml`.                                                      |
+| `@workos/openapi-spec/policy`         | Operation hints, mount rules, model hints, and transform functions used by SDK generation.    |
+| `@workos/openapi-spec/operation-overrides/node` | JSON path for the Node-emitter-specific operation overrides.                            |
 
 **TypeScript types:**
 
@@ -189,6 +200,34 @@ const spec = yaml.load(readFileSync(specPath, "utf8"));
 import spec from "@workos/openapi-spec/spec";
 ```
 
+**Applying the SDK resolution policy (e.g. for docs code snippets):**
+
+The `/policy` export exposes the same hints, mount rules, and transforms that drive SDK generation, so downstream tooling can resolve operations against the WorkOS spec with method names, mount targets, and parameter shapes that match the published SDKs.
+
+```ts
+import { parseSpec, resolveOperations } from "@workos/oagen";
+import {
+  operationHints,
+  mountRules,
+  modelHints,
+  nestjsOperationIdTransform,
+  schemaNameTransform,
+  transformSpec,
+} from "@workos/openapi-spec/policy";
+
+const spec = await parseSpec("./open-api-spec.yaml", {
+  operationIdTransform: nestjsOperationIdTransform,
+  schemaNameTransform,
+  transformSpec,
+});
+
+const resolved = resolveOperations(spec, operationHints, mountRules);
+```
+
+`@workos/oagen` is installed transitively when you install `@workos/openapi-spec` — no separate add needed.
+
+The vendored type aliases (`OperationHint`, `SplitHint`, `OpenApiDocument`) are inlined into the published `policy.d.mts`, so TypeScript users get full autocomplete without having to import types from `@workos/oagen` themselves.
+
 ## Generating Postman Collections
 
 This repository includes scripts to generate Postman collections from the OpenAPI specification. See the `scripts/postman` folder for more information.

package/dist/operationOverrides.node.json

@@ -0,0 +1,122 @@
+{
+  "POST /organizations/{organizationId}/groups": {
+    "methodName": "create_group",
+    "optionsType": "CreateGroupOptions"
+  },
+  "GET /organizations/{organizationId}/groups": {
+    "methodName": "list_groups",
+    "optionsType": "ListGroupsOptions"
+  },
+  "GET /organizations/{organizationId}/groups/{groupId}": {
+    "methodName": "get_group",
+    "optionsType": "GetGroupOptions"
+  },
+  "PATCH /organizations/{organizationId}/groups/{groupId}": {
+    "methodName": "update_group",
+    "optionsType": "UpdateGroupOptions"
+  },
+  "DELETE /organizations/{organizationId}/groups/{groupId}": {
+    "methodName": "delete_group",
+    "optionsType": "DeleteGroupOptions"
+  },
+  "POST /organizations/{organizationId}/groups/{groupId}/organization-memberships": {
+    "methodName": "add_organization_membership",
+    "optionsType": "AddGroupOrganizationMembershipOptions"
+  },
+  "GET /organizations/{organizationId}/groups/{groupId}/organization-memberships": {
+    "methodName": "list_organization_memberships",
+    "optionsType": "ListGroupOrganizationMembershipsOptions"
+  },
+  "DELETE /organizations/{organizationId}/groups/{groupId}/organization-memberships/{omId}": {
+    "methodName": "remove_organization_membership",
+    "optionsType": "RemoveGroupOrganizationMembershipOptions"
+  },
+  "GET /user_management/organization_memberships": {
+    "methodName": "list_organization_memberships",
+    "mountOn": "UserManagement"
+  },
+  "POST /user_management/organization_memberships": {
+    "methodName": "create_organization_membership",
+    "mountOn": "UserManagement"
+  },
+  "GET /user_management/organization_memberships/{id}": {
+    "methodName": "get_organization_membership",
+    "mountOn": "UserManagement"
+  },
+  "PUT /user_management/organization_memberships/{id}": {
+    "methodName": "update_organization_membership",
+    "mountOn": "UserManagement"
+  },
+  "DELETE /user_management/organization_memberships/{id}": {
+    "methodName": "delete_organization_membership",
+    "mountOn": "UserManagement"
+  },
+  "PUT /user_management/organization_memberships/{id}/deactivate": {
+    "methodName": "deactivate_organization_membership",
+    "mountOn": "UserManagement"
+  },
+  "PUT /user_management/organization_memberships/{id}/reactivate": {
+    "methodName": "reactivate_organization_membership",
+    "mountOn": "UserManagement"
+  },
+  "GET /user_management/organization_memberships/{omId}/groups": {
+    "methodName": "list_groups_for_organization_membership",
+    "mountOn": "UserManagement"
+  },
+  "POST /vault/v1/kv": {
+    "methodName": "create_object",
+    "optionsType": "CreateObjectOptions",
+    "bodyFieldMap": {
+      "context": "keyContext"
+    }
+  },
+  "GET /vault/v1/kv": {
+    "methodName": "list_objects"
+  },
+  "GET /vault/v1/kv/{id}": {
+    "methodName": "read_object",
+    "optionsType": "ReadObjectOptions"
+  },
+  "GET /vault/v1/kv/name/{name}": {
+    "methodName": "read_object_by_name"
+  },
+  "GET /vault/v1/kv/{id}/metadata": {
+    "methodName": "describe_object",
+    "optionsType": "ReadObjectOptions",
+    "returnType": "Promise<VaultObject>",
+    "returnExpression": "({ ...result, value: undefined })"
+  },
+  "PUT /vault/v1/kv/{id}": {
+    "methodName": "update_object",
+    "optionsType": "UpdateObjectOptions",
+    "returnType": "Promise<VaultObject>",
+    "returnExpression": "({ ...result, value: undefined })"
+  },
+  "DELETE /vault/v1/kv/{id}": {
+    "methodName": "delete_object",
+    "optionsType": "DeleteObjectOptions"
+  },
+  "GET /vault/v1/kv/{id}/versions": {
+    "methodName": "list_object_versions",
+    "optionsType": "ReadObjectOptions",
+    "returnType": "Promise<VersionListResponse['data']>",
+    "returnDataProperty": "data"
+  },
+  "POST /vault/v1/keys/data-key": {
+    "optionsType": "CreateDataKeyOptions",
+    "returnType": "Promise<DataKeyPair>",
+    "returnTypeImports": [
+      "DataKeyPair"
+    ],
+    "returnExpression": "({ context: result.context, dataKey: { key: result.dataKey!, id: result.id }, encryptedKeys: result.encryptedKeys! })"
+  },
+  "POST /vault/v1/keys/decrypt": {
+    "methodName": "decrypt_data_key",
+    "optionsType": "DecryptDataKeyOptions",
+    "returnType": "Promise<DataKey>",
+    "returnTypeImports": [
+      "DataKey"
+    ],
+    "returnExpression": "({ key: result.dataKey, id: result.id })"
+  }
+}

package/dist/policy.d.mts

@@ -0,0 +1,85 @@
+//#region src/policy/types.d.ts
+/**
+ * Vendored type definitions for the policy module.
+ *
+ * `OperationHint`, `SplitHint`, and `OpenApiDocument` are inlined from
+ * `@workos/oagen` so the published `@workos/openapi-spec/policy` .d.mts is
+ * self-contained — consumers get full autocomplete without resolving types
+ * through `@workos/oagen`. Keep these in sync with the upstream definitions
+ * in `oagen/src/ir/operation-hints.ts` and `oagen/src/parser/parse.ts`; bump
+ * when the upstream schema gains a field this repo wants to use.
+ */
+type OpenApiDocument = Record<string, unknown>;
+interface SplitHint {
+  /** Wrapper method name (snake_case). */
+  name: string;
+  /** The discriminated union variant model name (e.g. 'PasswordSessionAuthenticateRequest'). */
+  targetVariant: string;
+  /** Constant body fields injected by the wrapper. */
+  defaults?: Record<string, string | number | boolean>;
+  /** Fields the SDK reads from client config at runtime. */
+  inferFromClient?: string[];
+  /** Only these body fields are exposed as method params. */
+  exposedParams?: string[];
+  /** Subset of exposedParams that should be emitted as optional. */
+  optionalParams?: string[];
+}
+interface OperationHint {
+  /** Override the algorithm-derived method name. */
+  name?: string;
+  /** Remount this operation to a different service/namespace (PascalCase). */
+  mountOn?: string;
+  /** Split a union-body operation into N typed wrapper methods. */
+  split?: SplitHint[];
+  /** Inject constant body defaults (e.g. { grant_type: 'password' }). */
+  defaults?: Record<string, string | number | boolean>;
+  /** Fields the SDK reads from client config at runtime (e.g. ['client_id']). */
+  inferFromClient?: string[];
+  /**
+   * Marks this operation as a URL builder rather than a real HTTP call.
+   * Emitters generate a method that returns the constructed URL (typically
+   * as a string) without performing any I/O. Used for OAuth-style redirect
+   * endpoints such as /sso/authorize and /user_management/sessions/logout.
+   */
+  urlBuilder?: boolean;
+}
+//#endregion
+//#region src/policy/operation-hints.d.ts
+/**
+ * Per-operation overrides for the operation resolver. Keyed by `"METHOD /path"`.
+ * Only operations that need overrides are listed; the algorithm handles the rest.
+ */
+declare const operationHints: Record<string, OperationHint>;
+//#endregion
+//#region src/policy/mount-rules.d.ts
+/**
+ * Service-level remounting. Maps IR service name → target service/namespace
+ * (PascalCase). All operations in the source service are mounted on the
+ * target unless overridden per-operation in {@link operationHints}.
+ */
+declare const mountRules: Record<string, string>;
+//#endregion
+//#region src/policy/model-hints.d.ts
+/**
+ * Model placement hints — used by emitters that call
+ * `assignModelsToServices` so hinted models land in the configured service
+ * instead of the default first-reference winner.
+ */
+declare const modelHints: Record<string, string>;
+//#endregion
+//#region src/policy/transforms.d.ts
+/**
+ * NestJS-style operationId transform. Strips "Controller" and extracts the
+ * action after the first underscore: `FooController_bar` -> `bar`.
+ */
+declare function nestjsOperationIdTransform(id: string): string;
+declare function schemaNameTransform(name: string): string;
+/**
+ * Pre-IR spec overlay — patch around upstream spec quirks that would otherwise
+ * emit breaking SDK changes. See docs/breaking-change-playbook.md and the
+ * oagen `transformSpec` docs for usage. Reach for this only when the upstream
+ * fix can't land in time AND the change is genuinely additive.
+ */
+declare function transformSpec(spec: OpenApiDocument): OpenApiDocument;
+//#endregion
+export { type OpenApiDocument, type OperationHint, type SplitHint, modelHints, mountRules, nestjsOperationIdTransform, operationHints, schemaNameTransform, transformSpec };

package/dist/policy.mjs

@@ -0,0 +1,398 @@
+import { toCamelCase } from "@workos/oagen";
+//#region src/policy/operation-hints.ts
+/**
+* Per-operation overrides for the operation resolver. Keyed by `"METHOD /path"`.
+* Only operations that need overrides are listed; the algorithm handles the rest.
+*/
+const operationHints = {
+	"POST /radar/lists/{type}/{action}": { name: "add_list_entry" },
+	"DELETE /radar/lists/{type}/{action}": { name: "remove_list_entry" },
+	"GET /sso/authorize": {
+		name: "get_authorization_url",
+		defaults: { response_type: "code" },
+		inferFromClient: ["client_id"],
+		urlBuilder: true
+	},
+	"GET /sso/logout": {
+		name: "get_logout_url",
+		urlBuilder: true
+	},
+	"GET /sso/profile": { name: "get_profile" },
+	"POST /sso/token": {
+		name: "get_profile_and_token",
+		defaults: { grant_type: "authorization_code" },
+		inferFromClient: ["client_id", "client_secret"]
+	},
+	"GET /sso/jwks/{clientId}": { name: "get_jwks" },
+	"GET /user_management/authorize": {
+		name: "get_authorization_url",
+		defaults: { response_type: "code" },
+		inferFromClient: ["client_id"],
+		urlBuilder: true
+	},
+	"GET /user_management/sessions/logout": {
+		name: "get_logout_url",
+		urlBuilder: true
+	},
+	"POST /portal/generate_link": { name: "generate_link" },
+	"GET /organizations/{organizationId}/feature-flags": { name: "list_organization_feature_flags" },
+	"GET /user_management/users/{userId}/feature-flags": { name: "list_user_feature_flags" },
+	"GET /organizations/external_id/{external_id}": { name: "get_organization_by_external_id" },
+	"GET /user_management/users/external_id/{external_id}": { name: "get_user_by_external_id" },
+	"GET /authorization/roles": { name: "list_environment_roles" },
+	"POST /authorization/roles": { name: "create_environment_role" },
+	"GET /authorization/roles/{slug}": { name: "get_environment_role" },
+	"PATCH /authorization/roles/{slug}": { name: "update_environment_role" },
+	"PUT /authorization/roles/{slug}/permissions": { name: "set_environment_role_permissions" },
+	"POST /authorization/roles/{slug}/permissions": { name: "add_environment_role_permission" },
+	"POST /authorization/permissions": { name: "create_permission" },
+	"POST /authorization/resources": { name: "create_resource" },
+	"POST /authorization/organization_memberships/{organization_membership_id}/check": { name: "check" },
+	"GET /authorization/organization_memberships/{organization_membership_id}/resources": { name: "list_resources_for_membership" },
+	"GET /authorization/organization_memberships/{organization_membership_id}/resources/{resource_id}/permissions": { name: "list_effective_permissions" },
+	"GET /authorization/organization_memberships/{organization_membership_id}/resources/{resource_type_slug}/{external_id}/permissions": { name: "list_effective_permissions_by_external_id" },
+	"GET /authorization/organization_memberships/{organization_membership_id}/role_assignments": { name: "list_role_assignments" },
+	"POST /authorization/organization_memberships/{organization_membership_id}/role_assignments": { name: "assign_role" },
+	"DELETE /authorization/organization_memberships/{organization_membership_id}/role_assignments": { name: "remove_role" },
+	"DELETE /authorization/organization_memberships/{organization_membership_id}/role_assignments/{role_assignment_id}": { name: "remove_role_assignment" },
+	"POST /authorization/organizations/{organizationId}/roles": { name: "create_organization_role" },
+	"PUT /authorization/organizations/{organizationId}/roles/{slug}/permissions": { name: "set_organization_role_permissions" },
+	"POST /authorization/organizations/{organizationId}/roles/{slug}/permissions": { name: "add_organization_role_permission" },
+	"DELETE /authorization/organizations/{organizationId}/roles/{slug}/permissions/{permissionSlug}": { name: "remove_organization_role_permission" },
+	"GET /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}": { name: "get_resource_by_external_id" },
+	"PATCH /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}": { name: "update_resource_by_external_id" },
+	"DELETE /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}": { name: "delete_resource_by_external_id" },
+	"GET /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}/organization_memberships": { name: "list_memberships_for_resource_by_external_id" },
+	"GET /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}/role_assignments": { name: "list_role_assignments_for_resource_by_external_id" },
+	"GET /authorization/resources/{resource_id}/organization_memberships": { name: "list_memberships_for_resource" },
+	"GET /authorization/resources/{resource_id}/role_assignments": { name: "list_role_assignments_for_resource" },
+	"POST /user_management/users": { name: "create_user" },
+	"POST /user_management/invitations": { name: "send_invitation" },
+	"GET /user_management/invitations/by_token/{token}": { name: "find_invitation_by_token" },
+	"POST /user_management/users/{id}/email_verification/send": { name: "send_verification_email" },
+	"POST /user_management/users/{id}/email_verification/confirm": { name: "verify_email" },
+	"POST /user_management/password_reset": { name: "reset_password" },
+	"POST /user_management/password_reset/confirm": { name: "confirm_password_reset" },
+	"GET /user_management/users/{id}/sessions": { name: "list_sessions" },
+	"GET /user_management/users/{id}/identities": { name: "get_user_identities" },
+	"POST /user_management/cors_origins": { name: "create_cors_origin" },
+	"POST /user_management/redirect_uris": { name: "create_redirect_uri" },
+	"POST /organizations": { name: "create_organization" },
+	"GET /directory_groups": { name: "list_groups" },
+	"GET /directory_groups/{id}": { name: "get_group" },
+	"GET /directory_users": { name: "list_users" },
+	"GET /directory_users/{id}": { name: "get_user" },
+	"POST /audit_logs/events": { name: "create_event" },
+	"POST /audit_logs/exports": { name: "create_export" },
+	"POST /audit_logs/actions/{actionName}/schemas": { name: "create_schema" },
+	"POST /feature-flags/{slug}/targets/{resourceId}": { name: "add_flag_target" },
+	"DELETE /feature-flags/{slug}/targets/{resourceId}": { name: "remove_flag_target" },
+	"GET /organizations/{id}/audit_log_configuration": { name: "get_audit_log_configuration" },
+	"GET /organizations/{id}/audit_logs_retention": {
+		name: "get_organization_audit_logs_retention",
+		mountOn: "AuditLogs"
+	},
+	"PUT /organizations/{id}/audit_logs_retention": { mountOn: "AuditLogs" },
+	"POST /user_management/authenticate": { split: [
+		{
+			name: "authenticate_with_password",
+			targetVariant: "PasswordSessionAuthenticateRequest",
+			defaults: { grant_type: "password" },
+			inferFromClient: ["client_id", "client_secret"],
+			exposedParams: [
+				"email",
+				"password",
+				"invitation_token",
+				"ip_address",
+				"device_id",
+				"user_agent"
+			],
+			optionalParams: [
+				"invitation_token",
+				"ip_address",
+				"device_id",
+				"user_agent"
+			]
+		},
+		{
+			name: "authenticate_with_code",
+			targetVariant: "AuthorizationCodeSessionAuthenticateRequest",
+			defaults: { grant_type: "authorization_code" },
+			inferFromClient: ["client_id", "client_secret"],
+			exposedParams: [
+				"code",
+				"code_verifier",
+				"invitation_token",
+				"ip_address",
+				"device_id",
+				"user_agent"
+			],
+			optionalParams: [
+				"code_verifier",
+				"invitation_token",
+				"ip_address",
+				"device_id",
+				"user_agent"
+			]
+		},
+		{
+			name: "authenticate_with_refresh_token",
+			targetVariant: "RefreshTokenSessionAuthenticateRequest",
+			defaults: { grant_type: "refresh_token" },
+			inferFromClient: ["client_id", "client_secret"],
+			exposedParams: [
+				"refresh_token",
+				"organization_id",
+				"ip_address",
+				"device_id",
+				"user_agent"
+			],
+			optionalParams: [
+				"organization_id",
+				"ip_address",
+				"device_id",
+				"user_agent"
+			]
+		},
+		{
+			name: "authenticate_with_magic_auth",
+			targetVariant: "MagicAuthCodeSessionAuthenticateRequest",
+			defaults: { grant_type: "urn:workos:oauth:grant-type:magic-auth:code" },
+			inferFromClient: ["client_id", "client_secret"],
+			exposedParams: [
+				"code",
+				"email",
+				"invitation_token",
+				"ip_address",
+				"device_id",
+				"user_agent"
+			],
+			optionalParams: [
+				"invitation_token",
+				"ip_address",
+				"device_id",
+				"user_agent"
+			]
+		},
+		{
+			name: "authenticate_with_email_verification",
+			targetVariant: "EmailVerificationCodeSessionAuthenticateRequest",
+			defaults: { grant_type: "urn:workos:oauth:grant-type:email-verification:code" },
+			inferFromClient: ["client_id", "client_secret"],
+			exposedParams: [
+				"code",
+				"pending_authentication_token",
+				"ip_address",
+				"device_id",
+				"user_agent"
+			],
+			optionalParams: [
+				"ip_address",
+				"device_id",
+				"user_agent"
+			]
+		},
+		{
+			name: "authenticate_with_totp",
+			targetVariant: "MFATotpSessionAuthenticateRequest",
+			defaults: { grant_type: "urn:workos:oauth:grant-type:mfa-totp" },
+			inferFromClient: ["client_id", "client_secret"],
+			exposedParams: [
+				"code",
+				"pending_authentication_token",
+				"authentication_challenge_id",
+				"ip_address",
+				"device_id",
+				"user_agent"
+			],
+			optionalParams: [
+				"ip_address",
+				"device_id",
+				"user_agent"
+			]
+		},
+		{
+			name: "authenticate_with_organization_selection",
+			targetVariant: "OrganizationSelectionSessionAuthenticateRequest",
+			defaults: { grant_type: "urn:workos:oauth:grant-type:organization-selection" },
+			inferFromClient: ["client_id", "client_secret"],
+			exposedParams: [
+				"pending_authentication_token",
+				"organization_id",
+				"ip_address",
+				"device_id",
+				"user_agent"
+			],
+			optionalParams: [
+				"ip_address",
+				"device_id",
+				"user_agent"
+			]
+		},
+		{
+			name: "authenticate_with_device_code",
+			targetVariant: "DeviceCodeSessionAuthenticateRequest",
+			defaults: { grant_type: "urn:ietf:params:oauth:grant-type:device_code" },
+			inferFromClient: ["client_id"],
+			exposedParams: [
+				"device_code",
+				"ip_address",
+				"device_id",
+				"user_agent"
+			],
+			optionalParams: [
+				"ip_address",
+				"device_id",
+				"user_agent"
+			]
+		}
+	] },
+	"POST /connect/applications": { split: [{
+		name: "create_oauth_application",
+		targetVariant: "CreateOAuthApplication",
+		defaults: { application_type: "oauth" },
+		exposedParams: [
+			"name",
+			"is_first_party",
+			"description",
+			"scopes",
+			"redirect_uris",
+			"uses_pkce",
+			"organization_id"
+		]
+	}, {
+		name: "create_m2m_application",
+		targetVariant: "CreateM2MApplication",
+		defaults: { application_type: "m2m" },
+		exposedParams: [
+			"name",
+			"organization_id",
+			"description",
+			"scopes"
+		]
+	}] }
+};
+//#endregion
+//#region src/policy/mount-rules.ts
+/**
+* Service-level remounting. Maps IR service name → target service/namespace
+* (PascalCase). All operations in the source service are mounted on the
+* target unless overridden per-operation in {@link operationHints}.
+*/
+const mountRules = {
+	MultiFactorAuthChallenges: "MultiFactorAuth",
+	Permissions: "Authorization",
+	WorkosConnect: "Connect",
+	Applications: "Connect",
+	ApplicationClientSecrets: "Connect",
+	Connections: "SSO",
+	Directories: "DirectorySync",
+	DirectoryGroups: "DirectorySync",
+	DirectoryUsers: "DirectorySync",
+	FeatureFlagsTargets: "FeatureFlags",
+	OrganizationsFeatureFlags: "FeatureFlags",
+	UserManagementUsersFeatureFlags: "FeatureFlags",
+	OrganizationsApiKeys: "ApiKeys",
+	UserManagementSessionTokens: "UserManagement",
+	UserManagementAuthentication: "UserManagement",
+	UserManagementCorsOrigins: "UserManagement",
+	UserManagementUsers: "UserManagement",
+	UserManagementInvitations: "UserManagement",
+	UserManagementJWTTemplate: "UserManagement",
+	UserManagementMagicAuth: "UserManagement",
+	UserManagementOrganizationMembership: "OrganizationMembership",
+	UserManagementOrganizationMembershipGroups: "OrganizationMembership",
+	UserManagementRedirectUris: "UserManagement",
+	UserManagementUsersAuthorizedApplications: "UserManagement",
+	UserManagementDataProviders: "Pipes",
+	UserManagementMultiFactorAuthentication: "MultiFactorAuth"
+};
+//#endregion
+//#region src/policy/model-hints.ts
+/**
+* Model placement hints — used by emitters that call
+* `assignModelsToServices` so hinted models land in the configured service
+* instead of the default first-reference winner.
+*/
+const modelHints = {
+	User: "UserManagementUsers",
+	UserOrganizationMembershipBaseListData: "Groups",
+	UserApiKeyOwner: "UserManagementUsers"
+};
+//#endregion
+//#region src/policy/transforms.ts
+/**
+* NestJS-style operationId transform. Strips "Controller" and extracts the
+* action after the first underscore: `FooController_bar` -> `bar`.
+*/
+function nestjsOperationIdTransform(id) {
+	const stripped = id.replace(/Controller/g, "");
+	const idx = stripped.indexOf("_");
+	return idx !== -1 ? toCamelCase(stripped.slice(idx + 1)) : toCamelCase(stripped);
+}
+/**
+* Explicit renames plus suffix stripping applied during IR schema extraction.
+* Keeps `Dto`/`Json`/`Urn…` schema names consistent with the names already
+* exposed by the published SDKs.
+*/
+const COLLISION_RENAMES = {
+	Error: "ErrorResponse",
+	Object: "VaultObject",
+	OrganizationDto: "OrganizationInput",
+	RedirectUriDto: "RedirectUriInput",
+	AuditLogSchemaDto: "AuditLogSchemaInput",
+	AuditLogSchemaActorDto: "AuditLogSchemaActorInput",
+	AuditLogSchemaTargetDto: "AuditLogSchemaTargetInput",
+	ListData: "Role",
+	ListModel: "RoleList",
+	EventListListMetadata: "EventListMetadata",
+	RadarAction: "RadarListAction",
+	RadarType: "RadarListType"
+};
+function schemaNameTransform(name) {
+	if (COLLISION_RENAMES[name]) return COLLISION_RENAMES[name];
+	return name.replace(/Dto/g, "").replace(/DTO/g, "").replace(/Json$/, "").replace(/^Urn(?:IetfParams|Workos)O[Aa]uthGrantType/, "");
+}
+/**
+* Pre-IR spec overlay — patch around upstream spec quirks that would otherwise
+* emit breaking SDK changes. See docs/breaking-change-playbook.md and the
+* oagen `transformSpec` docs for usage. Reach for this only when the upstream
+* fix can't land in time AND the change is genuinely additive.
+*/
+function transformSpec(spec) {
+	const schemas = spec.components?.schemas;
+	const paths = spec.paths;
+	if (!schemas || !paths) return spec;
+	const forkedListRef = "#/components/schemas/UserlandUserOrganizationMembershipBaseWithUserList";
+	const originalListRef = "#/components/schemas/UserlandUserOrganizationMembershipBaseList";
+	for (const pathItem of Object.values(paths)) for (const op of Object.values(pathItem)) {
+		const schema = op.responses?.["200"]?.content?.["application/json"]?.schema;
+		if (schema?.$ref === forkedListRef) schema.$ref = originalListRef;
+	}
+	const itemProps = schemas["UserlandUserOrganizationMembershipBaseList"]?.properties?.data?.items;
+	if (itemProps?.properties && !itemProps.properties.user) {
+		itemProps.properties.user = {
+			$ref: "#/components/schemas/UserlandUser",
+			description: "The user that belongs to the organization through this membership."
+		};
+		if (itemProps.required && !itemProps.required.includes("user")) itemProps.required.push("user");
+	}
+	delete schemas["UserlandUserOrganizationMembershipBaseWithUser"];
+	delete schemas["UserlandUserOrganizationMembershipBaseWithUserList"];
+	if (schemas["JwtTemplate"] && !schemas["JwtTemplateResponse"]) {
+		schemas["JwtTemplateResponse"] = schemas["JwtTemplate"];
+		delete schemas["JwtTemplate"];
+		const oldRef = "#/components/schemas/JwtTemplate";
+		const newRef = "#/components/schemas/JwtTemplateResponse";
+		for (const pathItem of Object.values(paths)) for (const op of Object.values(pathItem)) {
+			const responses = op.responses;
+			for (const response of Object.values(responses ?? {})) {
+				const schema = response.content?.["application/json"]?.schema;
+				if (schema?.$ref === oldRef) schema.$ref = newRef;
+			}
+		}
+	}
+	return spec;
+}
+//#endregion
+export { modelHints, mountRules, nestjsOperationIdTransform, operationHints, schemaNameTransform, transformSpec };

package/package.json

@@ -1,23 +1,67 @@
 {
   "name": "@workos/openapi-spec",
-  "version": "0.4.0",
-  "description": "WorkOS OpenAPI specification and TypeScript types",
+  "version": "0.5.0",
+  "type": "module",
+  "description": "WorkOS OpenAPI specification, TypeScript types, and SDK resolution policy",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/workos/openapi-spec.git"
   },
+  "types": "./dist/types.d.ts",
   "files": [
-    "open-api-spec.yaml",
-    "types.d.ts"
+    "dist/"
   ],
-  "types": "types.d.ts",
   "exports": {
     ".": {
-      "types": "./types.d.ts",
-      "default": "./open-api-spec.yaml"
+      "types": "./dist/types.d.ts",
+      "default": "./dist/open-api-spec.yaml"
     },
-    "./spec": "./open-api-spec.yaml",
+    "./spec": "./dist/open-api-spec.yaml",
+    "./policy": {
+      "types": "./dist/policy.d.mts",
+      "import": "./dist/policy.mjs"
+    },
+    "./operation-overrides/node": "./dist/operationOverrides.node.json",
     "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@workos/oagen": "^0.22.0"
+  },
+  "scripts": {
+    "build:policy": "tsdown",
+    "generate:postman": "tsx scripts/postman/generate.ts",
+    "generate:postman:local": "tsx scripts/postman/generate.ts --local",
+    "sdk:resolve": "npx oagen resolve --spec spec/open-api-spec.yaml",
+    "sdk:generate": "bash scripts/sdk-generate.sh",
+    "sdk:diff": "bash scripts/sdk-diff.sh",
+    "sdk:verify": "bash scripts/sdk-verify.sh",
+    "sdk:extract": "bash scripts/sdk-extract.sh",
+    "sdk:compat-extract": "bash scripts/sdk-compat-extract.sh",
+    "sdk:compat-diff": "bash scripts/sdk-compat-diff.sh",
+    "sdk:compat-summary": "bash scripts/sdk-compat-summary.sh",
+    "sdk:compat-report": "node scripts/sdk-compat-pr-comment.mjs --artifacts-root .oagen --output compat-report.md --build-result success",
+    "sdk:languages": "node -e \"console.log(JSON.parse(require('fs').readFileSync('.github/sdk-matrix.json','utf8')).map(e=>e.language).join('\\n'))\"",
+    "sdk:generate-all": "bash scripts/sdk-generate-all.sh --parent-dir",
+    "sdk:check": "npx oagen resolve --spec spec/open-api-spec.yaml --format json > /dev/null && echo 'Config loaded successfully'",
+    "dev:link": "npm link @workos/oagen @workos/oagen-emitters",
+    "dev:unlink": "npm install",
+    "prepare": "husky"
+  },
+  "overrides": {
+    "js-yaml": "^4.2.0",
+    "lodash": "^4.17.23"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.9.1",
+    "@workos/oagen-emitters": "^0.16.0",
+    "diff2html": "^3.4.56",
+    "husky": "^9.1.7",
+    "js-yaml": "^4.2.0",
+    "openapi-to-postmanv2": "^6.0.1",
+    "tsdown": "^0.22.1",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
   }
 }