acn-client 0.12.0 → 0.14.0

package/dist/index.js

@@ -33,6 +33,7 @@ __export(index_exports, {
   ACNClient: () => ACNClient,
   ACNError: () => ACNError,
   ACNRealtime: () => ACNRealtime,
+  KNOWN_INBOX_MESSAGE_STATUSES: () => KNOWN_INBOX_MESSAGE_STATUSES,
   KNOWN_PAYMENT_TASK_STATUSES: () => KNOWN_PAYMENT_TASK_STATUSES,
   subscribeToACN: () => subscribeToACN
 });
@@ -123,6 +124,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);
   }
@@ -239,16 +243,39 @@ 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/{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(parentSlug) {
+    const data = await this.get(
+      `/api/v1/subnets/${parentSlug}/children`
+    );
+    return data.subnets;
+  }
+  /**
+   * Promote a `task_scoped` subnet to `persistent` (ADR-0003).
+   *
+   * Owner-only. Idempotent — promoting an already-persistent subnet
+   * returns its current state unchanged.
+   */
+  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)
@@ -263,18 +290,219 @@ 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) {
     return this.get(`/api/v1/agents/${agentId}/subnets`);
   }
   // ============================================
+  // ADR-0004 Subnet Admission
+  // ============================================
+  //
+  // 13 verbs gated by `subnet.join_policy === 'approval'`:
+  //   - Allowlist (3): owner pre-authorisation.
+  //   - Join requests (4): applicant-initiated path.
+  //   - Invitations (5): owner-initiated path.
+  //   - Agent-side (1): invitee's cross-subnet pending view.
+  //
+  // The plain `joinSubnet` verb dispatches the six-branch decision
+  // tree on the server side — these methods are the admin-side
+  // controls used by subnet owners and the per-row decisions used
+  // by applicants and invitees.
+  //
+  // Method names use the `subnet*` prefix to avoid colliding with
+  // the existing inbox `addToAllowlist` surface (which lives at
+  // `/api/v1/agents/{a}/allowlist/{target}` and is unrelated).
+  // ----- Allowlist (owner-only, 3 verbs) ---------------------------------
+  /**
+   * 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
+   * immediate member with an `allowlist_auto` audit row.
+   *
+   * Server returns 201 with the persisted entry; duplicate adds
+   * return 409 ALREADY_ON_ALLOWLIST (raised as an error, never
+   * silently no-op'd).
+   */
+  async subnetAllowlistAdd(slug, agentId) {
+    return this.post(`/api/v1/subnets/${slug}/allowlist`, {
+      agent_id: agentId
+    });
+  }
+  /**
+   * 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(slug, agentId) {
+    await this.delete(`/api/v1/subnets/${slug}/allowlist/${agentId}`);
+  }
+  /**
+   * 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(slug, options) {
+    const params = {
+      limit: options?.limit ?? 100,
+      offset: options?.offset ?? 0
+    };
+    return this.get(`/api/v1/subnets/${slug}/allowlist`, params);
+  }
+  // ----- Join requests (4 verbs: 3 owner-side + 1 applicant-side) --------
+  /**
+   * Owner approves a pending join_request (CAS pending → approved).
+   *
+   * Side effects: applicant added to `subnet.member_agent_ids` and
+   * the `subnet.join_approved` webhook fires. The applicant is
+   * still expected to call `joinSubnet` to register the
+   * `agent.subnet_ids` back-reference (per ADR-0004 §"State
+   * machine edges").
+   *
+   * Optional `note` (≤500 chars) is recorded on the audit row.
+   */
+  async subnetJoinRequestApprove(slug, requestId, options) {
+    return this.post(
+      `/api/v1/subnets/${slug}/join-requests/${requestId}/approve`,
+      options?.note !== void 0 ? { note: options.note } : void 0
+    );
+  }
+  /**
+   * Owner rejects a pending join_request (CAS pending → rejected).
+   *
+   * No membership change. `subnet.join_rejected` webhook fires.
+   */
+  async subnetJoinRequestReject(slug, requestId, options) {
+    return this.post(
+      `/api/v1/subnets/${slug}/join-requests/${requestId}/reject`,
+      options?.note !== void 0 ? { note: options.note } : void 0
+    );
+  }
+  /**
+   * Applicant withdraws their own pending join_request.
+   *
+   * Self-only — caller must be the agent who originally created
+   * the request. `subnet.join_withdrawn` webhook fires.
+   */
+  async subnetJoinRequestWithdraw(slug, requestId, options) {
+    return this.request(
+      "DELETE",
+      `/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 `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(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/${slug}/join-requests`, params);
+  }
+  // ----- Invitations (5 + 1 verbs) ---------------------------------------
+  /**
+   * Owner sends an invitation to `agentId` (or merges into a
+   * pending join_request from the same target).
+   *
+   * Two response shapes per ADR-0004 §"Invitation merge path":
+   *
+   *   - **Normal path** (server returns 202): `{ invitation_id, status: 'pending' }`.
+   *   - **Merge path**  (server returns 200, request auto-approved):
+   *     `{ auto_resolved: true, resolved_kind: 'join_request', request_id }`.
+   *
+   * Discriminate on `auto_resolved` to dispatch.
+   */
+  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/${slug}/invitations`, body);
+  }
+  /**
+   * Invitee accepts a pending invitation (CAS pending → approved).
+   *
+   * Self-only against the row's `agent_id`. Side effects: invitee
+   * added to `subnet.member_agent_ids`, the agent's `subnet_ids`
+   * gains the back-reference, and `subnet.invitation_accepted`
+   * webhook fires.
+   */
+  async subnetInvitationAccept(slug, requestId, options) {
+    return this.post(
+      `/api/v1/subnets/${slug}/invitations/${requestId}/accept`,
+      options?.note !== void 0 ? { note: options.note } : void 0
+    );
+  }
+  /**
+   * Invitee rejects a pending invitation (CAS pending → rejected).
+   *
+   * No membership change. `subnet.invitation_rejected` webhook
+   * fires.
+   */
+  async subnetInvitationReject(slug, requestId, options) {
+    return this.post(
+      `/api/v1/subnets/${slug}/invitations/${requestId}/reject`,
+      options?.note !== void 0 ? { note: options.note } : void 0
+    );
+  }
+  /**
+   * Owner cancels a pending invitation (CAS pending → withdrawn).
+   *
+   * Owner-only counterpart to applicant withdraw. The row goes to
+   * `withdrawn` (not `rejected`) — distinct audit token so
+   * consumers can tell "owner gave up" from "invitee said no".
+   */
+  async subnetInvitationCancel(slug, requestId, options) {
+    return this.request(
+      "DELETE",
+      `/api/v1/subnets/${slug}/invitations/${requestId}`,
+      options?.note !== void 0 ? { body: { note: options.note } } : void 0
+    );
+  }
+  /**
+   * Owner lists invitation rows for `slug`.
+   *
+   * Owner-only — invitees use `agentSubnetInvitations` for their
+   * own cross-subnet view.
+   */
+  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/${slug}/invitations`, params);
+  }
+  /**
+   * Invitee's cross-subnet pending-invitation list (self only).
+   *
+   * Returns only `status='pending'` rows. Historical decisions
+   * are queryable per-subnet through the owner-only
+   * `subnetInvitationList`.
+   */
+  async agentSubnetInvitations(agentId) {
+    return this.get(`/api/v1/agents/${agentId}/subnet-invitations`);
+  }
+  // ============================================
   // Communication
   // ============================================
   /** Send message to an agent */
@@ -327,6 +555,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)
   // ============================================
@@ -903,8 +1156,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
@@ -920,6 +1173,7 @@ var ACNError = class extends Error {
     this.errorCode = options?.errorCode;
     this.requestId = options?.requestId;
   }
+  status;
   /** ACN internal error code (present on sanitised 5xx responses) */
   errorCode;
   /** Request ID minted by ACN for 5xx responses (useful for support) */
@@ -1138,11 +1392,17 @@ var KNOWN_PAYMENT_TASK_STATUSES = [
   "payment_failed",
   "refunded"
 ];
+var KNOWN_INBOX_MESSAGE_STATUSES = [
+  "unread",
+  "read",
+  "processed"
+];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ACNClient,
   ACNError,
   ACNRealtime,
+  KNOWN_INBOX_MESSAGE_STATUSES,
   KNOWN_PAYMENT_TASK_STATUSES,
   subscribeToACN
 });