MLE-30272: [Node Client] Document ML-Agent-ID Telemetry Header and Provide Opt-Out Option

[ngodugu-marklogic]

Summary

This PR documents the ML-Agent-ID telemetry header behavior and adds an opt-out connection option so security-sensitive deployments can suppress that header when needed.
Default behavior is preserved: if no opt-out is provided, requests still include ML-Agent-ID: nodejs.

What Changed

1. Added conditional telemetry header logic in requester.js:
   • ML-Agent-ID is now added only when disableTelemetryHeader is not true.
2. Added disableTelemetryHeader to allowed connection parameters in marklogic.js.
3. Documented the new connection option in createDatabaseClient JSDoc in marklogic.js.
4. Added TypeScript typing for disableTelemetryHeader in marklogic.d.ts.
5. Added README documentation for:
   • default telemetry header behavior,
   • what it discloses,
   • and how to opt out with disableTelemetryHeader in README.md.
6. Added tests for both behaviors:
   • JS unit test: header present by default and omitted when disabled in telemetry-header-test.js
   • TS runtime smoke test with the same assertions in telemetry-header-runtime.test.ts
   • TS compile-time coverage for new config option in basic-types.test.ts:58

Why This Approach

1. Minimal surface-area change:
   • only gates a single header write,
   • no auth flow or request path behavior changes beyond the telemetry header.
2. Backward compatibility:
   • existing clients remain unchanged unless disableTelemetryHeader is explicitly set.
3. Clear security posture:
   • keeps telemetry by default for ecosystem consistency,
   • allows explicit opt-out for hardened environments.
4. Aligns with acceptance criteria:
   • implementation, docs, typings, and tests are all covered.

Validation

1. Use Node 22 or higher.
2. Install dependencies: npm install
3. Run focused JavaScript test for header behavior: npx mocha telemetry-header-test.js
4. Compile TypeScript runtime tests: npm run test:compile
5. Run TypeScript runtime tests: npm run test:typescript

Expected Results

1. test-basic telemetry test passes both cases:
   • Includes ML-Agent-ID by default
   • Omits ML-Agent-ID when disableTelemetryHeader is true
2. TypeScript compile completes with no errors.
3. TypeScript runtime suite executes successfully in Node 22+.

[Copilot]

Pull request overview

This PR adds an opt-out for the ML-Agent-ID: nodejs telemetry header and documents the default behavior across the JS API docs, README, and TypeScript typings, while preserving the existing default (header is sent unless explicitly disabled).

Changes:

• Gated setting the ML-Agent-ID header behind a new disableTelemetryHeader connection option.
• Added disableTelemetryHeader to the allowed connection parameters and TypeScript DatabaseClientConfig typing.
• Documented the behavior and added JS + TS runtime/compile-time tests covering both default and opt-out behavior.

Reviewed changes

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

Show a summary per file

File	Description
lib/requester.js	Conditionally adds ML-Agent-ID only when disableTelemetryHeader is not enabled.
lib/marklogic.js	Allows disableTelemetryHeader in connection parameters and documents it in createDatabaseClient JSDoc.
marklogic.d.ts	Adds disableTelemetryHeader?: boolean to DatabaseClientConfig.
README.md	Documents default telemetry header behavior and how to opt out.
test-basic/telemetry-header-test.js	JS unit test verifying header present by default and omitted when disabled.
test-typescript/telemetry-header-runtime.test.ts	TS runtime smoke test verifying the same header behavior at runtime.
test-typescript/basic-types.test.ts	TS compile-time coverage ensuring the new config option type-checks.

---

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

[rjrudin]

Couple thoughts here. First, I don't think we want to establish a pattern of every new feature being documented in the README file. That file should typically be brief, providing an overview of the client and links to the documentation and other resources. This establishes a pattern that will produce an enormous README file over time. The right place for this information is in the existing Node Client docs.

Second - I would provide a link to the MarkLogic telemetry docs in the type definition above - https://docs.progress.com/bundle/marklogic-server-monitor-12/page/topics/telemetry.html . And possibly in the config example above as well. I think saying that it enables or disables telemetry usage with a link to the telemetry docs is all we want.

[rjrudin]

I would make this and the next comment briefer by removing the name of the field, since it's obvious what it's referring too - e.g. Optional; set to true to suppress inclusion of the ML-Agent-ID header in each request to MarkLogic..