woocommerce-software-add-on

WooCommerce Software Add-on NodeJS module

A simple implementation of WooCommerce's Software Add-on API.

Installation

Install module by running the command:

npm install woocommerce-software-add-on

or from the GitHub repository:

npm install git+https://github.com/cruzjuniel/woocommerce-software-add-on.git

Initialization

The module exports the class WooCommerceSoftwareAddOn. Add this class from the module to your javascript project using:

const { WooCommerceSoftwareAddOn } = require("woocommerce-software-add-on");

Create a new instance of the class by specifying the hostname and product ID:

let licenseManager = new WooCommerceSoftwareAddOn("example.com", "example");

Optionally, an email can also be specified:

let licenseManager = new WooCommerceSoftwareAddOn("example.com", "example", "[e-mail]");

Additional option to allow insecure connections is also provided and is disabled by default. This can be used to handle errors from expired SSL certificates.

let licenseManager = new WooCommerceSoftwareAddOn("example.com", "example", "[e-mail]", true);

WARNING: It is not recommended to allow insecure connections. Alternatively, the SSL certificate needs to be checked and renewed as necessary.

WooCommerceSoftwareAddOn Methods

These methods are available for use after the class WooCommerceSoftwareAddOn is initialized.

setEmail

This can be used to replace the email used for the API requests.

Argument	Description
email	Email to replace the current default email set during initialization

Return: void

generateKey

This can be used to generate a new keys. This is based on the generate_key API call as documented here.

Argument	Description
secret_key	Secret product key for use with the API
email	Email to generate the license key for, default: email set during initialization
order_id	Optional order ID to link the license key to, default: null
version	Optional version information of the software license, default: null
key_prefix	Optional prefix for generated license keys, default: null
activations	Amount of activations possible per license key, default: 1

Return: Promise<WooCommerceSoftwareResult>

activateLicense

This can be used to activate a single instance of a license key. This is based on the activation API call as documented here.

Argument	Description
license_key	License key to activate for the software
instance	Pass to activate existing uses (previously deactivated), default: null, ignored
platform	Optional platform information that can be used to identify unique systems, default: null

If platform is not provided (null), the default platform is a string containing information from os.hostname(), os.platform(), os.cpus() and machine ID as generated by node-machine-id

Return: Promise<WooCommerceSoftwareResult>

resetLicense

This can be used to reset/deactivate all activations of a license key. This is based on the activation_reset API call as documented here.

Argument	Description
license_key	License key to reset all activations

Return: Promise<WooCommerceSoftwareResult>

deactivateLicense

This can be used to deactivate a single activations of a license key. This is based on the deactivation API call as documented here.

Argument	Description
license_key	License key to deactivate single activation
instance	Pass to deactivate existing uses (previously activated), default: null, ignored
activation_id	Pass to only deactivate a single use, default: null, ignored

If both instance and license_key are null (or not provided), this will deactivate the oldest activation of the license key.

Return: Promise<WooCommerceSoftwareResult>

checkLicense

This can be used to check the activation status of a license key. This is based on the check API call as documented here.

Argument	Description
license_key	License key to validate a single activation
timestamp	Pass to check the timestamp of the activation, default: 0, ignored
platform	Pass to check the platform used during activation,.default: null, auto-generated info

Return: Promise<WooCommerceSoftwareResult>

getActivations

This can be used to list the existing activations of a license key. This is based on the check API call as documented here.

Argument	Description
license_key	License key to check for activations

Return: Promise<Array<WooCommerceSoftwareActivations> | null>

Usage Example

Activating License and Checking Activation

const { WooCommerceSoftwareAddOn } = require("woocommerce-software-add-on");

let licenseKey = "example-license-key";
let licenseManager = new WooCommerceSoftwareAddOn("example.com", "example_product_id", "[e-mail]");

(async () => {

    // Activate License
    let instance = await licenseManager.activateLicense(licenseKey).then(async (value) => {
        // Initial attempt
        if (value.success) {
            return value.output.instance;
        } else if (value.output.code == 103) {
            // Deactivate oldest activation
            await licenseManager.deactivateLicense(licenseKey);
            // Retry activation
            return await licenseManager.activateLicense(licenseKey).then(value => {
                return value.output.instance;
            });
        } else {
            return null;
        }
    });
    // Save 'instance' for License Checking
    console.log(instance);

    // Check if the license key is activated with the saved instance
    let activated = await licenseManager.checkLicense(licenseKey, instance).then(async (value) => {
        return value.success;
    });
    console.log(activated);

})();

Additional Methods

Some methods are also exported so it is usable without the need to create a WooCommerceSoftwareAddOn instance. For these methods, hostname, product id and email are added as required arguments/parameters.

generateKey

Argument	Description
hostname	Wordpress site hosting the WooCommerce Software Add-on plugin
product_id	Product ID designated for the software license
email	Email address to validate the check activations of
secret_key	Secret product key for use with the API
order_id	Optional order ID to link the license key to, default: null
version	Optional version information of the software license, default: null
key_prefix	Optional prefix for generated license keys, default: null
activations	Amount of activations possible per license key, default: 1
allowInsecure	Indicates whether to allow insecure connections (expired SSL certificates)

Return: Promise<WooCommerceSoftwareResult>

Example

const { generateKey } = require("woocommerce-software-add-on");

(async () => {

    let licenseKey = await generateKey("example.com", "example_product_id", "[e-mail]", "examplesecretkey").then(value => {
        if (value.success) {
            return value.output.key;
        } else {
            return null;
        }
    });
    console.log(licenseKey);

})();

checkLicense

Argument	Description
hostname	Wordpress site hosting the WooCommerce Software Add-on plugin
product_id	Product ID designated for the software license
email	Email address to validate the check activations of
license_key	License key to validate a single activation
timestamp	Pass to check the timestamp of the activation, default: 0, ignored
platform	Pass to check the platform used during activation,.default: null, auto-generated info
allowInsecure	Indicates whether to allow insecure connections (expired SSL certificates)

Return: Promise<WooCommerceSoftwareResult>

Example

const { checkLicense } = require("woocommerce-software-add-on");

(async () => {
    
    let activated = await checkLicense("example.com", "example_product_id",
        "[e-mail]", "example-license-key", "example-timestamp").then(value => {
        return (value.success);
    });
    console.log(activated);

})();

Interface Types

WooCommerceSoftwareResult

Most methods/functions from the module can returns a Promise of this type. This interface type is an object with the following keys:

Key	Description
success	Indicates whethere the operation was a success or not
code	HTTP code or API error code
headers	HTTP headers response received to the API request
output	Actual JSON response to the API request, if API call received a proper API response
error	Error that occurred during the API request or as indicated by the API response

WooCommerceSoftwareActivations

The getActivations returns a promise of an array of this type when used. This type is also contained withing the response to checkLicense. This type is an object with the following keys:

Key	Description
activation_id	ID associated with the activation
instance	Usually a timestamp of the activation, or as indicated during activation
activation_platform	As indicated during activation
activation_time	Actual JSON response to the API request if API call received a proper API response

Known Error Codes

These error codes are found in the plugin source code. For more information about each, please contact the WooCommerce Software Add-on plugin developers or check their documentation.

• 100: Invalid Request
• 100: An undisclosed error occurred
• 100: The email provided is invalid
• 100: The following required information is missing
• 101: No matching license key exists
• 101: Invalid License Key
• 102: Software has been deactivated
• 102: The purchase matching this product is not complete
• 103: Remaining activations is equal to zero
• 103: Exceeded maximum number of activations
• 104: Could not activate key
• 104: No matching instance exists
• 104: Invalid Instance ID
• 105: Non matching product_id and secret_key provided
• 105: Invalid security key
• 403: Forbidden

Check Request

• 100: The email provided is invalid
• 101: No matching license key exists
• 102: The purchase matching this product is not complete

Activation Reset Request

• 100: An undisclosed error occurred
• 100: The email provided is invalid
• 101: No matching license key exists

Activation Request

• 100: The email provided is invalid
• 101: No matching license key exists
• 102: The purchase matching this product is not complete
• 103: Remaining activations is equal to zero
• 104: Could not activate key

Deactivation Request

• 100: The email provided is invalid
• 101: No matching license key exists
• 104: No matching instance exists

Generate Key Request

• 105: Non matching product_id and secret_key provided
• 105: Invalid security key