add telemetry header

[cb-karthikp]

TBA

Adds anonymous SDK telemetry to the Chargebee Node SDK. The SDK sends telemetry headers by default, records request outcomes, supports feature flags, and limits header size. Users can disable telemetry with sdkTelemetryEnabled: false. Documentation, exports, types, and tests are included.

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues
✅	Secrets	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

The client now emits anonymous SDK telemetry by default. It records completed request data, builds bounded structured-field headers for later requests, supports disabling telemetry, preserves adapter behavior, and exposes related types and constants.

Changes

SDK telemetry

Layer / File(s)	Summary
Telemetry contracts and client configuration src/telemetry/sdkTelemetrySnapshot.ts, src/telemetry/sdkTelemetryState.ts, src/telemetry/sdkTelemetryHeader.ts, src/types.d.ts, types/index.d.ts, src/telemetry/index.ts, src/chargebee.cjs.ts, src/chargebee.esm.ts	Added telemetry state and snapshot contracts, feature constants, sdkTelemetryEnabled configuration, environment fields, and public exports.
Structured telemetry header construction src/telemetry/sdkTelemetryHeaderBuilder.ts, test/sdkTelemetryHeaderBuilder.test.ts	Builds structured-field headers with escaping, validation, conditional values, and a 4096-byte limit. Tests cover invalid characters, optional fields, required fields, and feature tokens.
Telemetry recording and feature metadata src/telemetry/sdkTelemetryEmitter.ts	Attaches the previous snapshot and records successful or failed calls with status, errors, request IDs, duration, and feature tokens. Telemetry errors are logged and suppressed.
Request lifecycle integration and validation src/createChargebee.ts, src/RequestWrapper.ts, test/requestWrapper.test.ts, README.md	Initializes and preserves telemetry state, adds headers to requests, records outcomes, documents the configuration option, and tests enabled, disabled, successful, failed, and feature-flagged requests.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CreateChargebee
  participant RequestWrapper
  participant HTTPClient
  participant SdkTelemetryState
  CreateChargebee->>SdkTelemetryState: initialize telemetry state
  RequestWrapper->>SdkTelemetryState: read previous completed snapshot
  RequestWrapper->>HTTPClient: send request with telemetry header
  HTTPClient-->>RequestWrapper: return response or error
  RequestWrapper->>SdkTelemetryState: record success or failure snapshot

Loading

🚥 Pre-merge checks | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 9.09% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/telemetry/sdkTelemetryHeaderBuilder.ts`:
- Around line 78-87: Update escapeSfString to detect CR, LF, or NUL characters
before constructing the structured-field value, and omit the invalid parameter
or entire telemetry header according to the existing builder flow. Ensure
invalid api_error_code values never reach Headers.append and valid values retain
the current escaping behavior.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Enterprise

Run ID: 0851d4ae-0b64-4c83-8917-b060651111f8

📥 Commits

Reviewing files that changed from the base of the PR and between 29fb518 and b7dcec2.

📒 Files selected for processing (12)

• README.md
• src/RequestWrapper.ts
• src/createChargebee.ts
• src/telemetry/index.ts
• src/telemetry/sdkTelemetryEmitter.ts
• src/telemetry/sdkTelemetryHeader.ts
• src/telemetry/sdkTelemetryHeaderBuilder.ts
• src/telemetry/sdkTelemetrySnapshot.ts
• src/telemetry/sdkTelemetryState.ts
• src/types.d.ts
• test/requestWrapper.test.ts
• types/index.d.ts

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/telemetry/sdkTelemetryHeaderBuilder.ts (1)

72-75: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Validate feature tokens before adding them to the header.

featureTokens bypass all Structured Field and invalid-character validation. A token containing CR, LF, or NUL reaches the outgoing header and can make Headers.append throw, which prevents the subsequent API request. Skip invalid feature tokens, or omit the telemetry header. Add a regression test for an invalid feature token.

As per path instructions, restrict feedback to functionality-breaking problems.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/telemetry/sdkTelemetryHeaderBuilder.ts` around lines 72 - 75, Validate
each featureToken in the snapshot feature-token loop using the existing
Structured Field and invalid-character validation before pushing it into items;
skip tokens that fail validation so they cannot reach Headers.append. Add a
regression test covering CR, LF, or NUL in a feature token and verify the API
request still proceeds.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@src/telemetry/sdkTelemetryHeaderBuilder.ts`:
- Around line 72-75: Validate each featureToken in the snapshot feature-token
loop using the existing Structured Field and invalid-character validation before
pushing it into items; skip tokens that fail validation so they cannot reach
Headers.append. Add a regression test covering CR, LF, or NUL in a feature token
and verify the API request still proceeds.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Enterprise

Run ID: 0acadf37-8768-4b01-8eb8-3f2cbb9dd1f3

📥 Commits

Reviewing files that changed from the base of the PR and between edbf46f and 8a92dea.

📒 Files selected for processing (2)

• src/telemetry/sdkTelemetryHeaderBuilder.ts
• test/sdkTelemetryHeaderBuilder.test.ts