ctvault

Motivation

ctvault is a wrapper library around the commercetools JavaScript SDK that aims to reduce boilerplate code and provide consolidated credential management for multiple commercetools projects.

Configuration

There are multiple methods for configuring the type of data store that ctvault uses. Set the CT_VAULT_CONFIG environment variable to point to the location of the JSON configuration file.

commercetools project

This configuration will point ctvault at a commercetools project, specifying a namespace and key for a custom object to store the managed credentials.

key	value
type	"ctp"
namespace	the custom object namespace
key	the custom object key
credentials	the commercetools project credentials

Google Firebase

You can also use a Google Firebase store to serve as the credentials vault.

key	value
type	"firebase"
credentials	path to a JSON file with GCP service account credentials (see https://cloud.google.com/iam/docs/service-accounts)
collection	name of the firebase collection that holds the managed credentials

Local file

Alternatively you can store them in a file on the local file system.

key	value
type	"file"
credentials	an array of commercetools project credentials

commercetools Credentials

Here is the structure for the commercetools credentials objects. These are both to specify the project (if you are pointing at a commercetools project) and to specify the set of managed credentials.

key	value
oauth_url	URL to the commercetools auth server
api_url	URL to the commercetools API gateway
project	project key
client_id	API client ID
client_secret	API client secret

Usage

ctvault acts as a simple broker. You can query it by using two methods:

getClient(projectKey)

This will return a CTP client configured to talk to the project specified in projectKey if the credentials exist in the vault. If they are not, an exception is thrown to that effect.

If projectKey is empty, ctvault will attempt to find it in the command line argument --project.

getClients

This will return an array of CTP clients for which the vault contains credentials.

Both of these methods are asynchronous, so be sure to use await.

Using a ctvault CTP client (ctclient)

ctclient uses a syntax based on api-request-builder (https://commercetools.github.io/nodejs/sdk/api/apiRequestBuilder.html), specifically the Declarative Usage section (https://commercetools.github.io/nodejs/sdk/api/apiRequestBuilder.html#declarative-usage).

Largely syntactic sugar, it provides an interface for you to use standard CRUD operations (create, get, update, remove), but also adds the following verbs:

process: This will use the processRequest method from api-request-builder to page through objects.

ensure: Given a source object, will try to find an object with the matching key. If it is not found, it will be created with the source object as the template. Use when building data models.

Examples

Query for a tax category with a key of standard:

const argv = require('yargs').argv
let ct = await require('ctvault').getClient(argv.project)

let standardTaxCategory = await ct.taxCategories.get({ key: 'standard' })

Make sure order type foo is defined:

const argv = require('yargs').argv
let ct = await require('ctvault').getClient(argv.project)

let fooOrderType = {
    key: 'FooOrderType',
    name: { 
        en: 'Foo'
    },
    resourceTypeIds: ['order'],
    description: { 
        en: 'Foo'
    },
    fieldDefinitions: [{
        name: 'bar',
        type: { name: 'String' },
        required: false,
        label: { 
            en: 'Bar'
        }
    }]
}

let foo = await ct.types.ensure(fooOrderType)