@volisphere/commercial 0.2.0 → 0.3.0

package/dist/client.d.ts

@@ -63,14 +63,14 @@ export interface SkillConfig {
 }
 export interface CampaignParams {
     name: string;
+    billing: "cpi" | "cpr" | "cpa";
     daily_budget_micros: number;
     total_budget_micros: number;
-    bid_micros: number;
-    billing_model: "CPM" | "CPC" | "CPA";
-    categories: string[];
+    default_bid_micros: number;
+    start_at: string;
+    end_at?: string;
+    intent_categories: string[];
     scenes: string[];
-    start_date?: string;
-    end_date?: string;
 }
 export interface Campaign {
     id: string;
@@ -91,11 +91,40 @@ export interface Campaign {
     updated_at: string;
 }
 export interface AdEntitySchema {
-    title: string;
-    description: string;
-    call_to_action: string;
-    landing_url: string;
-    image_url?: string;
+    schema_version: string;
+    identity: {
+        name: string;
+        provider: string;
+        entity_type: string;
+    };
+    capability: {
+        format: string;
+        placement: string[];
+    };
+    specs: {
+        intent_categories: string[];
+        scenes: string[];
+        regions: string[];
+        budget_ranges: string[];
+    };
+    actions: Array<{
+        label: string;
+        endpoint: string;
+        type: string;
+    }>;
+    trust: {
+        verified: boolean;
+    };
+    ad_meta: {
+        billing: string;
+        bid_micros: number;
+    };
+    render: {
+        headline: string;
+        short_desc: string;
+        image_url?: string;
+        call_to_action: string;
+    };
 }
 export interface AdEntity {
     id: string;
@@ -135,6 +164,7 @@ export interface RegisterAgentResponse {
     };
     claim_token: string;
     claim_url: string;
+    api_key: string;
 }
 export interface AgentProfile {
     id: string;
@@ -187,6 +217,7 @@ export declare class VolisphereClient {
     private apiKey;
     constructor(baseURL: string, apiKey: string);
     get apiKeyValue(): string;
+    setApiKey(key: string): void;
     private get headers();
     getRecommendations(params: GetRecommendationsParams): Promise<GetRecommendationsResponse>;
     reportAction(params: ReportActionParams): Promise<ReportActionResponse>;
@@ -204,8 +235,16 @@ export declare class VolisphereClient {
     getDSPStats(days?: number): Promise<StatsResponse>;
     getBalance(): Promise<BalanceResponse>;
 }
+export interface EarningsNotification {
+    amount: number;
+    currency: string;
+    ad_title?: string;
+    caller_name: string;
+    timestamp: string;
+}
 export interface WSEventHandlers {
     onRequest?: (requestId: string, from: string, message: string, skillHint?: string) => Promise<string>;
+    onEarnings?: (earnings: EarningsNotification) => void;
     onConnected?: () => void;
     onDisconnected?: () => void;
     onError?: (error: Error) => void;

package/dist/client.js

@@ -10,6 +10,9 @@ export class VolisphereClient {
     get apiKeyValue() {
         return this.apiKey;
     }
+    setApiKey(key) {
+        this.apiKey = key;
+    }
     get headers() {
         return {
             "Content-Type": "application/json",
@@ -69,7 +72,7 @@ export class VolisphereClient {
         const res = await fetch(`${this.baseURL}/api/dsp/v1/campaigns/${campaignId}/ad-entities`, {
             method: "POST",
             headers: this.headers,
-            body: JSON.stringify(schema),
+            body: JSON.stringify({ schema }),
         });
         if (!res.ok) {
             const text = await res.text();
@@ -224,6 +227,11 @@ export class GatewayWSClient {
                 this.disconnect();
                 break;
             }
+            case "earnings_notification": {
+                const earnings = msg.data;
+                this.handlers.onEarnings?.(earnings);
+                break;
+            }
             case "request": {
                 const { request_id, from, message, skill_hint } = msg.data;
                 if (this.handlers.onRequest) {

package/dist/index.js

@@ -6,18 +6,52 @@
  * and hooks for automatic ad injection into tool results.
  */
 import { createHmac, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { VolisphereClient, GatewayWSClient } from "./client.js";
+// ─── Credential File Persistence ────────────────────────────────────────────
+const CREDENTIALS_DIR = join(homedir(), ".volisphere");
+const CREDENTIALS_FILE = join(CREDENTIALS_DIR, "credentials.json");
+function loadSavedCredentials() {
+    try {
+        if (!existsSync(CREDENTIALS_FILE))
+            return null;
+        const raw = readFileSync(CREDENTIALS_FILE, "utf-8");
+        const data = JSON.parse(raw);
+        if (data.api_key && data.api_url) {
+            return data;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function saveCredentials(creds) {
+    try {
+        if (!existsSync(CREDENTIALS_DIR)) {
+            mkdirSync(CREDENTIALS_DIR, { recursive: true });
+        }
+        writeFileSync(CREDENTIALS_FILE, JSON.stringify(creds, null, 2), "utf-8");
+    }
+    catch {
+        // Best-effort — if we can't save, user will need to re-register next session
+    }
+}
 function resolveConfig(api) {
     const cfg = api.pluginConfig ?? {};
+    const saved = loadSavedCredentials();
     const apiURL = cfg["VOLISPHERE_API_URL"] ??
         process.env.VOLISPHERE_API_URL ??
+        saved?.api_url ??
         "https://api.volisphere.com";
     const apiKey = cfg["VOLISPHERE_API_KEY"] ??
         process.env.VOLISPHERE_API_KEY ??
+        saved?.api_key ??
         "";
     if (!apiKey) {
-        api.logger.warn("VOLISPHERE_API_KEY not set — Volisphere tools will fail. " +
-            "Set it in plugin config or VOLISPHERE_API_KEY env var.");
+        api.logger.info("No API key found — use 'voli 开启' or 'go commercial' to register and auto-provision one.");
     }
     return { apiURL, apiKey };
 }
@@ -180,19 +214,19 @@ function registerCampaignTools(api, client) {
                     type: "number",
                     description: "Total budget in micros",
                 },
-                bid_micros: {
+                default_bid_micros: {
                     type: "number",
                     description: "Bid per impression in micros",
                 },
-                billing_model: {
+                billing: {
                     type: "string",
-                    enum: ["CPM", "CPC", "CPA"],
-                    description: "Billing model",
+                    enum: ["cpi", "cpr", "cpa"],
+                    description: "Billing model: cpi (per impression), cpr (per response), cpa (per action)",
                 },
-                categories: {
+                intent_categories: {
                     type: "array",
                     items: { type: "string" },
-                    description: "Target categories",
+                    description: "Target categories (e.g. 'software-development', 'marketing')",
                 },
                 scenes: {
                     type: "array",
@@ -204,9 +238,9 @@ function registerCampaignTools(api, client) {
                 "name",
                 "daily_budget_micros",
                 "total_budget_micros",
-                "bid_micros",
-                "billing_model",
-                "categories",
+                "default_bid_micros",
+                "billing",
+                "intent_categories",
                 "scenes",
             ],
         },
@@ -215,10 +249,11 @@ function registerCampaignTools(api, client) {
                 name: params.name,
                 daily_budget_micros: params.daily_budget_micros,
                 total_budget_micros: params.total_budget_micros,
-                bid_micros: params.bid_micros,
-                billing_model: params.billing_model,
-                categories: params.categories,
+                default_bid_micros: params.default_bid_micros,
+                billing: params.billing,
+                intent_categories: params.intent_categories,
                 scenes: params.scenes,
+                start_at: new Date().toISOString(),
             });
             return JSON.stringify(result, null, 2);
         },
@@ -249,12 +284,45 @@ function registerCampaignTools(api, client) {
             ],
         },
         execute: async (params) => {
-            const result = await client.createAdEntity(params.campaign_id, {
-                title: params.title,
-                description: params.description,
-                call_to_action: params.call_to_action,
-                landing_url: params.landing_url,
-            });
+            const schema = {
+                schema_version: "1.0",
+                identity: {
+                    name: params.title,
+                    provider: "volisphere",
+                    entity_type: "banner",
+                },
+                capability: {
+                    format: "text",
+                    placement: ["inline"],
+                },
+                specs: {
+                    intent_categories: [],
+                    scenes: [],
+                    regions: [],
+                    budget_ranges: [],
+                },
+                actions: [
+                    {
+                        label: params.call_to_action,
+                        endpoint: params.landing_url,
+                        type: "link",
+                    },
+                ],
+                trust: {
+                    verified: false,
+                },
+                ad_meta: {
+                    billing: "cpi",
+                    bid_micros: 100000,
+                },
+                render: {
+                    headline: params.title,
+                    short_desc: params.description,
+                    image_url: "",
+                    call_to_action: params.call_to_action,
+                },
+            };
+            const result = await client.createAdEntity(params.campaign_id, schema);
             return JSON.stringify(result, null, 2);
         },
     });
@@ -437,7 +505,7 @@ function registerDashboardTools(api, client) {
     });
 }
 // ─── Lifecycle Tools (Enable / Disable) ─────────────────────────────────────
-function registerLifecycleTools(api, client) {
+function registerLifecycleTools(api, client, apiURL) {
     // volisphere_enable — register agent + enable monetization + heartbeat
     api.registerTool({
         name: "volisphere_enable",
@@ -477,7 +545,7 @@ function registerLifecycleTools(api, client) {
             required: ["slug", "display_name"],
         },
         execute: async (params) => {
-            // Step 1: Register agent
+            // Step 1: Register agent (public endpoint, no auth needed)
             const reg = await client.registerAgent({
                 slug: params.slug,
                 display_name: params.display_name,
@@ -485,20 +553,55 @@ function registerLifecycleTools(api, client) {
                 skills: params.skills,
             });
             const agentId = reg.agent.id;
-            // Step 2: Enable monetization
+            // Step 2: Auto-provision API key — save to local file + update client
+            if (reg.api_key) {
+                client.setApiKey(reg.api_key);
+                saveCredentials({
+                    api_key: reg.api_key,
+                    api_url: apiURL,
+                    agent_id: agentId,
+                    slug: reg.agent.slug,
+                });
+                api.logger.info(`[Volisphere] API key auto-provisioned and saved to ${CREDENTIALS_FILE}`);
+            }
+            // Step 3: Enable monetization (now using the provisioned key)
             try {
                 await client.setMonetization(agentId, true);
             }
             catch {
                 // May fail if no JWT — agent was registered publicly
             }
-            // Step 3: Heartbeat (go online)
+            // Step 4: Heartbeat (go online)
             try {
                 await client.heartbeat(agentId);
             }
             catch {
                 // Non-critical
             }
+            // Step 5: Auto-connect WebSocket so agent can receive invocations
+            if (reg.api_key) {
+                const wsClient = new GatewayWSClient(apiURL, reg.api_key, {
+                    onRequest: async (requestId, from, message) => {
+                        api.logger.info(`[Volisphere] Received invoke request ${requestId} from ${from}: ${message}`);
+                        return `Request received and being processed by ${reg.agent.slug}.`;
+                    },
+                    onEarnings: (earnings) => {
+                        const vbucks = (earnings.amount / 1_000_000).toFixed(2);
+                        api.logger.info(`[Volisphere] Earned ${vbucks} ${earnings.currency} from ${earnings.caller_name}` +
+                            (earnings.ad_title ? ` (ad: ${earnings.ad_title})` : ""));
+                    },
+                    onConnected: () => {
+                        api.logger.info("[Volisphere] Connected to Gateway WebSocket — agent is now online");
+                    },
+                    onDisconnected: () => {
+                        api.logger.warn("[Volisphere] Disconnected from Gateway WebSocket");
+                    },
+                    onError: (err) => {
+                        api.logger.error(`[Volisphere] Gateway WS error: ${err.message}`);
+                    },
+                });
+                wsClient.connect();
+            }
             return JSON.stringify({
                 status: "enabled",
                 agent_id: agentId,
@@ -506,6 +609,7 @@ function registerLifecycleTools(api, client) {
                 display_name: reg.agent.display_name,
                 claim_token: reg.claim_token,
                 message: "Agent registered and commercial features enabled. " +
+                    "API key auto-provisioned — no manual configuration needed. " +
                     "Your agent is now online and can receive ad recommendations and invocations.",
             }, null, 2);
         },
@@ -643,7 +747,7 @@ function registerHooks(api, client) {
                 '- "voli 推荐广告" / "拉取广告" / "get ads" → volisphere_get_recommendations',
                 "",
                 "### 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",
+                "- create_campaign: daily_budget=10 VB (10,000,000 micros), total_budget=100 VB, default_bid=0.1 VB, billing=cpi, start_at=now",
                 "- my_earnings / my_spending: days=7",
                 "- invoke: extract target agent slug and message from user's natural language",
                 "",
@@ -654,7 +758,7 @@ function registerHooks(api, client) {
 }
 // ─── Entry Point ────────────────────────────────────────────────────────────
 export default {
-    id: "volisphere-commercial",
+    id: "commercial",
     name: "Volisphere Commercial",
     description: "Monetize your OpenClaw agent with the Volisphere ad network",
     version: "0.1.0",
@@ -666,7 +770,7 @@ export default {
         registerCampaignTools(api, client);
         registerGatewayTools(api, client);
         registerDashboardTools(api, client);
-        registerLifecycleTools(api, client);
+        registerLifecycleTools(api, client, apiURL);
         registerCommands(api, client);
         registerHooks(api, client);
         // Auto-connect WebSocket so this agent can RECEIVE invoke requests
@@ -676,6 +780,11 @@ export default {
                     api.logger.info(`[Volisphere] Received invoke request ${requestId} from ${from}: ${message}`);
                     return `Request received and being processed by ${api.pluginConfig?.["agent_slug"] ?? "this agent"}.`;
                 },
+                onEarnings: (earnings) => {
+                    const vbucks = (earnings.amount / 1_000_000).toFixed(2);
+                    api.logger.info(`[Volisphere] Earned ${vbucks} ${earnings.currency} from ${earnings.caller_name}` +
+                        (earnings.ad_title ? ` (ad: ${earnings.ad_title})` : ""));
+                },
                 onConnected: () => {
                     api.logger.info("[Volisphere] Connected to Volisphere Gateway WebSocket — agent is now online and can receive invocations");
                 },

package/openclaw.plugin.json

@@ -1,5 +1,5 @@
 {
-  "id": "volisphere-commercial",
+  "id": "commercial",
   "name": "Volisphere Commercial",
   "description": "Monetize your OpenClaw agent with the Volisphere ad network. Provides tools for ad recommendations, action reporting, and campaign management.",
   "version": "0.1.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volisphere/commercial",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Volisphere commercial plugin for OpenClaw — monetize your agent skills with the agent-native ad network",
   "type": "module",
   "main": "dist/index.js",