feat(oagen[2/2]): Update existing SDK modules with generated types, docs, and serializers

[gjtorikian]

Description

This PR is the output of running npm run sdk:generate:node --target ../backend/workos-node against the existing SDK. Everything in this diff was produced by the generator in a single run — no manual edits.

The changes fall into a few categories:

JSDoc on every public method

The generator pulls descriptions, parameter docs, return types, and error codes directly from the OpenAPI spec and attaches them as JSDoc comments. This affects every service class: api-keys, audit-logs, authorization, directory-sync, events, feature-flags, mfa, organizations, pipes, sso, user-management, and widgets. No method signatures or behavior changed—just documentation.

Serialize functions and Response interfaces

Previously, most modules only had deserialize* functions (wire → SDK model). The generator now produces the inverse serialize* functions (SDK model → wire) and corresponding *Response interfaces. These are needed for features like request body serialization and round-trip type safety, and will be consumed by service methods as additional endpoints are wired up.

Six new user-management sub-services

The generator identified groups of user-management endpoints that the API spec treats as distinct resources:

• UserManagementSessionTokens
• UserManagementCorsOrigins
• UserManagementJWTTemplate
• UserManagementRedirectUris
• UserManagementUsersAuthorizedApplications
• UserManagementDataProviders

These are wired into workos.ts as new readonly properties. Like the naming decisions in PR #1535 (AdminPortal, Permissions), these names come from the generator and match the API docs grouping.

New dependency files (244 new, 39 modified)

Each modified file may import new types that didn't exist before. The generator only integrates files that are transitively reachable from resource/client entry points via the import graph — two layers of tree-shaking (model-level in generate-files.ts and file-level in integrate.ts) prevent orphan serializers, fixtures, and interfaces from being written to the target.

Note: this is the second of two PRs. PR #1535 introduced the new services; this one updates existing services.

[dandorman]

Here's what Claude found, and I double checked.

1. JSDoc placed on wrong methods (oagen bug — HIGH)

   The generator appears to match JSDoc to methods by position rather than by name/operationId. This causes off-by-one mismatches in files where the existing method order doesn't match the OpenAPI spec order:

   • src/authorization/authorization.ts — "List environment roles" JSDoc is on createEnvironmentRole(), "Create an environment role" is on listEnvironmentRoles(), etc.
   • src/organizations/organizations.ts — "Create an Organization Domain" JSDoc is on createOrganization()
   • src/user-management/user-management.ts — "List authentication factors" JSDoc appears on enrollAuthFactor()

   This will mislead anyone using IDE hover docs.

2. Lost @deprecated notice (SEMANTIC)
   src/authorization/authorization.ts — the hand-written @deprecated Use workos.permissions.delete() instead on deletePermission() was silently replaced by the generator's JSDoc ("Remove a permission from an organization role"). The deprecation signal is gone.

3. Lost SDK-specific documentation (SEMANTIC)
   src/sso/sso.ts — the detailed hand-written JSDoc on getProfileAndToken() (documenting PKCE flow, public vs confidential client auto-detection, OAuth 2.1 behavior, @throws) was replaced with a generic API description from the OpenAPI spec.

4. Duplicate ConnectionType enum (COMPILE RISK)
   src/sso/interfaces/ now has both connection-type.interface.ts and a pre-existing connection-type.enum.ts, both exporting export enum ConnectionType. The new one adds ~15 new members. If both are re-exported from the barrel, this is a duplicate identifier error.

5. Redundant union type (oagen bug — MINOR)
   src/mfa/interfaces/authentication-factor.interface.ts has totp?: AuthenticationFactorTotp | AuthenticationFactorTotp;. Same type unioned with itself — likely from an OpenAPI oneOf with duplicate refs.

6. Missing barrel exports (oagen bug — MINOR)
   src/authorization/interfaces/index.ts doesn't export role-list.interface.ts or role-assignment-resource.interface.ts. Similarly, src/audit-logs/interfaces/index.ts doesn't export audit-log-schema.interface.ts.

7. "auto-generated" header on mixed files (MISLEADING)
   Files like sso.ts and user-management.ts now have // This file is auto-generated by oagen. Do not edit. at the top, but they still contain substantial hand-written code. The header implies the entire file is generated.

[gjtorikian]

@dandorman appreciate the review! addressed the concerns in the last push.

[dandorman]

It doesn't look any of the seven items substantially changed? I get that some of them might be WONTFIX or working as intended, but 1 and maybe 2 seem like things that need to be fixed.

[gjtorikian]

Ugh, really sorry about. I've now manually verified rather than trusting that jerk, Claude.

[dandorman]

Looks like 1, 3, 4, and 5 were all fixed! 🎉 Of the remaining ones:

2. Losing the @deprecated tag on deletePermission still feels weird? (Unless we're _un_deprecating it?)
3. Missing barrel exports. Maybe this is intentional? Looks like they're exported from the file—maybe they don't need to be exported via the barrel file.
4. The autogenerated // This file is auo-generated ... warning at the top. I don't think this is a big deal either.

Anyway, 2 is the only one that still seems like a concern? If you'd like to proceed, though, let me know. Just making sure it's intentional.