chargebee 3.31.0 → 3.32.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+### v3.32.0 (2026-09-08)
+* * *
+### New Features
+* Added anonymous SDK telemetry. On the first API call of a client instance, the SDK may attach an `x-chargebee-sdk-telemetry` header listing enabled feature codes (`telemetryAdapter`, custom HTTP client, retry config). Later calls on the same client do not send the header again. A default client with no optional features sends no telemetry header.
+* Disable SDK telemetry with `sdkTelemetryEnabled: false`.
+* Exported `SDK_TELEMETRY_HEADER_NAME` from the CJS and ESM entry points.
+
+
 ### v3.31.0 (2026-08-19)
 * * *
 ### New Resources:

package/README.md

@@ -602,6 +602,20 @@ const chargebee = new Chargebee({
 
 These examples demonstrate how to implement and inject custom clients using `axios` and `ky`, respectively.
 
+### SDK telemetry
+
+By default, the library sends anonymous usage telemetry to Chargebee. This helps us improve the SDK and API.
+
+You can disable this behavior if you prefer:
+
+```javascript
+const chargebee = new Chargebee({
+  site: 'your-site',
+  apiKey: 'your-api-key',
+  sdkTelemetryEnabled: false,
+});
+```
+
 ### Telemetry (OpenTelemetry)
 
 Optional. Pass a `telemetryAdapter` when you want Chargebee API calls traced in your observability stack (Datadog, Splunk, Honeycomb, Jaeger, etc.). The SDK ships a ready-to-use OpenTelemetry adapter, so for most setups you only need to add `@opentelemetry/api` and wire the adapter on the client.

package/cjs/RequestWrapper.js

@@ -68,6 +68,15 @@ class RequestWrapper {
         if (this.envArg.telemetryAdapter !== undefined) {
             _env.telemetryAdapter = this.envArg.telemetryAdapter;
         }
+        if (this.envArg.sdkTelemetryState !== undefined) {
+            _env.sdkTelemetryState = this.envArg.sdkTelemetryState;
+        }
+        if (this.envArg.sdkTelemetryEnabled !== undefined) {
+            _env.sdkTelemetryEnabled = this.envArg.sdkTelemetryEnabled;
+        }
+        if (this.envArg.httpClientIsCustom !== undefined) {
+            _env.httpClientIsCustom = this.envArg.httpClientIsCustom;
+        }
         const env = _env;
         const retryConfig = Object.assign({ enabled: false, maxRetries: 3, delayMs: 200, retryOn: [500, 502, 503, 504] }, env.retryConfig);
         const urlIdParam = this.apiCall.hasIdInUrl ? this.args[0] : null;
@@ -142,6 +151,7 @@ class RequestWrapper {
                     : (0, util_js_1.encodeParams)(requestParams, undefined, undefined, undefined, jsonKeys);
             }
             const requestHeaders = Object.assign(Object.assign({}, this.httpHeaders), telemetryHeaders);
+            (0, index_js_1.attachSdkTelemetryHeader)(env, requestHeaders);
             const contentType = this.apiCall.isJsonRequest
                 ? 'application/json;charset=UTF-8'
                 : 'application/x-www-form-urlencoded; charset=utf-8';
@@ -264,9 +274,10 @@ class RequestWrapper {
                 throw err;
             }
         };
-        const promise = telemetryAdapter !== undefined
+        const executeCall = () => telemetryAdapter !== undefined
             ? runWithTelemetry(telemetryAdapter)
             : withRetry(0, requestStartTime);
+        const promise = executeCall();
         return (0, util_js_1.callbackifyPromise)(promise);
     }
     _createHeaders(httpHeaders) {

package/cjs/chargebee.cjs.js

@@ -21,5 +21,6 @@ module.exports.WebhookAuthenticationError = handler_js_1.WebhookAuthenticationEr
 module.exports.WebhookPayloadValidationError = handler_js_1.WebhookPayloadValidationError;
 module.exports.WebhookPayloadParseError = handler_js_1.WebhookPayloadParseError;
 module.exports.TelemetryAttributeKeys = index_js_1.TelemetryAttributeKeys;
+module.exports.SDK_TELEMETRY_HEADER_NAME = index_js_1.SDK_TELEMETRY_HEADER_NAME;
 // Export validation error class
 module.exports.ChargebeeZodValidationError = chargebeeZodValidationError_js_1.ChargebeeZodValidationError;

package/cjs/createChargebee.js

@@ -18,14 +18,18 @@ const api_endpoints_js_1 = require("./resources/api_endpoints.js");
 const util_js_1 = require("./util.js");
 const asyncApiSupport_js_1 = require("./asyncApiSupport.js");
 const handler_js_1 = require("./resources/webhook/handler.js");
+const index_js_1 = require("./telemetry/index.js");
 const CreateChargebee = (httpClient) => {
     const Chargebee = function (conf) {
         this._env = Object.assign({}, environment_js_1.Environment);
-        const { telemetryAdapter, httpClient: configHttpClient } = conf, confToMerge = __rest(conf, ["telemetryAdapter", "httpClient"]);
+        const { telemetryAdapter, httpClient: configHttpClient, sdkTelemetryEnabled } = conf, confToMerge = __rest(conf, ["telemetryAdapter", "httpClient", "sdkTelemetryEnabled"]);
         (0, util_js_1.extend)(true, this._env, confToMerge);
         // @ts-ignore
         this._env.httpClient =
             configHttpClient != null ? configHttpClient : httpClient;
+        this._env.sdkTelemetryState = new index_js_1.SdkTelemetryState();
+        this._env.sdkTelemetryEnabled = sdkTelemetryEnabled !== false;
+        this._env.httpClientIsCustom = configHttpClient != null;
         if (telemetryAdapter !== undefined) {
             this._env.telemetryAdapter = telemetryAdapter;
         }

package/cjs/environment.js

@@ -11,7 +11,7 @@ exports.Environment = {
     hostSuffix: '.chargebee.com',
     apiPath: '/api/v2',
     timeout: DEFAULT_TIME_OUT,
-    clientVersion: 'v3.31.0',
+    clientVersion: 'v3.32.0',
     port: DEFAULT_PORT,
     timemachineWaitInMillis: DEFAULT_TIME_MACHINE_WAIT,
     exportWaitInMillis: DEFAULT_EXPORT_WAIT,

package/cjs/telemetry/index.js

@@ -6,7 +6,7 @@
  * Copyright 2026 Chargebee Inc.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveChargebeeApiVersion = exports.extractRequestTelemetryError = exports.extractHttpStatusCode = exports.buildSpanName = exports.buildRequestTelemetryResult = exports.buildRequestTelemetryContext = exports.buildRequestStartSpanAttributes = exports.buildRequestHeaderSpanAttributes = exports.buildRequestEndSpanAttributes = exports.NoOpTelemetryAdapter = exports.NO_OP_TELEMETRY_ADAPTER = exports.TelemetryAttributeKeys = exports.TELEMETRY_SPAN_NAME_PREFIX = exports.HTTP_REQUEST_HEADER_ATTRIBUTE_PREFIX = exports.CHARGEBEE_TELEMETRY_HEADER_PREFIX = exports.CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX = exports.CHARGEBEE_SDK_NAME = void 0;
+exports.attachSdkTelemetryHeader = exports.buildSdkTelemetryHeader = exports.SdkTelemetryState = exports.SdkTelemetryFeature = exports.SDK_TELEMETRY_MAX_HEADER_BYTES = exports.SDK_TELEMETRY_HEADER_NAME = exports.SDK_TELEMETRY_FEATURES_KEY = exports.resolveChargebeeApiVersion = exports.extractRequestTelemetryError = exports.extractHttpStatusCode = exports.buildSpanName = exports.buildRequestTelemetryResult = exports.buildRequestTelemetryContext = exports.buildRequestStartSpanAttributes = exports.buildRequestHeaderSpanAttributes = exports.buildRequestEndSpanAttributes = exports.NoOpTelemetryAdapter = exports.NO_OP_TELEMETRY_ADAPTER = exports.TelemetryAttributeKeys = exports.TELEMETRY_SPAN_NAME_PREFIX = exports.HTTP_REQUEST_HEADER_ATTRIBUTE_PREFIX = exports.CHARGEBEE_TELEMETRY_HEADER_PREFIX = exports.CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX = exports.CHARGEBEE_SDK_NAME = void 0;
 var types_js_1 = require("./types.js");
 Object.defineProperty(exports, "CHARGEBEE_SDK_NAME", { enumerable: true, get: function () { return types_js_1.CHARGEBEE_SDK_NAME; } });
 Object.defineProperty(exports, "CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX", { enumerable: true, get: function () { return types_js_1.CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX; } });
@@ -26,3 +26,15 @@ Object.defineProperty(exports, "buildSpanName", { enumerable: true, get: functio
 Object.defineProperty(exports, "extractHttpStatusCode", { enumerable: true, get: function () { return TelemetryAdapter_js_1.extractHttpStatusCode; } });
 Object.defineProperty(exports, "extractRequestTelemetryError", { enumerable: true, get: function () { return TelemetryAdapter_js_1.extractRequestTelemetryError; } });
 Object.defineProperty(exports, "resolveChargebeeApiVersion", { enumerable: true, get: function () { return TelemetryAdapter_js_1.resolveChargebeeApiVersion; } });
+var sdkTelemetryHeader_js_1 = require("./sdkTelemetryHeader.js");
+Object.defineProperty(exports, "SDK_TELEMETRY_FEATURES_KEY", { enumerable: true, get: function () { return sdkTelemetryHeader_js_1.SDK_TELEMETRY_FEATURES_KEY; } });
+Object.defineProperty(exports, "SDK_TELEMETRY_HEADER_NAME", { enumerable: true, get: function () { return sdkTelemetryHeader_js_1.SDK_TELEMETRY_HEADER_NAME; } });
+Object.defineProperty(exports, "SDK_TELEMETRY_MAX_HEADER_BYTES", { enumerable: true, get: function () { return sdkTelemetryHeader_js_1.SDK_TELEMETRY_MAX_HEADER_BYTES; } });
+var sdkTelemetryFeature_js_1 = require("./sdkTelemetryFeature.js");
+Object.defineProperty(exports, "SdkTelemetryFeature", { enumerable: true, get: function () { return sdkTelemetryFeature_js_1.SdkTelemetryFeature; } });
+var sdkTelemetryState_js_1 = require("./sdkTelemetryState.js");
+Object.defineProperty(exports, "SdkTelemetryState", { enumerable: true, get: function () { return sdkTelemetryState_js_1.SdkTelemetryState; } });
+var sdkTelemetryHeaderBuilder_js_1 = require("./sdkTelemetryHeaderBuilder.js");
+Object.defineProperty(exports, "buildSdkTelemetryHeader", { enumerable: true, get: function () { return sdkTelemetryHeaderBuilder_js_1.buildSdkTelemetryHeader; } });
+var sdkTelemetryEmitter_js_1 = require("./sdkTelemetryEmitter.js");
+Object.defineProperty(exports, "attachSdkTelemetryHeader", { enumerable: true, get: function () { return sdkTelemetryEmitter_js_1.attachSdkTelemetryHeader; } });

package/cjs/telemetry/sdkTelemetryEmitter.js

@@ -0,0 +1,64 @@
+"use strict";
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachSdkTelemetryHeader = attachSdkTelemetryHeader;
+const sdkTelemetryHeaderBuilder_js_1 = require("./sdkTelemetryHeaderBuilder.js");
+const sdkTelemetryFeature_js_1 = require("./sdkTelemetryFeature.js");
+const sdkTelemetryHeader_js_1 = require("./sdkTelemetryHeader.js");
+/**
+ * Emits the anonymous SDK telemetry request header, independently of any customer telemetry
+ * adapter.
+ *
+ * On the first API call of a client instance, attaches {@code f;…} with enabled feature codes when
+ * any are present; omits the header when none are enabled. Later calls on the same client never
+ * attach again. SDK identity is correlated via User-Agent. Every failure path is swallowed and
+ * logged at WARNING: telemetry must never fail an API call.
+ */
+function attachSdkTelemetryHeader(env, headers) {
+    var _a;
+    if (env.sdkTelemetryEnabled === false) {
+        return;
+    }
+    try {
+        if (!((_a = env.sdkTelemetryState) === null || _a === void 0 ? void 0 : _a.tryMarkEmitted())) {
+            return;
+        }
+        const headerValue = (0, sdkTelemetryHeaderBuilder_js_1.buildSdkTelemetryHeader)(resolveFeatures(env));
+        if (!headerValue) {
+            return;
+        }
+        headers[sdkTelemetryHeader_js_1.SDK_TELEMETRY_HEADER_NAME] = headerValue;
+    }
+    catch (err) {
+        logSuppressed('attach header', err);
+    }
+}
+/** Collects enabled feature codes for the current client configuration. */
+function resolveFeatures(env) {
+    const features = [];
+    if (env.telemetryAdapter !== undefined) {
+        features.push(sdkTelemetryFeature_js_1.SdkTelemetryFeature.TELEMETRY_ADAPTER);
+    }
+    if (env.httpClientIsCustom) {
+        features.push(sdkTelemetryFeature_js_1.SdkTelemetryFeature.CUSTOM_TRANSPORT);
+    }
+    if (isRetryConfigActive(env)) {
+        features.push(sdkTelemetryFeature_js_1.SdkTelemetryFeature.RETRY_CONFIG);
+    }
+    return features;
+}
+/** Whether retries are enabled on the client. */
+function isRetryConfigActive(env) {
+    var _a;
+    return ((_a = env.retryConfig) === null || _a === void 0 ? void 0 : _a.enabled) === true;
+}
+/** Logs a suppressed telemetry failure without affecting the API call. */
+function logSuppressed(step, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`SDK telemetry could not ${step} (${message}); API call unaffected.`, err);
+}

package/cjs/telemetry/sdkTelemetryFeature.js

@@ -0,0 +1,22 @@
+"use strict";
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SdkTelemetryFeature = void 0;
+/**
+ * SDK configuration features reported under the {@code f} segment of
+ * {@link SDK_TELEMETRY_HEADER_NAME}. Wire codes are maintained in sdk-generator.
+ */
+var SdkTelemetryFeature;
+(function (SdkTelemetryFeature) {
+    /** Customer TelemetryAdapter configured. */
+    SdkTelemetryFeature["TELEMETRY_ADAPTER"] = "ta";
+    /** Custom HTTP client configured. */
+    SdkTelemetryFeature["CUSTOM_TRANSPORT"] = "ct";
+    /** Retries enabled on the client. */
+    SdkTelemetryFeature["RETRY_CONFIG"] = "rc";
+})(SdkTelemetryFeature || (exports.SdkTelemetryFeature = SdkTelemetryFeature = {}));

package/cjs/telemetry/sdkTelemetryHeader.js

@@ -0,0 +1,15 @@
+"use strict";
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_TELEMETRY_FEATURES_KEY = exports.SDK_TELEMETRY_MAX_HEADER_BYTES = exports.SDK_TELEMETRY_HEADER_NAME = void 0;
+/** Constants for the anonymous SDK telemetry request header. */
+exports.SDK_TELEMETRY_HEADER_NAME = 'x-chargebee-sdk-telemetry';
+/** Defensive size cap; feature-only values are tiny. */
+exports.SDK_TELEMETRY_MAX_HEADER_BYTES = 4096;
+/** RFC 9651 sf-list item name for the features segment. */
+exports.SDK_TELEMETRY_FEATURES_KEY = 'f';

package/cjs/telemetry/sdkTelemetryHeaderBuilder.js

@@ -0,0 +1,34 @@
+"use strict";
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSdkTelemetryHeader = buildSdkTelemetryHeader;
+const sdkTelemetryHeader_js_1 = require("./sdkTelemetryHeader.js");
+/**
+ * Builds RFC 9651 values for {@link SDK_TELEMETRY_HEADER_NAME}: a features segment keyed by
+ * {@link SDK_TELEMETRY_FEATURES_KEY} with enabled feature codes as boolean params
+ * (for example {@code f;ta;rc}). Correlate SDK identity via User-Agent.
+ */
+function buildSdkTelemetryHeader(features) {
+    if (!features || features.length === 0) {
+        return undefined;
+    }
+    let value = sdkTelemetryHeader_js_1.SDK_TELEMETRY_FEATURES_KEY;
+    for (const feature of features) {
+        if (feature == null) {
+            continue;
+        }
+        value += `;${feature}`;
+    }
+    if (value.length === sdkTelemetryHeader_js_1.SDK_TELEMETRY_FEATURES_KEY.length) {
+        return undefined;
+    }
+    if (new TextEncoder().encode(value).length > sdkTelemetryHeader_js_1.SDK_TELEMETRY_MAX_HEADER_BYTES) {
+        return undefined;
+    }
+    return value;
+}

package/cjs/telemetry/sdkTelemetryState.js

@@ -0,0 +1,36 @@
+"use strict";
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SdkTelemetryState = void 0;
+/**
+ * Per-client gate so the SDK telemetry header is considered at most once per client instance.
+ */
+class SdkTelemetryState {
+    constructor() {
+        this.emitted = false;
+    }
+    /**
+     * Claims the single emission slot for this client. Returns true only for the first caller.
+     */
+    tryMarkEmitted() {
+        if (this.emitted) {
+            return false;
+        }
+        this.emitted = true;
+        return true;
+    }
+    /** Whether this client has already considered emitting the telemetry header. */
+    hasEmitted() {
+        return this.emitted;
+    }
+    /** Clears the emission gate (tests only). */
+    clear() {
+        this.emitted = false;
+    }
+}
+exports.SdkTelemetryState = SdkTelemetryState;

package/esm/RequestWrapper.js

@@ -1,5 +1,5 @@
 import { extend, callbackifyPromise, getApiURL, encodeListParams, encodeParams, serialize, getHost, log, generateUUIDv4 as uuidv4, } from './util.js';
-import { buildRequestTelemetryContext, buildRequestTelemetryResult, extractHttpStatusCode, extractRequestTelemetryError, resolveChargebeeApiVersion, } from './telemetry/index.js';
+import { buildRequestTelemetryContext, buildRequestTelemetryResult, extractHttpStatusCode, extractRequestTelemetryError, resolveChargebeeApiVersion, attachSdkTelemetryHeader, } from './telemetry/index.js';
 import { handleResponse } from './coreCommon.js';
 import { Buffer } from 'node:buffer';
 import { ChargebeeZodValidationError } from './chargebeeZodValidationError.js';
@@ -65,6 +65,15 @@ export class RequestWrapper {
         if (this.envArg.telemetryAdapter !== undefined) {
             _env.telemetryAdapter = this.envArg.telemetryAdapter;
         }
+        if (this.envArg.sdkTelemetryState !== undefined) {
+            _env.sdkTelemetryState = this.envArg.sdkTelemetryState;
+        }
+        if (this.envArg.sdkTelemetryEnabled !== undefined) {
+            _env.sdkTelemetryEnabled = this.envArg.sdkTelemetryEnabled;
+        }
+        if (this.envArg.httpClientIsCustom !== undefined) {
+            _env.httpClientIsCustom = this.envArg.httpClientIsCustom;
+        }
         const env = _env;
         const retryConfig = Object.assign({ enabled: false, maxRetries: 3, delayMs: 200, retryOn: [500, 502, 503, 504] }, env.retryConfig);
         const urlIdParam = this.apiCall.hasIdInUrl ? this.args[0] : null;
@@ -139,6 +148,7 @@ export class RequestWrapper {
                     : encodeParams(requestParams, undefined, undefined, undefined, jsonKeys);
             }
             const requestHeaders = Object.assign(Object.assign({}, this.httpHeaders), telemetryHeaders);
+            attachSdkTelemetryHeader(env, requestHeaders);
             const contentType = this.apiCall.isJsonRequest
                 ? 'application/json;charset=UTF-8'
                 : 'application/x-www-form-urlencoded; charset=utf-8';
@@ -261,9 +271,10 @@ export class RequestWrapper {
                 throw err;
             }
         };
-        const promise = telemetryAdapter !== undefined
+        const executeCall = () => telemetryAdapter !== undefined
             ? runWithTelemetry(telemetryAdapter)
             : withRetry(0, requestStartTime);
+        const promise = executeCall();
         return callbackifyPromise(promise);
     }
     _createHeaders(httpHeaders) {

package/esm/chargebee.esm.js

@@ -7,6 +7,6 @@ export default Chargebee;
 export { WebhookEventType, WebhookContentType, } from './resources/webhook/handler.js';
 export { basicAuthValidator } from './resources/webhook/auth.js';
 export { WebhookError, WebhookAuthenticationError, WebhookPayloadValidationError, WebhookPayloadParseError, } from './resources/webhook/handler.js';
-export { TelemetryAttributeKeys } from './telemetry/index.js';
+export { TelemetryAttributeKeys, SDK_TELEMETRY_HEADER_NAME, } from './telemetry/index.js';
 // Export validation error class
 export { ChargebeeZodValidationError } from './chargebeeZodValidationError.js';

package/esm/createChargebee.js

@@ -15,14 +15,18 @@ import { Endpoints } from './resources/api_endpoints.js';
 import { extend, sleep } from './util.js';
 import { waitForProcessToComplete } from './asyncApiSupport.js';
 import { WebhookHandler, createDefaultHandler, } from './resources/webhook/handler.js';
+import { SdkTelemetryState } from './telemetry/index.js';
 export const CreateChargebee = (httpClient) => {
     const Chargebee = function (conf) {
         this._env = Object.assign({}, Environment);
-        const { telemetryAdapter, httpClient: configHttpClient } = conf, confToMerge = __rest(conf, ["telemetryAdapter", "httpClient"]);
+        const { telemetryAdapter, httpClient: configHttpClient, sdkTelemetryEnabled } = conf, confToMerge = __rest(conf, ["telemetryAdapter", "httpClient", "sdkTelemetryEnabled"]);
         extend(true, this._env, confToMerge);
         // @ts-ignore
         this._env.httpClient =
             configHttpClient != null ? configHttpClient : httpClient;
+        this._env.sdkTelemetryState = new SdkTelemetryState();
+        this._env.sdkTelemetryEnabled = sdkTelemetryEnabled !== false;
+        this._env.httpClientIsCustom = configHttpClient != null;
         if (telemetryAdapter !== undefined) {
             this._env.telemetryAdapter = telemetryAdapter;
         }

package/esm/environment.js

@@ -8,7 +8,7 @@ export const Environment = {
     hostSuffix: '.chargebee.com',
     apiPath: '/api/v2',
     timeout: DEFAULT_TIME_OUT,
-    clientVersion: 'v3.31.0',
+    clientVersion: 'v3.32.0',
     port: DEFAULT_PORT,
     timemachineWaitInMillis: DEFAULT_TIME_MACHINE_WAIT,
     exportWaitInMillis: DEFAULT_EXPORT_WAIT,

package/esm/telemetry/index.js

@@ -6,3 +6,8 @@
  */
 export { CHARGEBEE_SDK_NAME, CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX, CHARGEBEE_TELEMETRY_HEADER_PREFIX, HTTP_REQUEST_HEADER_ATTRIBUTE_PREFIX, TELEMETRY_SPAN_NAME_PREFIX, TelemetryAttributeKeys, } from './types.js';
 export { NO_OP_TELEMETRY_ADAPTER, NoOpTelemetryAdapter, buildRequestEndSpanAttributes, buildRequestHeaderSpanAttributes, buildRequestStartSpanAttributes, buildRequestTelemetryContext, buildRequestTelemetryResult, buildSpanName, extractHttpStatusCode, extractRequestTelemetryError, resolveChargebeeApiVersion, } from './TelemetryAdapter.js';
+export { SDK_TELEMETRY_FEATURES_KEY, SDK_TELEMETRY_HEADER_NAME, SDK_TELEMETRY_MAX_HEADER_BYTES, } from './sdkTelemetryHeader.js';
+export { SdkTelemetryFeature } from './sdkTelemetryFeature.js';
+export { SdkTelemetryState } from './sdkTelemetryState.js';
+export { buildSdkTelemetryHeader } from './sdkTelemetryHeaderBuilder.js';
+export { attachSdkTelemetryHeader, } from './sdkTelemetryEmitter.js';

package/esm/telemetry/sdkTelemetryEmitter.js

@@ -0,0 +1,61 @@
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+import { buildSdkTelemetryHeader } from './sdkTelemetryHeaderBuilder.js';
+import { SdkTelemetryFeature } from './sdkTelemetryFeature.js';
+import { SDK_TELEMETRY_HEADER_NAME } from './sdkTelemetryHeader.js';
+/**
+ * Emits the anonymous SDK telemetry request header, independently of any customer telemetry
+ * adapter.
+ *
+ * On the first API call of a client instance, attaches {@code f;…} with enabled feature codes when
+ * any are present; omits the header when none are enabled. Later calls on the same client never
+ * attach again. SDK identity is correlated via User-Agent. Every failure path is swallowed and
+ * logged at WARNING: telemetry must never fail an API call.
+ */
+export function attachSdkTelemetryHeader(env, headers) {
+    var _a;
+    if (env.sdkTelemetryEnabled === false) {
+        return;
+    }
+    try {
+        if (!((_a = env.sdkTelemetryState) === null || _a === void 0 ? void 0 : _a.tryMarkEmitted())) {
+            return;
+        }
+        const headerValue = buildSdkTelemetryHeader(resolveFeatures(env));
+        if (!headerValue) {
+            return;
+        }
+        headers[SDK_TELEMETRY_HEADER_NAME] = headerValue;
+    }
+    catch (err) {
+        logSuppressed('attach header', err);
+    }
+}
+/** Collects enabled feature codes for the current client configuration. */
+function resolveFeatures(env) {
+    const features = [];
+    if (env.telemetryAdapter !== undefined) {
+        features.push(SdkTelemetryFeature.TELEMETRY_ADAPTER);
+    }
+    if (env.httpClientIsCustom) {
+        features.push(SdkTelemetryFeature.CUSTOM_TRANSPORT);
+    }
+    if (isRetryConfigActive(env)) {
+        features.push(SdkTelemetryFeature.RETRY_CONFIG);
+    }
+    return features;
+}
+/** Whether retries are enabled on the client. */
+function isRetryConfigActive(env) {
+    var _a;
+    return ((_a = env.retryConfig) === null || _a === void 0 ? void 0 : _a.enabled) === true;
+}
+/** Logs a suppressed telemetry failure without affecting the API call. */
+function logSuppressed(step, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`SDK telemetry could not ${step} (${message}); API call unaffected.`, err);
+}

package/esm/telemetry/sdkTelemetryFeature.js

@@ -0,0 +1,19 @@
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+/**
+ * SDK configuration features reported under the {@code f} segment of
+ * {@link SDK_TELEMETRY_HEADER_NAME}. Wire codes are maintained in sdk-generator.
+ */
+export var SdkTelemetryFeature;
+(function (SdkTelemetryFeature) {
+    /** Customer TelemetryAdapter configured. */
+    SdkTelemetryFeature["TELEMETRY_ADAPTER"] = "ta";
+    /** Custom HTTP client configured. */
+    SdkTelemetryFeature["CUSTOM_TRANSPORT"] = "ct";
+    /** Retries enabled on the client. */
+    SdkTelemetryFeature["RETRY_CONFIG"] = "rc";
+})(SdkTelemetryFeature || (SdkTelemetryFeature = {}));

package/esm/telemetry/sdkTelemetryHeader.js

@@ -0,0 +1,12 @@
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+/** Constants for the anonymous SDK telemetry request header. */
+export const SDK_TELEMETRY_HEADER_NAME = 'x-chargebee-sdk-telemetry';
+/** Defensive size cap; feature-only values are tiny. */
+export const SDK_TELEMETRY_MAX_HEADER_BYTES = 4096;
+/** RFC 9651 sf-list item name for the features segment. */
+export const SDK_TELEMETRY_FEATURES_KEY = 'f';

package/esm/telemetry/sdkTelemetryHeaderBuilder.js

@@ -0,0 +1,31 @@
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+import { SDK_TELEMETRY_FEATURES_KEY, SDK_TELEMETRY_MAX_HEADER_BYTES, } from './sdkTelemetryHeader.js';
+/**
+ * Builds RFC 9651 values for {@link SDK_TELEMETRY_HEADER_NAME}: a features segment keyed by
+ * {@link SDK_TELEMETRY_FEATURES_KEY} with enabled feature codes as boolean params
+ * (for example {@code f;ta;rc}). Correlate SDK identity via User-Agent.
+ */
+export function buildSdkTelemetryHeader(features) {
+    if (!features || features.length === 0) {
+        return undefined;
+    }
+    let value = SDK_TELEMETRY_FEATURES_KEY;
+    for (const feature of features) {
+        if (feature == null) {
+            continue;
+        }
+        value += `;${feature}`;
+    }
+    if (value.length === SDK_TELEMETRY_FEATURES_KEY.length) {
+        return undefined;
+    }
+    if (new TextEncoder().encode(value).length > SDK_TELEMETRY_MAX_HEADER_BYTES) {
+        return undefined;
+    }
+    return value;
+}

package/esm/telemetry/sdkTelemetryState.js

@@ -0,0 +1,32 @@
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+/**
+ * Per-client gate so the SDK telemetry header is considered at most once per client instance.
+ */
+export class SdkTelemetryState {
+    constructor() {
+        this.emitted = false;
+    }
+    /**
+     * Claims the single emission slot for this client. Returns true only for the first caller.
+     */
+    tryMarkEmitted() {
+        if (this.emitted) {
+            return false;
+        }
+        this.emitted = true;
+        return true;
+    }
+    /** Whether this client has already considered emitting the telemetry header. */
+    hasEmitted() {
+        return this.emitted;
+    }
+    /** Clears the emission gate (tests only). */
+    clear() {
+        this.emitted = false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chargebee",
-  "version": "3.31.0",
+  "version": "3.32.0",
   "description": "A library for integrating with Chargebee.",
   "scripts": {
     "prepack": "npm ci && npm run build",
@@ -8,7 +8,8 @@
     "build": "npm run build-esm && npm run build-cjs",
     "build-esm": "rm -rf esm && mkdir -p esm && tsc -p tsconfig.esm.json && echo '{\"type\":\"module\"}' > esm/package.json",
     "build-cjs": "rm -rf cjs && mkdir -p cjs && tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > cjs/package.json",
-    "prettier": "prettier --write \"src/**/*.ts\" \"types/**/*.d.ts\""
+    "format": "biome format --write",
+    "format:check": "biome format"
   },
   "types": "./types/index.d.ts",
   "keywords": [
@@ -76,22 +77,17 @@
     }
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.5.7",
     "@opentelemetry/api": "^1.9.0",
     "@types/chai": "^4.3.5",
     "@types/mocha": "^10.0.10",
     "@types/node": "20.12.0",
     "chai": "^4.3.7",
     "mocha": "^10.2.0",
-    "prettier": "^3.3.3",
     "ts-node": "^10.9.1",
     "typescript": "^5.5.4",
     "undici-types": "^7.16.0"
   },
-  "prettier": {
-    "semi": true,
-    "singleQuote": true,
-    "parser": "typescript"
-  },
   "dependencies": {
     "zod": "^4.3.6"
   }

package/types/index.d.ts

@@ -189,14 +189,17 @@ declare module 'chargebee' {
      * @telemetryAdapter optional telemetry adapter for observability (e.g. OpenTelemetry)
      */
     telemetryAdapter?: TelemetryAdapter;
+
+    /**
+     * @sdkTelemetryEnabled when false, the SDK does not send the anonymous x-chargebee-sdk-telemetry header. Default true.
+     */
+    sdkTelemetryEnabled?: boolean;
   };
 
   export interface HttpClientInterface {
     makeApiRequest: (request: Request, timeout: number) => Promise<Response>;
   }
 
-  export type RequestTelemetryHandle = unknown;
-
   export const TelemetryAttributeKeys: {
     readonly URL_FULL: 'url.full';
     readonly HTTP_REQUEST_METHOD: 'http.request.method';
@@ -214,6 +217,10 @@ declare module 'chargebee' {
     readonly CHARGEBEE_ERROR_PARAM: 'chargebee.error.param';
   };
 
+  export const SDK_TELEMETRY_HEADER_NAME: 'x-chargebee-sdk-telemetry';
+
+  export type RequestTelemetryHandle = unknown;
+
   export type RequestTelemetryContext = {
     spanName: string;
     resource: string;