[v8] Add runtime analytics to User-Agent string

[nicknisi]

Summary

Add runtime and version detection to the WorkOS Node SDK User-Agent string to gather analytics about JavaScript runtime environments and versions being used by customers.

Changes

Core Implementation

• New utility: src/common/utils/runtime-info.ts - Detects runtime type and version across Node.js, Deno, Bun, Cloudflare Workers, and other environments
• User-Agent enhancement: Modified createUserAgent() method in src/workos.ts to include runtime information in standard format
• Error handling: Graceful fallbacks when runtime version detection fails

User-Agent Format

Before: workos-node/8.0.0-beta.1 MyApp: 1.0.0
After: workos-node/8.0.0-beta.1 (node/v20.5.0) MyApp: 1.0.0

The new format follows standard User-Agent conventions with runtime information in parentheses, maintaining backward compatibility with existing analytics parsing.

Examples

• Node.js: workos-node/8.0.0-beta.1 (node/v20.5.0)
• Node.js with appInfo: workos-node/8.0.0-beta.1 (node/v20.5.0) MyApp: 1.0.0
• Deno: workos-node/8.0.0-beta.1 (deno/1.36.4)
• Edge runtime: workos-node/8.0.0-beta.1 (edge-light)

Testing

Unit Tests

• 17 comprehensive test cases for getRuntimeInfo() utility covering all runtime scenarios
• Mock testing for different environments (Node.js, Deno, Bun, edge runtimes)
• Error handling verification with graceful degradation
• Real-world testing with actual Node.js environment

Integration Tests

• Updated workos.spec.ts with runtime info mocking
• Jest snapshots updated to reflect new User-Agent format
• Backward compatibility verified for existing appInfo functionality

Benefits

For WorkOS Analytics

• Node.js adoption tracking: Monitor which Node.js versions are most popular
• Runtime diversity insights: Understand usage across Node.js, Deno, Bun, and edge environments
• Support optimization: Prioritize support for popular runtime versions
• Migration patterns: Track adoption of new JavaScript runtime versions

For Customer Support

• Environment debugging: Quickly identify runtime-specific issues from API logs
• Performance optimization: Focus optimization efforts on popular runtime combinations
• Compatibility planning: Make informed decisions about runtime support

Technical Details

Runtime Detection

• Cached detection: Uses existing detectRuntime() from env.ts for performance
• Version extraction: Safely extracts version numbers from runtime-specific globals
• Fallback mechanisms: Multiple strategies for version detection (e.g., Bun version from user-agent)
• Error resilience: Never crashes, gracefully degrades to runtime name only

Implementation Approach

• No configuration needed: Runtime info is always included (internal analytics feature)
• Zero breaking changes: Existing functionality unchanged
• Standards compliant: Follows established User-Agent format conventions
• Minimal overhead: One-time detection per process with cached results

Risk Mitigation

• Version detection failures: Graceful fallback to runtime name only
• Performance impact: Minimal (cached detection, ~1ms overhead)
• User-Agent length: Reasonable increase (~20 characters)
• Privacy concerns: No personally identifiable information collected

[greptile-apps]

PR Summary

Enhanced User-Agent string analytics by adding runtime environment detection for improved debugging and analytics tracking across different JavaScript runtimes.

• Implemented new runtime detection utility in src/common/utils/runtime-info.ts with comprehensive environment support (Node.js, Deno, Bun, Edge)
• Modified createUserAgent() in src/workos.ts to include runtime info like workos-node/8.0.0-beta.1 (node/v20.5.0)
• Added thorough test coverage in src/common/utils/runtime-info.spec.ts with 17 test cases
• Implemented graceful fallbacks for version detection failures to ensure robustness
• Used cached detection mechanism from existing env.ts for minimal performance impact

_{4 files reviewed, 3 comments
Edit PR Review Bot Settings | Greptile}