[AGI-550] Add uiLibrary parameter to agent and PIA tracking events

[joesurf]

Summary

Our UI libraries (cio-ui-asa, cio-ui-pia) let a customer pass in their own cioClient. Events then carry that client's c tag (e.g. ciojs-client-2.94.0), so you can't tell they came from the library. We use c to measure which customers are on our UI libraries, and those customers currently show up as custom UIs.

This adds an optional uiLibrary parameter that the library sets on each call, so it identifies the library regardless of whose client sent the event:

• New optional parameter uiLibrary on the agent tracker methods (trackAgentSubmit, trackAgentResultLoadStarted, trackAgentResultLoadFinished, trackAgentResultClick, trackAgentResultView, trackAgentSearchSubmit, trackAgentButtonClick) and on all nine trackProductInsightsAgent* methods. The deprecated trackAssistant* methods delegate to the agent ones, so they support it too.
• Sent as the ui_library query parameter, e.g. ui_library=cio-ui-pia-1.4.0. It goes in the URL rather than the body so it appears in ALB logs, which only record the URL.
• c and everything else are unchanged. It's only sent when passed, so existing callers send exactly what they did before.
• JSDoc and tracker.d.ts updated.

Notes

• Backend: the behavioural API needs to accept the extra query parameter. The updated spec tests send it to the real API and expect ok, so CI confirms this.
• Name: ui_library is a proposal; happy to rename it. I avoided ui_lib because ui is already the user ID parameter.
• Follow-ups: constructorio-ui-pia and constructorio-ui-asa will pass uiLibrary on every tracking call once this is released. The agentic integrations dashboard will read ui_library first and fall back to the c prefix.

Test plan

• Spec: each agent, assistant and PIA tracker "required and optional parameters" test now passes uiLibrary and checks ui_library in the request URL (22 tests).
• npm run lint clean; npm run compile and tsd pass.
• Local smoke test against the compiled lib with a stubbed fetch:
  • ui_library is in the URL and the client's own c is kept.
  • Nothing is added to the body.
  • The parameter is left off when uiLibrary isn't passed.
• Full mocha suite in CI. It needs the test API keys, which aren't available locally.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

The additive implementation, declarations, and tests align with no blocking issues identified; live-API tests remain for CI.

0 open findings

What changed in this PR

Adds UI-library attribution to agent and PIA tracking events, independent of the customer’s client identifier.

Changes:

• Sends optional uiLibrary as the ui_library query parameter.
• Updates TypeScript declarations and JSDoc.
• Adds URL assertions across 22 tracking tests, including deprecated assistant methods.

File	Description
src/​types/​tracker.d.ts	Declares the optional uiLibrary parameter.
src/​modules/​tracker.js	Adds query-parameter handling and documentation.
spec/​src/​modules/​tracker.js	Checks UI-library attribution in request URLs.

🧠 Review effort: Balanced

---

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

[joesurf]

Closing: the behavioural API rejects unknown fields, so a ui_library param returns 400 ("ui_library: Extra inputs are not permitted") and the event is dropped. Checked against the demo indexes. We'll tag events from the UI libraries through c instead.