@nordsym/apiclaw 1.5.8 → 1.5.10

package/HIVR-WHITELIST-STATUS.md

@@ -0,0 +1,205 @@
+# Hivr Whitelist - Status & Verification
+
+**Date:** 2026-03-19
+**Issue:** Whitelist checking wrong field, no account attribution
+
+---
+
+## ✅ What I Fixed
+
+### 1. Hivr Whitelist — Field Name Mismatch
+
+**Problem:** Both whitelist files were looking for `agentId` field, but Hivr agents have `handle`
+
+**Files Fixed:**
+- `src/hivr-whitelist.ts` — Line 60: `a.agentId` → `a.handle`
+- `src/product-whitelist.ts` — Line 15: `agentIdField: 'agentId'` → `agentIdField: 'handle'`
+
+**Result:** Whitelist will now correctly extract bee handles from Hivr Convex
+
+---
+
+## ⚠️ What's Missing: Account Attribution
+
+**Your expectation:** All Hivr bee requests counted under `gustav@nordsym.com`
+
+**Current reality:** Requests logged only by bee handle (`bytebee`, `elderbee`, etc.)
+
+**Where tracking happens:**
+```typescript
+// src/http-api.ts line ~94
+logAPICall({
+  userId: agentId || 'unknown',  // Just the bee handle, no account email
+  // ...
+});
+```
+
+**No account/email field exists in the current system.**
+
+---
+
+## 🔍 Verification Steps
+
+### 1. Check Whitelist Works
+
+**Start APIClaw HTTP server:**
+```bash
+cd ~/Projects/apiclaw
+npm run start:http
+```
+
+**Expected log:**
+```
+[Hivr Whitelist] Fetched 12 agents from Hivr
+```
+
+**Test authorization:**
+```bash
+# Should return 200 (authorized)
+curl "http://localhost:3000/api/discover?query=web&agentId=elderbee"
+
+# Should return 403 (unauthorized)
+curl "http://localhost:3000/api/discover?query=web&agentId=fakeagent"
+```
+
+### 2. Check Which Bees Are Whitelisted
+
+**In APIClaw console (when server running):**
+```typescript
+import { getWhitelist } from './hivr-whitelist.js';
+const bees = await getWhitelist();
+console.log(bees); // Should list all Hivr bee handles
+```
+
+---
+
+## 📊 Account Attribution (NOT Implemented)
+
+**If you want gustav@nordsym.com attribution:**
+
+### Option A: Product Namespace (Already in place)
+
+Current system namespaces as `hivr:bytebee`, `hivr:elderbee`
+
+You can group by product:
+```typescript
+// In analytics
+const hivrRequests = logs.filter(log => log.userId.startsWith('hivr:'));
+const nordsymRequests = logs.filter(log => log.userId.startsWith('nordsym:'));
+```
+
+**Pros:** Works now with the fix
+**Cons:** Still no email/account tracking
+
+### Option B: Add Account Field (Requires Implementation)
+
+**Change needed:**
+```typescript
+// src/http-api.ts
+logAPICall({
+  userId: agentId,
+  accountEmail: 'gustav@nordsym.com',  // ← Add this
+  product: getProduct(agentId),        // Already exists
+  // ...
+});
+```
+
+**Pros:** Clear separation NordSym vs Hivr
+**Cons:** Requires code changes + analytics schema update
+
+### Option C: Convex Metadata (Clean Approach)
+
+**Store account mapping in Convex:**
+```typescript
+// apiclawProviders table (already exists!)
+{
+  agentId: "elderbee",
+  slug: "hivr-elderbee",
+  accountEmail: "gustav@nordsym.com",  // ← Add this field
+}
+```
+
+**Then in APIClaw:**
+```typescript
+const provider = await getProviderByAgent(agentId);
+logAPICall({
+  userId: agentId,
+  accountEmail: provider?.accountEmail,
+  // ...
+});
+```
+
+**Pros:** Clean, uses existing infrastructure
+**Cons:** Requires schema update + backfill
+
+---
+
+## 🎯 Recommendation
+
+**Immediate (today):**
+1. ✅ Field fix deployed (handle instead of agentId)
+2. Restart APIClaw HTTP server to apply
+3. Verify whitelist works (see steps above)
+
+**Short-term (if account attribution needed):**
+- Option C (Convex metadata) is cleanest
+- Add `accountEmail` to `apiclawProviders` table
+- Update HTTP API to include it in logs
+- **This aligns with the provider registration work already started**
+
+---
+
+## 📝 Current Whitelist Status
+
+**Bees expected to be whitelisted after fix:**
+- hivrqueen
+- elderbee
+- hivemind
+- hivesage_hivr_bot
+- buzzwriter
+- analyzerbee
+- buildbee
+- bytebee
+- reconbee
+- sprintbee
+- quillbee
+- marketmaven
+
+**Total:** 12 bees (all active Hivr agents)
+
+---
+
+**Created:** 2026-03-19 12:20 CET  
+**Updated:** 2026-03-19 12:26 CET  
+**Status:** ✅ VERIFIED WORKING — All Hivr bees whitelisted  
+**Server:** Running on localhost:3001
+
+---
+
+## ✅ Verification Complete (2026-03-19 12:26)
+
+**Issues Fixed:**
+1. Field name: `agentId` → `handle` ✓
+2. Convex HTTP response parsing: Access `.value` field ✓
+
+**Whitelist Status:** 14 Hivr bees successfully fetched and authorized
+
+**Tested Bees (all authorized ✓):**
+- bytebee
+- elderbee  
+- hivrqueen
+- symbot
+- marketmaven
+- reconbee
+- HiveMind_Hivr_bot
+- AnalyzerBee_Hivr_bot
+- Buzzwriter_Hivr_bot
+- BuildBee_Hivr_bot
+- HiveSage_Hivr_bot
+- OutreachBee_Hivr_bot
+- quillbee
+- sprintbee
+
+**Authorization Test:** Fake agents correctly blocked ✓
+
+**Next:** Account attribution (gustav@nordsym.com) — see Option C above

package/HIVR-WHITELIST.md

@@ -0,0 +1,148 @@
+# Hivr Auto-Whitelist System
+
+**Problem:** Manually updating hardcoded whitelist every time new bee is added = fragile + easy to forget.
+
+**Solution:** APIClaw dynamically fetches active agents from Hivr's Convex deployment.
+
+---
+
+## How It Works
+
+1. **Hivr Convex Deployment:** `sensible-quail-275` (PROD)
+2. **APIClaw queries:** `agents:list` from Hivr
+3. **Cache:** 5 minutes (performance)
+4. **Fallback:** Static whitelist if Convex unreachable
+
+---
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `src/hivr-whitelist.ts` | Dynamic whitelist module |
+| `src/http-api.ts` | Uses `isAuthorized()` from hivr-whitelist |
+
+---
+
+## Usage
+
+### In Code
+```typescript
+import { isAuthorized, invalidateCache } from './hivr-whitelist.js';
+
+// Check if agent is whitelisted
+const authorized = await isAuthorized('bytebee'); // true
+
+// Force refresh (after adding new bee)
+invalidateCache();
+```
+
+### Adding New Bee (Automatic!)
+1. Add agent in Hivr (hivr.online admin)
+2. APIClaw will auto-discover within 5 minutes
+3. **No code changes needed!**
+
+---
+
+## Manual Override (Emergency)
+
+If Hivr Convex is down, edit static fallback:
+
+**File:** `src/hivr-whitelist.ts`  
+**Line:** 10-23
+
+```typescript
+const STATIC_WHITELIST = [
+  'bytebee',
+  'symbot',
+  // Add emergency agents here
+];
+```
+
+Then rebuild:
+```bash
+npm run build
+```
+
+---
+
+## Testing
+
+### Local Test
+```bash
+# Start APIClaw HTTP API
+npm run start:http
+
+# Test authorization
+curl "http://localhost:3000/api/discover?query=web&agentId=bytebee"
+# Should return 200 (authorized)
+
+curl "http://localhost:3000/api/discover?query=web&agentId=unauthorized"
+# Should return 403 (unauthorized)
+```
+
+### Check Whitelist Cache
+APIClaw logs when fetching whitelist:
+```
+[Hivr Whitelist] Fetched 12 agents from Hivr
+```
+
+---
+
+## Troubleshooting
+
+**Problem:** New bee not authorized immediately  
+**Solution:** Wait 5 minutes (cache) or restart APIClaw server
+
+**Problem:** "Failed to fetch from Hivr Convex"  
+**Solution:** Check Hivr Convex URL in `hivr-whitelist.ts`, fallback to static
+
+**Problem:** All bees unauthorized  
+**Solution:** Check Hivr agents table has `agentId` field
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│  Hivr.online (sensible-quail-275)           │
+│  ┌───────────────────────────────────────┐  │
+│  │  agents table                         │  │
+│  │  { agentId: "bytebee", ... }          │  │
+│  └───────────────────────────────────────┘  │
+└─────────────────────────────────────────────┘
+                    ▲
+                    │ Query agents:list
+                    │ (every 5 min)
+                    │
+┌─────────────────────────────────────────────┐
+│  APIClaw HTTP API                           │
+│  ┌───────────────────────────────────────┐  │
+│  │  hivr-whitelist.ts                    │  │
+│  │  - Cached whitelist                   │  │
+│  │  - Auto-refresh every 5 min           │  │
+│  │  - Fallback to static list            │  │
+│  └───────────────────────────────────────┘  │
+│                    │                         │
+│  ┌───────────────────────────────────────┐  │
+│  │  http-api.ts                          │  │
+│  │  - /api/discover                      │  │
+│  │  - /api/call_api                      │  │
+│  │  - Calls isAuthorized(agentId)        │  │
+│  └───────────────────────────────────────┘  │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## Future Improvements
+
+- [ ] Webhook from Hivr when new agent added (instant refresh)
+- [ ] Admin endpoint to manually refresh: `GET /api/admin/refresh-whitelist`
+- [ ] Whitelist per-API (some bees only get certain providers)
+- [ ] Usage quotas per bee (track in Convex)
+
+---
+
+**TL;DR:** Add agent in Hivr → APIClaw auto-whitelists within 5 min. Zero manual code changes.

package/HTTP-API.md

@@ -0,0 +1,306 @@
+# APIClaw HTTP API
+
+REST endpoints for headless agents (Hivr bees, webhooks, serverless functions).
+
+## 🚀 Quick Start
+
+**Start server:**
+```bash
+npx apiclaw-http --port 3000
+```
+
+**Or via npm:**
+```bash
+npm i -g @nordsym/apiclaw
+apiclaw-http
+```
+
+Server runs on `http://localhost:3000` by default.
+
+---
+
+## 📡 Endpoints
+
+### 1. Discover APIs
+
+Search for APIs by capability.
+
+**Request:**
+```http
+GET /api/discover?query=web+search&agentId=bytebee&category=Search&maxResults=5
+```
+
+**Parameters:**
+| Param | Required | Description |
+|-------|----------|-------------|
+| `query` | Yes | Search query (e.g., "web search", "send SMS") |
+| `agentId` | Yes | Your agent ID (must be whitelisted) |
+| `category` | No | Filter by category |
+| `maxResults` | No | Max results to return (default: 5) |
+
+**Response:**
+```json
+{
+  "success": true,
+  "query": "web search",
+  "results": [
+    {
+      "provider": {
+        "id": "brave_search",
+        "name": "Brave Search",
+        "category": "Search"
+      },
+      "score": 95,
+      "reasons": ["keyword: search", "capability: web search"]
+    }
+  ],
+  "count": 1,
+  "responseTimeMs": 12
+}
+```
+
+---
+
+### 2. Call API
+
+Execute an API call.
+
+**Request:**
+```http
+POST /api/call_api
+Content-Type: application/json
+
+{
+  "provider": "brave_search",
+  "action": "search",
+  "params": {
+    "query": "AI news",
+    "count": 5
+  },
+  "agentId": "bytebee"
+}
+```
+
+**Parameters:**
+| Field | Required | Description |
+|-------|----------|-------------|
+| `provider` | Yes | Provider ID (from discover results) |
+| `action` | Yes | Action to perform (e.g., "search", "send_sms") |
+| `params` | Yes | Action parameters (varies by provider) |
+| `agentId` | Yes | Your agent ID (must be whitelisted) |
+
+**Response (success):**
+```json
+{
+  "success": true,
+  "provider": "brave_search",
+  "action": "search",
+  "agentId": "bytebee",
+  "data": {
+    "results": [
+      {
+        "title": "Latest AI News",
+        "url": "https://example.com/ai-news",
+        "snippet": "..."
+      }
+    ]
+  },
+  "latencyMs": 234
+}
+```
+
+**Response (error):**
+```json
+{
+  "success": false,
+  "provider": "brave_search",
+  "action": "search",
+  "agentId": "bytebee",
+  "error": "Rate limit exceeded",
+  "latencyMs": 12
+}
+```
+
+---
+
+### 3. Health Check
+
+Check if server is running.
+
+**Request:**
+```http
+GET /health
+```
+
+**Response:**
+```json
+{
+  "status": "ok",
+  "service": "apiclaw-http-api"
+}
+```
+
+---
+
+## 🔐 Authentication
+
+**Hivr Bees Whitelist:**
+
+Access is restricted to whitelisted Hivr bees. The `agentId` parameter must match one of these:
+
+```
+bytebee, analyzerbee, buildbee, buzzwriter, hivemind, 
+hivesage, symbot, hivrqueen, marketmaven, reconbee, 
+sprintbee, quillbee
+```
+
+**Unauthorized response:**
+```json
+{
+  "error": "Unauthorized",
+  "message": "This endpoint is restricted to Hivr bees. Contact admin@nordsym.com for access."
+}
+```
+
+---
+
+## 📊 Usage Logging
+
+All API calls are logged to APIClaw analytics with:
+- Provider + action
+- Agent ID (e.g., `hivr:bytebee`)
+- Success/failure
+- Latency
+
+This enables usage tracking per Hivr bee.
+
+---
+
+## 🎯 Example: Web Search
+
+**1. Discover search APIs:**
+```bash
+curl "http://localhost:3000/api/discover?query=web+search&agentId=bytebee"
+```
+
+**2. Call Brave Search:**
+```bash
+curl -X POST http://localhost:3000/api/call_api \
+  -H "Content-Type: application/json" \
+  -d '{
+    "provider": "brave_search",
+    "action": "search",
+    "params": {
+      "query": "latest AI developments",
+      "count": 5
+    },
+    "agentId": "bytebee"
+  }'
+```
+
+---
+
+## 🌐 CORS
+
+CORS headers are set to allow cross-origin requests from anywhere:
+- `Access-Control-Allow-Origin: *`
+- `Access-Control-Allow-Methods: GET, POST, OPTIONS`
+- `Access-Control-Allow-Headers: Content-Type, X-Agent-Id`
+
+Safe for browser-based agents.
+
+---
+
+## 🚀 Deployment
+
+### Local Development
+```bash
+apiclaw-http --port 3000
+```
+
+### Production (systemd)
+```ini
+[Unit]
+Description=APIClaw HTTP API
+After=network.target
+
+[Service]
+Type=simple
+User=apiclaw
+WorkingDirectory=/opt/apiclaw
+ExecStart=/usr/bin/apiclaw-http --port 3000
+Restart=always
+Environment="PORT=3000"
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### Docker
+```dockerfile
+FROM node:20
+RUN npm i -g @nordsym/apiclaw
+CMD ["apiclaw-http", "--port", "3000"]
+EXPOSE 3000
+```
+
+### Vercel (Serverless)
+See `landing/` directory for Next.js API routes wrapper.
+
+---
+
+## 🐝 Hivr Integration
+
+**In your Hivr bee instructions:**
+```markdown
+## APIClaw Access 🦞
+
+You have access to APIClaw via HTTP API.
+
+**Discover APIs:**
+GET https://apiclaw.nordsym.com/api/discover?query=web+search&agentId=YOUR_HANDLE
+
+**Call APIs:**
+POST https://apiclaw.nordsym.com/api/call_api
+Body: { provider: "brave_search", action: "search", params: {...}, agentId: "YOUR_HANDLE" }
+
+**Your agent ID:** Replace `YOUR_HANDLE` with your actual handle (e.g., "bytebee").
+```
+
+---
+
+## 📚 API Provider Reference
+
+See [apiclaw.nordsym.com/docs](https://apiclaw.nordsym.com/docs) for:
+- List of all 18 Direct Call providers
+- Available actions per provider
+- Parameter schemas
+- Rate limits & pricing
+
+---
+
+## 🔧 Development
+
+**Run from source:**
+```bash
+cd apiclaw
+npm run build
+node dist/bin-http.js --port 3000
+```
+
+**Watch mode:**
+```bash
+tsx watch src/bin-http.ts
+```
+
+---
+
+## ❓ Support
+
+- **Docs:** [apiclaw.nordsym.com/docs](https://apiclaw.nordsym.com/docs)
+- **Issues:** [github.com/nordsym/apiclaw/issues](https://github.com/nordsym/apiclaw/issues)
+- **Email:** admin@nordsym.com
+
+---
+
+MIT © [NordSym](https://nordsym.com)