feat(api): always announce as Convert SDK via ConvertAgent User-Agent - #41
Merged
Conversation
Set the User-Agent header to ConvertAgent/1.0 on every outbound request from ApiManager, after the header merge so neither $headers nor $defaultHeaders can override it. This matches the metrics-endpoint's isConvertAgentUA bypass and removes the fragility of relying on the source field for legitimate-SDK-traffic identification. Why this matters: ConvertSDK::create() lets customers override network.source via config, and a VERSION env var override hook exists in ConvertSDK.php. Either could break the metrics-endpoint's source- field bypass silently. The UA is now an SDK invariant: not config- driven, not env-driven, baked at the HTTP transport layer. Source-field bypass at the metrics endpoint stays in place as legacy fallback for already-deployed SDK versions. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Replaces the hard-coded 'ConvertAgent/1.0' literal in ApiManager with a private class constant, matching the existing pattern for DEFAULT_HEADERS and DEFAULT_TRACK_ENDPOINT. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the ApiManager to include a mandatory User-Agent header, ConvertAgent/1.0, in all outgoing requests to ensure the SDK is correctly identified by bot filters. A review comment suggests updating the spelling of 'recognises' to 'recognizes' in the code comments to maintain consistency with the American English conventions used throughout the codebase.
I am having trouble creating individual review comments. Click here to see my feedback.
packages/Api/src/ApiManager.php (220)
The comment uses the British English spelling 'recognises', while the rest of the codebase (e.g., 'Authorization' on line 167, 'transformation' on line 107) follows American English. For consistency with the existing code style, 'recognizes' should be used.
// bot filter recognizes us via its `isConvertAgentUA` bypass. Set
DmytroConvert
approved these changes
May 23, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
User-Agent: ConvertAgent/1.0on every outbound HTTP request fromApiManager, applied after the per-call and default header merge so it cannot be overridden by config.isConvertAgentUAbypass — replaces dependence on the source-field bypass for SDK-traffic identification.Why now
The May 19 metrics-endpoint isbot regression exposed that:
ConvertSDK::create()lets customers overridenetwork.sourcevia config (packages/Php-sdk/src/Config/DefaultConfig.php:49default'php-sdk').VERSIONenv-var override hook exists inConvertSDK.php:70-73(for CI/release builds). If a future release stampsVERSION=php2.1.0, the wiresourcebecomesphp2.1.0and matches neither of the metrics-endpoint bypass conditions today (endsWith('-sdk')or/^js\d+\.\d+\.\d+/). Silent customer outage.Baking the UA at the transport layer makes the announcement an SDK invariant — not config-driven, not env-driven, not customer-overridable. Metrics-endpoint code stays untouched (the
isConvertAgentUAbypass has been in place since 2026-05-20).What stays in place
The source-field bypass at the metrics endpoint remains as legacy fallback for already-deployed SDK versions. Customers on older SDKs continue to work via the
endsWith('-sdk')path.Test plan
MockHttpClienttest) thatUser-Agent: ConvertAgent/1.0is present on outbound requestsbotCheckSkippedevents fire with emptysource+userAgent: "ConvertAgent/1.0"(the ConvertAgent UA bypass path)🤖 Generated with Claude Code