Connectors

Uygulamanı Slack, Resend ve ElevenLabs gibi üçüncü taraf servislerle bağla. Kimlik bilgileri şifrelenir ve işlemler önceden doğrulanır.

Connector’lar, kod içinde ham API anahtarlarını yönetmeden harici servisleri uygulamanla entegre etmeni sağlar. Bir bağlantıyı bir kez kurarsın, projenle ilişkilendirirsin ve Proyecta SDK aracılığıyla uygulamandan hazır işlemleri çağırırsın. Kimlik bilgileri depolanırken şifrelenir ve frontend koduna hiçbir zaman açık edilmez.

Mevcut connector’lar

Connector	Kategori	Kimlik doğrulama türü	Ne yapar
Resend	İletişim	API anahtarı	İşlemsel e-posta gönder, toplu e-posta gönder, doğrulanmış domainleri listele
Slack	İletişim	OAuth	Mesaj gönder, kanal ve kullanıcıları listele, mesajlara tepki ver, thread’leri oku
ElevenLabs	Yapay Zeka	API anahtarı	Metinden sese dönüştürme, mevcut sesleri listele, ses efekti üret

Daha fazla connector düzenli olarak eklenmektedir.

Connector’lar nasıl çalışır

1. Bir bağlantı oluşturursun — kimlik bilgilerini sağlarsın (API anahtarı ya da OAuth ile giriş yaparsın)
2. Bağlantıyı bir projeyle ilişkilendirirsin — bu, projenin söz konusu kimlik bilgilerini kullanmasına yetki verir
3. Uygulamanın işlemleri çağırır — SDK, isteği Proyecta Cloud üzerinden gönderir; Proyecta Cloud kimlik bilgilerini sunucu tarafında enjekte eder

Uygulama kodun ham API anahtarına veya OAuth token’ına hiçbir zaman dokunmaz. Connector sistemi kimlik doğrulama, hız sınırlama ve denetim günlüğünü yönetir.

Bir connector kurma

1. Projeyi builder’da aç
2. Settings > Connectors bölümüne git
3. Katalogdan bir connector’a tıkla (örneğin Resend)
4. Kimlik bilgilerini gir:
   • API anahtarı connector’ları (Resend, ElevenLabs): Gizli anahtarını yapıştır
   • OAuth connector’ları (Slack): Giriş yap ve erişimi yetkilendir
5. Bağlantıya bir isim ver (örneğin “Production Resend”)
6. Bağlantı otomatik olarak test edilir ve geçerliyse Active olarak işaretlenir

Uygulamanda bir connector kullanma

Connector işlemleri, Proyecta SDK kullanılarak sunucu tarafı kodundan (Convex actions) çağrılır:

'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 metodu şunları döndürür:

Alan	Açıklama
output	İşlemin döndürdüğü değer (şekli işleme göre değişir)
durationMs	Milisaniye cinsinden yürütme süresi
invocationId	Denetim günlüğü giriş kimliği

Yapay zekaya bırak

Connector kodunu elle yazmak zorunda değilsin. AI builder, projenle hangi connector’ların ilişkilendirildiğini bilir ve entegrasyonu senin için üretebilir:

• "Kullanıcılar kayıt olduğunda karşılama e-postası gönder" — Resend connector’ını kullanır
• "Yeni bir sipariş geldiğinde Slack mesajı gönder" — Slack connector’ını kullanır
• "Makale sayfasında sesli anlatım oynat" — ElevenLabs connector’ını kullanır

Connector işlemleri referansı

Resend

İşlem	Yan etkiler	Açıklama
sendEmail	yazma	Tek bir işlemsel e-posta gönder
sendBatch	yazma	Birden fazla e-postayı aynı anda gönder
listDomains	okuma	Doğrulanmış gönderim domainlerini listele

Slack

İşlem	Yan etkiler	Açıklama
postMessage	yazma	Bir kanala mesaj gönder
listChannels	okuma	Çalışma alanındaki kanalları listele
listUsers	okuma	Çalışma alanı üyelerini listele
reactToMessage	yazma	Emoji tepkisi ekle
getThread	okuma	Bir thread’deki yanıtları getir

ElevenLabs

İşlem	Yan etkiler	Açıklama
textToSpeech	yazma	Metni konuşma sesine dönüştür
listVoices	okuma	Mevcut sesleri listele
generateSoundEffect	yazma	Yapay zeka ile ses efekti üret

Bağlantı durumları

Durum	Anlamı
Active	Kimlik bilgileri geçerli ve bağlantı kullanıma hazır
Broken	Kimlik bilgilerinin süresi dolmuş veya iptal edilmiş — geri yüklemek için güncelle

Güvenlik

• Kimlik bilgileri depolanırken AES-256-GCM ile şifrelenir
• İşlemler, proje başına connector başına dakikada 1.000 istekle hız sınırlamasına tabidir
• Her işlem çağrısı denetim izi ile günlüğe kaydedilir (bağlantı, işlem, süre, durum)
• Bağlantılar tüm çalışma alanına kapsamlandırılmıştır

SSS

Aynı bağlantıyı birden fazla projede kullanabilir miyim?

Evet. Bağlantıyı bir kez oluştur ve aynı çalışma alanındaki istediğin kadar projeyle ilişkilendir.

API anahtarımın süresi dolarsa veya iptal edilirse ne olur?

Bağlantı durumu Broken olarak değişir. Geri yüklemek için Settings > Connectors bölümünden kimlik bilgilerini güncelle.

Connector işlemlerini frontend’den çağırabilir miyim?

Hayır. Kimlik bilgilerini güvende tutmak için connector işlemleri sunucu tarafı kodundan (Convex actions) çağrılmalıdır. SDK, Proyecta Cloud üzerinden yönlendirir; Proyecta Cloud kimlik doğrulamayı sunucu tarafında enjekte eder.

Kendi özel connector’larımı ekleyebilir miyim?

Henüz değil. Özel connector tanımları yol haritasında yer almaktadır.

Yakında

• Ek connector’lar (Google, Twilio, SendGrid ve daha fazlası)
• Özel connector tanımları — kendi API’nı getir
• Bağlı servislerden gelen olaylar için webhook alımı
• OAuth gateway — istemci tarafından başlatılan akışlarda bile token’ları sunucu tarafında tut