Connectors

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

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

Connectorهای موجود

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

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

نحوه کارکرد Connectors

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

کد اپ تو هرگز با 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 در اپ

اپ تو می‌تواند یک API شخص ثالث را مستقیماً از داخل مرورگر بخواند، بدون اینکه API key هرگز به bundle برسد. اعتبارنامه به‌صورت رمزگذاری‌شده روی پلتفرم می‌ماند؛ اپ تو فقط نام connector، نام اکشن و یک ورودی typed را می‌دهد و پلتفرم فراخوانی را برایت انجام می‌دهد.

import { useConnectorData, useHttpRead } from '@/hooks/useConnector.ts';

// A connector's own read action, as a cached query
const { data, isLoading, error } = useConnectorData('eleven-labs', 'listVoices');

// The generic HTTP-read connector, by endpoint name
const { data: feed } = useHttpRead('news-feed', { limit: 10 });

دو محافظ ارزش دانستن دارند، چون عمدی هستند:

• فقط خواندن. تنها اکشن‌هایی که پلتفرم آن‌ها را ایمن‌برای‌مرورگر علامت زده در دسترس هستند — هر چیز دیگری 403 برمی‌گرداند. نوشتن‌ها (ارسال پیام در Slack، فرستادن ایمیل، برداشت از کارت) هرگز از مرورگر قابل دسترسی نیستند.
• نمی‌توانی URL یا host پاس بدهی. برای connector عمومی http-read ورودی برابر { endpointKey, params } است، و URL پشت endpointKey را تو، یعنی مالک اپ، پیکربندی می‌کنی — نه کد اپ. پاسخ‌ها در سمت سرور cache می‌شوند و rate limit دارند، چون کلیدهای شخص ثالث سهمیه‌بندی‌شده‌اند.

یک 404 یعنی مالک هنوز آن connector را متصل نکرده است — همان حالتی که ارزش دارد در UI خودت مدیریتش کنی.

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

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

• "Send a welcome email when users sign up" — از Resend connector استفاده می‌کند
• "Post a Slack message when a new order comes in" — از Slack connector استفاده می‌کند
• "Play audio narration on the article page" — از ElevenLabs connector استفاده می‌کند

مرجع اکشن‌های Connector

Resend (connectorId: 'resend')

اکشن	تأثیرات جانبی	توضیحات
sendEmail	write	ارسال یک ایمیل تراکنشی تکی
sendBatch	write	ارسال چندین ایمیل به‌صورت همزمان
listDomains	read	فهرست دامنه‌های ارسال تأییدشده

Slack (connectorId: 'slack')

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

ElevenLabs (connectorId: 'eleven-labs')

اکشن	تأثیرات جانبی	توضیحات
textToSpeech	write	تبدیل متن به صوت گفتار
listVoices	read	فهرست صداهای موجود
generateSoundEffect	write	تولید یک جلوه صوتی با هوش مصنوعی

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

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

امنیت

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

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

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

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

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

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

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

اپ تو هرگز اعتبارنامه‌ها را در اختیار ندارد. اکشن‌های خواندنیِ ایمن‌برای‌مرورگر از طریق Proyecta Cloud پروکسی می‌شوند، که اعتبارنامه‌ها را در سمت سرور تزریق می‌کند، بنابراین کلید هرگز در bundle تو نیست. اکشن‌های نوشتن اصلاً از مرورگر قابل دسترسی نیستند.

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

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

به‌زودی

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