@teneo-protocol/sdk 3.1.5 → 3.3.0

package/src/core/websocket-client.ts

@@ -19,6 +19,7 @@ import {
   BaseMessageSchema,
   createRequestChallenge,
   createCheckCachedAuth,
+  createApiKeyAuth,
   createPing,
   safeParseMessage,
   Logger
@@ -606,7 +607,7 @@ export class WebSocketClient extends EventEmitter<SDKEvents> {
    * Authenticate with the server
    */
   private async authenticate(): Promise<void> {
-    if (!this.account && !this.config.walletAddress) {
+    if (!this.account && !this.config.walletAddress && !this.config.apiKey) {
       this.logger.info("No authentication configured, continuing without auth");
       this.updateAuthState({ authenticated: false });
       this.emit("ready");
@@ -614,6 +615,22 @@ export class WebSocketClient extends EventEmitter<SDKEvents> {
     }
 
     try {
+      // API-key auth: single message, no challenge-response needed
+      if (this.config.apiKey) {
+        const address = this.account?.address || this.config.walletAddress;
+        if (!address) {
+          throw new AuthenticationError("walletAddress is required for API-key authentication");
+        }
+
+        this.logger.debug("Authenticating with API key");
+        await this.sendMessage(
+          createApiKeyAuth(address, this.config.apiKey, this.config.clientType || "user")
+        );
+
+        await this.waitForAuthCompletion();
+        return;
+      }
+
       // Check for cached authentication first
       if (this.config.walletAddress) {
         const sessionToken = this.authState.sessionToken;
@@ -631,7 +648,7 @@ export class WebSocketClient extends EventEmitter<SDKEvents> {
         }
       }
 
-      // Request challenge
+      // Challenge-response auth (requires privateKey)
       this.logger.debug("Requesting authentication challenge");
       await this.sendMessage(
         createRequestChallenge(
@@ -641,49 +658,53 @@ export class WebSocketClient extends EventEmitter<SDKEvents> {
       );
 
       // Wait for authentication to complete
-      await new Promise<void>((resolve, reject) => {
-        let timeout: NodeJS.Timeout | undefined;
-        const pollTimeouts: NodeJS.Timeout[] = [];
-
-        // Centralized cleanup function - guarantees cleanup in all scenarios
-        const cleanup = () => {
-          if (timeout) {
-            clearTimeout(timeout);
-            timeout = undefined;
-          }
-          // Clear all polling timeouts
-          pollTimeouts.forEach((t) => clearTimeout(t));
-          pollTimeouts.length = 0;
-        };
-
-        // Set main authentication timeout
-        timeout = setTimeout(() => {
-          cleanup();
-          reject(new AuthenticationError("Authentication timeout"));
-        }, TIMEOUTS.AUTH_TIMEOUT);
-
-        const checkAuth = () => {
-          if (this.authState.authenticated) {
-            cleanup();
-            resolve();
-          } else if (this.connectionState.lastError) {
-            cleanup();
-            reject(this.connectionState.lastError);
-          } else {
-            // Store polling timeout for cleanup
-            const pollTimeout = setTimeout(checkAuth, TIMEOUTS.AUTH_POLL_INTERVAL);
-            pollTimeouts.push(pollTimeout);
-          }
-        };
-
-        checkAuth();
-      });
+      await this.waitForAuthCompletion();
     } catch (error) {
       this.logger.error("Authentication failed", error);
       throw new AuthenticationError("Failed to authenticate", error);
     }
   }
 
+  /**
+   * Waits for authentication state to become authenticated.
+   * Used by both API-key and challenge-response auth flows.
+   */
+  private async waitForAuthCompletion(): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+      let timeout: NodeJS.Timeout | undefined;
+      const pollTimeouts: NodeJS.Timeout[] = [];
+
+      const cleanup = () => {
+        if (timeout) {
+          clearTimeout(timeout);
+          timeout = undefined;
+        }
+        pollTimeouts.forEach((t) => clearTimeout(t));
+        pollTimeouts.length = 0;
+      };
+
+      timeout = setTimeout(() => {
+        cleanup();
+        reject(new AuthenticationError("Authentication timeout"));
+      }, TIMEOUTS.AUTH_TIMEOUT);
+
+      const checkAuth = () => {
+        if (this.authState.authenticated) {
+          cleanup();
+          resolve();
+        } else if (this.connectionState.lastError) {
+          cleanup();
+          reject(this.connectionState.lastError);
+        } else {
+          const pollTimeout = setTimeout(checkAuth, TIMEOUTS.AUTH_POLL_INTERVAL);
+          pollTimeouts.push(pollTimeout);
+        }
+      };
+
+      checkAuth();
+    });
+  }
+
   /**
    * Create handler context with all dependencies
    */

package/src/formatters/response-formatter.ts

@@ -456,7 +456,17 @@ export class ResponseFormatter {
       if (agent.commands && agent.commands.length > 0) {
         result += "\n   Commands:";
         for (const cmd of agent.commands) {
-          result += `\n      - ${cmd.trigger}${cmd.argument ? ` ${cmd.argument}` : ""}`;
+          const paramUsage = cmd.parameters?.length && !cmd.argument
+            ? " " + cmd.parameters.map((p: any) => p.required !== false ? `<${p.name}>` : `[${p.name}]`).join(" ")
+            : cmd.argument ? ` ${cmd.argument}` : "";
+          result += `\n      - ${cmd.trigger}${paramUsage}`;
+          if (cmd.parameters?.length) {
+            for (const p of cmd.parameters) {
+              const req = p.required !== false ? "required" : "optional";
+              const desc = p.description ? `: ${p.description}` : "";
+              result += `\n          ${p.name} (${p.type || "string"}, ${req})${desc}`;
+            }
+          }
         }
       }
     }

package/src/handlers/webhook-handler.ts

@@ -280,8 +280,10 @@ export class WebhookHandler extends EventEmitter<SDKEvents> {
       await this.sendWebhook(eventType, validatedMessage, metadata);
     } catch (error) {
       if (error instanceof z.ZodError) {
-        this.logger.error("Invalid message for webhook", error);
-        throw new ValidationError("Invalid message for webhook", error);
+        this.logger.debug("Skipping webhook for unrecognized message type", {
+          type: message.type
+        });
+        return;
       }
       throw error;
     }

package/src/index.ts

@@ -151,6 +151,7 @@ export {
   createRequestChallenge,
   createCheckCachedAuth,
   createAuth,
+  createApiKeyAuth,
   createUserMessage,
   createPing,
   createSubscribe,
@@ -233,6 +234,12 @@ export {
  */
 export { SecurePrivateKey } from "./utils/secure-private-key";
 
+/**
+ * ERC20 utilities for wallet transaction flows
+ * Check allowances to skip unnecessary approval transactions
+ */
+export { checkERC20Allowance, parseApproveCalldata, ERC20_APPROVE_SELECTOR } from "./utils/erc20";
+
 /**
  * Payment utilities for x402 payment signing
  * Enables SDK users to make payments directly using private keys
@@ -264,7 +271,7 @@ export {
 /**
  * SDK version string
  */
-export const VERSION = "3.0.1";
+export const VERSION = "3.3.0";
 
 /**
  * Convenience type re-exports for message operations

package/src/managers/message-router.ts

@@ -86,6 +86,7 @@ export interface MessageRouterConfig {
   maxPricePerRequest?: number;
   quoteTimeout?: number;
   wsUrl?: string;
+  apiKey?: string; // API key for session-key payment flow
   paymentNetwork?: string; // CAIP-2 format (e.g., "eip155:3338")
   paymentAsset?: string;
   network?: string; // Network name (e.g., "peaq", "base", "avalanche")
@@ -107,6 +108,7 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
   private readonly maxPricePerRequest?: number;
   private readonly quoteTimeout: number;
   private readonly wsUrl: string;
+  private readonly apiKey?: string; // API key for session-key payment
   private readonly paymentNetwork: string; // CAIP-2 format if set
   private readonly paymentAsset: string;
   private readonly networkName: string; // Network name (peaq, base, avalanche)
@@ -135,6 +137,7 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
     this.maxPricePerRequest = config.maxPricePerRequest;
     this.quoteTimeout = config.quoteTimeout ?? 30000;
     this.wsUrl = config.wsUrl ?? "";
+    this.apiKey = config.apiKey;
 
     // Store config values - dynamic network resolution happens lazily in getPaymentNetwork/Asset()
     // because networks are only initialized after connect() is called
@@ -627,7 +630,7 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
     let paymentHeader: string | undefined;
 
     // Create payment header if payment client is configured and price > 0
-    if (this.paymentClient && quote.pricing.pricePerUnit > 0) {
+    if (this.paymentClient && quote.pricing.pricePerUnit > 0 && !this.apiKey) {
       try {
         // Pass backend-provided settlement data to payment header creation
         paymentHeader = await this.paymentClient.createPaymentHeader(
@@ -650,7 +653,12 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
       }
     }
 
-    const confirmMessage = createConfirmTask(taskId, paymentHeader);
+    // Build confirm message — x402 payment or API-key, whichever is available
+    const confirmMessage = createConfirmTask(taskId, {
+      x402Payment: paymentHeader,
+      apiKey: this.apiKey,
+      network: this.apiKey ? this.networkName || undefined : undefined
+    });
 
     this.logger.debug("MessageRouter: Confirming quote", { taskId });
 

package/src/teneo-sdk.ts

@@ -211,6 +211,7 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
           maxPricePerRequest: this.config.maxPricePerRequest,
           quoteTimeout: this.config.quoteTimeout,
           wsUrl: this.config.wsUrl,
+          apiKey: this.config.apiKey,
           paymentNetwork: this.config.paymentNetwork,
           paymentAsset: this.config.paymentAsset,
           network: this.config.network, // Network name from withNetwork()
@@ -1344,8 +1345,8 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
    * when a chainId is provided, matching the format the UI uses.
    *
    * @param taskId - The task ID from the wallet:tx_requested event
-   * @param status - Transaction result: "confirmed", "rejected", or "failed"
-   * @param txHash - The on-chain transaction hash (required for "confirmed" status)
+   * @param status - Transaction result: "broadcasted" (tx sent, hash available), "confirmed" (on-chain receipt), "rejected" (user declined), or "failed" (error)
+   * @param txHash - The on-chain transaction hash (required for "broadcasted" and "confirmed" status)
    * @param error - Error message (optional, for "failed" status)
    * @param room - The room ID from the wallet:tx_requested event (required for routing)
    * @param chainId - The chain ID from data.tx.chainId (used to format txHash with network name)
@@ -1356,6 +1357,10 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
    * sdk.on("wallet:tx_requested", async (data) => {
    *   try {
    *     const txHash = await wallet.sendTransaction(data.tx);
+   *     // Notify agent that tx was broadcast (hash available, not yet confirmed)
+   *     await sdk.sendTxResult(data.taskId, "broadcasted", txHash, undefined, data.room, data.tx.chainId);
+   *     // Wait for on-chain confirmation
+   *     await waitForReceipt(txHash);
    *     await sdk.sendTxResult(data.taskId, "confirmed", txHash, undefined, data.room, data.tx.chainId);
    *   } catch (err) {
    *     await sdk.sendTxResult(data.taskId, "failed", undefined, err.message, data.room, data.tx.chainId);
@@ -1365,7 +1370,7 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
    */
   public async sendTxResult(
     taskId: string,
-    status: "confirmed" | "rejected" | "failed",
+    status: "broadcasted" | "confirmed" | "rejected" | "failed",
     txHash?: string,
     error?: string,
     room?: string,

package/src/types/config.ts

@@ -86,6 +86,7 @@ const SDKConfigBaseSchema = z.object({
   // Authentication
   privateKey: PrivateKeySchema.optional(),
   walletAddress: z.string().optional(),
+  apiKey: z.string().optional(), // API key for session-key auth & payment (no privateKey needed)
 
   // Client identification
   clientType: ClientTypeSchema.optional(),
@@ -432,6 +433,28 @@ export class SDKConfigBuilder {
     return this;
   }
 
+  /**
+   * Sets the API key for session-key-based authentication and payment.
+   * When set, the SDK authenticates with the API key directly (no challenge-response)
+   * and uses it for task confirmations instead of x402 payment signing.
+   *
+   * @param apiKey - API key string (e.g., 'sk_live_...')
+   * @param walletAddress - Wallet address associated with the API key
+   * @returns this builder for method chaining
+   *
+   * @example
+   * ```typescript
+   * builder.withApiKey('sk_live_kQp3x...', '0xYourWalletAddress')
+   * ```
+   */
+  withApiKey(apiKey: string, walletAddress?: string): this {
+    this.config.apiKey = z.string().min(1).parse(apiKey);
+    if (walletAddress) {
+      this.config.walletAddress = z.string().parse(walletAddress);
+    }
+    return this;
+  }
+
   /**
    * Configures webhook URL and optional HTTP headers for receiving real-time event notifications.
    * Webhook URL must use HTTPS for non-localhost endpoints (security requirement).

package/src/types/index.ts

@@ -221,6 +221,7 @@ export {
   createRequestChallenge,
   createCheckCachedAuth,
   createAuth,
+  createApiKeyAuth,
   createUserMessage,
   createPing,
   createSubscribe,

package/src/types/messages.ts

@@ -31,7 +31,7 @@ const stringToBoolean = z
       }
 
       // Accept falsy values
-      if (normalized === "false" || normalized === "0" || normalized === "no") {
+      if (normalized === "false" || normalized === "0" || normalized === "no" || normalized === "skipped") {
         return false;
       }
 
@@ -135,7 +135,10 @@ export const MessageTypeSchema = z.enum([
 
   // Wallet Transaction Flow
   "trigger_wallet_tx",
-  "tx_result"
+  "tx_result",
+
+  // Agent Owner Wallets
+  "agent_owner_wallets"
 ]);
 
 export const ContentTypeSchema = z.enum([
@@ -327,7 +330,10 @@ export const AuthMessageSchema = BaseMessageSchema.extend({
       jwt_token: z.string().optional(), // JWT token for KeyVault API authentication
       session_token: z.string().optional(), // 64-char hex token for fast re-auth (24h validity)
       whitelist_verified: z.union([z.boolean(), z.string()]).optional(), // Whitelist verification status
-      user_count: z.number().optional() // Total user count (admin only)
+      user_count: z.number().optional(), // Total user count (admin only)
+      // API-key auth fields
+      api_key: z.string().optional(), // API key for session-key auth (no challenge-response needed)
+      platform: z.string().optional() // Platform identifier (e.g., "community")
     })
     .optional()
 });
@@ -504,7 +510,9 @@ export const TaskQuoteMessageSchema = BaseMessageSchema.extend({
 export const ConfirmTaskMessageSchema = BaseMessageSchema.extend({
   type: z.literal("confirm_task"),
   data: z.object({
-    task_id: z.string()
+    task_id: z.string(),
+    api_key: z.string().optional(), // API key for session-key payment flow
+    network: z.string().optional() // Payment network: "peaq", "base", "avalanche", "x-layer"
   }),
   payment: z.string().optional() // x402 payment at top level (backend checks msg.Payment)
 });
@@ -1043,7 +1051,7 @@ export const AgentErrorMessageSchema = BaseMessageSchema.extend({
 export type AgentErrorMessage = z.infer<typeof AgentErrorMessageSchema>;
 
 // Wallet Transaction schemas
-export const TxResultStatusSchema = z.enum(["confirmed", "rejected", "failed"]);
+export const TxResultStatusSchema = z.enum(["broadcasted", "confirmed", "rejected", "failed"]);
 export type TxResultStatus = z.infer<typeof TxResultStatusSchema>;
 
 export const TriggerWalletTxMessageSchema = BaseMessageSchema.extend({
@@ -1283,6 +1291,23 @@ export function createAuth(
   });
 }
 
+export function createApiKeyAuth(
+  address: string,
+  apiKey: string,
+  userType: ClientType = "user",
+  platform: string = "community"
+): AuthMessage {
+  return AuthMessageSchema.parse({
+    type: "auth",
+    data: {
+      address,
+      userType,
+      api_key: apiKey,
+      platform
+    }
+  });
+}
+
 export function createUserMessage(content: string, room: string, from?: string): UserMessage {
   return UserMessageSchema.parse({
     type: "message",
@@ -1332,13 +1357,18 @@ export function createRequestTask(
   });
 }
 
-export function createConfirmTask(taskId: string, x402Payment?: string): ConfirmTaskMessage {
+export function createConfirmTask(
+  taskId: string,
+  options?: { x402Payment?: string; apiKey?: string; network?: string }
+): ConfirmTaskMessage {
   return ConfirmTaskMessageSchema.parse({
     type: "confirm_task",
     data: {
-      task_id: taskId
+      task_id: taskId,
+      ...(options?.apiKey && { api_key: options.apiKey }),
+      ...(options?.network && { network: options.network })
     },
-    ...(x402Payment && { payment: x402Payment }) // payment at top level for backend
+    ...(options?.x402Payment && { payment: options.x402Payment })
   });
 }
 

package/src/utils/erc20.test.ts

@@ -0,0 +1,161 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { parseApproveCalldata, checkERC20Allowance, ERC20_APPROVE_SELECTOR } from "./erc20";
+
+describe("parseApproveCalldata", () => {
+  // Valid approve calldata: approve(0x1234...5678, max_uint256)
+  const spender = "1234567890abcdef1234567890abcdef12345678";
+  const maxUint256Hex = "f".repeat(64);
+  const validCalldata = ERC20_APPROVE_SELECTOR +
+    spender.padStart(64, "0") +
+    maxUint256Hex;
+
+  it("should parse valid approve calldata", () => {
+    const result = parseApproveCalldata(validCalldata);
+    expect(result).not.toBeNull();
+    expect(result!.spender).toBe(`0x${spender}`);
+    expect(result!.amount).toBe(BigInt("0x" + maxUint256Hex));
+  });
+
+  it("should return null for undefined data", () => {
+    expect(parseApproveCalldata(undefined)).toBeNull();
+  });
+
+  it("should return null for empty string", () => {
+    expect(parseApproveCalldata("")).toBeNull();
+  });
+
+  it("should return null for short data", () => {
+    expect(parseApproveCalldata("0x095ea7b3")).toBeNull();
+  });
+
+  it("should return null for wrong selector", () => {
+    const wrongSelector = "0xa9059cbb" + "0".repeat(128); // transfer() selector
+    expect(parseApproveCalldata(wrongSelector)).toBeNull();
+  });
+
+  it("should return null for data shorter than 138 chars", () => {
+    const shortData = ERC20_APPROVE_SELECTOR + "0".repeat(60); // only 68 + 10 = 78 chars
+    expect(parseApproveCalldata(shortData)).toBeNull();
+  });
+
+  it("should handle uppercase hex", () => {
+    const upper = validCalldata.toUpperCase();
+    // selector check lowercases, so "0X" prefix won't match "0x"
+    const withLowerPrefix = "0x" + upper.slice(2);
+    const result = parseApproveCalldata(withLowerPrefix);
+    expect(result).not.toBeNull();
+    expect(result!.spender).toBe(`0x${spender.toUpperCase()}`);
+  });
+
+  it("should parse a specific amount correctly", () => {
+    const amount = "0000000000000000000000000000000000000000000000000de0b6b3a7640000"; // 1e18
+    const calldata = ERC20_APPROVE_SELECTOR + "0".repeat(24) + spender + amount;
+    const result = parseApproveCalldata(calldata);
+    expect(result).not.toBeNull();
+    expect(result!.amount).toBe(BigInt("0xde0b6b3a7640000")); // 1e18 in hex
+  });
+
+  it("should parse zero amount", () => {
+    const calldata = ERC20_APPROVE_SELECTOR + "0".repeat(24) + spender + "0".repeat(64);
+    const result = parseApproveCalldata(calldata);
+    expect(result).not.toBeNull();
+    expect(result!.amount).toBe(0n);
+  });
+});
+
+describe("checkERC20Allowance", () => {
+  const mockFetch = vi.fn();
+
+  beforeEach(() => {
+    vi.stubGlobal("fetch", mockFetch);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  const rpcUrl = "https://rpc.example.com";
+  const tokenAddress = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
+  const owner = "0x1111111111111111111111111111111111111111";
+  const spender = "0x2222222222222222222222222222222222222222";
+
+  it("should return allowance as bigint", async () => {
+    const allowanceHex = "0x00000000000000000000000000000000000000000000000000000000000f4240"; // 1000000
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ result: allowanceHex }),
+    });
+
+    const result = await checkERC20Allowance(rpcUrl, tokenAddress, owner, spender);
+    expect(result).toBe(1000000n);
+  });
+
+  it("should return 0n for zero allowance", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ result: "0x" }),
+    });
+
+    const result = await checkERC20Allowance(rpcUrl, tokenAddress, owner, spender);
+    expect(result).toBe(0n);
+  });
+
+  it("should throw on RPC error response", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ error: { message: "execution reverted" } }),
+    });
+
+    await expect(checkERC20Allowance(rpcUrl, tokenAddress, owner, spender))
+      .rejects.toThrow("RPC error: execution reverted");
+  });
+
+  it("should throw on HTTP error", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 503,
+    });
+
+    await expect(checkERC20Allowance(rpcUrl, tokenAddress, owner, spender))
+      .rejects.toThrow("RPC request failed with status 503");
+  });
+
+  it("should throw on network failure", async () => {
+    mockFetch.mockRejectedValueOnce(new Error("fetch failed"));
+
+    await expect(checkERC20Allowance(rpcUrl, tokenAddress, owner, spender))
+      .rejects.toThrow("fetch failed");
+  });
+
+  it("should send correct eth_call params", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ result: "0x0" }),
+    });
+
+    await checkERC20Allowance(rpcUrl, tokenAddress, owner, spender);
+
+    expect(mockFetch).toHaveBeenCalledWith(rpcUrl, expect.objectContaining({
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+    }));
+
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.method).toBe("eth_call");
+    expect(body.params[0].to).toBe(tokenAddress);
+    // Should contain allowance selector 0xdd62ed3e
+    expect(body.params[0].data.startsWith("0xdd62ed3e")).toBe(true);
+    expect(body.params[1]).toBe("latest");
+  });
+
+  it("should handle max uint256 allowance", async () => {
+    const maxAllowance = "0x" + "f".repeat(64);
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ result: maxAllowance }),
+    });
+
+    const result = await checkERC20Allowance(rpcUrl, tokenAddress, owner, spender);
+    expect(result).toBe(BigInt(maxAllowance));
+  });
+});