سطر الأوامر CLI

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

نسخة المصدر هذه تضيف 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.

npm i -g @inboxychat/cli
inboxy --version

npx -y -p @inboxychat/cli inboxy --help

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

تسجيل الدخول

في الطرفية، يفتح inboxy auth login المتصفح لتوافق على مفتاح لهذه الشركة. المفتاح ليس وسيطاً في الأمر: يُرفض inboxy auth login <key> وأي خيار ‎--key أو ‎--token أو ‎--api-key. وإذا لم يكن الإدخال طرفية، الصق المفتاح أو مرّره عبر الأنبوب.

inboxy auth login                      # browser approval on a terminal
pbpaste | inboxy auth login            # or pipe a key (macOS, not a TTY)
inboxy auth login --profile client-a   # one profile per company
inboxy auth status                     # where the key comes from + is it accepted
inboxy auth logout --profile client-a

أين يُحفظ المفتاح

• في سلسلة مفاتيح النظام: macOS Keychain أو Linux Secret Service ‏(secret-tool).
• بدون سلسلة مفاتيح (أو مع --store file): في ملف الإعداد بأذونات 0600 داخل مجلد بأذونات 0700. ويُرفض ملف إعداد يستطيع مستخدمون آخرون قراءته.
• ملف الإعداد: $INBOXY_CONFIG_DIR، وإلا $XDG_CONFIG_HOME/inboxy، وإلا ~/.config/inboxy/config.json.

البحث عن عميل وطلباته

inboxy contacts search "9665" --stage customer
inboxy orders list --contact CONTACT_ID

تصدير الطلبات بصيغة JSON

الخيار --all يتبع المؤشرات حتى --max-pages ‏(الافتراضي 10).

inboxy orders list --after 2026-10-20 --all --json > orders.json

الوكالات: ملف تعريف لكل شركة

inboxy auth login --profile client-a
inboxy --profile client-a usage
INBOXY_PROFILE=client-b inboxy orders list

الاستخدام في CI أو سكربت

اضبط INBOXY_API_KEY من مخزن الأسرار؛ فهو يتقدم على سلسلة المفاتيح. واعتمد على رمز الخروج.

INBOXY_API_KEY="$INBOXY_API_KEY" inboxy doctor --json > doctor.json || echo "doctor exit $?"

الأوامر

inboxy auth login [--store keychain|file] [--no-verify] [--profile <name>]
inboxy auth status [--offline]
inboxy auth logout [--profile <name>]
inboxy whoami
inboxy usage
inboxy stores list
inboxy orders list [--status] [--payment-status] [--fulfillment-status] [--source] [--store <id>] [--contact <id>] [--search <text>] [--after <iso>] [--before <iso>]
inboxy orders get <id>
inboxy contacts search [text] [--status] [--stage] [--tags <ids>] [--created-after <iso>] [--created-before <iso>]
inboxy doctor
inboxy operations list
inboxy operations inspect <operation>
inboxy operations preview <operation> --input <json> --idempotency-key <key>
inboxy operations run <operation> --input <json> --idempotency-key <key> --confirm <preview-hash>
inboxy messages send --input <json> --idempotency-key <key> --confirm <preview-hash>
inboxy lifecycle activate <operation> --input <json> --idempotency-key <key> --confirm <hash>
inboxy campaigns send <operation> --input <json> --idempotency-key <key> --confirm <hash>
inboxy campaigns schedule --input <json> --idempotency-key <key> --confirm <hash>

التنقل والخيارات العامة

• --limit من 1 إلى 100، أو --cursor <nextCursor>، أو --all (مع --max-pages، الافتراضي 10).
• --json و--profile <name> و--url <origin> و--timeout <ms>. ويمكن وضع الخيارات العامة قبل الأمر أو بعده.

مخرجات --json

مستند واحد على stdout بإصدار schemaVersion 1. قد تُضاف حقول، ولا تُعاد تسميتها أو تُحذف أبداً. وعناصر data هي كائنات الواجهة العامة v1 كما هي.

{ "schemaVersion": 1, "ok": true, "command": "orders list",
  "data": [ ... ], "meta": { "limit": 20, "hasMore": true, "nextCursor": "...", "pages": 1 } }

{ "schemaVersion": 1, "ok": false, "command": "orders list",
  "error": { "kind": "forbidden", "code": "INSUFFICIENT_PERMISSIONS", "status": 403,
             "message": "...", "details": { "requiredScope": "orders:read" }, "retryAfterSeconds": null } }

متغيرات البيئة

• أمر operations run يستطيع تغيير البيانات بعد تأكيد المعاينة الدقيقة.
• لا يُطبع المفتاح أبداً. المخرجات والأخطاء تمر عبر إخفاء (أي قيمة inboxy_… أو Bearer والمفتاح المستخدم)، ويظهر في الحالة أول 8 أحرف فقط.
• بلا Shell: تصل المدخلات إلى الواجهة كقيم مُتحقق منها ومُرمّزة فقط؛ والمعرّفات من 1 إلى 64 حرفاً أو رقماً أو "_" أو "-".
• HTTPS فقط (وhttp لـlocalhost)؛ وتُرفض إعادة التوجيه. وتنطبق حدود طلبات واجهة REST.

ابدأ بـinboxy doctor. يخرج بالرمز 10 عند فشل أي فحص ويوضح ما يجب إصلاحه.

رموز الخروج

أخطاء شائعة

• "No API key" (الرمز 3): نفّذ inboxy auth login أو اضبط INBOXY_API_KEY.
• "Inboxy refused the API key" (الرمز 4): المفتاح غير معروف أو ملغى أو منتهٍ. أنشئ مفتاحاً جديداً.
• "does not have the … scope" (الرمز 5): أنشئ مفتاحاً يتضمن الصلاحية المذكورة.
• لينكس بدون secret-tool: ثبّت أدوات libsecret أو استخدم inboxy auth login --store file.