Connectors

اپ خود را به سرویس‌های شخص ثالث مانند Slack، Resend و ElevenLabs متصل کنید. اعتبارنامه‌ها رمزگذاری شده و اقدامات از پیش احراز هویت‌شده هستند.

Connectors به شما امکان می‌دهند سرویس‌های خارجی را بدون نیاز به مدیریت مستقیم API keyها در کد، در اپ خود یکپارچه کنید. یک بار اتصال را راه‌اندازی می‌کنید، آن را به پروژه‌تان متصل می‌کنید، و از طریق Proyecta SDK اقدامات از پیش ساخته‌شده را از اپ فراخوانی می‌کنید. اعتبارنامه‌ها در حالت استراحت رمزگذاری شده‌اند و هرگز در معرض کد frontend شما قرار نمی‌گیرند.

Connectorهای موجود

Connector	دسته‌بندی	نوع احراز هویت	کارایی
Resend	ارتباطات	API key	ارسال ایمیل تراکنشی، ارسال دسته‌ای ایمیل، فهرست دامنه‌های تأییدشده
Slack	ارتباطات	OAuth	ارسال پیام، فهرست کانال‌ها و کاربران، واکنش به پیام‌ها، خواندن thread‌ها
ElevenLabs	هوش مصنوعی	API key	تبدیل متن به گفتار، فهرست صداهای موجود، تولید جلوه‌های صوتی

Connectorهای بیشتری به‌طور منظم در حال اضافه شدن هستند.

نحوه عملکرد Connectorها

1. یک اتصال ایجاد می‌کنید — اعتبارنامه‌ها را وارد می‌کنید (یک API key یا ورود از طریق OAuth)
2. اتصال را به یک پروژه متصل می‌کنید — این کار به پروژه اجازه می‌دهد از آن اعتبارنامه‌ها استفاده کند
3. اپ شما اقدامات را فراخوانی می‌کند — SDK درخواست را از طریق Proyecta Cloud ارسال می‌کند، که اعتبارنامه‌ها را در سمت server تزریق می‌کند

کد اپ شما هرگز با API key خام یا OAuth token در تماس نیست. سیستم connector احراز هویت، rate limiting و audit logging را مدیریت می‌کند.

راه‌اندازی یک Connector

1. پروژه‌تان را در builder باز کنید
2. به Settings > Connectors بروید
3. روی یک connector از کاتالوگ کلیک کنید (مثلاً Resend)
4. اعتبارنامه‌هایتان را وارد کنید:
   • Connectorهای API key (Resend، ElevenLabs): کلید مخفی خود را paste کنید
   • Connectorهای OAuth (Slack): وارد شوید و دسترسی را مجاز کنید
5. یک نام برای اتصال انتخاب کنید (مثلاً «Production Resend»)
6. اتصال به‌طور خودکار آزمایش می‌شود و در صورت معتبر بودن Active علامت‌گذاری می‌شود

استفاده از یک Connector در اپ

اقدامات connector از کد سمت server (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 log

بگذارید هوش مصنوعی آن را سیم‌کشی کند

لازم نیست کد connector را به‌صورت دستی بنویسید. AI builder می‌داند کدام connectorها به پروژه‌تان متصل هستند و می‌تواند یکپارچه‌سازی را برای شما تولید کند:

• "وقتی کاربران ثبت‌نام می‌کنند یک ایمیل خوش‌آمدگویی بفرست" — از Resend connector استفاده می‌کند
• "وقتی سفارش جدیدی می‌آید یک پیام Slack بفرست" — از Slack connector استفاده می‌کند
• "در صفحه مقاله روایت صوتی پخش کن" — از ElevenLabs connector استفاده می‌کند

مرجع اقدامات Connector

Resend

اقدام	عوارض جانبی	توضیحات
sendEmail	نوشتن	ارسال یک ایمیل تراکنشی تکی
sendBatch	نوشتن	ارسال چند ایمیل به‌یک‌باره
listDomains	خواندن	فهرست دامنه‌های ارسال تأییدشده

Slack

اقدام	عوارض جانبی	توضیحات
postMessage	نوشتن	ارسال پیام به یک کانال
listChannels	خواندن	فهرست کانال‌های workspace
listUsers	خواندن	فهرست اعضای workspace
reactToMessage	نوشتن	اضافه کردن واکنش emoji
getThread	خواندن	دریافت پاسخ‌های یک thread

ElevenLabs

اقدام	عوارض جانبی	توضیحات
textToSpeech	نوشتن	تبدیل متن به صدا
listVoices	خواندن	فهرست صداهای موجود
generateSoundEffect	نوشتن	تولید جلوه صوتی با هوش مصنوعی

وضعیت‌های اتصال

وضعیت	معنا
Active	اعتبارنامه‌ها معتبر هستند و اتصال آماده استفاده است
Broken	اعتبارنامه‌ها منقضی شده یا لغو شده‌اند — برای بازیابی آن‌ها را به‌روز کنید

امنیت

• اعتبارنامه‌ها با AES-256-GCM در حالت استراحت رمزگذاری می‌شوند
• اقدامات به ۱٬۰۰۰ درخواست در دقیقه به ازای هر connector در هر پروژه محدود هستند
• هر فراخوانی اقدام با یک audit trail ثبت می‌شود (اتصال، اقدام، مدت، وضعیت)
• اتصال‌ها در محدوده کل workspace هستند

سؤالات متداول

آیا می‌توانم از یک اتصال در چند پروژه استفاده کنم؟

بله. یک بار اتصال را ایجاد کنید و آن را به هر تعداد پروژه در همان workspace متصل کنید.

اگر API key من منقضی شود یا لغو شود چه اتفاقی می‌افتد؟

وضعیت اتصال به Broken تغییر می‌کند. برای بازیابی آن، اعتبارنامه‌ها را در Settings > Connectors به‌روز کنید.

آیا می‌توانم اقدامات connector را از frontend فراخوانی کنم؟

خیر. اقدامات connector باید از کد سمت server (Convex actions) فراخوانی شوند تا اعتبارنامه‌ها ایمن بمانند. SDK از طریق Proyecta Cloud مسیریابی می‌کند، که احراز هویت را در سمت server تزریق می‌کند.

آیا می‌توانم connectorهای سفارشی خودم را اضافه کنم؟

هنوز نه. تعاریف connector سفارشی در نقشه راه قرار دارند.

به‌زودی

• Connectorهای بیشتر (Google، Twilio، SendGrid و موارد دیگر)
• تعاریف connector سفارشی — API خودتان را بیاورید
• دریافت Webhook برای رویدادهای ورودی از سرویس‌های متصل
• OAuth gateway — نگه‌داشتن tokenها در سمت server حتی برای جریان‌های آغازشده از client