zakkur-sdk 1.0.0

package/README.md

@@ -0,0 +1,152 @@
+Zakkur AI Enterprise SDK 🚀
+
+محرك تشغيل القرارات المؤسسية الذكي (Digital C-Suite)
+
+مرحباً بك في الدليل التقني الرسمي لمكتبة زكور (Zakkur). تم تصميم هذا الـ SDK لتمكين المطورين من دمج طاقم تنفيذي رقمي متكامل (C-Suite) داخل تطبيقاتهم، مما يسمح بأتمتة القرارات الاستراتيجية، وتحليل البيانات المالية، وتنفيذ العمليات التقنية والقانونية عبر ذكاء اصطناعي متخصص.
+
+🌟 المميزات الرئيسية
+
+Digital Boardroom: استدعاء كافة أعضاء المجلس (12 وكيلاً) بطلب واحد لتحليل القضايا المعقدة.
+
+Dynamic Agent Proxy: وصول ذكي للوكلاء (CEO, CFO, CTO...) بأسلوب برمجي حديث وأنيق.
+
+RAG Integrated: ربط الوكلاء بقاعدة المعرفة المؤسسية (ملفات PDF و TXT) لاتخاذ قرارات بناءً على بياناتك الفعلية.
+
+Ops Execution Engine: تحويل القرارات إلى خطوات تنفيذية (Action Items) قابلة للربط مع الأدوات الخارجية.
+
+Enterprise Grade: دعم إعادة المحاولة تلقائياً (Retries)، إدارة المهلة الزمنية (Timeouts)، ومعالجة أخطاء تفصيلية.
+
+📦 التثبيت
+
+يتطلب الـ SDK بيئة عمل Node.js إصدار 18 أو أحدث.
+
+npm install zakkur-sdk
+
+
+🛠️ التهيئة (Initialization)
+
+ابدأ بإنشاء كائن من الفئة Zakkur باستخدام مفتاح الوصول الخاص بمؤسستك.
+
+const 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      // عدد محاولات إعادة الطلب عند فشل الشبكة
+});
+
+
+🧠 دليل استخدام الوحدات
+
+1. وحدة مجلس الإدارة (The Board)
+
+تُستخدم لاتخاذ القرارات الكبرى التي تتطلب رؤية من تخصصات متعددة (مالية، تقنية، قانونية).
+
+// استشارة كامل المجلس في قضية استراتيجية
+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("حلل التدفق النقدي المتوقع للربع القادم");
+
+// طلب مهمة تنفيذية من المدير التقني (CTO)
+const codeTask = await sdk.agents.cto.execute("اكتب سكربت بايثون لتنظيف بيانات العملاء");
+
+
+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;
+
+// الطلب الأول
+const step1 = await sdk.agents.ceo.consult("من هو منافسنا الرئيسي؟");
+threadId = step1.threadId;
+
+// الطلب الثاني (بنفس السياق)
+const step2 = await sdk.agents.ceo.consult("وكيف نتفوق عليه؟", { threadId });
+
+
+⚠️ معالجة الأخطاء (Error Handling)
+
+يوفر الـ SDK كلاس خاص للأخطاء ZakkurError يعطيك تفاصيل دقيقة عن سبب الفشل.
+
+try {
+    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(`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

package/package.json

@@ -0,0 +1,30 @@
+{
+    "name": "zakkur-sdk",
+    "version": "1.0.0",
+    "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"
+    },
+    "keywords": [
+        "ai",
+        "enterprise",
+        "decision-engine",
+        "zakkur",
+        "sdk",
+        "executive-ai"
+    ],
+    "author": "Zakkur Team",
+    "license": "MIT",
+    "engines": {
+        "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"
+    },
+    "homepage": "https://zakkur.com"
+}

package/test-sdk.js

@@ -0,0 +1,41 @@
+/**
+ * سكربت تجريبي لاختبار عمل الـ SDK مع السيرفر
+ * تأكد من تشغيل السيرفر أولاً (node server.js)
+ */
+
+const Zakkur = require('./zakkur-sdk');
+
+// استبدل المفتاح بمفتاح صالح من قاعدة البيانات الخاصة بك
+const sdk = new Zakkur({
+    apiKey: 'zk_live_your_actual_key_here',
+    baseUrl: 'http://localhost:8080/api'
+});
+
+async function runTest() {
+    console.log("🚀 بدء اختبار نظام زكور...");
+
+    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. جلب سجل القرارات...");
+        const history = await sdk.board.getHistory();
+        console.log(`✅ تم استرجاع ${history.data.length} قرار سابق.`);
+
+    } catch (error) {
+        console.error("\n❌ فشل الاختبار:");
+        console.error(`الرسالة: ${error.message}`);
+        console.error(`الكود: ${error.code}`);
+        console.error(`الحالة: ${error.status}`);
+    }
+}
+
+runTest();

package/zakkur-sdk.js

@@ -0,0 +1,149 @@
+class ZakkurError extends Error {
+    constructor(message, status, code, details = null) {
+        super(message);
+        this.name = 'ZakkurError';
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+
+class Zakkur {
+    #apiKey;
+    #baseUrl;
+    #config;
+
+    constructor({ 
+        apiKey, 
+        baseUrl = 'http://localhost:8080/api', 
+        timeout = 30000, 
+        retries = 3 
+    }) {
+        if (!apiKey) throw new ZakkurError("API Key is missing", 400, 'AUTH_REQUIRED');
+
+        this.#apiKey = apiKey;
+        this.#baseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+        this.#config = { timeout, retries };
+        this.version = '3.0.2';
+
+        this.board = this.#initBoardModule();
+        this.agents = this.#initAgentsProxy();
+        this.knowledge = this.#initKnowledgeModule();
+    }
+
+    async #executeRequest(endpoint, method = 'GET', payload = null, isFileUpload = false) {
+        const url = `${this.#baseUrl}${endpoint}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.#config.timeout);
+
+        let headers = {
+            'x-api-key': this.#apiKey,
+            'X-SDK-Version': this.version,
+            'X-SDK-Client': typeof window !== 'undefined' ? 'Browser' : 'Node.js'
+        };
+
+        let body = null;
+        if (isFileUpload) {
+            body = payload;
+        } else if (payload) {
+            headers['Content-Type'] = 'application/json';
+            body = JSON.stringify(payload);
+        }
+
+        let attempt = 0;
+        const maxAttempts = this.#config.retries;
+
+        while (attempt <= maxAttempts) {
+            try {
+                const response = await fetch(url, { method, headers, body, signal: controller.signal });
+                clearTimeout(timeoutId);
+
+                const contentType = response.headers.get("content-type");
+                let result;
+
+                // التحقق من أن الرد بصيغة JSON قبل المعالجة لضمان القوة والاستقرار
+                if (contentType && contentType.includes("application/json")) {
+                    result = await response.json();
+                } else {
+                    const text = await response.text();
+                    throw new ZakkurError("Unexpected non-JSON response from server", response.status, 'INVALID_RESPONSE_FORMAT', { raw: text });
+                }
+
+                if (!response.ok) {
+                    if ([429, 503].includes(response.status) && attempt < maxAttempts) {
+                        attempt++;
+                        const backoff = Math.pow(2, attempt) * 1000;
+                        await new Promise(r => setTimeout(r, backoff));
+                        continue;
+                    }
+
+                    throw new ZakkurError(
+                        result.message || "Upstream server error",
+                        response.status,
+                        result.code || 'UPSTREAM_ERROR',
+                        result.errors
+                    );
+                }
+
+                return result;
+
+            } catch (error) {
+                clearTimeout(timeoutId);
+                if (error.name === 'AbortError') throw new ZakkurError("Request Timeout", 408, 'TIMEOUT');
+                if (error instanceof ZakkurError) throw error;
+                
+                if (attempt >= maxAttempts) throw new ZakkurError(error.message, 500, 'NET_ERROR');
+                
+                attempt++;
+                await new Promise(r => setTimeout(r, 1000));
+            }
+        }
+    }
+
+    #initBoardModule() {
+        return {
+            consult: (context) => this.#executeRequest('/decision', 'POST', { context }),
+            getHistory: () => this.#executeRequest('/history', 'GET')
+        };
+    }
+
+    #initAgentsProxy() {
+        const self = this;
+        return new Proxy({}, {
+            get(target, role) {
+                const agentRole = role.toLowerCase();
+                return {
+                    consult: (userPrompt, options = {}) => 
+                        self.#executeRequest(`/agent/${agentRole}/consult`, 'POST', { 
+                            prompt: userPrompt, 
+                            threadId: options.threadId 
+                        }),
+                    execute: (task, options = {}) => 
+                        self.#executeRequest(`/agent/${agentRole}/execute`, 'POST', { 
+                            prompt: task,
+                            threadId: options.threadId 
+                        })
+                };
+            }
+        });
+    }
+
+    #initKnowledgeModule() {
+        return {
+            upload: (fileObject, title = null) => {
+                const formData = new FormData();
+                formData.append('file', fileObject);
+                if (title) formData.append('title', title);
+                return this.#executeRequest('/knowledge/upload', 'POST', formData, true);
+            },
+            list: () => this.#executeRequest('/knowledge', 'GET'),
+            delete: (docId) => this.#executeRequest(`/knowledge/${docId}`, 'DELETE')
+        };
+    }
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = Zakkur;
+} else {
+    window.Zakkur = Zakkur;
+}