SDK

Свойства

Справочник по системе Property — 11 типов свойств для объявления типизированных входных данных в действиях и триггерах.

Свойства

Пространство имён Property предоставляет 11 фабричных методов для объявления типизированных входных полей в действиях и триггерах. Каждый возвращает замороженный PropertyDefinition, описывающий тип поля, метку, валидацию и значение по умолчанию.

import { Property } from "@triggo/connector-sdk";

Базовая конфигурация

Все типы свойств имеют общие поля конфигурации:

ПолеТипОбязательноОписание
displayNamestringДаМетка, отображаемая в интерфейсе.
descriptionstringНетВспомогательный текст с описанием поля.
requiredbooleanДаОбязательно ли заполнение поля.
defaultValueзависит от типаНетЗначение по умолчанию, если пользователь не указал значение.

Типы свойств

Property.ShortText

Однострочное текстовое поле.

Property.ShortText({
  displayName: "Name",
  description: "The recipient's name.",
  required: true,
})

Тип значения по умолчанию: string

Property.LongText

Многострочное текстовое поле.

Property.LongText({
  displayName: "Message Body",
  description: "The full message content. Supports multiple lines.",
  required: true,
})

Тип значения по умолчанию: string

Property.Number

Числовое поле.

Property.Number({
  displayName: "Quantity",
  description: "Number of items.",
  required: true,
  defaultValue: 1,
})

Тип значения по умолчанию: number

Property.Checkbox

Булево переключение.

Property.Checkbox({
  displayName: "Send Notification",
  description: "Whether to send an email notification.",
  required: false,
  defaultValue: false,
})

Тип значения по умолчанию: boolean

Property.DateTime

Ввод даты и времени в формате ISO 8601.

Property.DateTime({
  displayName: "Due Date",
  description: "Task deadline in ISO 8601 format.",
  required: false,
})

Тип значения по умолчанию: string (формат: date-time)

Property.Array

Массив значений.

Property.Array({
  displayName: "Tags",
  description: "List of tags to apply.",
  required: false,
  defaultValue: [],
})

Тип значения по умолчанию: readonly unknown[]

Property.Object

Произвольный объект с парами ключ-значение.

Property.Object({
  displayName: "Metadata",
  description: "Custom key-value pairs.",
  required: false,
  defaultValue: {},
})

Тип значения по умолчанию: Record<string, unknown>

Property.SecretText

Ввод конфиденциального текста. Значение маскируется в интерфейсе и шифруется при хранении.

Property.SecretText({
  displayName: "Webhook Secret",
  description: "HMAC secret for signature verification.",
  required: true,
})

Тип значения по умолчанию: string (без defaultValue -- секреты не должны иметь значений по умолчанию)

Property.OAuth2

Ссылка на OAuth2-учётные данные. Используется внутренне системой аутентификации.

Property.OAuth2({
  displayName: "OAuth2 Connection",
  description: "Select an OAuth2 connection.",
  required: true,
})

Тип значения по умолчанию: Record<string, unknown>

Property.Dropdown

Статический выпадающий список с предопределёнными вариантами.

Property.Dropdown({
  displayName: "Priority",
  description: "Task priority level.",
  required: true,
  defaultValue: "medium",
  options: [
    { label: "Low", value: "low" },
    { label: "Medium", value: "medium" },
    { label: "High", value: "high" },
  ],
})

Тип значения по умолчанию: string

Массив options содержит объекты DropdownOption:

interface DropdownOption {
  readonly label: string;  // Shown in the UI
  readonly value: string;  // Stored value passed to run()
}

Варианты Dropdown включаются в автоматически генерируемую JSON Schema как ограничение enum.

Property.DynamicDropdown

Выпадающий список, варианты которого загружаются во время выполнения через API-вызов.

Property.DynamicDropdown({
  displayName: "Pipeline",
  description: "Select a pipeline to reference.",
  required: true,
  refreshers: ["workspace_id"],
  options: async (context) => {
    const auth = context.auth as { secret: string };
    const workspaceId = context.values?.["workspace_id"] as string | undefined;

    if (!workspaceId) {
      return {
        disabled: true,
        placeholder: "Select a workspace first",
        options: [],
      };
    }

    const response = await fetch(
      `https://api.example.com/workspaces/${workspaceId}/pipelines`,
      { headers: { Authorization: `Bearer ${auth.secret}` } },
    );
    const pipelines = (await response.json()) as Array<{ id: string; name: string }>;

    return {
      disabled: false,
      options: pipelines.map((p) => ({ label: p.name, value: p.id })),
    };
  },
})

Конфигурация DynamicDropdown

ПолеТипОбязательноОписание
optionsDynamicDropdownResolverДаАсинхронная функция, возвращающая состояние выпадающего списка.
refreshersreadonly string[]НетИмена свойств, изменение значений которых вызывает повторную загрузку.

DynamicDropdownResolver

type DynamicDropdownResolver = (
  context: DynamicDropdownResolverContext,
) => Promise<DynamicDropdownState>;

interface DynamicDropdownResolverContext {
  readonly auth: unknown;
  readonly values?: Record<string, unknown>;
}

interface DynamicDropdownState {
  readonly disabled: boolean;
  readonly placeholder?: string;
  readonly options: readonly DropdownOption[];
}

Верните { disabled: true } с placeholder, когда зависимое поле ещё не заполнено.

Генерация JSON Schema

Все свойства автоматически преобразуются в JSON Schema через propertiesToJsonSchema(). Результирующая схема прикрепляется к определению действия/триггера как inputSchema и используется AI-системой при генерации пайплайнов.

Тип свойстваТип JSON Schema
ShortText{ type: "string" }
LongText{ type: "string" }
Number{ type: "number" }
Checkbox{ type: "boolean" }
DateTime{ type: "string", format: "date-time" }
Array{ type: "array" }
Object{ type: "object" }
SecretText{ type: "string" }
OAuth2{ type: "object" }
Dropdown{ type: "string", enum: [...] }
DynamicDropdown{ type: "string" }

On this page