acn-client 0.13.0 → 0.14.0

package/dist/index.mjs

@@ -83,6 +83,9 @@ var ACNClient = class {
   post(path, body) {
     return this.request("POST", path, { body });
   }
+  patch(path, body) {
+    return this.request("PATCH", path, { body });
+  }
   delete(path) {
     return this.request("DELETE", path);
   }
@@ -199,20 +202,20 @@ var ACNClient = class {
     return this.get("/api/v1/subnets");
   }
   /** Get subnet by ID */
-  async getSubnet(subnetId) {
-    return this.get(`/api/v1/subnets/${subnetId}`);
+  async getSubnet(slug) {
+    return this.get(`/api/v1/subnets/${slug}`);
   }
   /**
    * List immediate children of a subnet (ADR-0003).
    *
-   * Wraps `GET /api/v1/subnets/{parentSubnetId}/children`. Returns
+   * Wraps `GET /api/v1/subnets/{parentSlug}/children`. Returns
    * `SUBNET_NOT_FOUND` when the parent does not exist. Visibility
    * matches `listSubnets` — private children you cannot see are
    * omitted from the result set.
    */
-  async listChildren(parentSubnetId) {
+  async listChildren(parentSlug) {
     const data = await this.get(
-      `/api/v1/subnets/${parentSubnetId}/children`
+      `/api/v1/subnets/${parentSlug}/children`
     );
     return data.subnets;
   }
@@ -222,16 +225,16 @@ var ACNClient = class {
    * Owner-only. Idempotent — promoting an already-persistent subnet
    * returns its current state unchanged.
    */
-  async promoteSubnet(subnetId) {
-    return this.post(`/api/v1/subnets/${subnetId}/promote`);
+  async promoteSubnet(slug) {
+    return this.post(`/api/v1/subnets/${slug}/promote`);
   }
   /** 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}`);
+  async deleteSubnet(slug) {
+    return this.request("DELETE", `/api/v1/subnets/${slug}`);
   }
   /** Get agents in a subnet */
-  async getSubnetAgents(subnetId) {
-    return this.get(`/api/v1/subnets/${subnetId}/agents`);
+  async getSubnetAgents(slug) {
+    return this.get(`/api/v1/subnets/${slug}/agents`);
   }
   // ──────────────────────────────────────────────────────────────────────
   //  Subnet membership (agent-side)
@@ -246,12 +249,12 @@ var ACNClient = class {
   //  scheduled for removal. Requires ACN backend ≥ post-PR-#42.
   // ──────────────────────────────────────────────────────────────────────
   /** Join agent to subnet */
-  async joinSubnet(agentId, subnetId) {
-    return this.post(`/api/v1/agents/${agentId}/subnets/${subnetId}`);
+  async joinSubnet(agentId, slug) {
+    return this.post(`/api/v1/agents/${agentId}/subnets/${slug}`);
   }
   /** Remove agent from subnet */
-  async leaveSubnet(agentId, subnetId) {
-    return this.delete(`/api/v1/agents/${agentId}/subnets/${subnetId}`);
+  async leaveSubnet(agentId, slug) {
+    return this.delete(`/api/v1/agents/${agentId}/subnets/${slug}`);
   }
   /** Get agent's subnets */
   async getAgentSubnets(agentId) {
@@ -277,7 +280,7 @@ var ACNClient = class {
   // `/api/v1/agents/{a}/allowlist/{target}` and is unrelated).
   // ----- Allowlist (owner-only, 3 verbs) ---------------------------------
   /**
-   * Pre-authorise `agentId` on `subnetId`'s allowlist (owner only).
+   * Pre-authorise `agentId` on `slug`'s allowlist (owner only).
    *
    * Allowlisted agents skip the approval queue: their next
    * `joinSubnet` lands in branch 4 (allowlist hit) and becomes an
@@ -287,35 +290,35 @@ var ACNClient = class {
    * return 409 ALREADY_ON_ALLOWLIST (raised as an error, never
    * silently no-op'd).
    */
-  async subnetAllowlistAdd(subnetId, agentId) {
-    return this.post(`/api/v1/subnets/${subnetId}/allowlist`, {
+  async subnetAllowlistAdd(slug, agentId) {
+    return this.post(`/api/v1/subnets/${slug}/allowlist`, {
       agent_id: agentId
     });
   }
   /**
-   * Remove `agentId` from `subnetId`'s allowlist (owner only).
+   * Remove `agentId` from `slug`'s allowlist (owner only).
    *
    * Idempotent — removing an entry that doesn't exist still
    * returns 204. Per ADR-0004 §"Allowlist mutation does not
    * affect agents who already joined", this does NOT revoke
    * membership for agents already admitted via the allowlist.
    */
-  async subnetAllowlistRemove(subnetId, agentId) {
-    await this.delete(`/api/v1/subnets/${subnetId}/allowlist/${agentId}`);
+  async subnetAllowlistRemove(slug, agentId) {
+    await this.delete(`/api/v1/subnets/${slug}/allowlist/${agentId}`);
   }
   /**
-   * List `subnetId`'s allowlist entries (owner only).
+   * List `slug`'s allowlist entries (owner only).
    *
    * Owner-only by design — the allowlist is a privacy-sensitive
    * trust signal and exposing it publicly would leak relationship
    * metadata.
    */
-  async subnetAllowlistList(subnetId, options) {
+  async subnetAllowlistList(slug, options) {
     const params = {
       limit: options?.limit ?? 100,
       offset: options?.offset ?? 0
     };
-    return this.get(`/api/v1/subnets/${subnetId}/allowlist`, params);
+    return this.get(`/api/v1/subnets/${slug}/allowlist`, params);
   }
   // ----- Join requests (4 verbs: 3 owner-side + 1 applicant-side) --------
   /**
@@ -329,9 +332,9 @@ var ACNClient = class {
    *
    * Optional `note` (≤500 chars) is recorded on the audit row.
    */
-  async subnetJoinRequestApprove(subnetId, requestId, options) {
+  async subnetJoinRequestApprove(slug, requestId, options) {
     return this.post(
-      `/api/v1/subnets/${subnetId}/join-requests/${requestId}/approve`,
+      `/api/v1/subnets/${slug}/join-requests/${requestId}/approve`,
       options?.note !== void 0 ? { note: options.note } : void 0
     );
   }
@@ -340,9 +343,9 @@ var ACNClient = class {
    *
    * No membership change. `subnet.join_rejected` webhook fires.
    */
-  async subnetJoinRequestReject(subnetId, requestId, options) {
+  async subnetJoinRequestReject(slug, requestId, options) {
     return this.post(
-      `/api/v1/subnets/${subnetId}/join-requests/${requestId}/reject`,
+      `/api/v1/subnets/${slug}/join-requests/${requestId}/reject`,
       options?.note !== void 0 ? { note: options.note } : void 0
     );
   }
@@ -352,29 +355,29 @@ var ACNClient = class {
    * Self-only — caller must be the agent who originally created
    * the request. `subnet.join_withdrawn` webhook fires.
    */
-  async subnetJoinRequestWithdraw(subnetId, requestId, options) {
+  async subnetJoinRequestWithdraw(slug, requestId, options) {
     return this.request(
       "DELETE",
-      `/api/v1/subnets/${subnetId}/join-requests/${requestId}`,
+      `/api/v1/subnets/${slug}/join-requests/${requestId}`,
       options?.note !== void 0 ? { body: { note: options.note } } : void 0
     );
   }
   /**
-   * Owner lists join_request / allowlist_auto rows for `subnetId`.
+   * Owner lists join_request / allowlist_auto rows for `slug`.
    *
    * `kind` defaults to `'join_request'`; pass `'allowlist_auto'`
    * to inspect synthesised allowlist-hit audit rows. Server
    * rejects `kind='invitation'` with 400 INVALID_KIND_FILTER —
    * use `subnetInvitationList` instead.
    */
-  async subnetJoinRequestList(subnetId, options) {
+  async subnetJoinRequestList(slug, options) {
     const params = {
       kind: options?.kind ?? "join_request",
       limit: options?.limit ?? 100,
       offset: options?.offset ?? 0
     };
     if (options?.status !== void 0) params.status = options.status;
-    return this.get(`/api/v1/subnets/${subnetId}/join-requests`, params);
+    return this.get(`/api/v1/subnets/${slug}/join-requests`, params);
   }
   // ----- Invitations (5 + 1 verbs) ---------------------------------------
   /**
@@ -389,10 +392,10 @@ var ACNClient = class {
    *
    * Discriminate on `auto_resolved` to dispatch.
    */
-  async subnetInvitationSend(subnetId, agentId, options) {
+  async subnetInvitationSend(slug, agentId, options) {
     const body = { agent_id: agentId };
     if (options?.note !== void 0) body.note = options.note;
-    return this.post(`/api/v1/subnets/${subnetId}/invitations`, body);
+    return this.post(`/api/v1/subnets/${slug}/invitations`, body);
   }
   /**
    * Invitee accepts a pending invitation (CAS pending → approved).
@@ -402,9 +405,9 @@ var ACNClient = class {
    * gains the back-reference, and `subnet.invitation_accepted`
    * webhook fires.
    */
-  async subnetInvitationAccept(subnetId, requestId, options) {
+  async subnetInvitationAccept(slug, requestId, options) {
     return this.post(
-      `/api/v1/subnets/${subnetId}/invitations/${requestId}/accept`,
+      `/api/v1/subnets/${slug}/invitations/${requestId}/accept`,
       options?.note !== void 0 ? { note: options.note } : void 0
     );
   }
@@ -414,9 +417,9 @@ var ACNClient = class {
    * No membership change. `subnet.invitation_rejected` webhook
    * fires.
    */
-  async subnetInvitationReject(subnetId, requestId, options) {
+  async subnetInvitationReject(slug, requestId, options) {
     return this.post(
-      `/api/v1/subnets/${subnetId}/invitations/${requestId}/reject`,
+      `/api/v1/subnets/${slug}/invitations/${requestId}/reject`,
       options?.note !== void 0 ? { note: options.note } : void 0
     );
   }
@@ -427,26 +430,26 @@ var ACNClient = class {
    * `withdrawn` (not `rejected`) — distinct audit token so
    * consumers can tell "owner gave up" from "invitee said no".
    */
-  async subnetInvitationCancel(subnetId, requestId, options) {
+  async subnetInvitationCancel(slug, requestId, options) {
     return this.request(
       "DELETE",
-      `/api/v1/subnets/${subnetId}/invitations/${requestId}`,
+      `/api/v1/subnets/${slug}/invitations/${requestId}`,
       options?.note !== void 0 ? { body: { note: options.note } } : void 0
     );
   }
   /**
-   * Owner lists invitation rows for `subnetId`.
+   * Owner lists invitation rows for `slug`.
    *
    * Owner-only — invitees use `agentSubnetInvitations` for their
    * own cross-subnet view.
    */
-  async subnetInvitationList(subnetId, options) {
+  async subnetInvitationList(slug, options) {
     const params = {
       limit: options?.limit ?? 100,
       offset: options?.offset ?? 0
     };
     if (options?.status !== void 0) params.status = options.status;
-    return this.get(`/api/v1/subnets/${subnetId}/invitations`, params);
+    return this.get(`/api/v1/subnets/${slug}/invitations`, params);
   }
   /**
    * Invitee's cross-subnet pending-invitation list (self only).
@@ -511,6 +514,31 @@ var ACNClient = class {
     if (options?.consume) params.ack = true;
     return this.get(`/api/v1/communication/history/${agentId}`, params);
   }
+  /**
+   * Precisely acknowledge (remove) specific messages from the inbox.
+   *
+   * Unlike `getMessageHistory({ consume: true })` which clears the entire inbox,
+   * this method removes only the messages whose `route_id` values are listed.
+   *
+   * @param agentId   Must match the authenticated agent's ID.
+   * @param routeIds  List of `route_id` values to remove (up to 500).
+   * @returns         Number of messages actually removed.
+   */
+  async ackInbox(agentId, routeIds) {
+    return this.post(`/api/v1/communication/history/${agentId}/ack`, { route_ids: routeIds });
+  }
+  /**
+   * Update the lifecycle status of a specific inbox message.
+   *
+   * @param agentId  Must match the authenticated agent's ID.
+   * @param routeId  `route_id` of the target message (from inbox listing).
+   * @param status   New status: `"unread"` | `"read"` | `"processed"`.
+   * @returns        Object with `agent_id`, `route_id`, and `status`.
+   * @throws         404 (`inbox_message_not_found`) if route_id is absent from inbox.
+   */
+  async updateInboxMessageStatus(agentId, routeId, status) {
+    return this.patch(`/api/v1/communication/history/${agentId}/${routeId}`, { status });
+  }
   // ============================================
   // Manifest Queue (Phase 2/3)
   // ============================================
@@ -1087,8 +1115,8 @@ var ACNClient = class {
    * Register (or clear) an org-harness webhook URL for a subnet.
    * Pass `harnessUrl: null` to deregister.
    */
-  async registerSubnetHarness(subnetId, harnessUrl, harnessSecret) {
-    await this.request("PATCH", `/api/v1/subnets/${subnetId}/harness`, {
+  async registerSubnetHarness(slug, harnessUrl, harnessSecret) {
+    await this.request("PATCH", `/api/v1/subnets/${slug}/harness`, {
       body: {
         harness_url: harnessUrl,
         harness_secret: harnessSecret ?? null
@@ -1323,10 +1351,16 @@ var KNOWN_PAYMENT_TASK_STATUSES = [
   "payment_failed",
   "refunded"
 ];
+var KNOWN_INBOX_MESSAGE_STATUSES = [
+  "unread",
+  "read",
+  "processed"
+];
 export {
   ACNClient,
   ACNError,
   ACNRealtime,
+  KNOWN_INBOX_MESSAGE_STATUSES,
   KNOWN_PAYMENT_TASK_STATUSES,
   subscribeToACN
 };

package/package.json

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