SDK 2 Migration
Introduction
The release of SDK 2.0 adds many capabilities to the Ops Platform, but requires the Op developer to update their code to use its new API. This document will guide you through the steps necessary to convert an Op using SDK 1.x to SDK 2.0.
ops.yml and Dockerfile changes
The first change that you will need to make is to the ops.yml
. Add the line
to the command definition, alongside the run
key. This will signal to the Ops CLI that your Op is expecting the SDK 2.0 environment. Second, you must change the final base image in your Dockerfile; it must be one of the Ops base images provided by CTO.ai. If you’re using the JavaScript SDK, use registry.cto.ai/official_images/node:latest
, otherwise use registry.cto.ai/official_images/base:latest
. If you are unfamiliar with Dockerfiles, this must go on the line beginning with FROM
that does not have a suffix of AS <identifier>
.
The official CTO.ai images for SDK 2.0 are based on a slim install of Debian, so additional external packages are available through apt-get
. The 1.x templates generated a Dockerfile that creates an Alpine image, so any custom apk
commands must be replaced by their corresponding commands using apt-get
.
Type Definition Changes for Typescript Users
The 1.x SDK used type definitions from the underlying user interface library, inquirer
. As SDK 2.0 no longer uses Inquirer for its interface, it now incorporates these types into the SDK itself. Typescript code using SDK 1.x will need to change type imports from Inquirer into imports from @cto.ai/sdk
.
User Output Changes
In SDK 2.0, the primary function for outputting to the user is ux.print
. ux.print
relays its argument to the user’s interface, regardless of whether the interface is a local terminal or a remote interface such as Slack. We recommend that you change as many uses as possible of sdk.log
and console.log
to ux.print
calls, keeping in mind that ux.print
takes a single formatted string rather than arbitrary arguments.
Prompt Changes
A variety of changes to the prompt API are required since the new architecture requires the prompt definitions to be JSON-serializable. These will be categorized into general changes and changes that affect only specific prompt types.
General Prompt Changes
These changes apply to all or most of the prompt definition types.
No Optional Callbacks
In the 1.x SDK, the message
, default
, and choices
properties are allowed to be functions of the set of previous answers, rather than explicit values. To port to SDK 2.0, you’ll need to replace these functions with code outside the prompt
call if you’re using them. Similarly, the when
callback for conditionally executing prompts is removed in SDK 2.0
No Validation Or Transformations
The 1.x SDK permits passing validation and filter functions that check or modify the user input inside the prompt logic before returning. These are not available in SDK 2.0, but may return in a different form in later versions if needed.
No afterMessage
The afterMessage
property is not used by SDK 2.0 at launch. You can replace this with a ux.print
call.
Input Prompt Changes
In SDK 1.x, the input
prompt type accepts empty input by default. In SDK 2 this default is switched to disallowing empty input. Set the allowEmpty
field in the prompt to true
if empty input makes sense.
Password Prompt Changes
The password
prompt type in SDK 1.x takes a mask
character to replace the typed text in the prompt. In SDK 2.0 this is unnecessary and ignored, and passwords are concealed invisibly.
List Prompt Changes
In SDK 1.x, the list
prompt type can take a choices
array containing Javascript objects allowing the list rows to have metadata. This is not available in SDK 2.0, but may return in a different form in later versions if needed. In SDK 2.0 it must be an array of strings.
This applies to the autocomplete
and checkbox
prompt types as well.
Autocomplete Prompt Changes
Earlier versions of SDK 1.x required a manual autocomplete function to be supplied to this prompt type as the source
property. This is no longer available in SDK 2.0. Instead, the autocomplete functionality is built in, so you just need to pass the array of possibilities as the choices
property, in the same way as in a list
prompt type.
If the prompt uses the autocomplete
property to pass the array, you do not need to change the prompt. This variation is supported for compatibility.
Datetime Prompt Changes
The date/time prompt is substantially changed from the form in SDK 1.x. The name of the prompt has changed from datepicker
to datetime
. Rather than needing a format for the date and/or time to be requested, there is a variant
field that can be 'date'
, 'time'
, or 'datetime'
.
For full details, check the prompt API documentation.
New async Functions
The following functions change from plain functions to async
functions in SDK 2.0:
ux.spinner.start
ux.spinner.stop
ux.table
ux.tree().display()
Removed Functions and Objects
The following SDK 1.x functions have been removed from SDK 2.0:
sdk.isContainer
- the new SDK does not support containerless opssdk.user
- this information is now kept within the SDK daemonsdk.yargs
- the SDK daemon now parses arguments. Ifyargs
is necessary you can just depend on it directly.sdk.inquirer
- we no longer use Inquirer in the SDK.