@volisphere/commercial 0.1.0 → 0.2.0

package/dist/client.d.ts

@@ -144,6 +144,44 @@ export interface AgentProfile {
     is_online: boolean;
     monetization_enabled: boolean;
 }
+export interface InvokeAgentParams {
+    target_agent: string;
+    message: string;
+    skill?: string;
+}
+export interface InvokeAgentResponse {
+    request_id: string;
+    agent_slug: string;
+    agent_name: string;
+    response: string;
+    sponsored?: Array<{
+        ad_entity_id: string;
+        campaign_id: string;
+        title: string;
+        description: string;
+        call_to_action: string;
+        landing_url: string;
+        recommendation_id: string;
+    }>;
+}
+export interface DailyStatPoint {
+    date: string;
+    spend_micros: number;
+    earnings_micros: number;
+    match_count: number;
+    impression_count: number;
+    action_count: number;
+}
+export interface StatsResponse {
+    period: string;
+    points: DailyStatPoint[];
+    total_spend_micros: number;
+    total_earnings_micros: number;
+    total_matches: number;
+}
+export interface BalanceResponse {
+    balance_micros: number;
+}
 export declare class VolisphereClient {
     private baseURL;
     private apiKey;
@@ -161,4 +199,27 @@ export declare class VolisphereClient {
     registerAgent(params: RegisterAgentParams): Promise<RegisterAgentResponse>;
     heartbeat(agentId: string): Promise<void>;
     setMonetization(agentId: string, enabled: boolean): Promise<AgentProfile>;
+    invokeAgent(params: InvokeAgentParams): Promise<InvokeAgentResponse>;
+    getSSPStats(days?: number): Promise<StatsResponse>;
+    getDSPStats(days?: number): Promise<StatsResponse>;
+    getBalance(): Promise<BalanceResponse>;
+}
+export interface WSEventHandlers {
+    onRequest?: (requestId: string, from: string, message: string, skillHint?: string) => Promise<string>;
+    onConnected?: () => void;
+    onDisconnected?: () => void;
+    onError?: (error: Error) => void;
+}
+export declare class GatewayWSClient {
+    private ws;
+    private baseURL;
+    private apiKey;
+    private handlers;
+    private reconnectTimer;
+    private isShuttingDown;
+    constructor(baseURL: string, apiKey: string, handlers: WSEventHandlers);
+    connect(): void;
+    private handleMessage;
+    private send;
+    disconnect(): void;
 }

package/dist/client.js

@@ -1,4 +1,4 @@
-// ─── SSP Types (Developer / Monetization) ───────────────────────────────────
+import WebSocket from "ws";
 // ─── Unified Client ─────────────────────────────────────────────────────────
 export class VolisphereClient {
     baseURL;
@@ -133,4 +133,132 @@ export class VolisphereClient {
         }
         return res.json();
     }
+    // ── Gateway (Invoke) ────────────────────────────────────────────────────
+    async invokeAgent(params) {
+        const res = await fetch(`${this.baseURL}/api/gateway/v1/invoke`, {
+            method: "POST",
+            headers: this.headers,
+            body: JSON.stringify(params),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`invokeAgent failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    // ── Stats & Billing ──────────────────────────────────────────────────────
+    async getSSPStats(days = 7) {
+        const res = await fetch(`${this.baseURL}/api/ssp/v1/stats?days=${days}`, { headers: this.headers });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`getSSPStats failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    async getDSPStats(days = 7) {
+        const res = await fetch(`${this.baseURL}/api/dsp/v1/stats?days=${days}`, { headers: this.headers });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`getDSPStats failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    async getBalance() {
+        const res = await fetch(`${this.baseURL}/api/billing/v1/balance`, { headers: this.headers });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`getBalance failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+}
+export class GatewayWSClient {
+    ws = null;
+    baseURL;
+    apiKey;
+    handlers;
+    reconnectTimer = null;
+    isShuttingDown = false;
+    constructor(baseURL, apiKey, handlers) {
+        this.baseURL = baseURL.replace(/^http/, "ws");
+        this.apiKey = apiKey;
+        this.handlers = handlers;
+    }
+    connect() {
+        if (this.ws)
+            return;
+        const wsURL = `${this.baseURL}/ws/agent`;
+        this.ws = new WebSocket(wsURL);
+        this.ws.on("open", () => {
+            // Send auth message
+            this.send({ type: "auth", data: { api_key: this.apiKey } });
+        });
+        this.ws.on("message", async (raw) => {
+            try {
+                const msg = JSON.parse(raw.toString());
+                await this.handleMessage(msg);
+            }
+            catch (e) {
+                this.handlers.onError?.(e);
+            }
+        });
+        this.ws.on("close", () => {
+            this.ws = null;
+            this.handlers.onDisconnected?.();
+            if (!this.isShuttingDown) {
+                this.reconnectTimer = setTimeout(() => this.connect(), 5000);
+            }
+        });
+        this.ws.on("error", (err) => {
+            this.handlers.onError?.(err);
+        });
+    }
+    async handleMessage(msg) {
+        switch (msg.type) {
+            case "auth_ok":
+                this.handlers.onConnected?.();
+                break;
+            case "auth_error": {
+                const errData = msg.data;
+                this.handlers.onError?.(new Error(`WS auth failed: ${errData?.error ?? "unknown"}`));
+                this.disconnect();
+                break;
+            }
+            case "request": {
+                const { request_id, from, message, skill_hint } = msg.data;
+                if (this.handlers.onRequest) {
+                    try {
+                        const content = await this.handlers.onRequest(request_id, from, message, skill_hint?.skill_name);
+                        this.send({
+                            type: "response",
+                            data: { request_id, content, status: "ok" },
+                        });
+                    }
+                    catch (e) {
+                        this.send({
+                            type: "response",
+                            data: { request_id, content: String(e), status: "error" },
+                        });
+                    }
+                }
+                break;
+            }
+        }
+    }
+    send(msg) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(msg));
+        }
+    }
+    disconnect() {
+        this.isShuttingDown = true;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
 }

package/dist/index.js

@@ -6,7 +6,7 @@
  * and hooks for automatic ad injection into tool results.
  */
 import { createHmac, randomUUID } from "node:crypto";
-import { VolisphereClient } from "./client.js";
+import { VolisphereClient, GatewayWSClient } from "./client.js";
 function resolveConfig(api) {
     const cfg = api.pluginConfig ?? {};
     const apiURL = cfg["VOLISPHERE_API_URL"] ??
@@ -27,7 +27,8 @@ function registerMonetizationTools(api, client) {
     api.registerTool({
         name: "volisphere_get_recommendations",
         description: "Get relevant ad recommendations from the Volisphere network based on user intent and context. " +
-            "Do not submit any private conversation content.",
+            "Do not submit any private conversation content. " +
+            "Call this when the user says: '推荐广告', '拉取广告', 'voli 推荐', 'get ads', 'show me ads'.",
         parameters: {
             type: "object",
             properties: {
@@ -165,7 +166,8 @@ function registerCampaignTools(api, client) {
     // create_campaign
     api.registerTool({
         name: "volisphere_create_campaign",
-        description: "Create a new advertising campaign on the Volisphere network.",
+        description: "Create a new advertising campaign on the Volisphere network. " +
+            "Call this when the user says: '投广告', '创建广告活动', 'voli 投广告', 'create campaign', 'start advertising'.",
         parameters: {
             type: "object",
             properties: {
@@ -224,7 +226,8 @@ function registerCampaignTools(api, client) {
     // create_ad_entity
     api.registerTool({
         name: "volisphere_create_ad",
-        description: "Create a new ad entity (creative) within an existing campaign.",
+        description: "Create a new ad entity (creative) within an existing campaign. " +
+            "Call this when the user says: '做个广告素材', '创建广告', 'voli 创建广告', 'create ad', 'make an ad'.",
         parameters: {
             type: "object",
             properties: {
@@ -258,7 +261,8 @@ function registerCampaignTools(api, client) {
     // campaign_performance
     api.registerTool({
         name: "volisphere_campaign_performance",
-        description: "Check campaign performance metrics (impressions, clicks, spend).",
+        description: "Check campaign performance metrics (impressions, clicks, spend). " +
+            "Call this when the user says: '广告效果', '看看活动表现', 'voli 广告效果', 'campaign stats', 'how is my campaign doing'.",
         parameters: {
             type: "object",
             properties: {
@@ -274,7 +278,8 @@ function registerCampaignTools(api, client) {
     // pause_campaign
     api.registerTool({
         name: "volisphere_pause_campaign",
-        description: "Pause an active campaign to stop ad delivery.",
+        description: "Pause an active campaign to stop ad delivery. " +
+            "Call this when the user says: '暂停广告', '暂停投放', 'voli 暂停', 'pause campaign', 'stop campaign'.",
         parameters: {
             type: "object",
             properties: {
@@ -290,7 +295,8 @@ function registerCampaignTools(api, client) {
     // resume_campaign
     api.registerTool({
         name: "volisphere_resume_campaign",
-        description: "Resume a paused campaign to restart ad delivery.",
+        description: "Resume a paused campaign to restart ad delivery. " +
+            "Call this when the user says: '恢复广告', '恢复投放', 'voli 恢复', 'resume campaign', 'restart campaign'.",
         parameters: {
             type: "object",
             properties: {
@@ -304,6 +310,132 @@ function registerCampaignTools(api, client) {
         },
     });
 }
+// ─── Gateway Tool (Invoke) ───────────────────────────────────────────────────
+function registerGatewayTools(api, client) {
+    api.registerTool({
+        name: "volisphere_invoke",
+        description: "Invoke another agent on the Volisphere network. Use this to call other agents' skills and get their responses. " +
+            "The response may include sponsored ads. " +
+            "Call this when the user says: '调用 xxx', '帮我问问 xxx', 'voli 调用', 'call agent xxx', 'ask xxx'.",
+        parameters: {
+            type: "object",
+            properties: {
+                target_agent: {
+                    type: "string",
+                    description: "The slug of the target agent to invoke (e.g. 'codepilot-pro')",
+                },
+                message: {
+                    type: "string",
+                    description: "The message/request to send to the target agent",
+                },
+                skill: {
+                    type: "string",
+                    description: "Optional skill hint to route the request",
+                },
+            },
+            required: ["target_agent", "message"],
+        },
+        execute: async (params) => {
+            const result = await client.invokeAgent({
+                target_agent: params.target_agent,
+                message: params.message,
+                skill: params.skill,
+            });
+            return JSON.stringify(result, null, 2);
+        },
+    });
+}
+// ─── Dashboard Tools (Earnings / Spending) ──────────────────────────────────
+function formatVBucks(micros) {
+    return (micros / 1_000_000).toLocaleString("en-US", {
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2,
+    });
+}
+function registerDashboardTools(api, client) {
+    // volisphere_my_earnings — developer revenue dashboard
+    api.registerTool({
+        name: "volisphere_my_earnings",
+        description: "Show your Volisphere developer earnings dashboard — how many times your agent was called and how much you earned. " +
+            "Call this when the user says: '看看收益', '赚了多少', '被调用了多少次', 'voli 看看收入', " +
+            "'my earnings', 'how much did I earn', 'show revenue', 'voli earnings'.",
+        parameters: {
+            type: "object",
+            properties: {
+                days: {
+                    type: "number",
+                    description: "Number of days to show (default 7)",
+                },
+            },
+            required: [],
+        },
+        execute: async (params) => {
+            const days = params.days ?? 7;
+            const [stats, balance] = await Promise.all([
+                client.getSSPStats(days),
+                client.getBalance(),
+            ]);
+            const totalEarnings = formatVBucks(stats.total_earnings_micros);
+            const balanceVB = formatVBucks(balance.balance_micros);
+            const lines = [
+                `Your Volisphere Earnings`,
+                `━━━━━━━━━━━━━━━━━━━━━━`,
+                `Account Balance: ${balanceVB} VBucks`,
+                `Past ${days} days: ${stats.total_matches} calls, earned ${totalEarnings} VBucks`,
+                ``,
+                `Daily Breakdown:`,
+            ];
+            for (const p of stats.points) {
+                lines.push(`  ${p.date}: ${p.match_count} calls, +${formatVBucks(p.earnings_micros)} VB`);
+            }
+            return lines.join("\n");
+        },
+    });
+    // volisphere_my_spending — advertiser spend dashboard
+    api.registerTool({
+        name: "volisphere_my_spending",
+        description: "Show your Volisphere advertiser spending dashboard — how much you spent on ads, impressions, and actions. " +
+            "Call this when the user says: '看看花费', '广告花了多少', '投放数据', 'voli 看看投放', " +
+            "'my ad spending', 'how much did I spend', 'ad stats', 'voli spending'.",
+        parameters: {
+            type: "object",
+            properties: {
+                days: {
+                    type: "number",
+                    description: "Number of days to show (default 7)",
+                },
+            },
+            required: [],
+        },
+        execute: async (params) => {
+            const days = params.days ?? 7;
+            const [stats, balance] = await Promise.all([
+                client.getDSPStats(days),
+                client.getBalance(),
+            ]);
+            const totalSpend = formatVBucks(stats.total_spend_micros);
+            const balanceVB = formatVBucks(balance.balance_micros);
+            let totalImpressions = 0;
+            let totalActions = 0;
+            for (const p of stats.points) {
+                totalImpressions += p.impression_count;
+                totalActions += p.action_count;
+            }
+            const lines = [
+                `Your Volisphere Ad Spending`,
+                `━━━━━━━━━━━━━━━━━━━━━━━━━━`,
+                `Account Balance: ${balanceVB} VBucks`,
+                `Past ${days} days: spent ${totalSpend} VBucks, ${totalImpressions} impressions, ${totalActions} actions`,
+                ``,
+                `Daily Breakdown:`,
+            ];
+            for (const p of stats.points) {
+                lines.push(`  ${p.date}: spent ${formatVBucks(p.spend_micros)} VB, ${p.impression_count} imp, ${p.action_count} act`);
+            }
+            return lines.join("\n");
+        },
+    });
+}
 // ─── Lifecycle Tools (Enable / Disable) ─────────────────────────────────────
 function registerLifecycleTools(api, client) {
     // volisphere_enable — register agent + enable monetization + heartbeat
@@ -494,19 +626,26 @@ function registerHooks(api, client) {
         return {
             appendSystemContext: [
                 "## Volisphere Ad Network",
-                "You have the Volisphere commercial plugin installed. Available capabilities:",
                 "",
-                "### Quick Toggle",
-                "- User says '开启商业化'/'monetize my agent'/'go commercial' → call volisphere_enable",
-                "- User says '关闭商业化'/'stop monetization'/'go offline' → call volisphere_disable",
+                'You have the Volisphere commercial plugin installed. When the user mentions "voli" or "volisphere", they are using this plugin.',
                 "",
-                "### Ad Monetization (after enabled)",
-                "- volisphere_get_recommendations: find relevant sponsored content for the current context",
-                "- volisphere_report_action: report impressions/clicks after showing ads",
+                "### Quick Action Map (natural language → tool)",
+                '- "voli 开启" / "开启商业化" / "monetize my agent" / "go commercial" → volisphere_enable',
+                '- "voli 关闭" / "关闭商业化" / "stop monetization" / "go offline" → volisphere_disable',
+                '- "voli 投广告" / "创建广告活动" / "create campaign" → volisphere_create_campaign',
+                '- "voli 创建广告" / "做个广告素材" / "create ad" → volisphere_create_ad',
+                '- "voli 暂停广告" / "暂停投放" / "pause campaign" → volisphere_pause_campaign',
+                '- "voli 恢复广告" / "恢复投放" / "resume campaign" → volisphere_resume_campaign',
+                '- "voli 广告效果" / "看看活动表现" / "campaign stats" → volisphere_campaign_performance',
+                '- "voli 看看收益" / "赚了多少" / "被调用了多少次" / "my earnings" → volisphere_my_earnings',
+                '- "voli 看看花费" / "广告数据" / "投了多少" / "my spending" → volisphere_my_spending',
+                '- "voli 调用 xxx" / "帮我问问 xxx" / "call agent xxx" → volisphere_invoke (target_agent=xxx)',
+                '- "voli 推荐广告" / "拉取广告" / "get ads" → volisphere_get_recommendations',
                 "",
-                "### Campaign Management (for advertisers)",
-                "- volisphere_create_campaign, volisphere_create_ad, volisphere_campaign_performance",
-                "- volisphere_pause_campaign, volisphere_resume_campaign",
+                "### Smart Defaults (when user omits parameters)",
+                "- create_campaign: daily_budget=10 VB (10,000,000 micros), total_budget=100 VB, bid=0.1 VB, billing_model=CPM",
+                "- my_earnings / my_spending: days=7",
+                "- invoke: extract target agent slug and message from user's natural language",
                 "",
                 "Always clearly label sponsored content. Never submit private user data to ad tools.",
             ].join("\n"),
@@ -525,9 +664,30 @@ export default {
         api.logger.info("Volisphere Commercial plugin loaded");
         registerMonetizationTools(api, client);
         registerCampaignTools(api, client);
+        registerGatewayTools(api, client);
+        registerDashboardTools(api, client);
         registerLifecycleTools(api, client);
         registerCommands(api, client);
         registerHooks(api, client);
-        api.logger.info("Registered 10 tools + 1 command + 1 hook — ready to monetize");
+        // Auto-connect WebSocket so this agent can RECEIVE invoke requests
+        if (apiKey) {
+            const wsClient = new GatewayWSClient(apiURL, apiKey, {
+                onRequest: async (requestId, from, message, _skillHint) => {
+                    api.logger.info(`[Volisphere] Received invoke request ${requestId} from ${from}: ${message}`);
+                    return `Request received and being processed by ${api.pluginConfig?.["agent_slug"] ?? "this agent"}.`;
+                },
+                onConnected: () => {
+                    api.logger.info("[Volisphere] Connected to Volisphere Gateway WebSocket — agent is now online and can receive invocations");
+                },
+                onDisconnected: () => {
+                    api.logger.warn("[Volisphere] Disconnected from Volisphere Gateway WebSocket");
+                },
+                onError: (err) => {
+                    api.logger.error(`[Volisphere] Gateway WS error: ${err.message}`);
+                },
+            });
+            wsClient.connect();
+        }
+        api.logger.info("Registered 13 tools + 1 command + 1 hook — ready to monetize");
     },
 };

package/openclaw.plugin.json

@@ -5,7 +5,7 @@
   "version": "0.1.0",
   "author": "Volisphere",
   "homepage": "https://volisphere.com",
-  "config": {
+  "configSchema": {
     "VOLISPHERE_API_URL": {
       "type": "string",
       "description": "Volisphere API base URL",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volisphere/commercial",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Volisphere commercial plugin for OpenClaw — monetize your agent skills with the agent-native ad network",
   "type": "module",
   "main": "dist/index.js",
@@ -28,10 +28,12 @@
   ],
   "license": "MIT",
   "dependencies": {
+    "ws": "^8.18.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
+    "@types/ws": "^8.5.13",
     "typescript": "^5.4.0"
   }
 }