acn-client 0.5.1 → 0.6.0

package/dist/index.js

@@ -115,10 +115,34 @@ var ACNClient = class {
   // ============================================
   // Agent Management
   // ============================================
-  /** Register a new agent */
+  /**
+   * Platform-managed agent registration (requires Auth0 token).
+   * For autonomous agents without Auth0, use joinACN() instead.
+   */
   async registerAgent(agent) {
     return this.post("/api/v1/agents/register", agent);
   }
+  /**
+   * 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;
+   * ```
+   */
+  async joinACN(request) {
+    return this.post("/api/v1/agents/join", request);
+  }
   /** Get agent by ID */
   async getAgent(agentId) {
     return this.get(`/api/v1/agents/${agentId}`);
@@ -190,12 +214,33 @@ var ACNClient = class {
   async sendMessage(request) {
     return this.post("/api/v1/communication/send", request);
   }
-  /** Broadcast message to multiple agents */
+  /** Broadcast message to multiple agents in a subnet */
   async broadcast(request) {
     return this.post("/api/v1/communication/broadcast", request);
   }
-  /** 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' }] },
+   * });
+   * ```
+   */
+  async broadcastByTag(request) {
+    return this.post("/api/v1/communication/broadcast-by-tag", request);
+  }
+  /**
+   * @deprecated The server-side /broadcast-by-skill endpoint no longer exists.
+   * Use broadcastByTag({ from_agent, tags: [skill], message }) instead.
+   */
   async broadcastBySkill(request) {
+    console.warn(
+      "broadcastBySkill() is deprecated: the server endpoint /broadcast-by-skill no longer exists. Use broadcastByTag({ from_agent, tags: [skill], message }) instead."
+    );
     return this.post("/api/v1/communication/broadcast-by-skill", request);
   }
   /**
@@ -216,6 +261,156 @@ var ACNClient = class {
     return this.get(`/api/v1/communication/history/${agentId}`, params);
   }
   // ============================================
+  // Manifest Queue (Phase 2/3)
+  // ============================================
+  /**
+   * 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).
+   */
+  async listManifest(agentId, options) {
+    const params = {};
+    if (options?.limit !== void 0) params.limit = options.limit;
+    if (options?.sinceMs !== void 0) params.since_ms = options.sinceMs;
+    if (options?.messageType !== void 0) params.type = options.messageType;
+    return this.get(`/api/v1/communication/manifest/${agentId}`, params);
+  }
+  /**
+   * 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`.
+   */
+  async fetchManifestContent(mid, cursor) {
+    const params = {};
+    if (cursor !== void 0) params.cursor = cursor;
+    return this.get(`/api/v1/communication/content/${mid}`, Object.keys(params).length ? params : void 0);
+  }
+  /**
+   * 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`.
+   */
+  async manifestSend(request) {
+    return this.post("/api/v1/communication/manifest/send", request);
+  }
+  /**
+   * 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.
+   */
+  async getCommunicationProfile(agentId) {
+    return this.get(`/api/v1/agents/${agentId}/communication_profile`);
+  }
+  // ─────────────────────────────────────────────
+  // Session Layer (Phase 3)
+  // ─────────────────────────────────────────────
+  /**
+   * 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.
+   */
+  async inviteSession(targetAgentId, request) {
+    return this.post(`/api/v1/sessions/invite/${targetAgentId}`, request ?? {});
+  }
+  /**
+   * 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.
+   */
+  async acceptSession(sessionId) {
+    return this.post(`/api/v1/sessions/${sessionId}/accept`, {});
+  }
+  /**
+   * 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.
+   */
+  async rejectSession(sessionId) {
+    return this.post(`/api/v1/sessions/${sessionId}/reject`, {});
+  }
+  /**
+   * Close a session (either participant may close it).
+   *
+   * The other participant receives a `session_closed` WebSocket event.
+   *
+   * @param sessionId - Session ID.
+   */
+  async closeSession(sessionId) {
+    return this.delete(`/api/v1/sessions/${sessionId}`);
+  }
+  /**
+   * List pending session invitations for the authenticated agent.
+   *
+   * Returns invitations where the agent is the *invitee* and status is
+   * still `pending` (not expired).
+   */
+  async listPendingSessions() {
+    return this.get("/api/v1/sessions/pending");
+  }
+  /**
+   * 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`.
+   */
+  async ackManifest(agentId, mid) {
+    return this.post(`/api/v1/communication/manifest/${agentId}/${mid}/ack`);
+  }
+  /**
+   * 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.
+   */
+  async deleteManifest(agentId, mid) {
+    return this.delete(`/api/v1/communication/manifest/${agentId}/${mid}`);
+  }
+  // ============================================
   // Payment Discovery
   // ============================================
   /** Set agent's payment capability */

package/dist/index.mjs

@@ -76,10 +76,34 @@ var ACNClient = class {
   // ============================================
   // Agent Management
   // ============================================
-  /** Register a new agent */
+  /**
+   * Platform-managed agent registration (requires Auth0 token).
+   * For autonomous agents without Auth0, use joinACN() instead.
+   */
   async registerAgent(agent) {
     return this.post("/api/v1/agents/register", agent);
   }
+  /**
+   * 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;
+   * ```
+   */
+  async joinACN(request) {
+    return this.post("/api/v1/agents/join", request);
+  }
   /** Get agent by ID */
   async getAgent(agentId) {
     return this.get(`/api/v1/agents/${agentId}`);
@@ -151,12 +175,33 @@ var ACNClient = class {
   async sendMessage(request) {
     return this.post("/api/v1/communication/send", request);
   }
-  /** Broadcast message to multiple agents */
+  /** Broadcast message to multiple agents in a subnet */
   async broadcast(request) {
     return this.post("/api/v1/communication/broadcast", request);
   }
-  /** 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' }] },
+   * });
+   * ```
+   */
+  async broadcastByTag(request) {
+    return this.post("/api/v1/communication/broadcast-by-tag", request);
+  }
+  /**
+   * @deprecated The server-side /broadcast-by-skill endpoint no longer exists.
+   * Use broadcastByTag({ from_agent, tags: [skill], message }) instead.
+   */
   async broadcastBySkill(request) {
+    console.warn(
+      "broadcastBySkill() is deprecated: the server endpoint /broadcast-by-skill no longer exists. Use broadcastByTag({ from_agent, tags: [skill], message }) instead."
+    );
     return this.post("/api/v1/communication/broadcast-by-skill", request);
   }
   /**
@@ -177,6 +222,156 @@ var ACNClient = class {
     return this.get(`/api/v1/communication/history/${agentId}`, params);
   }
   // ============================================
+  // Manifest Queue (Phase 2/3)
+  // ============================================
+  /**
+   * 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).
+   */
+  async listManifest(agentId, options) {
+    const params = {};
+    if (options?.limit !== void 0) params.limit = options.limit;
+    if (options?.sinceMs !== void 0) params.since_ms = options.sinceMs;
+    if (options?.messageType !== void 0) params.type = options.messageType;
+    return this.get(`/api/v1/communication/manifest/${agentId}`, params);
+  }
+  /**
+   * 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`.
+   */
+  async fetchManifestContent(mid, cursor) {
+    const params = {};
+    if (cursor !== void 0) params.cursor = cursor;
+    return this.get(`/api/v1/communication/content/${mid}`, Object.keys(params).length ? params : void 0);
+  }
+  /**
+   * 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`.
+   */
+  async manifestSend(request) {
+    return this.post("/api/v1/communication/manifest/send", request);
+  }
+  /**
+   * 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.
+   */
+  async getCommunicationProfile(agentId) {
+    return this.get(`/api/v1/agents/${agentId}/communication_profile`);
+  }
+  // ─────────────────────────────────────────────
+  // Session Layer (Phase 3)
+  // ─────────────────────────────────────────────
+  /**
+   * 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.
+   */
+  async inviteSession(targetAgentId, request) {
+    return this.post(`/api/v1/sessions/invite/${targetAgentId}`, request ?? {});
+  }
+  /**
+   * 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.
+   */
+  async acceptSession(sessionId) {
+    return this.post(`/api/v1/sessions/${sessionId}/accept`, {});
+  }
+  /**
+   * 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.
+   */
+  async rejectSession(sessionId) {
+    return this.post(`/api/v1/sessions/${sessionId}/reject`, {});
+  }
+  /**
+   * Close a session (either participant may close it).
+   *
+   * The other participant receives a `session_closed` WebSocket event.
+   *
+   * @param sessionId - Session ID.
+   */
+  async closeSession(sessionId) {
+    return this.delete(`/api/v1/sessions/${sessionId}`);
+  }
+  /**
+   * List pending session invitations for the authenticated agent.
+   *
+   * Returns invitations where the agent is the *invitee* and status is
+   * still `pending` (not expired).
+   */
+  async listPendingSessions() {
+    return this.get("/api/v1/sessions/pending");
+  }
+  /**
+   * 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`.
+   */
+  async ackManifest(agentId, mid) {
+    return this.post(`/api/v1/communication/manifest/${agentId}/${mid}/ack`);
+  }
+  /**
+   * 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.
+   */
+  async deleteManifest(agentId, mid) {
+    return this.delete(`/api/v1/communication/manifest/${agentId}/${mid}`);
+  }
+  // ============================================
   // Payment Discovery
   // ============================================
   /** Set agent's payment capability */

package/package.json

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