[v8] Add runtime analytics to User-Agent string #1293

nicknisi · 2025-06-12T15:48:10Z

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

Drop support for Node 16, which is long past EOL. This will be merged into the `version-8` branch. >[!WARNING] > >Node 18 is where we're moving to, but that will also be EOL in April, 2025. Does this require changes to the WorkOS Docs? E.g. the [API Reference](https://workos.com/docs/reference) or code snippets need updates. ``` [ ] Yes ``` If yes, link a related docs PR and add a docs maintainer as a reviewer. Their approval is required.

>[!Note] > >This PR is against the `version-8` branch. ## Description TSLint has been EOL for several years. This replaces it with typeScript-eslint and provides a comparable configuration for minimal changes to the code. ## Documentation Does this require changes to the WorkOS Docs? E.g. the [API Reference](https://workos.com/docs/reference) or code snippets need updates. ``` [ ] Yes ``` If yes, link a related docs PR and add a docs maintainer as a reviewer. Their approval is required.

## Description ## Documentation Does this require changes to the WorkOS Docs? E.g. the [API Reference](https://workos.com/docs/reference) or code snippets need updates. ``` [ ] Yes ``` If yes, link a related docs PR and add a docs maintainer as a reviewer. Their approval is required.

>[!note] >This is against the `version-8` branch, which drops support for Node 16, allowing for this update to happen. ## Description Update to latest version of iron-session. ## Documentation Does this require changes to the WorkOS Docs? E.g. the [API Reference](https://workos.com/docs/reference) or code snippets need updates. ``` [ ] Yes ``` If yes, link a related docs PR and add a docs maintainer as a reviewer. Their approval is required.

>[!note] >This change is against the `version-8` branch. ## Description Upgrade to Prettier v3 and commit minimal changes resulting from that. ## Documentation Does this require changes to the WorkOS Docs? E.g. the [API Reference](https://workos.com/docs/reference) or code snippets need updates. ``` [ ] Yes ``` If yes, link a related docs PR and add a docs maintainer as a reviewer. Their approval is required.

>[!note] >This change is against the `version-8` branch. ## Description Update to latest of the following dev dependencies - TypeScript - ts-jest - Jest - Supertest ## Documentation Does this require changes to the WorkOS Docs? E.g. the [API Reference](https://workos.com/docs/reference) or code snippets need updates. ``` [ ] Yes ``` If yes, link a related docs PR and add a docs maintainer as a reviewer. Their approval is required.

Adds tests and updates typing for pagination utils.

…emberships (#1250)

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}

src/common/utils/runtime-info.ts

src/common/utils/runtime-info.spec.ts

kendallstrautman and others added 17 commits June 11, 2025 14:33

Remove dsync.deactivated event (#1086)

396ba7b

Remove deprecated code for major version (#1224)

1063a5b

Add tests and typing updates for pagination utils (#1252)

64d0617

Adds tests and updates typing for pagination utils.

Make userId or organizationId required when calling listOrganizationM…

f08136c

…emberships (#1250)

[v8] Remove NodeCryptoProvider (#1270)

88f9bdd

[v8] remove NodeHttpClient (#1271)

9372291

[v8] Add Node 24 to CI testing (#1278)

939302b

[v8] Add other runtime checks for environment variables (#1279)

225d70a

[v8] Add ESM / CJS dual build (#1287)

c9f4d83

fix fga pagination

58e99e0

v8.0.0-beta.1

8c068af

nicknisi requested a review from a team as a code owner June 12, 2025 15:48

nicknisi requested review from kendallstrautman and removed request for a team June 12, 2025 15:48

greptile-apps bot reviewed Jun 12, 2025

View reviewed changes

src/common/utils/runtime-info.ts Outdated Show resolved Hide resolved

src/common/utils/runtime-info.ts Outdated Show resolved Hide resolved

src/common/utils/runtime-info.spec.ts Show resolved Hide resolved

nicknisi added 5 commits June 12, 2025 11:04

formatting

a6d2b16

add new runtime-info utility

476d31c

add createUserAgent method to WorkOS class

4a19971

update tests

48f689d

formatting

eacd64d

nicknisi force-pushed the nicknisi/runtime-info branch from bd54a1a to eacd64d Compare June 12, 2025 16:05

nicknisi added 3 commits June 12, 2025 11:39

formatting

2dca7ef

remove as any casts

71afb31

turn on noImplicitAny

707fd76

nicknisi added 2 commits June 12, 2025 13:02

normalize user agent version in snapshot tests

834ca7d

normalize node version number in tests

56c9fd4

nicknisi changed the title ~~Add runtime analytics to User-Agent string~~ [v8] Add runtime analytics to User-Agent string Jun 12, 2025

nicknisi requested a review from cmatheson June 12, 2025 20:40

nicknisi added 2 commits June 12, 2025 15:41

trigger CI

5184967

formatting

96089b3

nicknisi force-pushed the nicknisi/runtime-info branch from 4dbb78c to 96089b3 Compare June 12, 2025 20:43

nicknisi force-pushed the version-8 branch 2 times, most recently from 7912f61 to bee7e85 Compare June 30, 2025 19:28

nicknisi force-pushed the version-8 branch from 39ab2f2 to 1593c85 Compare July 17, 2025 16:44

nicknisi force-pushed the version-8 branch 2 times, most recently from 7a0eeb3 to 57b9aab Compare August 7, 2025 16:56

nicknisi force-pushed the version-8 branch 2 times, most recently from d4f3297 to d477188 Compare August 25, 2025 20:43

nicknisi force-pushed the version-8 branch from d477188 to 369afff Compare August 28, 2025 21:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[v8] Add runtime analytics to User-Agent string #1293

[v8] Add runtime analytics to User-Agent string #1293

Uh oh!

nicknisi commented Jun 12, 2025 •

edited

Loading

Uh oh!

greptile-apps bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

[v8] Add runtime analytics to User-Agent string #1293

Are you sure you want to change the base?

[v8] Add runtime analytics to User-Agent string #1293

Uh oh!

Conversation

nicknisi commented Jun 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Core Implementation

User-Agent Format

Examples

Testing

Unit Tests

Integration Tests

Benefits

For WorkOS Analytics

For Customer Support

Technical Details

Runtime Detection

Implementation Approach

Risk Mitigation

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

PR Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nicknisi commented Jun 12, 2025 •

edited

Loading