acn-client 0.2.1

package/dist/index.d.mts

@@ -0,0 +1,579 @@
+/**
+ * ACN Client Types
+ *
+ * Type definitions synced with ACN API models.
+ * @see https://github.com/ACNet-AI/ACN
+ */
+/** Agent status */
+type AgentStatus = 'online' | 'offline' | 'busy';
+/** Agent list filter status (includes "all" for discovery) */
+type AgentSearchStatus = AgentStatus | 'all';
+/** Agent information */
+interface AgentInfo {
+    id: string;
+    name: string;
+    description?: string;
+    skills: string[];
+    status: AgentStatus;
+    endpoint?: string;
+    metadata?: Record<string, unknown>;
+    subnets?: string[];
+    created_at?: string;
+    last_seen?: string;
+    wallet_address?: string;
+    accepts_payment?: boolean;
+    payment_methods?: string[];
+    supported_networks?: string[];
+}
+/** Agent registration request */
+interface AgentRegisterRequest {
+    id: string;
+    name: string;
+    description?: string;
+    skills: string[];
+    endpoint?: string;
+    metadata?: Record<string, unknown>;
+    wallet_address?: string;
+    payment_capability?: PaymentCapability;
+}
+/** Agent registration response */
+interface AgentRegisterResponse {
+    success: boolean;
+    agent_id: string;
+    message: string;
+}
+/** Agent search response */
+interface AgentSearchResponse {
+    agents: AgentInfo[];
+    total: number;
+}
+/** Agent search options */
+interface AgentSearchOptions {
+    skills?: string;
+    /** online (default) | offline | all. Public list does not include verification_code. */
+    status?: AgentSearchStatus;
+    subnet_id?: string;
+}
+/** Subnet information */
+interface SubnetInfo {
+    id: string;
+    name: string;
+    description?: string;
+    created_at: string;
+    agent_count: number;
+    metadata?: Record<string, unknown>;
+}
+/** Subnet creation request */
+interface SubnetCreateRequest {
+    name: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Subnet creation response */
+interface SubnetCreateResponse {
+    success: boolean;
+    subnet_id: string;
+    message: string;
+}
+/** Message types */
+type MessageType = 'text' | 'data' | 'notification' | 'task' | 'result';
+/** A2A Message */
+interface Message {
+    id: string;
+    type: MessageType;
+    from_agent: string;
+    to_agent?: string;
+    content: unknown;
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+}
+/** Send message request */
+interface SendMessageRequest {
+    from_agent: string;
+    to_agent: string;
+    message_type: MessageType;
+    content: unknown;
+    metadata?: Record<string, unknown>;
+}
+/** Broadcast strategy */
+type BroadcastStrategy = 'all' | 'random' | 'round_robin' | 'load_balanced';
+/** Broadcast request */
+interface BroadcastRequest {
+    from_agent: string;
+    message_type: MessageType;
+    content: unknown;
+    strategy?: BroadcastStrategy;
+    target_agents?: string[];
+    metadata?: Record<string, unknown>;
+}
+/** Broadcast by skill request */
+interface BroadcastBySkillRequest {
+    from_agent: string;
+    skill: string;
+    message_type: MessageType;
+    content: unknown;
+    strategy?: BroadcastStrategy;
+    metadata?: Record<string, unknown>;
+}
+/** 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 */
+interface PaymentCapability {
+    accepts_payment: boolean;
+    wallet_address?: string;
+    supported_methods: PaymentMethod[];
+    supported_networks: PaymentNetwork[];
+    min_amount?: number;
+    max_amount?: number;
+    currency?: string;
+}
+/** Payment task status */
+type PaymentTaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
+/** Payment task */
+interface PaymentTask {
+    id: string;
+    payer_agent_id: string;
+    payee_agent_id: string;
+    amount: number;
+    currency: string;
+    method: PaymentMethod;
+    network?: PaymentNetwork;
+    status: PaymentTaskStatus;
+    created_at: string;
+    updated_at: string;
+    transaction_hash?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Payment discovery options */
+interface PaymentDiscoveryOptions {
+    method?: PaymentMethod;
+    network?: PaymentNetwork;
+    min_amount?: number;
+    max_amount?: number;
+}
+/** Payment statistics */
+interface PaymentStats {
+    total_received: number;
+    total_sent: number;
+    transaction_count: number;
+    avg_amount: number;
+}
+/** System health */
+interface SystemHealth {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    uptime: number;
+    version: string;
+    components: Record<string, ComponentHealth>;
+}
+/** Component health */
+interface ComponentHealth {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    latency_ms?: number;
+    message?: string;
+}
+/** Dashboard data */
+interface DashboardData {
+    agents: {
+        total: number;
+        online: number;
+        offline: number;
+    };
+    messages: {
+        total: number;
+        last_hour: number;
+        last_24h: number;
+    };
+    subnets: {
+        total: number;
+        active: number;
+    };
+    system: SystemHealth;
+}
+/** Metrics data */
+interface MetricsData {
+    timestamp: string;
+    metrics: Record<string, number>;
+}
+/** Agent analytics */
+interface AgentAnalytics {
+    agent_id: string;
+    messages_sent: number;
+    messages_received: number;
+    tasks_completed: number;
+    avg_response_time_ms: number;
+    uptime_percentage: number;
+}
+/** Agent activity */
+interface AgentActivity {
+    agent_id: string;
+    activities: ActivityEntry[];
+}
+/** Activity entry */
+interface ActivityEntry {
+    timestamp: string;
+    type: string;
+    description: string;
+    metadata?: Record<string, unknown>;
+}
+/** Audit event */
+interface AuditEvent {
+    id: string;
+    timestamp: string;
+    event_type: string;
+    actor_id?: string;
+    target_id?: string;
+    action: string;
+    details?: Record<string, unknown>;
+    ip_address?: string;
+}
+/** Audit query options */
+interface AuditQueryOptions {
+    event_type?: string;
+    actor_id?: string;
+    start_time?: string;
+    end_time?: string;
+    limit?: number;
+    offset?: number;
+}
+/** WebSocket message */
+interface WSMessage<T = unknown> {
+    type: string;
+    channel: string;
+    data: T;
+    timestamp: string;
+}
+/** WebSocket event types */
+type WSEventType = 'agent_online' | 'agent_offline' | 'message' | 'broadcast' | 'task_update' | 'payment_update' | 'error';
+/** WebSocket connection options */
+interface WSConnectionOptions {
+    /** Reconnect automatically on disconnect */
+    autoReconnect?: boolean;
+    /** Reconnect interval in ms */
+    reconnectInterval?: number;
+    /** Max reconnect attempts */
+    maxReconnectAttempts?: number;
+    /** Heartbeat interval in ms */
+    heartbeatInterval?: number;
+}
+/** ACN Client configuration */
+interface ACNClientOptions {
+    /** ACN server base URL */
+    baseUrl: string;
+    /** Request timeout in ms */
+    timeout?: number;
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** API key for authentication (optional) */
+    apiKey?: string;
+}
+/** API response wrapper */
+interface ApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    message?: string;
+}
+
+/**
+ * ACN HTTP Client
+ *
+ * Official TypeScript client for ACN REST API.
+ */
+
+/**
+ * ACN Client - HTTP API
+ *
+ * @example
+ * ```typescript
+ * import { ACNClient } from '@acn/client';
+ *
+ * const client = new ACNClient({ baseUrl: 'http://localhost:9000' });
+ *
+ * // Search agents
+ * const { agents } = await client.searchAgents({ skills: 'coding' });
+ *
+ * // Get agent details
+ * const agent = await client.getAgent('agent-123');
+ * ```
+ */
+declare class ACNClient {
+    private baseUrl;
+    private timeout;
+    private headers;
+    constructor(options: ACNClientOptions | string);
+    private request;
+    private get;
+    private post;
+    private delete;
+    /** Check if ACN server is healthy */
+    health(): Promise<{
+        status: string;
+    }>;
+    /** Get server statistics */
+    getStats(): Promise<{
+        total_agents: number;
+        online_agents: number;
+        total_messages: number;
+    }>;
+    /** Register a new agent */
+    registerAgent(agent: AgentRegisterRequest): Promise<AgentRegisterResponse>;
+    /** Get agent by ID */
+    getAgent(agentId: string): Promise<AgentInfo>;
+    /** Search agents (status: online | offline | all; public list does not include verification_code) */
+    searchAgents(options?: AgentSearchOptions): Promise<AgentSearchResponse>;
+    /** Unregister an agent */
+    unregisterAgent(agentId: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /** Send agent heartbeat */
+    heartbeat(agentId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Get agent endpoint */
+    getAgentEndpoint(agentId: string): Promise<{
+        endpoint: string;
+    }>;
+    /** List all available skills */
+    getSkills(): Promise<{
+        skills: string[];
+        counts: Record<string, number>;
+    }>;
+    /** Create a new subnet */
+    createSubnet(request: SubnetCreateRequest): Promise<SubnetCreateResponse>;
+    /** List all subnets */
+    listSubnets(): Promise<{
+        subnets: SubnetInfo[];
+    }>;
+    /** Get subnet by ID */
+    getSubnet(subnetId: string): Promise<SubnetInfo>;
+    /** Delete a subnet */
+    deleteSubnet(subnetId: string, force?: boolean): Promise<{
+        success: boolean;
+    }>;
+    /** Get agents in a subnet */
+    getSubnetAgents(subnetId: string): Promise<{
+        agents: AgentInfo[];
+    }>;
+    /** Join agent to subnet */
+    joinSubnet(agentId: string, subnetId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Remove agent from subnet */
+    leaveSubnet(agentId: string, subnetId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Get agent's subnets */
+    getAgentSubnets(agentId: string): Promise<{
+        subnets: string[];
+    }>;
+    /** Send message to an agent */
+    sendMessage(request: SendMessageRequest): Promise<{
+        success: boolean;
+        message_id: string;
+    }>;
+    /** Broadcast message to multiple agents */
+    broadcast(request: BroadcastRequest): Promise<{
+        success: boolean;
+        delivered_count: number;
+    }>;
+    /** Broadcast message to agents with specific skill */
+    broadcastBySkill(request: BroadcastBySkillRequest): Promise<{
+        success: boolean;
+        delivered_count: number;
+    }>;
+    /** Get message history for an agent */
+    getMessageHistory(agentId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        messages: Message[];
+    }>;
+    /** Set agent's payment capability */
+    setPaymentCapability(agentId: string, capability: PaymentCapability): Promise<{
+        success: boolean;
+    }>;
+    /** Get agent's payment capability */
+    getPaymentCapability(agentId: string): Promise<PaymentCapability | null>;
+    /** Discover agents that accept payments */
+    discoverPaymentAgents(options?: PaymentDiscoveryOptions): Promise<{
+        agents: AgentInfo[];
+    }>;
+    /** Get payment task by ID */
+    getPaymentTask(taskId: string): Promise<PaymentTask>;
+    /** Get agent's payment tasks */
+    getAgentPaymentTasks(agentId: string, options?: {
+        role?: 'payer' | 'payee';
+        status?: string;
+        limit?: number;
+    }): Promise<{
+        tasks: PaymentTask[];
+    }>;
+    /** Get agent's payment statistics */
+    getPaymentStats(agentId: string): Promise<PaymentStats>;
+    /** Get Prometheus metrics (text format) */
+    getPrometheusMetrics(): Promise<string>;
+    /** Get all metrics */
+    getMetrics(): Promise<MetricsData>;
+    /** Get system health */
+    getSystemHealth(): Promise<SystemHealth>;
+    /** Get dashboard data */
+    getDashboard(): Promise<DashboardData>;
+    /** Get agent analytics */
+    getAgentAnalytics(): Promise<{
+        analytics: AgentAnalytics[];
+    }>;
+    /** Get specific agent's activity */
+    getAgentActivity(agentId: string, options?: {
+        start_time?: string;
+        end_time?: string;
+    }): Promise<AgentActivity>;
+    /** Get message analytics */
+    getMessageAnalytics(): Promise<Record<string, unknown>>;
+    /** Get latency analytics */
+    getLatencyAnalytics(): Promise<Record<string, unknown>>;
+    /** Get subnet analytics */
+    getSubnetAnalytics(): Promise<Record<string, unknown>>;
+    /** Get audit events */
+    getAuditEvents(options?: AuditQueryOptions): Promise<{
+        events: AuditEvent[];
+    }>;
+    /** Get recent audit events */
+    getRecentAuditEvents(limit?: number): Promise<{
+        events: AuditEvent[];
+    }>;
+    /**
+     * 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.
+     */
+    registerOnchain(agentId: string, options?: {
+        privateKey?: `0x${string}`;
+        chain?: 'base' | 'base-sepolia';
+        rpcUrl?: string;
+        saveWalletPath?: string;
+    }): Promise<{
+        tokenId: bigint;
+        txHash: string;
+        chain: string;
+        agentRegistrationUrl: string;
+        walletAddress: string;
+        walletGenerated: boolean;
+    }>;
+    /** @internal Save generated wallet credentials to a .env file. */
+    private _saveWalletToEnv;
+    /** Get audit statistics */
+    getAuditStats(options?: {
+        start_time?: string;
+        end_time?: string;
+    }): Promise<Record<string, unknown>>;
+}
+/**
+ * ACN API Error
+ */
+declare class ACNError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+
+/**
+ * ACN WebSocket Client
+ *
+ * Real-time communication with ACN server.
+ */
+
+/** WebSocket event handler */
+type WSEventHandler<T = unknown> = (message: WSMessage<T>) => void;
+/** WebSocket state */
+type WSState = 'connecting' | 'connected' | 'disconnected' | 'reconnecting';
+/**
+ * ACN Real-time Client
+ *
+ * @example
+ * ```typescript
+ * import { ACNRealtime } from '@acn/client';
+ *
+ * const realtime = new ACNRealtime('ws://localhost:9000');
+ *
+ * // Subscribe to a channel
+ * realtime.subscribe('agents', (message) => {
+ *   console.log('Agent event:', message);
+ * });
+ *
+ * // Connect
+ * await realtime.connect();
+ * ```
+ */
+declare class ACNRealtime {
+    private baseUrl;
+    private options;
+    private ws;
+    private state;
+    private reconnectAttempts;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private channels;
+    private globalHandlers;
+    private stateHandlers;
+    constructor(baseUrl: string, options?: WSConnectionOptions);
+    /** Current connection state */
+    get connectionState(): WSState;
+    /** Whether currently connected */
+    get isConnected(): boolean;
+    /**
+     * Connect to a channel
+     */
+    connect(channel?: string): Promise<void>;
+    /**
+     * Disconnect from server
+     */
+    disconnect(): void;
+    /**
+     * Subscribe to a channel
+     */
+    subscribe<T = unknown>(channel: string, handler: WSEventHandler<T>): () => void;
+    /**
+     * Subscribe to all messages
+     */
+    onMessage<T = unknown>(handler: WSEventHandler<T>): () => void;
+    /**
+     * Subscribe to state changes
+     */
+    onStateChange(handler: (state: WSState) => void): () => void;
+    /**
+     * Send a message
+     */
+    send(message: unknown): void;
+    private setState;
+    private handleMessage;
+    private handleError;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+}
+/**
+ * Create a simple subscription to ACN events
+ *
+ * @example
+ * ```typescript
+ * const unsubscribe = subscribeToACN('ws://localhost:9000', 'agents', (msg) => {
+ *   console.log('Agent event:', msg);
+ * });
+ *
+ * // Later: unsubscribe();
+ * ```
+ */
+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 AgentRegisterRequest, type AgentRegisterResponse, type AgentSearchOptions, type AgentSearchResponse, type AgentStatus, type ApiResponse, type AuditEvent, type AuditQueryOptions, type BroadcastBySkillRequest, type BroadcastRequest, type BroadcastStrategy, type ComponentHealth, type DashboardData, type Message, type MessageType, type MetricsData, type PaymentCapability, type PaymentDiscoveryOptions, type PaymentMethod, type PaymentNetwork, type PaymentStats, type PaymentTask, type PaymentTaskStatus, type SendMessageRequest, type SubnetCreateRequest, type SubnetCreateResponse, type SubnetInfo, type SystemHealth, type WSConnectionOptions, type WSEventHandler, type WSEventType, type WSMessage, type WSState, subscribeToACN };