@avalw/search-worker 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AVALW
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,259 @@
+# @avalw/search-worker
+
+Free privacy-focused search API in exchange for compute power.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://nodejs.org)
+
+## 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.
+
+**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  │  │
+│  └───────────┘  │      │                 │      │  └───────────┘  │
+└─────────────────┘      └─────────────────┘      └─────────────────┘
+```
+
+## Tiers
+
+Choose the tier that fits your needs:
+
+| 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%              |
+
+## Quick Start
+
+### 1. Get Your Token
+
+Visit [worker.avalw.org](https://worker.avalw.org) and create a free account. You'll receive:
+- **Account Hash** - Your unique identifier (save this!)
+- **Worker Token** - Used to run the worker
+
+### 2. Install the Worker
+
+```bash
+# Install globally via npm
+npm install -g @avalw/search-worker
+
+# Or install from GitHub
+npm install -g github:avalw/search-worker
+```
+
+### 3. Run the Worker
+
+```bash
+avalw-worker YOUR_WORKER_TOKEN
+```
+
+You should see:
+```
+  ╔═══════════════════════════════════════════════╗
+  ║         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.
+```
+
+### 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
+
+### Using PM2 (Recommended)
+
+```bash
+# Install PM2
+npm install -g pm2
+
+# Start worker
+pm2 start avalw-worker -- YOUR_WORKER_TOKEN
+
+# Save for auto-restart
+pm2 save
+pm2 startup
+```
+
+### Using systemd (Linux)
+
+Create `/etc/systemd/system/avalw-worker.service`:
+
+```ini
+[Unit]
+Description=AVALW Search Worker
+After=network.target
+
+[Service]
+Type=simple
+User=your-user
+ExecStart=/usr/bin/avalw-worker YOUR_WORKER_TOKEN
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Then:
+```bash
+sudo systemctl enable avalw-worker
+sudo systemctl start avalw-worker
+```
+
+### Using Docker
+
+```dockerfile
+FROM node:20-alpine
+RUN npm install -g @avalw/search-worker
+CMD ["avalw-worker", "YOUR_WORKER_TOKEN"]
+```
+
+```bash
+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
+
+```
+GET https://worker.avalw.org/api/search
+```
+
+**Parameters:**
+| Parameter | Type   | Required | Description                    |
+|-----------|--------|----------|--------------------------------|
+| q         | string | Yes      | Search query                   |
+| token     | string | Yes      | Your worker token              |
+| page      | number | No       | Page number (default: 1)       |
+| limit     | number | No       | Results per page (default: 10) |
+
+**Response:**
+```json
+{
+  "success": true,
+  "results": [
+    {
+      "title": "Example Result",
+      "url": "https://example.com",
+      "snippet": "This is a snippet..."
+    }
+  ],
+  "total": 100,
+  "page": 1
+}
+```
+
+## Domain Whitelisting
+
+For security, API requests only work from whitelisted domains. Manage your domains at [worker.avalw.org](https://worker.avalw.org) dashboard.
+
+## Troubleshooting
+
+### Worker won't connect
+- Check your internet connection
+- Verify your token is correct
+- Ensure port 443 (HTTPS) is not blocked
+
+### API returns "Worker offline"
+- Make sure your worker is running
+- Check the worker console for errors
+- Worker must send heartbeat every 30 seconds
+
+### Rate limit exceeded
+- Upgrade to a higher tier for more requests
+- Wait until the daily limit resets (midnight UTC)
+
+## Security
+
+- **No data collection**: We don't log search queries
+- **No tracking**: No cookies, no fingerprinting
+- **Open protocol**: Transparent heartbeat mechanism
+- **Your server, your control**: Worker runs on your infrastructure
+
+## Support
+
+- Website: [worker.avalw.org](https://worker.avalw.org)
+- Issues: [GitHub Issues](https://github.com/avalw/search-worker/issues)
+- Email: contact@avalw.com
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+Made with privacy in mind by [AVALW](https://avalw.org)

package/bin/cli.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+const { AvalwWorker } = require('../lib/worker');
+
+const token = process.argv[2];
+const apiUrl = process.argv[3] || 'https://worker.avalw.org';
+
+if (!token) {
+  console.log('');
+  console.log('  AVALW Search Worker');
+  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('  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', () => {
+  console.log('\n  Shutting down worker...');
+  worker.stop();
+  process.exit(0);
+});
+
+process.on('SIGTERM', () => {
+  console.log('\n  Shutting down worker...');
+  worker.stop();
+  process.exit(0);
+});
+
+// Start worker
+worker.start();

package/examples/basic-usage.js

@@ -0,0 +1,32 @@
+/**
+ * Basic Usage Example
+ *
+ * This example shows how to use the AVALW Worker programmatically
+ * in your Node.js application.
+ */
+
+const { AvalwWorker } = require('@avalw/search-worker');
+
+// Replace with your actual token from worker.avalw.org
+const WORKER_TOKEN = 'YOUR_WORKER_TOKEN_HERE';
+
+async function main() {
+  // Create worker instance
+  const worker = new AvalwWorker(WORKER_TOKEN);
+
+  // Handle shutdown gracefully
+  process.on('SIGINT', async () => {
+    console.log('\nStopping worker...');
+    await worker.stop();
+    process.exit(0);
+  });
+
+  // Start the worker
+  console.log('Starting AVALW Worker...');
+  await worker.start();
+
+  // Worker is now running and contributing compute power
+  // Your search API is now active!
+}
+
+main().catch(console.error);

package/examples/express-integration.js

@@ -0,0 +1,73 @@
+/**
+ * Express.js Integration Example
+ *
+ * This example shows how to integrate AVALW Search
+ * into an Express.js application.
+ */
+
+const express = require('express');
+const { AvalwWorker } = require('@avalw/search-worker');
+
+// Replace with your actual token
+const WORKER_TOKEN = 'YOUR_WORKER_TOKEN_HERE';
+const API_URL = 'https://worker.avalw.org';
+
+const app = express();
+const PORT = 3000;
+
+// Start the worker when the server starts
+const worker = new AvalwWorker(WORKER_TOKEN);
+
+// Search endpoint for your users
+app.get('/search', async (req, res) => {
+  const { q, page = 1 } = req.query;
+
+  if (!q) {
+    return res.status(400).json({ error: 'Query parameter "q" is required' });
+  }
+
+  try {
+    const params = new URLSearchParams({
+      q,
+      token: WORKER_TOKEN,
+      page: page.toString()
+    });
+
+    const response = await fetch(`${API_URL}/api/search?${params}`);
+    const results = await response.json();
+
+    res.json(results);
+  } catch (error) {
+    res.status(500).json({ error: 'Search failed', message: error.message });
+  }
+});
+
+// Health check
+app.get('/health', (req, res) => {
+  res.json({
+    status: 'ok',
+    worker: worker.running ? 'running' : 'stopped'
+  });
+});
+
+// Start server and worker
+async function start() {
+  // Start the AVALW worker
+  await worker.start();
+  console.log('AVALW Worker started');
+
+  // Start Express server
+  app.listen(PORT, () => {
+    console.log(`Server running on http://localhost:${PORT}`);
+    console.log(`Try: http://localhost:${PORT}/search?q=test`);
+  });
+}
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  console.log('\nShutting down...');
+  await worker.stop();
+  process.exit(0);
+});
+
+start().catch(console.error);

package/examples/search-api.js

@@ -0,0 +1,58 @@
+/**
+ * Search API Example
+ *
+ * This example shows how to use the AVALW Search API
+ * once your worker is running.
+ */
+
+// Replace with your actual token
+const WORKER_TOKEN = 'YOUR_WORKER_TOKEN_HERE';
+const API_URL = 'https://worker.avalw.org';
+
+/**
+ * Search using the AVALW API
+ * @param {string} query - Search query
+ * @param {number} page - Page number (optional)
+ * @returns {Promise<object>} Search results
+ */
+async function search(query, page = 1) {
+  const params = new URLSearchParams({
+    q: query,
+    token: WORKER_TOKEN,
+    page: page.toString()
+  });
+
+  const response = await fetch(`${API_URL}/api/search?${params}`);
+
+  if (!response.ok) {
+    throw new Error(`Search failed: ${response.statusText}`);
+  }
+
+  return response.json();
+}
+
+// Example usage
+async function main() {
+  try {
+    console.log('Searching for "privacy search engine"...\n');
+
+    const results = await search('privacy search engine');
+
+    if (results.success) {
+      console.log(`Found ${results.total || results.results?.length || 0} results:\n`);
+
+      results.results?.forEach((result, index) => {
+        console.log(`${index + 1}. ${result.title}`);
+        console.log(`   ${result.url}`);
+        console.log(`   ${result.snippet?.substring(0, 100)}...`);
+        console.log('');
+      });
+    } else {
+      console.log('Search error:', results.error);
+    }
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+main();

package/lib/worker.js

@@ -0,0 +1,158 @@
+/**
+ * AVALW Search Worker
+ * Connects to worker.avalw.org and contributes compute power
+ * in exchange for free search API access.
+ */
+
+const https = require('https');
+const http = require('http');
+const os = require('os');
+
+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;
+  }
+
+  /**
+   * Start the worker
+   */
+  async start() {
+    this.running = true;
+    console.log(`  API URL: ${this.apiUrl}`);
+    console.log(`  Token:   ${this.token.substring(0, 12)}...`);
+    console.log('');
+
+    // Initial heartbeat
+    await this.sendHeartbeat();
+
+    // Start heartbeat loop
+    this.heartbeatInterval = setInterval(() => {
+      if (this.running) {
+        this.sendHeartbeat();
+      }
+    }, 30000);  // Every 30 seconds
+
+    console.log('  Worker started. Press Ctrl+C to stop.');
+    console.log('');
+  }
+
+  /**
+   * Stop the worker
+   */
+  async stop() {
+    this.running = false;
+
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = null;
+    }
+
+    // Notify server we're going offline
+    try {
+      await this.apiRequest('/api/worker/offline', 'POST', {
+        worker_token: this.token
+      });
+      console.log('  Worker marked offline.');
+    } catch (error) {
+      // Ignore errors during shutdown
+    }
+  }
+
+  /**
+   * Send heartbeat to server
+   */
+  async sendHeartbeat() {
+    try {
+      const response = await this.apiRequest('/api/worker/heartbeat', 'POST', {
+        worker_token: this.token,
+        system_info: this.getSystemInfo()
+      });
+
+      if (response.success) {
+        this.cpuLimit = response.cpu_limit || this.cpuLimit;
+        this.tier = response.tier || this.tier;
+        this.lastHeartbeat = new Date();
+
+        const time = this.lastHeartbeat.toLocaleTimeString();
+        console.log(`  [${time}] Heartbeat OK | Tier: ${this.tier} | CPU Limit: ${this.cpuLimit}%`);
+      } else {
+        console.error(`  [ERROR] Heartbeat failed: ${response.error}`);
+      }
+    } catch (error) {
+      console.error(`  [ERROR] Heartbeat error: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get system information
+   */
+  getSystemInfo() {
+    const cpus = os.cpus();
+    const totalMem = os.totalmem();
+    const freeMem = os.freemem();
+
+    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
+      uptime: os.uptime()
+    };
+  }
+
+  /**
+   * Make API request
+   */
+  apiRequest(endpoint, method = 'GET', body = null) {
+    return new Promise((resolve, reject) => {
+      const url = new URL(`${this.apiUrl}${endpoint}`);
+      const isHttps = url.protocol === 'https:';
+      const lib = isHttps ? https : http;
+
+      const options = {
+        hostname: url.hostname,
+        port: url.port || (isHttps ? 443 : 80),
+        path: url.pathname,
+        method: method,
+        headers: {
+          'Content-Type': 'application/json',
+          'User-Agent': 'AvalwWorker/1.0.0'
+        }
+      };
+
+      const req = lib.request(options, (res) => {
+        let data = '';
+        res.on('data', chunk => data += chunk);
+        res.on('end', () => {
+          try {
+            resolve(JSON.parse(data));
+          } catch (e) {
+            resolve({ raw: data });
+          }
+        });
+      });
+
+      req.on('error', reject);
+      req.setTimeout(15000, () => {
+        req.destroy();
+        reject(new Error('Request timeout'));
+      });
+
+      if (body) {
+        req.write(JSON.stringify(body));
+      }
+      req.end();
+    });
+  }
+}
+
+module.exports = { AvalwWorker };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@avalw/search-worker",
+  "version": "1.0.0",
+  "description": "AVALW Search Worker - Contribute compute power, get free privacy-focused search API access",
+  "main": "lib/worker.js",
+  "bin": {
+    "avalw-worker": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js",
+    "test": "node test/test.js"
+  },
+  "keywords": [
+    "avalw",
+    "search",
+    "worker",
+    "distributed",
+    "api",
+    "privacy",
+    "search-engine",
+    "decentralized"
+  ],
+  "author": "AVALW <contact@avalw.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/avalw/search-worker.git"
+  },
+  "bugs": {
+    "url": "https://github.com/avalw/search-worker/issues"
+  },
+  "homepage": "https://worker.avalw.org",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "files": [
+    "bin/",
+    "lib/",
+    "examples/",
+    "README.md",
+    "LICENSE"
+  ]
+}