موصل Supabase

اربط مشروع Supabase الخاص بك لمزامنة سجلات قاعدة البيانات، وبيانات مصادقة المستخدمين، وأحداث تخزين الملفات، والتغييرات الآنية لأتمتة تفاعل العملاء.

نظرة عامة

الميزات

• واجهة REST API المُولَّدة تلقائيًا, عمليات CRUD على أي جدول Postgres عبر PostgREST، بدون كود
• مزامنة مستخدمي Auth, مزامنة مستخدمي Supabase Auth (البريد الإلكتروني، الهاتف، تسجيلات الدخول الاجتماعية) مع منصة التفاعل الخاصة بك
• الاشتراكات الآنية, الاستماع إلى أحداث INSERT وUPDATE وDELETE على أي جدول في الوقت الفعلي
• أمان مستوى الصف, يحترم جميع الوصول إلى API سياسات RLS في Postgres لبيانات آمنة متعددة المستأجرين
• تكامل التخزين, تتبع تحميل الملفات وإدارة الأصول عبر دلاء التخزين
• وظائف Edge, استدعاء وظائف Deno بدون خادم لمنطق مخصص وwebhooks
• البحث النصي الكامل, الاستفادة من إمكانيات البحث النصي الكامل في Postgres عبر API

المتطلبات الأساسية

قبل البدء، تأكد من توفر ما يلي:

1. مشروع Supabase (app.supabase.com)
2. عنوان URL الخاص بـ API ومفاتيح API لمشروعك (موجودة في Settings → API)
3. حساب Tajo مع وصول إلى API

المصادقة

يستخدم Supabase مصادقة مفتاح API. يتطلب كل طلب ترويسة apikey واختياريًا رمز Authorization bearer للوصول المُقيد بالمستخدم.

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

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

الإعداد

الإعداد الأساسي

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

    # Data sync options
    sync:
      users: true
      tables:
        - customers
        - orders
        - products
      storage: true
      realtime: true

    # Map Supabase Auth users to contacts
    user_mapping:
      email: email
      phone: SMS
      user_metadata.full_name: FIRSTNAME
      created_at: SIGNUP_DATE

تعيين الحقول

ربط أعمدة جداول Supabase بسمات منصة التفاعل:

تعيين جدول مخصص

table_mapping:
  customers:
    # Column → Attribute mapping
    email: email
    full_name: FIRSTNAME
    company: COMPANY
    plan: SUBSCRIPTION_PLAN
    mrr: MONTHLY_REVENUE
    created_at: SIGNUP_DATE

  orders:
    # Track as events
    sync_as: events
    event_name: "order_placed"
    properties:
      total: amount
      status: order_status
      items: line_items

نقاط نهاية واجهة البرمجة

تُولَّد واجهة REST API الخاصة بـ Supabase تلقائيًا من مخطط قاعدة البيانات في https://<ref>.supabase.co/rest/v1/.

عوامل التصفية

الأحداث

أحداث Auth

أحداث قاعدة البيانات (Realtime)

أحداث Webhook

أمثلة على الكود

تهيئة الموصل

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

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

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

مزامنة المستخدمين مع جهات الاتصال

// مزامنة جميع مستخدمي Supabase Auth كجهات اتصال
await tajo.connectors.sync('supabase', {
  type: 'full',
  resources: ['users'],
});

// مزامنة تزايدية (المستخدمون الجدد/المتغيرون فقط)
await tajo.connectors.sync('supabase', {
  type: 'incremental',
  resources: ['users'],
  since: '2024-01-01T00:00:00Z',
});

الاستماع إلى التغييرات الآنية

// الاشتراك في الطلبات الجديدة لمحفزات التفاعل
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) => {
      // إعادة توجيه إلى Tajo كحدث
      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();

الاستعلام والتقسيم

// استعلام العملاء حسب الخطة للحملات المستهدفة
const { data: proUsers } = await supabase
  .from('customers')
  .select('email, full_name, plan, mrr')
  .eq('plan', 'pro')
  .gt('mrr', 100)
  .order('mrr', { ascending: false });

// المزامنة مع قائمة Brevo لاستهداف الحملات
await tajo.lists.addContacts(PRO_LIST_ID, proUsers);

حدود المعدل

استكشاف الأخطاء وإصلاحها

المشاكل الشائعة

وضع التصحيح

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

اختبار الاتصال

tajo connectors test supabase
# ✓ API connection successful
# ✓ Auth endpoint accessible
# ✓ Tables readable (12 tables found)
# ✓ Storage accessible (3 buckets)
# ✓ Realtime connection established
# ✓ Edge Functions available (4 functions)

أفضل الممارسات

1. استخدم مفتاح service_role من جانب الخادم فقط, لا تكشف عنه أبدًا في كود العميل
2. فعّل RLS على جميع الجداول, حتى مع service_role، صمّم بـ RLS للدفاع المتعمق
3. استخدم Realtime للمزامنة القائمة على الأحداث, أكثر كفاءة من الاستطلاع للتغييرات
4. عمليات مُجمّعة, استخدم الإدراجات بالجملة وعامل in للعمليات عالية الحجم
5. عيّن البيانات الوصفية للمستخدم, خزّن الحقول ذات الصلة بالتفاعل في user_metadata أثناء التسجيل
6. استخدم Edge Functions لـ webhooks, عالج webhooks الواردة باستخدام Supabase Edge Functions لمعالجة منخفضة الكمون

الأمان

• مصادقة مفتاح API, تتطلب جميع الطلبات مفاتيح API صالحة
• أمان مستوى الصف (RLS), تحكم في الوصول أصلي في Postgres لكل صف
• التحقق من JWT, رموز Auth هي JWTs موقّعة يتم التحقق منها في كل طلب
• SSL/TLS, جميع الاتصالات مشفرة أثناء النقل
• SOC 2 Type II, Supabase متوافق مع SOC 2
• قيود الشبكة, قائمة IP المسموح بها الاختيارية في الخطط المدفوعة

موارد ذات صلة

• موصل Shopify
• موصل Stripe
• موصل Auth0
• وثائق Supabase الرسمية
• دليل Supabase REST API
• دليل Supabase Auth