Skip to main content
Version: v5.0

NPM package install

Overview#

This page describes the process of installing platform Javascript APIs from the Node Package Manager(NPM) repository.

The main steps in the process of installing the NPM package are as follows:

  1. Select NPM repository

  2. Create user access keys

  3. Configure environment

  4. Configure your NPM configuration file

  5. Add packages

Step 1: Select NPM repository#

Install the platform JavaScript APIs from the following Node NPM repository: npm.twinit.dev.

Important: To access this repository, you must use Production (not Sandbox) Passport Service User Access Keys. See next step for more information on access keys.

Step 2: Create user access keys#

To create your User Access Keys, see User Access Keys.

Important: Ensure you copy your keys when they display - keys are not accessible after you close the dialogue.

Note: Set your keys as environment variables for easier and more secure access and use.

Step 3: Configure environment#

Add your email and User Access Keys as environment variables on your system. Please note that these keys are generated from app.invicara.com, otherwise it will not work. The variables must be named as follows:

  • DTPLATFORM_KEY - Enter your platform access key
  • DTPLATFORM_SECRET - Enter your platform secret key
  • DTPLATFORM_SECRET_BASE64 - Enter your platform secret key with base64 encoding and no line breaks. You can generate the encoding with a command line script.
  • DTPLATFORM_EMAIL - The email address you registered on the platform

Set environment variables for macOS#

To set the environment variables on macOS edit ~/.bash_profile and set the variables listed below using appropriate values for your user.

DTPLATFORM_KEY=ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFDTPLATFORM_SECRET=aBcdefgHIJklMNOpQRStUVWxyZ0129456aBcdefgHIJklMNOpQRStUVWxyZ01294DTPLATFORM_SECRET_BASE64=$(echo -n "${DTPLATFORM_SECRET}" | base64)DTPLATFORM_EMAIL=user.name@domain.comexport DTPLATFORM_KEY DTPLATFORM_SECRET DTPLATFORM_SECRET_BASE64 DTPLATFORM_EMAIL

In macOS, this presumes you are using the default POSIX-based base64 utility installed and not the GNU-based utility.

If you are using the GNU coreutils on macOS, refer to the next section on Linux.

Set environment variables for Linux#

To set the environment variables on Linux edit your ~/.bash_profile and set the variables listed below, using appropriate values for your user.

Note: In Linux, this presumes you have the GNU base64 utility installed.

DTPLATFORM_KEY=ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFDTPLATFORM_SECRET=aBcdefgHIJklMNOpQRStUVWxyZ0129456aBcdefgHIJklMNOpQRStUVWxyZ01294DTPLATFORM_SECRET_BASE64=$(echo -n "${DTPLATFORM_SECRET}" | base64 -w0)DTPLATFORM_EMAIL=user.name@domain.comexport DTPLATFORM_KEY DTPLATFORM_SECRET DTPLATFORM_SECRET_BASE64 DTPLATFORM_EMAIL

Set environment variables for Windows#

For Windows, you need to encode the secret to base64 before you create the environment variable. There are several options to do this.

Using the node REPL, you can do the following (replace the example string with your secret):

C:\> node -e "console.log(Buffer.from('aBcdefgHIJklMNOpQRStUVWxyZ0129456aBcdefgHIJklMNOpQRStUVWxyZ01294').toString('base64'))"
YUJjZGVmZ0hJSmtsTU5PcFFSU3RVVld4eVowMTI5NDU2YUJjZGVmZ0hJSmtsTU5PcFFSU3RVVld4eVowMTI5NA==

In Powershell, you can do the following (replace the example string with your secret):

PS C:\ > [Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes('aBcdefgHIJklMNOpQRStUVWxyZ0129456aBcdefgHIJklMNOpQRStUVWxyZ01294')) 
YUJjZGVmZ0hJSmtsTU5PcFFSU3RVVld4eVowMTI5NDU2YUJjZGVmZ0hJSmtsTU5PcFFSU3RVVld4eVowMTI5NA==

Use the output for the value of DTPLATFORM_SECRET_BASE64.

To add the variables to your system, you need to add values in Control Panel. Do the following:

  1. Open System from the Control Panel.
  2. Click the Advanced system settings link.
  3. Click Environment Variables.
  4. In the User Variables section, click New and enter the name and value for the environment variable. Add the first variable and value. For each of the variables defined above using the output of the base64 command for DTPLATFORM_SECRET_BASE64.

Step 4: Configure your NPM configuration file#

To fetch the platform JavaScript packages, you will need to configure the .npmrc file.

This is an NPM configuration file which informs the npm install command how to match the repository short code (@invicara, @dtplatfrom) with the real URL to download libraries. It also specifies which operating system variables to look up when authenticating this URL.

You can set your user-level file at ~/.npmrc (or %USERPROFILE%\.npmrc on Windows) or at the project-level as simply .npmrc.

The platform specific contents of the file should look like this:

@dtplatform:registry=https://npm.twinit.dev/@invicara:registry=https://npm.twinit.dev///npm.twinit.dev/:username=${DTPLATFORM_KEY}//npm.twinit.dev/:_password=${DTPLATFORM_SECRET_BASE64}//npm.twinit.dev/:email=${DTPLATFORM_EMAIL}//npm.twinit.dev/:always-auth=true

Note: @invicara:registry=https://npm.twinit.dev/ is required as @invicara/ipa-core package is still hosted under @invicara registry.

Step 5: Add Packages#

Once the previous steps have been completed, the final step is to add packages to your project with the command below.

npm install @dtplatform/platform-api

Troubleshooting common NPM authentication errors#

If you encounter any errors, the most common NPM authentication errors are the error codes 401 or 403.

In general, these codes usually indicate the following:

  • Error Code 401: usually means that the NPM is trying to access a private package and your credentials are either missing or outdated.

  • Error code 403: usually means that a package version is forbidden by your security policy.

In the Platform environment, these errors will have two main root causes:

  • Root Cause 1: package-lock.json has wrong URLs
  • Root Cause 2: User does not have the .npmrc or the OS environments set up correctly

Root Cause 1: package-lock.json has wrong URLs#

In the scenario, the package-lock.json file will have the wrong URL. It could be a situation where it points to https://npm.pkg.github.com instead of https://npm.twinit.dev/.

Solution#

The solution is to remove package-lock.json and proceed with the install.

Root Cause 2: User does not have the .npmrc or the OS environments set up correctly#

In this scenario where the user does not have the .npmrc or the OS environments set up correctly, study the notes below to find a solution.

Note 1 - Check the user#

DTPLATFORM_KEY and DTPLATFORM_SECRET_BASE64 must be of the Production user (https://api.invicara.com/passportsvc/api/accounts), and not the Sandbox user (https://sandbox-api.invicara.com/passportsvc/api/accounts).

Note 2 - Check the encoding#

DTPLATFORM_SECRET_BASE64 is not the same as Secret, the BASE64 encoding is important.