@analytix402/openclaw-skill 0.1.0

package/SKILL.md

@@ -0,0 +1,47 @@
+# Analytix402
+
+Monitor, control, and optimize your AI agent's API spend and LLM costs in real-time.
+
+## Description
+
+Analytix402 gives your OpenClaw agent financial visibility and guardrails. Track every API call, LLM invocation, and x402 payment your agent makes. Set budget limits, detect duplicate purchases, and get alerts before costs spiral.
+
+**What it does:**
+- Tracks all outbound API calls and x402 payments automatically
+- Monitors LLM token usage and costs across OpenAI, Anthropic, and other providers
+- Enforces daily budget limits and per-call spend caps
+- Detects duplicate API purchases to prevent waste
+- Sends heartbeats so you know your agent is alive and healthy
+- Provides a real-time dashboard at analytix402.com
+
+## Configuration
+
+```yaml
+# Required
+ANALYTIX402_API_KEY: ax_live_your_key_here
+
+# Optional
+ANALYTIX402_AGENT_ID: my-openclaw-agent
+ANALYTIX402_BASE_URL: https://analytix402.com
+ANALYTIX402_DAILY_BUDGET: 50.00
+ANALYTIX402_PER_CALL_LIMIT: 5.00
+ANALYTIX402_TRACK_LLM: true
+```
+
+## Tools
+
+### analytix402_spend_report
+Get a summary of your agent's spend — total cost, breakdown by API and LLM provider, and efficiency score.
+
+### analytix402_set_budget
+Set or update the daily budget limit for this agent session.
+
+### analytix402_check_budget
+Check remaining budget before making an expensive API call.
+
+### analytix402_flag_purchase
+Flag a potential duplicate or unnecessary purchase for review.
+
+## Tags
+
+monitoring, analytics, budget, x402, payments, observability, cost-tracking

package/dist/index.d.mts

@@ -0,0 +1,60 @@
+/**
+ * Analytix402 OpenClaw Skill
+ *
+ * Provides AI agent spend tracking, budget enforcement,
+ * and observability for OpenClaw agents.
+ *
+ * Integrates with the Analytix402 platform to give operators
+ * real-time visibility into what their agents are spending.
+ */
+declare function analytix402_spend_report(): Promise<string>;
+interface SetBudgetParams {
+    daily_limit?: number;
+    per_call_limit?: number;
+}
+declare function analytix402_set_budget(params: SetBudgetParams): string;
+interface CheckBudgetParams {
+    estimated_cost?: number;
+}
+declare function analytix402_check_budget(params: CheckBudgetParams): string;
+interface FlagPurchaseParams {
+    url: string;
+    reason?: string;
+    estimated_cost?: number;
+}
+declare function analytix402_flag_purchase(params: FlagPurchaseParams): string;
+/**
+ * Call this after any LLM invocation to track usage.
+ * OpenClaw skills can hook into the agent lifecycle.
+ */
+declare function trackLLMCall(params: {
+    model: string;
+    provider: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd?: number;
+    durationMs?: number;
+    taskId?: string;
+}): void;
+/**
+ * Call this after any API call to track spend.
+ */
+declare function trackAPICall(params: {
+    method: string;
+    url: string;
+    statusCode: number;
+    responseTimeMs: number;
+    paymentAmount?: number;
+    paymentCurrency?: string;
+    txHash?: string;
+}): void;
+/**
+ * Send a heartbeat — call periodically to show agent is alive.
+ */
+declare function sendHeartbeat(status?: 'healthy' | 'degraded' | 'error'): void;
+/**
+ * Gracefully shutdown — flush all pending events.
+ */
+declare function shutdown(): Promise<void>;
+
+export { type CheckBudgetParams, type FlagPurchaseParams, type SetBudgetParams, analytix402_check_budget, analytix402_flag_purchase, analytix402_set_budget, analytix402_spend_report, sendHeartbeat, shutdown, trackAPICall, trackLLMCall };

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Analytix402 OpenClaw Skill
+ *
+ * Provides AI agent spend tracking, budget enforcement,
+ * and observability for OpenClaw agents.
+ *
+ * Integrates with the Analytix402 platform to give operators
+ * real-time visibility into what their agents are spending.
+ */
+declare function analytix402_spend_report(): Promise<string>;
+interface SetBudgetParams {
+    daily_limit?: number;
+    per_call_limit?: number;
+}
+declare function analytix402_set_budget(params: SetBudgetParams): string;
+interface CheckBudgetParams {
+    estimated_cost?: number;
+}
+declare function analytix402_check_budget(params: CheckBudgetParams): string;
+interface FlagPurchaseParams {
+    url: string;
+    reason?: string;
+    estimated_cost?: number;
+}
+declare function analytix402_flag_purchase(params: FlagPurchaseParams): string;
+/**
+ * Call this after any LLM invocation to track usage.
+ * OpenClaw skills can hook into the agent lifecycle.
+ */
+declare function trackLLMCall(params: {
+    model: string;
+    provider: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd?: number;
+    durationMs?: number;
+    taskId?: string;
+}): void;
+/**
+ * Call this after any API call to track spend.
+ */
+declare function trackAPICall(params: {
+    method: string;
+    url: string;
+    statusCode: number;
+    responseTimeMs: number;
+    paymentAmount?: number;
+    paymentCurrency?: string;
+    txHash?: string;
+}): void;
+/**
+ * Send a heartbeat — call periodically to show agent is alive.
+ */
+declare function sendHeartbeat(status?: 'healthy' | 'degraded' | 'error'): void;
+/**
+ * Gracefully shutdown — flush all pending events.
+ */
+declare function shutdown(): Promise<void>;
+
+export { type CheckBudgetParams, type FlagPurchaseParams, type SetBudgetParams, analytix402_check_budget, analytix402_flag_purchase, analytix402_set_budget, analytix402_spend_report, sendHeartbeat, shutdown, trackAPICall, trackLLMCall };

package/dist/index.js

@@ -0,0 +1,480 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  analytix402_check_budget: () => analytix402_check_budget,
+  analytix402_flag_purchase: () => analytix402_flag_purchase,
+  analytix402_set_budget: () => analytix402_set_budget,
+  analytix402_spend_report: () => analytix402_spend_report,
+  sendHeartbeat: () => sendHeartbeat,
+  shutdown: () => shutdown,
+  trackAPICall: () => trackAPICall,
+  trackLLMCall: () => trackLLMCall
+});
+module.exports = __toCommonJS(index_exports);
+
+// ../sdk/src/client.ts
+var SDK_NAME = "@analytix402/sdk";
+var SDK_VERSION = "0.1.1";
+var DEFAULT_CONFIG = {
+  baseUrl: "https://analytix402.com",
+  debug: false,
+  batchSize: 100,
+  flushInterval: 5e3,
+  maxRetries: 3,
+  maxQueueSize: 1e3,
+  timeout: 1e4,
+  excludePaths: ["/health", "/healthz", "/ready", "/metrics", "/favicon.ico"]
+};
+function createClient(config) {
+  if (!config.apiKey) {
+    throw new Error("Analytix402: apiKey is required");
+  }
+  if (!config.apiKey.startsWith("ax_live_") && !config.apiKey.startsWith("ax_test_")) {
+    console.warn("Analytix402: API key should start with ax_live_ or ax_test_");
+  }
+  const cfg = {
+    ...DEFAULT_CONFIG,
+    ...config
+  };
+  const agentId = cfg.agentId;
+  const queue = [];
+  let flushTimer = null;
+  let isFlushing = false;
+  let isShutdown = false;
+  const log = (...args) => {
+    if (cfg.debug) {
+      console.log("[Analytix402]", ...args);
+    }
+  };
+  const warn = (...args) => {
+    console.warn("[Analytix402]", ...args);
+  };
+  function enqueue(event) {
+    if (isShutdown) {
+      warn("Client is shutdown, event dropped");
+      return;
+    }
+    if (queue.length >= cfg.maxQueueSize) {
+      warn(`Queue full (${cfg.maxQueueSize}), dropping oldest event`);
+      queue.shift();
+    }
+    queue.push({
+      event,
+      attempts: 0,
+      addedAt: Date.now()
+    });
+    log(`Event queued (${queue.length} in queue)`);
+    if (queue.length >= cfg.batchSize) {
+      log("Batch size reached, flushing");
+      flush();
+    } else if (!flushTimer) {
+      flushTimer = setTimeout(() => {
+        flushTimer = null;
+        flush();
+      }, cfg.flushInterval);
+    }
+  }
+  function track(event) {
+    if (agentId && !event.agentId) {
+      event.agentId = agentId;
+    }
+    enqueue(event);
+  }
+  function heartbeat(status = "healthy", metadata) {
+    if (!agentId) {
+      warn("heartbeat() requires agentId in config");
+      return;
+    }
+    const event = {
+      type: "heartbeat",
+      agentId,
+      status,
+      metadata,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    enqueue(event);
+  }
+  function reportOutcome(taskId, success, options) {
+    const event = {
+      type: "task_outcome",
+      agentId,
+      taskId,
+      success,
+      durationMs: options == null ? void 0 : options.durationMs,
+      cost: options == null ? void 0 : options.cost,
+      metadata: options == null ? void 0 : options.metadata,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    enqueue(event);
+  }
+  function startTask(taskId) {
+    const id = taskId || `task_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+    const startTime = Date.now();
+    return {
+      taskId: id,
+      end(success, metadata) {
+        const durationMs = Date.now() - startTime;
+        reportOutcome(id, success, { durationMs, metadata });
+      }
+    };
+  }
+  function trackLLM(usage) {
+    const event = {
+      type: "llm_usage",
+      agentId,
+      taskId: usage.taskId,
+      model: usage.model,
+      provider: usage.provider,
+      inputTokens: usage.inputTokens,
+      outputTokens: usage.outputTokens,
+      totalTokens: usage.inputTokens + usage.outputTokens,
+      costUsd: usage.costUsd,
+      durationMs: usage.durationMs,
+      metadata: usage.metadata,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    enqueue(event);
+  }
+  async function sendBatch(events) {
+    if (events.length === 0) return true;
+    const payload = {
+      events,
+      sdk: {
+        name: SDK_NAME,
+        version: SDK_VERSION
+      },
+      sentAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), cfg.timeout);
+      const response = await fetch(`${cfg.baseUrl}/api/ingest/batch`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": cfg.apiKey,
+          "User-Agent": `${SDK_NAME}/${SDK_VERSION}`
+        },
+        body: JSON.stringify(payload),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const text = await response.text().catch(() => "Unknown error");
+        throw new Error(`HTTP ${response.status}: ${text}`);
+      }
+      log(`Sent ${events.length} events successfully`);
+      return true;
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        warn("Request timed out");
+      } else {
+        warn("Failed to send events:", error);
+      }
+      return false;
+    }
+  }
+  async function flush() {
+    if (isFlushing || queue.length === 0) {
+      return;
+    }
+    isFlushing = true;
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    const batch = queue.splice(0, cfg.batchSize);
+    const events = batch.map((q) => q.event);
+    log(`Flushing ${events.length} events`);
+    const success = await sendBatch(events);
+    if (!success) {
+      const retriable = batch.filter((q) => q.attempts < cfg.maxRetries);
+      if (retriable.length > 0) {
+        log(`Re-queuing ${retriable.length} events for retry`);
+        for (const item of retriable.reverse()) {
+          item.attempts++;
+          queue.unshift(item);
+        }
+        const backoff = Math.min(1e3 * Math.pow(2, retriable[0].attempts), 3e4);
+        log(`Retry scheduled in ${backoff}ms`);
+        flushTimer = setTimeout(() => {
+          flushTimer = null;
+          flush();
+        }, backoff);
+      } else {
+        warn(`Dropped ${batch.length} events after ${cfg.maxRetries} retries`);
+      }
+    }
+    isFlushing = false;
+    if (queue.length > 0 && !flushTimer) {
+      flushTimer = setTimeout(() => {
+        flushTimer = null;
+        flush();
+      }, cfg.flushInterval);
+    }
+  }
+  async function shutdown2() {
+    log("Shutting down...");
+    isShutdown = true;
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    if (queue.length > 0) {
+      log(`Flushing ${queue.length} remaining events`);
+      isFlushing = false;
+      await flush();
+    }
+    log("Shutdown complete");
+  }
+  if (typeof process !== "undefined") {
+    const handleExit = () => {
+      shutdown2().catch(console.error);
+    };
+    process.on("beforeExit", handleExit);
+    process.on("SIGINT", handleExit);
+    process.on("SIGTERM", handleExit);
+  }
+  return {
+    track,
+    flush,
+    shutdown: shutdown2,
+    heartbeat,
+    reportOutcome,
+    startTask,
+    trackLLM
+  };
+}
+
+// src/index.ts
+var API_KEY = process.env.ANALYTIX402_API_KEY || "";
+var BASE_URL = (process.env.ANALYTIX402_BASE_URL || "https://analytix402.com").replace(/\/$/, "");
+var AGENT_ID = process.env.ANALYTIX402_AGENT_ID || `openclaw-${Date.now()}`;
+var AGENT_NAME = process.env.ANALYTIX402_AGENT_NAME || "OpenClaw Agent";
+var DAILY_BUDGET = parseFloat(process.env.ANALYTIX402_DAILY_BUDGET || "0") || 0;
+var PER_CALL_LIMIT = parseFloat(process.env.ANALYTIX402_PER_CALL_LIMIT || "0") || 0;
+var TRACK_LLM = process.env.ANALYTIX402_TRACK_LLM !== "false";
+var client = null;
+var sessionSpend = 0;
+var sessionCalls = 0;
+var dailySpend = 0;
+var dailySpendDate = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+function getClient() {
+  if (!client) {
+    if (!API_KEY) {
+      throw new Error(
+        "ANALYTIX402_API_KEY is not set. Add it to your OpenClaw skill config."
+      );
+    }
+    client = createClient({
+      apiKey: API_KEY,
+      baseUrl: BASE_URL,
+      agentId: AGENT_ID,
+      agentName: AGENT_NAME
+    });
+  }
+  return client;
+}
+async function apiRequest(method, path, body) {
+  const url = `${BASE_URL}/api${path}`;
+  const headers = {
+    "Content-Type": "application/json",
+    "Authorization": `Bearer ${API_KEY}`,
+    "X-API-Key": API_KEY
+  };
+  const opts = { method, headers };
+  if (body && method !== "GET") {
+    opts.body = JSON.stringify(body);
+  }
+  const res = await fetch(url, opts);
+  const text = await res.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = { raw: text };
+  }
+  if (!res.ok) {
+    throw new Error(`Analytix402 API ${res.status}: ${data.error || text}`);
+  }
+  return data;
+}
+async function analytix402_spend_report() {
+  const c = getClient();
+  c.heartbeat("healthy", { sessionCalls, sessionSpend });
+  try {
+    const overview = await apiRequest("GET", "/agents/overview");
+    const insights = await apiRequest("GET", "/agents/insights");
+    return JSON.stringify({
+      session: {
+        totalCalls: sessionCalls,
+        totalSpend: `$${sessionSpend.toFixed(4)}`,
+        dailySpend: `$${dailySpend.toFixed(4)}`,
+        dailyBudget: DAILY_BUDGET > 0 ? `$${DAILY_BUDGET.toFixed(2)}` : "unlimited",
+        budgetRemaining: DAILY_BUDGET > 0 ? `$${(DAILY_BUDGET - dailySpend).toFixed(4)}` : "unlimited"
+      },
+      platform: overview,
+      insights
+    }, null, 2);
+  } catch (error) {
+    return JSON.stringify({
+      session: {
+        totalCalls: sessionCalls,
+        totalSpend: `$${sessionSpend.toFixed(4)}`,
+        dailySpend: `$${dailySpend.toFixed(4)}`,
+        dailyBudget: DAILY_BUDGET > 0 ? `$${DAILY_BUDGET.toFixed(2)}` : "unlimited"
+      },
+      error: error instanceof Error ? error.message : String(error)
+    }, null, 2);
+  }
+}
+function analytix402_set_budget(params) {
+  const updates = [];
+  if (params.daily_limit !== void 0 && params.daily_limit >= 0) {
+    Object.defineProperty(globalThis, "__ax402_daily_budget", {
+      value: params.daily_limit,
+      writable: true,
+      configurable: true
+    });
+    updates.push(`Daily budget set to $${params.daily_limit.toFixed(2)}`);
+  }
+  if (params.per_call_limit !== void 0 && params.per_call_limit >= 0) {
+    Object.defineProperty(globalThis, "__ax402_per_call_limit", {
+      value: params.per_call_limit,
+      writable: true,
+      configurable: true
+    });
+    updates.push(`Per-call limit set to $${params.per_call_limit.toFixed(2)}`);
+  }
+  if (updates.length === 0) {
+    return "No budget parameters provided. Use daily_limit and/or per_call_limit.";
+  }
+  return updates.join(". ") + ".";
+}
+function analytix402_check_budget(params) {
+  const budget = DAILY_BUDGET || globalThis.__ax402_daily_budget || 0;
+  const callLimit = PER_CALL_LIMIT || globalThis.__ax402_per_call_limit || 0;
+  const estimated = params.estimated_cost || 0;
+  const remaining = budget > 0 ? budget - dailySpend : Infinity;
+  const allowed = (budget === 0 || remaining >= estimated) && (callLimit === 0 || estimated <= callLimit);
+  return JSON.stringify({
+    allowed,
+    dailyBudget: budget > 0 ? `$${budget.toFixed(2)}` : "unlimited",
+    dailySpent: `$${dailySpend.toFixed(4)}`,
+    remaining: budget > 0 ? `$${remaining.toFixed(4)}` : "unlimited",
+    estimatedCost: `$${estimated.toFixed(4)}`,
+    perCallLimit: callLimit > 0 ? `$${callLimit.toFixed(2)}` : "unlimited",
+    withinPerCallLimit: callLimit === 0 || estimated <= callLimit,
+    withinDailyBudget: budget === 0 || remaining >= estimated
+  }, null, 2);
+}
+function analytix402_flag_purchase(params) {
+  const c = getClient();
+  c.track({
+    type: "request",
+    method: "FLAG",
+    path: params.url,
+    endpoint: params.url,
+    statusCode: 0,
+    responseTimeMs: 0,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    agentId: AGENT_ID,
+    metadata: {
+      flagged: true,
+      reason: params.reason || "Potential duplicate or unnecessary purchase",
+      estimatedCost: params.estimated_cost
+    }
+  });
+  return `Flagged: ${params.url} \u2014 ${params.reason || "potential duplicate purchase"}. This will appear in your Analytix402 dashboard for review.`;
+}
+function trackLLMCall(params) {
+  if (!TRACK_LLM) return;
+  const c = getClient();
+  const cost = params.costUsd || 0;
+  c.trackLLM({
+    model: params.model,
+    provider: params.provider,
+    inputTokens: params.inputTokens,
+    outputTokens: params.outputTokens,
+    costUsd: params.costUsd,
+    durationMs: params.durationMs,
+    taskId: params.taskId
+  });
+  sessionSpend += cost;
+  sessionCalls += 1;
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  if (today !== dailySpendDate) {
+    dailySpend = 0;
+  }
+  dailySpend += cost;
+}
+function trackAPICall(params) {
+  const c = getClient();
+  const payment = params.paymentAmount ? {
+    amount: String(params.paymentAmount),
+    currency: params.paymentCurrency || "USDC",
+    wallet: "",
+    status: "success",
+    txHash: params.txHash
+  } : void 0;
+  c.track({
+    type: "request",
+    method: params.method,
+    path: params.url,
+    endpoint: params.url,
+    statusCode: params.statusCode,
+    responseTimeMs: params.responseTimeMs,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    agentId: AGENT_ID,
+    payment
+  });
+  if (params.paymentAmount) {
+    sessionSpend += params.paymentAmount;
+    dailySpend += params.paymentAmount;
+  }
+  sessionCalls += 1;
+}
+function sendHeartbeat(status = "healthy") {
+  const c = getClient();
+  c.heartbeat(status, {
+    sessionCalls,
+    sessionSpend,
+    dailySpend,
+    uptime: process.uptime()
+  });
+}
+async function shutdown() {
+  if (client) {
+    await client.shutdown();
+    client = null;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  analytix402_check_budget,
+  analytix402_flag_purchase,
+  analytix402_set_budget,
+  analytix402_spend_report,
+  sendHeartbeat,
+  shutdown,
+  trackAPICall,
+  trackLLMCall
+});