Документация Triggo
SDK коннекторов

Свойства

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

Свойства

Пространство имён Property предоставляет 17 фабричных методов для объявления типизированных входных полей в действиях и триггерах. Каждый возвращает замороженный 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, когда зависимое поле ещё не заполнено.

Property.MultiSelect

Статический многовариантный выпадающий список. Интерфейс отображает поиск с флажками и чипами для выбранных значений.

Property.MultiSelect({
  displayName: "Channels",
  description: "Slack channels to post to.",
  required: true,
  options: [
    { label: "General", value: "general" },
    { label: "Alerts", value: "alerts" },
  ],
});

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

Property.MultiSelectDynamic

Многовариантный выпадающий список, варианты которого загружаются во время выполнения. Использует тот же контракт DynamicDropdownResolver, что и Property.DynamicDropdown — возвращает { disabled, placeholder, options }.

Property.MultiSelectDynamic({
  displayName: "Tags",
  description: "Tags to apply to the new deal.",
  required: false,
  options: async ({ auth }) => ({
    disabled: false,
    options: await fetchTags(auth),
  }),
  refreshers: ["connectionId"],
});

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

Property.KeyValue

Произвольное отображение строковых ключей на строковые значения. Интерфейс отображает строки ключ/значение с кнопкой добавления; каждая ячейка значения поддерживает {{упоминания}} при наличии вышестоящих узлов. Строки с пустыми ключами исключаются из результирующей записи.

Property.KeyValue({
  displayName: "Custom Headers",
  description: "Additional HTTP headers to attach to the request.",
  required: false,
  keyPlaceholder: "Header name",
  valuePlaceholder: "Header value",
});

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

Property.ResourceLocator

Двухрежимный выбор для больших поисковых ресурсов, когда перечислить все варианты заранее невозможно (например, страницы Notion, сделки HubSpot, файлы Google Drive). Интерфейс предоставляет вкладку Поиск с асинхронным резолвером и debounce, а также вкладку Вставить ID для пользователей, которые уже знают идентификатор.

Property.ResourceLocator({
  displayName: "Notion Page",
  description: "Page to append the new block to.",
  required: true,
  idLabel: "Page ID",
  placeholder: "Search pages…",
  refreshers: ["connectionId"],
  search: async ({ auth, query, cursor }) => {
    const resp = await fetch(`https://api.notion.com/v1/search`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${(auth as { token: string }).token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        query,
        start_cursor: cursor,
        filter: { property: "object", value: "page" },
      }),
    });
    const data = (await resp.json()) as {
      results: Array<{ id: string; properties: { title: { title: { plain_text: string }[] } } }>;
      next_cursor?: string;
    };
    return {
      items: data.results.map((r) => ({
        label: r.properties.title.title[0]?.plain_text ?? r.id,
        value: r.id,
      })),
      nextCursor: data.next_cursor,
    };
  },
});

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

ПолеТипОбязательноОписание
searchSearchResolverДаАсинхронная функция, вызываемая с поисковым запросом пользователя.
refreshersreadonly string[]НетИмена свойств, изменение которых инвалидирует кэш.
placeholderstringНетПодсказка для поля поиска.
idLabelstringНетМетка поля ввода во вкладке «Вставить ID».

SearchResolver

type SearchResolver = (
  context: SearchResolverContext,
) => Promise<SearchResolverResult>;

interface SearchResolverContext {
  readonly auth: unknown;
  readonly query: string;
  readonly cursor?: string;
  readonly values?: Record<string, unknown>;
}

interface SearchResolverResult {
  readonly items: readonly { label: string; value: string }[];
  readonly nextCursor?: string;
}

Инспектор канваса применяет debounce 200 мс и вызывает tRPC-эндпоинт connection.searchResource, который ограничен 200 запросами в минуту на пользователя. Возвращайте nextCursor для постраничной подгрузки; опускайте его, когда результаты исчерпаны.

Тип значения по умолчанию: string (идентификатор ресурса)

Property.File

Принимает строку URL или шаблонное упоминание ({{step1.fileUrl}}), которое во время выполнения разрешается в URL. При литеральном URL интерфейс показывает предпросмотр и кнопку «Загрузить с устройства», которая пока отключена — прямая загрузка появится позже.

Property.File({
  displayName: "Attachment",
  description: "Public URL of the file to attach.",
  required: true,
  allowedMimeTypes: ["image/png", "image/jpeg", "application/pdf"],
});

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

ПолеТипОбязательноОписание
allowedMimeTypesreadonly string[]НетMIME-типы, принимаемые коннектором. Используется только для клиентских подсказок валидации; валидация во время выполнения — ответственность коннектора.

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

Property.MarkdownNotice

Текст-подсказка только для отображения, без значения. Свойство исключается из сгенерированной JSON Schema и никогда не передаётся в run(). Используйте внутри инспекторов для предупреждений о scope, инструкций по настройке или пояснений рядом с соответствующими полями.

Property.MarkdownNotice({
  displayName: "oauth_scope_notice",
  markdown:
    "This action requires the `drive.file` scope. **Reconnect** the integration if you added it after authorization.",
  variant: "warning",
});

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

ПолеТипОбязательноОписание
displayNamestringДаИспользуется только как локальный идентификатор узла; не отображается.
markdownstringДаТело Markdown. Санитизируется до жирного, курсива, inline code и ссылок; <script>, <img> и обработчики событий вырезаются.
variant"info" | "warning" | "success"НетНеобязательная рамка Alert. При отсутствии подсказка отображается inline без рамки.

MarkdownNotice — единственный тип свойства без поля required: оно всегда неинтерактивно.

Тип значения по умолчанию: отсутствует (значение не эмитируется)

Генерация 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" }
MultiSelect{ type: "array", items: { type: "string" } }
MultiSelectDynamic{ type: "array", items: { type: "string" } }
KeyValue{ type: "object", additionalProperties: { type: "string" } }
ResourceLocator{ type: "string" }
File{ type: "string", format: "uri" }
MarkdownNoticeотсутствует в схеме

On this page