Connectors

Подключайте приложение к сторонним сервисам — Slack, Resend и ElevenLabs. Учётные данные шифруются, а действия предварительно аутентифицированы.

Connectors позволяют интегрировать внешние сервисы в твоё приложение без необходимости хранить API-ключи в коде. Ты настраиваешь подключение один раз, привязываешь его к проекту и вызываешь готовые действия из приложения через Proyecta SDK. Учётные данные хранятся в зашифрованном виде и никогда не попадают во frontend-код.

Доступные connectors

Connector	Категория	Тип аутентификации	Что умеет
Resend	Коммуникации	API key	Отправка транзакционных писем, массовая рассылка, список верифицированных доменов
Slack	Коммуникации	OAuth	Отправка сообщений, список каналов и пользователей, реакции на сообщения, чтение тредов
ElevenLabs	ИИ	API key	Преобразование текста в речь, список доступных голосов, генерация звуковых эффектов

Новые connectors добавляются регулярно.

Как работают connectors

1. Ты создаёшь подключение — вводишь учётные данные (API key или вход через OAuth)
2. Привязываешь подключение к проекту — это разрешает проекту использовать эти учётные данные
3. Приложение вызывает действия — SDK отправляет запрос через Proyecta Cloud, который подставляет учётные данные на стороне сервера

Код приложения никогда не касается сырого API-ключа или OAuth-токена. Система connectors берёт на себя аутентификацию, ограничение запросов и audit-логирование.

Настройка connector

1. Открой свой проект в Builder
2. Перейди в Settings > Connectors
3. Выбери connector из каталога (например, Resend)
4. Введи учётные данные:
   • Connectors с API key (Resend, ElevenLabs): вставь свой секретный ключ
   • OAuth-connectors (Slack): войди в аккаунт и разреши доступ
5. Дай подключению имя (например, «Production Resend»)
6. Подключение автоматически проверяется и получает статус Active, если всё в порядке

Использование connector в приложении

Действия connectors вызываются из серверного кода (Convex actions) с помощью Proyecta SDK:

'use node';
import { action } from './_generated/server';
import { v } from 'convex/values';
import Proyecta from '@proyecta-ai/sdk';

const proyecta = new Proyecta({ apiKey: process.env.PROYECTA_API_KEY ?? null });

export const notifySlack = action({
    args: {
        message: v.string(),
    },
    handler: async (ctx, args) => {
        const result = await proyecta.connectors.execute({
            connectorId: 'slack',
            actionId: 'postMessage',
            input: {
                channel: '#general',
                text: args.message,
            },
        });
        return result.output;
    },
});

Метод execute возвращает:

Поле	Описание
output	Возвращаемое значение действия (структура зависит от действия)
durationMs	Время выполнения в миллисекундах
invocationId	Идентификатор записи в audit-логе

Пусть ИИ сам всё подключит

Писать код для connector вручную необязательно. Builder знает, какие connectors привязаны к твоему проекту, и может сгенерировать интеграцию самостоятельно:

• "Send a welcome email when users sign up" — использует connector Resend
• "Post a Slack message when a new order comes in" — использует connector Slack
• "Play audio narration on the article page" — использует connector ElevenLabs

Справочник по действиям connectors

Resend

Действие	Побочные эффекты	Описание
sendEmail	write	Отправить одно транзакционное письмо
sendBatch	write	Отправить несколько писем за раз
listDomains	read	Список верифицированных отправляющих доменов

Slack

Действие	Побочные эффекты	Описание
postMessage	write	Отправить сообщение в канал
listChannels	read	Список каналов в воркспейсе
listUsers	read	Список участников воркспейса
reactToMessage	write	Добавить эмодзи-реакцию
getThread	read	Получить ответы в треде

ElevenLabs

Действие	Побочные эффекты	Описание
textToSpeech	write	Преобразовать текст в аудио
listVoices	read	Список доступных голосов
generateSoundEffect	write	Сгенерировать звуковой эффект с помощью ИИ

Статусы подключений

Статус	Значение
Active	Учётные данные действительны, подключение готово к использованию
Broken	Учётные данные истекли или были отозваны — обнови их, чтобы восстановить подключение

Безопасность

• Учётные данные шифруются по алгоритму AES-256-GCM в состоянии покоя
• Действия ограничены 1 000 запросов в минуту на один connector на один проект
• Каждый вызов действия записывается в audit-лог (подключение, действие, продолжительность, статус)
• Подключения действуют в рамках всего воркспейса

Часто задаваемые вопросы

Можно ли использовать одно подключение в нескольких проектах?

Да. Создай подключение один раз и привяжи его к любому количеству проектов в одном воркспейсе.

Что произойдёт, если мой API key истечёт или будет отозван?

Статус подключения изменится на Broken. Обнови учётные данные в Settings > Connectors, чтобы восстановить его.

Можно ли вызывать действия connector из frontend?

Нет. Действия connectors необходимо вызывать из серверного кода (Convex actions), чтобы учётные данные оставались в безопасности. SDK маршрутизирует запросы через Proyecta Cloud, который подставляет аутентификацию на стороне сервера.

Можно ли добавить собственные connectors?

Пока нет. Поддержка пользовательских connectors есть в roadmap.

Скоро

• Новые connectors (Google, Twilio, SendGrid и другие)
• Пользовательские connector-определения — подключай собственные API
• Приём вебхуков для входящих событий от подключённых сервисов
• OAuth gateway — токены остаются на сервере даже при потоках, инициированных клиентом