acn-client 0.13.0 → 0.14.0

package/dist/index.d.mts

@@ -115,17 +115,17 @@ interface AgentSearchOptions {
     skills?: string;
     /** online (default) | offline | all. Public list does not include verification_code. */
     status?: AgentSearchStatus;
-    subnet_id?: string;
+    slug?: string;
 }
 /** Subnet information */
 interface SubnetInfo {
     /**
-     * Subnet identifier. The server wire field is `subnet_id`; some
-     * older responses may also surface `id`. Prefer `subnet_id` when
-     * present, falling back to `id`.
+     * Opaque UUID identifier from the persistence layer.
      */
     id: string;
-    /** Wire-side identifier (ADR-0003+ servers always emit this). */
+    /** URL-safe slug identifier (server wire field). */
+    slug?: string;
+    /** @deprecated Use `slug` instead. */
     subnet_id?: string;
     name: string;
     description?: string;
@@ -135,8 +135,16 @@ interface SubnetInfo {
     owner?: string;
     harness_url?: string;
     harness_registered?: boolean;
-    /** ADR-0003 — parent subnet when this is a nested child. */
+    /**
+     * Deprecated — ACL V6 B6: the server no longer emits the slug.
+     * Use `parent_id` (UUID) instead.  Kept for backward-compat parsing
+     * of responses from older server versions.
+     */
+    parent_slug?: string | null;
+    /** @deprecated Use `parent_slug` instead. */
     parent_subnet_id?: string | null;
+    /** ACL V6 B6 — parent subnet's opaque UUID. */
+    parent_id?: string | null;
     /** ADR-0003 — defaults to `'persistent'` on the server. */
     lifecycle?: SubnetLifecycle;
     /** ADR-0003 — bound task when `lifecycle === 'task_scoped'`. */
@@ -162,10 +170,10 @@ interface SubnetCreateRequest {
     metadata?: Record<string, unknown>;
     /**
      * ADR-0003 nested-subnet parent. When set, the new subnet becomes a
-     * child of `parent_subnet_id`. Single-layer cap: the parent itself
+     * child of `parent_slug`. Single-layer cap: the parent itself
      * must be top-level. Immutable after creation.
      */
-    parent_subnet_id?: string;
+    parent_slug?: string;
     /**
      * ADR-0003 lifecycle. Defaults to `'persistent'` when omitted.
      * `'task_scoped'` requires `linked_task_id` and the subnet
@@ -190,7 +198,7 @@ interface SubnetCreateRequest {
 /** Subnet creation response */
 interface SubnetCreateResponse {
     success: boolean;
-    subnet_id: string;
+    slug: string;
     message: string;
 }
 /** Subnet join-policy values. Immutable post-creation. */
@@ -204,7 +212,7 @@ interface SubnetAllowlistEntry {
 }
 /** Response envelope for `subnetAllowlistList` (owner only). */
 interface SubnetAllowlistListResponse {
-    subnet_id: string;
+    slug: string;
     entries: SubnetAllowlistEntry[];
     [key: string]: unknown;
 }
@@ -218,7 +226,7 @@ interface SubnetAllowlistListResponse {
  */
 interface SubnetJoinRequestRow {
     request_id: string;
-    subnet_id: string;
+    slug: string;
     kind: 'join_request' | 'allowlist_auto' | 'invitation';
     status: 'pending' | 'approved' | 'rejected' | 'withdrawn';
     initiated_by: string;
@@ -231,13 +239,13 @@ interface SubnetJoinRequestRow {
 }
 /** Response envelope for `subnetJoinRequestList` (owner only). */
 interface SubnetJoinRequestListResponse {
-    subnet_id: string;
+    slug: string;
     items: SubnetJoinRequestRow[];
     [key: string]: unknown;
 }
 /** Response envelope for `subnetInvitationList` (owner only). */
 interface SubnetInvitationListResponse {
-    subnet_id: string;
+    slug: string;
     items: SubnetJoinRequestRow[];
     [key: string]: unknown;
 }
@@ -552,7 +560,7 @@ interface Task {
     required_tags?: string[];
     /** Reward in numeric form — convenience alias, equals `parseFloat(reward)`. */
     reward_amount?: number;
-    subnet_id: string | null;
+    subnet_slug: string | null;
     created_at: string;
     deadline?: string | null;
     use_escrow?: boolean;
@@ -588,7 +596,7 @@ interface TaskCreateRequest {
     reward: string;
     /** Deadline in hours (1–2 160). Required. */
     deadline_hours: number;
-    subnet_id?: string | null;
+    subnet_slug?: string | null;
     /** Default: "credits" */
     reward_currency?: string;
     /** Default: 1 */
@@ -856,6 +864,7 @@ interface AllowlistListResponse {
     entries: AllowlistEntry[];
     total: number;
 }
+declare const KNOWN_INBOX_MESSAGE_STATUSES: readonly ["unread", "read", "processed"];
 
 /**
  * ACN HTTP Client
@@ -887,6 +896,7 @@ declare class ACNClient {
     private request;
     private get;
     private post;
+    private patch;
     private delete;
     /** Check if ACN server is healthy */
     health(): Promise<{
@@ -988,37 +998,37 @@ declare class ACNClient {
         subnets: SubnetInfo[];
     }>;
     /** Get subnet by ID */
-    getSubnet(subnetId: string): Promise<SubnetInfo>;
+    getSubnet(slug: string): Promise<SubnetInfo>;
     /**
      * 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.
      */
-    listChildren(parentSubnetId: string): Promise<SubnetInfo[]>;
+    listChildren(parentSlug: string): Promise<SubnetInfo[]>;
     /**
      * Promote a `task_scoped` subnet to `persistent` (ADR-0003).
      *
      * Owner-only. Idempotent — promoting an already-persistent subnet
      * returns its current state unchanged.
      */
-    promoteSubnet(subnetId: string): Promise<SubnetInfo>;
+    promoteSubnet(slug: string): Promise<SubnetInfo>;
     /** Delete a subnet you own (requires Agent API Key — only the owning agent can delete) */
-    deleteSubnet(subnetId: string): Promise<{
+    deleteSubnet(slug: string): Promise<{
         success: boolean;
     }>;
     /** Get agents in a subnet */
-    getSubnetAgents(subnetId: string): Promise<{
+    getSubnetAgents(slug: string): Promise<{
         agents: AgentInfo[];
     }>;
     /** Join agent to subnet */
-    joinSubnet(agentId: string, subnetId: string): Promise<{
+    joinSubnet(agentId: string, slug: string): Promise<{
         success: boolean;
     }>;
     /** Remove agent from subnet */
-    leaveSubnet(agentId: string, subnetId: string): Promise<{
+    leaveSubnet(agentId: string, slug: string): Promise<{
         success: boolean;
     }>;
     /** Get agent's subnets */
@@ -1026,7 +1036,7 @@ declare class ACNClient {
         subnets: string[];
     }>;
     /**
-     * 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
@@ -1036,24 +1046,24 @@ declare class ACNClient {
      * return 409 ALREADY_ON_ALLOWLIST (raised as an error, never
      * silently no-op'd).
      */
-    subnetAllowlistAdd(subnetId: string, agentId: string): Promise<SubnetAllowlistEntry>;
+    subnetAllowlistAdd(slug: string, agentId: string): Promise<SubnetAllowlistEntry>;
     /**
-     * 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.
      */
-    subnetAllowlistRemove(subnetId: string, agentId: string): Promise<void>;
+    subnetAllowlistRemove(slug: string, agentId: string): Promise<void>;
     /**
-     * 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.
      */
-    subnetAllowlistList(subnetId: string, options?: {
+    subnetAllowlistList(slug: string, options?: {
         limit?: number;
         offset?: number;
     }): Promise<SubnetAllowlistListResponse>;
@@ -1068,7 +1078,7 @@ declare class ACNClient {
      *
      * Optional `note` (≤500 chars) is recorded on the audit row.
      */
-    subnetJoinRequestApprove(subnetId: string, requestId: string, options?: {
+    subnetJoinRequestApprove(slug: string, requestId: string, options?: {
         note?: string;
     }): Promise<SubnetJoinRequestRow>;
     /**
@@ -1076,7 +1086,7 @@ declare class ACNClient {
      *
      * No membership change. `subnet.join_rejected` webhook fires.
      */
-    subnetJoinRequestReject(subnetId: string, requestId: string, options?: {
+    subnetJoinRequestReject(slug: string, requestId: string, options?: {
         note?: string;
     }): Promise<SubnetJoinRequestRow>;
     /**
@@ -1085,18 +1095,18 @@ declare class ACNClient {
      * Self-only — caller must be the agent who originally created
      * the request. `subnet.join_withdrawn` webhook fires.
      */
-    subnetJoinRequestWithdraw(subnetId: string, requestId: string, options?: {
+    subnetJoinRequestWithdraw(slug: string, requestId: string, options?: {
         note?: string;
     }): Promise<SubnetJoinRequestRow>;
     /**
-     * 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.
      */
-    subnetJoinRequestList(subnetId: string, options?: SubnetJoinRequestListOptions): Promise<SubnetJoinRequestListResponse>;
+    subnetJoinRequestList(slug: string, options?: SubnetJoinRequestListOptions): Promise<SubnetJoinRequestListResponse>;
     /**
      * Owner sends an invitation to `agentId` (or merges into a
      * pending join_request from the same target).
@@ -1109,7 +1119,7 @@ declare class ACNClient {
      *
      * Discriminate on `auto_resolved` to dispatch.
      */
-    subnetInvitationSend(subnetId: string, agentId: string, options?: {
+    subnetInvitationSend(slug: string, agentId: string, options?: {
         note?: string;
     }): Promise<SubnetInvitationSendResponse>;
     /**
@@ -1120,7 +1130,7 @@ declare class ACNClient {
      * gains the back-reference, and `subnet.invitation_accepted`
      * webhook fires.
      */
-    subnetInvitationAccept(subnetId: string, requestId: string, options?: {
+    subnetInvitationAccept(slug: string, requestId: string, options?: {
         note?: string;
     }): Promise<SubnetJoinRequestRow>;
     /**
@@ -1129,7 +1139,7 @@ declare class ACNClient {
      * No membership change. `subnet.invitation_rejected` webhook
      * fires.
      */
-    subnetInvitationReject(subnetId: string, requestId: string, options?: {
+    subnetInvitationReject(slug: string, requestId: string, options?: {
         note?: string;
     }): Promise<SubnetJoinRequestRow>;
     /**
@@ -1139,16 +1149,16 @@ declare class ACNClient {
      * `withdrawn` (not `rejected`) — distinct audit token so
      * consumers can tell "owner gave up" from "invitee said no".
      */
-    subnetInvitationCancel(subnetId: string, requestId: string, options?: {
+    subnetInvitationCancel(slug: string, requestId: string, options?: {
         note?: string;
     }): Promise<SubnetJoinRequestRow>;
     /**
-     * Owner lists invitation rows for `subnetId`.
+     * Owner lists invitation rows for `slug`.
      *
      * Owner-only — invitees use `agentSubnetInvitations` for their
      * own cross-subnet view.
      */
-    subnetInvitationList(subnetId: string, options?: SubnetInvitationListOptions): Promise<SubnetInvitationListResponse>;
+    subnetInvitationList(slug: string, options?: SubnetInvitationListOptions): Promise<SubnetInvitationListResponse>;
     /**
      * Invitee's cross-subnet pending-invitation list (self only).
      *
@@ -1220,6 +1230,33 @@ declare class ACNClient {
     }): Promise<{
         messages: Message[];
     }>;
+    /**
+     * 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.
+     */
+    ackInbox(agentId: string, routeIds: string[]): Promise<{
+        acked: number;
+    }>;
+    /**
+     * 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.
+     */
+    updateInboxMessageStatus(agentId: string, routeId: string, status: string): Promise<{
+        agent_id: string;
+        route_id: string;
+        status: string;
+    }>;
     /**
      * List manifest queue entries for the authenticated agent.
      *
@@ -1599,7 +1636,7 @@ declare class ACNClient {
      * Register (or clear) an org-harness webhook URL for a subnet.
      * Pass `harnessUrl: null` to deregister.
      */
-    registerSubnetHarness(subnetId: string, harnessUrl: string | null, harnessSecret?: string | null): Promise<void>;
+    registerSubnetHarness(slug: string, harnessUrl: string | null, harnessSecret?: string | null): Promise<void>;
 }
 /**
  * ACN API Error
@@ -1715,4 +1752,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 AgentJoinRequest, type AgentJoinResponse, type AgentRegisterRequest, type AgentRegisterResponse, type AgentSearchOptions, type AgentSearchResponse, type AgentSearchStatus, type AgentStatus, type AgentSubnetInvitationsResponse, type AllowlistActionResponse, type AllowlistEntry, type AllowlistListResponse, type ApiResponse, type AttentionFee, type AuditEvent, type AuditQueryOptions, type BroadcastBySkillRequest, type BroadcastByTagRequest, type BroadcastRequest, type BroadcastStrategy, type CommunicationPolicyMode, type CommunicationPolicyResponse, type CommunicationProfile, type ComponentHealth, type DashboardData, type FollowActionResponse, type FollowCheckResponse, KNOWN_PAYMENT_TASK_STATUSES, type ManifestContentResponse, type ManifestEntry, type ManifestListResponse, type ManifestMessageType, type ManifestSendRequest, type Message, type MessageType, type MetricsData, type Participation, type ParticipationListResponse, type PaymentCapability, type PaymentDiscoveryOptions, type PaymentMethod, type PaymentNetwork, type PaymentRoleStats, type PaymentStats, type PaymentTask, type PaymentTaskStatus, type PendingSessionsResponse, type SendMessageRequest, type SendMessageResponse, type SessionEntry, type SessionInviteRequest, type SessionStatus, type SubnetAllowlistEntry, type SubnetAllowlistListResponse, type SubnetChildrenListResponse, type SubnetCreateRequest, type SubnetCreateResponse, type SubnetHarnessRequest, type SubnetInfo, type SubnetInvitationListOptions, type SubnetInvitationListResponse, type SubnetInvitationSendResponse, type SubnetJoinPolicy, type SubnetJoinRequestListOptions, type SubnetJoinRequestListResponse, type SubnetJoinRequestRow, type SubnetLifecycle, type SystemHealth, type Task, type TaskAcceptResponse, type TaskCreateRequest, type TaskListOptions, type TaskListResponse, type TaskStatus, 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 AgentSearchStatus, type AgentStatus, type AgentSubnetInvitationsResponse, type AllowlistActionResponse, type AllowlistEntry, type AllowlistListResponse, type ApiResponse, type AttentionFee, type AuditEvent, type AuditQueryOptions, type BroadcastBySkillRequest, type BroadcastByTagRequest, type BroadcastRequest, type BroadcastStrategy, type CommunicationPolicyMode, type CommunicationPolicyResponse, type CommunicationProfile, type ComponentHealth, type DashboardData, type FollowActionResponse, type FollowCheckResponse, KNOWN_INBOX_MESSAGE_STATUSES, KNOWN_PAYMENT_TASK_STATUSES, type ManifestContentResponse, type ManifestEntry, type ManifestListResponse, type ManifestMessageType, type ManifestSendRequest, type Message, type MessageType, type MetricsData, type Participation, type ParticipationListResponse, type PaymentCapability, type PaymentDiscoveryOptions, type PaymentMethod, type PaymentNetwork, type PaymentRoleStats, type PaymentStats, type PaymentTask, type PaymentTaskStatus, type PendingSessionsResponse, type SendMessageRequest, type SendMessageResponse, type SessionEntry, type SessionInviteRequest, type SessionStatus, type SubnetAllowlistEntry, type SubnetAllowlistListResponse, type SubnetChildrenListResponse, type SubnetCreateRequest, type SubnetCreateResponse, type SubnetHarnessRequest, type SubnetInfo, type SubnetInvitationListOptions, type SubnetInvitationListResponse, type SubnetInvitationSendResponse, type SubnetJoinPolicy, type SubnetJoinRequestListOptions, type SubnetJoinRequestListResponse, type SubnetJoinRequestRow, type SubnetLifecycle, type SystemHealth, type Task, type TaskAcceptResponse, type TaskCreateRequest, type TaskListOptions, type TaskListResponse, type TaskStatus, type WSConnectionOptions, type WSEventHandler, type WSEventType, type WSMessage, type WSState, subscribeToACN };