@cloudbolt/js-sdk NPM

CloudBolt Javascript SDK

Features

Use idomatic js to interact with the CloudBolt API for a subset of endpoints
- Normalizes responses for list requests
- In-IDE documentation/intellisense for all included endpoints
Helper methods for common tasks
built with axios with through-access for advanced use cases

Installation

Install as a local dependency in your project:

npm install @cloudbolt/js-sdk

Usage

Package Structure

The package exports a single function, createApi. This function returns an api instance with methods for interacting with the CloudBolt API. The api instance is simply an object with nested objects and methods. Important properties include:

api.base - helper methods and objects for interacting with the CloudBolt API
- api.base.instance - the axios instance used for all requests
- api.base.crud - helper methods for interacting with the CloudBolt API at a low-level. They take an endpoint string and various other arguments and options.
- api.base.setAuthHeader - set the auth header on the axios instance
- api.base.setErrorHandler - set a custom error handler for failed requests
api.v3 - methods for interacting with the CloudBolt API v3. Generally they attempt to follow the url structure of the underlying endpoints, as documented in Swaggerhub. Examples are:
- api.v3.cmp.environments
  - api.v3.cmp.environments.list(options)
  - api.v3.cmp.environments.get(id)
  - api.v3.cmp.environments.create(newEnvironment)
  - api.v3.cmp.environments.update(id, updatedEnvironment)
  - api.v3.cmp.environments.replace(id, newEnvironment)
  - api.v3.cmp.environments.delete(id)
  - api.v3.cmp.environments.export(id)
  - api.v3.cmp.environments.getParameters(id)
  - api.v3.cmp.environments.setParameters(id, parameters)
- api.v3.cmp.groups
  - api.v3.cmp.groups.list(options)
  - api.v3.cmp.groups.get(id)
  - api.v3.cmp.groups.create(newGroup)
  - api.v3.cmp.groups.update(id, updatedGroup)
  - api.v3.cmp.groups.delete(id)
- api.v3.cmp.users
  - api.v3.cmp.users.list(options)
  - api.v3.cmp.users.getCurrentUser(options)
  - api.v3.cmp.users.getUserDetails(id)
  - api.v3.cmp.users.getUserPermissions(id)
  - api.v3.cmp.users.updatePassword(id, options)

For an exhaustive look at what is available in api.v3..., see in-IDE documentation as you code or the built types list. For all other API capabilities, use the api.base.crud methods and refer to the Swaggerhub documentation.

What do endpoints return?

Refer to the examples in the Swaggerhub documentation for specific endpoint examples. Generally, endpoints return a Promise that resolves to the response data from the API.

This package restructures responses from list endpoints slightly to make responses more predictable and ergonomic for a js context. If you ever need the original, unstructured response from a query, use the axios instance at api.base.instance and query endpoints directly. When using api.v3... list endpoints or the helper api.base.crud.getItems, the response data looks like this:

{
   items: any[];
   pageInfo: {
      page: number;
      nextPage: string;
      previousPage: string;
      totalElements: number;
   };
}

Examples

Authentication

If using js-sdk from within a CB Applet, the applet receives a pre-authenticated api instance for the currently logged in user. It will automatically refresh the auth token as needed.

If using js-sdk from a stand-alone app, you will need to obtain an auth token from CloudBolt, set it on the api instance, and handle token refreshing manually.

// Initialize the sdk
import { createApi } from '@cloudbolt/js-sdk'
const api = createApi()

// Get an auth token from CloudBolt
const token = await api.v3.cmp.apiToken.obtainToken('username', 'password')
// If operating from within a CloudBolt UI Extension, you can use the session cookie:
// const token = await api.v3.cmp.apiToken.obtainTokenWithSessionCookie()

// Save the auth token to the sdk's axios instance
api.base.setAuthHeader(token)

// Congrat's! You're ready to start making requests to the CloudBolt API with the `api` instance

// As needed (according to the timeout set in CloudBolt or on auth failure), refresh the auth token
const newToken = await api.v3.cmp.apiToken.refreshToken()
api.base.setAuthHeader(newToken)

Simple Queries

// Get a list of environments
const environments = await api.v3.cmp.environments.list()
// Show all of their names
environments.items.forEach((env) => console.log(env.name))
// How many are there total?
console.log(environments.pageInfo.totalElements)

// Get a single environment
const environment = await api.v3.cmp.environments.get('ENV-12345678')
// Show its name
console.log(environment.name)

Queries with options

List endpoints (and some get endpoints) take optional options arguments. These options are js objects that generally get converted to query parameters on the request. See Swaggerhub documentation for per-endpoint available querystrings, our API Conventions for some commonly available querystrings. For example:

// Get the second page of 300 resources
const resources = await api.v3.cmp.resources.list({ page: 2, page_size: 300 })

// Get groups named "my-group"
const groups = await api.v3.cmp.groups.list({ filter: 'name:my-group' })
  .items[0]

// Get jobs ordered by endDate descending
const jobs = await api.v3.cmp.jobs.list({ ordering: '-endDate' })

Querying the base API

Not all endpoints are included in the api.v3... helpers. For all other endpoints, use the api.base.crud methods. These methods are generic and can be used to query any endpoint and include the /api prefix. For example:

// Get a list of all f5 load balancers
const loadBalancers = await api.base.crud.getItems('/v3/cmp/loadBalancers/', {
  filter: 'type:f5'
})

// Get an OS Image
const osImage = await api.base.crud.getItem('/v3/cmp/osImages/IMG-12345678/')

// Patch a tenant
const newTenant = await api.base.crud.patchItemById(
  '/v3/cmp/tenants/TNT-12345678/',
  { label: 'My Tenant Update' }
)

// Get the next page of a list result
const userPage1 = await api.v3.cmp.users.list()
const page2Url = userPage1.pageInfo.nextPage
const userPage2 = await api.base.crud.getItems(page2Url)

You can also use the base axios instance directly (useful if there isn't a helper method for the endpoint or verb you need, or if you have an advanced use case):

// Download web logs
const logs = await api.base.instance.get('/api/v3/cmp/logs/web/')

// Delete a network
await api.base.instance.delete('/api/v3/cmp/networks/ET-12345678/')

Development (for maintainers)

Publishing a New Release to NPM

Follow these steps to publish a new version of the package to NPM. This process ensures version consistency between GitHub and NPM and is essential for effective release management:

Update Version in package.json
- Increment Version: Run npm version patch to update the version in package.json. This command also updates package-lock.json and creates a Git tag.
- For Beta Versions: Use npm version prepatch --preid beta to create a beta version.
Create a New Release on GitHub
- Navigate to the 'Releases' section of your GitHub repository.
- Click 'Draft a new release'.
- Tag the release with the same version number as in package.json, ensuring the tag is on the main branch.
- Complete the release title and description, then publish it.
Automated NPM Publishing
- An automated workflow is triggered when you create a new release with the correct tag, which will publish the new version to NPM.
- Ensure all necessary checks for the release are in place.
Verification
- After the automated process, verify that the new version is available on NPM.