From efdcffe18fc68ebf75161697b29f339ae1eecec5 Mon Sep 17 00:00:00 2001
From: szbk <wisecolt@gmail.com>
Date: Fri, 7 Nov 2025 23:06:37 +0300
Subject: [PATCH] first commit

---
 Readme.md | 432 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 382 insertions(+), 50 deletions(-)

diff --git a/Readme.md b/Readme.md
index cdbd45e..17a87cb 100644
--- a/Readme.md
+++ b/Readme.md
@@ -1,87 +1,419 @@
-# Unoffical Amazon Book Search
+# Unofficial Amazon Book Search
 
-This library allows you to retrieve book information from Amazon using only the ISBN number, without needing an API key. The library analyzes Amazon HTML structure and returns book details in JSON format. It works asynchronously (based on Promises). 
+A powerful Node.js library that retrieves comprehensive book information from Amazon using ISBN numbers without requiring an Amazon API key. This library intelligently parses Amazon's HTML structure to extract book details and returns them in a clean JSON format. Built with asynchronous operations for optimal performance.
 
-At the same time, you can recreate book descriptions using Gemini AI with this library. Remember that you need an API key for the Gemini service to do this! 
+Additionally, integrate Google's Gemini AI to enhance or regenerate book descriptions, providing richer and more engaging content for your applications.
 
 ## ✨ Features
 
-- 📚 Retrieves book information from Amazon using the ISBN number.
-- 🖼️ Returns detailed information such as book cover, title, author, genre, and publication date.
-- 🕒 Customizable delay between requests.
-- ✅ Tests integrated with Mocha and Chai.
-- 🌐 Web data is fetched and parsed using Axios and Cheerio.
-- 🤖 Book descriptions created with Gemini AI!
+- 📚 **ISBN-based Search**: Retrieve book information from Amazon using ISBN numbers only
+- 🌍 **Multi-regional Support**: Works with both Amazon.com (English) and Amazon.com.tr (Turkish)
+- 🖼️ **Rich Metadata**: Extract comprehensive details including:
+  - Book cover images (thumbnail URLs)
+  - Title and author information
+  - Page count and publication date
+  - Publisher information
+  - Customer ratings
+  - Original and AI-enhanced descriptions
+- 🤖 **AI-Powered Descriptions**: Optional integration with Google Gemini AI to generate enhanced book descriptions
+- ⚡ **Asynchronous Operations**: Promise-based API for non-blocking operations
+- 🕒 **Rate Limiting**: Built-in configurable delay between requests to avoid Amazon rate limiting
+- ✅ **Comprehensive Testing**: Full test suite using Mocha and Chai
+- 🔧 **Flexible Configuration**: Customizable headers, timeouts, and request parameters
+- 🌐 **Web Scraping**: Intelligent HTML parsing using Axios and Cheerio
+- 📦 **Lightweight**: Minimal dependencies and easy integration
 
 ## 🎯 Requirements
 
-- Node.js (v14 veya üzeri)
-- NPM
-- Internet connection
-- Curiosity
-- Preferred Gemini AI API Key!
+- **Node.js**: Version 14.0 or higher
+- **NPM**: Version 6.0 or higher (comes with Node.js)
+- **Internet Connection**: Required to access Amazon websites
+- **Google Gemini API Key**: Optional, for AI-enhanced book descriptions
 
 ## 📦 Installation
 
+Install the package via npm:
+
 ```bash
 npm install szbk-amazon-book-search
 ```
+
+### Development Installation
+
+For development or testing purposes:
+
+```bash
+git clone https://github.com/szbk/szbk-amazon-book-search.git
+cd szbk-amazon-book-search
+npm install
+```
+
 ## 🚀 Usage
 
-The following example shows how to use the API:
+### Basic Usage
+
+The following example demonstrates basic usage with ISBN search:
 
 ```javascript
 const AmazonBookSearch = require("szbk-amazon-book-search");
 
 (async () => {
   try {
-    const BookSearch = new AmazonBookSearch("en");
-    const bookDetails = await BookSearch.getBookDetails("0593724283");
-    // const bookDetails = await BookSearch.getBookDetails("0593724283", "Gemini API Key");
+    // Initialize for English Amazon
+    const bookSearch = new AmazonBookSearch("en");
+
+    // Get book details using ISBN
+    const bookDetails = await bookSearch.getBookDetails("0593724283");
 
     console.log(bookDetails);
   } catch (error) {
     console.error("Error:", error.message);
   }
 })();
+```
 
+### Usage with Gemini AI Integration
 
-// Example Output:
+Enhance book descriptions using Google's Gemini AI:
+
+```javascript
+const AmazonBookSearch = require("szbk-amazon-book-search");
+
+(async () => {
+  try {
+    const bookSearch = new AmazonBookSearch("en");
+
+    // Include your Gemini API key for enhanced descriptions
+    const bookDetails = await bookSearch.getBookDetails(
+      "0593724283",
+      "YOUR_GEMINI_API_KEY"
+    );
+
+    console.log(bookDetails);
+  } catch (error) {
+    console.error("Error:", error.message);
+  }
+})();
+```
+
+### Turkish Amazon Support
+
+Search on Amazon Turkey:
+
+```javascript
+const AmazonBookSearch = require("szbk-amazon-book-search");
+
+(async () => {
+  try {
+    // Initialize for Turkish Amazon
+    const bookSearch = new AmazonBookSearch("tr");
+
+    const bookDetails = await bookSearch.getBookDetails("9944824453");
+
+    console.log(bookDetails);
+  } catch (error) {
+    console.error("Error:", error.message);
+  }
+})();
+```
+
+## 📋 API Reference
+
+### Constructor
+
+```javascript
+new AmazonBookSearch(location)
+```
+
+**Parameters:**
+- `location` (string): Amazon region to use.
+  - `"en"` - Amazon.com (English)
+  - `"tr"` - Amazon.com.tr (Turkish)
+
+**Returns:** AmazonBookSearch instance
+
+### Methods
+
+#### `getBookDetails(isbn, geminiApiKey?)`
+
+Retrieves detailed book information using the ISBN number.
+
+**Parameters:**
+- `isbn` (string): The ISBN number of the book (10 or 13 digits)
+- `geminiApiKey` (string, optional): Google Gemini API key for enhanced descriptions
+
+**Returns:** Promise resolving to book details object
+
+## 📊 Response Format
+
+The `getBookDetails` method returns an object with the following structure:
+
+```json
 {
-  title: 'The Desert Spear: Book Two of The Demon Cycle',
-  thumbImage: 'https://m.media-amazon.com/images/I/51VC3BV9KBL._SY445_SX342_.jpg',
-  authorName: 'Peter V. Brett',
-  description: 'INTERNATIONAL BESTSELLER •  “[Peter V. Brett] confirms his place among epic fantasy’s pantheon of greats amid the likes of George R. R. Martin, Steven Erikson, and Robert Jordan.”—Fantasy Book Critic The second volume in the internationally bestselling Demon Cycle series continues the epic tale of humanity’s last stand against an army of demons—and reveals a new contender for the role of savior. The sun is setting on humanity. The night now belongs to voracious demons that prey upon a dwindling population forced to cower behind half-forgotten symbols of power. Legends tell of a Deliverer: a general who once bound all mankind into a single force that defeated the demons. But is the return of the Deliverer just another myth?  Out of the sands rides Ahmann Jardir, who has forged the desert tribes of Krasia into a demon-killing army. He has proclaimed himself Shar’Dama Ka, the Deliverer, and carries ancient weapons—a spear and a crown—that give credence to his claim.  But the Northerners claim their own Deliverer: the Warded Man, a dark, forbidding figure. Once, the Shar’Dama Ka and the Warded Man were friends. Now they are fierce adversaries. Yet as old allegiances are tested and fresh alliances forged, all are unaware of the appearance of a new breed of demon, more intelligent—and deadly—than any that have come before.  Includes a bonus Demon Cycle novella, Brayan’s Gold, and a Krasian dictionaryDon’t miss any of the thrilling novels in Peter V. Brett’s Demon Cycle THE WARDED MAN • THE DESERT SPEAR • THE DAYLIGHT WAR • THE SKULL THRONE • THE CORE',
-  page: 864,
-  publisher: 'Del Rey',
-  isbn: '0593724283',
-  date: 'November 7, 2023',
-  rate: '4.5'
+  "title": "The Desert Spear: Book Two of The Demon Cycle",
+  "thumbImage": "https://m.media-amazon.com/images/I/51VC3BV9KBL._SY445_SX342_.jpg",
+  "authorName": "Peter V. Brett",
+  "description": "Enhanced book description (if Gemini API key provided) or original description",
+  "page": 864,
+  "publisher": "Del Rey",
+  "isbn": "0593724283",
+  "date": "November 7, 2023",
+  "rate": "4.5"
 }
 ```
 
+**Field Descriptions:**
+- `title`: Book title
+- `thumbImage`: URL to the book cover thumbnail image
+- `authorName`: Author's full name
+- `description`: Book description (original or AI-enhanced)
+- `page`: Number of pages
+- `publisher`: Publishing house name
+- `isbn`: ISBN number used for search
+- `date`: Publication date
+- `rate`: Customer rating (format: "X.X")
+
 ## 📂 Project Structure
-```javascript
-szbk-amazon-search-book
-├── config
-│   └── index.js        # Configuration file
-├── lib
-│   ├── index.js        # AmazonBookSearch class
-│   └── module.js       # Data processing and parsing operations
-├── test
-│   └── index.js        # Integration tests
-├── index.js            # Entry point
-├── package.json        # Dependencies and scripts
-└── README.md           # Documentation
+
+```
+szbk-amazon-book-search/
+├── config/
+│   └── index.js              # Configuration settings (URLs, headers, timeouts)
+├── lib/
+│   ├── index.js              # Main AmazonBookSearch class
+│   └── module.js             # Data processing, HTML parsing, and Gemini AI integration
+├── test/
+│   └── index.js              # Comprehensive integration tests (English & Turkish)
+├── reports/                  # Test report output directory
+├── .claude/                  # Claude configuration directory
+├── .git/                     # Git repository metadata
+├── index.js                  # Package entry point
+├── package.json              # Dependencies and npm scripts
+├── package-lock.json         # Dependency lock file
+├── Jenkinsfile               # CI/CD pipeline configuration
+├── mocha-report-config.json  # Test reporting configuration
+├── .gitignore                # Git ignore patterns
+├── .npmignore                # NPM ignore patterns
+└── README.md                 # This documentation
 ```
 
-## 🧪 Tests
-To run the tests, follow these steps:
-1. Install test dependencies:
-    ```javascript
-    npm install
-    ```
-2. Run the tests:
-      ```javascript
-    npm test
-    ```  
\ No newline at end of file
+### Key Components
+
+- **`config/index.js`**: Amazon URLs, request headers, timeout settings
+- **`lib/index.js`**: Core AmazonBookSearch class with search functionality
+- **`lib/module.js`**: HTML parsing logic and Gemini AI integration
+- **`test/index.js`**: Comprehensive test suite covering both regions and AI features
+
+## 🧪 Testing
+
+### Running Tests
+
+The library includes a comprehensive test suite covering both Amazon regions and Gemini AI integration.
+
+```bash
+# Install dependencies
+npm install
+
+# Run all tests
+npm test
+```
+
+### Test Coverage
+
+The test suite includes:
+
+- **Turkish Amazon Tests** (ISBN: 9944824453)
+  - ISBN validation
+  - Title extraction ("Dövmeli Adam: İblis Döngüsü 1")
+  - Thumbnail image retrieval
+  - Publication date parsing
+  - Page count extraction
+  - Publisher information
+  - Gemini AI integration for Turkish descriptions
+
+- **English Amazon Tests** (ISBN: 0593724283)
+  - ISBN validation
+  - Title extraction ("The Desert Spear: Book Two of The Demon Cycle")
+  - Thumbnail image retrieval
+  - Publication date parsing
+  - Page count extraction
+  - Publisher information
+
+### Test Configuration
+
+Tests are configured using:
+- **Mocha**: Test framework
+- **Chai**: Assertion library
+- **Mocha Multi-Reporters**: Generates test reports in multiple formats
+- **Timeout**: 30 seconds per test to accommodate network requests
+
+### Test Reports
+
+Test results are generated in the `reports/` directory with detailed XML reports for CI/CD integration.
+
+## 🚀 CI/CD Integration
+
+### Jenkins Pipeline
+
+The project includes a pre-configured Jenkinsfile for automated testing and deployment:
+
+**Pipeline Features:**
+- **Scheduled Builds**: Runs every 6 hours
+- **Node.js Environment**: Uses Node.js v22.13.0
+- **Automated Testing**: Installs dependencies and runs test suite
+- **Test Reporting**: Publishes test results as JUnit XML
+- **Slack Integration**: Sends build notifications to #jenkins channel
+- **Build Status Tracking**: Success/failure notifications with build URLs
+
+**Pipeline Stages:**
+1. Directory cleanup
+2. Dependency installation
+3. Test execution
+4. Test result publishing
+5. Slack notifications
+
+## ⚙️ Configuration
+
+### Default Configuration
+
+The library uses predefined settings located in `config/index.js`:
+
+```javascript
+{
+  en_base_url: "https://www.amazon.com/s?k=",
+  en_detail_url: "https://www.amazon.com/dp/",
+  tr_base_url: "https://www.amazon.com.tr/s?k=",
+  tr_detail_url: "https://www.amazon.com.tr/dp/",
+  headers: {
+    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
+  },
+  fetchTimeout: 2000  // 2 seconds delay between requests
+}
+```
+
+### Rate Limiting
+
+The library includes built-in rate limiting with a 2-second delay between requests to prevent Amazon from blocking requests and to be respectful to their servers.
+
+## 🤖 Gemini AI Integration
+
+### Setup
+
+To use the Gemini AI feature for enhanced book descriptions:
+
+1. **Get API Key**: Obtain a Google Gemini API key from [Google AI Studio](https://aistudio.google.com/app/apikey)
+2. **Add to Project**: Include the API key in your environment variables or pass it directly to the method
+
+### Usage
+
+```javascript
+const AmazonBookSearch = require("szbk-amazon-book-search");
+
+// Method 1: Pass API key directly
+const bookDetails = await bookSearch.getBookDetails(isbn, "YOUR_GEMINI_API_KEY");
+
+// Method 2: Use environment variable
+require('dotenv').config();
+const bookDetails = await bookSearch.getBookDetails(isbn, process.env.GEMINI_API_KEY);
+```
+
+### Description Enhancement
+
+When Gemini AI is enabled:
+- **Original Description**: Extracted from Amazon's product page
+- **Enhanced Description**: Gemini analyzes the original and creates an improved, more engaging description
+- **Language Support**: Supports both English and Turkish descriptions
+- **Length Preservation**: Maintains similar length to original descriptions
+
+## ⚠️ Important Considerations
+
+### Rate Limiting & Best Practices
+
+- **Built-in Delay**: 2-second delay between requests prevents rate limiting
+- **Respectful Usage**: Don't make excessive requests in short time periods
+- **Error Handling**: Always wrap requests in try-catch blocks
+- **Network Issues**: Handle potential connection timeouts
+
+### Legal & Ethical Usage
+
+- **Educational Purposes**: This library is intended for educational and development use
+- **Amazon Terms**: Be aware of Amazon's terms of service regarding web scraping
+- **Commercial Use**: Obtain proper permissions before using in commercial applications
+- **Data Usage**: Use extracted data responsibly and ethically
+
+### Dependencies
+
+The library uses the following key dependencies:
+
+- **axios** (v1.6.8): HTTP client for making requests to Amazon
+- **cheerio** (v1.0.0-rc.12): HTML parsing and DOM manipulation
+- **@google/generative-ai** (v0.8.0): Google Gemini AI integration
+- **dotenv** (v16.4.5): Environment variable management
+
+### Development Dependencies
+
+- **mocha** (v11.0.1): Test framework
+- **chai** (v5.1.2): Assertion library
+- **mocha-junit-reporter** (v2.2.1): JUnit XML test reports
+- **mocha-multi-reporters** (v1.5.1): Multiple test report formats
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+#### "Yanlış konum!" Error
+**Solution**: Ensure you use valid location codes: `"en"` or `"tr"`
+
+#### "Kitap bilgisi bulunamadı!" Error
+**Causes**:
+- Invalid ISBN number
+- Book not found on Amazon
+- Network connectivity issues
+- Amazon blocking requests
+
+**Solutions**:
+- Verify ISBN is correct (10 or 13 digits)
+- Check network connection
+- Try again after some time (rate limiting)
+- Ensure book exists on the target Amazon site
+
+#### Timeouts
+**Cause**: Slow network or Amazon response times
+**Solution**: Increase timeout in configuration if needed
+
+#### Gemini AI Not Working
+**Solutions**:
+- Verify API key is valid
+- Check Gemini API quota
+- Ensure internet connectivity
+- Try without Gemini API key first
+
+### Debug Mode
+
+Enable detailed logging by adding console statements or using a debugger to trace request flows and identify issues.
+
+## 📄 License
+
+This project is licensed under the MIT License. See LICENSE file for details.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+## 📞 Support
+
+For support and questions:
+- Create an issue on GitHub
+- Check existing issues for common problems
+- Review the troubleshooting section above
+
+## 🔗 Related Links
+
+- [Amazon.com](https://www.amazon.com)
+- [Amazon Turkey](https://www.amazon.com.tr)
+- [Google Gemini AI](https://ai.google.dev/)
+- [NPM Package](https://www.npmjs.com/package/szbk-amazon-book-search)
+
+---
+
+**Note**: This is an unofficial library and is not affiliated with or endorsed by Amazon or Google. Use responsibly and in accordance with the terms of service of the respective platforms.  
\ No newline at end of file