Создание действия
Справочник по API createAction() — определяет операцию с типизированными входными свойствами, функцией run и опциональной обработкой ошибок.
Создание действия
createAction() определяет одну операцию, которую коннектор может выполнять, -- например, отправка сообщения, создание записи или получение данных.
Сигнатура
import { createAction } from "@triggo/connector-sdk";
function createAction<TAuth = unknown, TProps = unknown>(
config: ActionConfig<TAuth, TProps>,
): ActionDefinition<TAuth, TProps>;ActionConfig
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | Да | Уникальный идентификатор действия. Должен быть в формате snake_case (например, send_message). |
displayName | string | Да | Читаемое имя, отображаемое в интерфейсе. |
description | string | Да | Описание того, что делает действие. Также используется AI для выбора действий. |
props | Record<string, PropertyDefinition> | Да | Входные свойства. Используйте конструкторы Property.*. Передайте {} при отсутствии входных данных. |
run | (context: ActionContext<TAuth, TProps>) => Promise<unknown> | Да | Функция, выполняющая действие. Получает типизированный контекст с аутентификацией, свойствами и хранилищем. |
errorHandlingOptions | ErrorHandlingOptions | Нет | Настройка поведения при повторных попытках и продолжении при ошибке. |
aiHints | string | Нет | Дополнительный контекст для AI-генератора пайплайнов. Помогает AI понять, когда и как использовать это действие. |
ActionDefinition (возвращаемый тип)
Возвращаемый объект включает все поля конфигурации, а также:
| Поле | Тип | Описание |
|---|---|---|
inputSchema | Record<string, unknown> | Автоматически сгенерированная JSON Schema из props. Используется AI-системой и слоем валидации. |
Всё определение глубоко заморожено.
ActionContext
Функция run получает ActionContext следующей формы:
interface ActionContext<TAuth = unknown, TProps = unknown> {
readonly auth: TAuth;
readonly propsValue: TProps;
readonly store: StoreContext;
}| Поле | Тип | Описание |
|---|---|---|
auth | TAuth | Учётные данные аутентификации. Форма зависит от типа аутентификации коннектора. |
propsValue | TProps | Разрешённые значения входных свойств от пользователя или пайплайна. |
store | StoreContext | Персистентное key-value хранилище для кеширования или состояния. |
Подробнее см. Контекст и хранилище.
ErrorHandlingOptions
interface ErrorHandlingOptions {
retryOnFailure?: {
maxRetries: number;
baseIntervalMs: number;
};
continueOnFailure?: boolean;
}| Поле | Тип | Описание |
|---|---|---|
retryOnFailure.maxRetries | number | Максимальное количество повторных попыток. |
retryOnFailure.baseIntervalMs | number | Базовый интервал в миллисекундах между повторами (экспоненциальный откат). |
continueOnFailure | boolean | Если true, пайплайн продолжает выполнение даже при ошибке этого действия. |
Правила валидации
- Формат имени -- должен соответствовать
/^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/(непустой snake_case) - Некорректные имена вызывают
Errorпри создании
Пример
import { createAction, Property, ConnectorError } from "@triggo/connector-sdk";
import { CONNECTOR_ERROR_CODES } from "@triggo/shared";
export const createTask = createAction({
name: "create_task",
displayName: "Create Task",
description: "Creates a new task in the project management tool.",
props: {
title: Property.ShortText({
displayName: "Title",
description: "The task title.",
required: true,
}),
description: Property.LongText({
displayName: "Description",
description: "Detailed task description.",
required: false,
}),
priority: Property.Dropdown({
displayName: "Priority",
description: "Task priority level.",
required: true,
options: [
{ label: "Low", value: "low" },
{ label: "Medium", value: "medium" },
{ label: "High", value: "high" },
],
defaultValue: "medium",
}),
},
errorHandlingOptions: {
retryOnFailure: { maxRetries: 3, baseIntervalMs: 1000 },
continueOnFailure: false,
},
aiHints:
"Use this action to create a new task. " +
"Requires a title. Priority defaults to medium if not specified.",
async run(context) {
const { title, description, priority } = context.propsValue as {
title: string;
description?: string;
priority: string;
};
const auth = context.auth as { secret: string };
const response = await fetch("https://api.example.com/tasks", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${auth.secret}`,
},
body: JSON.stringify({ title, description, priority }),
});
if (!response.ok) {
throw new ConnectorError(
CONNECTOR_ERROR_CODES.UPSTREAM_ERROR,
`Failed to create task: ${response.status} ${response.statusText}`,
);
}
return await response.json();
},
});Лучшие практики
- Функции
runдолжны быть сфокусированы на одной операции - Всегда валидируйте ответы внешних API и выбрасывайте
ConnectorErrorс соответствующими кодами - Используйте
aiHints, чтобы описать, когда AI должен выбирать это действие среди похожих - Устанавливайте
continueOnFailure: trueтолько для некритичных побочных действий (например, логирование, уведомления) - Используйте
storeдля кеширования ресурсоёмких запросов (см. Контекст и хранилище)
Создание коннектора
Справочник по API createConnector() — собирает аутентификацию, действия и триггеры в иммутабельный ConnectorDefinition.
Создание триггера
Справочник по API createTrigger() — определяет webhook- или polling-триггеры с хуками жизненного цикла для включения, отключения и обработки событий.