@nordsym/apiclaw 1.8.1 → 1.8.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 NordSym AB
+
+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/apiclaw-README.md

@@ -12,12 +12,18 @@ The API layer for AI agents. 18 providers → 1000s of capabilities. Workspace
 [![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)
+[![GitHub Stars](https://img.shields.io/github/stars/nordsym/apiclaw?style=social)](https://github.com/nordsym/apiclaw)
+[![Built with MCP](https://img.shields.io/badge/Built%20with-MCP-purple)](https://modelcontextprotocol.io)
+
+> **If APIClaw saves you time, [⭐ star the repo](https://github.com/nordsym/apiclaw) — it helps more developers find us.**
+
+![APIClaw Demo](landing/public/demo.gif)
 
 ---
 
 ## The Platform
 
-**[apiclaw.com](https://apiclaw.com)** — Your workspace for API-powered agents.
+**[apiclaw.nordsym.com](https://apiclaw.nordsym.com)** — Your workspace for API-powered agents.
 
 | Layer | What You Get |
 |-------|--------------|
@@ -51,12 +57,52 @@ That's it. All 18 Direct Call providers work instantly through NordSym's infrast
 **Usage Limits:**
 - **Anonymous:** 10 calls/week (no registration)
 - **Registered:** 50 calls/week (5x more)
-- **Upgrade:** Contact us for higher limits
+- **Upgrade:** See [Pricing](#pricing) below
 
 Start calling APIs immediately. No setup, no API keys, no configuration.
 
 ---
 
+## End-to-End Example
+
+Here's a complete agent workflow — send an SMS, generate an image, and search the web in one session:
+
+```javascript
+// 1. Register for 50 calls/week
+register_owner({ email: "you@example.com" })
+
+// 2. Send an SMS via 46elks
+call_api({
+  provider: "46elks",
+  action: "send_sms",
+  params: {
+    to: "+46701234567",
+    message: "APIClaw is live! 🦞"
+  }
+})
+
+// 3. Generate an image via Replicate
+call_api({
+  provider: "replicate",
+  action: "run",
+  params: {
+    model: "stability-ai/sdxl",
+    input: { prompt: "a lobster wearing a top hat, digital art" }
+  }
+})
+
+// 4. Search the web via Brave
+call_api({
+  provider: "brave",
+  action: "search",
+  params: { q: "MCP protocol AI agents 2025", count: 5 }
+})
+```
+
+All three calls go through APIClaw's proxy — zero API keys, zero configuration.
+
+---
+
 ## What You Get
 
 ### Instant API Access
@@ -148,7 +194,7 @@ Public APIs, instantly callable. No API keys needed.
 - Food & Recipes
 - Science & Education
 
-Browse at [apiclaw.com/open-apis](https://apiclaw.com/open-apis)
+Browse at [apiclaw.nordsym.com/open-apis](https://apiclaw.nordsym.com/open-apis)
 
 ---
 
@@ -163,7 +209,7 @@ Use `discover_apis` to search:
 "What APIs exist for recipe data?"
 ```
 
-Browse at [apiclaw.com/discover](https://apiclaw.com/discover)
+Browse at [apiclaw.nordsym.com/discover](https://apiclaw.nordsym.com/discover)
 
 ---
 
@@ -358,7 +404,7 @@ You don't manage API keys. You don't configure auth. You don't worry about rate
 - Usage analytics in your workspace
 - Production-ready from day one
 
-**Want higher limits?** Upgrade at [apiclaw.com](https://apiclaw.com) or contact us.
+**Want higher limits?** See [Pricing](#pricing) below or upgrade at [apiclaw.nordsym.com](https://apiclaw.nordsym.com).
 
 ---
 
@@ -379,12 +425,66 @@ Returns the exact request that *would* be sent, with mock response data.
 
 ---
 
+## Why APIClaw?
+
+| | **APIClaw** | **RapidAPI** | **Direct API Keys** | **Kong / custom gateway** |
+|---|---|---|---|---|
+| **Setup time** | `curl \| bash` (30 sec) | Account + per-API signup | Per-provider signup | Hours of config |
+| **API keys to manage** | 0 | Per API | 1 per provider | 1 per provider |
+| **Providers covered** | 18 premium + 1,636 open | 40,000+ (DIY) | 1 at a time | Any (DIY) |
+| **MCP-native** | ✅ First-class | ❌ | ❌ | ❌ |
+| **Works in AI agents** | ✅ Out of the box | ⚠️ Manual wiring | ⚠️ Manual wiring | ⚠️ Manual wiring |
+| **Free tier** | ✅ 50 calls/week | ✅ Limited | Varies | ❌ |
+| **Self-hosted option** | ✅ | ❌ | — | ✅ |
+
+APIClaw is purpose-built for AI agents and MCP clients. No glue code, no key juggling — just call the API.
+
+---
+
+## Social Proof
+
+**9,000+ npm installs** · 88 versions shipped · Used in Claude Agents, GPT Builders, and Codex workflows worldwide.
+
+---
+
+## Pricing
+
+| Plan | Price | Calls/month | Best for |
+|------|-------|-------------|----------|
+| **Free** | $0 | 50 | Exploring, prototyping |
+| **Pro** | $79/mo | 5,000 | Solo builders & small teams |
+| **Scale** | $249/mo | 25,000 | Production agents |
+| **Enterprise** | Custom | Unlimited | Large teams & custom SLAs |
+
+→ [Upgrade at apiclaw.nordsym.com](https://apiclaw.nordsym.com) · Enterprise: [book a call](https://apiclaw.nordsym.com/contact)
+
+---
+
+## AI Discoverability
+
+APIClaw is optimized for discovery by AI agents and LLM tooling:
+
+- **llms.txt:** [apiclaw.nordsym.com/llms.txt](https://apiclaw.nordsym.com/llms.txt) — Machine-readable API index
+- **llms-full.txt:** [apiclaw.nordsym.com/llms-full.txt](https://apiclaw.nordsym.com/llms-full.txt) — Full capability descriptions
+- **ai-plugin.json:** [apiclaw.nordsym.com/.well-known/ai-plugin.json](https://apiclaw.nordsym.com/.well-known/ai-plugin.json) — OpenAI plugin manifest
+- **MCP:** Install with one command and any MCP-compatible agent can use APIClaw immediately
+
+---
+
+## Contributing & Changelog
+
+- [CONTRIBUTING.md](apiclaw-CONTRIBUTING.md) — How to contribute
+- [CHANGELOG.md](apiclaw-CHANGELOG.md) — Release history
+
+---
+
 ## Links
 
-- **Platform:** [apiclaw.com](https://apiclaw.com)
+- **Platform:** [apiclaw.nordsym.com](https://apiclaw.nordsym.com)
 - **Docs:** [apiclaw.nordsym.com/docs](https://apiclaw.nordsym.com/docs)
 - **GitHub:** [github.com/nordsym/apiclaw](https://github.com/nordsym/apiclaw)
 - **npm:** [@nordsym/apiclaw](https://www.npmjs.com/package/@nordsym/apiclaw)
+- **Security:** [SECURITY.md](SECURITY.md)
 
 ---
 

package/dist/index.js

@@ -1,49 +1,48 @@
 #!/usr/bin/env node
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var import_server = require("@modelcontextprotocol/sdk/server/index.js");
-var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
-var import_types = require("@modelcontextprotocol/sdk/types.js");
-var import_discovery = require("./discovery.js");
-var import_telemetry = require("./telemetry.js");
-var import_credits = require("./credits.js");
-var import_credentials = require("./credentials.js");
-var import_execute = require("./execute.js");
-var import_metered = require("./metered.js");
-var import_mcp_analytics = require("./mcp-analytics.js");
-var import_open_apis = require("./open-apis.js");
-var import_proxy = require("./proxy.js");
-var import_confirmation = require("./confirmation.js");
-var import_capability_router = require("./capability-router.js");
-var import_session = require("./session.js");
-var import_browser = require("convex/browser");
-var import_stripe = require("./stripe.js");
-var import_metered2 = require("./metered.js");
-var import_chainExecutor = require("./chainExecutor.js");
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { discoverAPIs, getAPIDetails, getCategories, getAllAPIs } from "./discovery.js";
+import { trackStartup, trackSearch } from "./telemetry.js";
+import {
+  addCredits,
+  purchaseAPIAccess,
+  getBalanceSummary
+} from "./credits.js";
+import { hasRealCredentials } from "./credentials.js";
+import { getConnectedProviders } from "./execute.js";
+import { executeMetered } from "./metered.js";
+import { logAPICall } from "./mcp-analytics.js";
+import { isOpenAPI, executeOpenAPI, listOpenAPIs } from "./open-apis.js";
+import { PROXY_PROVIDERS } from "./proxy.js";
+import {
+  requiresConfirmationAsync,
+  createPendingAction,
+  consumePendingAction,
+  generatePreview,
+  validateParams
+} from "./confirmation.js";
+import { executeCapability, listCapabilities, hasCapability } from "./capability-router.js";
+import { readSession, writeSession, clearSession, getMachineFingerprint, detectMCPClient } from "./session.js";
+import { ConvexHttpClient } from "convex/browser";
+import {
+  getOrCreateCustomer,
+  createMeteredCheckoutSession,
+  getUsageSummary,
+  METERED_BILLING
+} from "./stripe.js";
+import { estimateCost } from "./metered.js";
+import {
+  executeChain,
+  getChainStatus,
+  resumeChain
+} from "./chainExecutor.js";
 const DEFAULT_AGENT_ID = "agent_default";
 const CONVEX_URL = process.env.CONVEX_URL || "https://adventurous-avocet-799.convex.cloud";
-const convex = new import_browser.ConvexHttpClient(CONVEX_URL);
+const convex = new ConvexHttpClient(CONVEX_URL);
 let workspaceContext = null;
 let currentAgentId = null;
 const anonymousRateLimits = /* @__PURE__ */ new Map();
@@ -100,9 +99,11 @@ function checkAnonymousRateLimit(fingerprint) {
       allowed: false,
       error: JSON.stringify({
         success: false,
-        error: `Monthly limit reached (${ANONYMOUS_WEEKLY_LIMIT} calls)`,
-        hint: "Register to get 50 calls/month",
+        error: `\u26A1 You've hit your free tier limit (${ANONYMOUS_WEEKLY_LIMIT} calls/week).
+   Upgrade: https://apiclaw.nordsym.com/upgrade`,
+        hint: "Register for 50 calls/week, or upgrade for unlimited",
         action: "Run: register_owner({ email: 'you@example.com' })",
+        upgrade_url: "https://apiclaw.nordsym.com/upgrade",
         retry_after: getNextMonthUTC()
       }, null, 2)
     };
@@ -112,7 +113,7 @@ function checkAnonymousRateLimit(fingerprint) {
   return { allowed: true };
 }
 async function validateSession() {
-  const session = (0, import_session.readSession)();
+  const session = readSession();
   if (!session) {
     console.error("[APIClaw] No session found. Use register_owner to authenticate.");
     return false;
@@ -123,7 +124,7 @@ async function validateSession() {
     });
     if (!result.authenticated) {
       console.error("[APIClaw] Session invalid or expired. Clearing...");
-      (0, import_session.clearSession)();
+      clearSession();
       return false;
     }
     if (result.status !== "active") {
@@ -167,9 +168,9 @@ async function trackEarnProgress(workspaceId, provider, action) {
 const rateLimitStore = /* @__PURE__ */ new Map();
 const UNREGISTERED_CALL_LIMIT = 5;
 function checkWorkspaceAccess(providerId) {
-  if (providerId && import_proxy.PROXY_PROVIDERS.includes(providerId)) {
+  if (providerId && PROXY_PROVIDERS.includes(providerId)) {
     if (!workspaceContext) {
-      const fingerprint = (0, import_session.getMachineFingerprint)();
+      const fingerprint = getMachineFingerprint();
       const rateLimitCheck = checkAnonymousRateLimit(fingerprint);
       if (!rateLimitCheck.allowed) {
         return {
@@ -211,7 +212,8 @@ function checkWorkspaceAccess(providerId) {
         allowed: false,
         error: JSON.stringify({
           success: false,
-          error: `Monthly limit reached (${FREE_MONTHLY_LIMIT} calls)`,
+          error: `\u26A1 You've hit your free tier limit (${FREE_MONTHLY_LIMIT} calls/week).
+   Upgrade: https://apiclaw.nordsym.com/upgrade`,
           hint: "Upgrade to Backer for unlimited calls",
           upgrade_url: "https://apiclaw.nordsym.com/upgrade",
           retry_after: getNextMonthUTC()
@@ -220,7 +222,8 @@ function checkWorkspaceAccess(providerId) {
     }
     return {
       allowed: false,
-      error: `Usage limit reached. Contact support or check your plan at https://apiclaw.nordsym.com/account`
+      error: `\u26A1 You've hit your free tier limit (${FREE_MONTHLY_LIMIT} calls/week).
+   Upgrade: https://apiclaw.nordsym.com/upgrade`
     };
   }
   return { allowed: true, isAnonymous: false };
@@ -664,7 +667,7 @@ Example chain:
     }
   }
 ];
-const server = new import_server.Server(
+const server = new Server(
   {
     name: "apivault",
     version: "0.1.0"
@@ -675,10 +678,10 @@ const server = new import_server.Server(
     }
   }
 );
-server.setRequestHandler(import_types.ListToolsRequestSchema, async () => {
+server.setRequestHandler(ListToolsRequestSchema, async () => {
   return { tools };
 });
-server.setRequestHandler(import_types.CallToolRequestSchema, async (request) => {
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
   try {
     switch (name) {
@@ -729,10 +732,10 @@ Docs: https://apiclaw.nordsym.com
         const subagentId = args?.subagent_id;
         const aiBackend = args?.ai_backend;
         const startTime = Date.now();
-        const results = (0, import_discovery.discoverAPIs)(query, { category, maxResults, region });
+        const results = discoverAPIs(query, { category, maxResults, region });
         const responseTimeMs = Date.now() - startTime;
-        (0, import_telemetry.trackSearch)(query, results.length, responseTimeMs);
-        const analyticsUserId = workspaceContext?.workspaceId || `anon:${(0, import_session.getMachineFingerprint)()}`;
+        trackSearch(query, results.length, responseTimeMs);
+        const analyticsUserId = workspaceContext?.workspaceId || `anon:${getMachineFingerprint()}`;
         const convexUrl = CONVEX_URL;
         if (convexUrl) {
           fetch(`${convexUrl}/api/mutation`, {
@@ -822,7 +825,7 @@ Docs: https://apiclaw.nordsym.com
                 text: JSON.stringify({
                   status: "no_results",
                   message: `No APIs found matching "${query}". Try broader terms or check available categories with list_categories.`,
-                  available_categories: (0, import_discovery.getCategories)()
+                  available_categories: getCategories()
                 }, null, 2)
               }
             ]
@@ -856,7 +859,7 @@ Docs: https://apiclaw.nordsym.com
       case "get_api_details": {
         const apiId = args?.api_id;
         const compact = args?.compact || false;
-        const api = (0, import_discovery.getAPIDetails)(apiId, { compact });
+        const api = getAPIDetails(apiId, { compact });
         if (!api) {
           return {
             content: [
@@ -897,7 +900,7 @@ Docs: https://apiclaw.nordsym.com
         const apiId = args?.api_id;
         const amountUsd = args?.amount_usd;
         const agentId = args?.agent_id || DEFAULT_AGENT_ID;
-        const result = (0, import_credits.purchaseAPIAccess)(agentId, apiId, amountUsd);
+        const result = purchaseAPIAccess(agentId, apiId, amountUsd);
         if (!result.success) {
           return {
             content: [
@@ -911,7 +914,7 @@ Docs: https://apiclaw.nordsym.com
             ]
           };
         }
-        const api = (0, import_discovery.getAPIDetails)(apiId);
+        const api = getAPIDetails(apiId);
         return {
           content: [
             {
@@ -925,7 +928,7 @@ Docs: https://apiclaw.nordsym.com
                   amount_paid_usd: amountUsd,
                   credits_received: result.purchase.credits_purchased,
                   status: result.purchase.status,
-                  real_credentials: (0, import_credentials.hasRealCredentials)(apiId)
+                  real_credentials: hasRealCredentials(apiId)
                 },
                 credentials: result.purchase.credentials,
                 access: {
@@ -940,7 +943,7 @@ Docs: https://apiclaw.nordsym.com
       }
       case "check_balance": {
         const agentId = args?.agent_id || DEFAULT_AGENT_ID;
-        const summary = (0, import_credits.getBalanceSummary)(agentId);
+        const summary = getBalanceSummary(agentId);
         return {
           content: [
             {
@@ -957,7 +960,7 @@ Docs: https://apiclaw.nordsym.com
                   provider: p.provider_id,
                   credits_remaining: p.credits_purchased,
                   status: p.status,
-                  real_credentials: (0, import_credentials.hasRealCredentials)(p.provider_id)
+                  real_credentials: hasRealCredentials(p.provider_id)
                 }))
               }, null, 2)
             }
@@ -967,7 +970,7 @@ Docs: https://apiclaw.nordsym.com
       case "add_credits": {
         const amountUsd = args?.amount_usd;
         const agentId = args?.agent_id || DEFAULT_AGENT_ID;
-        const credits = (0, import_credits.addCredits)(agentId, amountUsd);
+        const credits = addCredits(agentId, amountUsd);
         return {
           content: [
             {
@@ -982,10 +985,10 @@ Docs: https://apiclaw.nordsym.com
         };
       }
       case "list_categories": {
-        const categories = (0, import_discovery.getCategories)();
+        const categories = getCategories();
         const apisByCategory = {};
         for (const cat of categories) {
-          apisByCategory[cat] = (0, import_discovery.getAllAPIs)().filter((a) => a.category === cat).map((a) => a.id);
+          apisByCategory[cat] = getAllAPIs().filter((a) => a.category === cat).map((a) => a.id);
         }
         return {
           content: [
@@ -1064,7 +1067,7 @@ Docs: https://apiclaw.nordsym.com
             const chainOptions = {
               verbose: false
             };
-            const chainResult = await (0, import_chainExecutor.executeChain)(
+            const chainResult = await executeChain(
               chainDefinition,
               chainCredentials,
               {},
@@ -1142,7 +1145,7 @@ Docs: https://apiclaw.nordsym.com
             }]
           };
         }
-        const isFreeAPI = (0, import_open_apis.isOpenAPI)(provider);
+        const isFreeAPI = isOpenAPI(provider);
         if (!isFreeAPI) {
           const access = checkWorkspaceAccess(provider);
           if (!access.allowed) {
@@ -1163,7 +1166,7 @@ Docs: https://apiclaw.nordsym.com
         let result;
         let apiType;
         if (confirmToken) {
-          const pending = (0, import_confirmation.consumePendingAction)(confirmToken);
+          const pending = consumePendingAction(confirmToken);
           if (!pending) {
             return {
               content: [{
@@ -1179,13 +1182,13 @@ Docs: https://apiclaw.nordsym.com
           apiType = "direct";
           const customerKey = args?.customer_key || getCustomerKey(pending.provider);
           const stripeCustomerId = args?.stripe_customer_id || process.env.APICLAW_STRIPE_CUSTOMER_ID;
-          result = await (0, import_metered.executeMetered)(pending.provider, pending.action, pending.params, {
+          result = await executeMetered(pending.provider, pending.action, pending.params, {
             customerId: stripeCustomerId,
             customerKey,
             userId: DEFAULT_AGENT_ID
           });
-          const analyticsUserId2 = workspaceContext ? workspaceContext.workspaceId : `anon:${(0, import_session.getMachineFingerprint)()}`;
-          (0, import_mcp_analytics.logAPICall)({
+          const analyticsUserId2 = workspaceContext ? workspaceContext.workspaceId : `anon:${getMachineFingerprint()}`;
+          logAPICall({
             timestamp: (/* @__PURE__ */ new Date()).toISOString(),
             provider: pending.provider,
             action: pending.action,
@@ -1212,10 +1215,10 @@ Docs: https://apiclaw.nordsym.com
             isError: !result.success
           };
         }
-        const confirmCheck = await (0, import_confirmation.requiresConfirmationAsync)(provider, action);
+        const confirmCheck = await requiresConfirmationAsync(provider, action);
         if (confirmCheck.required) {
           if (!confirmCheck.isDynamic) {
-            const validation = (0, import_confirmation.validateParams)(provider, action, params);
+            const validation = validateParams(provider, action, params);
             if (!validation.valid) {
               return {
                 content: [{
@@ -1231,11 +1234,11 @@ Docs: https://apiclaw.nordsym.com
               };
             }
           }
-          const preview = (0, import_confirmation.generatePreview)(provider, action, params);
+          const preview = generatePreview(provider, action, params);
           if (confirmCheck.estimatedCost) {
             preview.estimated_cost = confirmCheck.estimatedCost;
           }
-          const pending = (0, import_confirmation.createPendingAction)(provider, action, params, preview, DEFAULT_AGENT_ID);
+          const pending = createPendingAction(provider, action, params, preview, DEFAULT_AGENT_ID);
           return {
             content: [{
               type: "text",
@@ -1250,21 +1253,21 @@ Docs: https://apiclaw.nordsym.com
             }]
           };
         }
-        if ((0, import_open_apis.isOpenAPI)(provider)) {
+        if (isOpenAPI(provider)) {
           apiType = "open";
-          result = await (0, import_open_apis.executeOpenAPI)(provider, action, params);
+          result = await executeOpenAPI(provider, action, params);
         } else {
           apiType = "direct";
           const customerKey = args?.customer_key || getCustomerKey(provider);
           const stripeCustomerId = args?.stripe_customer_id || process.env.APICLAW_STRIPE_CUSTOMER_ID;
-          result = await (0, import_metered.executeMetered)(provider, action, params, {
+          result = await executeMetered(provider, action, params, {
             customerId: stripeCustomerId,
             customerKey,
             userId: DEFAULT_AGENT_ID
           });
         }
-        const analyticsUserId = workspaceContext ? workspaceContext.workspaceId : `anon:${(0, import_session.getMachineFingerprint)()}`;
-        (0, import_mcp_analytics.logAPICall)({
+        const analyticsUserId = workspaceContext ? workspaceContext.workspaceId : `anon:${getMachineFingerprint()}`;
+        logAPICall({
           timestamp: (/* @__PURE__ */ new Date()).toISOString(),
           provider,
           action,
@@ -1338,8 +1341,8 @@ Docs: https://apiclaw.nordsym.com
         };
       }
       case "list_connected": {
-        const directProviders = (0, import_execute.getConnectedProviders)();
-        const openProviders = (0, import_open_apis.listOpenAPIs)();
+        const directProviders = getConnectedProviders();
+        const openProviders = listOpenAPIs();
         return {
           content: [
             {
@@ -1383,9 +1386,9 @@ Docs: https://apiclaw.nordsym.com
           }).catch(() => {
           });
         }
-        const exists = await (0, import_capability_router.hasCapability)(capabilityId);
+        const exists = await hasCapability(capabilityId);
         if (!exists) {
-          const available = await (0, import_capability_router.listCapabilities)();
+          const available = await listCapabilities();
           return {
             content: [{
               type: "text",
@@ -1399,7 +1402,7 @@ Docs: https://apiclaw.nordsym.com
             isError: true
           };
         }
-        const result = await (0, import_capability_router.executeCapability)(
+        const result = await executeCapability(
           capabilityId,
           action,
           params,
@@ -1425,7 +1428,7 @@ Docs: https://apiclaw.nordsym.com
         };
       }
       case "list_capabilities": {
-        const capabilities = await (0, import_capability_router.listCapabilities)();
+        const capabilities = await listCapabilities();
         return {
           content: [{
             type: "text",
@@ -1458,13 +1461,13 @@ Docs: https://apiclaw.nordsym.com
         try {
           const existing = await convex.query("workspaces:getByEmail", { email });
           if (existing && existing.status === "active") {
-            const fingerprint2 = (0, import_session.getMachineFingerprint)();
+            const fingerprint2 = getMachineFingerprint();
             const sessionResult = await convex.mutation("workspaces:createAgentSession", {
               workspaceId: existing.id,
               fingerprint: fingerprint2
             });
             if (sessionResult.success) {
-              (0, import_session.writeSession)(sessionResult.sessionToken, existing.id, email);
+              writeSession(sessionResult.sessionToken, existing.id, email);
               try {
                 const claimResult = await convex.mutation("workspaces:claimAnonymousUsage", {
                   workspaceId: existing.id,
@@ -1511,7 +1514,7 @@ Docs: https://apiclaw.nordsym.com
           } else {
             throw new Error(createResult.error);
           }
-          const fingerprint = (0, import_session.getMachineFingerprint)();
+          const fingerprint = getMachineFingerprint();
           const magicLinkResult = await convex.mutation("workspaces:createMagicLink", {
             email,
             fingerprint
@@ -1560,7 +1563,7 @@ Docs: https://apiclaw.nordsym.com
         }
       }
       case "check_workspace_status": {
-        const session = (0, import_session.readSession)();
+        const session = readSession();
         if (!session) {
           return {
             content: [{
@@ -1577,7 +1580,7 @@ Docs: https://apiclaw.nordsym.com
             sessionToken: session.sessionToken
           });
           if (!result.authenticated) {
-            (0, import_session.clearSession)();
+            clearSession();
             workspaceContext = null;
             return {
               content: [{
@@ -1632,7 +1635,7 @@ Docs: https://apiclaw.nordsym.com
         }
       }
       case "remind_owner": {
-        const session = (0, import_session.readSession)();
+        const session = readSession();
         if (!session) {
           return {
             content: [{
@@ -1661,7 +1664,7 @@ Docs: https://apiclaw.nordsym.com
               }]
             };
           }
-          const fingerprint = (0, import_session.getMachineFingerprint)();
+          const fingerprint = getMachineFingerprint();
           const magicLinkResult = await convex.mutation("workspaces:createMagicLink", {
             email: session.email,
             fingerprint
@@ -1705,7 +1708,7 @@ Docs: https://apiclaw.nordsym.com
             isError: true
           };
         }
-        const customerResult = await (0, import_stripe.getOrCreateCustomer)(email, email);
+        const customerResult = await getOrCreateCustomer(email, email);
         if ("error" in customerResult) {
           return {
             content: [{
@@ -1715,7 +1718,7 @@ Docs: https://apiclaw.nordsym.com
             isError: true
           };
         }
-        const checkoutResult = await (0, import_stripe.createMeteredCheckoutSession)(
+        const checkoutResult = await createMeteredCheckoutSession(
           email,
           success_url || "https://apiclaw.nordsym.com/billing/success",
           cancel_url || "https://apiclaw.nordsym.com/billing/cancel"
@@ -1758,7 +1761,7 @@ Docs: https://apiclaw.nordsym.com
             isError: true
           };
         }
-        const usage = await (0, import_stripe.getUsageSummary)(subscription_id);
+        const usage = await getUsageSummary(subscription_id);
         if ("error" in usage) {
           return {
             content: [{
@@ -1779,7 +1782,7 @@ Docs: https://apiclaw.nordsym.com
               },
               usage: {
                 total_calls: usage.totalCalls,
-                price_per_call: import_stripe.METERED_BILLING.pricePerCall,
+                price_per_call: METERED_BILLING.pricePerCall,
                 estimated_cost: `$${usage.totalCost.toFixed(4)}`
               }
             }, null, 2)
@@ -1797,7 +1800,7 @@ Docs: https://apiclaw.nordsym.com
             isError: true
           };
         }
-        const estimate = (0, import_metered2.estimateCost)(call_count);
+        const estimate = estimateCost(call_count);
         return {
           content: [{
             type: "text",
@@ -1810,9 +1813,9 @@ Docs: https://apiclaw.nordsym.com
                 currency: estimate.currency
               },
               examples: {
-                "100 calls": `$${(100 * import_stripe.METERED_BILLING.pricePerCall).toFixed(2)}`,
-                "1,000 calls": `$${(1e3 * import_stripe.METERED_BILLING.pricePerCall).toFixed(2)}`,
-                "10,000 calls": `$${(1e4 * import_stripe.METERED_BILLING.pricePerCall).toFixed(2)}`
+                "100 calls": `$${(100 * METERED_BILLING.pricePerCall).toFixed(2)}`,
+                "1,000 calls": `$${(1e3 * METERED_BILLING.pricePerCall).toFixed(2)}`,
+                "10,000 calls": `$${(1e4 * METERED_BILLING.pricePerCall).toFixed(2)}`
               }
             }, null, 2)
           }]
@@ -1835,7 +1838,7 @@ Docs: https://apiclaw.nordsym.com
             isError: true
           };
         }
-        const chainStatus = await (0, import_chainExecutor.getChainStatus)(chainId);
+        const chainStatus = await getChainStatus(chainId);
         if (chainStatus.status === "not_found") {
           return {
             content: [{
@@ -1929,7 +1932,7 @@ Docs: https://apiclaw.nordsym.com
           if (customerKey) {
             chainCredentials.customerKeys = { default: customerKey };
           }
-          const result = await (0, import_chainExecutor.resumeChain)(
+          const result = await resumeChain(
             resumeToken,
             chainDefinition,
             chainCredentials,
@@ -2012,14 +2015,14 @@ async function main() {
     await startCLI();
     return;
   }
-  const transport = new import_stdio.StdioServerTransport();
+  const transport = new StdioServerTransport();
   await server.connect(transport);
-  (0, import_telemetry.trackStartup)();
+  trackStartup();
   const hasValidSession = await validateSession();
   try {
-    const fingerprint = (0, import_session.getMachineFingerprint)();
-    const mcpClient = (0, import_session.detectMCPClient)();
-    const existingSession = (0, import_session.readSession)();
+    const fingerprint = getMachineFingerprint();
+    const mcpClient = detectMCPClient();
+    const existingSession = readSession();
     const result = await convex.mutation("agents:ensureAgent", {
       fingerprint,
       mcpClient,
@@ -2030,7 +2033,7 @@ async function main() {
       currentAgentId = result.agentId;
     }
     if (result?.isNew && result?.sessionToken && !hasValidSession) {
-      (0, import_session.writeSession)(result.sessionToken, result.workspaceId, "");
+      writeSession(result.sessionToken, result.workspaceId, "");
     }
   } catch (e) {
     console.error("[APIClaw] Agent registration failed (non-blocking):", e);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nordsym/apiclaw",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "The API layer for AI agents. Dashboard + 22K APIs + 18 Direct Call providers. MCP native.",
   "type": "module",
   "main": "dist/index.js",
@@ -14,6 +14,7 @@
   },
   "scripts": {
     "build": "tsc && cp -r src/registry dist/",
+    "postinstall": "node dist/postinstall.js || true",
     "dev": "tsx watch src/index.ts",
     "start": "node dist/index.js",
     "start:http": "tsx src/http-server-minimal.ts",

package/src/bin.ts

@@ -6,11 +6,26 @@
  * - setup/doctor/restore/uninstall → Run CLI
  */
 
+import { existsSync } from 'fs';
+import { join } from 'path';
+
 const cliCommands = ['setup', 'mcp-install', 'mcp-uninstall', 'doctor', 'restore', 'uninstall', 'help', '--help', '-h', '--version', '-V'];
 
 const firstArg = process.argv[2];
 
 if (!firstArg || !cliCommands.includes(firstArg)) {
+  // First-run nudge: non-blocking hint if no workspace is configured
+  try {
+    const sessionFile = join(process.env.HOME ?? '~', '.apiclaw', 'session');
+    if (!existsSync(sessionFile)) {
+      process.stderr.write(
+        '\x1b[33m💡 No workspace linked. Get one free: https://apiclaw.nordsym.com/workspace\x1b[0m\n'
+      );
+    }
+  } catch {
+    // Never let this block server startup
+  }
+
   // Run MCP server
   import('./index.js');
 } else {

package/src/index.ts

@@ -170,9 +170,10 @@ function checkAnonymousRateLimit(fingerprint: string): { allowed: boolean; error
       allowed: false,
       error: JSON.stringify({
         success: false,
-        error: `Monthly limit reached (${ANONYMOUS_WEEKLY_LIMIT} calls)`,
-        hint: "Register to get 50 calls/month",
+        error: `⚡ You've hit your free tier limit (${ANONYMOUS_WEEKLY_LIMIT} calls/week).\n   Upgrade: https://apiclaw.nordsym.com/upgrade`,
+        hint: "Register for 50 calls/week, or upgrade for unlimited",
         action: "Run: register_owner({ email: 'you@example.com' })",
+        upgrade_url: "https://apiclaw.nordsym.com/upgrade",
         retry_after: getNextMonthUTC()
       }, null, 2)
     };
@@ -335,7 +336,7 @@ function checkWorkspaceAccess(providerId?: string): { allowed: boolean; error?:
         allowed: false, 
         error: JSON.stringify({
           success: false,
-          error: `Monthly limit reached (${FREE_MONTHLY_LIMIT} calls)`,
+          error: `⚡ You've hit your free tier limit (${FREE_MONTHLY_LIMIT} calls/week).\n   Upgrade: https://apiclaw.nordsym.com/upgrade`,
           hint: "Upgrade to Backer for unlimited calls",
           upgrade_url: "https://apiclaw.nordsym.com/upgrade",
           retry_after: getNextMonthUTC()
@@ -346,7 +347,7 @@ function checkWorkspaceAccess(providerId?: string): { allowed: boolean; error?:
     // Other tiers (shouldn't happen, but handle gracefully)
     return { 
       allowed: false, 
-      error: `Usage limit reached. Contact support or check your plan at https://apiclaw.nordsym.com/account` 
+      error: `⚡ You've hit your free tier limit (${FREE_MONTHLY_LIMIT} calls/week).\n   Upgrade: https://apiclaw.nordsym.com/upgrade` 
     };
   }
   

package/src/postinstall.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * APIClaw Postinstall Hook
+ * Prints a welcome message with links after install.
+ * No network calls. No side effects.
+ */
+
+const CYAN = '\x1b[36m';
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+
+console.log('');
+console.log(`  🦞 APIClaw installed successfully!`);
+console.log('');
+console.log(`  → Create your free workspace: ${CYAN}https://apiclaw.nordsym.com/workspace${RESET}`);
+console.log(`  → Quick setup: ${CYAN}npx @nordsym/apiclaw setup${RESET}`);
+console.log(`  ⭐ Star us: ${CYAN}https://github.com/nordsym/apiclaw${RESET}  ${DIM}(helps more devs find us)${RESET}`);
+console.log('');