acn-client 0.6.2 → 0.7.1

package/dist/index.js

@@ -33,6 +33,7 @@ __export(index_exports, {
   ACNClient: () => ACNClient,
   ACNError: () => ACNError,
   ACNRealtime: () => ACNRealtime,
+  KNOWN_PAYMENT_TASK_STATUSES: () => KNOWN_PAYMENT_TASK_STATUSES,
   subscribeToACN: () => subscribeToACN
 });
 module.exports = __toCommonJS(index_exports);
@@ -81,8 +82,32 @@ var ACNClient = class {
         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");
+        let body = {};
+        try {
+          const parsed = await response.json();
+          if (parsed && typeof parsed === "object") body = parsed;
+        } catch {
+        }
+        let message;
+        const rawDetail = body.detail;
+        if (typeof rawDetail === "string") {
+          message = rawDetail;
+        } else if (Array.isArray(rawDetail) && rawDetail.length > 0) {
+          message = rawDetail.slice(0, 5).map((item) => {
+            if (item && typeof item === "object") {
+              const i = item;
+              const loc = Array.isArray(i.loc) ? i.loc.slice(1).join(".") : "";
+              const msg = String(i.msg ?? i.type ?? item);
+              return loc ? `${loc}: ${msg}` : msg;
+            }
+            return String(item);
+          }).join("; ");
+        } else {
+          message = String(body.message ?? response.statusText ?? `HTTP ${response.status}`);
+        }
+        const errorCode = typeof body.error === "string" ? body.error : void 0;
+        const requestId = typeof body.request_id === "string" ? body.request_id : response.headers.get("X-Request-ID") ?? void 0;
+        throw new ACNError(response.status, message, { errorCode, requestId });
       }
       if (response.status === 204) {
         return void 0;
@@ -185,11 +210,9 @@ var ACNClient = class {
   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 }
-    });
+  /** Delete a subnet you own (requires Agent API Key — only the owning agent can delete) */
+  async deleteSubnet(subnetId) {
+    return this.request("DELETE", `/api/v1/subnets/${subnetId}`);
   }
   /** Get agents in a subnet */
   async getSubnetAgents(subnetId) {
@@ -413,32 +436,82 @@ var ACNClient = class {
   // ============================================
   // Payment Discovery
   // ============================================
-  /** Set agent's payment capability */
+  /** Set agent's payment capability (requires Agent API Key) */
   async setPaymentCapability(agentId, capability) {
-    return this.post(`/api/v1/agents/${agentId}/payment-capability`, capability);
+    return this.post(`/api/v1/payments/${agentId}/payment-capability`, capability);
   }
-  /** Get agent's payment capability */
+  /**
+   * Get agent's payment capability (requires Agent API Key).
+   *
+   * The ACN server returns this resource using the internal
+   * `ap2.core.PaymentCapability` shape, which calls the methods list
+   * `payment_methods`.  We rewrite it to the request-shaped name
+   * `supported_methods` here so callers see the same field on read
+   * and on write.
+   */
   async getPaymentCapability(agentId) {
-    return this.get(`/api/v1/agents/${agentId}/payment-capability`);
+    const raw = await this.get(
+      `/api/v1/payments/${agentId}/payment-capability`
+    );
+    if (!raw) return null;
+    if (Array.isArray(raw.payment_methods) && raw.supported_methods === void 0) {
+      raw.supported_methods = raw.payment_methods;
+    }
+    return raw;
+  }
+  /** Set OpenAI-style per-million-token pricing in USD (requires Agent API Key) */
+  async setTokenPricing(agentId, pricing) {
+    return this.post(`/api/v1/payments/${agentId}/token-pricing`, pricing);
   }
-  /** Discover agents that accept payments */
+  /** Get an agent's per-million-token pricing (requires Agent API Key) */
+  async getTokenPricing(agentId) {
+    return this.get(`/api/v1/payments/${agentId}/token-pricing`);
+  }
+  /** Discover agents that accept payments. Filters by lowercase method/network. */
   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
+      network: options?.network
+    });
+  }
+  /**
+   * Create a payment task (requires Agent API Key).
+   *
+   * `from_agent` must equal the authenticated agent — the server rejects
+   * spoofed payers with `from_agent_mismatch`. `payment_method` and
+   * `network` use ACN lowercase values (e.g. `'usdc'`, `'base'`).
+   */
+  async createPaymentTask(request) {
+    return this.post("/api/v1/payments/tasks", request);
+  }
+  /**
+   * Estimate the cost of calling an agent before invoking its service.
+   *
+   * Returns `{ agent_id, estimate, note }` where `estimate` includes
+   * `total_usd`, `network_fee_usd`, `agent_income_usd` and credit
+   * equivalents derived from the target agent's token-pricing.
+   */
+  async estimateCost(request) {
+    return this.post("/api/v1/payments/billing/estimate", {
+      agent_id: request.agent_id,
+      estimated_input_tokens: request.estimated_input_tokens ?? 0,
+      estimated_output_tokens: request.estimated_output_tokens ?? 0
     });
   }
-  /** Get payment task by ID */
+  /**
+   * Get a payment task by ID.
+   *
+   * Note: `GET /payments/tasks/{task_id}` requires the ACN backend's
+   * internal token; agents typically use `getAgentPaymentTasks` instead.
+   */
   async getPaymentTask(taskId) {
     return this.get(`/api/v1/payments/tasks/${taskId}`);
   }
-  /** Get agent's payment tasks */
+  /** Get the payment tasks an agent is involved in (requires Agent API Key). */
   async getAgentPaymentTasks(agentId, options) {
     return this.get(`/api/v1/payments/tasks/agent/${agentId}`, options);
   }
-  /** Get agent's payment statistics */
+  /** Get an agent's payment statistics (requires Agent API Key). */
   async getPaymentStats(agentId) {
     return this.get(`/api/v1/payments/stats/${agentId}`);
   }
@@ -622,13 +695,116 @@ var ACNClient = class {
   async getAuditStats(options) {
     return this.get("/api/v1/audit/stats", options);
   }
+  // ============================================
+  // Social Graph (Follow)
+  // ============================================
+  /**
+   * Follow another agent.
+   *
+   * Idempotent — re-following returns `changed: false`.
+   * @param agentId   The follower (must match the authenticated agent).
+   * @param targetId  The agent to follow.
+   */
+  async follow(agentId, targetId) {
+    return this.post(`/api/v1/agents/${agentId}/follows/${targetId}`);
+  }
+  /**
+   * Unfollow an agent.
+   *
+   * Idempotent — unfollowing a non-followed agent returns `changed: false`.
+   * @param agentId   The follower (must match the authenticated agent).
+   * @param targetId  The agent to unfollow.
+   */
+  async unfollow(agentId, targetId) {
+    return this.delete(`/api/v1/agents/${agentId}/follows/${targetId}`);
+  }
+  /**
+   * Check whether `agentId` is following `targetId` (public endpoint).
+   */
+  async checkFollow(agentId, targetId) {
+    return this.get(`/api/v1/agents/${agentId}/follows/${targetId}`);
+  }
+  /**
+   * List agents that `agentId` follows (public endpoint).
+   */
+  async listFollows(agentId, options) {
+    return this.get(`/api/v1/agents/${agentId}/follows`, options);
+  }
+  /**
+   * List agents that follow `agentId` (public endpoint).
+   */
+  async listFollowers(agentId, options) {
+    return this.get(`/api/v1/agents/${agentId}/followers`, options);
+  }
+  // ============================================
+  // Communication Policy
+  // ============================================
+  /**
+   * Get the authenticated agent's current communication policy (owner only).
+   */
+  async getPolicy(agentId) {
+    return this.get(`/api/v1/agents/${agentId}/policy`);
+  }
+  /**
+   * Update the agent's inbound communication policy (owner only).
+   *
+   * @param agentId       Must match the authenticated agent.
+   * @param mode          `open` | `closed` | `manifest` | `allowlist`
+   * @param rejectReason  Optional message shown to rejected senders (closed mode).
+   */
+  async updatePolicy(agentId, mode, rejectReason) {
+    const policy = { mode };
+    if (rejectReason !== void 0) policy.reject_reason = rejectReason;
+    return this.request("PATCH", `/api/v1/agents/${agentId}/policy`, {
+      body: { communication_policy: policy }
+    });
+  }
+  // ============================================
+  // Allowlist
+  // ============================================
+  /**
+   * Add an agent to the allowlist (owner only).
+   *
+   * Only effective when `communication_policy.mode = 'allowlist'`.
+   * Idempotent — re-adding returns `changed: false`.
+   *
+   * @param agentId   Must match the authenticated agent.
+   * @param targetId  Agent to trust.
+   * @param reason    Optional free-form note (≤ 200 chars).
+   */
+  async addToAllowlist(agentId, targetId, reason) {
+    return this.post(
+      `/api/v1/agents/${agentId}/allowlist/${targetId}`,
+      reason !== void 0 ? { reason } : void 0
+    );
+  }
+  /**
+   * Remove an agent from the allowlist (owner only).
+   *
+   * Idempotent — removing a non-member returns `changed: false`.
+   */
+  async removeFromAllowlist(agentId, targetId) {
+    return this.delete(`/api/v1/agents/${agentId}/allowlist/${targetId}`);
+  }
+  /**
+   * List the authenticated agent's allowlist (owner only).
+   */
+  async listAllowlist(agentId, options) {
+    return this.get(`/api/v1/agents/${agentId}/allowlist`, options);
+  }
 };
 var ACNError = class extends Error {
-  constructor(status, message) {
+  constructor(status, message, options) {
     super(message);
     this.status = status;
     this.name = "ACNError";
+    this.errorCode = options?.errorCode;
+    this.requestId = options?.requestId;
   }
+  /** ACN internal error code (present on sanitised 5xx responses) */
+  errorCode;
+  /** Request ID minted by ACN for 5xx responses (useful for support) */
+  requestId;
 };
 
 // src/realtime.ts
@@ -826,10 +1002,28 @@ function subscribeToACN(baseUrl, channel, handler) {
     realtime.disconnect();
   };
 }
+
+// src/types.ts
+var KNOWN_PAYMENT_TASK_STATUSES = [
+  "created",
+  "payment_requested",
+  "payment_pending",
+  "payment_confirmed",
+  "task_in_progress",
+  "task_completed",
+  "payment_released",
+  "in_progress",
+  "disputed",
+  "cancelled",
+  "failed",
+  "payment_failed",
+  "refunded"
+];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ACNClient,
   ACNError,
   ACNRealtime,
+  KNOWN_PAYMENT_TASK_STATUSES,
   subscribeToACN
 });

package/dist/index.mjs

@@ -42,8 +42,32 @@ var ACNClient = class {
         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");
+        let body = {};
+        try {
+          const parsed = await response.json();
+          if (parsed && typeof parsed === "object") body = parsed;
+        } catch {
+        }
+        let message;
+        const rawDetail = body.detail;
+        if (typeof rawDetail === "string") {
+          message = rawDetail;
+        } else if (Array.isArray(rawDetail) && rawDetail.length > 0) {
+          message = rawDetail.slice(0, 5).map((item) => {
+            if (item && typeof item === "object") {
+              const i = item;
+              const loc = Array.isArray(i.loc) ? i.loc.slice(1).join(".") : "";
+              const msg = String(i.msg ?? i.type ?? item);
+              return loc ? `${loc}: ${msg}` : msg;
+            }
+            return String(item);
+          }).join("; ");
+        } else {
+          message = String(body.message ?? response.statusText ?? `HTTP ${response.status}`);
+        }
+        const errorCode = typeof body.error === "string" ? body.error : void 0;
+        const requestId = typeof body.request_id === "string" ? body.request_id : response.headers.get("X-Request-ID") ?? void 0;
+        throw new ACNError(response.status, message, { errorCode, requestId });
       }
       if (response.status === 204) {
         return void 0;
@@ -146,11 +170,9 @@ var ACNClient = class {
   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 }
-    });
+  /** Delete a subnet you own (requires Agent API Key — only the owning agent can delete) */
+  async deleteSubnet(subnetId) {
+    return this.request("DELETE", `/api/v1/subnets/${subnetId}`);
   }
   /** Get agents in a subnet */
   async getSubnetAgents(subnetId) {
@@ -374,32 +396,82 @@ var ACNClient = class {
   // ============================================
   // Payment Discovery
   // ============================================
-  /** Set agent's payment capability */
+  /** Set agent's payment capability (requires Agent API Key) */
   async setPaymentCapability(agentId, capability) {
-    return this.post(`/api/v1/agents/${agentId}/payment-capability`, capability);
+    return this.post(`/api/v1/payments/${agentId}/payment-capability`, capability);
   }
-  /** Get agent's payment capability */
+  /**
+   * Get agent's payment capability (requires Agent API Key).
+   *
+   * The ACN server returns this resource using the internal
+   * `ap2.core.PaymentCapability` shape, which calls the methods list
+   * `payment_methods`.  We rewrite it to the request-shaped name
+   * `supported_methods` here so callers see the same field on read
+   * and on write.
+   */
   async getPaymentCapability(agentId) {
-    return this.get(`/api/v1/agents/${agentId}/payment-capability`);
+    const raw = await this.get(
+      `/api/v1/payments/${agentId}/payment-capability`
+    );
+    if (!raw) return null;
+    if (Array.isArray(raw.payment_methods) && raw.supported_methods === void 0) {
+      raw.supported_methods = raw.payment_methods;
+    }
+    return raw;
+  }
+  /** Set OpenAI-style per-million-token pricing in USD (requires Agent API Key) */
+  async setTokenPricing(agentId, pricing) {
+    return this.post(`/api/v1/payments/${agentId}/token-pricing`, pricing);
   }
-  /** Discover agents that accept payments */
+  /** Get an agent's per-million-token pricing (requires Agent API Key) */
+  async getTokenPricing(agentId) {
+    return this.get(`/api/v1/payments/${agentId}/token-pricing`);
+  }
+  /** Discover agents that accept payments. Filters by lowercase method/network. */
   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
+      network: options?.network
+    });
+  }
+  /**
+   * Create a payment task (requires Agent API Key).
+   *
+   * `from_agent` must equal the authenticated agent — the server rejects
+   * spoofed payers with `from_agent_mismatch`. `payment_method` and
+   * `network` use ACN lowercase values (e.g. `'usdc'`, `'base'`).
+   */
+  async createPaymentTask(request) {
+    return this.post("/api/v1/payments/tasks", request);
+  }
+  /**
+   * Estimate the cost of calling an agent before invoking its service.
+   *
+   * Returns `{ agent_id, estimate, note }` where `estimate` includes
+   * `total_usd`, `network_fee_usd`, `agent_income_usd` and credit
+   * equivalents derived from the target agent's token-pricing.
+   */
+  async estimateCost(request) {
+    return this.post("/api/v1/payments/billing/estimate", {
+      agent_id: request.agent_id,
+      estimated_input_tokens: request.estimated_input_tokens ?? 0,
+      estimated_output_tokens: request.estimated_output_tokens ?? 0
     });
   }
-  /** Get payment task by ID */
+  /**
+   * Get a payment task by ID.
+   *
+   * Note: `GET /payments/tasks/{task_id}` requires the ACN backend's
+   * internal token; agents typically use `getAgentPaymentTasks` instead.
+   */
   async getPaymentTask(taskId) {
     return this.get(`/api/v1/payments/tasks/${taskId}`);
   }
-  /** Get agent's payment tasks */
+  /** Get the payment tasks an agent is involved in (requires Agent API Key). */
   async getAgentPaymentTasks(agentId, options) {
     return this.get(`/api/v1/payments/tasks/agent/${agentId}`, options);
   }
-  /** Get agent's payment statistics */
+  /** Get an agent's payment statistics (requires Agent API Key). */
   async getPaymentStats(agentId) {
     return this.get(`/api/v1/payments/stats/${agentId}`);
   }
@@ -583,13 +655,116 @@ var ACNClient = class {
   async getAuditStats(options) {
     return this.get("/api/v1/audit/stats", options);
   }
+  // ============================================
+  // Social Graph (Follow)
+  // ============================================
+  /**
+   * Follow another agent.
+   *
+   * Idempotent — re-following returns `changed: false`.
+   * @param agentId   The follower (must match the authenticated agent).
+   * @param targetId  The agent to follow.
+   */
+  async follow(agentId, targetId) {
+    return this.post(`/api/v1/agents/${agentId}/follows/${targetId}`);
+  }
+  /**
+   * Unfollow an agent.
+   *
+   * Idempotent — unfollowing a non-followed agent returns `changed: false`.
+   * @param agentId   The follower (must match the authenticated agent).
+   * @param targetId  The agent to unfollow.
+   */
+  async unfollow(agentId, targetId) {
+    return this.delete(`/api/v1/agents/${agentId}/follows/${targetId}`);
+  }
+  /**
+   * Check whether `agentId` is following `targetId` (public endpoint).
+   */
+  async checkFollow(agentId, targetId) {
+    return this.get(`/api/v1/agents/${agentId}/follows/${targetId}`);
+  }
+  /**
+   * List agents that `agentId` follows (public endpoint).
+   */
+  async listFollows(agentId, options) {
+    return this.get(`/api/v1/agents/${agentId}/follows`, options);
+  }
+  /**
+   * List agents that follow `agentId` (public endpoint).
+   */
+  async listFollowers(agentId, options) {
+    return this.get(`/api/v1/agents/${agentId}/followers`, options);
+  }
+  // ============================================
+  // Communication Policy
+  // ============================================
+  /**
+   * Get the authenticated agent's current communication policy (owner only).
+   */
+  async getPolicy(agentId) {
+    return this.get(`/api/v1/agents/${agentId}/policy`);
+  }
+  /**
+   * Update the agent's inbound communication policy (owner only).
+   *
+   * @param agentId       Must match the authenticated agent.
+   * @param mode          `open` | `closed` | `manifest` | `allowlist`
+   * @param rejectReason  Optional message shown to rejected senders (closed mode).
+   */
+  async updatePolicy(agentId, mode, rejectReason) {
+    const policy = { mode };
+    if (rejectReason !== void 0) policy.reject_reason = rejectReason;
+    return this.request("PATCH", `/api/v1/agents/${agentId}/policy`, {
+      body: { communication_policy: policy }
+    });
+  }
+  // ============================================
+  // Allowlist
+  // ============================================
+  /**
+   * Add an agent to the allowlist (owner only).
+   *
+   * Only effective when `communication_policy.mode = 'allowlist'`.
+   * Idempotent — re-adding returns `changed: false`.
+   *
+   * @param agentId   Must match the authenticated agent.
+   * @param targetId  Agent to trust.
+   * @param reason    Optional free-form note (≤ 200 chars).
+   */
+  async addToAllowlist(agentId, targetId, reason) {
+    return this.post(
+      `/api/v1/agents/${agentId}/allowlist/${targetId}`,
+      reason !== void 0 ? { reason } : void 0
+    );
+  }
+  /**
+   * Remove an agent from the allowlist (owner only).
+   *
+   * Idempotent — removing a non-member returns `changed: false`.
+   */
+  async removeFromAllowlist(agentId, targetId) {
+    return this.delete(`/api/v1/agents/${agentId}/allowlist/${targetId}`);
+  }
+  /**
+   * List the authenticated agent's allowlist (owner only).
+   */
+  async listAllowlist(agentId, options) {
+    return this.get(`/api/v1/agents/${agentId}/allowlist`, options);
+  }
 };
 var ACNError = class extends Error {
-  constructor(status, message) {
+  constructor(status, message, options) {
     super(message);
     this.status = status;
     this.name = "ACNError";
+    this.errorCode = options?.errorCode;
+    this.requestId = options?.requestId;
   }
+  /** ACN internal error code (present on sanitised 5xx responses) */
+  errorCode;
+  /** Request ID minted by ACN for 5xx responses (useful for support) */
+  requestId;
 };
 
 // src/realtime.ts
@@ -787,9 +962,27 @@ function subscribeToACN(baseUrl, channel, handler) {
     realtime.disconnect();
   };
 }
+
+// src/types.ts
+var KNOWN_PAYMENT_TASK_STATUSES = [
+  "created",
+  "payment_requested",
+  "payment_pending",
+  "payment_confirmed",
+  "task_in_progress",
+  "task_completed",
+  "payment_released",
+  "in_progress",
+  "disputed",
+  "cancelled",
+  "failed",
+  "payment_failed",
+  "refunded"
+];
 export {
   ACNClient,
   ACNError,
   ACNRealtime,
+  KNOWN_PAYMENT_TASK_STATUSES,
   subscribeToACN
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acn-client",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "description": "Official TypeScript/JavaScript client for ACN (Agent Collaboration Network)",
   "main": "dist/index.js",
   "module": "dist/index.mjs",