SDK

Создание триггера

Справочник по API createTrigger() — определяет webhook- или polling-триггеры с хуками жизненного цикла для включения, отключения и обработки событий.

Создание триггера

createTrigger() определяет источник событий, который запускает выполнение пайплайна. Триггеры могут быть основаны на вебхуках (push) или поллинге (pull).

Сигнатура

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

function createTrigger<TAuth = unknown, TProps = unknown>(
  config: TriggerConfig<TAuth, TProps>,
): TriggerDefinition<TAuth, TProps>;

TriggerConfig

ПолеТипОбязательноОписание
namestringДаУникальный идентификатор триггера. Должен быть в формате snake_case (например, new_message).
displayNamestringДаЧитаемое имя, отображаемое в интерфейсе.
descriptionstringДаОписание события, на которое реагирует триггер.
propsRecord<string, PropertyDefinition>ДаВходные свойства. Передайте {} при отсутствии входных данных.
typeTriggerTypeДаTRIGGER_TYPES.WEBHOOK или TRIGGER_TYPES.POLLING.
onEnable(context: TriggerContext) => Promise<void | OnEnableResult>ДаВызывается при активации пайплайна. Здесь регистрируются вебхуки или запускается поллинг.
onDisable(context: TriggerContext) => Promise<void>ДаВызывается при деактивации пайплайна. Очистка вебхуков или остановка поллинга.
run(context: TriggerContext) => Promise<unknown[]>ДаОбрабатывает входящее событие. Должен возвращать массив объектов событий.
outputSchemaRecord<string, unknown>НетJSON Schema, описывающая форму выходных данных триггера. Используется AI-системой.
sampleDataunknownНетПример выходных данных для предварительного просмотра и тестирования в интерфейсе.
test(context: TriggerContext) => Promise<unknown[]>НетВозвращает примеры событий для тестовой панели без необходимости реального события.
aiHintsstringНетДополнительный контекст для AI-генератора пайплайнов.

Типы триггеров

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

TRIGGER_TYPES.WEBHOOK  // "WEBHOOK" — external service pushes events via HTTP
TRIGGER_TYPES.POLLING  // "POLLING" — Triggo periodically checks for new events

Webhook-триггеры

Webhook-триггеры получают события, отправленные внешними сервисами. Triggo генерирует уникальный URL вебхука для каждого активного пайплайна. Поле context.webhookUrl содержит этот URL во время вызова onEnable.

Polling-триггеры

Polling-триггеры вызываются по расписанию. Используйте context.store для отслеживания метки времени последнего опроса или курсора, затем запрашивайте только новые события.

Жизненный цикл

Pipeline Activated → onEnable(context) → (register webhook / store cursor)
                                              ↓
Event Received   → run(context)        → returns event[]
                                              ↓
Pipeline Stopped → onDisable(context)  → (unregister webhook / cleanup)

OnEnableResult

onEnable может опционально возвращать объект с внешним ID вебхука для отслеживания:

interface OnEnableResult {
  readonly externalWebhookId?: string;
}

TriggerContext

interface TriggerContext<TAuth = unknown, TProps = unknown> {
  readonly auth: TAuth;
  readonly propsValue: TProps;
  readonly store: StoreContext;
  readonly webhookUrl?: string;
  readonly payload?: unknown;
}
ПолеТипОписание
authTAuthУчётные данные аутентификации.
propsValueTPropsРазрешённые значения свойств.
storeStoreContextПерсистентное key-value хранилище.
webhookUrlstring | undefinedСгенерированный URL вебхука. Доступен в onEnable для webhook-триггеров.
payloadunknown | undefinedСырые данные входящего события. Доступны в run для webhook-триггеров.

Правила валидации

  • Формат имени -- должен соответствовать /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/ (непустой snake_case)
  • Некорректные имена вызывают Error при создании

Пример webhook-триггера

import {
  createTrigger,
  TRIGGER_TYPES,
  ConnectorError,
} from "@triggo/connector-sdk";
import { CONNECTOR_ERROR_CODES } from "@triggo/shared";

export const newOrder = createTrigger({
  name: "new_order",
  displayName: "New Order",
  description: "Triggers when a new order is created in the shop.",
  props: {},
  type: TRIGGER_TYPES.WEBHOOK,
  outputSchema: {
    type: "object",
    properties: {
      orderId: { type: "string" },
      amount: { type: "number" },
      currency: { type: "string" },
    },
    required: ["orderId", "amount", "currency"],
  },
  sampleData: { orderId: "ORD-001", amount: 4999, currency: "RUB" },

  async onEnable(context) {
    const auth = context.auth as { secret: string };
    const response = await fetch("https://api.shop.com/webhooks", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${auth.secret}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        url: context.webhookUrl,
        events: ["order.created"],
      }),
    });

    if (!response.ok) {
      throw new ConnectorError(
        CONNECTOR_ERROR_CODES.UPSTREAM_ERROR,
        "Failed to register webhook",
      );
    }

    const { id } = (await response.json()) as { id: string };
    await context.store.put("webhookId", id);
    return { externalWebhookId: id };
  },

  async onDisable(context) {
    const webhookId = (await context.store.get("webhookId")) as string | null;
    if (webhookId) {
      const auth = context.auth as { secret: string };
      await fetch(`https://api.shop.com/webhooks/${webhookId}`, {
        method: "DELETE",
        headers: { Authorization: `Bearer ${auth.secret}` },
      });
      await context.store.delete("webhookId");
    }
  },

  async run(context) {
    const payload = context.payload as Record<string, unknown>;
    return [
      {
        orderId: payload["id"],
        amount: payload["amount"],
        currency: payload["currency"],
      },
    ];
  },
});

Пример polling-триггера

import { createTrigger, TRIGGER_TYPES } from "@triggo/connector-sdk";

export const newItem = createTrigger({
  name: "new_item",
  displayName: "New Item",
  description: "Polls for new items every interval.",
  props: {},
  type: TRIGGER_TYPES.POLLING,

  async onEnable(context) {
    await context.store.put("lastPollTime", new Date().toISOString());
  },

  async onDisable(context) {
    await context.store.delete("lastPollTime");
  },

  async run(context) {
    const auth = context.auth as { secret: string };
    const since = ((await context.store.get("lastPollTime")) as string) ?? new Date(0).toISOString();

    const response = await fetch(
      `https://api.example.com/items?since=${since}`,
      { headers: { Authorization: `Bearer ${auth.secret}` } },
    );
    const items = (await response.json()) as unknown[];

    await context.store.put("lastPollTime", new Date().toISOString());
    return items;
  },
});

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

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

Аутентификация

Справочник по ConnectorAuth — четыре типа аутентификации для коннекторов, включая OAuth2, SecretText, CustomAuth и None.

On this page

Создание триггераСигнатураTriggerConfigТипы триггеровWebhook-триггерыPolling-триггерыЖизненный циклOnEnableResultTriggerContextПравила валидацииПример webhook-триггераПример polling-триггера