chargebee 3.26.0 → 3.28.0

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/cjs/validationLoader.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Lazy schema loader for opt-in Zod validation.
+ *
+ * Schemas are loaded on first use. Node.js automatically caches imported modules,
+ * so repeated imports of the same schema file are efficient.
+ *
+ * Each resource module lives at {@code schema/<resource_snake>.schema.ts}
+ * and exports one body schema per action.
+ *
+ * The body schema const name follows {@code ZodNamingStrategy.bodySchemaName} in sdk-generator:
+ * {@code {PascalAction}{PascalResource}BodySchema}
+ *
+ * Uses native dynamic import() - TypeScript transpiles appropriately for ESM/CJS targets.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSchema = getSchema;
+function toCamel(s) {
+    return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+function toPascal(s) {
+    const camel = toCamel(s);
+    return camel.charAt(0).toUpperCase() + camel.slice(1);
+}
+/** Matches ZodNamingStrategy.bodySchemaName() in sdk-generator. */
+function schemaConstName(resourceKey, actionName) {
+    return toPascal(actionName) + toPascal(resourceKey) + 'BodySchema';
+}
+/** camelCase resource key → snake_case module basename (e.g. virtualBankAccount → virtual_bank_account). */
+function resourceSchemaBasename(resourceKey) {
+    return resourceKey
+        .replace(/([A-Z])/g, '_$1')
+        .toLowerCase()
+        .replace(/^_/, '');
+}
+/**
+ * Load the Zod schema for a given resource + action.
+ * Returns null if no schema file exists for this combination.
+ *
+ * Node.js automatically caches the imported modules, so repeated calls
+ * for the same resource will reuse the cached module.
+ *
+ * TypeScript compiler handles module system differences:
+ * - ESM build: keeps await import() as-is
+ * - CJS build: transpiles to require() or Promise-based equivalent
+ */
+async function getSchema(resourceKey, actionName) {
+    var _a;
+    const base = resourceSchemaBasename(resourceKey);
+    const constName = schemaConstName(resourceKey, actionName);
+    try {
+        const mod = await Promise.resolve(`${`./schema/${base}.schema.js`}`).then(s => require(s));
+        const schema = (_a = mod[constName]) !== null && _a !== void 0 ? _a : null;
+        return schema;
+    }
+    catch (_b) {
+        return null;
+    }
+}

package/esm/RequestWrapper.js

@@ -1,6 +1,9 @@
 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';
+import { getSchema } from './validationLoader.js';
 export class RequestWrapper {
     constructor(args, apiCall, envArg) {
         this.getRequest = () => {
@@ -20,6 +23,17 @@ export class RequestWrapper {
         }
         return idParam;
     }
+    /**
+     * Validate parameters against the action's Zod schema when enableValidation is true.
+     * Query params are validated as `params ?? {}`; body params are validated when `params` is non-null.
+     * Throws a descriptive error listing every validation violation.
+     */
+    static _validateParams(params, schema, actionName) {
+        const result = schema.safeParse(params);
+        if (!result.success) {
+            throw new ChargebeeZodValidationError(actionName, result.error);
+        }
+    }
     static parseRetryAfter(retryAfter) {
         if (!retryAfter)
             return null;
@@ -29,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;
@@ -39,6 +72,20 @@ export class RequestWrapper {
             ? this.args[1]
             : this.args[0];
         let headers = this.apiCall.hasIdInUrl ? this.args[2] : this.args[1];
+        // Lazy-load Zod schema when enableValidation is true
+        if (env.enableValidation &&
+            this.apiCall.resourceKey &&
+            this.apiCall.actionName) {
+            const schema = await getSchema(this.apiCall.resourceKey, this.apiCall.actionName);
+            if (schema) {
+                if (this.apiCall.httpMethod === 'GET') {
+                    RequestWrapper._validateParams(params !== null && params !== void 0 ? params : {}, schema, this.apiCall.methodName);
+                }
+                else if (params != null) {
+                    RequestWrapper._validateParams(params, schema, this.apiCall.methodName);
+                }
+            }
+        }
         Object.assign(this.httpHeaders, headers);
         if (this.apiCall.httpMethod === 'POST' &&
             !this.httpHeaders['chargebee-idempotency-key'] &&
@@ -47,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') {
@@ -67,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'),
@@ -87,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),
@@ -150,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,3 +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/chargebee.esm.worker.js

@@ -7,3 +7,4 @@ 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 { ChargebeeZodValidationError } from './chargebeeZodValidationError.js';

package/esm/chargebeeZodValidationError.js

@@ -0,0 +1,14 @@
+export class ChargebeeZodValidationError extends Error {
+    constructor(actionName, zodError) {
+        var _a;
+        const messages = zodError.issues
+            .map((e) => `${e.path.join('.')}: ${e.message}`)
+            .join('; ');
+        super(`[Chargebee] Validation failed for '${actionName}': ${messages}`);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = 'ChargebeeZodValidationError';
+        this.actionName = actionName;
+        this.zodError = zodError;
+        (_a = Error.captureStackTrace) === null || _a === void 0 ? void 0 : _a.call(Error, this, this.constructor);
+    }
+}

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],
@@ -93,6 +109,11 @@ export const CreateChargebee = (httpClient) => {
                         jsonKeys: metaArr[7],
                         options: metaArr[8],
                     };
+                    if (this._env.enableValidation) {
+                        // Store resource and action for lazy schema loading in RequestWrapper
+                        apiCall.resourceKey = res;
+                        apiCall.actionName = metaArr[0];
+                    }
                     this[res][apiCall.methodName] = this._createApiFunc(apiCall, this._env);
                 }
             }

package/esm/environment.js

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