@trayio/cdk-dsl 1.14.0 → 1.16.0

package/README.md

@@ -38,6 +38,245 @@ A connector will have one folder per operation under the `src` folder, this fold
 - `handler.ts` which is where the logic of the operation is
 - `handler.test.ts` which contains the test cases for testing the operation's behaviour defined in the handler
 
+## 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
 
 A handler at its core, describes a function, that takes an `ctx` value with an `auth` property described by the authentication type (which is the same for all operations) and it takes an `input` value described by the input type of the operation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trayio/cdk-dsl",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "A DSL for connector development",
   "exports": {
     "./*": "./dist/*.js"
@@ -14,7 +14,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@trayio/commons": "1.14.0"
+    "@trayio/commons": "1.16.0"
   },
   "typesVersions": {
     "*": {