acn-client 0.2.1

package/dist/index.mjs

@@ -0,0 +1,587 @@
+// src/client.ts
+var ACNClient = class {
+  baseUrl;
+  timeout;
+  headers;
+  constructor(options) {
+    if (typeof options === "string") {
+      this.baseUrl = options.replace(/\/$/, "");
+      this.timeout = 3e4;
+      this.headers = {};
+    } else {
+      this.baseUrl = options.baseUrl.replace(/\/$/, "");
+      this.timeout = options.timeout ?? 3e4;
+      this.headers = options.headers ?? {};
+      if (options.apiKey) {
+        this.headers["X-API-Key"] = options.apiKey;
+      }
+    }
+  }
+  // ============================================
+  // Internal HTTP Methods
+  // ============================================
+  async request(method, path, options) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (options?.params) {
+      Object.entries(options.params).forEach(([key, value]) => {
+        if (value !== void 0) {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url.toString(), {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          ...this.headers
+        },
+        body: options?.body ? JSON.stringify(options.body) : void 0,
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({ message: response.statusText }));
+        throw new ACNError(response.status, error.detail || error.message || "Request failed");
+      }
+      if (response.status === 204) {
+        return void 0;
+      }
+      return response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  get(path, params) {
+    return this.request("GET", path, { params });
+  }
+  post(path, body) {
+    return this.request("POST", path, { body });
+  }
+  delete(path) {
+    return this.request("DELETE", path);
+  }
+  // ============================================
+  // Health & Status
+  // ============================================
+  /** Check if ACN server is healthy */
+  async health() {
+    return this.get("/health");
+  }
+  /** Get server statistics */
+  async getStats() {
+    return this.get("/api/v1/stats");
+  }
+  // ============================================
+  // Agent Management
+  // ============================================
+  /** Register a new agent */
+  async registerAgent(agent) {
+    return this.post("/api/v1/agents/register", agent);
+  }
+  /** Get agent by ID */
+  async getAgent(agentId) {
+    return this.get(`/api/v1/agents/${agentId}`);
+  }
+  /** Search agents (status: online | offline | all; public list does not include verification_code) */
+  async searchAgents(options) {
+    return this.get("/api/v1/agents", {
+      skill: options?.skills,
+      status: options?.status
+    });
+  }
+  /** Unregister an agent */
+  async unregisterAgent(agentId) {
+    return this.delete(`/api/v1/agents/${agentId}`);
+  }
+  /** Send agent heartbeat */
+  async heartbeat(agentId) {
+    return this.post(`/api/v1/agents/${agentId}/heartbeat`);
+  }
+  /** Get agent endpoint */
+  async getAgentEndpoint(agentId) {
+    return this.get(`/api/v1/agents/${agentId}/endpoint`);
+  }
+  /** List all available skills */
+  async getSkills() {
+    return this.get("/api/v1/skills");
+  }
+  // ============================================
+  // Subnet Management
+  // ============================================
+  /** Create a new subnet */
+  async createSubnet(request) {
+    return this.post("/api/v1/subnets", request);
+  }
+  /** List all subnets */
+  async listSubnets() {
+    return this.get("/api/v1/subnets");
+  }
+  /** Get subnet by ID */
+  async getSubnet(subnetId) {
+    return this.get(`/api/v1/subnets/${subnetId}`);
+  }
+  /** Delete a subnet */
+  async deleteSubnet(subnetId, force = false) {
+    return this.request("DELETE", `/api/v1/subnets/${subnetId}`, {
+      params: { force }
+    });
+  }
+  /** Get agents in a subnet */
+  async getSubnetAgents(subnetId) {
+    return this.get(`/api/v1/subnets/${subnetId}/agents`);
+  }
+  /** Join agent to subnet */
+  async joinSubnet(agentId, subnetId) {
+    return this.post(`/api/v1/agents/${agentId}/subnets/${subnetId}`);
+  }
+  /** Remove agent from subnet */
+  async leaveSubnet(agentId, subnetId) {
+    return this.delete(`/api/v1/agents/${agentId}/subnets/${subnetId}`);
+  }
+  /** Get agent's subnets */
+  async getAgentSubnets(agentId) {
+    return this.get(`/api/v1/agents/${agentId}/subnets`);
+  }
+  // ============================================
+  // Communication
+  // ============================================
+  /** Send message to an agent */
+  async sendMessage(request) {
+    return this.post("/api/v1/communication/send", request);
+  }
+  /** Broadcast message to multiple agents */
+  async broadcast(request) {
+    return this.post("/api/v1/communication/broadcast", request);
+  }
+  /** Broadcast message to agents with specific skill */
+  async broadcastBySkill(request) {
+    return this.post("/api/v1/communication/broadcast-by-skill", request);
+  }
+  /** Get message history for an agent */
+  async getMessageHistory(agentId, options) {
+    return this.get(`/api/v1/communication/history/${agentId}`, options);
+  }
+  // ============================================
+  // Payment Discovery
+  // ============================================
+  /** Set agent's payment capability */
+  async setPaymentCapability(agentId, capability) {
+    return this.post(`/api/v1/agents/${agentId}/payment-capability`, capability);
+  }
+  /** Get agent's payment capability */
+  async getPaymentCapability(agentId) {
+    return this.get(`/api/v1/agents/${agentId}/payment-capability`);
+  }
+  /** Discover agents that accept payments */
+  async discoverPaymentAgents(options) {
+    return this.get("/api/v1/payments/discover", {
+      method: options?.method,
+      network: options?.network,
+      min_amount: options?.min_amount,
+      max_amount: options?.max_amount
+    });
+  }
+  /** Get payment task by ID */
+  async getPaymentTask(taskId) {
+    return this.get(`/api/v1/payments/tasks/${taskId}`);
+  }
+  /** Get agent's payment tasks */
+  async getAgentPaymentTasks(agentId, options) {
+    return this.get(`/api/v1/payments/tasks/agent/${agentId}`, options);
+  }
+  /** Get agent's payment statistics */
+  async getPaymentStats(agentId) {
+    return this.get(`/api/v1/payments/stats/${agentId}`);
+  }
+  // ============================================
+  // Monitoring & Analytics
+  // ============================================
+  /** Get Prometheus metrics (text format) */
+  async getPrometheusMetrics() {
+    const response = await fetch(`${this.baseUrl}/metrics`);
+    return response.text();
+  }
+  /** Get all metrics */
+  async getMetrics() {
+    return this.get("/api/v1/monitoring/metrics");
+  }
+  /** Get system health */
+  async getSystemHealth() {
+    return this.get("/api/v1/monitoring/health");
+  }
+  /** Get dashboard data */
+  async getDashboard() {
+    return this.get("/api/v1/monitoring/dashboard");
+  }
+  /** Get agent analytics */
+  async getAgentAnalytics() {
+    return this.get("/api/v1/analytics/agents");
+  }
+  /** Get specific agent's activity */
+  async getAgentActivity(agentId, options) {
+    return this.get(`/api/v1/analytics/agents/${agentId}`, options);
+  }
+  /** Get message analytics */
+  async getMessageAnalytics() {
+    return this.get("/api/v1/analytics/messages");
+  }
+  /** Get latency analytics */
+  async getLatencyAnalytics() {
+    return this.get("/api/v1/analytics/latency");
+  }
+  /** Get subnet analytics */
+  async getSubnetAnalytics() {
+    return this.get("/api/v1/analytics/subnets");
+  }
+  // ============================================
+  // Audit
+  // ============================================
+  /** Get audit events */
+  async getAuditEvents(options) {
+    return this.get("/api/v1/audit/events", options);
+  }
+  /** Get recent audit events */
+  async getRecentAuditEvents(limit = 100) {
+    return this.get("/api/v1/audit/events/recent", { limit });
+  }
+  // ============================================
+  // ERC-8004 On-Chain Identity
+  // ============================================
+  /**
+   * Register the agent on ERC-8004 Identity Registry and bind to ACN.
+   *
+   * Full flow:
+   * 1. Generate wallet if privateKey is undefined (saved to saveWalletPath).
+   * 2. Construct agentURI → agent-registration.json endpoint.
+   * 3. Sign and broadcast register(agentURI) transaction via viem.
+   * 4. Extract token ID from Registered event.
+   * 5. POST /api/v1/onchain/agents/{agentId}/bind to inform ACN.
+   *
+   * @param agentId  - ACN agent ID (from join response).
+   * @param options  - Chain, RPC, private key, wallet save path.
+   */
+  async registerOnchain(agentId, options = {}) {
+    const {
+      chain = "base",
+      rpcUrl,
+      saveWalletPath = ".env"
+    } = options;
+    const { createWalletClient, createPublicClient, http } = await import("viem");
+    const { generatePrivateKey, privateKeyToAccount } = await import("viem/accounts");
+    const { base, baseSepolia } = await import("viem/chains");
+    const chainConfigs = {
+      base: {
+        viemChain: base,
+        identityContract: "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
+        namespace: "eip155:8453"
+      },
+      "base-sepolia": {
+        viemChain: baseSepolia,
+        identityContract: "0x8004A818BFB912233c491871b3d84c89A494BD9e",
+        namespace: "eip155:84532"
+      }
+    };
+    const cfg = chainConfigs[chain];
+    let walletGenerated = false;
+    let privateKey;
+    if (!options.privateKey) {
+      privateKey = generatePrivateKey();
+      walletGenerated = true;
+      if (saveWalletPath) {
+        await this._saveWalletToEnv(saveWalletPath, privateKey);
+      }
+    } else {
+      privateKey = options.privateKey;
+    }
+    const account = privateKeyToAccount(privateKey);
+    const agentRegistrationUrl = `${this.baseUrl}/api/v1/agents/${agentId}/.well-known/agent-registration.json`;
+    const abi = [
+      {
+        name: "register",
+        type: "function",
+        stateMutability: "nonpayable",
+        inputs: [{ type: "string", name: "agentURI" }],
+        outputs: [{ type: "uint256", name: "agentId" }]
+      },
+      {
+        name: "Registered",
+        type: "event",
+        inputs: [
+          { type: "uint256", name: "agentId", indexed: true },
+          { type: "string", name: "agentURI", indexed: false },
+          { type: "address", name: "owner", indexed: true }
+        ]
+      }
+    ];
+    const transport = http(rpcUrl ?? void 0);
+    const walletClient = createWalletClient({ account, chain: cfg.viemChain, transport });
+    const publicClient = createPublicClient({ chain: cfg.viemChain, transport });
+    const txHash = await walletClient.writeContract({
+      address: cfg.identityContract,
+      abi,
+      functionName: "register",
+      args: [agentRegistrationUrl]
+    });
+    const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash });
+    const { decodeEventLog } = await import("viem");
+    let tokenId;
+    for (const log of receipt.logs) {
+      try {
+        const decoded = decodeEventLog({ abi, data: log.data, topics: log.topics });
+        if (decoded.eventName === "Registered") {
+          tokenId = decoded.args.agentId;
+          break;
+        }
+      } catch {
+      }
+    }
+    if (tokenId === void 0) {
+      throw new Error("Registered event not found in transaction receipt");
+    }
+    await this.post(`/api/v1/onchain/agents/${agentId}/bind`, {
+      token_id: Number(tokenId),
+      chain: cfg.namespace,
+      tx_hash: txHash
+    });
+    return {
+      tokenId,
+      txHash,
+      chain: cfg.namespace,
+      agentRegistrationUrl,
+      walletAddress: account.address,
+      walletGenerated
+    };
+  }
+  /** @internal Save generated wallet credentials to a .env file. */
+  async _saveWalletToEnv(path, privateKey) {
+    if (typeof window !== "undefined") return;
+    try {
+      const fs = await import("fs/promises");
+      let content = "";
+      try {
+        content = await fs.readFile(path, "utf8");
+      } catch {
+      }
+      const existing = new Set(content.split("\n").map((l) => l.split("=")[0].trim()));
+      const toAdd = [];
+      if (!existing.has("WALLET_PRIVATE_KEY")) toAdd.push(`WALLET_PRIVATE_KEY=${privateKey}`);
+      if (toAdd.length) await fs.appendFile(path, "\n" + toAdd.join("\n") + "\n");
+    } catch {
+    }
+  }
+  /** Get audit statistics */
+  async getAuditStats(options) {
+    return this.get("/api/v1/audit/stats", options);
+  }
+};
+var ACNError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "ACNError";
+  }
+};
+
+// src/realtime.ts
+var ACNRealtime = class {
+  baseUrl;
+  options;
+  ws = null;
+  state = "disconnected";
+  reconnectAttempts = 0;
+  heartbeatTimer = null;
+  reconnectTimer = null;
+  channels = /* @__PURE__ */ new Map();
+  globalHandlers = /* @__PURE__ */ new Set();
+  stateHandlers = /* @__PURE__ */ new Set();
+  constructor(baseUrl, options) {
+    this.baseUrl = baseUrl.replace(/^http:/, "ws:").replace(/^https:/, "wss:").replace(/\/$/, "");
+    this.options = {
+      autoReconnect: options?.autoReconnect ?? true,
+      reconnectInterval: options?.reconnectInterval ?? 3e3,
+      maxReconnectAttempts: options?.maxReconnectAttempts ?? 10,
+      heartbeatInterval: options?.heartbeatInterval ?? 3e4
+    };
+  }
+  /** Current connection state */
+  get connectionState() {
+    return this.state;
+  }
+  /** Whether currently connected */
+  get isConnected() {
+    return this.state === "connected";
+  }
+  /**
+   * Connect to a channel
+   */
+  async connect(channel = "default") {
+    if (this.ws && this.state === "connected") {
+      return;
+    }
+    return new Promise((resolve, reject) => {
+      this.setState("connecting");
+      try {
+        this.ws = new WebSocket(`${this.baseUrl}/ws/${channel}`);
+        this.ws.onopen = () => {
+          this.setState("connected");
+          this.reconnectAttempts = 0;
+          this.startHeartbeat();
+          resolve();
+        };
+        this.ws.onclose = (event) => {
+          this.stopHeartbeat();
+          if (event.wasClean) {
+            this.setState("disconnected");
+          } else if (this.options.autoReconnect && this.reconnectAttempts < this.options.maxReconnectAttempts) {
+            this.scheduleReconnect(channel);
+          } else {
+            this.setState("disconnected");
+          }
+        };
+        this.ws.onerror = (error) => {
+          if (this.state === "connecting") {
+            reject(new Error("WebSocket connection failed"));
+          }
+          this.handleError(error);
+        };
+        this.ws.onmessage = (event) => {
+          this.handleMessage(event.data);
+        };
+      } catch (error) {
+        this.setState("disconnected");
+        reject(error);
+      }
+    });
+  }
+  /**
+   * Disconnect from server
+   */
+  disconnect() {
+    this.stopHeartbeat();
+    this.clearReconnectTimer();
+    if (this.ws) {
+      this.ws.close(1e3, "Client disconnect");
+      this.ws = null;
+    }
+    this.setState("disconnected");
+  }
+  /**
+   * Subscribe to a channel
+   */
+  subscribe(channel, handler) {
+    let handlers = this.channels.get(channel);
+    if (!handlers) {
+      handlers = /* @__PURE__ */ new Set();
+      this.channels.set(channel, handlers);
+    }
+    handlers.add(handler);
+    return () => {
+      handlers?.delete(handler);
+      if (handlers?.size === 0) {
+        this.channels.delete(channel);
+      }
+    };
+  }
+  /**
+   * Subscribe to all messages
+   */
+  onMessage(handler) {
+    this.globalHandlers.add(handler);
+    return () => {
+      this.globalHandlers.delete(handler);
+    };
+  }
+  /**
+   * Subscribe to state changes
+   */
+  onStateChange(handler) {
+    this.stateHandlers.add(handler);
+    return () => {
+      this.stateHandlers.delete(handler);
+    };
+  }
+  /**
+   * Send a message
+   */
+  send(message) {
+    if (!this.ws || this.state !== "connected") {
+      throw new Error("WebSocket not connected");
+    }
+    this.ws.send(JSON.stringify(message));
+  }
+  // ============================================
+  // Private Methods
+  // ============================================
+  setState(state) {
+    this.state = state;
+    this.stateHandlers.forEach((handler) => handler(state));
+  }
+  handleMessage(data) {
+    try {
+      const message = JSON.parse(data);
+      this.globalHandlers.forEach((handler) => handler(message));
+      const channelHandlers = this.channels.get(message.channel);
+      if (channelHandlers) {
+        channelHandlers.forEach((handler) => handler(message));
+      }
+      const typeHandlers = this.channels.get(message.type);
+      if (typeHandlers) {
+        typeHandlers.forEach((handler) => handler(message));
+      }
+    } catch (error) {
+      console.error("Failed to parse WebSocket message:", error);
+    }
+  }
+  handleError(error) {
+    console.error("WebSocket error:", error);
+  }
+  startHeartbeat() {
+    this.stopHeartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      if (this.ws && this.state === "connected") {
+        this.send({ type: "ping", timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+      }
+    }, this.options.heartbeatInterval);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  scheduleReconnect(channel) {
+    this.clearReconnectTimer();
+    this.setState("reconnecting");
+    this.reconnectAttempts++;
+    const delay = this.options.reconnectInterval * Math.min(this.reconnectAttempts, 5);
+    this.reconnectTimer = setTimeout(() => {
+      this.connect(channel).catch(() => {
+      });
+    }, delay);
+  }
+  clearReconnectTimer() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+};
+function subscribeToACN(baseUrl, channel, handler) {
+  const realtime = new ACNRealtime(baseUrl);
+  const unsubscribe = realtime.subscribe(channel, handler);
+  realtime.connect(channel).catch((error) => {
+    console.error("Failed to connect to ACN:", error);
+  });
+  return () => {
+    unsubscribe();
+    realtime.disconnect();
+  };
+}
+export {
+  ACNClient,
+  ACNError,
+  ACNRealtime,
+  subscribeToACN
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "acn-client",
+  "version": "0.2.1",
+  "description": "Official TypeScript/JavaScript client for ACN (Agent Collaboration Network)",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "acn",
+    "agent",
+    "ai",
+    "collaboration",
+    "a2a",
+    "websocket",
+    "sdk"
+  ],
+  "author": "acnlabs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/acnlabs/ACN.git",
+    "directory": "clients/typescript"
+  },
+  "homepage": "https://github.com/acnlabs/ACN#readme",
+  "bugs": {
+    "url": "https://github.com/acnlabs/ACN/issues"
+  },
+  "dependencies": {
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=4.7.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}
+