@nordsym/apiclaw 1.4.2 → 1.4.3

package/README.md

@@ -1,365 +1,282 @@
 # 🦞 APIClaw
 
-> **The API layer for AI agents.** 22,000+ APIs indexed. Direct Call execution. Zero config.
+The API layer for AI agents. 18 providers → 1000s of capabilities. Workspace → Dashboard → Ship.
 
 [![npm version](https://img.shields.io/npm/v/@nordsym/apiclaw.svg)](https://www.npmjs.com/package/@nordsym/apiclaw)
 [![npm downloads](https://img.shields.io/npm/dw/@nordsym/apiclaw.svg)](https://www.npmjs.com/package/@nordsym/apiclaw)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
 
-**APIs Indexed:** 22,392 • **Open APIs:** 1,636 • **Direct Call Providers:** 18
+---
+
+## The Platform
+
+**[apiclaw.com](https://apiclaw.com)** — Your workspace for API-powered agents.
+
+| Layer | What You Get |
+|-------|--------------|
+| **Workspace** | Manage API keys, team access, usage analytics |
+| **Dashboard** | Real-time logs, cost tracking, rate limit monitoring |
+| **18 Direct Call Providers** | 1000+ ML models, 100+ LLMs, voice, SMS, email — zero config |
+| **1,636 Open APIs** | Curated public APIs, instant access |
+| **22,392 Discovery** | Full API index for exploration |
+
+One `mcp-install` connects your agent to all of it.
 
 ---
 
 ## Quick Start
 
 ```bash
-# Install APIClaw into Claude Desktop or Claude Code
 npx @nordsym/apiclaw mcp-install
-
-# That's it! Restart your AI assistant and ask:
-# "List available APIs" or "Send an SMS via 46elks"
 ```
 
-APIClaw automatically detects Claude Desktop and Claude Code — then configures itself as an MCP server in seconds. Works with any MCP-compatible agent.
+That's it. Restart your AI assistant. Ask it to *"Send an SMS"* or *"Generate an image"* — it works.
 
 ---
 
-## What is APIClaw?
+## What You Get
 
-**The API layer for AI agents.** APIClaw is an MCP server that gives any MCP-compatible agent access to real-world APIs:
+### Instant API Access
+Tell your agent what to do. APIClaw handles auth, rate limits, and execution.
 
-- **📱 SMS & Voice** — 46elks, Twilio
-- **📧 Email** — Resend, SendGrid
-- **💳 Payments** — Stripe
-- **🔍 Search** — Brave Search
-- **🤖 AI** — OpenRouter, ElevenLabs
-- **...and 100+ more** — growing weekly
+### 18 Direct Call Providers
+Premium APIs ready for production. Voice, AI, SMS, Email, Search — all pre-configured.
 
-Instead of manually configuring API keys and reading documentation, just tell your AI: *"Send a confirmation SMS to +46701234567"* — and it works.
+### 1,636 Open APIs
+Public APIs indexed and callable. Weather, crypto, sports, government data.
+
+### 22,392 Discovery APIs
+The full catalog. Search, explore, find the right API for any task.
+
+### Workspace Dashboard
+See every call, track costs, monitor usage. One place for your entire team.
 
 ---
 
-## Installation
+## 18 Direct Call Providers
 
-### Option 1: MCP Install (Recommended)
+Pre-configured, production-ready APIs. Just call them.
 
-```bash
-npx @nordsym/apiclaw mcp-install
-```
+### 🤖 AI & LLM
 
-This will:
-1. 🔍 Detect Claude Desktop or Claude Code
-2. 📝 Add APIClaw to the MCP config
-3. ✅ Verify the setup
+| Provider | Capability |
+|----------|------------|
+| **Replicate** | 1,000+ ML models — image gen, video, audio, any model |
+| **OpenRouter** | 100+ LLMs — GPT-4, Claude, Llama, Mistral, unified API |
+| **Groq** | Ultra-fast inference — Llama, Mixtral at 500+ tokens/sec |
+| **Mistral** | Mistral models — Mistral Large, Medium, Small |
+| **Cohere** | Enterprise NLP — embeddings, rerank, generate |
+| **Together AI** | Open models — fine-tuning, fast inference |
+| **Stability AI** | Image generation — Stable Diffusion, SDXL, SD3 |
 
-### Option 2: Manual Installation
+### 🎤 Voice
 
-```bash
-npm install -g @nordsym/apiclaw
-apiclaw setup
-```
+| Provider | Capability |
+|----------|------------|
+| **ElevenLabs** | Text-to-speech — 29 languages, voice cloning, realistic voices |
+| **Deepgram** | Speech-to-text — real-time transcription, 36 languages |
+| **AssemblyAI** | Audio intelligence — transcription, summarization, sentiment |
+
+### 📱 SMS
+
+| Provider | Capability |
+|----------|------------|
+| **46elks** | Swedish SMS API — simple, reliable, great pricing |
+| **Twilio** | Global SMS — 180+ countries, programmable messaging |
+
+### 📧 Email
+
+| Provider | Capability |
+|----------|------------|
+| **Resend** | Developer email — simple API, great deliverability |
+
+### 🔍 Search
+
+| Provider | Capability |
+|----------|------------|
+| **Brave Search** | Web search — privacy-focused, no tracking |
+| **Firecrawl** | Web scraping — extract content, convert to markdown |
+| **Serper** | Google Search API — SERP data, real-time results |
+
+### 💻 Code
+
+| Provider | Capability |
+|----------|------------|
+| **E2B** | Code sandbox — run any code safely, isolated environments |
 
-### Option 3: Use npx (No Install)
+### 🛠️ Dev
 
-Just use `npx @nordsym/apiclaw` anywhere — it downloads on demand.
+| Provider | Capability |
+|----------|------------|
+| **GitHub** | GitHub API — repos, issues, PRs, actions |
 
 ---
 
-## Commands
+## 1,636 Open APIs
+
+Public APIs, instantly callable. No API keys needed.
+
+**Categories:**
+- Weather & Environment
+- Finance & Crypto
+- Sports & Entertainment
+- Government & Public Data
+- Transportation
+- Food & Recipes
+- Science & Education
+
+Browse at [apiclaw.com/open-apis](https://apiclaw.com/open-apis)
+
+---
+
+## 22,392 Discovery APIs
+
+The full index. Every API we've cataloged.
+
+Use `discover_apis` to search:
+```
+"Find APIs for flight tracking"
+"Show me cryptocurrency price APIs"
+"What APIs exist for recipe data?"
+```
+
+Browse at [apiclaw.com/discover](https://apiclaw.com/discover)
 
-### `mcp-install`
+---
+
+## Installation
 
-Simple, focused installation for Claude Desktop and Claude Code.
+### One-Line Install (Recommended)
 
 ```bash
-# Auto-detect and install
 npx @nordsym/apiclaw mcp-install
+```
+
+Auto-detects Claude Desktop or Claude Code. Configures MCP. Done.
+
+### Options
 
-# Install to specific client
+```bash
+# Target specific client
 npx @nordsym/apiclaw mcp-install --client claude-desktop
 npx @nordsym/apiclaw mcp-install --client claude-code
 
-# Preview changes without applying
+# Preview without applying
 npx @nordsym/apiclaw mcp-install --dry-run
 ```
 
-### `setup`
-
-Full-featured setup with support for all MCP clients.
+### Global Install
 
 ```bash
-# Auto-detect and configure all clients
-npx @nordsym/apiclaw setup
+npm install -g @nordsym/apiclaw
+apiclaw setup
+```
 
-# Configure specific client
-npx @nordsym/apiclaw setup --client claude-desktop
-npx @nordsym/apiclaw setup --client cursor
-npx @nordsym/apiclaw setup --client windsurf
-npx @nordsym/apiclaw setup --client cline
-npx @nordsym/apiclaw setup --client continue
+---
 
-# Custom config path
-npx @nordsym/apiclaw setup --config /path/to/config.json
+## Commands
 
-# Link a workspace
-npx @nordsym/apiclaw setup --workspace ws_abc123
+| Command | Description |
+|---------|-------------|
+| `mcp-install` | Quick setup for Claude Desktop/Code |
+| `setup` | Full setup with all MCP client options |
+| `doctor` | Diagnose your APIClaw installation |
+| `restore` | Restore config from backup |
+| `uninstall` | Remove APIClaw from clients |
 
-# Preview changes without applying
-npx @nordsym/apiclaw setup --dry-run
+### setup
 
-# Force overwrite existing config
-npx @nordsym/apiclaw setup --force
+Full-featured setup for any MCP client.
 
-# Interactive mode
+```bash
+npx @nordsym/apiclaw setup --client cursor
+npx @nordsym/apiclaw setup --client windsurf
+npx @nordsym/apiclaw setup --client cline
+npx @nordsym/apiclaw setup --workspace ws_abc123
 npx @nordsym/apiclaw setup --wizard
 ```
 
-### `doctor`
+### doctor
 
-Diagnose your APIClaw setup.
+Check your setup.
 
 ```bash
 npx @nordsym/apiclaw doctor
 ```
 
-Output:
 ```
 🔍 APIClaw Health Check
 ========================
-
 System:
   ✓ Node.js v20.11.0
   ✓ npm 10.2.4
-  ✓ npx available
 
 MCP Clients:
   ✓ Claude Desktop - Configured ✓
   ✓ Cursor - Configured ✓
-  ✗ Windsurf - Not installed
-
-Connectivity:
-  ✓ api.apiclaw.com reachable
 
 Status: All systems operational ✓
 ```
 
-### `restore`
+### restore
 
-Restore config from backup.
+Restore from backup.
 
 ```bash
-# Restore most recent backup
-npx @nordsym/apiclaw restore
-
-# List available backups
 npx @nordsym/apiclaw restore --list
-
-# Restore specific backup
-npx @nordsym/apiclaw restore --backup config.backup.1709150400.json
+npx @nordsym/apiclaw restore
 ```
 
-### `uninstall`
+### uninstall
 
-Remove APIClaw from all configured clients.
+Remove APIClaw.
 
 ```bash
 npx @nordsym/apiclaw uninstall
-
-# Remove from specific client
 npx @nordsym/apiclaw uninstall --client cursor
 ```
 
 ---
 
-## Options
-
-| Option | Description |
-|--------|-------------|
-| `--client <name>` | Target specific MCP client |
-| `--config <path>` | Use custom config file path |
-| `--workspace <id>` | Link an APIClaw workspace |
-| `--dry-run` | Preview changes without applying |
-| `--force` | Overwrite existing APIClaw config |
-| `--wizard` | Interactive setup mode |
-| `--no-backup` | Skip creating backup (not recommended) |
-| `--verbose` | Show detailed output |
-| `--version` | Show version number |
-| `--help` | Show help |
-
----
-
-## Supported MCP Clients
+## MCP Clients
 
 | Client | macOS | Windows | Linux |
 |--------|:-----:|:-------:|:-----:|
 | **Claude Desktop** | ✅ | ✅ | ✅ |
+| **Claude Code** | ✅ | ✅ | ✅ |
 | **Cursor** | ✅ | ✅ | ✅ |
 | **Windsurf** | ✅ | ✅ | ✅ |
-| **Cline** (VS Code) | ✅ | ✅ | ✅ |
+| **Cline** | ✅ | ✅ | ✅ |
 | **Continue** | ✅ | ✅ | ✅ |
-| **Custom** | ✅ | ✅ | ✅ |
-
-### Config Locations
-
-<details>
-<summary>Claude Desktop</summary>
-
-| OS | Path |
-|----|------|
-| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
-| Linux | `~/.config/Claude/claude_desktop_config.json` |
-
-</details>
-
-<details>
-<summary>Cursor</summary>
-
-| OS | Path |
-|----|------|
-| macOS | `~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/config.json` |
-| Windows | `%APPDATA%\Cursor\User\globalStorage\cursor.mcp\config.json` |
-| Linux | `~/.config/Cursor/User/globalStorage/cursor.mcp/config.json` |
-
-</details>
 
 <details>
-<summary>Windsurf</summary>
-
-| OS | Path |
-|----|------|
-| macOS | `~/.codeium/windsurf/mcp_config.json` |
-| Windows | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` |
-| Linux | `~/.codeium/windsurf/mcp_config.json` |
-
-</details>
+<summary>Config Locations</summary>
 
-<details>
-<summary>Cline</summary>
+**Claude Desktop**
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
 
-| OS | Path |
-|----|------|
-| macOS | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
-| Windows | `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json` |
-| Linux | `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
+**Cursor**
+- macOS: `~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/config.json`
+- Windows: `%APPDATA%\Cursor\User\globalStorage\cursor.mcp\config.json`
 
-</details>
+**Windsurf**
+- All: `~/.codeium/windsurf/mcp_config.json`
 
-<details>
-<summary>Continue</summary>
+**Cline**
+- macOS: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
 
-| OS | Path |
-|----|------|
-| macOS | `~/.continue/config.json` |
-| Windows | `%USERPROFILE%\.continue\config.json` |
-| Linux | `~/.continue/config.json` |
+**Continue**
+- All: `~/.continue/config.json`
 
 </details>
 
 ---
 
-## Enterprise Deployment
-
-Deploy APIClaw to your entire development team.
-
-### Environment Variables
-
-```bash
-# Pre-configure workspace for all users
-export APICLAW_WORKSPACE="ws_enterprise_123"
-
-# Point to self-hosted instance
-export APICLAW_API_URL="https://api.company.com/apiclaw"
-
-# Disable telemetry
-export APICLAW_DISABLE_TELEMETRY="true"
-
-npx @nordsym/apiclaw mcp-install
-```
-
-### Generate Deployment Script
-
-```bash
-# Generate cross-platform setup script
-npx @nordsym/apiclaw setup --enterprise --output deploy.sh
-```
-
-The generated script handles:
-- OS detection
-- Client detection
-- Config injection
-- Verification
-- Error reporting
-
-### MDM/Group Policy
-
-See [Enterprise Deployment Guide](docs/enterprise-deployment.md) for:
-- Jamf/Kandji/Mosyle (macOS)
-- Intune/Group Policy (Windows)
-- Ansible/Chef/Puppet (Linux)
-
----
-
-## Troubleshooting
-
-### "Permission denied"
-
-```bash
-# Option 1: Run with sudo
-sudo npx @nordsym/apiclaw mcp-install
-
-# Option 2: Fix permissions
-chmod 644 ~/Library/Application\ Support/Claude/claude_desktop_config.json
-```
-
-### "Config file not found"
-
-The MCP client hasn't created its config yet:
-1. Open the client (Claude Desktop or Claude Code)
-2. Close it
-3. Try mcp-install again
-
-Or use the full setup command with a custom path:
-```bash
-npx @nordsym/apiclaw setup --config /path/to/config.json
-```
-
-### "Invalid JSON"
-
-Your config file has syntax errors:
-```bash
-# Restore from backup
-npx @nordsym/apiclaw restore --list
-npx @nordsym/apiclaw restore
-
-# Or manually fix the JSON
-```
-
-### "Already configured"
-
-APIClaw is already set up. To update:
-```bash
-npx @nordsym/apiclaw setup --force
-```
-
-### Still having issues?
-
-```bash
-# Run diagnostics
-npx @nordsym/apiclaw doctor --verbose
-
-# Get help
-https://docs.apiclaw.com/setup
-https://github.com/nordsym/apiclaw/issues
-```
-
----
-
 ## How It Works
 
-APIClaw modifies your MCP client's config file to register itself as a server:
-
 ```json
 {
   "mcpServers": {
@@ -371,215 +288,38 @@ APIClaw modifies your MCP client's config file to register itself as a server:
 }
 ```
 
-When your AI assistant starts, it launches APIClaw as an MCP server. APIClaw then:
-1. Exposes available APIs as MCP tools
-2. Handles authentication and rate limiting
-3. Executes API calls on behalf of the AI
-
----
-
-## Safety Features
-
-### Automatic Backups
-
-Before modifying any config, APIClaw creates a timestamped backup:
-```
-claude_desktop_config.backup.1709150400.json
-```
-
-### Non-Destructive
-
-- Never overwrites existing configurations
-- Deep merges APIClaw into `mcpServers`
-- Preserves all other settings
-
-### Validation
-
-- Parses JSON before and after modifications
-- Verifies required fields exist
-- Rolls back on any error
+1. Your agent launches APIClaw as an MCP server
+2. APIClaw exposes APIs as callable tools
+3. Agent calls `send_sms`, `generate_image`, `search_web`
+4. APIClaw handles auth, rate limits, execution
+5. Results flow back to the agent
 
 ---
 
 ## Dry-Run Mode
 
-Test API calls without actually executing them. Perfect for debugging, development, and agent testing.
-
-### Usage
+Test without making real API calls.
 
 ```javascript
-// In MCP tool call
 call_api({
   provider: "46elks",
   action: "send_sms",
-  params: {
-    to: "+46701234567",
-    message: "Hello from dry-run!"
-  },
-  dry_run: true  // ← No actual API call made
+  params: { to: "+46701234567", message: "Test" },
+  dry_run: true
 })
 ```
 
-### Response
-
-```json
-{
-  "dry_run": true,
-  "provider": "46elks",
-  "action": "send_sms",
-  "would_send": {
-    "url": "https://api.46elks.com/a1/sms",
-    "method": "POST",
-    "headers": {
-      "Content-Type": "application/json",
-      "Authorization": "Basic [base64(username:password)]"
-    },
-    "body": {
-      "from": "APIClaw",
-      "to": "+46701234567",
-      "message": "Hello from dry-run!"
-    }
-  },
-  "mock_response": {
-    "success": true,
-    "data": {
-      "id": "mock_sms_123",
-      "status": "delivered"
-    },
-    "estimated_cost": "~0.35-0.52 SEK"
-  },
-  "notes": [
-    "⚠️ DRY-RUN MODE: No actual API call was made",
-    "This shows what WOULD be sent if you remove dry_run: true"
-  ]
-}
-```
-
-### Benefits
-
-- **💰 No cost** — Test without burning API credits
-- **🔍 Debug** — See exact request that would be sent
-- **🧪 Test** — Validate agent workflows before going live
-- **📋 Mock data** — Get realistic response shapes for development
-
-### Supported Providers
-
-All Direct Call providers support dry-run:
-- 46elks, Twilio (SMS)
-- Resend (Email)
-- Brave Search
-- OpenRouter (LLM)
-- ElevenLabs (TTS)
-- Replicate (AI models)
-- Firecrawl (Web scraping)
-- GitHub
-- E2B (Code sandbox)
-
----
-
-## Error Handling
-
-APIClaw returns structured error responses across all providers, making it easy to handle failures programmatically.
-
-### Error Response Format
-
-All errors follow this structure:
-
-```json
-{
-  "success": false,
-  "provider": "replicate",
-  "action": "run",
-  "error": "Rate limit exceeded",
-  "code": "RATE_LIMITED"
-}
-```
-
-### Error Codes
-
-| Code | Description |
-|------|-------------|
-| `RATE_LIMITED` | API rate limit hit (429) |
-| `SERVICE_UNAVAILABLE` | Service temporarily unavailable (502, 503, 504) |
-| `UNAUTHORIZED` | Invalid or missing credentials (401) |
-| `FORBIDDEN` | Access denied (403) |
-| `NOT_FOUND` | Resource not found (404) |
-| `BAD_REQUEST` | Invalid request parameters (400) |
-| `TIMEOUT` | Request timed out |
-| `NETWORK_ERROR` | Network connectivity issue |
-| `PROVIDER_ERROR` | Provider-specific error |
-| `INVALID_PARAMS` | Missing or invalid parameters |
-| `NO_CREDENTIALS` | No credentials configured for provider |
-| `UNKNOWN_PROVIDER` | Provider not available |
-| `UNKNOWN_ACTION` | Action not available for provider |
-| `MAX_RETRIES_EXCEEDED` | All retry attempts failed |
-
-### Automatic Retry
-
-APIClaw automatically retries transient failures with exponential backoff:
-
-- **Retryable errors:** 429 (Rate Limited), 502, 503, 504 (Service Unavailable)
-- **Max retries:** 3
-- **Backoff:** Exponential with jitter (1s → 2s → 4s, capped at 30s)
-- **Retry-After:** Respects `Retry-After` header when present
-
-```javascript
-// APIClaw handles retries automatically — you just see the final result
-const result = await call_api({
-  provider: "openrouter",
-  action: "chat",
-  params: { messages: [...] }
-});
-
-if (!result.success) {
-  console.log(`Error: ${result.error} (${result.code})`);
-  // Handle error based on code
-  if (result.code === "RATE_LIMITED") {
-    // Wait longer before next request
-  }
-}
-```
-
-### Best Practices
-
-1. **Always check `success`** before accessing `data`
-2. **Use `code`** for programmatic error handling
-3. **Use `error`** for human-readable messages
-4. **Let APIClaw retry** — don't implement your own retry logic for 429/503
+Returns the exact request that *would* be sent, with mock response data.
 
 ---
 
-## Development
-
-```bash
-# Clone the repo
-git clone https://github.com/nordsym/apiclaw.git
-cd apiclaw
-
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Run locally
-npm run dev
+## Links
 
-# Test setup locally
-npm run setup:test
-```
+- **Platform:** [apiclaw.com](https://apiclaw.com)
+- **Docs:** [docs.apiclaw.com](https://docs.apiclaw.com)
+- **GitHub:** [github.com/nordsym/apiclaw](https://github.com/nordsym/apiclaw)
+- **npm:** [@nordsym/apiclaw](https://www.npmjs.com/package/@nordsym/apiclaw)
 
 ---
 
-## License
-
 MIT © [NordSym](https://nordsym.com)
-
----
-
-## Links
-
-- **Website:** [apiclaw.com](https://apiclaw.com)
-- **Documentation:** [docs.apiclaw.com](https://docs.apiclaw.com)
-- **GitHub:** [github.com/nordsym/apiclaw](https://github.com/nordsym/apiclaw)
-- **npm:** [@nordsym/apiclaw](https://www.npmjs.com/package/@nordsym/apiclaw)