@nordsym/apiclaw 1.5.9 → 1.5.11

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/TERMINOLOGY-AUDIT.md

@@ -0,0 +1,99 @@
+# 🔍 APIClaw Terminology Audit - "Provider Dashboard" → "Workspace"
+
+**Goal:** Unify all dashboard terminology to "Workspace" regardless of user role.
+
+**Principle:** ONE dashboard for ALL users. Same name: **Workspace**. Different data based on role.
+
+---
+
+## ❌ Current Issues
+
+**Problem:** Multiple terms for the same concept:
+- "Provider Dashboard" (for API providers like APILayer)
+- "Workspace" (for regular users)
+- Routes: `/providers/dashboard` vs `/workspace`
+
+**Confusion:** Users/AI don't know if these are different things or the same.
+
+---
+
+## 📋 Files to Update
+
+### **1. Component Rename**
+
+**File:** `src/components/ProviderDashboard.tsx`
+- Rename to: `Workspace.tsx`
+- Export: `ProviderDashboard` → `Workspace`
+
+### **2. Route Structure**
+
+**Current:** `/providers/dashboard/*`
+**Decision needed:** 
+- Option A: Rename to `/providers/workspace/*` (keeps separation)
+- Option B: Merge into `/workspace` (unified, role-based views)
+
+**Recommendation:** Option B - One workspace, role-based content.
+
+### **3. UI Text Changes (9 files)**
+
+| File | Line | Current | Replace With |
+|------|------|---------|--------------|
+| `src/app/api/auth/magic-link/route.ts` | 54 | "provider dashboard" | "workspace" |
+| `src/app/login/page.tsx` | 202 | "Provider Dashboard" | "Workspace" |
+| `src/app/providers/dashboard/[apiId]/direct-call/page.tsx` | 448 | "provider dashboard" | "workspace" |
+| `src/app/providers/dashboard/login/page.tsx` | 112 | "Provider Dashboard" | "Workspace" |
+| `src/app/providers/dashboard/page.tsx` | 7 | `ProviderDashboardRedirect` | `WorkspaceRedirect` |
+| `src/app/providers/layout.tsx` | 4 | "Provider Dashboard" | "Workspace" |
+| `src/components/ProviderDashboard.tsx` | 79 | "Provider Dashboard" | "Workspace" |
+| `src/lib/mock-data.ts` | 1 | "provider dashboard demo" | "workspace demo" |
+
+---
+
+## ✅ Acceptable "Provider" Usage
+
+**These are OK (not confusing):**
+- "API provider" (describes what someone IS, not a UI element)
+- "Direct Call provider" (describes a service type)
+- Technical variable names like `providerId`, `providerName` (code internals)
+- "Provider" in list contexts ("Browse providers")
+
+**Rule:** "Provider" OK when describing a ROLE or TYPE. NOT OK when naming UI elements.
+
+---
+
+## 🎯 Proposed Changes
+
+### Phase 1: UI Text (Quick Win)
+Replace all "Provider Dashboard" → "Workspace" in user-facing text.
+
+### Phase 2: Component Rename
+`ProviderDashboard.tsx` → `Workspace.tsx`
+
+### Phase 3: Route Consolidation (Optional)
+Merge `/providers/dashboard` into `/workspace` with role-based rendering.
+
+---
+
+## 📝 Implementation Script
+
+```bash
+# Find all instances (for verification)
+cd ~/Projects/apiclaw/landing
+grep -rn "Provider Dashboard" src/ --include="*.tsx" --include="*.ts"
+
+# Replace in files (do manually or scripted)
+# See detailed file list above
+```
+
+---
+
+## 🚀 Next Steps
+
+1. Review this audit
+2. Confirm approach (Phase 1-3 vs all at once)
+3. Execute changes
+4. Test routes still work
+5. Deploy
+
+**Created:** 2026-03-24
+**Status:** Ready for implementation

package/TERMINOLOGY-FIXED.md

@@ -0,0 +1,74 @@
+# ✅ Terminology Fixed - "Provider Dashboard" → "Workspace"
+
+**Completed:** 2026-03-24 16:39
+
+---
+
+## Changes Made
+
+### 1. Component Renamed ✅
+- `src/components/ProviderDashboard.tsx` → `Workspace.tsx`
+- Export function: `ProviderDashboard()` → `Workspace()`
+- Internal h1: "Provider Dashboard" → "Workspace"
+
+### 2. All UI Text Updated ✅
+
+| File | Old | New |
+|------|-----|-----|
+| `src/app/api/auth/magic-link/route.ts` | "provider dashboard" | "workspace" |
+| `src/app/login/page.tsx` | "Provider Dashboard" | "Workspace" |
+| `src/app/providers/dashboard/[apiId]/direct-call/page.tsx` | "provider dashboard" | "workspace" |
+| `src/app/providers/dashboard/login/page.tsx` | "Provider Dashboard" | "Workspace" |
+| `src/app/providers/dashboard/page.tsx` | `ProviderDashboardRedirect` | `WorkspaceRedirect` |
+| `src/app/providers/layout.tsx` | "Provider Dashboard" | "Workspace" |
+| `src/lib/mock-data.ts` | "provider dashboard demo" | "workspace demo" |
+
+### 3. Verification ✅
+```bash
+grep -rn "Provider Dashboard\|ProviderDashboard" src/
+# Result: No matches found ✓
+```
+
+---
+
+## Result
+
+**Before:**
+- "Provider Dashboard" for API providers
+- "Workspace" for regular users
+- **Confusing:** Are these different things?
+
+**After:**
+- **"Workspace"** for EVERYONE
+- Same name, different data based on role
+- **Clear:** One unified dashboard concept
+
+---
+
+## Next Steps
+
+**When ready to deploy:**
+```bash
+cd ~/Projects/apiclaw/landing
+npm install  # if needed
+npm run build
+npx vercel --prod --yes
+```
+
+**Routes still work:**
+- `/workspace` → User workspace
+- `/providers/dashboard` → Still routes to workspace (URL unchanged for now)
+- Both show "Workspace" in UI
+
+---
+
+## No More Confusion
+
+✅ Users see: "Workspace"
+✅ API providers see: "Workspace"
+✅ Pratham will see: "Workspace"
+✅ AI/bots see: "Workspace"
+
+**One term. Clear meaning. No confusion.**
+
+🎯 **Done.**

package/VIDEO-DEMO-GUIDE.md

@@ -0,0 +1,82 @@
+# 🎬 Video Demo Setup Guide
+
+## ✅ What's Ready
+
+**Component created:** `landing/src/components/VideoDemo.tsx`
+**Integrated:** Landing page (`landing/src/app/page.tsx`)
+**Position:** Floating bubble, bottom-right corner
+**Animation:** Pulse effect + hover expand
+
+## 📹 Tomorrow Morning - Steps
+
+### 1. Record with Tella
+- Open Tella on Mac
+- Record 2-minute demo:
+  - Install: `npx @nordsym/apiclaw mcp-install`
+  - Show workspace
+  - Make an API call
+  - Show it working
+- Upload to Tella & get embed URL
+
+### 2. Update Component
+
+Open: `landing/src/components/VideoDemo.tsx`
+
+**Line 14** - Replace:
+```tsx
+videoUrl = "PASTE_TELLA_URL_HERE"
+```
+
+With your Tella embed URL (format: `https://www.tella.tv/video/...`)
+
+### 3. Deploy
+
+```bash
+cd ~/Projects/apiclaw/landing
+npm run build
+npx vercel --prod --yes
+```
+
+## 🎨 Styling
+
+**Already styled to match APIClaw design:**
+- Red accent (#ef4444)
+- Pulse animation
+- Clean modal
+- Mobile responsive
+- Dark mode compatible
+
+## 📝 Video Content Suggestion
+
+**0:00-0:20** - "I'm going to show you how to use APIClaw in 2 minutes"
+**0:20-0:40** - Install command + MCP setup
+**0:40-1:20** - Open workspace, discover APIs, make call
+**1:20-1:40** - Show response, explain Direct Call
+**1:40-2:00** - "That's it. No API keys needed. Go to apiclaw.cloud"
+
+## 🔧 Optional Customization
+
+**Change button text:**
+```tsx
+// In VideoDemo.tsx, line 28
+<span>Watch Demo</span>  // Change this
+```
+
+**Change video title:**
+```tsx
+// In VideoDemo.tsx, line 65
+<h3>🦞 APIClaw Quick Start</h3>  // Change this
+```
+
+## ✨ Features
+
+- ✅ Floating button (always visible while scrolling)
+- ✅ Click to open full-screen modal
+- ✅ Click outside to close
+- ✅ ESC key support
+- ✅ Responsive (works on mobile)
+- ✅ Smooth animations
+
+## 🚀 Ready to Go!
+
+Just record the video and paste the URL. Everything else is done.