Release v8.0.0: Universal Runtime Support & API Modernization

[nicknisi]

Overview

Version 8 is a major release focused on universal runtime compatibility, PKCE authentication support, and API modernization. The SDK now works seamlessly across Node.js, Deno, Bun, and Cloudflare Workers while removing long-deprecated APIs.

---

BREAKING CHANGES

Runtime & Build System

1. Node.js Version Requirement (BREAKING)

• Changed: Minimum Node.js version: 16 → 20
• Reason: Node 18 reached end-of-life in April 2025
• Files: package.json (engines.node)
• Migration: Update to Node.js 20 or higher

2. Package Type Change to ESM-First (BREAKING)

• Changed: package.json now includes "type": "module"
• Impact: The package is now ESM-first with dual CJS/ESM exports
• Files: package.json
• Migration: Most users won't need changes due to conditional exports, but projects with custom build configurations may need adjustments

3. Build System Migration (Internal)

• Changed: Migrated from tsc to tsdown (Rolldown/Oxc-based) for building
• Added: tsdown.config.ts configuration
• Removed: tslint.json, tsup.config.ts
• Impact: Faster builds, lower memory usage, improved tree-shaking

Removed Internal Classes (BREAKING)

4. HTTP Client Removal (BREAKING)

• Removed: NodeHttpClient class and createHttpClient() method
• Files: src/common/net/node-client.ts (deleted)
• Impact: Only affects deep imports into internal modules (never part of public API)
• Migration: Use WorkOS instance instead - HTTP is handled automatically

5. Crypto Provider Removal (BREAKING)

• Removed: NodeCryptoProvider, IronSessionProvider, EdgeIronSessionProvider, WebIronSessionProvider
• Changed: Now using iron-webcrypto v2 directly with lightweight wrapper
• Files: src/common/crypto/node-crypto-provider.ts (deleted), src/common/iron-session/* (deleted), src/common/crypto/seal.ts (added)
• Impact: Only affects deep imports into internal modules
• Migration: Use WorkOS instance methods - crypto is handled automatically

Directory Sync (BREAKING)

6. DirectoryUser Interface Changes (BREAKING)

• Removed fields:
  • emails → Use customAttributes.emails
  • username → Use customAttributes.username
  • jobTitle → Use customAttributes.jobTitle
• Removed utility: getPrimaryEmail() function
• Files: src/directory-sync/interfaces/directory-user.interface.ts, src/directory-sync/utils/get-primary-email.ts (deleted)
• Migration:

  // v7
  user.emails
  user.username
  user.jobTitle
  
  // v8
  user.customAttributes?.emails
  user.customAttributes?.username
  user.customAttributes?.jobTitle

User Management (BREAKING)

7. AuthorizationURLOptions Changes (BREAKING)

• Removed: context field (no longer supported)
• Files: src/user-management/interfaces/authorization-url-options.interface.ts
• Migration: Remove the context parameter from authorization URL calls

8. Removed Deprecated Methods (BREAKING)

• Removed:
  • sendMagicAuthCode() → Use userManagement.sendMagicCode() instead
  • sendPasswordResetEmail() → Use userManagement.sendPasswordResetEmail() instead
  • refreshAndSealSessionData() → Use new session helper methods instead
• Files: src/user-management/user-management.ts, serializers removed

9. listOrganizationMemberships Requires userId or organizationId (BREAKING)

• Changed: listOrganizationMemberships() now requires either userId or organizationId
• Files: src/user-management/user-management.ts
• Migration:

  // v7 - Could call without parameters
  workos.userManagement.listOrganizationMemberships();
  
  // v8 - Must specify userId or organizationId
  workos.userManagement.listOrganizationMemberships({ userId: 'user_123' });
  // OR
  workos.userManagement.listOrganizationMemberships({ organizationId: 'org_456' });

SSO (BREAKING)

10. SSOAuthorizationURLOptions Type Changes (BREAKING)

• Changed: Converted to discriminated union for type safety
• Removed: domain field (deprecated)
• Files: src/sso/interfaces/authorization-url-options.interface.ts
• Impact: Stricter TypeScript types - must now specify exactly one of: connection, organization, or provider
• Migration:

  // v7 - Multiple options allowed
  { connection: 'conn_123', organization: 'org_456' } // Both accepted
  
  // v8 - Mutually exclusive (enforced by types)
  { connection: 'conn_123' } // OR
  { organization: 'org_456' } // OR
  { provider: 'GoogleOAuth' }

11. Connection Interface (BREAKING)

• Removed: Several deprecated internal fields
• Files: src/sso/interfaces/connection.interface.ts
• Migration: Use only documented fields

MFA (BREAKING)

12. Method Removal (BREAKING)

• Removed: verifyFactor() method
• Files: src/mfa/mfa.ts, src/mfa/interfaces/verify-factor-options.ts (deleted)
• Migration: Use verifyChallenge() instead (same functionality)

  // v7
  await workos.mfa.verifyFactor({ authenticationFactorId, code });
  
  // v8
  await workos.mfa.verifyChallenge({ authenticationFactorId, code });

Organizations (BREAKING)

13. Organization Options Changes (BREAKING)

• Removed from CreateOrganizationOptions and UpdateOrganizationOptions:
  • allowProfilesOutsideOrganization
  • domains (use domainData instead)
• Files: src/organizations/interfaces/*.interface.ts
• Migration: Remove these fields from organization creation/update calls

14. Organization Domain Enum (BREAKING)

• Removed: LegacyVerified from OrganizationDomainState enum
• Files: src/organizations/interfaces/organization-domain.interface.ts
• Migration: Use Verified instead

Events (BREAKING)

15. Event Type Removals (BREAKING)

• Removed event interfaces:
  • DsyncDeactivatedEvent → Use dsync.deleted instead
  • OrganizationMembershipAdded → Not applicable in v8
  • OrganizationMembershipRemoved → Not applicable in v8
• Files: src/common/interfaces/event.interface.ts
• Migration:

  // v7
  if (event.event === 'dsync.deactivated') { }
  
  // v8
  if (event.event === 'dsync.deleted') { }

Vault (BREAKING)

16. Removed Deprecated Method Aliases (BREAKING)

• Removed methods:
  • createSecret() → Use createObject() instead
  • listSecrets() → Use listObjects() instead
  • listSecretVersions() → Use listObjectVersions() instead
  • readSecret() → Use readObject() instead
  • describeSecret() → Use describeObject() instead
  • updateSecret() → Use updateObject() instead
  • deleteSecret() → Use deleteObject() instead
• Files: src/vault/vault.ts
• Migration: Replace all *Secret methods with *Object equivalents

Webhooks (NON-BREAKING)

17. constructEvent Payload Typing (NON-BREAKING)

• Changed: constructEvent payload parameter typed as Record<string, unknown> for better type safety
• Files: src/webhooks/webhooks.ts
• Impact: Stricter typing, but backwards compatible

---

NEW FEATURES

18. PKCE Authentication Support (NON-BREAKING)

• Added: Full PKCE (Proof Key for Code Exchange) support for public and confidential clients
• API key now optional: Initialize with just clientId for PKCE-only mode
• New methods:
  • userManagement.getAuthorizationUrlWithPKCE() - generates PKCE internally, returns { url, state, codeVerifier }
  • userManagement.authenticateWithCodeAndVerifier() - explicit PKCE token exchange
  • workos.pkce.generate() - manual PKCE generation
• Enhanced: authenticateWithCode() auto-detects client mode based on credentials
• Example:

  import { WorkOS } from '@workos-inc/node';
  
  // Public client (no API key)
  const workos = new WorkOS({ clientId: 'client_123' });
  
  // Generate authorization URL with PKCE
  const { url, state, codeVerifier } = await workos.userManagement.getAuthorizationUrlWithPKCE({
    redirectUri: 'myapp://callback',
    provider: 'authkit',
  });
  
  // Exchange code for tokens
  const { accessToken, refreshToken, user } = await workos.userManagement.authenticateWithCode({
    code: authCode,
    codeVerifier,
  });

19. createWorkOS Factory Function (NON-BREAKING)

• Added: createWorkOS() factory with compile-time type safety for public vs confidential clients
• Files: src/workos.ts
• Benefit: TypeScript will error at compile time if you try to use methods unavailable to public clients
• Example:

  import { createWorkOS } from '@workos-inc/node';
  
  // Public client - only PKCE methods available
  const publicClient = createWorkOS({ clientId: 'client_123' });
  publicClient.userManagement.getAuthorizationUrlWithPKCE({ ... }); // ✅ Works
  publicClient.userManagement.listUsers(); // ❌ TypeScript error
  
  // Confidential client - full access
  const serverClient = createWorkOS({ apiKey: 'sk_...', clientId: 'client_123' });
  serverClient.userManagement.listUsers(); // ✅ Works

20. Universal Runtime Support (NON-BREAKING)

• Improved: Better support for Deno, Bun, and Cloudflare Workers
• Added: Conditional exports in package.json for runtime-specific entry points
• Files: package.json (exports), src/index.worker.ts
• Example:

  // Cloudflare Workers
  import { WorkOS } from '@workos-inc/node/worker';
  
  // Deno
  import { WorkOS } from 'npm:@workos-inc/node';
  
  // Bun (same as Node.js)
  import { WorkOS } from '@workos-inc/node';

21. Environment Variable Helper (NON-BREAKING)

• Added: Internal getEnv() helper for better cross-runtime environment variable access
• Files: src/common/utils/env.ts
• Benefit: Works consistently across Node.js, Deno, Cloudflare Workers, etc.

22. Pagination Improvements (NON-BREAKING)

• Changed: AutoPaginatable now properly defaults PaginationOptions generic parameter
• Files: src/common/utils/pagination.ts
• Benefit: Better TypeScript inference and type safety

23. Runtime Analytics (NON-BREAKING)

• Added: Runtime information included in User-Agent string for better debugging
• Files: src/workos.ts
• Impact: Helps identify runtime-specific issues

---

INTERNAL IMPROVEMENTS

24. Linting Migration (Internal)

• Changed: Migrated from TSLint to ESLint with flat config
• Added: eslint.config.mjs
• Removed: tslint.json
• Impact: Better code quality checks, modern linting setup

25. Runtime Testing (Internal)

• Added: New GitHub Actions workflow for testing across multiple runtimes
• Added: Ecosystem check script (scripts/ecosystem-check.ts)
• Files: .github/workflows/runtime-tests.yml
• Benefit: Ensures SDK works correctly in all supported runtimes

26. Dependency Updates (Internal)

• Updated: All dependencies to latest compatible versions
• Updated: Development tooling (Jest 30, TypeScript 5.9, etc.)
• Removed: External leb and qs packages - replaced with internal vanilla implementations
• Files: package.json, package-lock.json

27. Test Infrastructure (Internal)

• Updated: Jest configuration migrated to CommonJS
• Added: Jest ESM transform
• Files: jest.config.cjs, jest-transform-esm.cjs
• Updated: Worker test environment with latest Miniflare

28. Dynamic jose Import (Internal)

• Added: Dynamic import wrapper for jose to support Node.js 20.15-20.18 compatibility
• Files: src/common/utils/jose.ts
• Benefit: Wider Node.js version compatibility

29. Runtime-Agnostic UUIDs (Internal)

• Changed: Now uses globalThis.crypto.randomUUID instead of Node-specific crypto
• Files: Various
• Benefit: Better cross-runtime compatibility

---

REMOVED (Previously Announced)

30. /client Entry Point Removed (BREAKING)

• Removed: The @workos-inc/node/client entry point
• Migration: Use the main SDK without an API key instead:

  // Old approach (v8 beta)
  import { userManagement } from '@workos-inc/node/client';
  const url = userManagement.getAuthorizationUrl({ ... });
  
  // New approach (v8 final)
  import { WorkOS } from '@workos-inc/node';
  const workos = new WorkOS({ clientId: 'client_...' });
  const url = workos.userManagement.getAuthorizationUrl({ ... });

---

Files Changed Summary

• Major additions: PKCE support, createWorkOS factory, runtime-specific exports, environment helper
• Major deletions: Internal HTTP/crypto providers, deprecated methods, legacy event types, /client entry point
• Configuration: New build system (tsdown), new linting (ESLint), updated Jest

---

Migration Guide

See V8_MIGRATION_GUIDE.md for detailed migration instructions.

---

Testing

• All existing tests updated and passing
• Runtime compatibility tests added
• Worker environment tests updated
• Ecosystem check script validates multi-runtime support

[benasher44]

Since you're going for dual ESM/CJS, you might want to check "are the types wrong". For example: https://arethetypeswrong.github.io/?p=%40workos-inc%2Fnode%408.0.0-rc.2

[socket-security]

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

View full report

[greptile-apps]

Too many files changed for review.

[greptile-apps]

Too many files changed for review.

[greptile-apps]

Too many files changed for review.

[greptile-apps]

Too many files changed for review.

[greptile-apps]

Too many files changed for review.

[greptile-apps]

Too many files changed for review.

[greptile-apps]

Too many files changed for review.

[greptile-apps]

Too many files changed for review.

[greptile-apps]

Too many files changed for review.

[greptile-apps]

Too many files changed for review.