Connectors

Collega la tua app a servizi di terze parti come Slack, Resend ed ElevenLabs. Le credenziali sono crittografate e le azioni sono pre-autenticate.

I Connectors ti permettono di integrare servizi esterni nella tua app senza dover gestire chiavi API grezze nel codice. Configuri una connessione una volta sola, la associ al tuo progetto e chiami azioni pre-costruite dalla tua app tramite il Proyecta SDK. Le credenziali sono crittografate a riposo e non vengono mai esposte al codice del tuo frontend.

Connectors disponibili

Connector	Categoria	Tipo di autenticazione	Cosa fa
Resend	Comunicazioni	Chiave API	Invia email transazionali, invia email in blocco, elenca i domini verificati
Slack	Comunicazioni	OAuth	Pubblica messaggi, elenca canali e utenti, reagisce ai messaggi, legge i thread
ElevenLabs	AI	Chiave API	Text-to-speech, elenca le voci disponibili, genera effetti sonori

Nuovi connectors vengono aggiunti regolarmente.

Come funzionano i connectors

1. Crei una connessione — fornisci le credenziali (una chiave API o accedi tramite OAuth)
2. Associ la connessione a un progetto — questo autorizza il progetto a utilizzare quelle credenziali
3. La tua app chiama le azioni — l’SDK invia la richiesta attraverso Proyecta Cloud, che iniette le credenziali lato server

Il codice della tua app non entra mai in contatto con la chiave API grezza o il token OAuth. Il sistema dei connectors gestisce autenticazione, rate limiting e audit logging.

Configura un connector

1. Apri il tuo progetto nel builder
2. Vai su Settings > Connectors
3. Clicca su un connector dal catalogo (ad es., Resend)
4. Inserisci le tue credenziali:
   • Connectors con chiave API (Resend, ElevenLabs): Incolla la tua chiave segreta
   • Connectors OAuth (Slack): Accedi e autorizza l’accesso
5. Dai un nome alla connessione (ad es., “Production Resend”)
6. La connessione viene testata automaticamente e contrassegnata come Active se valida

Usa un connector nella tua app

Le azioni dei connectors vengono chiamate da codice lato server (Convex actions) tramite il 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;
    },
});

Il metodo execute restituisce:

Campo	Descrizione
output	Il valore di ritorno dell’azione (la struttura dipende dall’azione)
durationMs	Tempo di esecuzione in millisecondi
invocationId	ID della voce nel log di audit

Lascia che l’AI lo colleghi per te

Non devi scrivere il codice del connector a mano. Il builder AI conosce quali connectors sono associati al tuo progetto e può generare l’integrazione per te:

• "Invia un'email di benvenuto quando gli utenti si registrano" — usa il connector Resend
• "Pubblica un messaggio Slack quando arriva un nuovo ordine" — usa il connector Slack
• "Riproduci la narrazione audio sulla pagina dell'articolo" — usa il connector ElevenLabs

Riferimento alle azioni dei connectors

Resend

Azione	Effetti collaterali	Descrizione
sendEmail	write	Invia una singola email transazionale
sendBatch	write	Invia più email contemporaneamente
listDomains	read	Elenca i domini di invio verificati

Slack

Azione	Effetti collaterali	Descrizione
postMessage	write	Pubblica un messaggio in un canale
listChannels	read	Elenca i canali nel workspace
listUsers	read	Elenca i membri del workspace
reactToMessage	write	Aggiunge una reazione emoji
getThread	read	Recupera le risposte in un thread

ElevenLabs

Azione	Effetti collaterali	Descrizione
textToSpeech	write	Converte testo in audio vocale
listVoices	read	Elenca le voci disponibili
generateSoundEffect	write	Genera un effetto sonoro con l’AI

Stato delle connessioni

Stato	Significato
Active	Le credenziali sono valide e la connessione è pronta all’uso
Broken	Le credenziali sono scadute o sono state revocate — aggiornale per ripristinare la connessione

Sicurezza

• Le credenziali sono crittografate con AES-256-GCM a riposo
• Le azioni sono soggette a rate limiting di 1.000 richieste al minuto per connector per progetto
• Ogni chiamata a un’azione viene registrata con un audit trail (connessione, azione, durata, stato)
• Le connessioni hanno scope sull’intero workspace

FAQ

Posso usare la stessa connessione su più progetti?

Sì. Crea la connessione una volta sola e associala a qualsiasi numero di progetti nello stesso workspace.

Cosa succede se la mia chiave API scade o viene revocata?

Lo stato della connessione cambia in Broken. Aggiorna le credenziali in Settings > Connectors per ripristinarla.

Posso chiamare le azioni dei connectors dal frontend?

No. Le azioni dei connectors devono essere chiamate da codice lato server (Convex actions) per mantenere le credenziali al sicuro. L’SDK instrada le richieste attraverso Proyecta Cloud, che inietta l’autenticazione lato server.

Posso aggiungere connector personalizzati?

Non ancora. Le definizioni di connector personalizzati sono nella roadmap.

Prossimamente

• Connectors aggiuntivi (Google, Twilio, SendGrid e altri)
• Definizioni di connector personalizzati — porta la tua API
• Webhook ingestion per eventi in entrata dai servizi connessi
• OAuth gateway — mantieni i token lato server anche per i flussi avviati dal client