@avalw/search-worker 1.0.2 → 1.1.0

package/README.md

@@ -7,39 +7,217 @@ Free privacy-focused search API in exchange for compute power.
 
 ## What is AVALW Worker?
 
-AVALW Worker is a lightweight Node.js application that runs on your server and contributes a small amount of CPU power to the AVALW distributed network. In return, you get **free, unlimited access** to the AVALW Search API - a privacy-focused search engine that doesn't track users.
+AVALW Worker is a lightweight Node.js application that runs on your server and contributes CPU power to the AVALW distributed network. In return, you get **free access** to the AVALW Search API - a privacy-focused search engine that doesn't track users. Your API quota scales with your contribution.
 
 **No tracking. No ads. No data collection. Just search.**
 
 ## How It Works
 
 ```
-┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
-│   Your Server   │      │  AVALW Network  │      │   Your Users    │
-│                 │      │                 │      │                 │
-│  ┌───────────┐  │      │                 │      │                 │
-│  │  Worker   │──┼─────►│  Contributes    │      │                 │
-│  │  Process  │  │      │  compute power  │      │                 │
-│  └───────────┘  │      │                 │      │                 │
-│                 │      │                 │      │                 │
-│  ┌───────────┐  │      │                 │      │  ┌───────────┐  │
-│  │  Your App │◄─┼──────┤  Search API     │◄─────┼──│  Search   │  │
-│  │           │  │      │  (free access)  │      │  │  Queries  │  │
-│  └───────────┘  │      │                 │      │  └───────────┘  │
-└─────────────────┘      └─────────────────┘      └─────────────────┘
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           AVALW WORKER SYSTEM                               │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   YOUR SERVER                      AVALW NETWORK           YOUR USERS       │
+│   ───────────                      ────────────            ──────────       │
+│                                                                             │
+│   ┌─────────────┐                 ┌─────────────┐                           │
+│   │   Worker    │ ───────────────►│  Compute    │                           │
+│   │   Process   │   Contributes   │   Pool      │                           │
+│   │             │   Core-Hours    │             │                           │
+│   │  CPU: ████░ │                 │ ┌─┐┌─┐┌─┐┌─┐│                           │
+│   │       70%   │                 │ └─┘└─┘└─┘└─┘│                           │
+│   └─────────────┘                 └──────┬──────┘                           │
+│         │                                │                                  │
+│         │ Reports:                       │ Calculates:                      │
+│         │ • CPU cores                    │ • Core-hours                     │
+│         │ • CPU speed (GHz)              │ • Your tier                      │
+│         │ • Usage %                      │ • API quota                      │
+│         │ • Online time                  │                                  │
+│         ▼                                ▼                                  │
+│   ┌─────────────┐                 ┌─────────────┐        ┌─────────────┐   │
+│   │   Your App  │◄────────────────│  Search API │◄───────│   Search    │   │
+│   │             │   Free access   │  (quota     │        │   Query     │   │
+│   │  // search  │   based on      │   based)    │        │             │   │
+│   │  fetch(..); │   contribution  │             │        │  "weather"  │   │
+│   └─────────────┘                 └─────────────┘        └─────────────┘   │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
 ```
 
-## Tiers
+## Core-Hours System
 
-Choose the tier that fits your needs:
+Unlike simple percentage-based systems, AVALW uses **Core-Hours** - a fair metric that accounts for your actual hardware contribution.
 
-| Tier       | Requests/Day | CPU Contribution |
-|------------|--------------|------------------|
-| Starter    | 1,000        | 2%               |
-| Basic      | 5,000        | 5%               |
-| Pro        | 20,000       | 10%              |
-| Business   | 50,000       | 20%              |
-| Enterprise | 500,000      | 50%              |
+### What is a Core-Hour?
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         CORE-HOUR CALCULATION                               │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   Core-Hours = CPU Cores × (CPU Speed ÷ 3.0 GHz) × Usage% × Hours Online   │
+│                                                                             │
+│   ═══════════════════════════════════════════════════════════════════════   │
+│                                                                             │
+│   EXAMPLE: Intel i7-10700 running for 24 hours at 50%                       │
+│                                                                             │
+│   • Cores: 8                                                                │
+│   • Speed: 2.9 GHz base (normalized to 3.0 GHz baseline)                    │
+│   • Usage: 50%                                                              │
+│   • Time: 24 hours                                                          │
+│                                                                             │
+│   Calculation: 8 × (2.9 ÷ 3.0) × 0.50 × 24 = 92.8 core-hours/day           │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Tiers Based on Core-Hours
+
+| Tier | Requests/Day | Core-Hours/Day | Minimum Cores |
+|------|--------------|----------------|---------------|
+| **Starter** | 1,000 | 3 | 3 cores |
+| **Basic** | 5,000 | 12 | 4 cores |
+| **Pro** | 20,000 | 36 | 6 cores |
+| **Business** | 50,000 | 72 | 8 cores |
+| **Enterprise** | 500,000 | 240 | 16 cores |
+
+## Real CPU Examples
+
+### Desktop CPUs
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        DESKTOP CPU EXAMPLES                                 │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │ Intel Core i5-10400 (6 cores @ 2.9 GHz)                             │   │
+│  ├─────────────────────────────────────────────────────────────────────┤   │
+│  │ At 50% for 24h: 6 × 0.97 × 0.50 × 24 = 69.8 core-hours             │   │
+│  │ ✓ Qualifies for: PRO tier (20,000 requests/day)                    │   │
+│  │                                                                     │   │
+│  │ At 30% for 24h: 6 × 0.97 × 0.30 × 24 = 41.9 core-hours             │   │
+│  │ ✓ Qualifies for: PRO tier (20,000 requests/day)                    │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │ Intel Core i7-10700 (8 cores @ 2.9 GHz)                             │   │
+│  ├─────────────────────────────────────────────────────────────────────┤   │
+│  │ At 50% for 24h: 8 × 0.97 × 0.50 × 24 = 93.1 core-hours             │   │
+│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
+│  │                                                                     │   │
+│  │ At 25% for 24h: 8 × 0.97 × 0.25 × 24 = 46.6 core-hours             │   │
+│  │ ✓ Qualifies for: PRO tier (20,000 requests/day)                    │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │ Intel Core i9-10900 (10 cores @ 2.8 GHz)                            │   │
+│  ├─────────────────────────────────────────────────────────────────────┤   │
+│  │ At 50% for 24h: 10 × 0.93 × 0.50 × 24 = 111.6 core-hours           │   │
+│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
+│  │                                                                     │   │
+│  │ At 80% for 24h: 10 × 0.93 × 0.80 × 24 = 178.6 core-hours           │   │
+│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │ AMD Ryzen 5 5600X (6 cores @ 3.7 GHz)                               │   │
+│  ├─────────────────────────────────────────────────────────────────────┤   │
+│  │ At 50% for 24h: 6 × 1.23 × 0.50 × 24 = 88.6 core-hours             │   │
+│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │ AMD Ryzen 7 5800X (8 cores @ 3.8 GHz)                               │   │
+│  ├─────────────────────────────────────────────────────────────────────┤   │
+│  │ At 50% for 24h: 8 × 1.27 × 0.50 × 24 = 121.9 core-hours            │   │
+│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Server CPUs
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         SERVER CPU EXAMPLES                                 │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │ Intel Xeon E-2288G (8 cores @ 3.7 GHz)                              │   │
+│  ├─────────────────────────────────────────────────────────────────────┤   │
+│  │ At 30% for 24h: 8 × 1.23 × 0.30 × 24 = 70.8 core-hours             │   │
+│  │ ✓ Qualifies for: PRO tier (20,000 requests/day)                    │   │
+│  │                                                                     │   │
+│  │ At 50% for 24h: 8 × 1.23 × 0.50 × 24 = 118.1 core-hours            │   │
+│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │ AMD EPYC 7302 (16 cores @ 3.0 GHz)                                  │   │
+│  ├─────────────────────────────────────────────────────────────────────┤   │
+│  │ At 30% for 24h: 16 × 1.00 × 0.30 × 24 = 115.2 core-hours           │   │
+│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
+│  │                                                                     │   │
+│  │ At 60% for 24h: 16 × 1.00 × 0.60 × 24 = 230.4 core-hours           │   │
+│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │ AMD EPYC 7742 (64 cores @ 2.25 GHz)                                 │   │
+│  ├─────────────────────────────────────────────────────────────────────┤   │
+│  │ At 20% for 24h: 64 × 0.75 × 0.20 × 24 = 230.4 core-hours           │   │
+│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
+│  │                                                                     │   │
+│  │ At 50% for 24h: 64 × 0.75 × 0.50 × 24 = 576.0 core-hours           │   │
+│  │ ✓ Qualifies for: ENTERPRISE tier (500,000 requests/day)            │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### VPS / Cloud Examples
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         VPS / CLOUD EXAMPLES                                │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │ Basic VPS (2 vCPU @ 2.5 GHz) - ~$5/month                            │   │
+│  ├─────────────────────────────────────────────────────────────────────┤   │
+│  │ At 80% for 24h: 2 × 0.83 × 0.80 × 24 = 31.9 core-hours             │   │
+│  │ ✗ Not enough for Starter (needs 3 cores minimum)                   │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │ Standard VPS (4 vCPU @ 2.5 GHz) - ~$20/month                        │   │
+│  ├─────────────────────────────────────────────────────────────────────┤   │
+│  │ At 50% for 24h: 4 × 0.83 × 0.50 × 24 = 39.8 core-hours             │   │
+│  │ ✓ Qualifies for: PRO tier (20,000 requests/day)                    │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │ Premium VPS (8 vCPU @ 3.0 GHz) - ~$80/month                         │   │
+│  ├─────────────────────────────────────────────────────────────────────┤   │
+│  │ At 50% for 24h: 8 × 1.00 × 0.50 × 24 = 96.0 core-hours             │   │
+│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │ AWS EC2 c5.4xlarge (16 vCPU @ 3.4 GHz)                              │   │
+│  ├─────────────────────────────────────────────────────────────────────┤   │
+│  │ At 40% for 24h: 16 × 1.13 × 0.40 × 24 = 173.6 core-hours           │   │
+│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
+│  │                                                                     │   │
+│  │ At 70% for 24h: 16 × 1.13 × 0.70 × 24 = 303.7 core-hours           │   │
+│  │ ✓ Qualifies for: ENTERPRISE tier (500,000 requests/day)            │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
 
 ## Quick Start
 
@@ -61,49 +239,41 @@ npm install -g @avalw/search-worker
 avalw-worker YOUR_WORKER_TOKEN
 ```
 
-You should see:
+You'll see real-time stats:
 ```
-  ╔═══════════════════════════════════════════════╗
-  ║         AVALW Search Worker v1.0.0            ║
-  ╠═══════════════════════════════════════════════╣
-  ║  Free Search API in exchange for compute      ║
-  ╚═══════════════════════════════════════════════╝
-
-  API URL: https://worker.avalw.org
-  Token:   abc123def456...
-
-  [10:30:45] Heartbeat OK | Tier: Starter | CPU Limit: 2%
-  Worker started. Press Ctrl+C to stop.
+  ╔═══════════════════════════════════════════════════════════════════╗
+  ║              AVALW Search Worker v1.1.0                           ║
+  ╠═══════════════════════════════════════════════════════════════════╣
+  ║  Free Search API in exchange for compute                          ║
+  ╚═══════════════════════════════════════════════════════════════════╝
+
+  System Info:
+  ├─ CPU: Intel(R) Core(TM) i7-10700 @ 2.90GHz
+  ├─ Cores: 8
+  ├─ Speed Factor: 0.97x (normalized to 3.0 GHz)
+  └─ Memory: 32 GB
+
+  Worker Status:
+  ├─ Token: abc123def456...
+  ├─ API URL: https://worker.avalw.org
+  └─ Target Usage: 50%
+
+  [10:30:45] ✓ Heartbeat OK
+  ├─ Core-Hours Today: 46.5 / 72 needed for BUSINESS
+  ├─ Current Tier: PRO (20,000 req/day)
+  ├─ Usage Today: 1,234 / 20,000
+  └─ Online: 12h 35m
+
+  Press Ctrl+C to stop.
 ```
 
 ### 4. Use the Search API
 
-Once your worker is running, make API requests from your whitelisted domains:
-
 ```javascript
-// Node.js / JavaScript
 const response = await fetch(
   'https://worker.avalw.org/api/search?q=your+query&token=YOUR_TOKEN'
 );
 const results = await response.json();
-console.log(results);
-```
-
-```python
-# Python
-import requests
-
-response = requests.get(
-    'https://worker.avalw.org/api/search',
-    params={'q': 'your query', 'token': 'YOUR_TOKEN'}
-)
-results = response.json()
-print(results)
-```
-
-```bash
-# cURL
-curl "https://worker.avalw.org/api/search?q=your+query&token=YOUR_TOKEN"
 ```
 
 ## Running as a Service
@@ -114,9 +284,12 @@ curl "https://worker.avalw.org/api/search?q=your+query&token=YOUR_TOKEN"
 # Install PM2
 npm install -g pm2
 
-# Start worker
+# Start worker with 50% CPU target
 pm2 start avalw-worker -- YOUR_WORKER_TOKEN
 
+# Or specify custom CPU percentage
+pm2 start avalw-worker -- YOUR_WORKER_TOKEN --cpu 30
+
 # Save for auto-restart
 pm2 save
 pm2 startup
@@ -161,26 +334,6 @@ docker build -t avalw-worker .
 docker run -d --name avalw-worker avalw-worker
 ```
 
-## Programmatic Usage
-
-You can also use the worker programmatically in your Node.js application:
-
-```javascript
-const { AvalwWorker } = require('@avalw/search-worker');
-
-const worker = new AvalwWorker('YOUR_WORKER_TOKEN');
-
-// Start the worker
-await worker.start();
-
-// Get system info
-const info = worker.getSystemInfo();
-console.log(info);
-
-// Stop the worker
-await worker.stop();
-```
-
 ## API Reference
 
 ### Search Endpoint
@@ -189,7 +342,6 @@ await worker.stop();
 GET https://worker.avalw.org/api/search
 ```
 
-**Parameters:**
 | Parameter | Type   | Required | Description                    |
 |-----------|--------|----------|--------------------------------|
 | q         | string | Yes      | Search query                   |
@@ -209,29 +361,46 @@ GET https://worker.avalw.org/api/search
     }
   ],
   "total": 100,
-  "page": 1
+  "page": 1,
+  "tier": "PRO",
+  "usage": {
+    "today": 1234,
+    "limit": 20000,
+    "core_hours": 46.5
+  }
 }
 ```
 
-## Domain Whitelisting
+## FAQ
 
-For security, API requests only work from whitelisted domains. Manage your domains at [worker.avalw.org](https://worker.avalw.org) dashboard.
+### Why do I need minimum 3 cores?
 
-## Troubleshooting
+The AVALW network requires meaningful contributions to remain sustainable. A 3-core minimum ensures:
+- Fair distribution of compute power
+- Quality of service for all users
+- Sustainable network operation
 
-### Worker won't connect
-- Check your internet connection
-- Verify your token is correct
-- Ensure port 443 (HTTPS) is not blocked
+### Can I run on a 2-core VPS?
 
-### API returns "Worker offline"
-- Make sure your worker is running
-- Check the worker console for errors
-- Worker must send heartbeat every 30 seconds
+Unfortunately, 2 cores don't meet the minimum requirement. Consider:
+- Upgrading to a 4-core VPS
+- Running on a different server with more cores
+- Combining with another server (coming soon: multi-worker support)
 
-### Rate limit exceeded
-- Upgrade to a higher tier for more requests
-- Wait until the daily limit resets (midnight UTC)
+### How is my tier calculated?
+
+Your tier is recalculated every hour based on your rolling 24-hour core-hours contribution. The formula:
+
+```
+Core-Hours = Cores × (Speed ÷ 3.0) × Usage% × Hours
+```
+
+### What if my server goes offline?
+
+Your core-hours accumulate only while online. If you go offline:
+- Your accumulated core-hours for the day remain
+- Your tier may drop if you don't maintain the required hours
+- API calls will fail until your worker reconnects
 
 ## Security
 
@@ -271,4 +440,11 @@ SOFTWARE.
 
 ---
 
-Made with privacy in mind by [AVALW](https://avalw.org)
+Made with privacy in mind by [AVALW](https://cronos.avalw.com/about)
+
+### Our Projects
+
+- [AVALW Search](https://avalw.org) - Privacy-focused search engine
+- [Cronos Browser](https://cronos.avalw.com) - Secure, private browser
+- [AVALW Protocol](https://avalw.com) - Decentralized communication protocol
+- [Worker API](https://worker.avalw.org) - This project

package/bin/cli.js

@@ -1,45 +1,52 @@
 #!/usr/bin/env node
 
-const { AvalwWorker } = require('../lib/worker');
+const { AvalwWorker, TIERS } = require('../lib/worker');
 
 const token = process.argv[2];
 const apiUrl = process.argv[3] || 'https://worker.avalw.org';
 
-if (!token) {
+if (!token || token === '--help' || token === '-h') {
   console.log('');
-  console.log('  AVALW Search Worker');
-  console.log('  ====================');
+  console.log('  ╔═══════════════════════════════════════════════════════════════════╗');
+  console.log('  ║              AVALW Search Worker v1.1.0                           ║');
+  console.log('  ╚═══════════════════════════════════════════════════════════════════╝');
   console.log('');
   console.log('  Usage: avalw-worker <WORKER_TOKEN> [API_URL]');
   console.log('');
   console.log('  Get your worker token at: https://worker.avalw.org');
   console.log('');
+  console.log('  Tiers (based on Core-Hours):');
+  console.log('  ┌───────────┬─────────────┬──────────────┬─────────────┐');
+  console.log('  │ Tier      │ Requests    │ Core-Hours   │ Min Cores   │');
+  console.log('  ├───────────┼─────────────┼──────────────┼─────────────┤');
+  console.log('  │ Starter   │ 1,000/day   │ 3/day        │ 3 cores     │');
+  console.log('  │ Basic     │ 5,000/day   │ 12/day       │ 4 cores     │');
+  console.log('  │ Pro       │ 20,000/day  │ 36/day       │ 6 cores     │');
+  console.log('  │ Business  │ 50,000/day  │ 72/day       │ 8 cores     │');
+  console.log('  │ Enterprise│ 500,000/day │ 240/day      │ 16 cores    │');
+  console.log('  └───────────┴─────────────┴──────────────┴─────────────┘');
+  console.log('');
+  console.log('  Core-Hours Formula:');
+  console.log('  Cores × (Speed ÷ 3.0 GHz) × Usage% × Hours');
+  console.log('');
   console.log('  Example:');
   console.log('    avalw-worker abc123def456...');
   console.log('');
   process.exit(1);
 }
 
-console.log('');
-console.log('  ╔═══════════════════════════════════════════════╗');
-console.log('  ║         AVALW Search Worker v1.0.0            ║');
-console.log('  ╠═══════════════════════════════════════════════╣');
-console.log('  ║  Free Search API in exchange for compute      ║');
-console.log('  ╚═══════════════════════════════════════════════╝');
-console.log('');
-
 const worker = new AvalwWorker(token, apiUrl);
 
 // Handle graceful shutdown
-process.on('SIGINT', () => {
+process.on('SIGINT', async () => {
   console.log('\n  Shutting down worker...');
-  worker.stop();
+  await worker.stop();
   process.exit(0);
 });
 
-process.on('SIGTERM', () => {
+process.on('SIGTERM', async () => {
   console.log('\n  Shutting down worker...');
-  worker.stop();
+  await worker.stop();
   process.exit(0);
 });
 

package/lib/worker.js

@@ -1,23 +1,99 @@
 /**
- * AVALW Search Worker
+ * AVALW Search Worker v1.1.0
  * Connects to worker.avalw.org and contributes compute power
  * in exchange for free search API access.
+ *
+ * Uses Core-Hours calculation for fair tier distribution.
  */
 
 const https = require('https');
 const http = require('http');
 const os = require('os');
 
+// Tier definitions based on core-hours
+const TIERS = {
+  STARTER:    { name: 'Starter',    coreHours: 3,   requests: 1000,   minCores: 3 },
+  BASIC:      { name: 'Basic',      coreHours: 12,  requests: 5000,   minCores: 4 },
+  PRO:        { name: 'Pro',        coreHours: 36,  requests: 20000,  minCores: 6 },
+  BUSINESS:   { name: 'Business',   coreHours: 72,  requests: 50000,  minCores: 8 },
+  ENTERPRISE: { name: 'Enterprise', coreHours: 240, requests: 500000, minCores: 16 }
+};
+
 class AvalwWorker {
   constructor(token, apiUrl = 'https://worker.avalw.org') {
     this.token = token;
     this.apiUrl = apiUrl;
     this.running = false;
     this.heartbeatInterval = null;
-    this.cpuLimit = 10;  // Default 10%, updated by server
-    this.tier = 'Unknown';
-    this.taskCount = 0;
-    this.lastHeartbeat = null;
+    this.startTime = null;
+    this.coreHoursToday = 0;
+    this.currentTier = null;
+    this.cpuInfo = this.getCpuInfo();
+  }
+
+  /**
+   * Get detailed CPU information
+   */
+  getCpuInfo() {
+    const cpus = os.cpus();
+    const cores = cpus.length;
+    const model = cpus[0]?.model || 'Unknown';
+
+    // Extract speed from CPU model or use reported speed
+    let speedGHz = cpus[0]?.speed ? cpus[0].speed / 1000 : 2.5;
+
+    // Try to parse speed from model string (e.g., "@ 2.90GHz")
+    const speedMatch = model.match(/@\s*([\d.]+)\s*GHz/i);
+    if (speedMatch) {
+      speedGHz = parseFloat(speedMatch[1]);
+    }
+
+    // Speed factor normalized to 3.0 GHz baseline
+    const speedFactor = speedGHz / 3.0;
+
+    return {
+      cores,
+      model,
+      speedGHz,
+      speedFactor: Math.round(speedFactor * 100) / 100,
+      totalMemoryGB: Math.round(os.totalmem() / 1024 / 1024 / 1024 * 10) / 10
+    };
+  }
+
+  /**
+   * Calculate core-hours contribution
+   * @param {number} usagePercent - CPU usage percentage (0-100)
+   * @param {number} hours - Time in hours
+   */
+  calculateCoreHours(usagePercent, hours) {
+    const { cores, speedFactor } = this.cpuInfo;
+    return cores * speedFactor * (usagePercent / 100) * hours;
+  }
+
+  /**
+   * Determine tier based on core-hours and minimum cores
+   */
+  determineTier(coreHours) {
+    const { cores } = this.cpuInfo;
+
+    // Check from highest to lowest tier
+    if (cores >= TIERS.ENTERPRISE.minCores && coreHours >= TIERS.ENTERPRISE.coreHours) {
+      return TIERS.ENTERPRISE;
+    }
+    if (cores >= TIERS.BUSINESS.minCores && coreHours >= TIERS.BUSINESS.coreHours) {
+      return TIERS.BUSINESS;
+    }
+    if (cores >= TIERS.PRO.minCores && coreHours >= TIERS.PRO.coreHours) {
+      return TIERS.PRO;
+    }
+    if (cores >= TIERS.BASIC.minCores && coreHours >= TIERS.BASIC.coreHours) {
+      return TIERS.BASIC;
+    }
+    if (cores >= TIERS.STARTER.minCores && coreHours >= TIERS.STARTER.coreHours) {
+      return TIERS.STARTER;
+    }
+
+    return null; // Not enough cores or core-hours
   }
 
   /**
@@ -25,21 +101,51 @@ class AvalwWorker {
    */
   async start() {
     this.running = true;
-    console.log(`  API URL: ${this.apiUrl}`);
-    console.log(`  Token:   ${this.token.substring(0, 12)}...`);
+    this.startTime = Date.now();
+
+    // Print banner
+    console.log('');
+    console.log('  ╔═══════════════════════════════════════════════════════════════════╗');
+    console.log('  ║              AVALW Search Worker v1.1.0                           ║');
+    console.log('  ╠═══════════════════════════════════════════════════════════════════╣');
+    console.log('  ║  Free Search API in exchange for compute                          ║');
+    console.log('  ╚═══════════════════════════════════════════════════════════════════╝');
+    console.log('');
+
+    // Print system info
+    console.log('  System Info:');
+    console.log(`  ├─ CPU: ${this.cpuInfo.model}`);
+    console.log(`  ├─ Cores: ${this.cpuInfo.cores}`);
+    console.log(`  ├─ Speed: ${this.cpuInfo.speedGHz} GHz (factor: ${this.cpuInfo.speedFactor}x)`);
+    console.log(`  └─ Memory: ${this.cpuInfo.totalMemoryGB} GB`);
+    console.log('');
+
+    // Check minimum cores requirement
+    if (this.cpuInfo.cores < TIERS.STARTER.minCores) {
+      console.log(`  ⚠ WARNING: Your system has ${this.cpuInfo.cores} cores.`);
+      console.log(`  ⚠ Minimum ${TIERS.STARTER.minCores} cores required for Starter tier.`);
+      console.log(`  ⚠ Worker will run but you won't qualify for any tier.`);
+      console.log('');
+    }
+
+    // Print worker status
+    console.log('  Worker Status:');
+    console.log(`  ├─ Token: ${this.token.substring(0, 12)}...`);
+    console.log(`  ├─ API URL: ${this.apiUrl}`);
+    console.log(`  └─ Target Usage: 50%`);
     console.log('');
 
     // Initial heartbeat
     await this.sendHeartbeat();
 
-    // Start heartbeat loop
+    // Start heartbeat loop (every 30 seconds)
     this.heartbeatInterval = setInterval(() => {
       if (this.running) {
         this.sendHeartbeat();
       }
-    }, 30000);  // Every 30 seconds
+    }, 30000);
 
-    console.log('  Worker started. Press Ctrl+C to stop.');
+    console.log('  Press Ctrl+C to stop.');
     console.log('');
   }
 
@@ -59,29 +165,59 @@ class AvalwWorker {
       await this.apiRequest('/api/worker/offline', 'POST', {
         worker_token: this.token
       });
-      console.log('  Worker marked offline.');
+      console.log('');
+      console.log('  Worker stopped and marked offline.');
     } catch (error) {
       // Ignore errors during shutdown
     }
   }
 
   /**
-   * Send heartbeat to server
+   * Send heartbeat to server with core-hours data
    */
   async sendHeartbeat() {
     try {
+      // Calculate hours online since start
+      const hoursOnline = (Date.now() - this.startTime) / 1000 / 60 / 60;
+
+      // Estimate core-hours (assuming 50% usage for now)
+      // In a real implementation, you'd measure actual CPU usage
+      const estimatedUsage = 50;
+      const sessionCoreHours = this.calculateCoreHours(estimatedUsage, hoursOnline);
+
       const response = await this.apiRequest('/api/worker/heartbeat', 'POST', {
         worker_token: this.token,
-        system_info: this.getSystemInfo()
+        system_info: {
+          platform: os.platform(),
+          arch: os.arch(),
+          cores: this.cpuInfo.cores,
+          cpu_model: this.cpuInfo.model,
+          cpu_speed_ghz: this.cpuInfo.speedGHz,
+          speed_factor: this.cpuInfo.speedFactor,
+          total_memory_gb: this.cpuInfo.totalMemoryGB,
+          free_memory_gb: Math.round(os.freemem() / 1024 / 1024 / 1024 * 10) / 10,
+          uptime: os.uptime(),
+          worker_uptime_hours: Math.round(hoursOnline * 100) / 100,
+          session_core_hours: Math.round(sessionCoreHours * 100) / 100,
+          estimated_usage_percent: estimatedUsage
+        }
       });
 
       if (response.success) {
-        this.cpuLimit = response.cpu_limit || this.cpuLimit;
-        this.tier = response.tier || this.tier;
-        this.lastHeartbeat = new Date();
+        this.coreHoursToday = response.core_hours_today || sessionCoreHours;
+        this.currentTier = response.tier || this.determineTier(this.coreHoursToday);
 
-        const time = this.lastHeartbeat.toLocaleTimeString();
-        console.log(`  [${time}] Heartbeat OK | Tier: ${this.tier} | CPU Limit: ${this.cpuLimit}%`);
+        const time = new Date().toLocaleTimeString();
+        const tierName = this.currentTier?.name || 'None';
+        const tierRequests = this.currentTier?.requests?.toLocaleString() || '0';
+        const nextTier = this.getNextTier();
+
+        console.log(`  [${time}] ✓ Heartbeat OK`);
+        console.log(`  ├─ Core-Hours Today: ${this.coreHoursToday.toFixed(1)}${nextTier ? ` / ${nextTier.coreHours} needed for ${nextTier.name}` : ''}`);
+        console.log(`  ├─ Current Tier: ${tierName} (${tierRequests} req/day)`);
+        console.log(`  ├─ Usage Today: ${(response.usage_today || 0).toLocaleString()} / ${tierRequests}`);
+        console.log(`  └─ Online: ${this.formatUptime(hoursOnline)}`);
+        console.log('');
       } else {
         console.error(`  [ERROR] Heartbeat failed: ${response.error}`);
       }
@@ -91,20 +227,45 @@ class AvalwWorker {
   }
 
   /**
-   * Get system information
+   * Get the next tier to aim for
    */
-  getSystemInfo() {
-    const cpus = os.cpus();
-    const totalMem = os.totalmem();
-    const freeMem = os.freemem();
+  getNextTier() {
+    const tierOrder = [TIERS.STARTER, TIERS.BASIC, TIERS.PRO, TIERS.BUSINESS, TIERS.ENTERPRISE];
 
+    for (const tier of tierOrder) {
+      if (this.cpuInfo.cores >= tier.minCores && this.coreHoursToday < tier.coreHours) {
+        return tier;
+      }
+    }
+
+    return null; // Already at max tier or can't qualify
+  }
+
+  /**
+   * Format uptime as human readable
+   */
+  formatUptime(hours) {
+    if (hours < 1) {
+      return `${Math.round(hours * 60)}m`;
+    }
+    const h = Math.floor(hours);
+    const m = Math.round((hours - h) * 60);
+    return `${h}h ${m}m`;
+  }
+
+  /**
+   * Get system information (legacy method for compatibility)
+   */
+  getSystemInfo() {
     return {
       platform: os.platform(),
       arch: os.arch(),
-      cpus: cpus.length,
-      cpu_model: cpus[0]?.model || 'Unknown',
-      total_memory: Math.round(totalMem / 1024 / 1024 / 1024 * 10) / 10,  // GB
-      free_memory: Math.round(freeMem / 1024 / 1024 / 1024 * 10) / 10,   // GB
+      cpus: this.cpuInfo.cores,
+      cpu_model: this.cpuInfo.model,
+      cpu_speed_ghz: this.cpuInfo.speedGHz,
+      speed_factor: this.cpuInfo.speedFactor,
+      total_memory: this.cpuInfo.totalMemoryGB,
+      free_memory: Math.round(os.freemem() / 1024 / 1024 / 1024 * 10) / 10,
       uptime: os.uptime()
     };
   }
@@ -125,7 +286,7 @@ class AvalwWorker {
         method: method,
         headers: {
           'Content-Type': 'application/json',
-          'User-Agent': 'AvalwWorker/1.0.0'
+          'User-Agent': 'AvalwWorker/1.1.0'
         }
       };
 
@@ -155,4 +316,4 @@ class AvalwWorker {
   }
 }
 
-module.exports = { AvalwWorker };
+module.exports = { AvalwWorker, TIERS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avalw/search-worker",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "AVALW Search Worker - Contribute compute power, get free privacy-focused search API access",
   "main": "lib/worker.js",
   "bin": {