Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,11 @@
### v3.37.0 (2026-11-13)
* * *
### New Features
* Added [response telemetry](https://apidocs.chargebee.com/docs/api/response-telemetry) support (Beta). Set `preferChargebeeTelemetry: true` alongside a `telemetryAdapter` to have the SDK send `Prefer: chargebee-telemetry=include` on each request. The SDK parses the `X-Chargebee-Telemetry` response header on both successful and failed responses and passes it to your adapter in the new optional `RequestTelemetryResult.responseTelemetryAttributes` field: the raw value under `http.response.header.x-chargebee-telemetry` and parsed values under `chargebee.telemetry.*`. The built-in `chargebee/telemetry/otel` adapter records them on the span automatically. A malformed header never fails the API call. Setting `preferChargebeeTelemetry` without a `telemetryAdapter` has no effect, and a `Prefer` header you set yourself is left unchanged.
* Exported `CHARGEBEE_TELEMETRY_PREFER_HEADER` and `CHARGEBEE_TELEMETRY_PREFER_VALUE` from the CJS and ESM entry points.
* No change for existing integrations: `RequestTelemetryResult.endAttributes` keeps the same keys and its `Record<string, string | number>` type. Response telemetry values (which can also be `boolean` or `string[]`) appear only in `responseTelemetryAttributes`, so existing custom adapters compile and behave as before.


### v3.36.0 (2026-11-12)
* * *
### New Resources:
Expand Down
11 changes: 11 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -626,6 +626,16 @@ The SDK builds standardized span attributes (`ctx.startAttributes`, `result.endA

Spans are named `chargebee.{resource}.{operation}` (e.g. `chargebee.subscription.create`).

#### Server-side timing telemetry (Beta)

> **Beta.** `X-Chargebee-Telemetry` response parsing and `preferChargebeeTelemetry` are in beta. Header availability, wire format, and SDK behavior may change.

Chargebee returns `X-Chargebee-Telemetry` only when the client opts in with `Prefer: chargebee-telemetry=include`. Set `preferChargebeeTelemetry: true` on the client to have the SDK add that header on each request when a `telemetryAdapter` is configured (parsed into `chargebee.telemetry.*` span attributes). You can also set the `Prefer` header yourself on individual requests.

The raw header and the parsed values are passed to your adapter in `result.responseTelemetryAttributes` (present only when the header was returned), separate from `result.endAttributes`, so existing adapters are unaffected. The built-in `chargebee/telemetry/otel` adapter records both; a custom adapter should forward `responseTelemetryAttributes` to its span as well.

For the header format and the meaning of each field, see [Response telemetry](https://apidocs.chargebee.com/docs/api/response-telemetry) in the API docs.

#### Quick start (built-in adapter)

```bash
Expand Down Expand Up @@ -657,6 +667,7 @@ const chargebee = new Chargebee({
site: '{{site}}',
apiKey: '{{api-key}}',
telemetryAdapter: otelDefaultAdapter,
preferChargebeeTelemetry: true,
});
```

Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
3.36.0
3.37.0
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "chargebee",
"version": "3.36.0",
"version": "3.37.0",
"description": "A library for integrating with Chargebee.",
"scripts": {
"prepack": "npm ci && npm run build",
Expand Down
13 changes: 12 additions & 1 deletion src/RequestWrapper.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,10 @@ import {
RetryConfig,
} from './types.js';
import {
applyResponseTelemetryPreferHeader,
buildRequestTelemetryContext,
buildRequestTelemetryResult,
extractResponseHeaders,
extractHttpStatusCode,
extractRequestTelemetryError,
resolveChargebeeApiVersion,
Expand Down Expand Up @@ -171,6 +173,14 @@ export class RequestWrapper {

Object.assign(this.httpHeaders, headers);

const telemetryAdapter = env.telemetryAdapter;
if (
telemetryAdapter !== undefined &&
env.preferChargebeeTelemetry === true
) {
applyResponseTelemetryPreferHeader(this.httpHeaders);
}

if (
this.apiCall.httpMethod === 'POST' &&
!this.httpHeaders['chargebee-idempotency-key'] &&
Expand All @@ -181,7 +191,6 @@ export class RequestWrapper {
this.httpHeaders['chargebee-idempotency-key'] = uuidv4();
}

const telemetryAdapter = env.telemetryAdapter;
const telemetryHeaders: RequestHeaders = {};
const requestStartTime = Date.now();

Expand Down Expand Up @@ -357,6 +366,7 @@ export class RequestWrapper {
buildRequestTelemetryResult({
httpStatusCode,
durationMs: Date.now() - requestStartTime,
responseHeaders: result?.headers,
}),
);
} catch (err) {
Expand All @@ -380,6 +390,7 @@ export class RequestWrapper {
httpStatusCode,
durationMs: Date.now() - requestStartTime,
error: telemetryError,
responseHeaders: extractResponseHeaders(err),
}),
);
} catch (telemetryErr) {
Expand Down
6 changes: 6 additions & 0 deletions src/chargebee.cjs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ import {
import { basicAuthValidator } from './resources/webhook/auth.js';
import { ChargebeeZodValidationError } from './chargebeeZodValidationError.js';
import {
CHARGEBEE_TELEMETRY_PREFER_HEADER,
CHARGEBEE_TELEMETRY_PREFER_VALUE,
TelemetryAttributeKeys,
SDK_TELEMETRY_HEADER_NAME,
} from './telemetry/index.js';
Expand All @@ -32,6 +34,10 @@ module.exports.WebhookAuthenticationError = WebhookAuthenticationError;
module.exports.WebhookPayloadValidationError = WebhookPayloadValidationError;
module.exports.WebhookPayloadParseError = WebhookPayloadParseError;
module.exports.TelemetryAttributeKeys = TelemetryAttributeKeys;
module.exports.CHARGEBEE_TELEMETRY_PREFER_HEADER =
CHARGEBEE_TELEMETRY_PREFER_HEADER;
module.exports.CHARGEBEE_TELEMETRY_PREFER_VALUE =
CHARGEBEE_TELEMETRY_PREFER_VALUE;
module.exports.SDK_TELEMETRY_HEADER_NAME = SDK_TELEMETRY_HEADER_NAME;

// Export validation error class
Expand Down
2 changes: 2 additions & 0 deletions src/chargebee.esm.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ export {
WebhookPayloadParseError,
} from './resources/webhook/handler.js';
export {
CHARGEBEE_TELEMETRY_PREFER_HEADER,
CHARGEBEE_TELEMETRY_PREFER_VALUE,
TelemetryAttributeKeys,
SDK_TELEMETRY_HEADER_NAME,
} from './telemetry/index.js';
Expand Down
2 changes: 1 addition & 1 deletion src/environment.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ export const Environment = {
hostSuffix: '.chargebee.com',
apiPath: '/api/v2',
timeout: DEFAULT_TIME_OUT,
clientVersion: 'v3.36.0',
clientVersion: 'v3.37.0',
port: DEFAULT_PORT,
timemachineWaitInMillis: DEFAULT_TIME_MACHINE_WAIT,
exportWaitInMillis: DEFAULT_EXPORT_WAIT,
Expand Down
134 changes: 130 additions & 4 deletions src/telemetry/TelemetryAdapter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,25 @@
* Copyright 2026 Chargebee Inc.
*/

import { parseChargebeeTelemetryHeaderToSpanAttributes } from './chargebeeTelemetryHeaderParser.js';
import {
BuildRequestTelemetryContextInput,
CHARGEBEE_SDK_NAME,
CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX,
CHARGEBEE_TELEMETRY_HEADER_PREFIX,
CHARGEBEE_TELEMETRY_PREFER_HEADER,
CHARGEBEE_TELEMETRY_PREFER_VALUE,
HTTP_REQUEST_HEADER_ATTRIBUTE_PREFIX,
HTTP_RESPONSE_HEADER_ATTRIBUTE_PREFIX,
RequestTelemetryContext,
ResponseTelemetryAttributeValue,
RequestTelemetryError,
RequestTelemetryHandle,
RequestTelemetryResult,
ResponseHeadersForTelemetry,
TELEMETRY_SPAN_NAME_PREFIX,
TelemetryAttributeKeys,
X_CHARGEBEE_TELEMETRY_HEADER,
} from './types.js';

export type RequestHeadersForTelemetry = Record<string, string | number>;
Expand Down Expand Up @@ -54,6 +61,23 @@ export function resolveChargebeeApiVersion(apiPath: string): 'v1' | 'v2' {
return apiPath === '/api/v1' ? 'v1' : 'v2';
}

/**
* Adds {@code Prefer: chargebee-telemetry=include} when not already set.
* Chargebee returns {@code X-Chargebee-Telemetry} only when this header is present.
*/
export function applyResponseTelemetryPreferHeader(
requestHeaders: Record<string, string | number>,
): void {
const preferHeader = CHARGEBEE_TELEMETRY_PREFER_HEADER.toLowerCase();
for (const name of Object.keys(requestHeaders)) {
if (name != null && name.toLowerCase() === preferHeader) {
return;
}
}
requestHeaders[CHARGEBEE_TELEMETRY_PREFER_HEADER] =
CHARGEBEE_TELEMETRY_PREFER_VALUE;
}

/**
* Captures Chargebee custom request headers as OTel span attributes.
*
Expand All @@ -72,7 +96,7 @@ export function buildRequestHeaderSpanAttributes(
}

for (const [name, value] of Object.entries(requestHeaders)) {
if (value === undefined || value === null) {
if (name == null || value === undefined || value === null) {
continue;
}
const lowerName = name.toLowerCase();
Expand All @@ -90,6 +114,54 @@ export function buildRequestHeaderSpanAttributes(
return attributes;
}

/** Case-insensitive response header lookup; skips entries whose name is null/undefined. */
export function getResponseHeaderValueIgnoreCase(
headers: Record<string, string | string[] | number | undefined> | undefined,
headerName: string,
): string | undefined {
if (!headers) {
return undefined;
}
const target = headerName.toLowerCase();
for (const [name, value] of Object.entries(headers)) {
if (name == null || value === undefined || value === null) {
continue;
}
if (name.toLowerCase() === target) {
return Array.isArray(value) ? value.join(', ') : String(value);
}
}
return undefined;
}

/**
* Captures the {@code X-Chargebee-Telemetry} response header as OpenTelemetry span attributes.
*/
export function buildResponseHeaderSpanAttributes(
responseHeaders: ResponseHeadersForTelemetry | undefined,
): Record<string, ResponseTelemetryAttributeValue> {
const attributes: Record<string, ResponseTelemetryAttributeValue> = {};
if (!responseHeaders) {
return attributes;
}

const value = getResponseHeaderValueIgnoreCase(
responseHeaders,
X_CHARGEBEE_TELEMETRY_HEADER,
);
if (value != null) {
attributes[
`${HTTP_RESPONSE_HEADER_ATTRIBUTE_PREFIX}${X_CHARGEBEE_TELEMETRY_HEADER}`
] = value;
Object.assign(
attributes,
parseChargebeeTelemetryHeaderToSpanAttributes(value),
);
}

return attributes;
}

export function buildRequestStartSpanAttributes(
input: BuildRequestTelemetryContextInput,
): Record<string, string | string[]> {
Expand All @@ -108,7 +180,10 @@ export function buildRequestStartSpanAttributes(
}

export function buildRequestEndSpanAttributes(
result: Omit<RequestTelemetryResult, 'endAttributes'>,
result: Omit<
RequestTelemetryResult,
'endAttributes' | 'responseTelemetryAttributes'
>,
): Record<string, string | number> {
const attributes: Record<string, string | number> = {
[TelemetryAttributeKeys.HTTP_RESPONSE_STATUS_CODE]: result.httpStatusCode,
Expand Down Expand Up @@ -154,12 +229,22 @@ export function buildRequestTelemetryContext(
}

export function buildRequestTelemetryResult(
result: Omit<RequestTelemetryResult, 'endAttributes'>,
result: Omit<
RequestTelemetryResult,
'endAttributes' | 'responseTelemetryAttributes'
>,
): RequestTelemetryResult {
return {
const telemetryResult: RequestTelemetryResult = {
...result,
endAttributes: buildRequestEndSpanAttributes(result),
};
const responseTelemetryAttributes = buildResponseHeaderSpanAttributes(
result.responseHeaders,
);
if (Object.keys(responseTelemetryAttributes).length > 0) {
telemetryResult.responseTelemetryAttributes = responseTelemetryAttributes;
}
return telemetryResult;
}

export function extractRequestTelemetryError(
Expand Down Expand Up @@ -213,3 +298,44 @@ export function extractHttpStatusCode(err: unknown): number | undefined {
}
return undefined;
}

export function extractResponseHeaders(
err: unknown,
): ResponseHeadersForTelemetry | undefined {
if (err == null || typeof err !== 'object') {
return undefined;
}

const errorObj = err as Record<string, unknown>;
const response = errorObj.response;
if (response != null && typeof response === 'object') {
const headers = normalizeResponseHeaders(
(response as Record<string, unknown>).headers,
);
if (headers) {
return headers;
}
}

return normalizeResponseHeaders(errorObj.headers);
}

/**
* Returns {@code headers} as a plain record. A native {@code Headers} instance (for example from
* an error thrown by a custom HTTP client) is converted, since its entries are not own properties.
*/
function normalizeResponseHeaders(
headers: unknown,
): ResponseHeadersForTelemetry | undefined {
if (headers == null || typeof headers !== 'object') {
return undefined;
}
if (typeof Headers !== 'undefined' && headers instanceof Headers) {
const record: ResponseHeadersForTelemetry = {};
headers.forEach((value, name) => {
record[name] = value;
});
return record;
}
return headers as ResponseHeadersForTelemetry;
}
Loading
Loading