Свойства
Справочник по системе Property — 17 типов свойств для объявления типизированных входных данных в действиях и триггерах.
Свойства
Пространство имён Property предоставляет 17 фабричных методов для объявления типизированных входных полей в действиях и триггерах. Каждый возвращает замороженный PropertyDefinition, описывающий тип поля, метку, валидацию и значение по умолчанию.
import { Property } from "@triggo/connector-sdk";Базовая конфигурация
Все типы свойств имеют общие поля конфигурации:
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
displayName | string | Да | Метка, отображаемая в интерфейсе. |
description | string | Нет | Вспомогательный текст с описанием поля. |
required | boolean | Да | Обязательно ли заполнение поля. |
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
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
options | DynamicDropdownResolver | Да | Асинхронная функция, возвращающая состояние выпадающего списка. |
refreshers | readonly 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
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
search | SearchResolver | Да | Асинхронная функция, вызываемая с поисковым запросом пользователя. |
refreshers | readonly string[] | Нет | Имена свойств, изменение которых инвалидирует кэш. |
placeholder | string | Нет | Подсказка для поля поиска. |
idLabel | string | Нет | Метка поля ввода во вкладке «Вставить 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
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
allowedMimeTypes | readonly 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
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
displayName | string | Да | Используется только как локальный идентификатор узла; не отображается. |
markdown | string | Да | Тело 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 | отсутствует в схеме |
Аутентификация
Справочник по ConnectorAuth — четыре типа аутентификации для коннекторов, включая OAuth2, SecretText, CustomAuth и None.
Контекст и хранилище
Справочник по ActionContext и TriggerContext — объекты контекста выполнения, предоставляющие аутентификацию, значения свойств, персистентное хранилище и данные вебхуков.