chargebee 3.20.0 → 3.21.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+### v3.21.1 (2026-02-20)
+* * * 
+
+### Core Changes: 
+
+- Added new core utility method. 
+
+### v3.21.0 (2026-02-11)
+* * * 
+
+### 🚀 New Feature
+
+* Added webhook handler support. Refer to the [README.md](https://github.com/chargebee/chargebee-node/blob/master/README.md#handle-webhooks) for more details.
+
 ### v3.20.0 (2026-02-06)
 * * *
 ### New Attributes:

package/README.md

@@ -20,6 +20,16 @@ If you're upgrading from an older version of [`chargebee-typescript`](https://ww
 
 Node.js 18 or higher.
 
+## Runtime Support
+
+This SDK supports multiple JavaScript runtimes:
+
+- **Node.js** 18+
+- **Deno**
+- **Bun**
+- **Cloudflare Workers**
+- **Edge Runtimes** (e.g., Vercel Edge, Netlify Edge Functions)
+
 ## Installation
 
 Install the library with npm:
@@ -37,6 +47,16 @@ With yarn:
 yarn add chargebee
 ```
 
+With bun:
+```sh
+bun add chargebee
+```
+
+With deno:
+```sh
+deno add npm:chargebee
+```
+
 ## Usage
 
 The package needs to be configured with your site's API key, which is available under Configure Chargebee Section. Refer [here](https://www.chargebee.com/docs/2.0/api_keys.html) for more details.
@@ -63,6 +83,34 @@ const chargebee = new Chargebee({
 });
 ```
 
+### Using Deno:
+
+```typescript
+import Chargebee from "npm:chargebee";
+
+const chargebee = new Chargebee({
+  site: "{{site}}",
+  apiKey: "{{api-key}}",
+});
+
+const response = await chargebee.customer.list();
+console.log(response);
+```
+
+### Using Bun:
+
+```typescript
+import Chargebee from "chargebee";
+
+const chargebee = new Chargebee({
+  site: "{{site}}",
+  apiKey: "{{api-key}}",
+});
+
+const response = await chargebee.customer.list();
+console.log(response);
+```
+
 ### Using Async / Await
 
 ```typescript
@@ -148,6 +196,259 @@ 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 instance `webhooks` handler
+
+The simplest way to handle webhooks is using the `webhooks` property on your initialized Chargebee client:
+
+```typescript
+import express from 'express';
+import Chargebee, {
+  WebhookEventType,
+  AuthenticationError,
+  PayloadValidationError,
+  PayloadParseError,
+} from 'chargebee';
+
+const chargebee = new Chargebee({
+  site: '{{site}}',
+  apiKey: '{{api-key}}',
+});
+
+const app = express();
+app.use(express.json());
+
+// ⚠️ Register listeners once at startup, not inside request handlers
+chargebee.webhooks.on(WebhookEventType.SubscriptionCreated, async ({ event, response }) => {
+  console.log(`Subscription created: ${event.id}`);
+  const subscription = event.content.subscription;
+  console.log(`Customer: ${subscription.customer_id}`);
+  response?.status(200).send('OK');
+});
+
+chargebee.webhooks.on('error', (error, { response }) => {
+  if (error instanceof AuthenticationError) {
+    response?.status(401).send('Unauthorized');
+  } else if (error instanceof PayloadValidationError || error instanceof PayloadParseError) {
+    response?.status(400).send('Bad Request');
+  } else {
+    console.error('Webhook error:', error.message);
+    response?.status(500).send('Internal Server Error');
+  }
+});
+
+app.post('/chargebee/webhooks', async (req, res) => {
+  await chargebee.webhooks.handle({
+    body: req.body,
+    headers: req.headers,
+    request: req,
+    response: res,
+  });
+});
+
+app.listen(8080);
+```
+
+**Auto-configured Basic Auth:** The `webhooks` handler 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.
+
+#### Creating typed webhook handlers
+
+For more control or multiple webhook endpoints, use `chargebee.webhooks.createHandler()`:
+
+```typescript
+import express, { Request, Response } from 'express';
+import Chargebee, {
+  WebhookEventType,
+  basicAuthValidator,
+  AuthenticationError,
+  PayloadValidationError,
+  PayloadParseError,
+} from 'chargebee';
+
+const chargebee = new Chargebee({
+  site: '{{site}}',
+  apiKey: '{{api-key}}',
+});
+
+const app = express();
+app.use(express.json());
+
+// Create a typed handler for Express
+const handler = chargebee.webhooks.createHandler<Request, Response>();
+
+// Optional: Add request validator (e.g., Basic Auth)
+handler.requestValidator = basicAuthValidator((username, password) => {
+  return username === 'admin' && password === 'secret';
+});
+
+// ⚠️ Register event listeners once at startup, not inside request handlers
+handler.on(WebhookEventType.SubscriptionCreated, async ({ event, response }) => {
+  console.log(`Subscription created: ${event.id}`);
+  const subscription = event.content.subscription;
+  console.log(`Customer: ${subscription.customer_id}`);
+  console.log(`Plan: ${subscription.plan_id}`);
+  response?.status(200).send('OK');
+});
+
+handler.on(WebhookEventType.PaymentSucceeded, async ({ event, response }) => {
+  console.log(`Payment succeeded: ${event.id}`);
+  const transaction = event.content.transaction;
+  const customer = event.content.customer;
+  console.log(`Amount: ${transaction.amount}, Customer: ${customer.email}`);
+  response?.status(200).send('OK');
+});
+
+handler.on('error', (error, { response }) => {
+  if (error instanceof AuthenticationError) {
+    response?.status(401).send('Unauthorized');
+  } else if (error instanceof PayloadValidationError || error instanceof PayloadParseError) {
+    response?.status(400).send('Bad Request');
+  } else {
+    console.error('Webhook error:', error.message);
+    response?.status(500).send('Internal Server Error');
+  }
+});
+
+app.post('/chargebee/webhooks', async (req, res) => {
+  await handler.handle({
+    body: req.body,
+    headers: req.headers,
+    request: req,
+    response: res,
+  });
+});
+
+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, WebhookEventType } 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 WebhookEventType.SubscriptionCreated: {
+        // Cast to specific event type for proper content typing
+        const typedEvent = event as WebhookEvent<WebhookEventType.SubscriptionCreated>;
+        const subscription = typedEvent.content.subscription;
+        console.log('Subscription created:', subscription.id);
+        break;
+      }
+
+      case WebhookEventType.PaymentSucceeded: {
+        const typedEvent = event as WebhookEvent<WebhookEventType.PaymentSucceeded>;
+        const transaction = typedEvent.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);
+```
+
+#### Responding to Webhooks
+
+> ⚠️ **Important:** Always send an HTTP response from your webhook handlers. If you don't respond with a 2xx status, Chargebee will retry the webhook, potentially causing duplicate processing.
+
+**Respond with 200** to acknowledge receipt:
+
+```typescript
+handler.on(WebhookEventType.SubscriptionCreated, async ({ event, response }) => {
+  await provisionAccess(event.content.subscription);
+  response?.status(200).json({ received: true });
+});
+```
+
+**Respond with 5xx** so Chargebee retries on failure:
+
+```typescript
+handler.on(WebhookEventType.PaymentSucceeded, async ({ event, response }) => {
+  try {
+    await recordPayment(event.content.transaction);
+    response?.status(200).send('OK');
+  } catch (err) {
+    response?.status(500).json({ error: 'Processing failed' });
+  }
+});
+```
+
+**Access request context** (headers, middleware data):
+
+```typescript
+handler.on(WebhookEventType.CustomerCreated, async ({ event, request, response }) => {
+  const tenantId = (request as any)?.tenant?.id;
+  await createCustomerForTenant(tenantId, event.content.customer);
+  response?.status(200).send('OK');
+});
+```
+
+#### Handling Unhandled Events and Errors
+
+The webhook handler provides specific error classes for different failure scenarios:
+
+- **`AuthenticationError`** - Authentication failed (missing/invalid credentials)
+- **`PayloadValidationError`** - Invalid webhook payload structure (missing required fields)
+- **`PayloadParseError`** - Failed to parse JSON body
+
+```typescript
+import {
+  AuthenticationError,
+  PayloadValidationError,
+  PayloadParseError,
+} from 'chargebee';
+
+// Handle events without registered listeners
+handler.on('unhandled_event', async ({ event, response }) => {
+  console.log(`Unhandled: ${event.event_type}`);
+  response?.status(200).send('OK');
+});
+
+// Handle errors with appropriate HTTP status codes
+handler.on('error', (error, { response }) => {
+  if (error instanceof AuthenticationError) {
+    console.error('Authentication failed:', error.message);
+    response?.status(401).send('Unauthorized');
+  } else if (error instanceof PayloadValidationError) {
+    console.error('Invalid payload:', error.message);
+    response?.status(400).send('Bad Request');
+  } else if (error instanceof PayloadParseError) {
+    console.error('Failed to parse JSON:', error.message);
+    response?.status(400).send('Bad Request');
+  } else {
+    console.error('Unknown error:', error.message);
+    response?.status(500).send('Internal Server Error');
+  }
+});
+```
+
 ### 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.
@@ -227,35 +528,15 @@ To improve type safety and gain better autocompletion when working with webhooks
 import Chargebee, { WebhookEventType, WebhookEvent } from "chargebee";
 
 const result = await chargebeeInstance.event.retrieve("{event-id}");
-const subscriptionActivatedEvent: WebhookEvent<typeof WebhookEventType.SubscriptionActivated> = result.event;
+const subscriptionActivatedEvent: WebhookEvent<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);
-  }
-}
-```
-
 #### 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 `WebhookEventType` 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,19 @@
 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 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 utilities
+module.exports.WebhookEventType = handler_js_1.WebhookEventType;
+module.exports.WebhookContentType = handler_js_1.WebhookContentType;
+module.exports.basicAuthValidator = auth_js_1.basicAuthValidator;
+// Export webhook error classes
+module.exports.WebhookError = handler_js_1.WebhookError;
+module.exports.WebhookAuthenticationError = handler_js_1.WebhookAuthenticationError;
+module.exports.WebhookPayloadValidationError = handler_js_1.WebhookPayloadValidationError;
+module.exports.WebhookPayloadParseError = handler_js_1.WebhookPayloadParseError;

package/cjs/createChargebee.js

@@ -6,6 +6,7 @@ const environment_js_1 = require("./environment.js");
 const api_endpoints_js_1 = require("./resources/api_endpoints.js");
 const util_js_1 = require("./util.js");
 const asyncApiSupport_js_1 = require("./asyncApiSupport.js");
+const handler_js_1 = require("./resources/webhook/handler.js");
 const CreateChargebee = (httpClient) => {
     const Chargebee = function (conf) {
         this._env = Object.assign({}, environment_js_1.Environment);
@@ -15,6 +16,17 @@ const CreateChargebee = (httpClient) => {
             conf.httpClient != null ? conf.httpClient : httpClient;
         this._buildResources();
         this._endpoints = api_endpoints_js_1.Endpoints;
+        // Initialize webhooks handler with auto-configured Basic Auth (if env vars are set)
+        const handler = (0, handler_js_1.createDefaultHandler)();
+        this.__clientIdentifier = (serviceName) => {
+            (0, util_js_1.extend)(true, this._env, { userAgentSuffix: serviceName });
+        };
+        // Create webhooks namespace with handler methods + createHandler factory
+        this.webhooks = Object.assign(handler, {
+            createHandler(options) {
+                return new handler_js_1.WebhookHandler(options);
+            },
+        });
     };
     Chargebee.prototype = {
         _createApiFunc(apiCall, env) {

package/cjs/environment.js

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

package/cjs/resources/webhook/auth.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.basicAuthValidator = void 0;
+const errors_js_1 = require("./errors.js");
+/**
+ * Creates a Basic Auth validator for webhook requests.
+ * Parses the Authorization header and validates credentials.
+ *
+ * @param validateCredentials - Function to validate username/password.
+ *   Can be sync or async (e.g., for database lookups).
+ * @returns A request validator function for use with WebhookHandler
+ *
+ * @throws {WebhookAuthenticationError} When authentication fails
+ *
+ * @example
+ * // Simple sync validation
+ * const validator = basicAuthValidator((u, p) => u === 'admin' && p === 'secret');
+ *
+ * @example
+ * // Async validation (e.g., database lookup)
+ * const validator = basicAuthValidator(async (u, p) => {
+ *   const user = await db.findUser(u);
+ *   return user && await bcrypt.compare(p, user.passwordHash);
+ * });
+ */
+const basicAuthValidator = (validateCredentials) => {
+    return async (headers) => {
+        const authHeader = headers['authorization'] || headers['Authorization'];
+        if (!authHeader) {
+            throw new errors_js_1.WebhookAuthenticationError('Missing authorization header');
+        }
+        const authStr = Array.isArray(authHeader) ? authHeader[0] : authHeader;
+        if (!authStr) {
+            throw new errors_js_1.WebhookAuthenticationError('Invalid authorization header');
+        }
+        const parts = authStr.split(' ');
+        if (parts.length !== 2 || parts[0] !== 'Basic') {
+            throw new errors_js_1.WebhookAuthenticationError('Invalid authorization header format');
+        }
+        const decoded = Buffer.from(parts[1], 'base64').toString();
+        const separatorIndex = decoded.indexOf(':');
+        if (separatorIndex === -1) {
+            throw new errors_js_1.WebhookAuthenticationError('Invalid credentials format');
+        }
+        const username = decoded.substring(0, separatorIndex);
+        const password = decoded.substring(separatorIndex + 1);
+        const isValid = await validateCredentials(username, password);
+        if (!isValid) {
+            throw new errors_js_1.WebhookAuthenticationError('Invalid credentials');
+        }
+    };
+};
+exports.basicAuthValidator = basicAuthValidator;

package/cjs/resources/webhook/content.js

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

package/cjs/resources/webhook/errors.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookPayloadParseError = exports.WebhookPayloadValidationError = exports.WebhookAuthenticationError = exports.WebhookError = void 0;
+/**
+ * Base class for all webhook-related errors.
+ * Extends the standard Error class with proper stack trace support.
+ */
+class WebhookError extends Error {
+    constructor(message) {
+        var _a;
+        super(message);
+        this.name = 'WebhookError';
+        // Maintains proper stack trace for where error was thrown (V8 only)
+        (_a = Error.captureStackTrace) === null || _a === void 0 ? void 0 : _a.call(Error, this, this.constructor);
+    }
+}
+exports.WebhookError = WebhookError;
+/**
+ * Authentication error thrown when webhook request authentication fails.
+ *
+ * Common scenarios:
+ * - Missing authorization header
+ * - Invalid authorization header format
+ * - Invalid credentials
+ *
+ * Typically maps to HTTP 401 Unauthorized.
+ *
+ * @example
+ * ```typescript
+ * handler.on('error', (error, { response }) => {
+ *   if (error instanceof WebhookAuthenticationError) {
+ *     response?.status(401).json({ error: 'Unauthorized' });
+ *   }
+ * });
+ * ```
+ */
+class WebhookAuthenticationError extends WebhookError {
+    constructor(message) {
+        super(message);
+        this.name = 'WebhookAuthenticationError';
+    }
+}
+exports.WebhookAuthenticationError = WebhookAuthenticationError;
+/**
+ * Payload validation error thrown when the webhook payload structure is invalid.
+ *
+ * Common scenarios:
+ * - Missing required fields (event_type, id)
+ * - Invalid field types
+ * - Malformed payload structure
+ *
+ * Typically maps to HTTP 400 Bad Request.
+ *
+ * @example
+ * ```typescript
+ * handler.on('error', (error, { response }) => {
+ *   if (error instanceof WebhookPayloadValidationError) {
+ *     response?.status(400).json({ error: 'Bad Request', message: error.message });
+ *   }
+ * });
+ * ```
+ */
+class WebhookPayloadValidationError extends WebhookError {
+    constructor(message) {
+        super(message);
+        this.name = 'WebhookPayloadValidationError';
+    }
+}
+exports.WebhookPayloadValidationError = WebhookPayloadValidationError;
+/**
+ * JSON parsing error thrown when the webhook body cannot be parsed as JSON.
+ *
+ * Includes the raw body that failed to parse (if available) for debugging.
+ *
+ * Typically maps to HTTP 400 Bad Request.
+ *
+ * @example
+ * ```typescript
+ * handler.on('error', (error, { response }) => {
+ *   if (error instanceof WebhookPayloadParseError) {
+ *     console.error('Failed to parse:', error.rawBody);
+ *     response?.status(400).json({ error: 'Invalid JSON' });
+ *   }
+ * });
+ * ```
+ */
+class WebhookPayloadParseError extends WebhookError {
+    constructor(message, rawBody) {
+        super(message);
+        this.rawBody = rawBody;
+        this.name = 'WebhookPayloadParseError';
+    }
+}
+exports.WebhookPayloadParseError = WebhookPayloadParseError;

package/cjs/resources/webhook/eventType.js

@@ -234,6 +234,16 @@ var WebhookEventType;
     WebhookEventType["VoucherExpired"] = "voucher_expired";
 })(WebhookEventType || (exports.WebhookEventType = WebhookEventType = {}));
 /**
- * @deprecated Use WebhookEventType instead.
+ * @deprecated Renamed to `WebhookEventType` for clarity. Use `WebhookEventType` instead.
+ * This alias will be removed in the next major version.
+ *
+ * @example
+ * // Before (deprecated)
+ * import { WebhookContentType } from 'chargebee';
+ * if (event.event_type === WebhookContentType.SubscriptionCreated) { ... }
+ *
+ * // After (recommended)
+ * import { WebhookEventType } from 'chargebee';
+ * if (event.event_type === WebhookEventType.SubscriptionCreated) { ... }
  */
 exports.WebhookContentType = WebhookEventType;