modix-mx
modix-mx is a library to handle files which are conform to the Modix MX Transfer Format.
System Requirements
- Node.js >= 8.0.0
Installation
Install the library globally, so you can use it from every directory:
npm install @modix/modix-mx -g
CLI Usage
You can now use modix-mx by via the following command:
modix-mx --help
/modixZF/mxapi
, you have to provide the whole URL to the modixZF
folder. In this case, it makes sense to set an alias:
[request->DEPTH_ZERO_SELF_SIGNED_CERT] self signed certificate
error may occur. In this case, the NODE_TLS_REJECT_UNAUTHORIZED
environment variable must be set to 0
. On MacOS/Linux you may do that with export NODE_TLS_REJECT_UNAUTHORIZED=0
.
modix-mx set-alias testing.modix.de/branches/testslot1/modixZF/public testing
Set your access token:
modix-mx set-access-token content.modix.net eyBBY2Nlc3MgVG9rZW4gfQ ...
# or by using an alias
modix-mx set-access-token myAlias eyBBY2Nlc3MgVG9rZW4gfQ ...
List information about all stored servers
modix-mx list-servers
Remove a stored server (including all settings and related aliases)
modix-mx remove-server content.modix.net
# or by using an alias
modix-mx remove-server myAlias
Download MX file:
modix-mx download content.modix.net 15392 --dir test --verbose
# or by using an alias
modix-mx download myAlias 15392 --dir test --verbose
Set access token and download MX file:
modix-mx download content.modix.net 15392 --access-token eyBBY2Nlc3MgVG9rZW4gfQ ...
# or by using an alias
modix-mx download myAlias 15392 --access-token eyBBY2Nlc3MgVG9rZW4gfQ ...
Upload MX file:
modix-mx upload content.modix.net 15392 --dir test --pattern '**/*.tpl' --verbose
# or by using an alias
modix-mx upload myAlias 15392 --dir test --pattern '**/*.tpl' --verbose
# with additional options set
modix-mx upload myAlias 15392 --dir test --pattern '**/*.tpl' --build --cleanup --dry-run --verbose
Patterns can be specified by using the micromatch matching features.
Using VSCode-URI instead of separate parameters
The Modix CMS provides an URL to open a specific account in the Modix MX Exchange extension in VSCode.
Instead of calling modix-mx
with separate arguments for server, account ID and access token, you can also simply provide this VSCode-URL, like:
modix-mx download "vscode://modix.mx-explorer/add-account?kid=15453&server=content.modix.net&label=My%20Account&token=eyBBY2Nlc3MgVG9rZW4gfQ ..." --dir test
Make sure to wrap the URL in quotes ("), otherwise your terminal software may misinterprete the ampersand (&) in the URL.
Programmatical usage
const modixMX = require('modix-mx');
Verbose mode
// Activate verbose mode (uses console.log)
modixMX.verbose();
// Activate verbose mode using custom function
modixMX.verbose((message) => alert(`modix-mx: ${message}`));
// Deactivate verbose mode
modixMX.verbose(false);
Write an access token to the config
const server = 'content.modix.de';
const accessToken = 'eyBBY2Nlc3MgVG9rZW4gfQ ...';
try {
await modixMX.setAccessToken(server, accessToken);
}
catch (error) {
console.error(error);
}
Set an alias and write an access token to the config
const server = 'content.modix.de';
const alias = 'Main server';
const accessToken = 'eyBBY2Nlc3MgVG9rZW4gfQ ...';
try {
await modixMX.setAlias(server, alias);
await modixMX.setAccessToken(alias, accessToken);
}
catch (error) {
console.error(error);
}
Retrieve a list of stored servers
console.log(modixMX.getServers());
Remove a server from the configuration
const server = 'content.modix.de';
try {
await modixMX.removeServer(server);
}
catch (error) {
console.error(error);
}
Determinate if an access token is valid
This includes a check that it's not expired.
const accessToken = 'eyBBY2Nlc3MgVG9rZW4gfQ ...';
if (await modixMX.isValidAccessToken(accessToken)) {
console.log('The access token is still valid');
}
else {
console.log('The access token is invalid');
}
Determinate if the stored access token for a server is valid
This includes a check that it's not expired.
const server = 'content.modix.de';
if (await modixMX.hasValidAccessToken(server)) {
console.log('The access token for the given server is still valid');
}
else {
console.log('The access token for the given server is invalid');
}
Get expiration information for the stored access token for a server
const server = 'content.modix.de';
const accessTokenExpiration = await modixMX.getAccessTokenExpiration(server);
const now = Date.now();
if (accessTokenExpiration === -1) {
console.log('The given server is invalid');
}
if (accessTokenExpiration === -2) {
console.log('No access token set for the given server');
}
if (accessTokenExpiration === -3) {
console.log('The access token format is invalid');
}
else if (accessTokenExpiration <= now) {
console.log(`The given access token is expired before ${modixMX.getStringFromMilliseconds(accessTokenExpiration - now)}`);
}
else { // accessTokenExpiration > now
console.log(`The given access token will be expire in ${modixMX.getStringFromMilliseconds(accessTokenExpiration - now)}`);
}
Download a file from the server
try {
const response = await modixMX.download({
server: 'content.modix.de',
accountId: 12345,
accessToken: 'eyBBY2Nlc3MgVG9rZW4gfQ ...',
basePath: './project'
});
console.log(JSON.stringify(response, null, '\t'));
}
catch (error) {
console.error(error);
}
Upload a file to the server
try {
const response = await modixMX.upload({
server: 'content.modix.de',
accountId: 12345,
accessToken: 'eyBBY2Nlc3MgVG9rZW4gfQ ...',
basePath: './project',
pattern: '**/*.tpl'
});
console.log(JSON.stringify(response, null, '\t'));
}
catch (error) {
console.error(error);
}
Upload a file to the server with additional options
try {
const response = await modixMX.upload({
server: 'content.modix.de',
accountId: 12345,
accessToken: 'eyBBY2Nlc3MgVG9rZW4gfQ ...',
basePath: './project',
pattern: '**/*.tpl',
build: false,
cleanup: true,
dryRun: true
});
console.log(JSON.stringify(response, null, '\t'));
}
catch (error) {
console.error(error);
}
Parse URL
console.log(await modixMX.getParsedURL('https://content.modix.de'));
// -> { "host": "content.modix.de", "path": "/modixZF" }
console.log(await modixMX.getParsedURL('https://content.modix.de/modixZF/mxapi'));
// -> { "host": "content.modix.de", "path": "/modixZF" }
console.log(await modixMX.getParsedURL('https://testing7.modix.de/branches/testslot11/modixZF/public/'));
// -> { "host": "testing7.modix.de", "path": "/branches/testslot11/modixZF/public" }
REST interface documentation
To open the API documentation HTML page on localhost port 8080:
modix-mx doc
To open the API documentation HTML page on any other port:
modix-mx doc --port 1337
Run E2E tests
npm run test
E2E tests are separated into different test suites. If a test fails in one suite, all further suites will be skipped.
To prevent this, use the following command:
npm run test -- --no-skip
To keep the terminal output shorter and show only failing tests:
npm run test -- --no-skip --errors-only
With custom configuration
To test using a local server, create a file test.custom.js
, and add a configuration to it:
module.exports = {
// Ignore invalid and self-signed certificates (otherwise "[request->DEPTH_ZERO_SELF_SIGNED_CERT] self signed certificate" may be thrown)
ignoreInsecure: true,
// The time in milliseconds, the test function should wait for the server response
requestTimeout: 120000,
// The server to test with
server: 'content.modix.net',
// The account to test download functionality
downloadAccountId: 15454,
// The account to test upload functionality
uploadAccountId: 15455
};