chargebee 3.16.2 → 3.17.0-beta.2

package/CHANGELOG.md

@@ -1,15 +1,14 @@
-### v3.16.2 (2025-12-17)
-* * * 
+### v3.17.0-beta.2 (2025-12-16)
 
-### Improvements:
-* `WebhookContentType` is now deprecated but still available for backward compatibility.
+### Enhancements
+* `WebhookEventType` is now a runtime enum that can be used for event type comparisons at runtime.
+* `WebhookEventType` and `WebhookContentType` are now exported from the main entry points.
 
-### v3.16.1 (2025-12-17)
-* * * 
+### v3.17.0-beta.1 (2025-12-10)
 
-### Improvements:
-* Renamed `WebhookContentType` to `WebhookEventType` for better clarity. `WebhookContentType` is now deprecated but still available for backward compatibility.
-* Added runtime export of `WebhookEventType` enum.
+### Enhancements
+* Add webhook event handler to process chargebee-events.
+* Deprecated `WebhookContentType` class, added `WebhookEventType` class.
 
 ### v3.16.0 (2025-12-01)
 * * * 

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.
@@ -224,38 +392,18 @@ To improve type safety and gain better autocompletion when working with webhooks
 #### Example
 
 ```ts
-import Chargebee, { WebhookEventType, WebhookEvent } from "chargebee";
+import Chargebee, { type WebhookContentType, WebhookEvent } from "chargebee";
 
 const result = await chargebeeInstance.event.retrieve("{event-id}");
-const subscriptionActivatedEvent: WebhookEvent<typeof WebhookEventType.SubscriptionActivated> = result.event;
-const subscription = subscriptionActivatedEvent.content.subscription;
-```
-
-You can also use `WebhookEventType` in switch statements for runtime event handling:
-
-```ts
-import { WebhookEventType, WebhookEvent } from "chargebee";
-
-function handleWebhook(event: WebhookEvent) {
-  switch (event.event_type) {
-    case WebhookEventType.SubscriptionCreated:
-      console.log("Subscription created:", event.content.subscription?.id);
-      break;
-    case WebhookEventType.PaymentSucceeded:
-      console.log("Payment succeeded:", event.content.transaction?.id);
-      break;
-    default:
-      console.log("Unhandled event:", event.event_type);
-  }
-}
+const subscripitonActivatedEvent: WebhookEvent<WebhookContentType.SubscriptionActivated> = result.event;
+const subscription = subscripitonActivatedEvent.content.subscription;
 ```
 
 #### Notes
 
 * `WebhookEvent<T>` provides type hinting for the event payload, making it easier to work with specific event structures.
-* Use `WebhookEventType` to specify the exact event type (e.g., `SubscriptionCreated`, `InvoiceGenerated`, etc.).
-* `WebhookEventType` is available at runtime, so you can use it in switch statements and comparisons.
-* `WebhookContentType` is deprecated but still available for backward compatibility.
+* Use the `WebhookContentType` to specify the exact event type (e.g., `SubscriptionCreated`, `InvoiceGenerated`, etc.).
+* This approach ensures you get proper IntelliSense and compile-time checks when accessing event fields.
 
 ### Custom HTTP Client
 

package/cjs/chargebee.cjs.js

@@ -2,12 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const createChargebee_js_1 = require("./createChargebee.js");
 const FetchClient_js_1 = require("./net/FetchClient.js");
-const eventType_js_1 = require("./resources/webhook/eventType.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 event types
-module.exports.WebhookEventType = eventType_js_1.WebhookEventType;
-module.exports.WebhookContentType = eventType_js_1.WebhookContentType;
+// Export webhook modules
+module.exports.WebhookHandler = handler_js_1.WebhookHandler;
+module.exports.WebhookEventType = handler_js_1.WebhookEventType;
+module.exports.WebhookContentType = handler_js_1.WebhookContentType;
+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.16.2',
+    clientVersion: '3.17.0-beta.2',
     port: DEFAULT_PORT,
     timemachineWaitInMillis: DEFAULT_TIME_MACHINE_WAIT,
     exportWaitInMillis: DEFAULT_EXPORT_WAIT,

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,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookHandler = exports.WebhookContentType = exports.WebhookEventType = void 0;
+const node_events_1 = require("node:events");
+const auth_js_1 = require("./auth.js");
+const eventType_js_1 = require("./eventType.js");
+Object.defineProperty(exports, "WebhookEventType", { enumerable: true, get: function () { return eventType_js_1.WebhookEventType; } });
+Object.defineProperty(exports, "WebhookContentType", { enumerable: true, get: function () { return eventType_js_1.WebhookContentType; } });
+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/chargebee.esm.js

@@ -3,5 +3,7 @@ import { FetchHttpClient } from './net/FetchClient.js';
 const httpClient = new FetchHttpClient();
 const Chargebee = CreateChargebee(httpClient);
 export default Chargebee;
-// Export webhook event types
-export { WebhookEventType, WebhookContentType, } from './resources/webhook/eventType.js';
+// Export webhook modules
+export { WebhookHandler, WebhookEventType, WebhookContentType, } 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.16.2',
+    clientVersion: '3.17.0-beta.2',
     port: DEFAULT_PORT,
     timemachineWaitInMillis: DEFAULT_TIME_MACHINE_WAIT,
     exportWaitInMillis: DEFAULT_EXPORT_WAIT,

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,35 @@
+import { EventEmitter } from 'node:events';
+import { basicAuthValidator } from './auth.js';
+import { WebhookEventType, WebhookContentType } from './eventType.js';
+export { WebhookEventType, WebhookContentType };
+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.16.2",
+  "version": "3.17.0-beta.2",
   "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/index.d.ts

@@ -250,4 +250,69 @@ declare module 'chargebee' {
     virtualBankAccount: VirtualBankAccount.VirtualBankAccountResource;
     webhookEndpoint: WebhookEndpoint.WebhookEndpointResource;
   }
+
+  // Webhook Handler
+  export type WebhookEventName = EventTypeEnum | 'unhandled_event';
+  export type WebhookEventTypeValue = `${WebhookEventType}`;
+  /** @deprecated Use WebhookEventTypeValue instead */
+  export type WebhookContentTypeValue = WebhookEventTypeValue;
+
+  export type WebhookEventListener<
+    T extends WebhookEventType = WebhookEventType,
+  > = (event: WebhookEvent<T>) => Promise<void> | void;
+  export type WebhookErrorListener = (error: Error) => Promise<void> | void;
+
+  // Helper type to map string literal to enum member
+  type StringToWebhookEventType<S extends WebhookEventTypeValue> = {
+    [K in WebhookEventType]: `${K}` extends S ? K : never;
+  }[WebhookEventType];
+
+  export class WebhookHandler {
+    on<T extends WebhookEventType>(
+      eventName: T,
+      listener: WebhookEventListener<T>,
+    ): this;
+    on<S extends WebhookEventTypeValue>(
+      eventName: S,
+      listener: WebhookEventListener<StringToWebhookEventType<S>>,
+    ): this;
+    on(eventName: 'unhandled_event', listener: WebhookEventListener): this;
+    on(eventName: 'error', listener: WebhookErrorListener): this;
+    once<T extends WebhookEventType>(
+      eventName: T,
+      listener: WebhookEventListener<T>,
+    ): this;
+    once<S extends WebhookEventTypeValue>(
+      eventName: S,
+      listener: WebhookEventListener<StringToWebhookEventType<S>>,
+    ): this;
+    once(eventName: 'unhandled_event', listener: WebhookEventListener): this;
+    once(eventName: 'error', listener: WebhookErrorListener): this;
+    off<T extends WebhookEventType>(
+      eventName: T,
+      listener: WebhookEventListener<T>,
+    ): this;
+    off<S extends WebhookEventTypeValue>(
+      eventName: S,
+      listener: WebhookEventListener<StringToWebhookEventType<S>>,
+    ): this;
+    off(eventName: 'unhandled_event', listener: WebhookEventListener): this;
+    off(eventName: 'error', listener: WebhookErrorListener): this;
+    handle(
+      body: string | object,
+      headers?: Record<string, string | string[] | undefined>,
+    ): void;
+    onError?: (error: any) => void;
+    requestValidator?: (
+      headers: Record<string, string | string[] | undefined>,
+    ) => void;
+  }
+
+  // Webhook Auth
+  export function basicAuthValidator(
+    validateCredentials: (username: string, password: string) => boolean,
+  ): (headers: Record<string, string | string[] | undefined>) => void;
+
+  // Default webhook handler instance
+  export const webhook: WebhookHandler;
 }

package/types/resources/WebhookEvent.d.ts

@@ -220,7 +220,6 @@ declare module 'chargebee' {
     PlanCreated = 'plan_created',
     PlanUpdated = 'plan_updated',
   }
-
   /**
    * @deprecated Use WebhookEventType instead.
    */