A simple implementation of WooCommerce's Software Add-on API.
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
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", "[email protected]");
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", "[email protected]", true);
WARNING: It is not recommended to allow insecure connections. Alternatively, the SSL certificate needs to be checked and renewed as necessary.
These methods are available for use after the class WooCommerceSoftwareAddOn is initialized.
This can be used to replace the email used for the API requests.
| Argument | Description |
|---|---|
| Email to replace the current default email set during initialization |
Return: void
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 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>
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>
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>
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>
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>
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>
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", "[email protected]");
(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);
})();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.
| Argument | Description |
|---|---|
| hostname | Wordpress site hosting the WooCommerce Software Add-on plugin |
| product_id | Product ID designated for the software license |
| 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", "[email protected]", "examplesecretkey").then(value => {
if (value.success) {
return value.output.key;
} else {
return null;
}
});
console.log(licenseKey);
})();| Argument | Description |
|---|---|
| hostname | Wordpress site hosting the WooCommerce Software Add-on plugin |
| product_id | Product ID designated for the software license |
| 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",
"[email protected]", "example-license-key", "example-timestamp").then(value => {
return (value.success);
});
console.log(activated);
})();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 |
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 |
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
- 100: The email provided is invalid
- 101: No matching license key exists
- 102: The purchase matching this product is not complete
- 100: An undisclosed error occurred
- 100: The email provided is invalid
- 101: No matching license key exists
- 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
- 100: The email provided is invalid
- 101: No matching license key exists
- 104: No matching instance exists
- 105: Non matching product_id and secret_key provided
- 105: Invalid security key