Connettore Supabase

Collega il tuo progetto Supabase per sincronizzare record del database, dati di autenticazione utente, eventi di file storage e modifiche in real-time per l’automazione dell’engagement cliente.

Panoramica

Funzionalità

• REST API auto-generata, Operazioni CRUD su qualsiasi tabella Postgres tramite PostgREST, senza codice
• Sync utenti Auth, Sincronizza utenti Supabase Auth (email, telefono, login social) sulla tua piattaforma di engagement
• Sottoscrizioni real-time, Ascolta eventi INSERT, UPDATE, DELETE su qualsiasi tabella in real-time
• Row Level Security, Tutti gli accessi API rispettano le policy RLS di Postgres per dati multi-tenant sicuri
• Integrazione Storage, Traccia gli upload di file e gestisci asset nei bucket Storage
• Edge Functions, Invoca funzioni serverless Deno per logica personalizzata e webhook
• Full-text search, Sfrutta le capacità di full-text search di Postgres tramite l’API

Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un progetto Supabase (app.supabase.com)
2. L’API URL e le API key del progetto (in Settings → API)
3. Un account Tajo con accesso API

Autenticazione

Supabase usa l’autenticazione tramite API key. Ogni richiesta richiede l’header apikey e, opzionalmente, un bearer token Authorization per l’accesso con scope utente.

# Usando la anon key (rispetta RLS)
curl 'https://<project_ref>.supabase.co/rest/v1/customers' \
  -H "apikey: <SUPABASE_ANON_KEY>" \
  -H "Authorization: Bearer <SUPABASE_ANON_KEY>"

# Usando la service_role key (bypassa RLS)
curl 'https://<project_ref>.supabase.co/rest/v1/customers' \
  -H "apikey: <SUPABASE_SERVICE_ROLE_KEY>" \
  -H "Authorization: Bearer <SUPABASE_SERVICE_ROLE_KEY>"

Configurazione

Setup di base

connectors:
  supabase:
    enabled: true
    project_url: "https://xyzcompany.supabase.co"
    api_key: "${SUPABASE_SERVICE_ROLE_KEY}"

    # Opzioni di sync dei dati
    sync:
      users: true
      tables:
        - customers
        - orders
        - products
      storage: true
      realtime: true

    # Mappa utenti Supabase Auth su contatti
    user_mapping:
      email: email
      phone: SMS
      user_metadata.full_name: FIRSTNAME
      created_at: SIGNUP_DATE

Mapping dei campi

Mappa le colonne delle tabelle Supabase sugli attributi della piattaforma di engagement:

Mapping tabelle personalizzato

table_mapping:
  customers:
    # Mapping colonna → attributo
    email: email
    full_name: FIRSTNAME
    company: COMPANY
    plan: SUBSCRIPTION_PLAN
    mrr: MONTHLY_REVENUE
    created_at: SIGNUP_DATE

  orders:
    # Traccia come eventi
    sync_as: events
    event_name: "order_placed"
    properties:
      total: amount
      status: order_status
      items: line_items

Endpoint API

La REST API di Supabase è auto-generata dallo schema del tuo database su https://<ref>.supabase.co/rest/v1/.

Operatori di filtro

Eventi

Eventi Auth

Eventi del database (Realtime)

Eventi webhook

Esempi di codice

Inizializzare il connettore

import { TajoClient } from '@tajo/sdk';
import { createClient } from '@supabase/supabase-js';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
});

// Collega il progetto Supabase
await tajo.connectors.connect('supabase', {
  projectUrl: process.env.SUPABASE_URL,
  serviceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY,
});

Sincronizzare gli utenti come contatti

// Sincronizza tutti gli utenti Supabase Auth come contatti
await tajo.connectors.sync('supabase', {
  type: 'full',
  resources: ['users'],
});

// Sync incrementale (solo utenti nuovi/modificati)
await tajo.connectors.sync('supabase', {
  type: 'incremental',
  resources: ['users'],
  since: '2024-01-01T00:00:00Z',
});

Ascoltare i cambiamenti in real-time

// Sottoscrivi i nuovi ordini per attivare l'engagement
const supabase = createClient(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_SERVICE_ROLE_KEY
);

supabase
  .channel('orders')
  .on('postgres_changes',
    { event: 'INSERT', schema: 'public', table: 'orders' },
    async (payload) => {
      // Inoltra a Tajo come evento
      await tajo.events.track({
        email: payload.new.customer_email,
        event: 'order_placed',
        properties: {
          order_id: payload.new.id,
          total: payload.new.total,
          items: payload.new.line_items,
        },
      });
    }
  )
  .subscribe();

Query e segmentazione

// Interroga i clienti per piano per campagne mirate
const { data: proUsers } = await supabase
  .from('customers')
  .select('email, full_name, plan, mrr')
  .eq('plan', 'pro')
  .gt('mrr', 100)
  .order('mrr', { ascending: false });

// Sincronizza su una lista Brevo per il targeting della campagna
await tajo.lists.addContacts(PRO_LIST_ID, proUsers);

Limiti di rate

Risoluzione dei problemi

Problemi comuni

Modalità debug

connectors:
  supabase:
    debug: true
    log_level: verbose
    log_queries: true
    log_realtime: true

Testare la connessione

tajo connectors test supabase
# ✓ Connessione API riuscita
# ✓ Endpoint Auth accessibile
# ✓ Tabelle leggibili (12 tabelle trovate)
# ✓ Storage accessibile (3 bucket)
# ✓ Connessione Realtime stabilita
# ✓ Edge Functions disponibili (4 funzioni)

Best practice

1. Usa la service_role key solo server-side, Non esporla mai nel codice client
2. Abilita RLS su tutte le tabelle, Anche con service_role, progetta con RLS per difesa in profondità
3. Usa Realtime per sync event-driven, Più efficiente del polling per i cambiamenti
4. Operazioni in batch, Usa inserti bulk e il filtro in per operazioni ad alto volume
5. Mappa i metadati utente, Memorizza campi rilevanti per l’engagement in user_metadata durante il signup
6. Usa Edge Functions per i webhook, Elabora webhook in ingresso con Edge Functions Supabase per bassa latenza

Sicurezza

• Autenticazione API key, Tutte le richieste richiedono API key valide
• Row Level Security (RLS), Controllo di accesso Postgres-native per riga
• Verifica JWT, I token Auth sono JWT firmati verificati a ogni richiesta
• SSL/TLS, Tutte le connessioni cifrate in transito
• SOC 2 Type II, Supabase è conforme SOC 2
• Restrizioni di rete, IP allowlisting opzionale sui piani a pagamento

Risorse correlate

• Connettore Shopify
• Connettore Stripe
• Connettore Auth0
• Documentazione ufficiale Supabase
• Guida REST API Supabase
• Guida Supabase Auth