{"_id":"@achrafmontage/turath-graphql-api","_rev":"3-ef79c6ab9637e819918198fa42f73024","name":"@achrafmontage/turath-graphql-api","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@achrafmontage/turath-graphql-api","version":"1.0.0","_id":"@achrafmontage/turath-graphql-api@1.0.0","maintainers":[{"name":"achmontage","email":"achmontage@gmail.com"}],"dist":{"shasum":"9a7af0692e1af96817069ad60d9b0bbdcb87fc43","tarball":"https://registry.npmjs.org/@achrafmontage/turath-graphql-api/-/turath-graphql-api-1.0.0.tgz","fileCount":3,"integrity":"sha512-8TsfymsmIGL/HHG4YBj2XBUdGkT9nZSfw3YbAL0ywmES+DB8Iny7iIa2FEZCFOffQSUYqUn8AeUK8/CtlXQqLQ==","signatures":[{"sig":"MEUCIGIRqJM5LSaq3CFVMBxVEKq/tc2MYHHjqLn68Q/7c9hhAiEAwAiNPwUeUS9KzAhPi3vGTPapW3NkK/LMZd+9WAuI074=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":4031770},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"ea9aaa7848220132c7d6990670151a555de40011","scripts":{"dev":"bun --watch src/index.ts","build":"bun build ./src/index.ts --outdir ./dist --target node"},"_npmUser":{"name":"achmontage","email":"achmontage@gmail.com"},"_npmVersion":"11.6.2","description":"SDK محرك بحث وقراءة للمكتبة التراثية الإسلامية","directories":{},"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/turath-graphql-api_1.0.0_1770592985403_0.6559223838994186","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@achrafmontage/turath-graphql-api","version":"1.0.1","_id":"@achrafmontage/turath-graphql-api@1.0.1","maintainers":[{"name":"achmontage","email":"achmontage@gmail.com"}],"dist":{"shasum":"1b3e649ff753aed12ce0f52ff599aaaa68dc90d0","tarball":"https://registry.npmjs.org/@achrafmontage/turath-graphql-api/-/turath-graphql-api-1.0.1.tgz","fileCount":3,"integrity":"sha512-jJGKAy4AG0gt1AautjgUggI1muVnjR2UuB5BAjfItKT6NLL6xqPYuwWYcBJeCVGJ+i4mP/wgI2UExypc5R8Y9A==","signatures":[{"sig":"MEUCIQCP7mcKl3zK9Odz8hOaWXa/byEX0v+XgkGT+Lk4oHqBPQIgZhJeC6ExiMl+orHRAFQqWn36tPKBeViiqyWt3Kkd86w=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":687387},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"ea9aaa7848220132c7d6990670151a555de40011","scripts":{"dev":"bun --watch src/index.ts","build":"bun build ./src/index.ts --outdir ./dist --target node"},"_npmUser":{"name":"achmontage","email":"achmontage@gmail.com"},"_npmVersion":"11.6.2","description":"SDK محرك بحث وقراءة للمكتبة التراثية الإسلامية","directories":{},"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/turath-graphql-api_1.0.1_1770595762840_0.20446618963746155","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@achrafmontage/turath-graphql-api","version":"1.0.2","description":"SDK محرك بحث وقراءة للمكتبة التراثية الإسلامية","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"dev":"bun --watch src/index.ts","build":"bun build ./src/index.ts --outdir ./dist --target node"},"PeerDependencies":{"@apollo/server":"^4.10.0","@types/jest":"^30.0.0","axios":"^1.13.4","bcryptjs":"^3.0.3","better-sqlite3":"^12.6.2","dataloader":"^2.2.3","dotenv":"^16.4.1","fs-extra":"^11.2.0","graphql":"^16.8.1","graphql-depth-limit":"^1.1.0","graphql-tag":"^2.12.6","jest":"^30.2.0","jsonwebtoken":"^9.0.3","lru-cache":"^11.2.5","node-cron":"^4.2.1","ts-jest":"^29.4.6","winston":"^3.19.0","winston-daily-rotate-file":"^5.0.0","zod":"^4.3.6"},"devDependencies":{"@jest/globals":"^30.2.0","@types/bcryptjs":"^3.0.0","@types/better-sqlite3":"^7.6.13","@types/bun":"^1.3.8","@types/jsonwebtoken":"^9.0.10","@types/node":"^20.11.0","@types/supertest":"^6.0.3","supertest":"^7.2.2","tsx":"^4.7.1","typescript":"^5.3.3","husky":"^8.0.0"},"gitHead":"ea9aaa7848220132c7d6990670151a555de40011","_id":"@achrafmontage/turath-graphql-api@1.0.2","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-jrrq5RNI92i17zQ0M9rnOa70gnwIhFF2NLbVXlITkBUZTrdwVL86+wDCT6PvvMUbInRBkgzjqezpj7hG/GZa5g==","shasum":"690d5145c38885b7ab1dc5b918c87c8130fe93f7","tarball":"https://registry.npmjs.org/@achrafmontage/turath-graphql-api/-/turath-graphql-api-1.0.2.tgz","fileCount":3,"unpackedSize":688319,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD7YzJynhriDa4jOH/nTH5DigCfBnRt22jXLERF4wo6oQIgHG8l6bdgiWAHnuAX2FyKmS/NLi4tfsN9M1vwOSd/PzA="}]},"_npmUser":{"name":"achmontage","email":"achmontage@gmail.com"},"directories":{},"maintainers":[{"name":"achmontage","email":"achmontage@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/turath-graphql-api_1.0.2_1770597005724_0.11110333555694618"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-08T23:23:05.293Z","modified":"2026-02-09T00:30:06.009Z","1.0.0":"2026-02-08T23:23:05.565Z","1.0.1":"2026-02-09T00:09:23.023Z","1.0.2":"2026-02-09T00:30:05.887Z"},"description":"SDK محرك بحث وقراءة للمكتبة التراثية الإسلامية","maintainers":[{"name":"achmontage","email":"achmontage@gmail.com"}],"readme":"\r\n---\r\n\r\n# 📚 Turath GraphQL API\r\n\r\nمحرك بحث وقراءة متطور للمكتبة التراثية الإسلامية، مبني باستخدام **GraphQL** و **Bun**، ويعتمد على محرك **تراث (Turath.io)** كخلفية للبيانات مع نظام كاش محلي فائق السرعة.\r\n\r\n## 🚀 المميزات الرئيسية\r\n\r\n* **Advanced Search**: بحث متقدم يدعم الفلترة حسب التصنيفات، المؤلفين، والكتب مع التحكم في دقة النتائج (Precision).\r\n* **High Performance**: سرعة خرافية بفضل استخدام **Bun** كبيئة تشغيل، ونظام **DataLoaders** لتقليل طلبات الـ API (حل مشكلة N+1).\r\n* **Smart Caching**: نظام كاش مزدوج (Memory Cache) للنصوص والنتائج المتكررة لضمان استجابة فورية.\r\n* **Favorites System**: نظام مفضلات متكامل مرتبط بقاعدة بيانات **SQLite** محلية، مع فهرسة (Indexing) تضمن جلب البيانات في أقل من 1ms.\r\n* **Book Reader**: مستعرض صفحات يدعم إزالة التشكيل، فصل الهوامش تلقائياً، واستخراج العناوين (Headings).\r\n* **Security**: حماية متكاملة عبر **JWT Authentication**، و **Rate Limiting**، ومنع الاستعلامات العميقة (Depth Limit).\r\n\r\n## 🛠 التكنولوجيات المستخدمة\r\n\r\n* **Runtime**: [Bun](https://bun.sh/) (Fast JS Runtime).\r\n* **API**: Apollo Server 4 (GraphQL).\r\n* **Database**: SQLite (Better-SQLite3).\r\n* **Validation**: Zod.\r\n* **Testing**: Bun Test (Integration Testing).\r\n* **Task Management**: Husky (Git Hooks).\r\n\r\n## 📥 التنصيب والتشغيل\r\n\r\n1. **استنساخ المستودع:**\r\n```bash\r\ngit clone https://github.com/your-username/turath-graphql-api.git\r\ncd turath-graphql-api\r\n\r\n```\r\n\r\n\r\n2. **تثبيت الاعتماديات:**\r\n```bash\r\nbun install\r\n\r\n```\r\n\r\n\r\n3. **إعداد المتغيرات البيئية:**\r\nقم بإنشاء ملف `.env` في المجلد الرئيسي وأضف القيم التالية:\r\n```env\r\nPORT=4000\r\nJWT_SECRET=your_super_secret_key\r\nAPI_KEY=your_internal_api_key\r\nNODE_ENV=development\r\n\r\n```\r\n\r\n\r\n4. **تشغيل السيرفر:**\r\n```bash\r\nbun run dev\r\n\r\n```\r\n\r\n\r\n\r\n## 🧪 الاختبارات (Testing)\r\n\r\nنستخدم نظام اختبارات متكامل يغطي دورة حياة المستخدم (التسجيل -> الدخول -> البحث -> التفضيل):\r\n\r\n```bash\r\nbun test\r\n\r\n```\r\n\r\n*يتم تشغيل الاختبارات تلقائياً قبل كل `git commit` لضمان استقرار النظام.*\r\n\r\n## 📈 هيكل البيانات (GraphQL Schema)\r\n\r\n### أهم الاستعلامات (Queries):\r\n\r\n* `searchTurath`: البحث العام والمتقدم في المكتبة.\r\n* `getPage`: جلب نص صفحة معينة مع معالجة الهوامش.\r\n* `allBooks`: عرض الكتب مع دعم الـ Pagination والـ Cursor.\r\n\r\n### أهم العمليات (Mutations):\r\n\r\n* `register` / `login`: نظام الهوية.\r\n* `toggleFavorite`: إضافة/إزالة الصفحات من المفضلة مع إمكانية إضافة ملاحظات.\r\n\r\n## 📂 تنظيم المشروع\r\n\r\n```text\r\n├── src/\r\n│   ├── schema/        # تعريف GraphQL TypeDefs\r\n│   ├── resolvers/     # منطق العمليات (Business Logic)\r\n│   ├── utils/         # الأدوات المساعدة (DB, Loaders, Logger)\r\n│   └── main.ts        # نقطة انطلاق السيرفر\r\n├── tests/             # اختبارات التكامل (Integration Tests)\r\n├── data/              # قاعدة بيانات SQLite والنسخ الاحتياطي\r\n└── .husky/            # خطافات Git للفحص التلقائي\r\n\r\n```\r\n\r\n---\r\n\r\n**ملاحظة:** هذا المشروع غير رسمي ويعتمد على API موقع تراث. شكراً للقائمين على مشروع تراث الأصلي.\r\n\r\n---\r\n\r\nإليك قسم توثيق الـ **API Endpoints** بشكل مفصل واحترافي، يمكنك إضافته مباشرة إلى ملف الـ `README.md`. تم تصميمه ليكون مرجعاً سهلاً لأي مطور يريد الربط مع السيرفر الخاص بك.\r\n\r\n---\r\n\r\n## 📖 توثيق نقاط الاتصال (API Endpoints Documentation)\r\n\r\nيستخدم المشروع **GraphQL**، مما يعني وجود نقطة اتصال واحدة (`/graphql`) تدعم الاستعلامات (Queries) والعمليات (Mutations).\r\n\r\n### 🔍 أولاً: البحث والقراءة (Search & Reading)\r\n\r\n#### 1. البحث المتقدم `searchTurath`\r\n\r\nيوفر بحثاً فائق السرعة مع فلاتر دقيقة.\r\n\r\n* **Arguments:**\r\n* `q` (String!): كلمة البحث.\r\n* `categories` ([Int]): قائمة بأرقام التصنيفات للبحث فيها فقط.\r\n* `books` ([Int]): قائمة بأرقام كتب محددة.\r\n* `precision` (Int): دقة البحث (1 = دقيق، 2 = عريض).\r\n* `limit` (Int): عدد النتائج في الصفحة (Default: 10).\r\n* `page` (Int): رقم الصفحة المطلوب جلبها.\r\n\r\n\r\n* **Response Field Example:** `data { id book_name text page isFavorite }`\r\n\r\n#### 2. جلب الصفحات `getPage`\r\n\r\nعرض محتوى صفحة معينة مع معالجة ذكية للنص.\r\n\r\n* **Arguments:**\r\n* `bookId` (Int!): معرف الكتاب.\r\n* `page` (Int!): رقم الصفحة.\r\n* `removeTashkeel` (Boolean): إزالة التشكيل من النص (Default: false).\r\n\r\n\r\n* **Key Response Fields:**\r\n* `mainText`: النص الأساسي بدون الهوامش.\r\n* `footnotes`: الهوامش المستخرجة من أسفل الصفحة.\r\n* `headings`: العناوين المستنبطة تلقائياً من النص.\r\n\r\n\r\n\r\n---\r\n\r\n### 🔐 ثانياً: الحساب والمفضلات (Auth & Favorites)\r\n\r\n#### 1. تسجيل الدخول `login` (Mutation)\r\n\r\n* **Arguments:** `username`, `password`\r\n* **Returns:** `token` (JWT) يُستخدم في الـ Header كـ `Authorization: Bearer <token>`.\r\n\r\n#### 2. تبديل المفضلة `toggleFavorite` (Mutation)\r\n\r\nإضافة أو إزالة صفحة من المفضلة في عملية واحدة.\r\n\r\n* **Arguments:**\r\n* `bookId` (ID!): معرف الكتاب.\r\n* `pageNumber` (Int!): رقم الصفحة.\r\n* `note` (String): ملاحظة شخصية على هذه الصفحة (اختياري).\r\n* `bookTitle` (String): عنوان الكتاب للحفظ السريع (اختياري).\r\n\r\n\r\n* **Returns:** `success`, `isFavorite` (الحالة الجديدة).\r\n\r\n---\r\n\r\n### 📚 ثالثاً: المكتبة والمؤلفين (Library Metadata)\r\n\r\n#### 1. استعراض الكتب `allBooks`\r\n\r\nجلب قائمة الكتب مع دعم الـ Pagination المعتمد على الـ Cursor.\r\n\r\n* **Arguments:** `limit`, `cursor`, `filter`.\r\n* **DataLoader Integration:** يتم جلب بيانات المؤلفين والتصنيفات بشكل دفعي (Batching) لضمان سرعة الاستجابة.\r\n\r\n#### 2. معلومات المؤلف `getAuthor`\r\n\r\n* **Arguments:** `id` (Int!).\r\n* **Fields:** `name`, `death`, `bio` (السيرة الذاتية).\r\n\r\n---\r\n\r\n### 🛠️ أمثلة على الطلبات (Query Samples)\r\n\r\n**البحث عن \"النية\" في كتب الفقه فقط:**\r\n\r\n```graphql\r\nquery {\r\n  searchTurath(q: \"النية\", categories: [5], limit: 5) {\r\n    count\r\n    data {\r\n      book_name\r\n      text\r\n      page\r\n    }\r\n  }\r\n}\r\n\r\n```\r\n\r\n**قراءة صفحة مع التحقق من المفضلة:**\r\n\r\n```graphql\r\nquery {\r\n  getPage(bookId: 36422, page: 12) {\r\n    mainText\r\n    footnotes\r\n    isFavorite\r\n  }\r\n}\r\n\r\n```\r\n\r\n---\r\n\r\n> **نصيحة للمطورين:** يمكنك الوصول إلى واجهة **Apollo Sandbox** التفاعلية عبر الرابط `http://localhost:4000/graphql` عند تشغيل السيرفر في وضع التطوير لرؤية التوثيق الحي (Schema Introspection).\r\n\r\n---\r\n","readmeFilename":"Readme.md"}