chargebee 3.27.0 → 3.28.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
-### v3.27.0 (2026-06-30)
+### v3.28.0 (2026-06-30)
 * * *
+
+### New Features
+* Added an optional `telemetryAdapter` config hook for tracing Chargebee API calls via OpenTelemetry (or any APM). When unconfigured, the SDK skips all telemetry work — no behavior change for existing integrations.
+* Each API call emits one CLIENT span (`chargebee.{resource}.{operation}`) with OpenTelemetry HTTP semantic-convention attributes plus `chargebee.*` attributes, and injects W3C trace context (`traceparent`) into outbound requests for distributed tracing.
+* Exposed `TelemetryAdapter`, `RequestTelemetryContext`, `RequestTelemetryResult`, `RequestTelemetryError`, `RequestTelemetryHandle` types and the `TelemetryAttributeKeys` constant from the CJS and ESM entry points.
+* Added a ready-to-use OpenTelemetry adapter via the `chargebee/telemetry/otel` subpath. `@opentelemetry/api` is an optional peer dependency and is not bundled — install it in your app to use this adapter.
+
 ### Enhancements:
 - **Zod-backed request validation** — Set `enableValidation: true` in the client configuration to validate outgoing request parameters against each endpoint's generated Zod schema before the API call is sent. Invalid payloads raise `ChargebeeZodValidationError`, which carries the offending `actionName` and the original `ZodError` (including `issues` and `flatten()`) for inspection.
 - **Runtime dependency** — Added [`zod`](https://www.npmjs.com/package/zod) (v4) as a runtime dependency to support request validation.
@@ -41,7 +48,6 @@
 - `updated_at` and `created_at` have been added as new values to enum query parameter `sort_by.desc` in [`list_omnichannel_subscriptions`](https://apidocs.chargebee.com/docs/api/omnichannel_subscriptions/list-omnichannel-subscriptions) of [`OmnichannelSubscription`](https://apidocs.chargebee.com/docs/api/omnichannel_subscriptions).
 
 
-
 ### v3.25.0 (2026-06-08)
 * * *
 ### New Attributes:

package/README.md

@@ -602,6 +602,98 @@ const chargebee = new Chargebee({
 
 These examples demonstrate how to implement and inject custom clients using `axios` and `ky`, respectively.
 
+### 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.
+
+`@opentelemetry/api` is an **optional peer dependency** — it is not bundled with `chargebee` and is only loaded when you import the adapter, so a plain `import 'chargebee'` stays dependency-free.
+
+The SDK builds standardized span attributes (`ctx.startAttributes`, `result.endAttributes`) following the stable [OpenTelemetry HTTP semantic conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/) (`url.full`, `http.request.method`, `http.response.status_code`, `server.address`, `error.type`) plus Chargebee-specific `chargebee.*` attributes — use them as-is so spans render correctly in your APM and stay consistent across SDKs.
+
+Spans are named `chargebee.{resource}.{operation}` (e.g. `chargebee.subscription.create`).
+
+#### Quick start (built-in adapter)
+
+```bash
+npm install chargebee @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http
+```
+
+Configure OpenTelemetry once at app startup. Exporting (endpoint, service name, credentials) is driven entirely by your OpenTelemetry runtime and the standard `OTEL_*` environment variables — the adapter just uses the globally registered tracer:
+
+```typescript
+// instrumentation.ts — node --require ./instrumentation.js app.js
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+
+new NodeSDK({
+  serviceName: process.env.OTEL_SERVICE_NAME ?? 'billing-service',
+  traceExporter: new OTLPTraceExporter({
+    url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ?? 'http://localhost:4318/v1/traces',
+  }),
+}).start();
+```
+
+Then import the ready-to-use adapter and pass it on client initialization:
+
+```typescript
+import Chargebee from 'chargebee';
+import otelDefaultAdapter from 'chargebee/telemetry/otel';
+
+const chargebee = new Chargebee({
+  site: '{{site}}',
+  apiKey: '{{api-key}}',
+  telemetryAdapter: otelDefaultAdapter,
+});
+```
+
+That's it — every SDK call now emits a `chargebee.<resource>.<operation>` CLIENT span that attaches to the active OpenTelemetry context (or starts a root span), with W3C trace context propagated to Chargebee. Spans are exported by your own OpenTelemetry setup, so they flow to whatever backend you've configured (Datadog, Splunk, Honeycomb, Jaeger, etc.) — refer to your APM vendor's OpenTelemetry/OTLP documentation for exporter endpoints.
+
+#### Custom adapter (advanced)
+
+To customize behavior (different tracer name, extra attributes, a non-OpenTelemetry backend, etc.), implement `TelemetryAdapter` yourself instead of importing the built-in adapter:
+
+```typescript
+import Chargebee, {
+  type TelemetryAdapter,
+  type RequestTelemetryContext,
+  type RequestTelemetryResult,
+} from 'chargebee';
+import { context, propagation, trace, SpanKind, SpanStatusCode, type Span } from '@opentelemetry/api';
+
+class OtelTelemetryAdapter implements TelemetryAdapter<Span> {
+  private readonly tracer = trace.getTracer('chargebee-node');
+
+  onRequestStart(ctx: RequestTelemetryContext, requestHeaders: Record<string, string | number>): Span {
+    const span = this.tracer.startSpan(ctx.spanName, {
+      kind: SpanKind.CLIENT,
+      attributes: ctx.startAttributes,
+    });
+    propagation.inject(trace.setSpan(context.active(), span), requestHeaders);
+    return span;
+  }
+
+  onRequestEnd(span: Span | void, result: RequestTelemetryResult) {
+    if (!span) return;
+    for (const [key, value] of Object.entries(result.endAttributes)) {
+      span.setAttribute(key, value);
+    }
+    if (result.error) {
+      span.recordException(new Error(result.error.message));
+      span.setStatus({ code: SpanStatusCode.ERROR, message: result.error.message });
+    } else {
+      span.setStatus({ code: SpanStatusCode.OK });
+    }
+    span.end();
+  }
+}
+
+const chargebee = new Chargebee({
+  site: '{{site}}',
+  apiKey: '{{api-key}}',
+  telemetryAdapter: new OtelTelemetryAdapter(),
+});
+```
+
 ## Feedback
 
 If you find any bugs or have any questions / feedback, open an issue in this repository or reach out to us on dx@chargebee.com

package/cjs/RequestWrapper.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RequestWrapper = void 0;
 const util_js_1 = require("./util.js");
+const index_js_1 = require("./telemetry/index.js");
 const coreCommon_js_1 = require("./coreCommon.js");
 const node_buffer_1 = require("node:buffer");
 const chargebeeZodValidationError_js_1 = require("./chargebeeZodValidationError.js");
@@ -45,9 +46,28 @@ class RequestWrapper {
         }
         return null;
     }
+    _buildRequestUrl(env, urlIdParam, params) {
+        let path = (0, util_js_1.getApiURL)(env, this.apiCall.urlPrefix, this.apiCall.urlSuffix, urlIdParam);
+        if (this.apiCall.httpMethod === 'GET') {
+            let requestParams = params;
+            if (typeof requestParams === 'undefined' || requestParams === null) {
+                requestParams = {};
+            }
+            const queryParam = this.apiCall.isListReq
+                ? (0, util_js_1.encodeListParams)((0, util_js_1.serialize)(requestParams))
+                : (0, util_js_1.encodeParams)((0, util_js_1.serialize)(requestParams));
+            path += '?' + queryParam;
+        }
+        return new URL(path, `${env.protocol}://${(0, util_js_1.getHost)(env, this.apiCall.subDomain)}${env.port ? `:${env.port}` : ''}`);
+    }
     async request() {
         let _env = {};
         (0, util_js_1.extend)(true, _env, this.envArg);
+        // Class-based adapters (e.g. OpenTelemetry) keep methods on the prototype;
+        // deep extend only copies own enumerable properties, so preserve by reference.
+        if (this.envArg.telemetryAdapter !== undefined) {
+            _env.telemetryAdapter = this.envArg.telemetryAdapter;
+        }
         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;
@@ -77,19 +97,43 @@ class RequestWrapper {
             retryConfig.enabled) {
             this.httpHeaders['chargebee-idempotency-key'] = (0, util_js_1.generateUUIDv4)();
         }
+        const telemetryAdapter = env.telemetryAdapter;
+        const telemetryHeaders = {};
+        const requestStartTime = Date.now();
+        const requestUrl = this._buildRequestUrl(env, urlIdParam, params);
+        // No telemetry adapter configured => skip all telemetry work (zero overhead).
+        let telemetryHandle;
+        if (telemetryAdapter !== undefined) {
+            const telemetryContext = (0, index_js_1.buildRequestTelemetryContext)({
+                resource: this.apiCall.resource,
+                operation: this.apiCall.methodName,
+                httpMethod: this.apiCall.httpMethod,
+                httpUrl: `${requestUrl.origin}${requestUrl.pathname}`,
+                serverAddress: requestUrl.hostname,
+                chargebeeSite: env.site,
+                chargebeeApiVersion: (0, index_js_1.resolveChargebeeApiVersion)(env.apiPath),
+                sdkVersion: env.clientVersion,
+                requestHeaders: this.httpHeaders,
+            });
+            try {
+                telemetryHandle = telemetryAdapter.onRequestStart(telemetryContext, telemetryHeaders);
+            }
+            catch (err) {
+                const message = err instanceof Error
+                    ? err.message
+                    : 'Unknown telemetry adapter error';
+                (0, util_js_1.log)(env, {
+                    level: 'ERROR',
+                    message: `Telemetry adapter onRequestStart failed: ${message}. Continuing without telemetry.`,
+                });
+                telemetryHandle = undefined;
+            }
+        }
         const makeRequest = async (attempt = 0) => {
-            let path = (0, util_js_1.getApiURL)(env, this.apiCall.urlPrefix, this.apiCall.urlSuffix, urlIdParam);
             let requestParams = params;
             if (typeof requestParams === 'undefined' || requestParams === null) {
                 requestParams = {};
             }
-            if (this.apiCall.httpMethod === 'GET') {
-                const queryParam = this.apiCall.isListReq
-                    ? (0, util_js_1.encodeListParams)((0, util_js_1.serialize)(requestParams))
-                    : (0, util_js_1.encodeParams)((0, util_js_1.serialize)(requestParams));
-                path += '?' + queryParam;
-                requestParams = {};
-            }
             const jsonKeys = this.apiCall.jsonKeys;
             let data = null;
             if (this.apiCall.httpMethod !== 'GET') {
@@ -97,7 +141,7 @@ class RequestWrapper {
                     ? JSON.stringify(requestParams)
                     : (0, util_js_1.encodeParams)(requestParams, undefined, undefined, undefined, jsonKeys);
             }
-            const requestHeaders = Object.assign({}, this.httpHeaders);
+            const requestHeaders = Object.assign(Object.assign({}, this.httpHeaders), telemetryHeaders);
             if (data && data.length) {
                 (0, util_js_1.extend)(true, requestHeaders, {
                     'Content-Length': node_buffer_1.Buffer.byteLength(data, 'utf8'),
@@ -117,8 +161,7 @@ class RequestWrapper {
             if (attempt > 0) {
                 requestHeaders['X-CB-Retry-Attempt'] = attempt.toString();
             }
-            const url = new URL(path, `${env.protocol}://${(0, util_js_1.getHost)(env, this.apiCall.subDomain)}${env.port ? `:${env.port}` : ''}`);
-            const request = new Request(url, {
+            const request = new Request(requestUrl, {
                 method: this.apiCall.httpMethod,
                 body: data || undefined,
                 headers: this._createHeaders(requestHeaders),
@@ -180,7 +223,55 @@ class RequestWrapper {
                 return await withRetry(retryCount + 1, startTime);
             }
         };
-        const promise = withRetry(0, Date.now());
+        const runWithTelemetry = async (adapter) => {
+            var _a;
+            try {
+                const result = await withRetry(0, requestStartTime);
+                const httpStatusCode = typeof (result === null || result === void 0 ? void 0 : result.httpStatusCode) === 'number'
+                    ? result.httpStatusCode
+                    : 200;
+                try {
+                    adapter.onRequestEnd(telemetryHandle, (0, index_js_1.buildRequestTelemetryResult)({
+                        httpStatusCode,
+                        durationMs: Date.now() - requestStartTime,
+                    }));
+                }
+                catch (err) {
+                    const message = err instanceof Error
+                        ? err.message
+                        : 'Unknown telemetry adapter error';
+                    (0, util_js_1.log)(env, {
+                        level: 'ERROR',
+                        message: `Telemetry adapter onRequestEnd failed: ${message}.`,
+                    });
+                }
+                return result;
+            }
+            catch (err) {
+                const httpStatusCode = (_a = (0, index_js_1.extractHttpStatusCode)(err)) !== null && _a !== void 0 ? _a : 500;
+                const telemetryError = (0, index_js_1.extractRequestTelemetryError)(err);
+                try {
+                    adapter.onRequestEnd(telemetryHandle, (0, index_js_1.buildRequestTelemetryResult)({
+                        httpStatusCode,
+                        durationMs: Date.now() - requestStartTime,
+                        error: telemetryError,
+                    }));
+                }
+                catch (telemetryErr) {
+                    const message = telemetryErr instanceof Error
+                        ? telemetryErr.message
+                        : 'Unknown telemetry adapter error';
+                    (0, util_js_1.log)(env, {
+                        level: 'ERROR',
+                        message: `Telemetry adapter onRequestEnd failed: ${message}.`,
+                    });
+                }
+                throw err;
+            }
+        };
+        const promise = telemetryAdapter !== undefined
+            ? runWithTelemetry(telemetryAdapter)
+            : withRetry(0, requestStartTime);
         return (0, util_js_1.callbackifyPromise)(promise);
     }
     _createHeaders(httpHeaders) {

package/cjs/chargebee.cjs.js

@@ -4,6 +4,7 @@ const createChargebee_js_1 = require("./createChargebee.js");
 const FetchClient_js_1 = require("./net/FetchClient.js");
 const handler_js_1 = require("./resources/webhook/handler.js");
 const auth_js_1 = require("./resources/webhook/auth.js");
+const index_js_1 = require("./telemetry/index.js");
 const chargebeeZodValidationError_js_1 = require("./chargebeeZodValidationError.js");
 const httpClient = new FetchClient_js_1.FetchHttpClient();
 const Chargebee = (0, createChargebee_js_1.CreateChargebee)(httpClient);
@@ -19,5 +20,6 @@ module.exports.WebhookError = handler_js_1.WebhookError;
 module.exports.WebhookAuthenticationError = handler_js_1.WebhookAuthenticationError;
 module.exports.WebhookPayloadValidationError = handler_js_1.WebhookPayloadValidationError;
 module.exports.WebhookPayloadParseError = handler_js_1.WebhookPayloadParseError;
+module.exports.TelemetryAttributeKeys = index_js_1.TelemetryAttributeKeys;
 // Export validation error class
 module.exports.ChargebeeZodValidationError = chargebeeZodValidationError_js_1.ChargebeeZodValidationError;

package/cjs/createChargebee.js

@@ -1,4 +1,15 @@
 "use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CreateChargebee = void 0;
 const RequestWrapper_js_1 = require("./RequestWrapper.js");
@@ -10,10 +21,14 @@ const handler_js_1 = require("./resources/webhook/handler.js");
 const CreateChargebee = (httpClient) => {
     const Chargebee = function (conf) {
         this._env = Object.assign({}, environment_js_1.Environment);
-        (0, util_js_1.extend)(true, this._env, conf);
+        const { telemetryAdapter, httpClient: configHttpClient } = conf, confToMerge = __rest(conf, ["telemetryAdapter", "httpClient"]);
+        (0, util_js_1.extend)(true, this._env, confToMerge);
         // @ts-ignore
         this._env.httpClient =
-            conf.httpClient != null ? conf.httpClient : httpClient;
+            configHttpClient != null ? configHttpClient : httpClient;
+        if (telemetryAdapter !== undefined) {
+            this._env.telemetryAdapter = telemetryAdapter;
+        }
         this._buildResources();
         this._endpoints = api_endpoints_js_1.Endpoints;
         // Initialize webhooks handler with auto-configured Basic Auth (if env vars are set)
@@ -85,6 +100,7 @@ const CreateChargebee = (httpClient) => {
                 for (let apiIdx = 0; apiIdx < apiCalls.length; apiIdx++) {
                     const metaArr = apiCalls[apiIdx];
                     const apiCall = {
+                        resource: res,
                         methodName: metaArr[0],
                         httpMethod: metaArr[1],
                         urlPrefix: metaArr[2],

package/cjs/environment.js

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

package/cjs/telemetry/TelemetryAdapter.js

@@ -0,0 +1,145 @@
+"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.NO_OP_TELEMETRY_ADAPTER = exports.NoOpTelemetryAdapter = void 0;
+exports.buildSpanName = buildSpanName;
+exports.resolveChargebeeApiVersion = resolveChargebeeApiVersion;
+exports.buildRequestHeaderSpanAttributes = buildRequestHeaderSpanAttributes;
+exports.buildRequestStartSpanAttributes = buildRequestStartSpanAttributes;
+exports.buildRequestEndSpanAttributes = buildRequestEndSpanAttributes;
+exports.buildRequestTelemetryContext = buildRequestTelemetryContext;
+exports.buildRequestTelemetryResult = buildRequestTelemetryResult;
+exports.extractRequestTelemetryError = extractRequestTelemetryError;
+exports.extractHttpStatusCode = extractHttpStatusCode;
+const types_js_1 = require("./types.js");
+class NoOpTelemetryAdapter {
+    onRequestStart() {
+        return;
+    }
+    onRequestEnd() {
+        return;
+    }
+}
+exports.NoOpTelemetryAdapter = NoOpTelemetryAdapter;
+exports.NO_OP_TELEMETRY_ADAPTER = new NoOpTelemetryAdapter();
+function buildSpanName(resource, operation) {
+    return `${types_js_1.TELEMETRY_SPAN_NAME_PREFIX}.${resource}.${operation}`;
+}
+function resolveChargebeeApiVersion(apiPath) {
+    return apiPath === '/api/v1' ? 'v1' : 'v2';
+}
+/**
+ * Captures Chargebee custom request headers as OTel span attributes.
+ *
+ * Headers whose (lowercased) name starts with `chargebee-` are recorded as
+ * `http.request.header.<name>` with string[] values, per the OpenTelemetry HTTP semantic
+ * conventions. The `chargebee-request-origin-*` family (origin IP, email, device) is skipped
+ * because it carries end-user PII. Matching by prefix means new `chargebee-*` headers are
+ * captured automatically without an SDK upgrade.
+ */
+function buildRequestHeaderSpanAttributes(requestHeaders) {
+    const attributes = {};
+    if (!requestHeaders) {
+        return attributes;
+    }
+    for (const [name, value] of Object.entries(requestHeaders)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        const lowerName = name.toLowerCase();
+        if (!lowerName.startsWith(types_js_1.CHARGEBEE_TELEMETRY_HEADER_PREFIX) ||
+            lowerName.startsWith(types_js_1.CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX)) {
+            continue;
+        }
+        attributes[`${types_js_1.HTTP_REQUEST_HEADER_ATTRIBUTE_PREFIX}${lowerName}`] = [
+            String(value),
+        ];
+    }
+    return attributes;
+}
+function buildRequestStartSpanAttributes(input) {
+    return Object.assign({ [types_js_1.TelemetryAttributeKeys.URL_FULL]: input.httpUrl, [types_js_1.TelemetryAttributeKeys.HTTP_REQUEST_METHOD]: input.httpMethod, [types_js_1.TelemetryAttributeKeys.SERVER_ADDRESS]: input.serverAddress, [types_js_1.TelemetryAttributeKeys.CHARGEBEE_SITE]: input.chargebeeSite, [types_js_1.TelemetryAttributeKeys.CHARGEBEE_API_VERSION]: input.chargebeeApiVersion, [types_js_1.TelemetryAttributeKeys.CHARGEBEE_RESOURCE]: input.resource, [types_js_1.TelemetryAttributeKeys.CHARGEBEE_OPERATION]: input.operation, [types_js_1.TelemetryAttributeKeys.CHARGEBEE_SDK_NAME]: types_js_1.CHARGEBEE_SDK_NAME, [types_js_1.TelemetryAttributeKeys.CHARGEBEE_SDK_VERSION]: input.sdkVersion }, buildRequestHeaderSpanAttributes(input.requestHeaders));
+}
+function buildRequestEndSpanAttributes(result) {
+    const attributes = {
+        [types_js_1.TelemetryAttributeKeys.HTTP_RESPONSE_STATUS_CODE]: result.httpStatusCode,
+    };
+    if (result.error) {
+        // error.type is the status code on failed requests
+        attributes[types_js_1.TelemetryAttributeKeys.ERROR_TYPE] = String(result.httpStatusCode);
+        if (result.error.chargebeeErrorCode) {
+            attributes[types_js_1.TelemetryAttributeKeys.CHARGEBEE_ERROR_CODE] =
+                result.error.chargebeeErrorCode;
+        }
+        if (result.error.chargebeeApiErrorType) {
+            attributes[types_js_1.TelemetryAttributeKeys.CHARGEBEE_ERROR_TYPE] =
+                result.error.chargebeeApiErrorType;
+        }
+        if (result.error.chargebeeErrorParam) {
+            attributes[types_js_1.TelemetryAttributeKeys.CHARGEBEE_ERROR_PARAM] =
+                result.error.chargebeeErrorParam;
+        }
+    }
+    return attributes;
+}
+function buildRequestTelemetryContext(input) {
+    return {
+        spanName: buildSpanName(input.resource, input.operation),
+        resource: input.resource,
+        operation: input.operation,
+        httpMethod: input.httpMethod,
+        httpUrl: input.httpUrl,
+        serverAddress: input.serverAddress,
+        chargebeeSite: input.chargebeeSite,
+        chargebeeApiVersion: input.chargebeeApiVersion,
+        sdkName: types_js_1.CHARGEBEE_SDK_NAME,
+        sdkVersion: input.sdkVersion,
+        startAttributes: buildRequestStartSpanAttributes(input),
+    };
+}
+function buildRequestTelemetryResult(result) {
+    return Object.assign(Object.assign({}, result), { endAttributes: buildRequestEndSpanAttributes(result) });
+}
+function extractRequestTelemetryError(err) {
+    if (err == null || typeof err !== 'object') {
+        return undefined;
+    }
+    const errorObj = err;
+    const message = typeof errorObj.message === 'string'
+        ? errorObj.message
+        : 'Chargebee API request failed';
+    const result = { message };
+    if (typeof errorObj.api_error_code === 'string') {
+        result.chargebeeErrorCode = errorObj.api_error_code;
+    }
+    if (typeof errorObj.type === 'string') {
+        result.chargebeeApiErrorType = errorObj.type;
+    }
+    if (typeof errorObj.param === 'string') {
+        result.chargebeeErrorParam = errorObj.param;
+    }
+    return result;
+}
+function extractHttpStatusCode(err) {
+    if (err == null || typeof err !== 'object') {
+        return undefined;
+    }
+    const errorObj = err;
+    for (const key of [
+        'http_status_code',
+        'httpStatusCode',
+        'http_code',
+        'statusCode',
+    ]) {
+        const value = errorObj[key];
+        if (typeof value === 'number') {
+            return value;
+        }
+    }
+    return undefined;
+}

package/cjs/telemetry/index.js

@@ -0,0 +1,28 @@
+"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.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; } });
+Object.defineProperty(exports, "CHARGEBEE_TELEMETRY_HEADER_PREFIX", { enumerable: true, get: function () { return types_js_1.CHARGEBEE_TELEMETRY_HEADER_PREFIX; } });
+Object.defineProperty(exports, "HTTP_REQUEST_HEADER_ATTRIBUTE_PREFIX", { enumerable: true, get: function () { return types_js_1.HTTP_REQUEST_HEADER_ATTRIBUTE_PREFIX; } });
+Object.defineProperty(exports, "TELEMETRY_SPAN_NAME_PREFIX", { enumerable: true, get: function () { return types_js_1.TELEMETRY_SPAN_NAME_PREFIX; } });
+Object.defineProperty(exports, "TelemetryAttributeKeys", { enumerable: true, get: function () { return types_js_1.TelemetryAttributeKeys; } });
+var TelemetryAdapter_js_1 = require("./TelemetryAdapter.js");
+Object.defineProperty(exports, "NO_OP_TELEMETRY_ADAPTER", { enumerable: true, get: function () { return TelemetryAdapter_js_1.NO_OP_TELEMETRY_ADAPTER; } });
+Object.defineProperty(exports, "NoOpTelemetryAdapter", { enumerable: true, get: function () { return TelemetryAdapter_js_1.NoOpTelemetryAdapter; } });
+Object.defineProperty(exports, "buildRequestEndSpanAttributes", { enumerable: true, get: function () { return TelemetryAdapter_js_1.buildRequestEndSpanAttributes; } });
+Object.defineProperty(exports, "buildRequestHeaderSpanAttributes", { enumerable: true, get: function () { return TelemetryAdapter_js_1.buildRequestHeaderSpanAttributes; } });
+Object.defineProperty(exports, "buildRequestStartSpanAttributes", { enumerable: true, get: function () { return TelemetryAdapter_js_1.buildRequestStartSpanAttributes; } });
+Object.defineProperty(exports, "buildRequestTelemetryContext", { enumerable: true, get: function () { return TelemetryAdapter_js_1.buildRequestTelemetryContext; } });
+Object.defineProperty(exports, "buildRequestTelemetryResult", { enumerable: true, get: function () { return TelemetryAdapter_js_1.buildRequestTelemetryResult; } });
+Object.defineProperty(exports, "buildSpanName", { enumerable: true, get: function () { return TelemetryAdapter_js_1.buildSpanName; } });
+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; } });

package/cjs/telemetry/otel.js

@@ -0,0 +1,66 @@
+"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.OtelTelemetryAdapter = void 0;
+const api_1 = require("@opentelemetry/api");
+const types_js_1 = require("./types.js");
+const tracer = api_1.trace.getTracer(types_js_1.CHARGEBEE_SDK_NAME);
+function toRecordedException(error) {
+    var _a;
+    const exception = new Error(error.message);
+    exception.name = (_a = error.chargebeeErrorCode) !== null && _a !== void 0 ? _a : 'ChargebeeAPIError';
+    return exception;
+}
+/**
+ * Ready-to-use OpenTelemetry adapter for the Chargebee SDK.
+ *
+ * Each SDK request becomes a CLIENT span attached to the active OpenTelemetry
+ * context (or a root span when none is active), and the W3C trace context is
+ * propagated to Chargebee so the trace continues server-side.
+ *
+ * Exporting (endpoint, service name, credentials) is configured by your own
+ * OpenTelemetry runtime via the standard `OTEL_*` environment variables — this
+ * adapter only uses the globally registered tracer from `@opentelemetry/api`.
+ *
+ * `@opentelemetry/api` is an optional peer dependency; install it to use this
+ * adapter. A default-exported, ready-to-use instance is provided.
+ */
+class OtelTelemetryAdapter {
+    onRequestStart(ctx, requestHeaders) {
+        // startSpan adopts the active context's span as parent (or starts a root span if none).
+        const span = tracer.startSpan(ctx.spanName, {
+            kind: api_1.SpanKind.CLIENT,
+            attributes: ctx.startAttributes,
+        });
+        // Propagate W3C trace context to Chargebee so the trace continues server-side.
+        api_1.propagation.inject(api_1.trace.setSpan(api_1.context.active(), span), requestHeaders);
+        return span;
+    }
+    onRequestEnd(span, result) {
+        if (!span) {
+            return;
+        }
+        for (const [key, value] of Object.entries(result.endAttributes)) {
+            span.setAttribute(key, value);
+        }
+        if (result.error) {
+            span.recordException(toRecordedException(result.error));
+            span.setStatus({
+                code: api_1.SpanStatusCode.ERROR,
+                message: result.error.message,
+            });
+        }
+        else {
+            span.setStatus({ code: api_1.SpanStatusCode.OK });
+        }
+        span.end();
+    }
+}
+exports.OtelTelemetryAdapter = OtelTelemetryAdapter;
+const otelDefaultAdapter = new OtelTelemetryAdapter();
+exports.default = otelDefaultAdapter;

package/cjs/telemetry/types.js

@@ -0,0 +1,47 @@
+"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.TelemetryAttributeKeys = exports.CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX = exports.CHARGEBEE_TELEMETRY_HEADER_PREFIX = exports.HTTP_REQUEST_HEADER_ATTRIBUTE_PREFIX = exports.TELEMETRY_SPAN_NAME_PREFIX = exports.CHARGEBEE_SDK_NAME = void 0;
+/** SDK identifier recorded on telemetry spans. */
+exports.CHARGEBEE_SDK_NAME = 'chargebee-node';
+/** Standard span name prefix: chargebee.{resource}.{operation} */
+exports.TELEMETRY_SPAN_NAME_PREFIX = 'chargebee';
+/**
+ * OTel HTTP semantic-convention prefix for request-header attributes:
+ * `http.request.header.<lowercased-name>` with string[] values.
+ */
+exports.HTTP_REQUEST_HEADER_ATTRIBUTE_PREFIX = 'http.request.header.';
+/**
+ * Request headers whose (lowercased) name starts with this prefix are captured as span
+ * attributes. Using a prefix instead of a fixed list means any future `chargebee-*` header
+ * is picked up automatically, with no SDK upgrade required.
+ */
+exports.CHARGEBEE_TELEMETRY_HEADER_PREFIX = 'chargebee-';
+/**
+ * Headers under this sub-prefix carry end-user PII (origin IP, email, device) and are
+ * excluded from spans by default. Chargebee namespaces such headers under
+ * `chargebee-request-origin-*`, so future PII headers stay excluded automatically.
+ */
+exports.CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX = 'chargebee-request-origin-';
+/** Span attribute keys — shared across Chargebee SDKs. */
+exports.TelemetryAttributeKeys = {
+    URL_FULL: 'url.full',
+    HTTP_REQUEST_METHOD: 'http.request.method',
+    HTTP_RESPONSE_STATUS_CODE: 'http.response.status_code',
+    SERVER_ADDRESS: 'server.address',
+    ERROR_TYPE: 'error.type',
+    CHARGEBEE_SITE: 'chargebee.site',
+    CHARGEBEE_API_VERSION: 'chargebee.api_version',
+    CHARGEBEE_RESOURCE: 'chargebee.resource',
+    CHARGEBEE_OPERATION: 'chargebee.operation',
+    CHARGEBEE_SDK_NAME: 'chargebee.sdk.name',
+    CHARGEBEE_SDK_VERSION: 'chargebee.sdk.version',
+    CHARGEBEE_ERROR_CODE: 'chargebee.error.code',
+    CHARGEBEE_ERROR_TYPE: 'chargebee.error.type',
+    CHARGEBEE_ERROR_PARAM: 'chargebee.error.param',
+};

package/esm/RequestWrapper.js

@@ -1,4 +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 { handleResponse } from './coreCommon.js';
 import { Buffer } from 'node:buffer';
 import { ChargebeeZodValidationError } from './chargebeeZodValidationError.js';
@@ -42,9 +43,28 @@ export class RequestWrapper {
         }
         return null;
     }
+    _buildRequestUrl(env, urlIdParam, params) {
+        let path = getApiURL(env, this.apiCall.urlPrefix, this.apiCall.urlSuffix, urlIdParam);
+        if (this.apiCall.httpMethod === 'GET') {
+            let requestParams = params;
+            if (typeof requestParams === 'undefined' || requestParams === null) {
+                requestParams = {};
+            }
+            const queryParam = this.apiCall.isListReq
+                ? encodeListParams(serialize(requestParams))
+                : encodeParams(serialize(requestParams));
+            path += '?' + queryParam;
+        }
+        return new URL(path, `${env.protocol}://${getHost(env, this.apiCall.subDomain)}${env.port ? `:${env.port}` : ''}`);
+    }
     async request() {
         let _env = {};
         extend(true, _env, this.envArg);
+        // Class-based adapters (e.g. OpenTelemetry) keep methods on the prototype;
+        // deep extend only copies own enumerable properties, so preserve by reference.
+        if (this.envArg.telemetryAdapter !== undefined) {
+            _env.telemetryAdapter = this.envArg.telemetryAdapter;
+        }
         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;
@@ -74,19 +94,43 @@ export class RequestWrapper {
             retryConfig.enabled) {
             this.httpHeaders['chargebee-idempotency-key'] = uuidv4();
         }
+        const telemetryAdapter = env.telemetryAdapter;
+        const telemetryHeaders = {};
+        const requestStartTime = Date.now();
+        const requestUrl = this._buildRequestUrl(env, urlIdParam, params);
+        // No telemetry adapter configured => skip all telemetry work (zero overhead).
+        let telemetryHandle;
+        if (telemetryAdapter !== undefined) {
+            const telemetryContext = buildRequestTelemetryContext({
+                resource: this.apiCall.resource,
+                operation: this.apiCall.methodName,
+                httpMethod: this.apiCall.httpMethod,
+                httpUrl: `${requestUrl.origin}${requestUrl.pathname}`,
+                serverAddress: requestUrl.hostname,
+                chargebeeSite: env.site,
+                chargebeeApiVersion: resolveChargebeeApiVersion(env.apiPath),
+                sdkVersion: env.clientVersion,
+                requestHeaders: this.httpHeaders,
+            });
+            try {
+                telemetryHandle = telemetryAdapter.onRequestStart(telemetryContext, telemetryHeaders);
+            }
+            catch (err) {
+                const message = err instanceof Error
+                    ? err.message
+                    : 'Unknown telemetry adapter error';
+                log(env, {
+                    level: 'ERROR',
+                    message: `Telemetry adapter onRequestStart failed: ${message}. Continuing without telemetry.`,
+                });
+                telemetryHandle = undefined;
+            }
+        }
         const makeRequest = async (attempt = 0) => {
-            let path = getApiURL(env, this.apiCall.urlPrefix, this.apiCall.urlSuffix, urlIdParam);
             let requestParams = params;
             if (typeof requestParams === 'undefined' || requestParams === null) {
                 requestParams = {};
             }
-            if (this.apiCall.httpMethod === 'GET') {
-                const queryParam = this.apiCall.isListReq
-                    ? encodeListParams(serialize(requestParams))
-                    : encodeParams(serialize(requestParams));
-                path += '?' + queryParam;
-                requestParams = {};
-            }
             const jsonKeys = this.apiCall.jsonKeys;
             let data = null;
             if (this.apiCall.httpMethod !== 'GET') {
@@ -94,7 +138,7 @@ export class RequestWrapper {
                     ? JSON.stringify(requestParams)
                     : encodeParams(requestParams, undefined, undefined, undefined, jsonKeys);
             }
-            const requestHeaders = Object.assign({}, this.httpHeaders);
+            const requestHeaders = Object.assign(Object.assign({}, this.httpHeaders), telemetryHeaders);
             if (data && data.length) {
                 extend(true, requestHeaders, {
                     'Content-Length': Buffer.byteLength(data, 'utf8'),
@@ -114,8 +158,7 @@ export class RequestWrapper {
             if (attempt > 0) {
                 requestHeaders['X-CB-Retry-Attempt'] = attempt.toString();
             }
-            const url = new URL(path, `${env.protocol}://${getHost(env, this.apiCall.subDomain)}${env.port ? `:${env.port}` : ''}`);
-            const request = new Request(url, {
+            const request = new Request(requestUrl, {
                 method: this.apiCall.httpMethod,
                 body: data || undefined,
                 headers: this._createHeaders(requestHeaders),
@@ -177,7 +220,55 @@ export class RequestWrapper {
                 return await withRetry(retryCount + 1, startTime);
             }
         };
-        const promise = withRetry(0, Date.now());
+        const runWithTelemetry = async (adapter) => {
+            var _a;
+            try {
+                const result = await withRetry(0, requestStartTime);
+                const httpStatusCode = typeof (result === null || result === void 0 ? void 0 : result.httpStatusCode) === 'number'
+                    ? result.httpStatusCode
+                    : 200;
+                try {
+                    adapter.onRequestEnd(telemetryHandle, buildRequestTelemetryResult({
+                        httpStatusCode,
+                        durationMs: Date.now() - requestStartTime,
+                    }));
+                }
+                catch (err) {
+                    const message = err instanceof Error
+                        ? err.message
+                        : 'Unknown telemetry adapter error';
+                    log(env, {
+                        level: 'ERROR',
+                        message: `Telemetry adapter onRequestEnd failed: ${message}.`,
+                    });
+                }
+                return result;
+            }
+            catch (err) {
+                const httpStatusCode = (_a = extractHttpStatusCode(err)) !== null && _a !== void 0 ? _a : 500;
+                const telemetryError = extractRequestTelemetryError(err);
+                try {
+                    adapter.onRequestEnd(telemetryHandle, buildRequestTelemetryResult({
+                        httpStatusCode,
+                        durationMs: Date.now() - requestStartTime,
+                        error: telemetryError,
+                    }));
+                }
+                catch (telemetryErr) {
+                    const message = telemetryErr instanceof Error
+                        ? telemetryErr.message
+                        : 'Unknown telemetry adapter error';
+                    log(env, {
+                        level: 'ERROR',
+                        message: `Telemetry adapter onRequestEnd failed: ${message}.`,
+                    });
+                }
+                throw err;
+            }
+        };
+        const promise = telemetryAdapter !== undefined
+            ? runWithTelemetry(telemetryAdapter)
+            : withRetry(0, requestStartTime);
         return callbackifyPromise(promise);
     }
     _createHeaders(httpHeaders) {

package/esm/chargebee.esm.js

@@ -7,5 +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 validation error class
 export { ChargebeeZodValidationError } from './chargebeeZodValidationError.js';

package/esm/createChargebee.js

@@ -1,3 +1,14 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 import { RequestWrapper } from './RequestWrapper.js';
 import { Environment } from './environment.js';
 import { Endpoints } from './resources/api_endpoints.js';
@@ -7,10 +18,14 @@ import { WebhookHandler, createDefaultHandler, } from './resources/webhook/handl
 export const CreateChargebee = (httpClient) => {
     const Chargebee = function (conf) {
         this._env = Object.assign({}, Environment);
-        extend(true, this._env, conf);
+        const { telemetryAdapter, httpClient: configHttpClient } = conf, confToMerge = __rest(conf, ["telemetryAdapter", "httpClient"]);
+        extend(true, this._env, confToMerge);
         // @ts-ignore
         this._env.httpClient =
-            conf.httpClient != null ? conf.httpClient : httpClient;
+            configHttpClient != null ? configHttpClient : httpClient;
+        if (telemetryAdapter !== undefined) {
+            this._env.telemetryAdapter = telemetryAdapter;
+        }
         this._buildResources();
         this._endpoints = Endpoints;
         // Initialize webhooks handler with auto-configured Basic Auth (if env vars are set)
@@ -82,6 +97,7 @@ export const CreateChargebee = (httpClient) => {
                 for (let apiIdx = 0; apiIdx < apiCalls.length; apiIdx++) {
                     const metaArr = apiCalls[apiIdx];
                     const apiCall = {
+                        resource: res,
                         methodName: metaArr[0],
                         httpMethod: metaArr[1],
                         urlPrefix: metaArr[2],

package/esm/environment.js

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

package/esm/telemetry/TelemetryAdapter.js

@@ -0,0 +1,132 @@
+/*
+ * 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 { 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 class NoOpTelemetryAdapter {
+    onRequestStart() {
+        return;
+    }
+    onRequestEnd() {
+        return;
+    }
+}
+export const NO_OP_TELEMETRY_ADAPTER = new NoOpTelemetryAdapter();
+export function buildSpanName(resource, operation) {
+    return `${TELEMETRY_SPAN_NAME_PREFIX}.${resource}.${operation}`;
+}
+export function resolveChargebeeApiVersion(apiPath) {
+    return apiPath === '/api/v1' ? 'v1' : 'v2';
+}
+/**
+ * Captures Chargebee custom request headers as OTel span attributes.
+ *
+ * Headers whose (lowercased) name starts with `chargebee-` are recorded as
+ * `http.request.header.<name>` with string[] values, per the OpenTelemetry HTTP semantic
+ * conventions. The `chargebee-request-origin-*` family (origin IP, email, device) is skipped
+ * because it carries end-user PII. Matching by prefix means new `chargebee-*` headers are
+ * captured automatically without an SDK upgrade.
+ */
+export function buildRequestHeaderSpanAttributes(requestHeaders) {
+    const attributes = {};
+    if (!requestHeaders) {
+        return attributes;
+    }
+    for (const [name, value] of Object.entries(requestHeaders)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        const lowerName = name.toLowerCase();
+        if (!lowerName.startsWith(CHARGEBEE_TELEMETRY_HEADER_PREFIX) ||
+            lowerName.startsWith(CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX)) {
+            continue;
+        }
+        attributes[`${HTTP_REQUEST_HEADER_ATTRIBUTE_PREFIX}${lowerName}`] = [
+            String(value),
+        ];
+    }
+    return attributes;
+}
+export function buildRequestStartSpanAttributes(input) {
+    return Object.assign({ [TelemetryAttributeKeys.URL_FULL]: input.httpUrl, [TelemetryAttributeKeys.HTTP_REQUEST_METHOD]: input.httpMethod, [TelemetryAttributeKeys.SERVER_ADDRESS]: input.serverAddress, [TelemetryAttributeKeys.CHARGEBEE_SITE]: input.chargebeeSite, [TelemetryAttributeKeys.CHARGEBEE_API_VERSION]: input.chargebeeApiVersion, [TelemetryAttributeKeys.CHARGEBEE_RESOURCE]: input.resource, [TelemetryAttributeKeys.CHARGEBEE_OPERATION]: input.operation, [TelemetryAttributeKeys.CHARGEBEE_SDK_NAME]: CHARGEBEE_SDK_NAME, [TelemetryAttributeKeys.CHARGEBEE_SDK_VERSION]: input.sdkVersion }, buildRequestHeaderSpanAttributes(input.requestHeaders));
+}
+export function buildRequestEndSpanAttributes(result) {
+    const attributes = {
+        [TelemetryAttributeKeys.HTTP_RESPONSE_STATUS_CODE]: result.httpStatusCode,
+    };
+    if (result.error) {
+        // error.type is the status code on failed requests
+        attributes[TelemetryAttributeKeys.ERROR_TYPE] = String(result.httpStatusCode);
+        if (result.error.chargebeeErrorCode) {
+            attributes[TelemetryAttributeKeys.CHARGEBEE_ERROR_CODE] =
+                result.error.chargebeeErrorCode;
+        }
+        if (result.error.chargebeeApiErrorType) {
+            attributes[TelemetryAttributeKeys.CHARGEBEE_ERROR_TYPE] =
+                result.error.chargebeeApiErrorType;
+        }
+        if (result.error.chargebeeErrorParam) {
+            attributes[TelemetryAttributeKeys.CHARGEBEE_ERROR_PARAM] =
+                result.error.chargebeeErrorParam;
+        }
+    }
+    return attributes;
+}
+export function buildRequestTelemetryContext(input) {
+    return {
+        spanName: buildSpanName(input.resource, input.operation),
+        resource: input.resource,
+        operation: input.operation,
+        httpMethod: input.httpMethod,
+        httpUrl: input.httpUrl,
+        serverAddress: input.serverAddress,
+        chargebeeSite: input.chargebeeSite,
+        chargebeeApiVersion: input.chargebeeApiVersion,
+        sdkName: CHARGEBEE_SDK_NAME,
+        sdkVersion: input.sdkVersion,
+        startAttributes: buildRequestStartSpanAttributes(input),
+    };
+}
+export function buildRequestTelemetryResult(result) {
+    return Object.assign(Object.assign({}, result), { endAttributes: buildRequestEndSpanAttributes(result) });
+}
+export function extractRequestTelemetryError(err) {
+    if (err == null || typeof err !== 'object') {
+        return undefined;
+    }
+    const errorObj = err;
+    const message = typeof errorObj.message === 'string'
+        ? errorObj.message
+        : 'Chargebee API request failed';
+    const result = { message };
+    if (typeof errorObj.api_error_code === 'string') {
+        result.chargebeeErrorCode = errorObj.api_error_code;
+    }
+    if (typeof errorObj.type === 'string') {
+        result.chargebeeApiErrorType = errorObj.type;
+    }
+    if (typeof errorObj.param === 'string') {
+        result.chargebeeErrorParam = errorObj.param;
+    }
+    return result;
+}
+export function extractHttpStatusCode(err) {
+    if (err == null || typeof err !== 'object') {
+        return undefined;
+    }
+    const errorObj = err;
+    for (const key of [
+        'http_status_code',
+        'httpStatusCode',
+        'http_code',
+        'statusCode',
+    ]) {
+        const value = errorObj[key];
+        if (typeof value === 'number') {
+            return value;
+        }
+    }
+    return undefined;
+}

package/esm/telemetry/index.js

@@ -0,0 +1,8 @@
+/*
+ * 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.
+ */
+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';

package/esm/telemetry/otel.js

@@ -0,0 +1,62 @@
+/*
+ * 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 { context, propagation, SpanKind, SpanStatusCode, trace, } from '@opentelemetry/api';
+import { CHARGEBEE_SDK_NAME, } from './types.js';
+const tracer = trace.getTracer(CHARGEBEE_SDK_NAME);
+function toRecordedException(error) {
+    var _a;
+    const exception = new Error(error.message);
+    exception.name = (_a = error.chargebeeErrorCode) !== null && _a !== void 0 ? _a : 'ChargebeeAPIError';
+    return exception;
+}
+/**
+ * Ready-to-use OpenTelemetry adapter for the Chargebee SDK.
+ *
+ * Each SDK request becomes a CLIENT span attached to the active OpenTelemetry
+ * context (or a root span when none is active), and the W3C trace context is
+ * propagated to Chargebee so the trace continues server-side.
+ *
+ * Exporting (endpoint, service name, credentials) is configured by your own
+ * OpenTelemetry runtime via the standard `OTEL_*` environment variables — this
+ * adapter only uses the globally registered tracer from `@opentelemetry/api`.
+ *
+ * `@opentelemetry/api` is an optional peer dependency; install it to use this
+ * adapter. A default-exported, ready-to-use instance is provided.
+ */
+export class OtelTelemetryAdapter {
+    onRequestStart(ctx, requestHeaders) {
+        // startSpan adopts the active context's span as parent (or starts a root span if none).
+        const span = tracer.startSpan(ctx.spanName, {
+            kind: SpanKind.CLIENT,
+            attributes: ctx.startAttributes,
+        });
+        // Propagate W3C trace context to Chargebee so the trace continues server-side.
+        propagation.inject(trace.setSpan(context.active(), span), requestHeaders);
+        return span;
+    }
+    onRequestEnd(span, result) {
+        if (!span) {
+            return;
+        }
+        for (const [key, value] of Object.entries(result.endAttributes)) {
+            span.setAttribute(key, value);
+        }
+        if (result.error) {
+            span.recordException(toRecordedException(result.error));
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: result.error.message,
+            });
+        }
+        else {
+            span.setStatus({ code: SpanStatusCode.OK });
+        }
+        span.end();
+    }
+}
+const otelDefaultAdapter = new OtelTelemetryAdapter();
+export default otelDefaultAdapter;

package/esm/telemetry/types.js

@@ -0,0 +1,44 @@
+/*
+ * 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 identifier recorded on telemetry spans. */
+export const CHARGEBEE_SDK_NAME = 'chargebee-node';
+/** Standard span name prefix: chargebee.{resource}.{operation} */
+export const TELEMETRY_SPAN_NAME_PREFIX = 'chargebee';
+/**
+ * OTel HTTP semantic-convention prefix for request-header attributes:
+ * `http.request.header.<lowercased-name>` with string[] values.
+ */
+export const HTTP_REQUEST_HEADER_ATTRIBUTE_PREFIX = 'http.request.header.';
+/**
+ * Request headers whose (lowercased) name starts with this prefix are captured as span
+ * attributes. Using a prefix instead of a fixed list means any future `chargebee-*` header
+ * is picked up automatically, with no SDK upgrade required.
+ */
+export const CHARGEBEE_TELEMETRY_HEADER_PREFIX = 'chargebee-';
+/**
+ * Headers under this sub-prefix carry end-user PII (origin IP, email, device) and are
+ * excluded from spans by default. Chargebee namespaces such headers under
+ * `chargebee-request-origin-*`, so future PII headers stay excluded automatically.
+ */
+export const CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX = 'chargebee-request-origin-';
+/** Span attribute keys — shared across Chargebee SDKs. */
+export const TelemetryAttributeKeys = {
+    URL_FULL: 'url.full',
+    HTTP_REQUEST_METHOD: 'http.request.method',
+    HTTP_RESPONSE_STATUS_CODE: 'http.response.status_code',
+    SERVER_ADDRESS: 'server.address',
+    ERROR_TYPE: 'error.type',
+    CHARGEBEE_SITE: 'chargebee.site',
+    CHARGEBEE_API_VERSION: 'chargebee.api_version',
+    CHARGEBEE_RESOURCE: 'chargebee.resource',
+    CHARGEBEE_OPERATION: 'chargebee.operation',
+    CHARGEBEE_SDK_NAME: 'chargebee.sdk.name',
+    CHARGEBEE_SDK_VERSION: 'chargebee.sdk.version',
+    CHARGEBEE_ERROR_CODE: 'chargebee.error.code',
+    CHARGEBEE_ERROR_TYPE: 'chargebee.error.type',
+    CHARGEBEE_ERROR_PARAM: 'chargebee.error.param',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chargebee",
-  "version": "3.27.0",
+  "version": "3.28.0",
   "description": "A library for integrating with Chargebee.",
   "scripts": {
     "prepack": "npm install && npm run build",
@@ -34,33 +34,49 @@
     }
   ],
   "exports": {
-    "types": "./types/index.d.ts",
-    "browser": {
-      "import": "./esm/chargebee.esm.worker.js",
-      "require": "./cjs/chargebee.cjs.worker.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "browser": {
+        "import": "./esm/chargebee.esm.worker.js",
+        "require": "./cjs/chargebee.cjs.worker.js"
+      },
+      "worker": {
+        "import": "./esm/chargebee.esm.worker.js",
+        "require": "./cjs/chargebee.cjs.worker.js"
+      },
+      "workerd": {
+        "import": "./esm/chargebee.esm.worker.js",
+        "require": "./cjs/chargebee.cjs.worker.js"
+      },
+      "deno": {
+        "import": "./esm/chargebee.esm.worker.js",
+        "require": "./cjs/chargebee.cjs.worker.js"
+      },
+      "bun": {
+        "import": "./esm/chargebee.esm.worker.js",
+        "require": "./cjs/chargebee.cjs.worker.js"
+      },
+      "default": {
+        "import": "./esm/chargebee.esm.js",
+        "require": "./cjs/chargebee.cjs.js"
+      }
     },
-    "worker": {
-      "import": "./esm/chargebee.esm.worker.js",
-      "require": "./cjs/chargebee.cjs.worker.js"
-    },
-    "workerd": {
-      "import": "./esm/chargebee.esm.worker.js",
-      "require": "./cjs/chargebee.cjs.worker.js"
-    },
-    "deno": {
-      "import": "./esm/chargebee.esm.worker.js",
-      "require": "./cjs/chargebee.cjs.worker.js"
-    },
-    "bun": {
-      "import": "./esm/chargebee.esm.worker.js",
-      "require": "./cjs/chargebee.cjs.worker.js"
-    },
-    "default": {
-      "import": "./esm/chargebee.esm.js",
-      "require": "./cjs/chargebee.cjs.js"
+    "./telemetry/otel": {
+      "types": "./types/telemetry/otel.d.ts",
+      "import": "./esm/telemetry/otel.js",
+      "require": "./cjs/telemetry/otel.js"
+    }
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
     "@types/chai": "^4.3.5",
     "@types/mocha": "^10.0.10",
     "@types/node": "20.12.0",

package/types/index.d.ts

@@ -169,6 +169,11 @@ declare module 'chargebee' {
      */
     httpClient?: HttpClientInterface;
 
+    /**
+     * @telemetryAdapter optional telemetry adapter for observability (e.g. OpenTelemetry)
+     */
+    telemetryAdapter?: TelemetryAdapter;
+
     /**
      * @enableValidation When true, every request's parameters are validated against each endpoint's generated Zod schema before the HTTP request is sent. Violations throw `ChargebeeZodValidationError` with structured Zod issues. Calls with no params argument are validated as `{}`. Required resource ids in the URL path are still checked separately.
      */
@@ -179,6 +184,70 @@ declare module 'chargebee' {
     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';
+    readonly HTTP_RESPONSE_STATUS_CODE: 'http.response.status_code';
+    readonly SERVER_ADDRESS: 'server.address';
+    readonly ERROR_TYPE: 'error.type';
+    readonly CHARGEBEE_SITE: 'chargebee.site';
+    readonly CHARGEBEE_API_VERSION: 'chargebee.api_version';
+    readonly CHARGEBEE_RESOURCE: 'chargebee.resource';
+    readonly CHARGEBEE_OPERATION: 'chargebee.operation';
+    readonly CHARGEBEE_SDK_NAME: 'chargebee.sdk.name';
+    readonly CHARGEBEE_SDK_VERSION: 'chargebee.sdk.version';
+    readonly CHARGEBEE_ERROR_CODE: 'chargebee.error.code';
+    readonly CHARGEBEE_ERROR_TYPE: 'chargebee.error.type';
+    readonly CHARGEBEE_ERROR_PARAM: 'chargebee.error.param';
+  };
+
+  export type RequestTelemetryContext = {
+    spanName: string;
+    resource: string;
+    operation: string;
+    httpMethod: string;
+    httpUrl: string;
+    serverAddress: string;
+    chargebeeSite: string;
+    chargebeeApiVersion: 'v1' | 'v2';
+    sdkName: string;
+    sdkVersion: string;
+    /**
+     * Prebuilt span attributes — pass these to your tracer. Captured `chargebee-*` request
+     * headers appear as `http.request.header.<name>` with string[] values per OTel semconv.
+     */
+    startAttributes: Record<string, string | string[]>;
+  };
+
+  export type RequestTelemetryError = {
+    message: string;
+    chargebeeErrorCode?: string;
+    chargebeeApiErrorType?: string;
+    chargebeeErrorParam?: string;
+  };
+
+  export type RequestTelemetryResult = {
+    httpStatusCode: number;
+    durationMs: number;
+    error?: RequestTelemetryError;
+    /** Prebuilt span attributes — pass these to your tracer. */
+    endAttributes: Record<string, string | number>;
+  };
+
+  /**
+   * Optional telemetry adapter. Implement as a class or plain object — the SDK
+   * keeps it by reference (never deep-cloned). Wire OpenTelemetry or other tools here.
+   */
+  export interface TelemetryAdapter<THandle = RequestTelemetryHandle> {
+    onRequestStart(
+      context: RequestTelemetryContext,
+      requestHeaders: Record<string, string | number>,
+    ): THandle | void;
+    onRequestEnd(handle: THandle | void, result: RequestTelemetryResult): void;
+  }
+
   export type RetryConfig = {
     /**
      * @enabled whether to enable retry logic, default value is false

package/types/telemetry/otel.d.ts

@@ -0,0 +1,22 @@
+declare module 'chargebee/telemetry/otel' {
+  import type {
+    RequestTelemetryContext,
+    RequestTelemetryResult,
+    TelemetryAdapter,
+  } from 'chargebee';
+  /**
+   * Ready-to-use OpenTelemetry adapter for the Chargebee SDK. Exporting is
+   * configured by your own OpenTelemetry runtime via the standard `OTEL_*`
+   * environment variables; this adapter only uses the globally registered
+   * tracer from `@opentelemetry/api` (an optional peer dependency).
+   */
+  export class OtelTelemetryAdapter implements TelemetryAdapter {
+    onRequestStart(
+      ctx: RequestTelemetryContext,
+      requestHeaders: Record<string, string | number>,
+    ): unknown;
+    onRequestEnd(handle: unknown, result: RequestTelemetryResult): void;
+  }
+  const otelDefaultAdapter: OtelTelemetryAdapter;
+  export default otelDefaultAdapter;
+}