Node.js SDK: sdk

The Node.js support allows you to write your workflows in either JavaScript or Typescript. When you run ops init from the command-line, a JavaScript project will be created for you. To switch to TypeScript, you can copy the default ops.yml and Dockerfile from the JavaScript project and add them to your TypeScript project.

Node SDK Installation

You can install and use the SDK in a Node.js project like this:

$ npm install @cto.ai/sdk

Usage:

import {sdk, ux} from "@cto.ai/sdk"

sdk.exec

sdk.exec(command: string, options: ExecOptions = {}): Promise<{ stdout: string, stderr: string | child_process.ChildProcess}>

Runs a shell command inside the container. By default, it reads the full output of the command and returns it as stdout and stderr.

If this throws an ERR_CHILD_PROCESS_STDIO_MAXBUFFER error, consider using the spawn option (described below).

ExecOptions

export interface Env {
  [key: string]: string | undefined
}

export interface ExecOptions {
  spawn?: boolean
  env?: Env
}

If the spawn option is set to true, the child_process.spawn function is used to create the child process. In this case, the exec function returns a ChildProcess object rather than the stdout and stderr as strings. See the Node documentation for details on how to access the ChildProcess output streams.

The keys and values of the env option are set as environment variables for the child process. This is an alternative for providing them in the shell command that has fewer pitfalls and edge cases.

Examples:

Executing the following code in the command template:

import {sdk} from "@cto.ai/sdk"

const main = async () => {
  await sdk.exec("mkdir test-directory")
  const {stdout, stderr} = await sdk.exec("ls")

  sdk.log("stdout is:\\n", stdout)
  sdk.log("stderr is:\\n", stderr)
}

main()

will create a folder named test-directory in the container, and logs the following text.

stdout is:
demo.js
index.js
node_modules
package-lock.json
package.json
test-directory

stderr is:

The following script makes a Git commit with custom author information:

import {sdk} from "@cto.ai/sdk"

const main = async () => {
  const {name} = sdk.prompt({
    type: "input",
    name: "name",
    message: "What author name to use?",
  })
  const {email} = sdk.prompt({
    type: "input",
    name: "email",
    message: "What author email to use?",
  })
  const {message} = sdk.prompt({
    type: "input",
    name: "message",
    message: "What commit message to use?",
  })

  await sdk.exec(`git commit -a -m ${message}`, {
    env: {GIT_AUTHOR_NAME: name, GIT_AUTHOR_EMAIL: email},
  })
}

main()

The following code reads a large compressed file and searches for lines containing a specific word:

import {sdk, ux} from "@cto.ai/sdk"

const scan = async (word) => {
  const child = await sdk.exec("zcat data.txt.gz", {spawn: true})

  const matchingLines = []
  child.stdout.setEncoding("utf8")
  for await (const chunk of child.stdout) {
    matchingLines.push(...chunk.split("\n").filter((line) => line.includes(word)))
  }

  ux.print(`Found ${matchingLines.length} matching lines in the data file`)
  matchingLines.forEach((line) => sdk.log(line))
}

scan("DevOps")

sdk.start

Starts a remote command/pipeline/service that belongs to the same team as the workflow that executes the method.

sdk.start(workflowName: string): void

Example:

import {sdk} from "@cto.ai/sdk"

async function main() {
  sdk.start("workflow-name")
}
main().then().catch()

sdk.getHostOS

sdk.getHostOS(): string

Returns the Operating System the host is running on. For workflows not running locally, will return "unknown" as no host is accessible in the remote environment.

Example:

import {sdk} from "@cto.ai/sdk"

const main = async () => {
  const hostOs = sdk.getHostOS()
  sdk.log("Host's os is:", hostOs)
}

Output:

Host's os is: darwin

sdk.homeDir

sdk.homeDir(): string

Returns the home directory of the host machine.

Example:

import {sdk} from "@cto.ai/sdk"

const main = async () => {
  const homeDir = sdk.homeDir()
  console.log("Host's home directory is:", homeDir)
}

Output:

Host's home directory is: /root

sdk.log

sdk.log(...args: any[]): void

Logs to the console in in a standardized way. Will not be relayed to the user in a remote environment (use ux.print for that).

Example:

import {sdk} from "@cto.ai/sdk"

const main = async () => {
  sdk.log("I am a log!", "\\nI am too!")
}

Output:

I am a log!
I am too!

sdk.getStatePath

sdk.getStatePath(): string

Returns the path of the state directory. The contents of this directory are persistent through a workflow, including on remote.

Example:

import {sdk} from "@cto.ai/sdk"

const main = async () => {
  const statePath = sdk.getStatePath()
  sdk.log("The state path is:", statePath)
}

Output:

The state path is: /root/.config/@cto.ai/ops/superman/test-op/00000000-1111-2222-3333-444444444444

sdk.setConfig

sdk.setConfig(key: string, value: string): Promise<void>

Stores a key-value pair in the persistent team configuration. If the key is already present, the value will be replaced with the one provided.

Example:

import {sdk} from "@cto.ai/sdk"

const main = async () => {
  const key = "test-key"
  // config = {}
  const initialConfig = await sdk.getConfig(key)
  sdk.log("Initial config", initialConfig)

  // config = { test-key: 'Value one' }
  await sdk.setConfig(key, "Value one")
  const insertedConfig = await sdk.getConfig(key)
  sdk.log("Inserted config", insertedConfig)

  // config = { test-key: 'Value two' }
  await sdk.setConfig(key, "Value two")
  const updatedConfig = await sdk.getConfig(key)
  sdk.log("Updated config", updatedConfig)
}

Output:

Initial config null
Inserted config Value one
Updated config Value two

sdk.deleteConfig

sdk.deleteConfig(key: string): Promise<boolean>

Deletes a key-value pair in the persistent team configuration. Returns true if the key exists and the deletion is successful, or false if the key cannot be found.

Example:

import {sdk} from "@cto.ai/sdk"

const main = async () => {
  const key = "test-key"

  // config = {}
  const initialConfig = await sdk.getConfig(key)
  sdk.log("Initial config", initialConfig)

  // config = { 'test-key': 'Value one' }
  await sdk.setConfig(key, "Value one")
  const insertedConfig = await sdk.getConfig(key)
  sdk.log("Inserted config", insertedConfig)

  // config = {}
  const deleted = await sdk.deleteConfig(key)
  if (deleted) {
    sdk.log("Deleted config")
  }
}

Output:

Initial config null
Inserted config Value one
Deleted config

sdk.getConfig

sdk.getConfig(key: string): Promise<string | null>

Gets the value that is saved under the given key in the persistent team configuration, or null if the key is not set.

Example

See sdk.setConfig above.

sdk.getAllConfig

sdk.getAllConfig(): Promise<object>

Gets the full contents of the persistent team configuration.

Example

import {sdk} from "@cto.ai/sdk"

const main = async () => {
  await sdk.setConfig("key1", "Value one")
  await sdk.setConfig("key2", "Value two")

  const fullConfig = await sdk.getAllConfig()
  sdk.log("Full config: ", JSON.stringify(fullConfig))
}

sdk.getSecret

sdk.getSecret(key: string, hidden: boolean = false): Promise<any>

Requests a secret from the secret store with the given key.

If the secret exists, it is returned. A notification is printed to the user that the secret has been accessed, unless the hidden argument is true.

If the secret does not exist, the user is prompted to provide a replacement, either from the secret store or by direct entry through their interface.

Example

import {sdk} from "@cto.ai/sdk"

const main = async () => {
  const {SECRET} = sdk.getSecret("SECRET")
  // `ux.print` hides secret values but `sdk.log` does not.
  sdk.log(`my secret is ${SECRET}`)
}

main()

Output

my secret is SUPER_SECRET_VALUE

sdk.setSecret

sdk.setSecret(key: string, value: string): Promise<any | null>

Sets a particular value into the secret store.

If the secret already exists, the user is prompted on whether to overwrite it.

Returns the key that the secret is set to, or null if the user declines to overwrite the existing value.

Example

import {sdk, ux} from "@cto.ai/sdk"

const main = async () => {
  const {key} = await sdk.setSecret("secret1", "it's a secret to everybody")
  await ux.print(key)
}

Output

secret1

sdk.team

Allows a command to request the basic team information like team id and team name.

Example

const {sdk} = require("@cto.ai/sdk")

const main = async () => {
  const team = sdk.team()
  sdk.log(team)
}

main()

Output

{
  "id": "example-team-uuid",
  "name": "example"
}

sdk.track

The track function allows you to store and retrieve custom analytic data.

sdk.track(tags, metadata): Promise<any>

• (DEPRECATED) tags: (String || String[]) This field is deprecated, please do not use
• metaData: (Object) Data you want to be tracked

Using Track for Workflow Metrics

Tracking Workflow Metrics using CTO.ai can give deep insight into your team’s activity.

To use track to send a Workflow Metric event, place your event data in the metaData field like so:

const {sdk} = require("@cto.ai/sdk")
async function main() {
  const event = {
    event_name: "deployment",
    event_action: "succeeded",
    commit: "956b425e5bee",
    repo: "web",
    branch: "main",
  }

  sdk.track([], event)
}
main()

The first argument to sdk.track is a field that isn’t used by the metrics dashboard, so it has been left blank in this example.

NOTE: currenlty the supported values forevent_action are succeeded or failure.

More information about Insights can be found on the Insights Overview page.

sdk.events

This function will return the information that has been stored by sdk.track.

async function events(start: string, end?: string) -> Promise<Array<Any>>

Retrieve workflow events from The Ops Platform.

The start and end time can be given as ISO strings, for example "2020-05-12T20:47:45Z"

sdk.user

User allows an Command to get information about the CTO.ai user running it such as: id, username, & email. For example, you can set the username or email for a text field that corresponds with who created a ticket or flagged an incident.

Example

const {sdk} = require("@cto.ai/sdk")

const main = async () => {
  const user = sdk.user()
  sdk.log(user)
}

main()

Output

{
  "id": "example-user-uuid",
  "username": "example",
  "email": "[email protected]"
}