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

:warning: For different commands you have to provide a server name. For servers where the modix-mx API not located under /modixZF/mxapi, you have to provide the whole URL to the modixZF folder. In this case, it makes sense to set an alias:

:warning: On a local machine with self signed certificate, a [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

:warning: This is only available if you clone the Git repository. The E2E tests are part of the npm package.

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
};