# n8n Gemini AI Community Node - Installation & Deployment Guide
# دليل تثبيت ونشر إضافة Gemini AI لـ n8n

This document provides step-by-step instructions on how to publish the `n8n-nodes-wolfhub` community node to npm and install it on your n8n instance.

يحتوي هذا المستند على خطوات تفصيلية لكيفية نشر وتثبيت إضافة `n8n-nodes-wolfhub` على منصة npm وتثبيتها في بيئة n8n الخاصة بك.

---

## 🇸🇦 دليل التثبيت والنشر (Arabic Guide)

### 1. طريقة التثبيت المباشر داخل n8n (من خلال لوحة التحكم)
إذا كانت الإضافة منشورة بالفعل على موقع npm، يمكنك تثبيتها بسهولة كالتالي:
1. افتح واجهة n8n الخاصة بك واذهب إلى **Settings** (الإعدادات).
2. اختر **Community Nodes** (إضافات المجتمع).
3. اضغط على زر **Install a community node** (تثبيت إضافة مجتمع).
4. في خانة اسم الحزمة، اكتب الاسم التالي:
   ```text
   n8n-nodes-wolfhub
   ```
5. وافق على الشروط واضغط **Install** (تثبيت). سيقوم n8n بتحميل الإضافة وتفعيلها تلقائياً.

---

### 2. كيفية تجربة الإضافة محلياً (قبل النشر)
لتجربة التعديلات والتحقق من عمل الإضافة على جهازك محلياً دون الحاجة لنشرها على الإنترنت:

1. قم ببناء المشروع (Build) أولاً لتوليد ملفات الجافاسكريبت:
   ```bash
   npm run build
   ```
2. افتح مبدل الأوامر (Terminal) واذهب إلى مجلد إعدادات n8n الخاص بالمستخدم (عادة ما يكون باسم `.n8n` في مجلد المستخدم الرئيسي):
   * **على نظام Windows**:
     ```powershell
     cd $env:USERPROFILE\.n8n
     ```
   * **على نظام Linux / macOS**:
     ```bash
     cd ~/.n8n
     ```
3. قم بتثبيت المجلد المحلي الخاص بالإضافة داخل مجلد n8n:
   ```bash
   npm install "D:\Agents\nodes-wolfhub"
   ```
   *(قم باستبدال المسار بمسار مجلد الإضافة الفعلي على جهازك إذا اختلف).*
4. قم بإعادة تشغيل تطبيق n8n وسوف تظهر لك الإضافة باسم **WolfHub** مباشرة في قائمة العقد (Nodes).

---

### 3. كيفية نشر الإضافة على موقع npm (خطوة بخطوة بالتفصيل)
إذا كنت تريد إتاحة الإضافة للجميع ليتمكنوا من تثبيتها مباشرة من لوحة تحكم n8n:

#### الخطوة 1: إنشاء حساب على npm (لمرة واحدة فقط)
إذا لم يكن لديك حساب بالفعل، قم بزيارة موقع [npmjs.com](https://www.npmjs.com/) وأنشئ حساباً مجانياً وتأكد من تفعيل بريدك الإلكتروني (خطوة أساسية ليسمح لك بنشر الحزم).

#### الخطوة 2: تسجيل الدخول عبر Terminal
افتح موجه الأوامر (Terminal/PowerShell) داخل مجلد المشروع (`D:\Agents\nodes-wolfhub`) واكتب الأمر التالي:
```bash
npm login
```
* **ماذا سيحدث بعد كتابة هذا الأمر؟**
  1. سيطلب منك النظام الضغط على مفتاح (Enter) لفتح المتصفح لتسجيل الدخول بأمان، أو قد يطلب منك إدخال اسم المستخدم وكلمة المرور والرمز السري (OTP) المرسل لبريدك الإلكتروني مباشرة في الـ Terminal.
  2. بمجرد إكمال تسجيل الدخول بنجاح، ستظهر لك رسالة في الـ Terminal تؤكد تسجيل دخولك:
     ```text
     Logged in as <username> on https://registry.npmjs.org/.
     ```
  3. للتأكد من أنك متصل بحسابك بنجاح، يمكنك كتابة الأمر التالي:
     ```bash
     npm whoami
     ```
     (سيقوم بطباعة اسم المستخدم الخاص بك على npm).

#### الخطوة 3: إدارة رقم الإصدار (Version) في `package.json`
قبل أي عملية رفع أو تحديث، يجب عليك تحديد رقم الإصدار المناسب في ملف `package.json` (السطر رقم 3):
* **إذا كانت هذه المرة الأولى للنشر**: يمكنك ترك الإصدار كما هو `"version": "1.0.0"`.
* **إذا كنت تقوم بتحديث كود أو إصلاح مشكلة**: يجب عليك زيادة رقم الإصدار (مثال: `"version": "1.0.1"`).
  * *ملاحظة هامة:* لن يقبل موقع npm رفع الإضافة بنفس رقم الإصدار القديم أبداً، يجب دائماً زيادة الرقم لتفادي خطأ `You cannot publish over the previously published versions`.

#### الخطوة 4: بناء المشروع وفحصه (Build & Lint)
للتأكد من أن الكود سليم وخالٍ من الأخطاء التجميعية قبل رفعه:
```bash
npm run build
```
سيقوم هذا الأمر بترجمة كود TypeScript إلى JavaScript وتوليد المجلد `dist` الذي يحتوي على الملفات النهائية التي سيتم رفعها.

#### الخطوة 5: رفع الحزمة ونشرها للعامة (Publish)
لرفع المشروع وتثبيته كـ Public (متاح للجميع مجاناً)، قم بتشغيل الأمر التالي:
```bash
npm config set //registry.npmjs.org/:_authToken="npm_YOUR_TOKEN_HERE"

npm publish --access public
npm run build
npm publish --access public --ignore-scripts


```
* **لماذا نستخدم `--access public`؟** 
  لأن الحزم الجديدة قد تُعتبر خاصة (Private) بشكل افتراضي لدى npm إذا كانت تتبع نطاقاً معيناً، ولذلك نحدد الخيار `--access public` لضمان رفعها كحزمة عامة ومجانية يستطيع خادم n8n الوصول إليها وتحميلها.
* **ماذا يحدث بعد تشغيل هذا الأمر؟**
  1. سيقوم npm تلقائياً بتشغيل اختبار الفحص `lint` وبناء المشروع `build` (بفضل سكربت `prepublishOnly` الموجود في ملف `package.json`).
  2. سيتم ضغط ملفات مجلد `dist` ورفعها لخوادم npm.
  3. عند النجاح، ستظهر لك رسالة نجاح خضراء تشبه التالي:
     ```text
     + n8n-nodes-wolfhub@1.0.0
     ```

بعد اكتمال الخطوات بنجاح، يمكنك الذهاب إلى متصفحك وفتح الرابط:
`https://www.npmjs.com/package/n8n-nodes-wolfhub` لمشاهدة حزمتك منشورة على الإنترنت، ويمكنك الآن تثبيتها مباشرة في n8n بالاسم المذكور!

---


## 🇺🇸 Installation & Deployment Guide (English Guide)

### 1. Standard Installation inside n8n UI
Once the package is published on npm, anyone can install it on their n8n instance by following these steps:
1. Open your n8n Instance and navigate to **Settings**.
2. Click on **Community Nodes**.
3. Click the **Install a community node** button.
4. Enter the npm package name:
   ```text
   n8n-nodes-wolfhub
   ```
5. Agree to the terms and click **Install**. n8n will automatically download, compile, and add the node to your workspace.

---

### 2. Local Installation & Testing (Development Mode)
To test your changes locally on your machine without publishing to npm:

1. Compile the TypeScript project first:
   ```bash
   npm run build
   ```
2. Open your terminal and navigate to your local n8n configuration directory (usually `.n8n` in your user profile folder):
   * **On Windows**:
     ```powershell
     cd $env:USERPROFILE\.n8n
     ```
   * **On Linux / macOS**:
     ```bash
     cd ~/.n8n
     ```
3. Run `npm install` pointing to your local node repository folder:
   ```bash
   npm install "D:\Agents\nodes-wolfhub"
   ```
   *(Change the path to your actual repository path if it is different).*
4. Restart your n8n server. The **WolfHub** node will now be loaded and ready for use!

---

### 3. Publishing to npm (Step-by-Step Guide)
To make your community node available on the public npm registry for anyone to install directly from their n8n dashboard:

#### Step 1: Create an npm Account
If you haven't already, sign up for a free account at [npmjs.com](https://www.npmjs.com/). Make sure to verify your email address (this is a mandatory step by npm to allow package publishing).

#### Step 2: Log into npm via Terminal
Open your terminal/PowerShell in the repository directory and run:
```bash
npm login
```
* **What happens next?**
  1. The command will prompt you to press Enter to authenticate via a browser window or ask for your username, password, and OTP code.
  2. Once successfully authenticated, you will see a confirmation message:
     ```text
     Logged in as <username> on https://registry.npmjs.org/.
     ```
  3. You can verify your session at any time by running:
     ```bash
     npm whoami
     ```
     (This prints your logged-in username).

#### Step 3: Manage Your Version in `package.json`
Every publish operation requires a unique version number (configured on line 3 of `package.json`):
* **Initial Release**: Use `"version": "1.0.0"`.
* **Updates & Fixes**: Increment the version number (e.g., `"version": "1.0.1"`).
  * *Important:* npm will reject publishes using an existing version with a `You cannot publish over the previously published versions` error.

#### Step 4: Build the Project
Ensure that all TypeScript files compile properly before publishing:
```bash
npm run build
```
This generates the updated JS files in the `dist` directory.

#### Step 5: Publish the Package
To upload and publish your package publicly, run:
```bash
npm publish --access public
```
* **Why `--access public`?**
  npm requires this flag to ensure scoped packages or packages that could default to private are made public. Community nodes must be public for n8n to download them.
* **What happens behind the scenes?**
  1. npm automatically triggers the `prepublishOnly` script defined in `package.json` to build and lint the code.
  2. It packages the `dist` folder files and uploads them.
  3. On success, it displays:
     ```text
     + n8n-nodes-wolfhub@1.0.0
     ```

Your package will now be active at `https://www.npmjs.com/package/n8n-nodes-wolfhub` and can be immediately installed inside n8n!