chargebee 3.27.0 → 3.28.1

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,12 +138,7 @@ export class RequestWrapper {
                     ? JSON.stringify(requestParams)
                     : encodeParams(requestParams, undefined, undefined, undefined, jsonKeys);
             }
-            const requestHeaders = Object.assign({}, this.httpHeaders);
-            if (data && data.length) {
-                extend(true, requestHeaders, {
-                    'Content-Length': Buffer.byteLength(data, 'utf8'),
-                });
-            }
+            const requestHeaders = Object.assign(Object.assign({}, this.httpHeaders), telemetryHeaders);
             const contentType = this.apiCall.isJsonRequest
                 ? 'application/json;charset=UTF-8'
                 : 'application/x-www-form-urlencoded; charset=utf-8';
@@ -114,8 +153,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 +215,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.1',
     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.1",
   "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;
+}