SDK للعميل

SDK الرسمي لربط واجهتك بخلفية HeroMate. المصادقة والبيانات والوقت الفعلي ودردشة الذكاء الاصطناعي ورفع الملفات — كلها مكتوبة الأنواع، في حزمة واحدة.

الحزمة الحالية هي @dypai-ai/client-sdk v1.12.0، مع خطافات React تحت @dypai-ai/client-sdk/react.

التثبيت

JavaScript

npm install @dypai-ai/client-sdk

الإعداد

JavaScript

// lib/dypai.ts
import { createClient } from '@dypai-ai/client-sdk'

export const dypai = createClient(
  import.meta.env.VITE_DYPAI_URL,  // https://YOUR_PROJECT_ID.dypai.app
  {
    redirects: {
      passwordRecovery: '/set-password',
      signIn: '/dashboard',
    },
  }
)

تستخدم Next.js بدل Vite؟

اقرأ عنوان URL الأساسي من متغيّر بيئة عام: process.env.NEXT_PUBLIC_DYPAI_URL. القيمة دائماً أصل مشروعك، مثلاً https://YOUR_PROJECT_ID.dypai.app.

لتطبيقات React، غلّف بـ DypaiProvider:

JavaScript

import { DypaiProvider } from '@dypai-ai/client-sdk/react'
import { dypai } from './lib/dypai'

function App() {
  return (
    <DypaiProvider client={dypai}>
      <Router />
    </DypaiProvider>
  )
}

الوحدات

المصادقة

التسجيل وتسجيل الدخول و OAuth و OTP واستعادة كلمة المرور.

البيانات والـ API

استدعِ endpoints بـ get و post و put و delete.

الوقت الفعلي

تغييرات قاعدة البيانات والبث والحضور — تحديثات مباشرة.

دردشة الذكاء الاصطناعي

بث ردود وكيل الذكاء الاصطناعي مع استدعاءات الأدوات.

التخزين

رفع الملفات وتنزيلها عبر endpoints.

إدارة المستخدمين

عمليات الإدارة لإدارة المستخدمين.

خطافات React

JavaScript

import {
  DypaiProvider, useAuth, useEndpoint, useAction,
  useUpload, useChat, useRealtime, useChannel,
  useChannelMessages, useChannels, useChatList,
  ProtectedRoute
} from '@dypai-ai/client-sdk/react'

الخطافات الأساسية

Parameter	Type	Description
`useAuth()`	`Hook`	حالة المصادقة والإجراءات: user و signIn و signUp و signOut و isAuthenticated و isLoading
`useEndpoint(name)`	`Hook`	جلب البيانات من endpoints من نوع GET. يُرجع data و isLoading و error و refetch
`useAction(name)`	`Hook`	استدعاء endpoints من نوع POST/PUT/DELETE. يُرجع mutate و isLoading و error
`useUpload(name)`	`Hook`	رفع الملفات مع تتبّع التقدّم. يُرجع upload و progress و isUploading

خطافات وكيل الذكاء الاصطناعي جديد

Parameter	Type	Description
`useChat(endpoint, options?)`	`Hook`	بث ردود وكيل الذكاء الاصطناعي. يُرجع messages و sendMessage و isLoading و status واستدعاءات الأدوات
`useChatList(options?)`	`Hook`	سرد المحادثات السابقة. يُرجع chats و deleteChat و renameChat و refetch

خطافات الوقت الفعلي جديد

Parameter	Type	Description
`useRealtime(table, filter?)`	`Hook`	الاشتراك في تغييرات قاعدة البيانات (INSERT/UPDATE/DELETE) في الوقت الفعلي
`useChannel(name)`	`Hook`	الانضمام إلى قناة بث للمراسلة من عميل إلى عميل
`useChannelMessages(name)`	`Hook`	الحصول على الرسائل من قناة بث
`useChannels()`	`Hook`	سرد القنوات المتاحة

الوقت الفعلي والدردشة على مستوى SDK/المحرك

تعمل قنوات الوقت الفعلي ودردشة الذكاء الاصطناعي بالكامل عبر SDK والمحرك — لا إعداد منفصل في لوحة التحكم. تُنشأ القنوات عند الطلب (عبر الخطافات أو REST API على /api/v0/channels) وهي نطاق مستخدم، لذا تحتاج جلسة مصادَقة.

المكوّنات

Parameter	Type	Description
`DypaiProvider`	`Component`	موفّر السياق — يغلّف تطبيقك. مطلوب لكل الخطافات
`ProtectedRoute`	`Component`	يحمي المسارات حسب حالة المصادقة والأدوار. يعيد توجيه المستخدمين غير المصادَقين

أمثلة سريعة

المصادقة

JavaScript

const { signIn, isAuthenticated, user } = useAuth()

const handleLogin = async (email, password) => {
  const { error } = await signIn(email, password)
  if (error) setError(error.message)
}

جلب البيانات

JavaScript

const { data: products, isLoading } = useEndpoint('list_products')
const { mutate: createProduct } = useAction('create_product')

await createProduct({ name: 'Widget', price: 9.99 })

دردشة الذكاء الاصطناعي (بث)

JavaScript

const { messages, sendMessage, isLoading } = useChat('my_agent_endpoint')

await sendMessage('How many orders do I have this week?')
// Messages stream in real-time with tool call visibility

تحديثات الوقت الفعلي

JavaScript

// Subscribe to all changes on the "orders" table
const { data: orders } = useRealtime('orders')

// Broadcast to other clients
const channel = useChannel('room-1')
channel.send('typing', { user: 'john' })

المسارات المحمية

JavaScript

<ProtectedRoute redirectTo="/login" roles={['admin']}>
  <AdminPanel />
</ProtectedRoute>

طرق الـ API

كل طريقة تُرجع { data, error } — لا ترمي أبداً.

Parameter	Type	Description
`dypai.api.get(name, options?)`	`Promise`	استدعاء endpoint من نوع GET
`dypai.api.post(name, body, options?)`	`Promise`	استدعاء endpoint من نوع POST
`dypai.api.put(name, body, options?)`	`Promise`	استدعاء endpoint من نوع PUT
`dypai.api.delete(name, options?)`	`Promise`	استدعاء endpoint من نوع DELETE
`dypai.api.upload(name, file, options?)`	`Promise`	رفع ملف عبر endpoint
`dypai.api.stream(name, body)`	`AsyncIterator`	بث الرد من endpoint وكيل ذكاء اصطناعي

وحدة الوقت الفعلي

JavaScript

// Subscribe to database changes
const channel = dypai.realtime.channel('my-channel')

channel
  .on('postgres_changes', { event: '*', table: 'orders' }, (payload) => {
    console.log('Change:', payload)
  })
  .on('broadcast', { event: 'typing' }, (payload) => {
    console.log('Someone is typing:', payload)
  })
  .on('presence', { event: 'sync' }, () => {
    console.log('Online users:', channel.presenceState())
  })
  .subscribe()

Parameter	Type	Description
`dypai.realtime.channel(name, config?)`	`Channel`	إنشاء قناة وقت فعلي أو الانضمام إليها
`channel.on(type, filter, callback)`	`Channel`	الاشتراك في الأحداث: postgres_changes و broadcast و presence
`channel.subscribe()`	`void`	بدء استقبال الأحداث
`channel.unsubscribe()`	`void`	إيقاف استقبال الأحداث
`channel.send(event, payload)`	`void`	بث رسالة إلى كل المشتركين
`channel.track(state)`	`void`	مشاركة حالة الحضور (من المتصل)
`channel.presenceState()`	`object`	الحصول على حالة الحضور الحالية لكل المستخدمين

TypeScript

إكمال تلقائي كامل لأسماء endpoints والمعاملات والردود:

JavaScript

interface MyApi extends EndpointMap {
  'get_products': { response: Product[]; params: { limit?: number } }
  'create_product': { body: CreateProductInput; response: Product }
}

const dypai = createClient<{}, MyApi>(url)
const { data } = await dypai.api.get('get_products', { params: { limit: 10 } })
// data is Product[] with full autocomplete

SDK للعميل

الحزمة الحالية هي @dypai-ai/client-sdk v1.12.0، مع خطافات React تحت @dypai-ai/client-sdk/react.

التثبيت

JavaScript

npm install @dypai-ai/client-sdk

الإعداد

JavaScript

// lib/dypai.ts
import { createClient } from '@dypai-ai/client-sdk'

export const dypai = createClient(
  import.meta.env.VITE_DYPAI_URL,  // https://YOUR_PROJECT_ID.dypai.app
  {
    redirects: {
      passwordRecovery: '/set-password',
      signIn: '/dashboard',
    },
  }
)

تستخدم Next.js بدل Vite؟

لتطبيقات React، غلّف بـ DypaiProvider:

JavaScript

import { DypaiProvider } from '@dypai-ai/client-sdk/react'
import { dypai } from './lib/dypai'

function App() {
  return (
    <DypaiProvider client={dypai}>
      <Router />
    </DypaiProvider>
  )
}

الوحدات

المصادقة

التسجيل وتسجيل الدخول و OAuth و OTP واستعادة كلمة المرور.

البيانات والـ API

استدعِ endpoints بـ get و post و put و delete.

الوقت الفعلي

تغييرات قاعدة البيانات والبث والحضور — تحديثات مباشرة.

دردشة الذكاء الاصطناعي

بث ردود وكيل الذكاء الاصطناعي مع استدعاءات الأدوات.

التخزين

رفع الملفات وتنزيلها عبر endpoints.

إدارة المستخدمين

عمليات الإدارة لإدارة المستخدمين.

خطافات React

JavaScript

import {
  DypaiProvider, useAuth, useEndpoint, useAction,
  useUpload, useChat, useRealtime, useChannel,
  useChannelMessages, useChannels, useChatList,
  ProtectedRoute
} from '@dypai-ai/client-sdk/react'

الخطافات الأساسية

Parameter	Type	Description
`useAuth()`	`Hook`	حالة المصادقة والإجراءات: user و signIn و signUp و signOut و isAuthenticated و isLoading
`useEndpoint(name)`	`Hook`	جلب البيانات من endpoints من نوع GET. يُرجع data و isLoading و error و refetch
`useAction(name)`	`Hook`	استدعاء endpoints من نوع POST/PUT/DELETE. يُرجع mutate و isLoading و error
`useUpload(name)`	`Hook`	رفع الملفات مع تتبّع التقدّم. يُرجع upload و progress و isUploading

خطافات وكيل الذكاء الاصطناعي جديد

Parameter	Type	Description
`useChat(endpoint, options?)`	`Hook`	بث ردود وكيل الذكاء الاصطناعي. يُرجع messages و sendMessage و isLoading و status واستدعاءات الأدوات
`useChatList(options?)`	`Hook`	سرد المحادثات السابقة. يُرجع chats و deleteChat و renameChat و refetch

خطافات الوقت الفعلي جديد

Parameter	Type	Description
`useRealtime(table, filter?)`	`Hook`	الاشتراك في تغييرات قاعدة البيانات (INSERT/UPDATE/DELETE) في الوقت الفعلي
`useChannel(name)`	`Hook`	الانضمام إلى قناة بث للمراسلة من عميل إلى عميل
`useChannelMessages(name)`	`Hook`	الحصول على الرسائل من قناة بث
`useChannels()`	`Hook`	سرد القنوات المتاحة

الوقت الفعلي والدردشة على مستوى SDK/المحرك

المكوّنات

Parameter	Type	Description
`DypaiProvider`	`Component`	موفّر السياق — يغلّف تطبيقك. مطلوب لكل الخطافات
`ProtectedRoute`	`Component`	يحمي المسارات حسب حالة المصادقة والأدوار. يعيد توجيه المستخدمين غير المصادَقين

أمثلة سريعة

المصادقة

JavaScript

const { signIn, isAuthenticated, user } = useAuth()

const handleLogin = async (email, password) => {
  const { error } = await signIn(email, password)
  if (error) setError(error.message)
}

جلب البيانات

JavaScript

const { data: products, isLoading } = useEndpoint('list_products')
const { mutate: createProduct } = useAction('create_product')

await createProduct({ name: 'Widget', price: 9.99 })

دردشة الذكاء الاصطناعي (بث)

JavaScript

const { messages, sendMessage, isLoading } = useChat('my_agent_endpoint')

await sendMessage('How many orders do I have this week?')
// Messages stream in real-time with tool call visibility

تحديثات الوقت الفعلي

JavaScript

// Subscribe to all changes on the "orders" table
const { data: orders } = useRealtime('orders')

// Broadcast to other clients
const channel = useChannel('room-1')
channel.send('typing', { user: 'john' })

المسارات المحمية

JavaScript

<ProtectedRoute redirectTo="/login" roles={['admin']}>
  <AdminPanel />
</ProtectedRoute>

طرق الـ API

كل طريقة تُرجع { data, error } — لا ترمي أبداً.

Parameter	Type	Description
`dypai.api.get(name, options?)`	`Promise`	استدعاء endpoint من نوع GET
`dypai.api.post(name, body, options?)`	`Promise`	استدعاء endpoint من نوع POST
`dypai.api.put(name, body, options?)`	`Promise`	استدعاء endpoint من نوع PUT
`dypai.api.delete(name, options?)`	`Promise`	استدعاء endpoint من نوع DELETE
`dypai.api.upload(name, file, options?)`	`Promise`	رفع ملف عبر endpoint
`dypai.api.stream(name, body)`	`AsyncIterator`	بث الرد من endpoint وكيل ذكاء اصطناعي

وحدة الوقت الفعلي

JavaScript

// Subscribe to database changes
const channel = dypai.realtime.channel('my-channel')

channel
  .on('postgres_changes', { event: '*', table: 'orders' }, (payload) => {
    console.log('Change:', payload)
  })
  .on('broadcast', { event: 'typing' }, (payload) => {
    console.log('Someone is typing:', payload)
  })
  .on('presence', { event: 'sync' }, () => {
    console.log('Online users:', channel.presenceState())
  })
  .subscribe()

Parameter	Type	Description
`dypai.realtime.channel(name, config?)`	`Channel`	إنشاء قناة وقت فعلي أو الانضمام إليها
`channel.on(type, filter, callback)`	`Channel`	الاشتراك في الأحداث: postgres_changes و broadcast و presence
`channel.subscribe()`	`void`	بدء استقبال الأحداث
`channel.unsubscribe()`	`void`	إيقاف استقبال الأحداث
`channel.send(event, payload)`	`void`	بث رسالة إلى كل المشتركين
`channel.track(state)`	`void`	مشاركة حالة الحضور (من المتصل)
`channel.presenceState()`	`object`	الحصول على حالة الحضور الحالية لكل المستخدمين

TypeScript

إكمال تلقائي كامل لأسماء endpoints والمعاملات والردود:

JavaScript

interface MyApi extends EndpointMap {
  'get_products': { response: Product[]; params: { limit?: number } }
  'create_product': { body: CreateProductInput; response: Product }
}

const dypai = createClient<{}, MyApi>(url)
const { data } = await dypai.api.get('get_products', { params: { limit: 10 } })
// data is Product[] with full autocomplete