fix(streaming): identify the SDK on the WebSocket handshake

[karlwaldman]

What this is not

This started as "make sdk_version populate" (it sits at 1.65% of requests). That premise is refuted. I verified in production that every SDK which sends a User-Agent is already parsed correctly — oilpriceapi-node/1.2.6 node/v22.23.2 arrives with sdk_language=node, sdk_version=1.2.6. There is no client-side or server-parsing defect on the HTTP path.

The 1.65% is a denominator artefact plus contamination, not a bug in this repo (details in the session summary; the fixes are server-side and are being routed separately). Notably the bucket named sdk-node is 8 requests ours out of 27,874 — the rest is generic node/axios/node-fetch traffic the server files under the same name.

What this actually fixes

One real, verified gap in this repo: the WebSocket handshake sent no SDK identification at all.

src/resources/streaming.ts sent only Authorization on the ActionCable upgrade. That upgrade is an ordinary HTTP request, so a streaming client was indistinguishable from a hand-rolled WebSocket and dropped out of SDK attribution entirely — while the HTTP path was attributed correctly all along.

The Go SDK already does this properly (stream.go sets User-Agent). Node and Python did not. This brings Node into line.

Honest scope of the benefit

This does not by itself make streaming measurable. ApplicationCable::Connection#track_connection in oilpriceapi-api deliberately does not record user_agent — issue #1291 removed it as fingerprinting data under data minimisation. So this is a prerequisite, not a win: the client now sends what a server could attribute, and whether the server should record it is a separate privacy decision, not something this PR presumes.

I would rather say that plainly than imply a metric will move.

The regression guard is the durable half

The server parses attribution with exactly:

/oilpriceapi-([a-z0-9-]+)\/v?([\d]+\.[\d]+\.?[\d]*)/i

A User-Agent that stops matching it still returns 200. The request succeeds and the SDK silently disappears from adoption reporting — a failure no HTTP-level test would ever catch, and nothing on either side guarded the shape. The new tests assert the parsed language and version, not a substring, across the HTTP, demo and WebSocket paths.

Red-capability proven

Rewriting buildUserAgent() to emit oilpriceapi-node-v1.2.6 fails 4 tests (2 pre-existing, 2 new). The WebSocket test failed before the fix and passes after. Reverted before commit.

Verification

npm run build   # clean
npx vitest run  # 34 files, 508 passed | 1 skipped

Please do not merge yet

Per house rules an SDK release changes what customers run. Leaving this open for review.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JKAExynd9zoKwt6rYA66EA

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f6745c50-b955-4ae8-bef8-381c3d20d72a

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}