Customer's Canvas Hub CLI sample

The source code of the Customer's Canvas Hub CLI application is available at:

https://github.com/aurigma/cchub-cli

This is a command-line interface (CLI) application built with Node.js and TypeScript. It demonstrates how to construct Customer's Canvas designs programmatically through the Design Atoms SDK and submit them to the Customer's Canvas Hub backend.

The sample demonstrates the following tasks:

1. Authenticating with the Customer's Canvas Hub API using two authentication modes.
2. Constructing a design programmatically with the Design Atoms SDK.
3. Submitting the design to the Customer's Canvas Hub backend.

Technical details

The application is coded in Node.js 18+ and TypeScript. The build produces a single distributable CLI file, dist/cchub-cli.js, with all dependencies bundled. No node_modules folder is required at runtime.

Getting started

Set up your Customer's Canvas tenant

Before you start, prepare the data you need to use the API. Specify this data in the configuration, as described below.

1. Tenant ID. Log in to your Customer's Canvas tenant, go to Settings > Tenant, and copy the number from the ID field (see the Tenant Settings Topic).
2. Client ID/Secret. Register your application using the Client Credentials authentication scheme in Settings > External Apps (see the External Apps Settings Topic).
3. API Gateway. Depending on your hosting environment, it's https://api.customerscanvashub.com, https://api.eu.customerscanvashub.com, or https://api.au.customerscanvashub.com (see the API Gateway topic).

Clone repo

Clone the repository with the following command:

git clone https://github.com/aurigma/cchub-cli.git

Configure app

Create a .env file. There are two supported authentication modes, and you can configure either one or both.

Common settings:

CCHUB_BASEURL=https://customerscanvashub.com
CCHUB_TENANTID=xxx  # Tenant ID from the Settings > Tenant
CCHUB_TOKENREFRESTIMEBEFOREEXPIRATIONSEC=60
APP_LOGLEVEL=info

Option 1. Client Credentials

Use this mode for non-interactive CLI usage when the app can authenticate directly with client_id and client_secret.

CCHUB_CLIENT_CREDENTIALS_CLIENTID=xxxxxxxxxx
CCHUB_CLIENT_CREDENTIALS_CLIENTSECRET=xxxxxxxxxxx

Option 2. Interactive Authorization Code login

Use this mode when you want to sign in through the browser and let the CLI keep a local session.

CCHUB_AUTHORIZATION_CODE_CLIENTID=xxxxxxxxxx
CCHUB_AUTHORIZATION_CODE_SCOPE=Assets_full Private_assets_update Projects_full Storefronts_read Templates_full StorefrontUsers_full Tenants_read TenantUsers_read Artifacts_full RenderingJobs_full
CCHUB_AUTHORIZATION_CODE_CALLBACK_HOST=127.0.0.1
CCHUB_AUTHORIZATION_CODE_CALLBACK_PORT=53682
CCHUB_AUTHORIZATION_CODE_CALLBACK_PATH=/oauth/callback

Notes:

• CCHUB_AUTHORIZATION_CODE_SCOPE should contain only resource scopes required by Customer's Canvas Hub.
• The CLI automatically adds openid profile email offline_access to the interactive login request.
• See supported scopes through the discovery endpoint https://customerscanvashub.com/.well-known/openid-configuration (see scopes_supported).
• If your identity provider requires an exact redirect URI, use a fixed callback port and register a URI like http://127.0.0.1:53682/oauth/callback.
• If CCHUB_AUTHORIZATION_CODE_CALLBACK_PORT is omitted, the CLI uses a random free port.

If both modes are configured

The CLI uses authentication in this order:

• If a persisted interactive session exists and is still valid, it is used.
• If the interactive session exists but the access token is expired, the CLI tries to refresh it.
• If there is no usable interactive session, the CLI falls back to Client Credentials if they are configured.

Run

Install the dependencies:

npm install

Run the CLI application:

npm start -- <command> <subcommand> <args>

By running npm start without arguments, you get a list of all supported commands.

Get help:

npm start -- help

or

npm start -- help <command>

or (for options of specific subcommands):

npm start -- help <command> <subcommand> --help

For interactive browser-based login:

npm start -- auth login

To inspect or clear the persisted session:

npm start -- auth status
npm start -- auth logout

If you have any problems or questions, create a ticket in the helpdesk.