acn-client 0.11.2 → 0.13.0

package/dist/index.js

@@ -194,6 +194,27 @@ var ACNClient = class {
   async unregisterAgent(agentId) {
     return this.delete(`/api/v1/agents/${agentId}`);
   }
+  /**
+   * Rotate the agent's API key (H1).
+   *
+   * Returns a fresh `acn_*` plaintext key exactly once. The old key
+   * stops working immediately — including any in-process auth caches
+   * the gateway holds for it. Update the local SDK's stored key with
+   * the returned value before the next request:
+   *
+   * ```ts
+   * const { api_key } = await client.rotateApiKey(agentId);
+   * client.config.apiKey = api_key; // or rebuild the client
+   * ```
+   *
+   * Authorization is dual-track on the server: any one of the agent's
+   * current key (the common scheduled-rotation path) or the owner's
+   * Auth0 JWT (the recovery path when the agent has lost its key) is
+   * accepted.
+   */
+  async rotateApiKey(agentId) {
+    return this.post(`/api/v1/agents/${agentId}/rotate-key`);
+  }
   /** Send agent heartbeat */
   async heartbeat(agentId) {
     return this.post(`/api/v1/agents/${agentId}/heartbeat`);
@@ -221,6 +242,29 @@ var ACNClient = class {
   async getSubnet(subnetId) {
     return this.get(`/api/v1/subnets/${subnetId}`);
   }
+  /**
+   * List immediate children of a subnet (ADR-0003).
+   *
+   * Wraps `GET /api/v1/subnets/{parentSubnetId}/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) {
+    const data = await this.get(
+      `/api/v1/subnets/${parentSubnetId}/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(subnetId) {
+    return this.post(`/api/v1/subnets/${subnetId}/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}`);
@@ -254,6 +298,207 @@ var ACNClient = class {
     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 `subnetId`'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(subnetId, agentId) {
+    return this.post(`/api/v1/subnets/${subnetId}/allowlist`, {
+      agent_id: agentId
+    });
+  }
+  /**
+   * Remove `agentId` from `subnetId`'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}`);
+  }
+  /**
+   * List `subnetId`'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) {
+    const params = {
+      limit: options?.limit ?? 100,
+      offset: options?.offset ?? 0
+    };
+    return this.get(`/api/v1/subnets/${subnetId}/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(subnetId, requestId, options) {
+    return this.post(
+      `/api/v1/subnets/${subnetId}/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(subnetId, requestId, options) {
+    return this.post(
+      `/api/v1/subnets/${subnetId}/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(subnetId, requestId, options) {
+    return this.request(
+      "DELETE",
+      `/api/v1/subnets/${subnetId}/join-requests/${requestId}`,
+      options?.note !== void 0 ? { body: { note: options.note } } : void 0
+    );
+  }
+  /**
+   * Owner lists join_request / allowlist_auto rows for `subnetId`.
+   *
+   * `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) {
+    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);
+  }
+  // ----- 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(subnetId, 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);
+  }
+  /**
+   * 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(subnetId, requestId, options) {
+    return this.post(
+      `/api/v1/subnets/${subnetId}/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(subnetId, requestId, options) {
+    return this.post(
+      `/api/v1/subnets/${subnetId}/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(subnetId, requestId, options) {
+    return this.request(
+      "DELETE",
+      `/api/v1/subnets/${subnetId}/invitations/${requestId}`,
+      options?.note !== void 0 ? { body: { note: options.note } } : void 0
+    );
+  }
+  /**
+   * Owner lists invitation rows for `subnetId`.
+   *
+   * Owner-only — invitees use `agentSubnetInvitations` for their
+   * own cross-subnet view.
+   */
+  async subnetInvitationList(subnetId, 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);
+  }
+  /**
+   * 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 */
@@ -899,6 +1144,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) */

package/dist/index.mjs

@@ -154,6 +154,27 @@ var ACNClient = class {
   async unregisterAgent(agentId) {
     return this.delete(`/api/v1/agents/${agentId}`);
   }
+  /**
+   * Rotate the agent's API key (H1).
+   *
+   * Returns a fresh `acn_*` plaintext key exactly once. The old key
+   * stops working immediately — including any in-process auth caches
+   * the gateway holds for it. Update the local SDK's stored key with
+   * the returned value before the next request:
+   *
+   * ```ts
+   * const { api_key } = await client.rotateApiKey(agentId);
+   * client.config.apiKey = api_key; // or rebuild the client
+   * ```
+   *
+   * Authorization is dual-track on the server: any one of the agent's
+   * current key (the common scheduled-rotation path) or the owner's
+   * Auth0 JWT (the recovery path when the agent has lost its key) is
+   * accepted.
+   */
+  async rotateApiKey(agentId) {
+    return this.post(`/api/v1/agents/${agentId}/rotate-key`);
+  }
   /** Send agent heartbeat */
   async heartbeat(agentId) {
     return this.post(`/api/v1/agents/${agentId}/heartbeat`);
@@ -181,6 +202,29 @@ var ACNClient = class {
   async getSubnet(subnetId) {
     return this.get(`/api/v1/subnets/${subnetId}`);
   }
+  /**
+   * List immediate children of a subnet (ADR-0003).
+   *
+   * Wraps `GET /api/v1/subnets/{parentSubnetId}/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) {
+    const data = await this.get(
+      `/api/v1/subnets/${parentSubnetId}/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(subnetId) {
+    return this.post(`/api/v1/subnets/${subnetId}/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}`);
@@ -214,6 +258,207 @@ var ACNClient = class {
     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 `subnetId`'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(subnetId, agentId) {
+    return this.post(`/api/v1/subnets/${subnetId}/allowlist`, {
+      agent_id: agentId
+    });
+  }
+  /**
+   * Remove `agentId` from `subnetId`'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}`);
+  }
+  /**
+   * List `subnetId`'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) {
+    const params = {
+      limit: options?.limit ?? 100,
+      offset: options?.offset ?? 0
+    };
+    return this.get(`/api/v1/subnets/${subnetId}/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(subnetId, requestId, options) {
+    return this.post(
+      `/api/v1/subnets/${subnetId}/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(subnetId, requestId, options) {
+    return this.post(
+      `/api/v1/subnets/${subnetId}/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(subnetId, requestId, options) {
+    return this.request(
+      "DELETE",
+      `/api/v1/subnets/${subnetId}/join-requests/${requestId}`,
+      options?.note !== void 0 ? { body: { note: options.note } } : void 0
+    );
+  }
+  /**
+   * Owner lists join_request / allowlist_auto rows for `subnetId`.
+   *
+   * `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) {
+    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);
+  }
+  // ----- 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(subnetId, 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);
+  }
+  /**
+   * 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(subnetId, requestId, options) {
+    return this.post(
+      `/api/v1/subnets/${subnetId}/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(subnetId, requestId, options) {
+    return this.post(
+      `/api/v1/subnets/${subnetId}/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(subnetId, requestId, options) {
+    return this.request(
+      "DELETE",
+      `/api/v1/subnets/${subnetId}/invitations/${requestId}`,
+      options?.note !== void 0 ? { body: { note: options.note } } : void 0
+    );
+  }
+  /**
+   * Owner lists invitation rows for `subnetId`.
+   *
+   * Owner-only — invitees use `agentSubnetInvitations` for their
+   * own cross-subnet view.
+   */
+  async subnetInvitationList(subnetId, 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);
+  }
+  /**
+   * 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 */
@@ -859,6 +1104,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) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acn-client",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "description": "Official TypeScript/JavaScript client for ACN (Agent Collaboration Network)",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -51,7 +51,7 @@
     "@types/node": "^20.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
-    "vitest": "^1.0.0"
+    "vitest": "^2.1.9"
   },
   "peerDependencies": {
     "typescript": ">=4.7.0"