Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@trayio/cdk-dsl

Package Overview
Dependencies
Maintainers
4
Versions
198
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@trayio/cdk-dsl - npm Package Compare versions

Comparing version 1.14.0 to 1.15.0

4

package.json
{
"name": "@trayio/cdk-dsl",
"version": "1.14.0",
"version": "1.15.0",
"description": "A DSL for connector development",

@@ -17,3 +17,3 @@ "exports": {

"dependencies": {
"@trayio/commons": "1.14.0"
"@trayio/commons": "1.15.0"
},

@@ -20,0 +20,0 @@ "typesVersions": {

@@ -41,2 +41,241 @@ # Connector Development Kit (CDK) DSL

## Input & Output
Each operation has an `input.ts` and `output.ts` that defines the input and output parameters for the operation. It should export this as a type named `<OperationName>Input` or `<OperationName>Output`.
During the deployment of a connector these input/output types are converted to JSON schema which powers how the Tray builder UI renders the input fields. This conversion also happens locally when you run the `tray-cdk build` command should you wish to inspect the generated JSON schema.
### Additional Input configuration
The following sections outline the number of different ways to render your input fields in Tray's builder UI by adding JSdoc annotations to the properties in your `input.ts`.
#### Data types
- string: represents string values
- number: represents a number, e.g. 42. If you want to limit an input field to a whole number you can use the JSdoc annotation `@TJS-type integer` above the number.
- boolean: is for the two values true and false
- array: represented by `[]`, e.g. number[]
- object: represented by object that contains different fields
Here is an example use of the different data types:
```typescript
export type ExampleOperationInput = {
str: string;
num: number;
/**
* @TJS-type integer
*/
int: number;
bool: boolean;
obj: object;
arr: object[];
};
```
#### Enums (Static dropdown lists)
Enums are rendered in the Tray builder UI as dropdowns. The user will see the enum display names and the enum values are what will be passed into the handler. By default, user friendly enum display names are generated. e.g. an enum of value `my-enum-value` will be rendered in the UI with the display name `My enum value`.
```typescript
export type ExampleOperationInput = {
type: ActionType;
};
enum ActionType {
first-option = 'first-option', // User will see an auto generated display name: First option
second-option = 'second-option', // User will see an auto generated display name: Second option
third-option = 'third-option', // User will see an auto generated display name: Third option
}
```
You may want to provide custom enum display names instead, to do so use the JSdoc annotation `@enumLabels` followed by a comma separated list of strings that matches the order you have defined your enums in.
```typescript
export type ExampleOperationInput = {
type: ActionType;
};
/**
* @enumLabels The First Option, The Second Option, The Third Option
*/
enum ActionType {
first-option = 'first-option',
second-option = 'second-option',
third-option = 'third-option',
}
```
#### DDL (Dynamic dropdown lists)
Sometimes you want to provide the user a dropdown list, but you don't know the items to display in the list because they come from another API. For example you may want to display a list of user names in a dropdown and based on the selection send the user ID. DDL's solve this problem. Once you have created an operation for your DDL (see more on this in the Composite Implementation section) you can use this DDL in the input of many other operations.
The JSdoc annotation `@lookupOperation` specifies what operation to invoke when the user expands the dropdown. `@lookupInput` is used to describe the JSON payload to send to that DDL operation. Any inputs defined in input.ts can be passed to the DDL operation using tripple braces. In this example we send the workspaceId field value by doing `{{{workspaceId}}}`. If your DDL operation calls an authenticated endpoint you can pass along the token used in the current operation by setting `@lookupAuthRequired true`.
```typescript
export type ExampleOperationInput = {
workspaceId: string;
/**
* @title user
* @lookupOperation list_users_ddl
* @lookupInput {"includePrivateChannels": false,"workspaceId": "{{{workspaceId}}}"}
* @lookupAuthRequired true
*/
userId: string;
};
```
#### Reusing types across multiple operations
You can reuse types by importing them and reuse sections of a schema by using TypeScript intersections.
```typescript
// input.ts
import { ReusableField } from './ReusableField';
import { ReusableSchema } from './ReusableSchema';
export type ExampleOperationInput = SpecificSchema & ReusableSchema;
type SpecificSchema = {
specificField: string;
reusableFields: ReusableField;
};
```
```typescript
// ReusableField.ts
export type ReusableField = {
reusableFieldA: number;
reusableFieldB: string;
};
```
```typescript
// ReusableSchema.ts
export type ReusableSchema = {
reusableSchemaA: number;
reusableSchemaB: string;
};
```
Once the imports and intersection are resolved the above example would look like this
```typescript
export type Input = {
specificField: string;
reusableFields: {
reusableFieldA: number;
reusableFieldB: string;
};
reusableSchemaA: number;
reusableSchemaB: string;
}
```
#### Union types (Supporting multiple types)
If you want to support two or more different object types in your schema you can achieve this using TypeScript unions.
In the example below our input accepts an array of elements. Each element of this array can be either of type image or text. When the user adds an item to the array they will see a dropdown where they can select if this element will be an image or text. The JSdoc annotation `@title` on the image and text types will be displayed in the dropdown the user sees.
```typescript
export type ExampleOperationInput = {
elements: ImageOrText[];
};
type ImageOrText = Image | Text;
/**
* @title Image
*/
type Image = {
name: string;
src: string;
};
/**
* @title Text
*/
type Text = {
text: string;
};
```
#### Required/Optional fields
By default all input fields are mandatory, you can set any to optional with a `?` in your TypeScript type. Mandatory fields get a red * in the Tray builder UI and will warn the user that they must be filled in before attempting to run a workflow.
```typescript
export type ExampleOperationInput = {
mandatoryField: string;
optionalField?: string;
};
```
#### Formatting fields
By default properties on your input type render as simple input fields. You can select a more user friendly way to render the field based on your needs by using the JSdoc annotation `@format`.
The format options available are:
- datetime - renders a date and time picker
- code - renders a button which on click opens a modal with a simple code editor
- text - for longer text inputs, expands when you enter new lines
```typescript
export type ExampleOperationInput = {
/**
* @format datetime
*/
timestamp: string;
/**
* @format code
*/
html: string;
/**
* @format text
*/
longNotes: string;
};
```
#### Default values
If you want to provide a default initial value for a field you can use the JSdoc annotation `@default`.
```typescript
export type ExampleOperationInput = {
/**
* @default string default
*/
str: string;
/**
* @default 0.1
*/
num: number;
/**
* @TJS-type integer
* @default 1
*/
int: number;
/**
* @default true
*/
bool: boolean;
/**
* @default { "default": true }
*/
obj: object;
/**
* @default ["default"]
*/
arr: object[];
};
```
#### Advanced fields
If you have optional fields that are for more advanced use cases you can obscure these into the Tray builder UI's advanced fields section. This can provide a cleaner interface for your operation, but can still be accessed by the user by expanding the advanced fields section. You can add fields here by using the JSdoc annotation `@advanced true`.
```typescript
export type ExampleOperationInput = {
normalField: string;
/**
* @advanced true
*/
advancedField?: string;
};
```
## Handler

@@ -43,0 +282,0 @@

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc