zakkur-sdk 1.0.0 → 1.0.1

package/README.md

@@ -1,152 +1,81 @@
-Zakkur AI Enterprise SDK 🚀
+# Zakkur AI Enterprise SDK 🚀
+### المحرك التنفيذي للقرارات المؤسسية الذكية (Digital C-Suite)
 
-محرك تشغيل القرارات المؤسسية الذكي (Digital C-Suite)
+![npm version](https://img.shields.io/badge/npm-v1.0.0-blue)
+![node version](https://img.shields.io/badge/node-%3E%3D18.0.0-green)
+![license](https://img.shields.io/badge/license-Enterprise-red)
 
-مرحباً بك في الدليل التقني الرسمي لمكتبة زكور (Zakkur). تم تصميم هذا الـ SDK لتمكين المطورين من دمج طاقم تنفيذي رقمي متكامل (C-Suite) داخل تطبيقاتهم، مما يسمح بأتمتة القرارات الاستراتيجية، وتحليل البيانات المالية، وتنفيذ العمليات التقنية والقانونية عبر ذكاء اصطناعي متخصص.
+تم تصميم هذا الـ SDK لتمكين المطورين من دمج طاقم تنفيذي رقمي متكامل (C-Suite) داخل تطبيقاتهم، مما يسمح بأتمتة القرارات الاستراتيجية وتحليل البيانات المالية عبر ذكاء اصطناعي متخصص.
 
-🌟 المميزات الرئيسية
+---
 
-Digital Boardroom: استدعاء كافة أعضاء المجلس (12 وكيلاً) بطلب واحد لتحليل القضايا المعقدة.
+## 📌 فهرس المحتويات
+* [✨ المميزات الرئيسية](#-المميزات-الرئيسية)
+* [📦 التثبيت](#-التثبيت)
+* [🛠️ التهيئة](#️-التهيئة)
+* [🧠 دليل استخدام الوحدات](#-دليل-استخدام-الوحدات)
+* [🔒 إدارة الجلسات](#-إدارة-الجلسات)
+* [⚠️ معالجة الأخطاء](#-معالجة-الأخطاء)
+* [📜 مراجع الـ API السريعة](#-مراجع-الـ-api-السريعة)
 
-Dynamic Agent Proxy: وصول ذكي للوكلاء (CEO, CFO, CTO...) بأسلوب برمجي حديث وأنيق.
+---
 
-RAG Integrated: ربط الوكلاء بقاعدة المعرفة المؤسسية (ملفات PDF و TXT) لاتخاذ قرارات بناءً على بياناتك الفعلية.
+## ✨ المميزات الرئيسية
 
-Ops Execution Engine: تحويل القرارات إلى خطوات تنفيذية (Action Items) قابلة للربط مع الأدوات الخارجية.
+* **🏛️ Digital Boardroom**: استدعاء كافة أعضاء المجلس (12 وكيلاً) بطلب واحد لتحليل القضايا المعقدة.
+* **🤖 Dynamic Agent Proxy**: وصول ذكي للوكلاء (CEO, CFO, CTO...) بأسلوب برمجي حديث وأنيق.
+* **📚 RAG Integrated**: ربط الوكلاء بقاعدة المعرفة المؤسسية (ملفات PDF و TXT).
+* **🦾 Ops Execution Engine**: تحويل القرارات إلى خطوات تنفيذية قابلة للربط مع الأدوات الخارجية.
+* **🛡️ Enterprise Grade**: دعم إعادة المحاولة تلقائياً (Retries) وإدارة المهلة الزمنية.
 
-Enterprise Grade: دعم إعادة المحاولة تلقائياً (Retries)، إدارة المهلة الزمنية (Timeouts)، ومعالجة أخطاء تفصيلية.
+---
 
-📦 التثبيت
+## 📦 التثبيت
 
-يتطلب الـ SDK بيئة عمل Node.js إصدار 18 أو أحدث.
+يتطلب الـ SDK بيئة عمل **Node.js إصدار 18** أو أحدث.
 
+```bash
 npm install zakkur-sdk
-
-
-🛠️ التهيئة (Initialization)
-
-ابدأ بإنشاء كائن من الفئة Zakkur باستخدام مفتاح الوصول الخاص بمؤسستك.
-
-const Zakkur = require('zakkur-sdk');
+🛠️ التهيئة (Initialization)قم بإنشاء كائن من الفئة Zakkur باستخدام مفتاح الوصول الخاص بمؤسستك.JavaScriptconst Zakkur = require('zakkur-sdk');
 
 const sdk = new Zakkur({
     apiKey: 'zk_live_xxxxxxxxxxxxxxxx', // احصل عليه من بوابة المطورين
-    baseUrl: '[https://api.zakkur.ai/api](https://api.zakkur.ai/api)', // رابط السيرفر الخاص بك
-    timeout: 30000, // مهلة الاستجابة (30 ثانية)
-    retries: 3      // عدد محاولات إعادة الطلب عند فشل الشبكة
+    baseUrl: '[https://zakkur.com/api](https://zakkur.com/api)',    // رابط السيرفر الخاص بك
+    timeout: 30000,                       // 30 ثانية
+    retries: 3                            // عدد محاولات إعادة الطلب
 });
-
-
-🧠 دليل استخدام الوحدات
-
-1. وحدة مجلس الإدارة (The Board)
-
-تُستخدم لاتخاذ القرارات الكبرى التي تتطلب رؤية من تخصصات متعددة (مالية، تقنية، قانونية).
-
-// استشارة كامل المجلس في قضية استراتيجية
-const response = await sdk.board.consult("نخطط لتوسيع عملياتنا في السوق الخليجي بميزانية مليون دولار، ما هي المخاطر والجدوى؟");
+🧠 دليل استخدام الوحدات1️⃣ وحدة مجلس الإدارة (The Board)تُستخدم لاتخاذ القرارات الكبرى التي تتطلب رؤية شاملة.JavaScript// استشارة كامل المجلس في قضية استراتيجية معقدة
+const response = await sdk.board.consult("نخطط لتوسيع عملياتنا في السوق العالمي، ما هي المخاطر التقنية والمالية؟");
 
 console.log("القرار التنفيذي:", response.data.final_decision.decision);
 console.log("خارطة الطريق:", response.data.final_decision.action_items);
-
-
-2. وحدة الوكلاء الديناميكية (Dynamic Agents)
-
-يمكنك التحدث مع أي مدير تنفيذي مباشرة. يتميز الـ SDK بدعم الاستدعاء عبر الخصائص (Proxy).
-
-// استشارة المدير المالي (CFO)
-const financialReport = await sdk.agents.cfo.consult("حلل التدفق النقدي المتوقع للربع القادم");
+2️⃣ وحدة الوكلاء الديناميكية (Dynamic Agents)يمكنك التحدث مع أي مدير تنفيذي مباشرة بأسلوب برمجي حديث.JavaScript// استشارة المدير المالي (CFO) مباشرة
+const financialReport = await sdk.agents.cfo.consult("قم بتحليل ميزانية الربع القادم");
 
 // طلب مهمة تنفيذية من المدير التقني (CTO)
-const codeTask = await sdk.agents.cto.execute("اكتب سكربت بايثون لتنظيف بيانات العملاء");
+const codeTask = await sdk.agents.cto.execute("اكتب سكربت بايثون لتحليل بيانات العملاء بأمان");
+3️⃣ وحدة المعرفة (Knowledge Base)تسمح لك بتغذية ذكاء زكور بملفات شركتك المؤسسية.JavaScript// رفع مستند جديد
+const upload = await sdk.knowledge.upload(fileBuffer, 'HR_Policy_2026.pdf');
 
-
-3. وحدة الذاكرة والمعرفة (Knowledge Base)
-
-تسمح لك بتغذية ذكاء زكور بملفاتك المؤسسية ليقرأها الوكلاء قبل الرد.
-
-// رفع مستند جديد (عقد أو سياسة شركة)
-const upload = await sdk.knowledge.upload(fileBuffer, 'Policy_2026.pdf');
-
-// عرض قائمة المستندات المرفوعة
+// عرض قائمة المستندات المتوفرة
 const docs = await sdk.knowledge.list();
-
-
-🔒 إدارة الجلسات (Contextual Threading)
-
-للحفاظ على سياق المحادثة وجعل الوكيل يتذكر ما قيل سابقاً، قم بتمرير الـ threadId.
-
-let threadId = null;
+🔒 إدارة الجلسات (Contextual Threading)للحفاظ على سياق المحادثة وجعل الوكيل يتذكر تاريخ الحوار السابق.JavaScriptlet threadId = null;
 
 // الطلب الأول
-const step1 = await sdk.agents.ceo.consult("من هو منافسنا الرئيسي؟");
+const step1 = await sdk.agents.ceo.consult("من هو عميلنا المثالي؟");
 threadId = step1.threadId;
 
-// الطلب الثاني (بنفس السياق)
-const step2 = await sdk.agents.ceo.consult("وكيف نتفوق عليه؟", { threadId });
-
-
-⚠️ معالجة الأخطاء (Error Handling)
-
-يوفر الـ SDK كلاس خاص للأخطاء ZakkurError يعطيك تفاصيل دقيقة عن سبب الفشل.
-
-try {
+// الطلب الثاني (بنفس السياق المستمر)
+const step2 = await sdk.agents.ceo.consult("وكيف يمكننا استهدافه بفاعلية؟", { threadId });
+⚠️ معالجة الأخطاء (Error Handling)يوفر الـ SDK كلاس خاص ZakkurError لتسهيل عملية التصحيح.JavaScripttry {
     const result = await sdk.board.consult("...");
 } catch (error) {
     if (error.name === 'ZakkurError') {
-        console.error(`Status: ${error.status}`); // 403, 429, etc.
-        console.error(`Code: ${error.code}`);     // AGENT_RESTRICTED, QUOTA_EXCEEDED
+        console.error(`Status: ${error.status}`); // مثل 403 أو 429
+        console.error(`Code: ${error.code}`);     // AGENT_RESTRICTED
         console.error(`Message: ${error.message}`);
     } else {
         console.error("خطأ غير متوقع في الشبكة");
     }
 }
-
-
-🛡️ الصلاحيات والقيود
-
-باقة Startup: توفر الوصول إلى (CEO, CFO, CTO) فقط وبحد استهلاك 1,000 طلب شهرياً.
-
-باقة Enterprise: تفتح كامل أعضاء المجلس (12 وكيلاً) مع دعم الأتمتة المستقلة والذاكرة غير المحدودة.
-
-الأمان: لا تقم أبداً بتضمين مفتاح الـ API في كود الواجهة الأمامية (Client-side)؛ استخدم الـ SDK دائماً في بيئة خلفية (Backend).
-
-📜 مراجع الـ API السريعة
-
-المسار البرمجي
-
-الوصف
-
-المعاملات الأساسية
-
-sdk.board.consult(text)
-
-قرار مجلس إدارة شامل
-
-context
-
-sdk.agents.[role].consult(text)
-
-استشارة وكيل متخصص
-
-prompt, options
-
-sdk.agents.[role].execute(task)
-
-طلب مخرج عملي
-
-task, options
-
-sdk.knowledge.upload(file)
-
-رفع ملف للذاكرة
-
-file, title
-
-sdk.board.getHistory()
-
-استرجاع السجل
-
-لا يوجد
-
-تم بناء هذا النظام لتمكين الأتمتة المؤسسية الذكية. لطلب الدعم التقني أو الوصول المخصص، تواصل مع فريق المطورين عبر admin@sopen.ai
+🛡️ الصلاحيات والقيود[!IMPORTANT]باقة Startup: توفر الوصول إلى الوكلاء الأساسيين (CEO, CFO, CTO) فقط. للوصول لكامل الفريق، يرجى الترقية لباقة Enterprise.[!WARNING]الأمان: لا تقم أبداً بتضمين مفتاح الـ API في كود المتصفح العام (Client-side)؛ استخدم الـ SDK دائماً في بيئة خلفية آمنة (Backend).📜 مراجع الـ API السريعةالمسار البرمجيالوصفالمعاملات الأساسيةsdk.board.consult(text)قرار مجلس إدارة شاملtext (String)sdk.agents.[role].consult(text)استشارة وكيل متخصصprompt, optionssdk.agents.[role].execute(task)طلب مخرج عملي/تنفيذيtask, optionssdk.knowledge.upload(file)رفع ملف للذاكرة المؤسسيةfile, titlesdk.board.getHistory()استرجاع سجل القراراتلا يوجد📩 التواصل والدعمتم بناء هذا النظام لتمكين الأتمتة المؤسسية الذكية. لطلب الدعم التقني، تواصل مع فريق المطورين:📧 Email: admin@sopen.ai© 2026 Zakkur AI. All rights reserved.

package/package.json

@@ -1,30 +1,27 @@
 {
     "name": "zakkur-sdk",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "description": "The official Enterprise AI SDK for Zakkur - Digital C-Suite and Decision Engine.",
     "main": "zakkur-sdk.js",
     "scripts": {
-        "test": "echo \"Error: no test specified\" && exit 1"
+      "test": "echo \"Error: no test specified\" && exit 1"
     },
     "keywords": [
-        "ai",
-        "enterprise",
-        "decision-engine",
-        "zakkur",
-        "sdk",
-        "executive-ai"
+      "ai",
+      "enterprise",
+      "decision-engine",
+      "zakkur",
+      "sdk",
+      "executive-ai"
     ],
     "author": "Zakkur Team",
     "license": "MIT",
     "engines": {
-        "node": ">=18.0.0"
+      "node": ">=18.0.0"
     },
     "repository": {
-        "type": "git",
-        "url": "git+https://github.com/SopenAi/zakkur-sdk.git"
-    },
-    "bugs": {
-        "url": "https://github.com/SopenAi/zakkur-sdk.git"
+      "type": "git",
+      "url": "https://github.com/SopenAi/zakkur-sdk.git"
     },
     "homepage": "https://zakkur.com"
-}
+  }

package/test-sdk.js

@@ -1,41 +1,118 @@
 /**
- * سكربت تجريبي لاختبار عمل الـ SDK مع السيرفر
- * تأكد من تشغيل السيرفر أولاً (node server.js)
+ * Zakkur SDK - Full Integration & Diagnostic Test Suite (v1.1.0) 🚀
+ * تم تطوير هذا الملف لتشخيص أخطاء المصادقة (401) واختبار تكامل الوكلاء.
  */
 
-const Zakkur = require('./zakkur-sdk');
+const Zakkur = require('zakkur-sdk');
 
-// استبدل المفتاح بمفتاح صالح من قاعدة البيانات الخاصة بك
+// --- إعدادات البيئة ---
+// ملاحظة: تأكد من أن مفتاح الـ API يبدأ بـ _zk_live لضمان الوصول الشامل
 const sdk = new Zakkur({
-    apiKey: 'zk_live_your_actual_key_here',
-    baseUrl: 'http://localhost:8080/api'
+    apiKey: 'zk_live_f3cbd6c0860c4115881acb32', 
+    baseUrl: 'http://localhost:8080/api',   
+    timeout: 60000
 });
 
-async function runTest() {
-    console.log("🚀 بدء اختبار نظام زكور...");
+const log = {
+    info: (msg) => console.log(`\x1b[36mℹ️  ${msg}\x1b[0m`),
+    success: (msg) => console.log(`\x1b[32m✅ ${msg}\x1b[0m`),
+    warn: (msg) => console.log(`\x1b[33m⚠️  ${msg}\x1b[0m`),
+    error: (msg) => console.log(`\x1b[31m❌ ${msg}\x1b[0m`),
+    header: (msg) => console.log(`\n\x1b[35m=== ${msg.toUpperCase()} ===\x1b[0m`),
+    divider: () => console.log('\x1b[90m--------------------------------------------------\x1b[0m')
+};
+
+async function runFullDiagnostics() {
+    log.header("بدء تشخيص النظام المتكامل");
+    let sharedThreadId = null;
 
     try {
-        // 1. اختبار استشارة المجلس
-        console.log("\n1. استشارة مجلس الإدارة...");
-        const boardRes = await sdk.board.consult("هل يجب أن ننتقل لاستخدام الحوسبة السحابية بالكامل؟");
-        console.log("✅ رد المجلس:", boardRes.data.final_decision.decision);
-
-        // 2. اختبار استشارة وكيل محدد (CFO)
-        console.log("\n2. استشارة المدير المالي (CFO)...");
-        const cfoRes = await sdk.agents.cfo.consult("ما هي مخاطر الاستثمار في العملات الرقمية للشركة؟");
-        console.log("✅ رد الـ CFO:", cfoRes.response);
-
-        // 3. اختبار جلب السجل
-        console.log("\n3. جلب سجل القرارات...");
+        // 1. اختبار الاتصال الأساسي وصلاحية المفتاح
+        log.info("المرحلة 1: فحص صلاحية المفتاح والاتصال بالخادم...");
         const history = await sdk.board.getHistory();
-        console.log(`✅ تم استرجاع ${history.data.length} قرار سابق.`);
+        log.success(`تم الاتصال بنجاح. السجلات المتوفرة: ${history.data?.length || 0}`);
+        log.divider();
+
+        // 2. اختبار استشارة المجلس (Board Room)
+        log.info("المرحلة 2: استدعاء مجلس الإدارة...");
+        const board = await sdk.board.consult("هل تنصح بالاستحواذ على شركة تقنية صغيرة لتوسيع فريق العمل؟");
+        
+        // التحقق من بنية البيانات لضمان عدم حدوث خطأ عند القراءة
+        const decisionText = board.data?.final_decision?.decision || "لا يوجد رد";
+        const confidence = board.data?.final_decision?.confidence_score || 0;
+        
+        log.success(`تم الحصول على قرار المجلس بنجاح.`);
+        console.log(`\x1b[90m> القرار: ${decisionText.substring(0, 100)}...\x1b[0m`);
+        log.info(`ثقة النظام: ${confidence}%`);
+        log.divider();
+
+        // 3. اختبار إدارة الجلسات والوكلاء الفرديين (CFO)
+        log.header("المرحلة 3: اختبار الذاكرة الحوارية (CFO)");
+        log.info("جاري إرسال طلب استشارة للمدير المالي...");
+        
+        const step1 = await sdk.agents.cfo.consult("ما هي الميزانية المناسبة لمثل هذا الاستحواذ؟");
+        
+        // التحقق من نجاح الطلب واستخراج المعرف
+        if (step1 && (step1.threadId || step1.data?.threadId)) {
+            sharedThreadId = step1.threadId || step1.data.threadId;
+            log.success("تم إنشاء جلسة حوارية (Thread) بنجاح.");
+            console.log(`\x1b[90m> رد الوكيل: ${step1.response || step1.data?.result}\x1b[0m`);
+            
+            log.info("إرسال سؤال متابعة لتعزيز سياق الحوار...");
+            const step2 = await sdk.agents.cfo.consult("وكيف نوزع هذا المبلغ على 12 شهراً؟", { threadId: sharedThreadId });
+            log.success("تم استلام رد المتابعة بنجاح.");
+        } else {
+            log.warn("تم استلام رد ولكن لم يتم العثور على threadId في البيانات المسترجعة.");
+        }
+        log.divider();
+
+        // 4. اختبار قاعدة المعرفة (Knowledge Management)
+        log.header("المرحلة 4: اختبار الذاكرة المعرفية (RAG)");
+        log.info("جاري محاكاة رفع مستند 'سياسة الشركة'...");
+        
+        const mockFileBuffer = Buffer.from("سياسة الشركة: يمنع الاستحواذ إلا بموافقة 70% من المساهمين.");
+        const upload = await sdk.knowledge.upload(mockFileBuffer, 'Company_Policy_Test.txt');
+        
+        const docId = upload.data?._id || upload._id;
+        log.success(`تم رفع الملف بنجاح. المعرف: ${docId}`);
+
+        log.info("جاري فحص قائمة الملفات...");
+        const list = await sdk.knowledge.list();
+        log.success(`إجمالي الملفات في الذاكرة: ${list.data?.length || 0}`);
+
+        // 5. التنظيف (Cleanup)
+        if (docId) {
+            log.info(`جاري حذف مستند الاختبار لتنظيف البيانات...`);
+            await sdk.knowledge.delete(docId);
+            log.success("تم تنظيف الذاكرة المعرفية بنجاح.");
+        }
 
     } catch (error) {
-        console.error("\n❌ فشل الاختبار:");
-        console.error(`الرسالة: ${error.message}`);
-        console.error(`الكود: ${error.code}`);
-        console.error(`الحالة: ${error.status}`);
+        log.error("حدث خطأ أثناء تنفيذ الفحوصات التشخيصية:");
+        
+        if (error.name === 'ZakkurError') {
+            log.warn(`تفاصيل الخطأ التقني (Status: ${error.status}):`);
+            console.error({
+                code: error.code,
+                message: error.message,
+                details: error.details || "لا توجد تفاصيل إضافية من الخادم"
+            });
+
+            if (error.status === 401) {
+                log.info("💡 نصيحة للحل: خطأ 401 يعني أن الخادم يرفض الهوية. تحقق من:");
+                console.log("1. أن ملف 'agentRoutes.js' لا يتطلب 'verifyToken' (Firebase) لطلبات الـ API Key.");
+                console.log("2. أن مفتاح الـ API ينتمي لشركة مفعلة في قاعدة البيانات.");
+            }
+            if (error.status === 403) {
+                log.info("💡 نصيحة للحل: خطأ 403 يعني أن الوكيل غير متاح في باقتك الحالية (allowed_agent_roles).");
+            }
+        } else {
+            console.error(error);
+        }
+    } finally {
+        log.header("انتهت الفحوصات التشخيصية");
     }
 }
 
-runTest();
+// تنفيذ الاختبار
+runFullDiagnostics();