acn-client 0.6.2 → 0.7.1

package/dist/index.d.ts

@@ -329,50 +329,100 @@ interface PendingSessionsResponse {
     count: number;
     sessions: SessionEntry[];
 }
-/** Supported payment methods */
-type PaymentMethod = 'USDC' | 'USDT' | 'ETH' | 'DAI' | 'CREDIT_CARD' | 'BANK_TRANSFER' | 'PLATFORM_CREDITS';
-/** Supported networks */
-type PaymentNetwork = 'ETHEREUM' | 'POLYGON' | 'BASE' | 'ARBITRUM' | 'OPTIMISM' | 'SOLANA';
-/** Payment capability */
+/**
+ * Supported payment methods.
+ *
+ * Values aligned with ACN server `SupportedPaymentMethod` (lowercase).
+ */
+type PaymentMethod = 'credit_card' | 'debit_card' | 'bank_transfer' | 'paypal' | 'apple_pay' | 'google_pay' | 'usdc' | 'usdt' | 'dai' | 'eth' | 'btc' | 'platform_credits';
+/**
+ * Supported networks.
+ *
+ * Values aligned with ACN server `SupportedNetwork` (lowercase).
+ */
+type PaymentNetwork = 'ethereum' | 'base' | 'arbitrum' | 'optimism' | 'polygon' | 'solana' | 'bitcoin';
+/**
+ * Payment capability — aligned with ACN `PaymentCapabilityRequest`.
+ *
+ * Used both as the body for `setPaymentCapability` and the response
+ * shape of `getPaymentCapability`.
+ */
 interface PaymentCapability {
-    accepts_payment: boolean;
-    wallet_address?: string;
     supported_methods: PaymentMethod[];
     supported_networks: PaymentNetwork[];
-    min_amount?: number;
-    max_amount?: number;
-    currency?: string;
+    /** Legacy single-address field; prefer `wallet_addresses`. */
+    wallet_address?: string;
+    /** Per-network wallet addresses, e.g. `{ ethereum: '0x...', base: '0x...' }`. */
+    wallet_addresses?: Record<string, string>;
+    accepts_payment?: boolean;
+    /**
+     * Token-based pricing payload, e.g.
+     * `{ input_price_per_million: 2.5, output_price_per_million: 10.0, currency: 'USD' }`.
+     */
+    token_pricing?: Record<string, unknown> | null;
+    api_endpoint?: string;
+    webhook_url?: string;
 }
-/** Payment task status */
-type PaymentTaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
-/** Payment task */
+/**
+ * Known ACN payment task status values.
+ *
+ * `PaymentTask.status` is typed as `string` rather than this union so the
+ * SDK does not need a release whenever the server adds a state. Compare
+ * against these constants when branching on status.
+ */
+declare const KNOWN_PAYMENT_TASK_STATUSES: readonly ["created", "payment_requested", "payment_pending", "payment_confirmed", "task_in_progress", "task_completed", "payment_released", "in_progress", "disputed", "cancelled", "failed", "payment_failed", "refunded"];
+type PaymentTaskStatus = (typeof KNOWN_PAYMENT_TASK_STATUSES)[number];
+/** Payment task — aligned with ACN server `PaymentTask` (ap2.core). */
 interface PaymentTask {
-    id: string;
-    payer_agent_id: string;
-    payee_agent_id: string;
-    amount: number;
-    currency: string;
-    method: PaymentMethod;
-    network?: PaymentNetwork;
-    status: PaymentTaskStatus;
+    task_id: string;
+    payment_id?: string | null;
+    buyer_agent: string;
+    seller_agent: string;
+    task_description: string;
+    task_type?: string | null;
+    task_metadata?: Record<string, unknown>;
+    /** Decimal amount as a string (matches server contract). */
+    amount: string;
+    currency?: string;
+    payment_method?: PaymentMethod | null;
+    network?: PaymentNetwork | null;
+    recipient_wallet?: string | null;
+    /** A `KNOWN_PAYMENT_TASK_STATUSES` value, but typed wide for forward-compat. */
+    status: string;
     created_at: string;
-    updated_at: string;
-    transaction_hash?: string;
-    metadata?: Record<string, unknown>;
+    payment_requested_at?: string | null;
+    payment_confirmed_at?: string | null;
+    task_completed_at?: string | null;
+    payment_released_at?: string | null;
+    tx_hash?: string | null;
+    dispute?: Record<string, unknown> | null;
 }
-/** Payment discovery options */
+/** Payment discovery options. */
 interface PaymentDiscoveryOptions {
     method?: PaymentMethod;
     network?: PaymentNetwork;
-    min_amount?: number;
-    max_amount?: number;
 }
-/** Payment statistics */
+/**
+ * Per-role aggregate within {@link PaymentStats} (`as_buyer` / `as_seller`).
+ *
+ * `total_amount` is a decimal string (matches server contract).
+ */
+interface PaymentRoleStats {
+    count: number;
+    total_amount: string;
+}
+/**
+ * Payment statistics — aligned with `PaymentTaskManager.get_payment_stats`.
+ *
+ * The server aggregates per-status counts plus per-role (buyer/seller)
+ * totals as decimal strings, rather than flat received/sent floats.
+ */
 interface PaymentStats {
-    total_received: number;
-    total_sent: number;
-    transaction_count: number;
-    avg_amount: number;
+    total_tasks: number;
+    as_buyer: PaymentRoleStats;
+    as_seller: PaymentRoleStats;
+    by_status: Record<string, number>;
+    completed_transactions: number;
 }
 /** System health */
 interface SystemHealth {
@@ -489,6 +539,53 @@ interface ApiResponse<T> {
     error?: string;
     message?: string;
 }
+/** Result of a follow or unfollow action */
+interface FollowActionResponse {
+    follower_id: string;
+    followee_id: string;
+    /** Post-state: true after follow, false after unfollow */
+    following: boolean;
+    /** Whether this call actually mutated state (false on idempotent repeat) */
+    changed: boolean;
+}
+/** Result of a follow-status check */
+interface FollowCheckResponse {
+    follower_id: string;
+    followee_id: string;
+    following: boolean;
+}
+type CommunicationPolicyMode = 'open' | 'closed' | 'manifest' | 'allowlist';
+interface CommunicationPolicyResponse {
+    agent_id: string;
+    communication_policy: {
+        mode: CommunicationPolicyMode;
+        reject_reason?: string;
+    };
+}
+/** Result of an allowlist add/remove action */
+interface AllowlistActionResponse {
+    /** The allowlist owner's agent ID */
+    owner_id: string;
+    target_id: string;
+    /** Post-state: true after add, false after remove */
+    allowlisted: boolean;
+    /** Whether this call actually mutated state */
+    changed: boolean;
+}
+/** Single allowlist entry (as returned by GET listing) */
+interface AllowlistEntry {
+    target_id: string;
+    reason?: string;
+    /** ISO-8601 UTC timestamp of when the entry was added */
+    created_at: string;
+}
+/** GET /allowlist response */
+interface AllowlistListResponse {
+    /** The allowlist owner's agent ID */
+    owner_id: string;
+    entries: AllowlistEntry[];
+    total: number;
+}
 
 /**
  * ACN HTTP Client
@@ -585,8 +682,8 @@ declare class ACNClient {
     }>;
     /** Get subnet by ID */
     getSubnet(subnetId: string): Promise<SubnetInfo>;
-    /** Delete a subnet */
-    deleteSubnet(subnetId: string, force?: boolean): Promise<{
+    /** Delete a subnet you own (requires Agent API Key — only the owning agent can delete) */
+    deleteSubnet(subnetId: string): Promise<{
         success: boolean;
     }>;
     /** Get agents in a subnet */
@@ -788,27 +885,96 @@ declare class ACNClient {
      * after fetchManifestContent.
      */
     deleteManifest(agentId: string, mid: string): Promise<Record<string, unknown>>;
-    /** Set agent's payment capability */
+    /** Set agent's payment capability (requires Agent API Key) */
     setPaymentCapability(agentId: string, capability: PaymentCapability): Promise<{
         success: boolean;
     }>;
-    /** 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.
+     */
     getPaymentCapability(agentId: string): Promise<PaymentCapability | null>;
-    /** Discover agents that accept payments */
+    /** Set OpenAI-style per-million-token pricing in USD (requires Agent API Key) */
+    setTokenPricing(agentId: string, pricing: {
+        input_price_per_million: number;
+        output_price_per_million: number;
+    }): Promise<{
+        status: string;
+        agent_id: string;
+        token_pricing: {
+            input_price_per_million: number;
+            output_price_per_million: number;
+            currency: string;
+        };
+        network_fee_rate?: number;
+    }>;
+    /** Get an agent's per-million-token pricing (requires Agent API Key) */
+    getTokenPricing(agentId: string): Promise<{
+        input_price_per_million: number;
+        output_price_per_million: number;
+        currency: string;
+    } | null>;
+    /** Discover agents that accept payments. Filters by lowercase method/network. */
     discoverPaymentAgents(options?: PaymentDiscoveryOptions): Promise<{
         agents: AgentInfo[];
     }>;
-    /** Get payment task by ID */
+    /**
+     * 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'`).
+     */
+    createPaymentTask(request: {
+        from_agent: string;
+        to_agent: string;
+        amount: number;
+        currency: string;
+        payment_method: PaymentMethod;
+        network: PaymentNetwork;
+        description?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        task_id: string;
+        status: string;
+    }>;
+    /**
+     * 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.
+     */
+    estimateCost(request: {
+        agent_id: string;
+        estimated_input_tokens?: number;
+        estimated_output_tokens?: number;
+    }): Promise<{
+        agent_id: string;
+        estimate: Record<string, number>;
+        note?: string;
+    }>;
+    /**
+     * Get a payment task by ID.
+     *
+     * Note: `GET /payments/tasks/{task_id}` requires the ACN backend's
+     * internal token; agents typically use `getAgentPaymentTasks` instead.
+     */
     getPaymentTask(taskId: string): Promise<PaymentTask>;
-    /** Get agent's payment tasks */
+    /** Get the payment tasks an agent is involved in (requires Agent API Key). */
     getAgentPaymentTasks(agentId: string, options?: {
-        role?: 'payer' | 'payee';
         status?: string;
         limit?: number;
     }): Promise<{
+        agent_id: string;
         tasks: PaymentTask[];
     }>;
-    /** Get agent's payment statistics */
+    /** Get an agent's payment statistics (requires Agent API Key). */
     getPaymentStats(agentId: string): Promise<PaymentStats>;
     /** Get Prometheus metrics (text format) */
     getPrometheusMetrics(): Promise<string>;
@@ -874,13 +1040,99 @@ declare class ACNClient {
         start_time?: string;
         end_time?: string;
     }): Promise<Record<string, unknown>>;
+    /**
+     * Follow another agent.
+     *
+     * Idempotent — re-following returns `changed: false`.
+     * @param agentId   The follower (must match the authenticated agent).
+     * @param targetId  The agent to follow.
+     */
+    follow(agentId: string, targetId: string): Promise<FollowActionResponse>;
+    /**
+     * 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.
+     */
+    unfollow(agentId: string, targetId: string): Promise<FollowActionResponse>;
+    /**
+     * Check whether `agentId` is following `targetId` (public endpoint).
+     */
+    checkFollow(agentId: string, targetId: string): Promise<FollowCheckResponse>;
+    /**
+     * List agents that `agentId` follows (public endpoint).
+     */
+    listFollows(agentId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<AgentSearchResponse>;
+    /**
+     * List agents that follow `agentId` (public endpoint).
+     */
+    listFollowers(agentId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<AgentSearchResponse>;
+    /**
+     * Get the authenticated agent's current communication policy (owner only).
+     */
+    getPolicy(agentId: string): Promise<CommunicationPolicyResponse>;
+    /**
+     * 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).
+     */
+    updatePolicy(agentId: string, mode: CommunicationPolicyMode, rejectReason?: string): Promise<CommunicationPolicyResponse>;
+    /**
+     * 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).
+     */
+    addToAllowlist(agentId: string, targetId: string, reason?: string): Promise<AllowlistActionResponse>;
+    /**
+     * Remove an agent from the allowlist (owner only).
+     *
+     * Idempotent — removing a non-member returns `changed: false`.
+     */
+    removeFromAllowlist(agentId: string, targetId: string): Promise<AllowlistActionResponse>;
+    /**
+     * List the authenticated agent's allowlist (owner only).
+     */
+    listAllowlist(agentId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<AllowlistListResponse>;
 }
 /**
  * ACN API Error
+ *
+ * Three body shapes are normalised here:
+ * - 4xx with string detail   → `{ detail: "..." }`
+ * - 422 validation (FastAPI) → `{ detail: [{loc, msg, type}, ...] }`
+ * - 5xx sanitised (H4)       → `{ error: "...", message: "...", request_id: "..." }`
+ *
+ * `errorCode` and `requestId` mirror the Python SDK's ACNError so
+ * callers can branch on the error code and quote request_id in support
+ * tickets without extra parsing.
  */
 declare class ACNError extends Error {
     status: number;
-    constructor(status: number, message: string);
+    /** ACN internal error code (present on sanitised 5xx responses) */
+    errorCode?: string;
+    /** Request ID minted by ACN for 5xx responses (useful for support) */
+    requestId?: string;
+    constructor(status: number, message: string, options?: {
+        errorCode?: string;
+        requestId?: string;
+    });
 }
 
 /**
@@ -973,4 +1225,4 @@ declare class ACNRealtime {
  */
 declare function subscribeToACN<T = unknown>(baseUrl: string, channel: string, handler: WSEventHandler<T>): () => void;
 
-export { ACNClient, type ACNClientOptions, ACNError, ACNRealtime, type ActivityEntry, type AgentActivity, type AgentAnalytics, type AgentInfo, type AgentJoinRequest, type AgentJoinResponse, type AgentRegisterRequest, type AgentRegisterResponse, type AgentSearchOptions, type AgentSearchResponse, type AgentStatus, type ApiResponse, type AttentionFee, type AuditEvent, type AuditQueryOptions, type BroadcastBySkillRequest, type BroadcastByTagRequest, type BroadcastRequest, type BroadcastStrategy, type ComponentHealth, type DashboardData, type ManifestContentResponse, type ManifestEntry, type ManifestListResponse, type Message, type MessageType, type MetricsData, type PaymentCapability, type PaymentDiscoveryOptions, type PaymentMethod, type PaymentNetwork, type PaymentStats, type PaymentTask, type PaymentTaskStatus, type SendMessageRequest, type SendMessageResponse, type SubnetCreateRequest, type SubnetCreateResponse, type SubnetInfo, type SystemHealth, type WSConnectionOptions, type WSEventHandler, type WSEventType, type WSMessage, type WSState, subscribeToACN };
+export { ACNClient, type ACNClientOptions, ACNError, ACNRealtime, type ActivityEntry, type AgentActivity, type AgentAnalytics, type AgentInfo, type AgentJoinRequest, type AgentJoinResponse, type AgentRegisterRequest, type AgentRegisterResponse, type AgentSearchOptions, type AgentSearchResponse, type AgentStatus, type AllowlistActionResponse, type AllowlistEntry, type AllowlistListResponse, type ApiResponse, type AttentionFee, type AuditEvent, type AuditQueryOptions, type BroadcastBySkillRequest, type BroadcastByTagRequest, type BroadcastRequest, type BroadcastStrategy, type CommunicationPolicyMode, type CommunicationPolicyResponse, type ComponentHealth, type DashboardData, type FollowActionResponse, type FollowCheckResponse, KNOWN_PAYMENT_TASK_STATUSES, type ManifestContentResponse, type ManifestEntry, type ManifestListResponse, type Message, type MessageType, type MetricsData, type PaymentCapability, type PaymentDiscoveryOptions, type PaymentMethod, type PaymentNetwork, type PaymentRoleStats, type PaymentStats, type PaymentTask, type PaymentTaskStatus, type SendMessageRequest, type SendMessageResponse, type SubnetCreateRequest, type SubnetCreateResponse, type SubnetInfo, type SystemHealth, type WSConnectionOptions, type WSEventHandler, type WSEventType, type WSMessage, type WSState, subscribeToACN };