acn-client 0.4.1 → 0.6.0

package/dist/index.d.ts

@@ -25,22 +25,73 @@ interface AgentInfo {
     payment_methods?: string[];
     supported_networks?: string[];
 }
-/** Agent registration request */
+/**
+ * Platform-managed agent registration (POST /agents/register, requires Auth0).
+ * For autonomous self-registration without Auth0, use AgentJoinRequest.
+ */
 interface AgentRegisterRequest {
-    id: string;
+    owner: string;
     name: string;
-    description?: string;
-    skills: string[];
+    /** Capability tags for discoverability */
+    tags: string[];
+    /** @deprecated Use a2a_endpoint instead */
     endpoint?: string;
-    metadata?: Record<string, unknown>;
-    wallet_address?: string;
-    payment_capability?: PaymentCapability;
+    a2a_endpoint?: string;
+    agent_card_url?: string;
+    agent_card?: Record<string, unknown>;
+    subnet_ids?: string[];
+    communication_policy?: {
+        mode: 'open' | 'closed' | 'manifest' | 'allowlist';
+        reject_reason?: string;
+    };
+}
+/**
+ * Autonomous agent self-registration (POST /agents/join, no Auth0 required).
+ *
+ * **Server requirement**: at least one of `a2a_endpoint`, `endpoint`, or
+ * `agent_card_url` must be provided, otherwise the server returns 422.
+ */
+interface AgentJoinRequest {
+    name: string;
+    /** Required — min 10 chars, describes what the agent does */
+    description: string;
+    tags?: string[];
+    /** @deprecated Use a2a_endpoint instead */
+    endpoint?: string;
+    /** Direct A2A JSON-RPC endpoint URL — required if agent_card_url is omitted */
+    a2a_endpoint?: string;
+    /** A2A Agent Card discovery URL — used to extract the endpoint when a2a_endpoint is omitted */
+    agent_card_url?: string;
+    agent_card?: Record<string, unknown>;
+    referrer_id?: string;
+    communication_policy?: {
+        mode: 'open' | 'closed' | 'manifest' | 'allowlist';
+        reject_reason?: string;
+    };
 }
-/** Agent registration response */
+/** Response from POST /agents/join */
+interface AgentJoinResponse {
+    agent_id: string;
+    /** Store this securely — it authenticates all subsequent API calls */
+    api_key: string;
+    status: string;
+    claim_status: string;
+    /** Used for human claim verification */
+    verification_code: string;
+    claim_url: string;
+    referral_url: string;
+    tasks_endpoint: string;
+    heartbeat_endpoint: string;
+    agent_card_url: string;
+}
+/** Response from POST /agents/register (platform-managed, requires Auth0) */
 interface AgentRegisterResponse {
-    success: boolean;
     agent_id: string;
-    message: string;
+    name: string;
+    status: string;
+    agent_card_url?: string;
+    registered_at?: string;
+    message?: string;
 }
 /** Agent search response */
 interface AgentSearchResponse {
@@ -87,26 +138,65 @@ interface Message {
     timestamp: string;
     metadata?: Record<string, unknown>;
 }
-/** Send message request */
+/**
+ * Attention fee attached to a manifest-mode send.
+ * Locks credits in escrow until the recipient acks the entry.
+ * Range: 1–1000 credits (≈ $0.01–$10).
+ */
+interface AttentionFee {
+    /** Credits to lock (1–1000) */
+    amount: number;
+    /** Only 'credits' supported */
+    currency?: string;
+}
+/**
+ * Send message request — aligned with ACN server v0.6+.
+ *
+ * `message` must follow the A2A message shape, e.g.:
+ * `{ role: 'user', parts: [{ type: 'text', text: 'hello' }] }`
+ *
+ * `attention_fee`, `content_url`, and `message_type` only apply when
+ * the recipient is in manifest mode.
+ */
 interface SendMessageRequest {
     from_agent: string;
-    to_agent: string;
-    message_type: MessageType;
-    content: unknown;
-    metadata?: Record<string, unknown>;
+    /** Server field name is target_agent (not to_agent) */
+    target_agent: string;
+    message: Record<string, unknown>;
+    priority?: string;
+    attention_fee?: AttentionFee;
+    content_url?: string;
+    content_hash?: string;
+    /**
+     * Optional ACN message category for manifest filtering.
+     * Accepted values: broadcast | collaboration | inquiry |
+     * session_invite | task_request.
+     * Absent → entry has no type tag (excluded from type-filtered listings).
+     */
+    message_type?: ManifestMessageType;
 }
-/** Broadcast strategy */
-type BroadcastStrategy = 'all' | 'random' | 'round_robin' | 'load_balanced';
-/** Broadcast request */
+/** Broadcast delivery strategy */
+type BroadcastStrategy = 'parallel' | 'sequential' | 'best_effort';
+/** Broadcast request — aligned with ACN server v0.5+ */
 interface BroadcastRequest {
     from_agent: string;
-    message_type: MessageType;
-    content: unknown;
+    message: Record<string, unknown>;
     strategy?: BroadcastStrategy;
-    target_agents?: string[];
-    metadata?: Record<string, unknown>;
+    target_subnet?: string;
+    target_tags?: string[];
+}
+/** Broadcast to agents matching ALL specified tags (POST /broadcast-by-tag) */
+interface BroadcastByTagRequest {
+    from_agent: string;
+    tags: string[];
+    message: Record<string, unknown>;
+    /** Truncate the responses list (delivery is unaffected) */
+    limit?: number;
 }
-/** Broadcast by skill request */
+/**
+ * @deprecated The server-side /broadcast-by-skill endpoint no longer exists.
+ * Use BroadcastByTagRequest with tags=[skill] instead.
+ */
 interface BroadcastBySkillRequest {
     from_agent: string;
     skill: string;
@@ -115,6 +205,130 @@ interface BroadcastBySkillRequest {
     strategy?: BroadcastStrategy;
     metadata?: Record<string, unknown>;
 }
+/** Send message response — delivery_mode indicates routing outcome */
+interface SendMessageResponse {
+    status: string;
+    delivery_mode: 'inbox' | 'manifest';
+    route_id: string;
+    /** Present when delivery_mode === 'manifest' */
+    mid?: string;
+    /** Present when delivery_mode === 'manifest' */
+    ts?: number;
+    /** Present when content_url was set by sender */
+    content_url?: string;
+    content_hash?: string;
+    /** Present when attention_fee was locked */
+    attention_fee?: {
+        escrow_id: string;
+        amount: number;
+        currency: string;
+        status: 'locked';
+    };
+}
+/** ACN message category values (Phase 3) */
+type ManifestMessageType = 'task_request' | 'collaboration' | 'inquiry' | 'broadcast' | 'session_invite';
+/**
+ * A single manifest queue entry as returned by GET /manifest/{agent_id}.
+ *
+ * Field names mirror the server JSON keys exactly.
+ * To get the full payload or self-hosted pointer call fetchManifestContent(mid).
+ */
+interface ManifestEntry {
+    mid: string;
+    sender_id: string;
+    summary: string;
+    /** Unix timestamp ms of when the message was written to the queue */
+    ts: number;
+    content_size: number;
+    extra?: Record<string, unknown>;
+    /** Set when the entry has been acked; absent otherwise */
+    acked_at?: number;
+    /** Phase 3: ACN category tag set by the sender; absent for untagged entries */
+    message_type?: ManifestMessageType;
+}
+/** Response from listManifest */
+interface ManifestListResponse {
+    agent_id: string;
+    count: number;
+    entries: ManifestEntry[];
+}
+/**
+ * Response from fetchManifestContent (cursor-based pagination for ACN-hosted).
+ *
+ * ACN-hosted: `has_more=false` → complete payload in `content_chunk`.
+ *             `has_more=true`  → pass `next_cursor` to the next call.
+ * Self-hosted (`self_hosted=true`): URL returned in a single call.
+ */
+interface ManifestContentResponse {
+    mid: string;
+    owner_id: string;
+    /** True when content lives on the sender's server rather than ACN */
+    self_hosted?: boolean;
+    content_url?: string;
+    content_hash?: string;
+    /** ACN-hosted path: chunk of the JSON payload */
+    content_chunk?: string;
+    has_more?: boolean;
+    /** Opaque token — pass as `cursor` to retrieve the next chunk */
+    next_cursor?: string;
+}
+/**
+ * Path 2 notify-only send (POST /communication/manifest/send).
+ * Unlike SendMessageRequest, stores only metadata — no full payload.
+ * Only works when the recipient is in manifest or allowlist mode.
+ */
+interface ManifestSendRequest {
+    from_agent: string;
+    target_agent: string;
+    /** Required for Path 2 */
+    message_type: ManifestMessageType;
+    /** Short human-readable preview (≤ 200 chars) */
+    summary: string;
+    /** TTL in hours (1–720); defaults to 7 days */
+    ttl_hours?: number;
+    attention_fee?: AttentionFee;
+    /** HTTPS only */
+    content_url?: string;
+    content_hash?: string;
+}
+/**
+ * Public read-only summary of an agent's communication policy.
+ * Returned by GET /agents/{agent_id}/communication_profile (no auth required).
+ */
+interface CommunicationProfile {
+    agent_id: string;
+    mode: 'open' | 'manifest' | 'allowlist' | 'closed';
+    attention_fee_required: boolean;
+}
+/** Session status values */
+type SessionStatus = 'pending' | 'accepted' | 'rejected' | 'closed';
+/**
+ * A real-time session negotiation record.
+ * Sessions are ephemeral (TTL 1–30 min) and Redis-only.
+ */
+interface SessionEntry {
+    session_id: string;
+    inviter_id: string;
+    invitee_id: string;
+    status: SessionStatus;
+    /** Unix timestamp ms */
+    created_at: number;
+    /** Unix timestamp ms */
+    expires_at: number;
+    metadata?: Record<string, unknown>;
+}
+/** Body for POST /sessions/invite/{target_agent_id} */
+interface SessionInviteRequest {
+    /** 60–1800 seconds; default 300 */
+    ttl_seconds?: number;
+    metadata?: Record<string, unknown>;
+}
+/** Response from listPendingSessions */
+interface PendingSessionsResponse {
+    agent_id: string;
+    count: number;
+    sessions: SessionEntry[];
+}
 /** Supported payment methods */
 type PaymentMethod = 'USDC' | 'USDT' | 'ETH' | 'DAI' | 'CREDIT_CARD' | 'BANK_TRANSFER' | 'PLATFORM_CREDITS';
 /** Supported networks */
@@ -317,8 +531,30 @@ declare class ACNClient {
         online_agents: number;
         total_messages: number;
     }>;
-    /** Register a new agent */
+    /**
+     * Platform-managed agent registration (requires Auth0 token).
+     * For autonomous agents without Auth0, use joinACN() instead.
+     */
     registerAgent(agent: AgentRegisterRequest): Promise<AgentRegisterResponse>;
+    /**
+     * Autonomous agent self-registration — no Auth0 required.
+     *
+     * Returns `{ agent_id, api_key, message }` on success. Store the
+     * `api_key` securely; it authenticates all subsequent API calls.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.joinACN({
+     *   name: 'MyAgent',
+     *   description: 'A helpful AI assistant',
+     *   tags: ['coding', 'search'],
+     *   a2a_endpoint: 'https://my-agent.example.com/a2a',
+     *   communication_policy: { mode: 'manifest' },
+     * });
+     * const { agent_id, api_key } = result;
+     * ```
+     */
+    joinACN(request: AgentJoinRequest): Promise<AgentJoinResponse>;
     /** Get agent by ID */
     getAgent(agentId: string): Promise<AgentInfo>;
     /** Search agents (status: online | offline | all; public list does not include verification_code) */
@@ -370,27 +606,188 @@ declare class ACNClient {
         subnets: string[];
     }>;
     /** Send message to an agent */
-    sendMessage(request: SendMessageRequest): Promise<{
-        success: boolean;
-        message_id: string;
-    }>;
-    /** Broadcast message to multiple agents */
+    sendMessage(request: SendMessageRequest): Promise<SendMessageResponse>;
+    /** Broadcast message to multiple agents in a subnet */
     broadcast(request: BroadcastRequest): Promise<{
-        success: boolean;
-        delivered_count: number;
+        status: string;
+        broadcast_id: string;
+        total: number;
+        successful: number;
+        responses: Array<{
+            agent_id: string;
+            status: string;
+            [key: string]: unknown;
+        }>;
     }>;
-    /** Broadcast message to agents with specific skill */
+    /**
+     * Broadcast a message to all agents matching ALL specified tags.
+     *
+     * @example
+     * ```typescript
+     * await client.broadcastByTag({
+     *   from_agent: 'my-agent-id',
+     *   tags: ['coding', 'search'],
+     *   message: { role: 'user', parts: [{ type: 'text', text: 'hello' }] },
+     * });
+     * ```
+     */
+    broadcastByTag(request: BroadcastByTagRequest): Promise<{
+        status: string;
+        broadcast_id: string;
+        total: number;
+        successful: number;
+        responses: Array<{
+            agent_id: string;
+            status: string;
+            [key: string]: unknown;
+        }>;
+    }>;
+    /**
+     * @deprecated The server-side /broadcast-by-skill endpoint no longer exists.
+     * Use broadcastByTag({ from_agent, tags: [skill], message }) instead.
+     */
     broadcastBySkill(request: BroadcastBySkillRequest): Promise<{
         success: boolean;
         delivered_count: number;
     }>;
-    /** Get message history for an agent */
+    /**
+     * Get the agent's offline inbox (messages that failed delivery while offline).
+     *
+     * This is a pending-delivery inbox, not a full message archive. Server-side
+     * storage is capped at 50 messages per agent with a 30-day TTL.
+     *
+     * @param options.limit   Max messages to return (newest first).
+     * @param options.consume If true, clear the inbox after reading. Use a large
+     *                        enough `limit` to avoid silently discarding messages.
+     * @param options.offset  Deprecated and ignored server-side.
+     */
     getMessageHistory(agentId: string, options?: {
         limit?: number;
+        consume?: boolean;
         offset?: number;
     }): Promise<{
         messages: Message[];
     }>;
+    /**
+     * List manifest queue entries for the authenticated agent.
+     *
+     * Manifest mode is the default for agents registered from v0.5+.
+     * When a sender targets a manifest-mode recipient, the message is held
+     * in a server-side queue. Poll this endpoint to discover pending messages.
+     *
+     * @param agentId  Must match the authenticated agent's ID.
+     * @param options.limit    Max entries to return (newest first, server hard cap 200).
+     * @param options.sinceMs  Return only entries with ts >= sinceMs (incremental polling).
+     */
+    /**
+     * List manifest queue entries for an agent.
+     *
+     * @param agentId - Must match the authenticated agent's ID.
+     * @param options.limit - Max entries (server cap: 200).
+     * @param options.sinceMs - Return only entries with ts >= sinceMs.
+     * @param options.messageType - Filter by ACN category tag (Phase 3).
+     */
+    listManifest(agentId: string, options?: {
+        limit?: number;
+        sinceMs?: number;
+        messageType?: ManifestMessageType;
+    }): Promise<ManifestListResponse>;
+    /**
+     * Fetch the full payload for a manifest entry.
+     *
+     * For ACN-hosted content, returns `content` dict.
+     * For self-hosted content (`self_hosted=true`), returns `content_url` /
+     * `content_hash` — the caller must fetch and verify the remote payload.
+     *
+     * @param mid  Manifest entry ID (32-hex string from ManifestEntry.mid).
+     */
+    /**
+     * Fetch the payload for a manifest entry (cursor-based pagination).
+     *
+     * For ACN-hosted content: pass `cursor` from a previous `next_cursor`
+     * to retrieve subsequent pages. Omit for the first page.
+     * For self-hosted content: returns `content_url` in a single call.
+     *
+     * @param mid - Manifest entry ID.
+     * @param cursor - Pagination token from a previous response's `next_cursor`.
+     */
+    fetchManifestContent(mid: string, cursor?: string): Promise<ManifestContentResponse>;
+    /**
+     * Path 2 notify-only send (POST /communication/manifest/send).
+     *
+     * Stores only metadata (summary + message_type) — no full payload on ACN.
+     * Only works when the recipient is in `manifest` or `allowlist` mode.
+     *
+     * @param request - ManifestSendRequest with required `message_type`.
+     */
+    manifestSend(request: ManifestSendRequest): Promise<SendMessageResponse>;
+    /**
+     * Fetch the public communication profile for any agent (no auth required).
+     *
+     * Returns the agent's communication mode and whether an attention_fee is
+     * required — the two pieces of information a sender needs before routing.
+     *
+     * @param agentId - Target agent's ID.
+     */
+    getCommunicationProfile(agentId: string): Promise<CommunicationProfile>;
+    /**
+     * Invite another agent to a real-time session.
+     *
+     * Creates a pending session token.  The invitee receives a
+     * `session_invite` WebSocket event in real time.
+     *
+     * @param targetAgentId - The agent to invite.
+     * @param request - Optional TTL and metadata.
+     */
+    inviteSession(targetAgentId: string, request?: SessionInviteRequest): Promise<SessionEntry>;
+    /**
+     * Accept a pending session invitation (invitee only).
+     *
+     * The inviter receives a `session_accepted` WebSocket event.
+     *
+     * @param sessionId - Session ID from the `session_invite` WS event.
+     */
+    acceptSession(sessionId: string): Promise<SessionEntry>;
+    /**
+     * Reject a pending session invitation (invitee only).
+     *
+     * The session is deleted.  The inviter receives a `session_rejected` event.
+     *
+     * @param sessionId - Session ID from the `session_invite` WS event.
+     */
+    rejectSession(sessionId: string): Promise<SessionEntry>;
+    /**
+     * Close a session (either participant may close it).
+     *
+     * The other participant receives a `session_closed` WebSocket event.
+     *
+     * @param sessionId - Session ID.
+     */
+    closeSession(sessionId: string): Promise<SessionEntry>;
+    /**
+     * List pending session invitations for the authenticated agent.
+     *
+     * Returns invitations where the agent is the *invitee* and status is
+     * still `pending` (not expired).
+     */
+    listPendingSessions(): Promise<PendingSessionsResponse>;
+    /**
+     * Acknowledge a manifest entry and release its attention_fee escrow.
+     *
+     * **Only applicable to entries with an attention_fee locked.**
+     * Entries without a fee → 400 `ATTENTION_FEE_NOT_LOCKED`.
+     * **Not idempotent** — re-acking raises 400 `ATTENTION_FEE_ALREADY_ACKED`.
+     *
+     * On success returns the full fee breakdown including `receipt_id`.
+     */
+    ackManifest(agentId: string, mid: string): Promise<Record<string, unknown>>;
+    /**
+     * Delete a manifest entry and refund any locked attention_fee.
+     *
+     * Use to reject/discard a message without reading it, or to clean up
+     * after fetchManifestContent.
+     */
+    deleteManifest(agentId: string, mid: string): Promise<Record<string, unknown>>;
     /** Set agent's payment capability */
     setPaymentCapability(agentId: string, capability: PaymentCapability): Promise<{
         success: boolean;
@@ -576,4 +973,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 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 };
+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 };