SDK

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

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

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

Пространство имён ConnectorAuth предоставляет четыре фабричных метода для объявления способа аутентификации пользователей в коннекторе. Каждый возвращает замороженный AuthDefinition, который передаётся в createConnector().

import { ConnectorAuth, AUTH_TYPES } from "@triggo/connector-sdk";

Константа AUTH_TYPES

const AUTH_TYPES = {
  OAUTH2: "OAUTH2",
  SECRET_TEXT: "SECRET_TEXT",
  CUSTOM: "CUSTOM",
  NONE: "NONE",
} as const;

ConnectorAuth.OAuth2

Для сервисов, поддерживающих поток авторизации OAuth 2.0 (authorization code flow).

const auth = ConnectorAuth.OAuth2({
  authUrl: "https://service.com/oauth/authorize",
  tokenUrl: "https://service.com/oauth/token",
  scope: ["read", "write"],
  pkce: true,
  extraProps: {
    domain: Property.ShortText({
      displayName: "Domain",
      description: "Your account subdomain (e.g., mycompany).",
      required: true,
    }),
  },
  validateExtraProps: (props) => {
    if (!props["domain"]) {
      throw new Error("Domain is required");
    }
  },
});

Поля конфигурации OAuth2

ПолеТипОбязательноОписание
authUrlstringДаURL эндпоинта авторизации OAuth2.
tokenUrlstringДаURL эндпоинта обмена токенами OAuth2.
scopereadonly string[]ДаЗапрашиваемые OAuth2-скоупы.
pkcebooleanНетВключить PKCE (Proof Key for Code Exchange). Рекомендуется для публичных клиентов.
extraPropsRecord<string, PropertyDefinition>НетДополнительные поля, которые пользователь должен указать перед OAuth-потоком (например, домен, регион).
validateExtraProps(props: Record<string, string>) => voidНетСинхронная валидация дополнительных свойств. Выбросьте исключение для отклонения.

OAuth2Credentials

Когда выполняется функция run коннектора с OAuth2, context.auth имеет следующую форму:

interface OAuth2Credentials {
  readonly accessToken: string;
  readonly refreshToken: string;
  readonly tokenType: string;
  readonly expiresIn?: number;
  readonly claimedAt: number;
  readonly props?: Record<string, string>;
  readonly data?: Record<string, unknown>;
}
ПолеТипОписание
accessTokenstringТекущий токен доступа. Triggo автоматически обновляет его.
refreshTokenstringТокен обновления для получения новых токенов доступа.
tokenTypestringТип токена, обычно "Bearer".
expiresInnumberВремя жизни токена в секундах (из ответа токена).
claimedAtnumberUnix-метка времени (мс), когда токен был выпущен.
propsRecord<string, string>Значения из extraProps (например, { domain: "mycompany" }).
dataRecord<string, unknown>Нечувствительные данные из ответа токена (зарезервировано для будущего использования).

ConnectorAuth.SecretText

Для сервисов, использующих один API-ключ, токен или секретную строку.

const auth = ConnectorAuth.SecretText({
  displayName: "API Key",
  description: "Your API key from the service dashboard.",
  validate: async (authValue) => {
    const response = await fetch("https://api.example.com/me", {
      headers: { Authorization: `Bearer ${authValue.secret}` },
    });
    if (!response.ok) {
      throw new Error("Invalid API key");
    }
  },
});

Поля конфигурации SecretText

ПолеТипОбязательноОписание
displayNamestringДаМетка, отображаемая в интерфейсе подключения.
descriptionstringНетВспомогательный текст, объясняющий, где найти секрет.
validate(auth: { secret: string }) => Promise<void>НетАсинхронная функция валидации. Выбросьте исключение для отклонения учётных данных.

Во время выполнения context.auth имеет форму { secret: string }.

ConnectorAuth.CustomAuth

Для сервисов, требующих нескольких полей (например, логин + пароль или домен + API-ключ).

const auth = ConnectorAuth.CustomAuth({
  props: {
    apiKey: Property.SecretText({
      displayName: "API Key",
      description: "Your API key.",
      required: true,
    }),
    region: Property.Dropdown({
      displayName: "Region",
      description: "Data center region.",
      required: true,
      options: [
        { label: "US", value: "us" },
        { label: "EU", value: "eu" },
      ],
    }),
  },
  validate: async (authValue) => {
    const apiKey = authValue["apiKey"] as string;
    const region = authValue["region"] as string;
    const response = await fetch(`https://${region}.api.example.com/verify`, {
      headers: { "X-Api-Key": apiKey },
    });
    if (!response.ok) {
      throw new Error("Invalid credentials");
    }
  },
});

Поля конфигурации CustomAuth

ПолеТипОбязательноОписание
propsRecord<string, PropertyDefinition>ДаПользовательские поля с использованием системы Property.
validate(auth: Record<string, unknown>) => Promise<void>НетАсинхронная валидация. Получает разрешённые значения свойств. Выбросьте исключение для отклонения.

Во время выполнения context.auth -- это Record<string, unknown> с ключами, соответствующими именам свойств.

ConnectorAuth.None

Для коннекторов, не требующих аутентификации (например, публичные API, входящие вебхуки).

const auth = ConnectorAuth.None();

Конфигурация не требуется. Во время выполнения context.auth равен undefined.

Выбор типа аутентификации

СценарийТип аутентификации
Сервис использует OAuth2 (например, AmoCRM, Google)ConnectorAuth.OAuth2
Сервис использует один API-ключ или токен ботаConnectorAuth.SecretText
Сервис требует несколько учётных данных (например, домен + ключ)ConnectorAuth.CustomAuth
Аутентификация не нужна (публичный API, входящий вебхук)ConnectorAuth.None

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

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

Свойства

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

On this page

АутентификацияКонстанта AUTH_TYPESConnectorAuth.OAuth2Поля конфигурации OAuth2OAuth2CredentialsConnectorAuth.SecretTextПоля конфигурации SecretTextConnectorAuth.CustomAuthПоля конфигурации CustomAuthConnectorAuth.NoneВыбор типа аутентификации