SDK لـNode.js

العمليات الموثقة وحدود التغطية الفعلية

نسخة المصدر هذه تضيف 80 عملية موثقة عبر SDK وCLI وMCP. تحقق بشكل منفصل من إصدار npm المثبت وتفعيل الخدمة المستضافة.

التغطية: جهات الاتصال والمهام والتذاكر؛ إسناد وحالة وتصنيفات وملاحظات المحادثات وإرسال نص بإجراء مستقل؛ مسودات وإعداد ومعرفة نصية وقنوات واختبارات وتفعيل موظفي الذكاء الاصطناعي؛ الطلبات اليدوية وحالتها ودفعها وتنفيذها؛ المنتجات والتصنيفات؛ وحالة جهات الاتصال ومراحلها وإسنادها وتاجاتها وحقولها؛ وقراءة الأتمتة ومسوداتها ومحاكاتها وإيقافها وتفعيل نسختها المعتمدة؛ ومعاينة الحملات ومسوداتها وإيقافها وإلغائها وإرسالها واستئنافها وجدولتها بموافقة دقيقة. دليل 553 مسارًا هو بيانات اكتشاف وليس تغطية تنفيذية كاملة للوحة التحكم.

SDK: استخدم describeOperations() ثم prepareOperation(id, input, idempotencyKey) وexecuteOperation(id, input, { idempotencyKey, confirmation }). CLI: أوامر operations list/inspect/preview/run مع --input و--idempotency-key و--confirm. MCP: أدوات operations_list وoperation_inspect وoperation_preview وoperation_execute؛ الرسائل تستخدم message_send والتفعيل يستخدم lifecycle_activate؛ والحملات تستخدم campaign_send أو campaign_schedule. في CLI استخدم messages send بعد معاينة inbox.message.send.

اعرض المعاينة الدقيقة واحصل على موافقة المستخدم الصريحة قبل التعديل. بصمة التأكيد تربط الإدخال والمفتاح لكنها ليست إثباتًا للموافقة البشرية. احتفظ بنفس مفتاح منع التكرار عند استعادة الطلب. لا توجد إعادة محاولة تلقائية. تستمر قيود الشركة والدور والصلاحية والباقة. صلاحيات OAuth للكتابة تحتاج موافقة صريحة جديدة وتبدأ غير محددة؛ المنح القديمة لا تكتسب صلاحيات.

اختبارات ومعالجة معرفة الذكاء الاصطناعي قد تستهلك الرصيد. التفعيل وإسناد القنوات قد يؤثران على الردود الحية. الإرسال يحتاج موافقة على contactId وchannelId ونوع القناة والنص الكامل؛ والخادم يعيد التحقق من الوجهة. لا إرسال وسائط أو قوالب عبر المحادثات ولا حذف كيانات أو HTTP حر أو فوترة أو إدارة منصة. إرسال قوالب الحملات وجدولتها يتطلبان إجراء مستقل وموافقة على لقطة ثابتة للجمهور والمحتوى والمرسل والتوقيت. تعديل الطلبات والتاجات قد يشغّل الأتمتة؛ والحقول المخصصة تستبدل الخريطة كاملة؛ تحديث الدفع لا يخصم من مزود الدفع. استرداد وإلغاء الطلبات والتغطية الكاملة للحملات والأتمتة ما زالت مستثناة.

يحتاج Node.js ‏>= 20.3. الحزمة بصيغة ESM فقط (استخدم import وليس require) وتتضمن أنواع TypeScript.

npm i @inboxychat/sdk

pnpm add @inboxychat/sdk

1. سجّل الدخول إلى Inboxy بحساب مدير الشركة وافتح المطورون ← API keys في لوحة التحكم ‏(/developer-center/keys).
2. اختر "أنشئ مفتاح API" وسمِّ المفتاح باسم تعرفه لاحقاً (مثل "Claude على جهازي").
3. اختر الصلاحيات التي تحتاجها فقط. لا توجد صلاحيات افتراضية، ولا يمكن إنشاء مفتاح بلا صلاحيات. أدوات القراءة تحتاج صلاحيات ":read" ‏(contacts:read وorders:read ...).
4. اختر مدة الصلاحية: 30 أو 90 (الافتراضي) أو 180 أو 365 يوماً أو بلا انتهاء. الافتراضي 90 يوماً.
5. انسخ المفتاح عند ظهوره، وهو يبدأ بـ"inboxy_". احفظه في مدير أسرار أو في سلسلة مفاتيح النظام، ولا تضعه أبداً في مستودع كود.

مرّر المفتاح إلى العميل بنفسك من متغير بيئة أو مخزن أسرار. وعلى جهاز المطور، تستطيع resolveCredentials() أيضاً قراءة مفتاح حُفظ عبر inboxy auth login.

import { InboxyClient, resolveCredentials } from '@inboxychat/sdk';

const creds = await resolveCredentials();
if (!creds.apiKey) throw new Error('Run inboxy auth login or set INBOXY_API_KEY');
const inboxy = new InboxyClient({ apiKey: creds.apiKey, baseUrl: creds.apiUrl });

قراءة كل الصفحات

import { InboxyClient, collectPages } from '@inboxychat/sdk';

const inboxy = new InboxyClient({ apiKey: process.env.INBOXY_API_KEY! });
const { items, meta } = await collectPages(
  (q) => inboxy.listContacts(q),
  { lifecycleStage: 'customer', limit: 100 },
  20 // max pages
);
console.log(items.length, meta.hasMore ? 'more remain' : 'done');

معالجة الأخطاء

import { InboxyError } from '@inboxychat/sdk';

try {
  await inboxy.getOrder('ord_123');
} catch (err) {
  if (err instanceof InboxyError) {
    if (err.kind === 'rate_limited') console.log('retry after', err.retryAfterSeconds, 's');
    else if (err.kind === 'forbidden') console.log('missing scope', err.details.requiredScope);
    else console.log(err.kind, err.code, err.message);
  } else throw err;
}

إلغاء الطلب أو تحديد مهلته

const inboxy = new InboxyClient({ apiKey: process.env.INBOXY_API_KEY!, timeoutMs: 5000 });
const controller = new AbortController();
setTimeout(() => controller.abort(), 1000);
await inboxy.listConversations({ status: 'open' }, { signal: controller.signal });

new InboxyClient(options)

الدوال

كل دالة تعيد صيغة الواجهة ({ success, data, meta? }) وتقبل { signal } كآخر وسيط.

أنواع الأخطاء

يحمل InboxyError الحقول kind وstatus وcode وdetails وretryAfterSeconds. وقيمة kind واحدة من: auth، forbidden، not_found، rate_limited، invalid_request، server، timeout، cancelled، network، invalid_response، config.

• التعديلات تستخدم العمليات الموثقة بموافقة صريحة ومنع التكرار. إرسال النصوص والحملات يتطلب موافقة مستقلة وصريحة على المستلم والمحتوى.
• للخادم فقط. لا ترسل المفتاح أبداً إلى المتصفح.
• HTTPS فقط (وhttp لـlocalhost)؛ تُرفض إعادة التوجيه؛ وتُتحقق المعرّفات وتُرمَّز كجزء واحد من المسار.
• تنطبق حدود طلبات واجهة REST؛ والرمز 429 يصبح النوع "rate_limited" مع retryAfterSeconds.

• ERR_REQUIRE_ESM: الحزمة بصيغة ESM. استخدم import أو import() الديناميكي من CommonJS.
• AbortSignal.any is not a function: حدّث Node.js إلى 20.3 أو أحدث.
• النوع "config" مع INSECURE_API_URL: يجب أن يبدأ baseUrl بـhttps://‏ (http مقبول لـlocalhost فقط).
• النوع "auth" أو "forbidden": نفّذ inboxy doctor بالمفتاح نفسه لمعرفة الناقص.