SDK

Создание действия

Справочник по API createAction() — определяет операцию с типизированными входными свойствами, функцией run и опциональной обработкой ошибок.

Создание действия

createAction() определяет одну операцию, которую коннектор может выполнять, -- например, отправка сообщения, создание записи или получение данных.

Сигнатура

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

function createAction<TAuth = unknown, TProps = unknown>(
  config: ActionConfig<TAuth, TProps>,
): ActionDefinition<TAuth, TProps>;

ActionConfig

ПолеТипОбязательноОписание
namestringДаУникальный идентификатор действия. Должен быть в формате snake_case (например, send_message).
displayNamestringДаЧитаемое имя, отображаемое в интерфейсе.
descriptionstringДаОписание того, что делает действие. Также используется AI для выбора действий.
propsRecord<string, PropertyDefinition>ДаВходные свойства. Используйте конструкторы Property.*. Передайте {} при отсутствии входных данных.
run(context: ActionContext<TAuth, TProps>) => Promise<unknown>ДаФункция, выполняющая действие. Получает типизированный контекст с аутентификацией, свойствами и хранилищем.
errorHandlingOptionsErrorHandlingOptionsНетНастройка поведения при повторных попытках и продолжении при ошибке.
aiHintsstringНетДополнительный контекст для AI-генератора пайплайнов. Помогает AI понять, когда и как использовать это действие.

ActionDefinition (возвращаемый тип)

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

ПолеТипОписание
inputSchemaRecord<string, unknown>Автоматически сгенерированная JSON Schema из props. Используется AI-системой и слоем валидации.

Всё определение глубоко заморожено.

ActionContext

Функция run получает ActionContext следующей формы:

interface ActionContext<TAuth = unknown, TProps = unknown> {
  readonly auth: TAuth;
  readonly propsValue: TProps;
  readonly store: StoreContext;
}
ПолеТипОписание
authTAuthУчётные данные аутентификации. Форма зависит от типа аутентификации коннектора.
propsValueTPropsРазрешённые значения входных свойств от пользователя или пайплайна.
storeStoreContextПерсистентное key-value хранилище для кеширования или состояния.

Подробнее см. Контекст и хранилище.

ErrorHandlingOptions

interface ErrorHandlingOptions {
  retryOnFailure?: {
    maxRetries: number;
    baseIntervalMs: number;
  };
  continueOnFailure?: boolean;
}
ПолеТипОписание
retryOnFailure.maxRetriesnumberМаксимальное количество повторных попыток.
retryOnFailure.baseIntervalMsnumberБазовый интервал в миллисекундах между повторами (экспоненциальный откат).
continueOnFailurebooleanЕсли 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 для кеширования ресурсоёмких запросов (см. Контекст и хранилище)

On this page