chargebee 2.21.0 → 2.22.1

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+### v2.22.0 (2023-05-16)
+* * *
+
+#### New Feature:
+* Added setIdempotencyKey("UUID") utility to pass **Idempotency key** along with request headers to allow a safe retry of POST requests.
+* Added isIdempotencyReplayed utility to differentiate between original and replayed requests.
+* Added headers utility to fetch the response headers.
+
+
 ### v2.21.0 (2023-04-28)
 * * *
 

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2011-2022 ChargeBee, Inc.
+Copyright (c) 2011-2023 ChargeBee, Inc.
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

package/README.md

@@ -3,32 +3,207 @@
 [![npm](https://img.shields.io/npm/v/chargebee.svg?maxAge=2592000)](https://www.npmjs.com/package/chargebee)
 [![npm](https://img.shields.io/npm/dt/chargebee.svg?maxAge=2592000)](https://www.npmjs.com/package/chargebee)
 
-This is the [node.js](http://nodejs.org/) Library for integrating with Chargebee. Sign up for a Chargebee account [here](https://www.chargebee.com).
+This is the [node.js](http://nodejs.org/) library for integrating with Chargebee. Sign up for a Chargebee account [here](https://www.chargebee.com).
 
-Chargebee now supports two API versions - [V1](https://apidocs.chargebee.com/docs/api/v1) and [V2](https://apidocs.chargebee.com/docs/api), of which V2 is the latest release and all future developments will happen in V2. This library is for <b>API version V2</b>. If you’re looking for V1, head to [chargebee-v1 branch](https://github.com/chargebee/chargebee-node/tree/chargebee-v1).
+> **Note**
+> Chargebee now supports two API versions - [V1](https://apidocs.chargebee.com/docs/api/v1) and [V2](https://apidocs.chargebee.com/docs/api), of which V2 is the latest release and all future developments will happen in V2. This library is for <b>API version V2</b>. If you’re looking for V1, head to [chargebee-v1 branch](https://github.com/chargebee/chargebee-node/tree/chargebee-v1).
 
-### Processing Webhooks - API Version Check
+## Requirements
 
-An attribute, <b>api_version</b>, 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.
+Node 0.6 or higher.
 
 ## Installation
 
-Install the latest version 2.x.x of the library with the following commands:
-
-	$ npm install chargebee@">=2 <3"
+Install the latest version of the library with:
+
+```sh
+npm install chargebee
+# or
+yarn add chargebee
+# or
+pnpm install 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.
+
+```js
+var chargebee = require('chargebee');
+
+chargebee.configure({
+  site: 'YOUR_SITE_NAME',
+  api_key: 'YOUR_API_KEY',
+});
+```
+
+### Using Async / Await
+
+```js
+try {
+  const result = await chargebee.customer
+    .create({
+      email: 'john@test.com',
+      // other params
+    })
+    .request();
+    // access customer as result.response.customer;
+} catch (err) {
+  // handle error
+}
+```
+
+### Using Promises
+
+```js
+chargebee.customer
+  .create({
+    email: 'john@test.com',
+    // other params
+  })
+  .request()
+  .then((result) => {
+    // handle result
+    // access customer as result.response.customer;
+  })
+  .catch((err) => {
+    // handle error
+  });
+```
+
+### Using callbacks
+
+```js
+chargebee.customer
+  .create({
+    email: 'john@test.com',
+    // other params
+  })
+  .request(function (error, result) {
+    if (error) {
+      // handle error
+    } else {
+      // handle result
+     // access customer as result.customer;
+    }
+  });
+```
+
+### Accessing the response object
+
+The response object returned by the `request()` method is generic response wrapper. You need to access the resource from it. For example,
+
+- To access customer object.
+
+```js
+const result = await chargebee.customer.create({ email: 'john@test.com' }).request();
+console.log(result.response.customer);
+```
+
+Other resources can be accessed by the same approach. For subscription, it will be `result.subscription`
+
+- To access list response.
+
+```js
+const result = await chargebee.subscription
+  .list({
+    /* params */
+  })
+  .request();
+
+// A list of Subscription objects
+console.log(result.response.list.map((obj) => obj.subscription));
+```
+
+**Note**
+
+If you have a `result` (or children further down the line) and are unsure what properties are available, you can use `Object.keys` to get a list of available accessor properties. Using `Object.keys` in the previous example would yield
+
+```js
+// ['list', 'next_offset']
+console.log(Object.keys(result.response));
+// ['1', '2', '3'], e.g. `result.list` is an array with 3 entries
+console.log(Object.keys(result.response.list));
+// ['activated_at', 'base_currency_code', ...]
+// ['activated_at', 'base_currency_code', ...]
+// ['activated_at', 'base_currency_code', ...]
+// Which means we've reached the bottom and should have all the information available from this request
+console.log(result.response.list.map((obj) => obj.subscription));
+```
+
+#### Using filters in the List API
+
+For pagination: `offset` is the parameter that is being used. The value used for this parameter must be the value returned for `next_offset` parameter in the previous API call.
+
+```js
+const fetchCustomers = async (offset) => {
+    const result = await chargebee.customer.list({
+      limit: 2,
+      offset: offset,
+      first_name: { is: 'John' },
+    }).request();
+
+    return {
+      customers: result.response.list.map((obj) => obj.customer),
+      next_offset: result.response.next_offset,
+    };
+  };
+
+  const getCustomers = async () => {
+    const { customers, next_offset } = await fetchCustomers();
+    console.log('Offset:', next_offset); // Print the offset value
+
+    // Fetching next set of customers
+    await fetchCustomers(next_offset);
+  };
+
+  getCustomers().catch((err) => {
+    console.log(err);
+  });
+```
+
+#### Using custom headers and custom fields:
+
+```js
+const result = await chargebee.customer
+.create({ email: 'john@test.com', cf_host_url: 'http://xyz.com' }) //Add custom field in payload
+.headers({
+  'chargebee-event-email': 'all-disabled', // To disable webhooks
+  'chargebee-request-origin-ip': '192.168.1.2',
+})
+.setIdempotencyKey("safeKey")
+.request();
+
+const customer = result.response.customer;
+console.log(customer.cf_host_url);
+```
+
+### Create an idempotent request
+
+[Idempotency keys](https://apidocs.chargebee.com/docs/api/idempotency?prod_cat_ver=2) are passed along with request headers to allow a safe retry of POST requests.
+
+```js
+const result = await chargebee.customer
+    .create({ email: 'john@test.com' })
+    .setIdempotencyKey("safeKey")
+    .request();
+const customer = result.response.customer;
+console.log(result.headers); // Retrieves response headers
+console.log(result.isIdempotencyReplayed); // Retrieves idempotency replayed header
+```
+
+`isIdempotencyReplayed()` method can be accessed to differentiate between original and replayed requests.
 
-Then require the library as:
+### Processing Webhooks - API Version Check
 
-	var chargebee = require('chargebee');
+An attribute, <b>api_version</b>, 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.
 
 ## Documentation
 
-The full documentation can be found on the chargebee site here:
+The full documentation can be found on the Chargebee API Docs:
 
 [https://apidocs.chargebee.com/docs/api?lang=node](https://apidocs.chargebee.com/docs/api?lang=node)
 
-
 ## License
 
-See the LICENSE file.
-
+See the [LICENSE](./LICENSE) file.

package/lib/chargebee.js

@@ -3,12 +3,15 @@ var ChargeBee = {};
 var Q = require("q");
 var os = require("os");
 var Buffer = require("safer-buffer").Buffer;
+const IDEMPOTENCY_HEADER = "chargebee-idempotency-key";
+const IDEMPOTENCY_REPLAY_HEADER = 'chargebee-idempotency-replayed';
+
 ChargeBee._env = {
     protocol: 'https',
     hostSuffix: '.chargebee.com',
     apiPath: '/api/v2',
     timeout: 80000,
-    clientVersion: 'v2.21.0',
+    clientVersion: 'v2.22.1',
     port: 443,
     timemachineWaitInMillis: 3000,
     exportWaitInMillis: 3000
@@ -24,6 +27,12 @@ ChargeBee.updateRequestTimeoutInMillis = function(timeout) {
 
 ChargeBee._endpoints = require('./resources/api_endpoints.js');
 
+RequestWrapper.prototype.setIdempotencyKey = function(idempotencyKey) {
+    this.headers({[IDEMPOTENCY_HEADER]: idempotencyKey});
+    return this;
+};
+
+
 
 ChargeBee._waitToProcessComplete = function(retrieveHandling){
     if(typeof retrieveHandling == 'undefined' || !ChargeBee._util.isFunction(retrieveHandling)){
@@ -131,6 +140,7 @@ RequestWrapper.prototype.headers = function(headers) {
     return this;
 };
 
+
 RequestWrapper.prototype.request = function(callBack, envOptions) {
     var env = {};
     var jsonConstructor =  {}.constructor;
@@ -147,11 +157,11 @@ RequestWrapper.prototype.request = function(callBack, envOptions) {
     if (typeof callBack !== 'undefined' && !ChargeBee._util.isFunction(callBack)) {
         throw new Error('The callback parameter passed is incorrect.');
     }
-    function callBackWrapper(err, response) {
+    function callBackWrapper(err, response, headers, isIdempotencyReplayed) {
         if (err) {
             deferred.reject(err);
         } else {
-            deferred.resolve(response);
+            deferred.resolve({'response': response, 'headers': headers, 'isIdempotencyReplayed' : isIdempotencyReplayed});
         }
     };
     ChargeBee._core.makeApiRequest(env, callBackWrapper, this.apiCall.httpMethod, this.apiCall.urlPrefix, this.apiCall.urlSuffix, urlIdParam, params, this.httpHeaders, this.apiCall.isListReq);
@@ -224,9 +234,13 @@ ChargeBee._core = (function() {
                 }
                 if (res.statusCode < 200 || res.statusCode > 299) {
                     response.http_status_code = res.statusCode;
-                    callBack(response, null);
+                    callBack(response, null, res.headers);
                 } else {
-                    callBack(null, response);
+                    isIdempotencyReplayed = false
+                    if(typeof res.headers[IDEMPOTENCY_REPLAY_HEADER] !== 'undefined' && res.headers[IDEMPOTENCY_REPLAY_HEADER] !== ''){
+                        isIdempotencyReplayed = res.headers[IDEMPOTENCY_REPLAY_HEADER];
+                    }
+                    callBack(null, response, res.headers, isIdempotencyReplayed);
                 }
             });
         };
@@ -460,7 +474,7 @@ ChargeBee._util = (function() {
         if (callback) {
             deferred.promise.then(function(res) {
                 setTimeout(function() {
-                    callback(null, res);
+                    callback(null, res.response, res.headers, isIdempotencyReplayed);
                 }, 0);
             }, function(err) {
                 setTimeout(function() {

package/package.json

@@ -1,6 +1,6 @@
 {
    "name":"chargebee",
-   "version":"2.21.0",
+   "version":"2.22.1",
    "description":"A library for integrating with ChargeBee.",
    "keywords":[
       "payments",