@teneo-protocol/sdk 2.0.0 → 2.2.0

package/src/handlers/message-handlers/types.ts

@@ -7,6 +7,24 @@ import { z } from "zod";
 import { BaseMessage, MessageType, Logger, WebhookEventType } from "../../types";
 import { FormattedResponse } from "../../formatters/response-formatter";
 import { PrivateKeyAccount } from "viem/accounts";
+import type { RoomManager } from "../../managers/room-manager";
+import type { RoomManagementManager } from "../../managers/room-management-manager";
+import type { AgentRoomManager } from "../../managers/agent-room-manager";
+import type { AdminManager } from "../../managers/admin-manager";
+import type { AgentRegistry } from "../../managers/agent-registry";
+
+// Re-export connection and auth state types from main config
+// These types define the shape of state used by handlers
+import type {
+  ConnectionState as ConfigConnectionState,
+  AuthenticationState as ConfigAuthenticationState
+} from "../../types/config";
+
+/** Connection state for the WebSocket client (re-exported from config) */
+export type ConnectionState = ConfigConnectionState;
+
+/** Authentication state (re-exported from config) */
+export type AuthState = ConfigAuthenticationState;
 
 /**
  * Context provided to message handlers
@@ -14,10 +32,14 @@ import { PrivateKeyAccount } from "viem/accounts";
  */
 export interface HandlerContext {
   // Event emission
-  emit: (event: string, ...args: any[]) => void;
+  emit: (event: string, ...args: unknown[]) => void;
 
   // Webhook delivery
-  sendWebhook: (type: WebhookEventType, data: any, metadata?: any) => Promise<void>;
+  sendWebhook: (
+    type: WebhookEventType,
+    data: Record<string, unknown>,
+    metadata?: Record<string, unknown>
+  ) => Promise<void>;
 
   // Response formatting (optional)
   formatResponse?: (message: BaseMessage) => FormattedResponse;
@@ -26,19 +48,25 @@ export interface HandlerContext {
   logger: Logger;
 
   // State access
-  getConnectionState: () => any;
-  getAuthState: () => any;
-  updateConnectionState: (update: any) => void;
-  updateAuthState: (update: any) => void;
+  getConnectionState: () => ConnectionState;
+  getAuthState: () => AuthState;
+  updateConnectionState: (update: Partial<ConnectionState>) => void;
+  updateAuthState: (update: Partial<AuthState>) => void;
 
   // Room manager for subscription updates (optional)
-  roomManager?: any;
+  roomManager?: RoomManager;
 
   // Room management manager for CRUD operations (v2.0.0, optional)
-  roomManagementManager?: any;
+  roomManagementManager?: RoomManagementManager;
 
   // Agent room manager for agent-room operations (v2.0.0, optional)
-  agentRoomManager?: any;
+  agentRoomManager?: AgentRoomManager;
+
+  // Admin manager for admin-only features (optional)
+  adminManager?: AdminManager;
+
+  // Agent registry for agent details lookups (optional)
+  agentRegistry?: AgentRegistry;
 
   // Account for signing (optional, for auth handlers)
   account?: PrivateKeyAccount;

package/src/handlers/message-handlers/unsubscribe-response-handler.ts

@@ -3,7 +3,8 @@
  * Processes room unsubscription confirmations
  */
 
-import { UnsubscribeResponse, UnsubscribeResponseSchema } from "../../types";
+import { UnsubscribeResponse, UnsubscribeResponseSchema, ErrorCode } from "../../types";
+import { SDKError } from "../../types/events";
 import { BaseMessageHandler } from "./base-handler";
 import { HandlerContext } from "./types";
 
@@ -41,7 +42,16 @@ export class UnsubscribeResponseHandler extends BaseMessageHandler<UnsubscribeRe
       });
 
       // Emit error event
-      this.emit(context, "error", new Error(`Unsubscription failed: ${message.data.message}`));
+      this.emit(
+        context,
+        "error",
+        new SDKError(
+          `Unsubscription failed: ${message.data.message}`,
+          ErrorCode.OPERATION_FAILED,
+          { roomId: message.data.room_id },
+          true
+        )
+      );
     }
   }
 }

package/src/handlers/message-handlers/user-authenticated-handler.ts

@@ -0,0 +1,31 @@
+/**
+ * Handler for user_authenticated messages
+ * Processes user authentication broadcasts for presence tracking
+ */
+
+import { UserAuthenticatedMessage, UserAuthenticatedMessageSchema } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class UserAuthenticatedHandler extends BaseMessageHandler<UserAuthenticatedMessage> {
+  readonly type = "user_authenticated" as const;
+  readonly schema = UserAuthenticatedMessageSchema;
+
+  protected handleValidated(message: UserAuthenticatedMessage, context: HandlerContext): void {
+    const { wallet } = message.data;
+
+    context.logger.debug("Handling user_authenticated", {
+      wallet
+    });
+
+    context.logger.info("User authenticated broadcast received", {
+      wallet
+    });
+
+    // Emit presence event
+    this.emit(context, "user:authenticated", { wallet });
+
+    // Send webhook
+    this.sendWebhook(context, "user_authenticated", message.data);
+  }
+}

package/src/handlers/message-handlers/user-count-handler.ts

@@ -0,0 +1,34 @@
+/**
+ * Handler for user_count messages (Admin only)
+ * Processes user count broadcasts to admin users
+ */
+
+import { UserCountMessage, UserCountMessageSchema } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class UserCountHandler extends BaseMessageHandler<UserCountMessage> {
+  readonly type = "user_count" as const;
+  readonly schema = UserCountMessageSchema;
+
+  protected handleValidated(message: UserCountMessage, context: HandlerContext): void {
+    const { count, timestamp } = message.data;
+
+    context.logger.debug("Handling user_count", {
+      count,
+      timestamp
+    });
+
+    // Delegate to admin manager if available
+    const adminManager = context.adminManager;
+    if (adminManager && typeof adminManager.handleUserCount === "function") {
+      adminManager.handleUserCount(message.data);
+    }
+
+    // Emit admin event
+    this.emit(context, "admin:user_count", { count, timestamp });
+
+    // Send webhook
+    this.sendWebhook(context, "user_count", message.data);
+  }
+}

package/src/handlers/webhook-handler.test.ts

@@ -15,11 +15,12 @@ describe("WebhookHandler", () => {
   let handler: WebhookHandler;
   let mockConfig: SDKConfig;
   let mockLogger: Logger;
-  let mockFetch: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let mockFetch: ReturnType<typeof vi.fn>;
 
   beforeEach(() => {
     vi.useFakeTimers();
-    mockFetch = fetch as any;
+    mockFetch = fetch as unknown as ReturnType<typeof vi.fn>;
     mockFetch.mockClear();
 
     mockConfig = {

package/src/handlers/webhook-handler.ts

@@ -166,7 +166,11 @@ export class WebhookHandler extends EventEmitter<SDKEvents> {
    * });
    * ```
    */
-  public async sendWebhook(eventType: WebhookEventType, data: any, metadata?: any): Promise<void> {
+  public async sendWebhook(
+    eventType: WebhookEventType,
+    data: Record<string, unknown>,
+    metadata?: Record<string, unknown>
+  ): Promise<void> {
     if (!this.webhookConfig || this.isDestroyed) {
       return;
     }
@@ -388,7 +392,7 @@ export class WebhookHandler extends EventEmitter<SDKEvents> {
           ...this.webhookConfig.headers
         },
         body: JSON.stringify(item.payload),
-        signal: controller.signal as any
+        signal: controller.signal as AbortSignal
       };
 
       const response = await fetch(this.webhookConfig.url, options);
@@ -408,13 +412,14 @@ export class WebhookHandler extends EventEmitter<SDKEvents> {
 
       this.emit("webhook:sent", item.payload, this.webhookConfig.url);
       this.emit("webhook:success", responseData, this.webhookConfig.url);
-    } catch (error: any) {
-      if (error.name === "AbortError") {
+    } catch (error: unknown) {
+      const err = error as Error;
+      if (err.name === "AbortError") {
         throw new WebhookError("Webhook timeout", {
           timeout: this.webhookConfig.timeout
         });
       }
-      throw new WebhookError(`Webhook delivery failed: ${error.message}`, error);
+      throw new WebhookError(`Webhook delivery failed: ${err.message}`, error);
     } finally {
       clearTimeout(timeout);
     }
@@ -434,8 +439,9 @@ export class WebhookHandler extends EventEmitter<SDKEvents> {
       // Use comprehensive SSRF validator
       // allowInsecureWebhooks controls whether localhost/HTTP is allowed
       validateSSRF(url, this.config.allowInsecureWebhooks ?? false);
-    } catch (error: any) {
-      throw new WebhookError(`Webhook URL validation failed: ${error.message}`, { url });
+    } catch (error: unknown) {
+      const err = error as Error;
+      throw new WebhookError(`Webhook URL validation failed: ${err.message}`, { url });
     }
   }
 

package/src/index.ts

@@ -202,6 +202,7 @@ export {
   RateLimitError,
   SignatureVerificationError,
   ConfigurationError,
+  PaymentError,
 
   // Validation helpers
   validateEventData,
@@ -232,6 +233,26 @@ export {
  */
 export { SecurePrivateKey } from "./utils/secure-private-key";
 
+/**
+ * Payment utilities for x402 payment signing
+ * Enables SDK users to make payments directly using private keys
+ */
+export {
+  PaymentClient,
+  type PaymentClientConfig,
+  PEAQ_CHAIN_ID,
+  USDC_CONTRACT,
+  DEFAULT_PAY_TO_ADDRESS,
+  DEFAULT_RPC_URL,
+  USDC_DECIMALS,
+  X402_VERSION,
+  DEFAULT_PAYMENT_TIMEOUT_SECONDS,
+  buildX402ResourceUrl,
+  usdcToUnits,
+  unitsToUsdc,
+  type SupportedChain
+} from "./payments";
+
 /**
  * SDK version string
  */

package/src/managers/admin-manager.ts

@@ -0,0 +1,249 @@
+/**
+ * AdminManager - Manages admin-only features
+ * Provides access to admin APIs like listing all agents, user counts, etc.
+ * Only available to users with admin privileges.
+ */
+
+import { EventEmitter } from "eventemitter3";
+import { WebSocketClient } from "../core/websocket-client";
+import { Logger, AdminAgentInfo, UserCountData } from "../types";
+import { SDKError } from "../types/events";
+import { ErrorCode } from "../types/error-codes";
+
+/**
+ * Events emitted by the AdminManager
+ */
+export interface AdminManagerEvents {
+  /** Emitted when user count is updated (broadcast to admins) */
+  user_count: (data: UserCountData) => void;
+  /** Emitted when admin status changes */
+  status_changed: (isAdmin: boolean) => void;
+}
+
+/**
+ * Options for listing all agents (admin only)
+ */
+export interface ListAllAgentsOptions {
+  /** Filter string for agent search */
+  filter?: string;
+  /** Pagination offset */
+  offset?: number;
+  /** Number of agents to return (default: 50) */
+  limit?: number;
+}
+
+/**
+ * Response from listing all agents
+ */
+export interface AllAgentsResult {
+  /** List of agents */
+  agents: AdminAgentInfo[];
+  /** Total number of agents matching filter */
+  total: number;
+  /** Current offset */
+  offset: number;
+  /** Page size */
+  limit: number;
+  /** Whether there are more agents to load */
+  hasMore: boolean;
+  /** Applied filter (if any) */
+  filter?: string;
+}
+
+/**
+ * Pending request waiting for response
+ */
+interface PendingRequest<T> {
+  resolve: (result: T) => void;
+  reject: (error: Error) => void;
+  timeout: ReturnType<typeof setTimeout>;
+}
+
+export class AdminManager extends EventEmitter<AdminManagerEvents> {
+  private readonly wsClient: WebSocketClient;
+  private readonly logger: Logger;
+  private _isAdmin: boolean = false;
+  private readonly pendingListRequests = new Map<string, PendingRequest<AllAgentsResult>>();
+  private lastUserCount: UserCountData | null = null;
+
+  /** Default timeout for requests (30 seconds) */
+  private readonly requestTimeout = 30000;
+
+  constructor(wsClient: WebSocketClient, logger: Logger) {
+    super();
+    this.wsClient = wsClient;
+    this.logger = logger;
+  }
+
+  /**
+   * Whether the current user has admin privileges.
+   */
+  public get isAdmin(): boolean {
+    return this._isAdmin;
+  }
+
+  /**
+   * Sets the admin status. Called internally after authentication.
+   * @internal
+   */
+  public setAdminStatus(isAdmin: boolean): void {
+    const changed = this._isAdmin !== isAdmin;
+    this._isAdmin = isAdmin;
+
+    if (changed) {
+      this.logger.info("AdminManager: Admin status changed", { isAdmin });
+      this.emit("status_changed", isAdmin);
+    }
+  }
+
+  /**
+   * Lists all agents in the network (admin only).
+   * Returns paginated list of agents with full admin information.
+   *
+   * @param options - Pagination and filter options
+   * @returns Promise that resolves with agents list
+   * @throws {SDKError} If not connected or not an admin
+   *
+   * @example
+   * ```typescript
+   * if (sdk.admin?.isAdmin) {
+   *   const result = await sdk.admin.listAllAgents({ limit: 20 });
+   *   console.log(`Found ${result.total} agents`);
+   *   result.agents.forEach(agent => {
+   *     console.log(`${agent.agent_name}: verified=${agent.is_verified}, banned=${agent.is_banned}`);
+   *   });
+   * }
+   * ```
+   */
+  public async listAllAgents(options: ListAllAgentsOptions = {}): Promise<AllAgentsResult> {
+    if (!this.wsClient.isConnected) {
+      throw new SDKError("Not connected to Teneo Protocol", ErrorCode.NOT_CONNECTED);
+    }
+
+    if (!this._isAdmin) {
+      throw new SDKError("Admin privileges required", ErrorCode.AUTH_ERROR);
+    }
+
+    const { filter, offset = 0, limit = 50 } = options;
+
+    this.logger.info("AdminManager: Listing all agents", { filter, offset, limit });
+
+    // Generate request ID
+    const requestId = `admin_list_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+
+    // Send list_all_agents message
+    const message = {
+      type: "list_all_agents" as const,
+      filter,
+      offset,
+      limit,
+      request_id: requestId
+    };
+
+    await this.wsClient.sendMessage(message);
+
+    // Wait for response
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingListRequests.delete(requestId);
+        reject(new SDKError("List agents request timed out", ErrorCode.TIMEOUT_ERROR));
+      }, this.requestTimeout);
+
+      this.pendingListRequests.set(requestId, { resolve, reject, timeout });
+    });
+  }
+
+  /**
+   * Gets the last received user count.
+   *
+   * @returns The last user count data, or null if not received yet
+   */
+  public getLastUserCount(): UserCountData | null {
+    return this.lastUserCount;
+  }
+
+  /**
+   * Handles incoming all_agents_response message from server.
+   * @internal
+   */
+  public handleAllAgentsResponse(
+    data: {
+      agents: AdminAgentInfo[];
+      total: number;
+      offset: number;
+      limit: number;
+      has_more: boolean;
+      filter?: string;
+    },
+    requestId?: string
+  ): void {
+    this.logger.debug("AdminManager: Received agents list", {
+      count: data.agents.length,
+      total: data.total,
+      requestId
+    });
+
+    const result: AllAgentsResult = {
+      agents: data.agents,
+      total: data.total,
+      offset: data.offset,
+      limit: data.limit,
+      hasMore: data.has_more,
+      filter: data.filter
+    };
+
+    // Resolve pending request - prefer matching by request_id if available
+    if (requestId && this.pendingListRequests.has(requestId)) {
+      // Exact match by request_id (preferred)
+      const pending = this.pendingListRequests.get(requestId)!;
+      clearTimeout(pending.timeout);
+      this.pendingListRequests.delete(requestId);
+      pending.resolve(result);
+    } else if (this.pendingListRequests.size > 0) {
+      // Fallback to FIFO for backwards compatibility (when server doesn't echo request_id)
+      const pendingEntries = Array.from(this.pendingListRequests.entries());
+      const [fallbackRequestId, pending] = pendingEntries[0];
+      this.logger.warn("AdminManager: Using FIFO fallback for list agents correlation", {
+        pendingCount: pendingEntries.length
+      });
+      clearTimeout(pending.timeout);
+      this.pendingListRequests.delete(fallbackRequestId);
+      pending.resolve(result);
+    }
+  }
+
+  /**
+   * Handles incoming user_count message from server.
+   * @internal
+   */
+  public handleUserCount(data: UserCountData): void {
+    this.logger.debug("AdminManager: Received user count", { count: data.count });
+
+    this.lastUserCount = data;
+    this.emit("user_count", data);
+  }
+
+  /**
+   * Clears all cached data and pending requests.
+   */
+  public clear(): void {
+    // Clear pending requests
+    for (const [, pending] of this.pendingListRequests) {
+      clearTimeout(pending.timeout);
+      pending.reject(new SDKError("Admin manager cleared", ErrorCode.SDK_DESTROYED));
+    }
+    this.pendingListRequests.clear();
+
+    this.lastUserCount = null;
+  }
+
+  /**
+   * Destroys the admin manager and cleans up resources.
+   */
+  public destroy(): void {
+    this.logger.info("AdminManager: Destroying");
+    this.clear();
+    this._isAdmin = false;
+    this.removeAllListeners();
+  }
+}

package/src/managers/agent-registry.test.ts

@@ -59,7 +59,8 @@ describe("AgentRegistry", () => {
       registry.updateAgents([agent]);
 
       const agents = registry.getAgents();
-      const firstAgent = agents[0] as any;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const firstAgent = agents[0] as Record<string, any>;
 
       // Mutate returned object
       firstAgent.name = "Modified";