feat(DXG-1408): add analytics headers

[Maksim Filipenka (mfilipenka)]

No description provided.

[linear-code]

DXG-1408

[Copilot]

Pull request overview

Adds SDK-managed analytics metadata propagation to Corti requests by introducing a standardized X-Corti-Analytics header for HTTP calls and an x-corti-analytics query parameter for WebSocket handshakes, enabling consistent downstream analytics attribution.

Changes:

• Introduces src/custom/utils/analytics.ts helpers to build an SDK-owned analytics payload and merge it into headers/query params.
• Wires analytics query parameters into Custom Stream/Transcribe WebSocket connection flows.
• Adds unit tests validating payload construction, reserved-key behavior, and merge semantics.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/unit/utils/analytics.test.ts	Adds unit coverage for analytics payload building and header/query merging behavior.
src/custom/utils/sdkHeaderNames.ts	Registers X-Corti-Analytics as an SDK-managed header name.
src/custom/utils/analytics.ts	Implements analytics payload construction, serialization, and merge helpers.
src/custom/transcribe/CustomTranscribe.ts	Injects analytics into WebSocket handshake query parameters for transcribe flows.
src/custom/stream/CustomStream.ts	Injects analytics into WebSocket handshake query parameters for stream flows.
src/custom/CortiClient.ts	Adds analytics option and merges analytics header into client default headers.

Suppressed comments (1)

tests/unit/utils/analytics.test.ts:51

• This assertion relies on a specific JSON string ordering inside the query parameter value. Consider parsing the JSON value and asserting the object contents to avoid order-dependent failures.

        it("returns a single x-corti-analytics query parameter with a JSON value", () => {
            expect(analyticsQueryParams({ source: "web" })).toEqual({
                [X_CORTI_ANALYTICS_QUERY]: `{"sdk_version":"${SDK_VERSION}","sdk_type":"javascript","source":"web"}`,
            });
        });

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (2)

README.md:694

• This says analytics metadata is sent “with every request”, but the implementation only adds the X-Corti-Analytics/x-corti-analytics payload when analytics is provided (client-level analytics or a per-call header/query param). Either update the docs to match the current behavior, or change the code to always send the reserved keys even when analytics isn’t configured.

The SDK sends metadata about itself (`sdk_version`, `sdk_type`) with every request via the `X-Corti-Analytics` header (REST) or the `x-corti-analytics` query parameter (WebSocket). You can extend this payload with your own fields on the client constructor, and overlay extra fields on individual REST calls or WebSocket connections.

src/custom/overrides/headers.ts:26

• mergeHeaders strips the x-corti-analytics key from all input objects, which changes merge semantics for that key: passing a later { "x-corti-analytics": null } no longer deletes a previously-set analytics header (it gets ignored). This is inconsistent with mergeHeadersOriginal behavior (null deletes) and makes it impossible to explicitly clear analytics on a specific call.

            if (key.toLowerCase() !== X_CORTI_ANALYTICS) {
                cleaned[key] = value;
                continue;
            }