chargebee 3.15.1 → 3.17.0-beta.1

package/CHANGELOG.md

@@ -1,3 +1,49 @@
+### v3.17.0-beta.1 (2025-12-10)
+
+### Enhancements
+* add webhook event handler to process chargebee-events.
+* deprecated `WebhookContentType` class, added `WebhookEventType` class.
+
+### v3.16.0 (2025-12-01)
+* * * 
+
+### New Resources: 
+* Einvoice has been added.
+* QuotedDeltaRamp has been added. 
+
+### New Attributes: 
+* line_items_next_offset has been added to CreditNote.
+* line_items_next_offset has been added to Invoice.
+* credit_lines has been added to SalesOrder.
+* billable_unit_price has been added to SalesOrder#LineItem.
+* billable_quantity has been added to SalesOrder#LineItem.
+* billable_amount has been added to SalesOrder#LineItem.
+
+### New Endpoint: 
+* move action has been added to ItemPrice.
+
+### New Parameters: 
+* line_items_limit has been added to CreditNote#RetrieveRequest.
+* line_items_offset has been added to CreditNote#RetrieveRequest.
+* line_items_limit has been added to Invoice#RetrieveRequest.
+* line_items_offset has been added to Invoice#RetrieveRequest.
+* item_tiers has been added to Estimate#GiftSubscriptionForItemsRequest.
+* unit_price has been added to Estimate#SubscriptionItems#GiftSubscriptionForItemsRequest.
+* unit_price_in_decimal has been added to Estimate#SubscriptionItems#GiftSubscriptionForItemsRequest.
+* item_tiers has been added to Gift#CreateForItemsRequest.
+* meta_data has been added to Gift#CreateForItemsRequest.
+* unit_price has been added to Gift#SubscriptionItems#CreateForItemsRequest.
+* unit_price_in_decimal has been added to Gift#SubscriptionItems#CreateForItemsRequest.
+* item_tiers has been added to HostedPage#CheckoutGiftForItemsRequest.
+* unit_price has been added to HostedPage#SubscriptionItems#CheckoutGiftForItemsRequest.
+* unit_price_in_decimal has been added to HostedPage#SubscriptionItems#CheckoutGiftForItemsRequest.
+* auto_select_local_currency has been added to PricingPageSession#CreateForNewSubscriptionRequest.
+
+### New Enums: 
+* EZIDEBIT has been added to GatewayEnum.
+* BUSINESS_RULE has been added to EntityTypeEnum.
+* RULESET has been added to EntityTypeEnum.
+
 ### v3.15.1 (2025-10-29)
 * * * 
 

package/README.md

@@ -148,6 +148,174 @@ const chargebeeSiteEU = new Chargebee({
 });
 ```
 
+### Handle webhooks
+
+Use the webhook handlers to parse and route webhook payloads from Chargebee with full TypeScript support.
+
+#### Quick Start: Using the default `webhook` instance
+
+The simplest way to handle webhooks is using the pre-configured `webhook` instance:
+
+```typescript
+import express from 'express';
+import { webhook, type WebhookEvent } from 'chargebee';
+
+const app = express();
+app.use(express.json());
+
+webhook.on('subscription_created', async (event: WebhookEvent) => {
+  console.log(`Subscription created: ${event.id}`);
+  const subscription = event.content.subscription;
+  console.log(`Customer: ${subscription.customer_id}`);
+});
+
+webhook.on('error', (err: Error) => {
+  console.error('Webhook error:', err.message);
+});
+
+app.post('/chargebee/webhooks', (req, res) => {
+  webhook.handle(req.body, req.headers);
+  res.status(200).send('OK');
+});
+
+app.listen(8080);
+```
+
+**Auto-configured Basic Auth:** The default `webhook` instance automatically configures Basic Auth validation if the following environment variables are set:
+
+- `CHARGEBEE_WEBHOOK_USERNAME` - The expected username
+- `CHARGEBEE_WEBHOOK_PASSWORD` - The expected password
+
+When both are present, incoming webhook requests will be validated against these credentials. If not set, no authentication is applied.
+
+#### Creating custom `WebhookHandler` instances
+
+For more control or multiple webhook endpoints, create your own instances:
+
+```typescript
+import express from 'express';
+import { WebhookHandler, basicAuthValidator } from 'chargebee';
+
+const app = express();
+app.use(express.json());
+
+const handler = new WebhookHandler();
+
+// Register event listeners using .on() - events are fully typed
+handler.on('subscription_created', async (event) => {
+  console.log(`Subscription created: ${event.id}`);
+  const subscription = event.content.subscription;
+  console.log(`Customer: ${subscription.customer_id}`);
+  console.log(`Plan: ${subscription.plan_id}`);
+});
+
+handler.on('payment_succeeded', async (event) => {
+  console.log(`Payment succeeded: ${event.id}`);
+  const transaction = event.content.transaction;
+  const customer = event.content.customer;
+  console.log(`Amount: ${transaction.amount}, Customer: ${customer.email}`);
+});
+
+// Optional: Add request validator (e.g., Basic Auth)
+handler.requestValidator = basicAuthValidator((username, password) => {
+  return username === 'admin' && password === 'secret';
+});
+
+app.post('/chargebee/webhooks', (req, res) => {
+  handler.handle(req.body, req.headers);
+  res.status(200).send('OK');
+});
+
+app.listen(8080);
+```
+
+#### Low-level: Parse and handle events manually
+
+For more control, you can parse webhook events manually:
+
+```typescript
+import express from 'express';
+import Chargebee, { type WebhookEvent } from 'chargebee';
+
+const app = express();
+app.use(express.json());
+
+app.post('/chargebee/webhooks', async (req, res) => {
+  try {
+    const event = req.body as WebhookEvent;
+    
+    switch (event.event_type) {
+      case 'subscription_created':
+        // Access event content with proper typing
+        const subscription = event.content.subscription;
+        console.log('Subscription created:', subscription.id);
+        break;
+        
+      case 'payment_succeeded':
+        const transaction = event.content.transaction;
+        console.log('Payment succeeded:', transaction.amount);
+        break;
+        
+      default:
+        console.log('Unhandled event type:', event.event_type);
+    }
+    
+    res.status(200).send('OK');
+  } catch (err) {
+    console.error('Error processing webhook:', err);
+    res.status(500).send('Error processing webhook');
+  }
+});
+
+app.listen(8080);
+```
+
+#### Handling Unhandled Events
+
+By default, if an incoming webhook event type is not recognized or you haven't registered a corresponding callback handler, the SDK provides flexible options to handle these scenarios:
+
+**Using the `unhandled_event` listener:**
+
+```typescript
+import { WebhookHandler } from 'chargebee';
+
+const handler = new WebhookHandler();
+
+handler.on('subscription_created', async (event) => {
+  // Handle subscription created
+});
+
+// Gracefully handle events without registered listeners
+handler.on('unhandled_event', async (event) => {
+  console.log(`Received unhandled event: ${event.event_type}`);
+  // Log for monitoring or store for later processing
+});
+```
+
+**Using the `error` listener for error handling:**
+
+If an error occurs during webhook processing (e.g., invalid JSON, validator failure), the SDK will emit an `error` event:
+
+```typescript
+const handler = new WebhookHandler();
+
+handler.on('subscription_created', async (event) => {
+  // Handle subscription created
+});
+
+// Catch any errors during webhook processing
+handler.on('error', (err) => {
+  console.error('Webhook processing error:', err);
+  // Log to monitoring service, alert team, etc.
+});
+```
+
+**Best Practices:**
+
+- Use `unhandled_event` listener to acknowledge unknown events (return 200 OK) and log them
+- Use `error` listener to catch and handle exceptions thrown during event processing
+- Both listeners help ensure your webhook endpoint remains stable even when new event types are introduced by Chargebee
+
 ### Processing Webhooks - API Version Check
 
 An attribute `api_version` is added to the [Event](https://apidocs.chargebee.com/docs/api/events) resource, which indicates the API version based on which the event content is structured. In your webhook servers, ensure this `api_version` is the same as the [API version](https://apidocs.chargebee.com/docs/api#versions) used by your webhook server's client library.

package/cjs/RequestWrapper.js

@@ -38,7 +38,7 @@ class RequestWrapper {
         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;
-        let params = this.apiCall.hasIdInUrl
+        const params = this.apiCall.hasIdInUrl
             ? this.args[1]
             : this.args[0];
         let headers = this.apiCall.hasIdInUrl ? this.args[2] : this.args[1];
@@ -52,20 +52,21 @@ class RequestWrapper {
         }
         const makeRequest = async (attempt = 0) => {
             let path = (0, util_js_1.getApiURL)(env, this.apiCall.urlPrefix, this.apiCall.urlSuffix, urlIdParam);
-            if (typeof params === 'undefined' || params === null) {
-                params = {};
+            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)(params))
-                    : (0, util_js_1.encodeParams)((0, util_js_1.serialize)(params));
+                    ? (0, util_js_1.encodeListParams)((0, util_js_1.serialize)(requestParams))
+                    : (0, util_js_1.encodeParams)((0, util_js_1.serialize)(requestParams));
                 path += '?' + queryParam;
-                params = {};
+                requestParams = {};
             }
             const jsonKeys = this.apiCall.jsonKeys;
             const data = this.apiCall.isJsonRequest
-                ? JSON.stringify(params)
-                : (0, util_js_1.encodeParams)(params, undefined, undefined, undefined, jsonKeys);
+                ? JSON.stringify(requestParams)
+                : (0, util_js_1.encodeParams)(requestParams, undefined, undefined, undefined, jsonKeys);
             const requestHeaders = Object.assign({}, this.httpHeaders);
             if (data.length) {
                 (0, util_js_1.extend)(true, requestHeaders, {

package/cjs/chargebee.cjs.js

@@ -2,8 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 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 handler_js_2 = require("./resources/webhook/handler.js");
+const auth_js_1 = require("./resources/webhook/auth.js");
 const httpClient = new FetchClient_js_1.FetchHttpClient();
 const Chargebee = (0, createChargebee_js_1.CreateChargebee)(httpClient);
 module.exports = Chargebee;
 module.exports.Chargebee = Chargebee;
 module.exports.default = Chargebee;
+// Export webhook modules
+module.exports.WebhookHandler = handler_js_1.WebhookHandler;
+module.exports.webhook = handler_js_2.default;
+module.exports.basicAuthValidator = auth_js_1.basicAuthValidator;

package/cjs/environment.js

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

package/cjs/resources/api_endpoints.js

@@ -1671,6 +1671,7 @@ exports.Endpoints = {
     ],
     paymentReferenceNumber: [],
     paymentSchedule: [],
+    einvoice: [],
     taxWithheld: [],
     creditNote: [
         [
@@ -2051,6 +2052,7 @@ exports.Endpoints = {
             null,
             false,
             {
+                meta_data: 0,
                 additional_information: 1,
             },
             {
@@ -2951,6 +2953,7 @@ exports.Endpoints = {
     quotedSubscription: [],
     quotedCharge: [],
     quotedRamp: [],
+    quotedDeltaRamp: [],
     billingConfiguration: [],
     quoteLineGroup: [],
     plan: [
@@ -3960,6 +3963,19 @@ exports.Endpoints = {
             {},
             {},
         ],
+        [
+            'moveItemPrice',
+            'POST',
+            '/item_prices',
+            '/move',
+            true,
+            null,
+            false,
+            {},
+            {
+                isIdempotent: true,
+            },
+        ],
     ],
     attachedItem: [
         [

package/cjs/resources/webhook/auth.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.basicAuthValidator = void 0;
+const basicAuthValidator = (validateCredentials) => {
+    return (headers) => {
+        const authHeader = headers['authorization'] || headers['Authorization'];
+        if (!authHeader) {
+            throw new Error('Invalid authorization header');
+        }
+        const authStr = Array.isArray(authHeader) ? authHeader[0] : authHeader;
+        if (!authStr) {
+            throw new Error('Invalid authorization header');
+        }
+        const parts = authStr.split(' ');
+        if (parts.length !== 2 || parts[0] !== 'Basic') {
+            throw new Error('Invalid authorization header');
+        }
+        const credentials = Buffer.from(parts[1], 'base64').toString().split(':');
+        if (credentials.length !== 2) {
+            throw new Error('Invalid credentials');
+        }
+        if (!validateCredentials(credentials[0], credentials[1])) {
+            throw new Error('Invalid credentials');
+        }
+    };
+};
+exports.basicAuthValidator = basicAuthValidator;

package/cjs/resources/webhook/content.js

@@ -0,0 +1,3 @@
+"use strict";
+///<reference path='../../../types/index.d.ts'/>
+Object.defineProperty(exports, "__esModule", { value: true });

package/cjs/resources/webhook/handler.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookHandler = void 0;
+const node_events_1 = require("node:events");
+const auth_js_1 = require("./auth.js");
+class WebhookHandler extends node_events_1.EventEmitter {
+    constructor() {
+        super({ captureRejections: true });
+    }
+    handle(body, headers) {
+        try {
+            if (this.requestValidator && headers) {
+                this.requestValidator(headers);
+            }
+            const event = typeof body === 'string' ? JSON.parse(body) : body;
+            const eventType = event.event_type;
+            if (this.listenerCount(eventType) > 0) {
+                this.emit(eventType, event);
+            }
+            else {
+                this.emit('unhandled_event', event);
+            }
+        }
+        catch (err) {
+            this.emit('error', err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+}
+exports.WebhookHandler = WebhookHandler;
+const webhook = new WebhookHandler();
+// Auto-configure basic auth if env vars are present
+const username = process.env.CHARGEBEE_WEBHOOK_USERNAME;
+const password = process.env.CHARGEBEE_WEBHOOK_PASSWORD;
+if (username && password) {
+    webhook.requestValidator = (0, auth_js_1.basicAuthValidator)((u, p) => u === username && p === password);
+}
+exports.default = webhook;

package/esm/RequestWrapper.js

@@ -35,7 +35,7 @@ export class RequestWrapper {
         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;
-        let params = this.apiCall.hasIdInUrl
+        const params = this.apiCall.hasIdInUrl
             ? this.args[1]
             : this.args[0];
         let headers = this.apiCall.hasIdInUrl ? this.args[2] : this.args[1];
@@ -49,20 +49,21 @@ export class RequestWrapper {
         }
         const makeRequest = async (attempt = 0) => {
             let path = getApiURL(env, this.apiCall.urlPrefix, this.apiCall.urlSuffix, urlIdParam);
-            if (typeof params === 'undefined' || params === null) {
-                params = {};
+            let requestParams = params;
+            if (typeof requestParams === 'undefined' || requestParams === null) {
+                requestParams = {};
             }
             if (this.apiCall.httpMethod === 'GET') {
                 const queryParam = this.apiCall.isListReq
-                    ? encodeListParams(serialize(params))
-                    : encodeParams(serialize(params));
+                    ? encodeListParams(serialize(requestParams))
+                    : encodeParams(serialize(requestParams));
                 path += '?' + queryParam;
-                params = {};
+                requestParams = {};
             }
             const jsonKeys = this.apiCall.jsonKeys;
             const data = this.apiCall.isJsonRequest
-                ? JSON.stringify(params)
-                : encodeParams(params, undefined, undefined, undefined, jsonKeys);
+                ? JSON.stringify(requestParams)
+                : encodeParams(requestParams, undefined, undefined, undefined, jsonKeys);
             const requestHeaders = Object.assign({}, this.httpHeaders);
             if (data.length) {
                 extend(true, requestHeaders, {

package/esm/chargebee.esm.js

@@ -3,3 +3,7 @@ import { FetchHttpClient } from './net/FetchClient.js';
 const httpClient = new FetchHttpClient();
 const Chargebee = CreateChargebee(httpClient);
 export default Chargebee;
+// Export webhook modules
+export { WebhookHandler } from './resources/webhook/handler.js';
+export { default as webhook } from './resources/webhook/handler.js';
+export { basicAuthValidator } from './resources/webhook/auth.js';

package/esm/environment.js

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

package/esm/resources/api_endpoints.js

@@ -1668,6 +1668,7 @@ export const Endpoints = {
     ],
     paymentReferenceNumber: [],
     paymentSchedule: [],
+    einvoice: [],
     taxWithheld: [],
     creditNote: [
         [
@@ -2048,6 +2049,7 @@ export const Endpoints = {
             null,
             false,
             {
+                meta_data: 0,
                 additional_information: 1,
             },
             {
@@ -2948,6 +2950,7 @@ export const Endpoints = {
     quotedSubscription: [],
     quotedCharge: [],
     quotedRamp: [],
+    quotedDeltaRamp: [],
     billingConfiguration: [],
     quoteLineGroup: [],
     plan: [
@@ -3957,6 +3960,19 @@ export const Endpoints = {
             {},
             {},
         ],
+        [
+            'moveItemPrice',
+            'POST',
+            '/item_prices',
+            '/move',
+            true,
+            null,
+            false,
+            {},
+            {
+                isIdempotent: true,
+            },
+        ],
     ],
     attachedItem: [
         [

package/esm/resources/webhook/auth.js

@@ -0,0 +1,23 @@
+export const basicAuthValidator = (validateCredentials) => {
+    return (headers) => {
+        const authHeader = headers['authorization'] || headers['Authorization'];
+        if (!authHeader) {
+            throw new Error('Invalid authorization header');
+        }
+        const authStr = Array.isArray(authHeader) ? authHeader[0] : authHeader;
+        if (!authStr) {
+            throw new Error('Invalid authorization header');
+        }
+        const parts = authStr.split(' ');
+        if (parts.length !== 2 || parts[0] !== 'Basic') {
+            throw new Error('Invalid authorization header');
+        }
+        const credentials = Buffer.from(parts[1], 'base64').toString().split(':');
+        if (credentials.length !== 2) {
+            throw new Error('Invalid credentials');
+        }
+        if (!validateCredentials(credentials[0], credentials[1])) {
+            throw new Error('Invalid credentials');
+        }
+    };
+};

package/esm/resources/webhook/content.js

@@ -0,0 +1,2 @@
+///<reference path='../../../types/index.d.ts'/>
+export {};

package/esm/resources/webhook/handler.js

@@ -0,0 +1,33 @@
+import { EventEmitter } from 'node:events';
+import { basicAuthValidator } from './auth.js';
+export class WebhookHandler extends EventEmitter {
+    constructor() {
+        super({ captureRejections: true });
+    }
+    handle(body, headers) {
+        try {
+            if (this.requestValidator && headers) {
+                this.requestValidator(headers);
+            }
+            const event = typeof body === 'string' ? JSON.parse(body) : body;
+            const eventType = event.event_type;
+            if (this.listenerCount(eventType) > 0) {
+                this.emit(eventType, event);
+            }
+            else {
+                this.emit('unhandled_event', event);
+            }
+        }
+        catch (err) {
+            this.emit('error', err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+}
+const webhook = new WebhookHandler();
+// Auto-configure basic auth if env vars are present
+const username = process.env.CHARGEBEE_WEBHOOK_USERNAME;
+const password = process.env.CHARGEBEE_WEBHOOK_PASSWORD;
+if (username && password) {
+    webhook.requestValidator = basicAuthValidator((u, p) => u === username && p === password);
+}
+export default webhook;

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "chargebee",
-  "version": "3.15.1",
+  "version": "3.17.0-beta.1",
   "description": "A library for integrating with Chargebee.",
   "scripts": {
     "prepack": "npm install && npm run build",
+    "test": "mocha -r ts-node/register 'test/**/*.test.ts'",
     "build": "npm run build-esm && npm run build-cjs",
     "build-esm": "rm -rf esm && mkdir -p esm && tsc -p tsconfig.esm.json && echo '{\"type\":\"module\"}' > esm/package.json",
     "build-cjs": "rm -rf cjs && mkdir -p cjs && tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > cjs/package.json",
@@ -32,8 +33,6 @@
       "url": "http://github.com/chargebee/chargebee-node/blob/master/LICENSE"
     }
   ],
-  "dependencies": {
-  },
   "exports": {
     "types": "./types/index.d.ts",
     "browser": {
@@ -62,13 +61,19 @@
     }
   },
   "devDependencies": {
-    "@types/node": "20.0.0",
+    "@types/chai": "^4.3.5",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "20.12.0",
+    "chai": "^4.3.7",
+    "mocha": "^10.2.0",
     "prettier": "^3.3.3",
-    "typescript": "^5.5.4"
+    "ts-node": "^10.9.1",
+    "typescript": "^5.5.4",
+    "undici-types": "^7.16.0"
   },
   "prettier": {
     "semi": true,
     "singleQuote": true,
     "parser": "typescript"
   }
-}
+}

package/types/core.d.ts

@@ -149,7 +149,9 @@ declare module 'chargebee' {
     | 'sales_order'
     | 'omnichannel_one_time_order'
     | 'omnichannel_one_time_order_item'
-    | 'usage_file';
+    | 'usage_file'
+    | 'business_rule'
+    | 'ruleset';
   type EventNameEnum = 'cancellation_page_loaded';
   type EventTypeEnum =
     | 'coupon_created'
@@ -425,6 +427,7 @@ declare module 'chargebee' {
     | 'paystack'
     | 'jp_morgan'
     | 'deutsche_bank'
+    | 'ezidebit'
     | 'gocardless'
     | 'not_applicable';
   type HierarchyOperationTypeEnum =