@zyfai/sdk 0.1.5 → 0.1.6

package/README.md

@@ -65,7 +65,7 @@ const sdk = new ZyfaiSDK({
 
 ### Connect Account
 
-The SDK accepts either a private key or a modern wallet provider:
+The SDK accepts either a private key or a modern wallet provider. **The SDK automatically authenticates the user via SIWE (Sign-In with Ethereum) when connecting.**
 
 ```typescript
 // Option 1: With private key (chainId required)
@@ -84,7 +84,25 @@ const userAddress = "0xUser...";
 await sdk.deploySafe(userAddress, 42161);
 ```
 
-**Note:** When using a wallet provider, the SDK automatically detects the chain from the provider. You can optionally specify `chainId` to override.
+**Note:**
+- When using a wallet provider, the SDK automatically detects the chain from the provider. You can optionally specify `chainId` to override.
+- The SDK automatically performs SIWE authentication when connecting, so you don't need to call any additional authentication methods.
+
+### Disconnect Account
+
+Disconnect the current account and clear all authentication state:
+
+```typescript
+// Disconnect account and clear JWT token
+await sdk.disconnectAccount();
+console.log("Account disconnected and authentication cleared");
+```
+
+This method:
+- Clears the wallet connection
+- Resets authentication state
+- Clears the JWT token
+- Resets session key tracking
 
 ## Core Features
 
@@ -164,7 +182,7 @@ new ZyfaiSDK(config: SDKConfig | string)
 
 ##### `connectAccount(account: string | any, chainId?: SupportedChainId): Promise<Address>`
 
-Connect account for signing transactions. Accepts either a private key string or a modern wallet provider.
+Connect account for signing transactions and authenticate via SIWE. Accepts either a private key string or a modern wallet provider.
 
 **Parameters:**
 
@@ -176,6 +194,11 @@ Connect account for signing transactions. Accepts either a private key string or
 
 **Returns:** Connected wallet address
 
+**Automatic Actions:**
+- Connects the wallet
+- Authenticates via SIWE (Sign-In with Ethereum)
+- Stores JWT token for authenticated endpoints
+
 **Examples:**
 
 ```typescript
@@ -187,6 +210,25 @@ const provider = await connector.getProvider();
 await sdk.connectAccount(provider); // Uses provider's current chain
 ```
 
+##### `disconnectAccount(): Promise<void>`
+
+Disconnect account and clear all authentication state.
+
+**Returns:** Promise that resolves when disconnection is complete
+
+**Actions:**
+- Clears wallet connection
+- Resets authentication state
+- Clears JWT token
+- Resets session key tracking
+
+**Example:**
+
+```typescript
+await sdk.disconnectAccount();
+console.log("Disconnected and cleared");
+```
+
 ##### `getSmartWalletAddress(userAddress: string, chainId: SupportedChainId): Promise<SmartWalletResponse>`
 
 Get the Smart Wallet (Safe) address for a user.
@@ -235,7 +277,7 @@ The SDK automatically fetches optimal session configuration from ZyFAI API:
 
 ```typescript
 // SDK automatically:
-// 1. Authenticates via SIWE (creates user record if needed)
+// 1. Uses existing SIWE authentication (from connectAccount)
 // 2. Checks if user already has an active session key (returns early if so)
 // 3. Calculates the deterministic Safe address
 // 4. Retrieves personalized config via /session-keys/config
@@ -257,9 +299,9 @@ console.log("User ID:", result.userId);
 
 **Important**:
 
-- `createSessionKey` requires SIWE authentication (prompts wallet signature on first call)
-- The SDK proactively checks if the user already has an active session key (from login response) and returns early without requiring any signature if one exists
-- The user record must have `smartWallet` and `chainId` set (automatically handled after calling `deploySafe` or `updateUserProfile`)
+- User must be authenticated (automatically done via `connectAccount()`)
+- The SDK proactively checks if the user already has an active session key and returns early without requiring any signature if one exists
+- The user record must have `smartWallet` and `chainId` set (automatically handled after calling `deploySafe`)
 - When `alreadyActive` is `true`, `sessionKeyAddress` and `signature` are not available in the response
 
 ### 4. Deposit Funds
@@ -286,7 +328,7 @@ The SDK automatically authenticates via SIWE before logging the deposit with ZyF
 
 ### 5. Withdraw Funds
 
-Withdraw funds from your Safe:
+Initiate a withdrawal from your Safe. **Note: Withdrawals are processed asynchronously by the backend.**
 
 ```typescript
 // Full withdrawal
@@ -301,13 +343,22 @@ const result = await sdk.withdrawFunds(
 );
 
 if (result.success) {
-  console.log("Withdrawal successful!");
-  console.log("Transaction Hash:", result.txHash);
+  console.log("Withdrawal initiated!");
+  console.log("Message:", result.message); // e.g., "Withdrawal request sent"
+  if (result.txHash) {
+    console.log("Transaction Hash:", result.txHash);
+  } else {
+    console.log("Transaction will be processed asynchronously");
+  }
 }
 ```
 
-**Note:** Amount must be in least decimal units. For USDC (6 decimals): 1 USDC = 1000000
-The SDK authenticates via SIWE before calling the withdrawal endpoints (`/users/withdraw` or `/users/partial-withdraw`) so you don't need to manage tokens manually.
+**Important Notes:**
+- Amount must be in least decimal units. For USDC (6 decimals): 1 USDC = 1000000
+- The SDK authenticates via SIWE before calling the withdrawal endpoints
+- Withdrawals are processed asynchronously - the `txHash` may not be immediately available
+- Check the `message` field for the withdrawal status
+- Use `getHistory()` to track the withdrawal transaction once it's processed
 
 ### 6. Get Available Protocols
 
@@ -549,7 +600,7 @@ async function main() {
     bundlerApiKey: process.env.BUNDLER_API_KEY!,
   });
 
-  // Connect account (for signing)
+  // Connect account (automatically authenticates via SIWE)
   await sdk.connectAccount(process.env.PRIVATE_KEY!, 42161);
 
   const userAddress = "0xUser..."; // User's EOA address
@@ -598,9 +649,10 @@ function SafeDeployment() {
     try {
       // Client passes the wallet provider from their frontend
       // e.g., from wagmi: const provider = await connector.getProvider();
+      // connectAccount automatically authenticates via SIWE
       const address = await sdk.connectAccount(walletProvider); // chainId auto-detected
       setUserAddress(address);
-      console.log("Connected:", address);
+      console.log("Connected and authenticated:", address);
 
       // Get Safe address for this user
       const walletInfo = await sdk.getSmartWalletAddress(address, 42161);
@@ -720,7 +772,7 @@ CHAIN_ID=8453
 
 ### "No account connected" Error
 
-Make sure to call `connectAccount()` before calling other methods that require signing.
+Make sure to call `connectAccount()` before calling other methods that require signing. Note that `connectAccount()` automatically authenticates the user via SIWE.
 
 ### "Unsupported chain" Error
 
@@ -728,18 +780,26 @@ Check that the chain ID is in the supported chains list: Arbitrum (42161), Base
 
 ### SIWE Authentication Issues in Browser
 
-The SDK automatically detects browser vs Node.js environments for SIWE authentication:
+The SDK automatically performs SIWE authentication when you call `connectAccount()`. The SDK automatically detects browser vs Node.js environments:
 - **Browser**: Uses `window.location.origin` for the SIWE message domain/uri to match the browser's automatic `Origin` header
 - **Node.js**: Uses the API endpoint URL
 
 If you encounter SIWE authentication failures in a browser, ensure:
 1. Your frontend origin is allowed by the API's CORS configuration
 2. You're using the correct `environment` setting (`staging` or `production`)
+3. The user approves the SIWE signature request in their wallet
 
 ### Session Key Already Exists
 
 If `createSessionKey` returns `{ alreadyActive: true }`, the user already has an active session key. This is not an error - the SDK proactively checks before attempting to create a new one.
 
+### Withdrawal Transaction Hash Not Available
+
+If `withdrawFunds` returns without a `txHash`, the withdrawal is being processed asynchronously by the backend. You can:
+1. Check the `message` field for status information
+2. Use `getHistory()` to track when the withdrawal transaction is processed
+3. The transaction will appear in the history once it's been executed
+
 ### Data API CORS Errors
 
 Some Data API endpoints may require server-side CORS configuration. If you see CORS errors for endpoints like `onchain-earnings`, `calculate-onchain-earnings`, or `opportunities`, contact ZyFAI support to ensure your origin is whitelisted.

package/dist/index.d.mts

@@ -347,7 +347,8 @@ interface DepositResponse {
 }
 interface WithdrawResponse {
     success: boolean;
-    txHash: string;
+    message: string;
+    txHash?: string;
     type: "full" | "partial";
     amount: string;
     receiver: string;
@@ -456,6 +457,17 @@ declare class ZyfaiSDK {
      * await sdk.connectAccount(provider);
      */
     connectAccount(account: string | any, chainId?: SupportedChainId): Promise<Address>;
+    /**
+     * Disconnect account and clear authentication state
+     * Resets wallet connection, JWT token, and all authentication-related state
+     *
+     * @example
+     * ```typescript
+     * await sdk.disconnectAccount();
+     * console.log("Account disconnected");
+     * ```
+     */
+    disconnectAccount(): Promise<void>;
     /**
      * Get wallet client (throws if not connected)
      * @private
@@ -531,18 +543,20 @@ declare class ZyfaiSDK {
     depositFunds(userAddress: string, chainId: SupportedChainId, tokenAddress: string, amount: string): Promise<DepositResponse>;
     /**
      * Withdraw funds from Safe smart wallet
-     * Triggers a withdrawal request to the ZyFAI API
+     * Initiates a withdrawal request to the ZyFAI API
+     * Note: The withdrawal is processed asynchronously, so txHash may not be immediately available
      *
      * @param userAddress - User's address (owner of the Safe)
      * @param chainId - Target chain ID
      * @param amount - Optional: Amount in least decimal units to withdraw (partial withdrawal). If not specified, withdraws all funds
      * @param receiver - Optional: Receiver address. If not specified, sends to Safe owner
-     * @returns Withdraw response with transaction hash
+     * @returns Withdraw response with message and optional transaction hash (available once processed)
      *
      * @example
      * ```typescript
      * // Full withdrawal
      * const result = await sdk.withdrawFunds("0xUser...", 42161);
+     * console.log(result.message); // "Withdrawal request sent"
      *
      * // Partial withdrawal of 50 USDC (6 decimals)
      * const result = await sdk.withdrawFunds(

package/dist/index.d.ts

@@ -347,7 +347,8 @@ interface DepositResponse {
 }
 interface WithdrawResponse {
     success: boolean;
-    txHash: string;
+    message: string;
+    txHash?: string;
     type: "full" | "partial";
     amount: string;
     receiver: string;
@@ -456,6 +457,17 @@ declare class ZyfaiSDK {
      * await sdk.connectAccount(provider);
      */
     connectAccount(account: string | any, chainId?: SupportedChainId): Promise<Address>;
+    /**
+     * Disconnect account and clear authentication state
+     * Resets wallet connection, JWT token, and all authentication-related state
+     *
+     * @example
+     * ```typescript
+     * await sdk.disconnectAccount();
+     * console.log("Account disconnected");
+     * ```
+     */
+    disconnectAccount(): Promise<void>;
     /**
      * Get wallet client (throws if not connected)
      * @private
@@ -531,18 +543,20 @@ declare class ZyfaiSDK {
     depositFunds(userAddress: string, chainId: SupportedChainId, tokenAddress: string, amount: string): Promise<DepositResponse>;
     /**
      * Withdraw funds from Safe smart wallet
-     * Triggers a withdrawal request to the ZyFAI API
+     * Initiates a withdrawal request to the ZyFAI API
+     * Note: The withdrawal is processed asynchronously, so txHash may not be immediately available
      *
      * @param userAddress - User's address (owner of the Safe)
      * @param chainId - Target chain ID
      * @param amount - Optional: Amount in least decimal units to withdraw (partial withdrawal). If not specified, withdraws all funds
      * @param receiver - Optional: Receiver address. If not specified, sends to Safe owner
-     * @returns Withdraw response with transaction hash
+     * @returns Withdraw response with message and optional transaction hash (available once processed)
      *
      * @example
      * ```typescript
      * // Full withdrawal
      * const result = await sdk.withdrawFunds("0xUser...", 42161);
+     * console.log(result.message); // "Withdrawal request sent"
      *
      * // Partial withdrawal of 50 USDC (6 decimals)
      * const result = await sdk.withdrawFunds(

package/dist/index.js

@@ -757,6 +757,7 @@ var ZyfaiSDK = class {
     this.isAuthenticated = false;
     this.httpClient.clearAuthToken();
     const chainConfig = getChainConfig(chainId);
+    let connectedAddress;
     if (typeof account === "string") {
       let privateKey = account;
       if (!privateKey.startsWith("0x")) {
@@ -768,39 +769,60 @@ var ZyfaiSDK = class {
         chain: chainConfig.chain,
         transport: (0, import_viem4.http)(chainConfig.rpcUrl)
       });
-      return this.signer.address;
-    }
-    const provider = account;
-    if (!provider) {
-      throw new Error(
-        "Invalid account parameter. Expected private key string or wallet provider."
-      );
-    }
-    if (provider.request) {
-      const accounts = await provider.request({
-        method: "eth_requestAccounts"
-      });
-      if (!accounts || accounts.length === 0) {
-        throw new Error("No accounts found in wallet provider");
+      connectedAddress = this.signer.address;
+    } else {
+      const provider = account;
+      if (!provider) {
+        throw new Error(
+          "Invalid account parameter. Expected private key string or wallet provider."
+        );
+      }
+      if (provider.request) {
+        const accounts = await provider.request({
+          method: "eth_requestAccounts"
+        });
+        if (!accounts || accounts.length === 0) {
+          throw new Error("No accounts found in wallet provider");
+        }
+        this.walletClient = (0, import_viem4.createWalletClient)({
+          account: accounts[0],
+          chain: chainConfig.chain,
+          transport: (0, import_viem4.custom)(provider)
+        });
+        connectedAddress = accounts[0];
+      } else if (provider.account && provider.transport) {
+        this.walletClient = (0, import_viem4.createWalletClient)({
+          account: provider.account,
+          chain: chainConfig.chain,
+          transport: provider.transport
+        });
+        connectedAddress = provider.account.address;
+      } else {
+        throw new Error(
+          "Invalid wallet provider. Expected EIP-1193 provider or viem WalletClient."
+        );
       }
-      this.walletClient = (0, import_viem4.createWalletClient)({
-        account: accounts[0],
-        chain: chainConfig.chain,
-        transport: (0, import_viem4.custom)(provider)
-      });
-      return accounts[0];
-    }
-    if (provider.account && provider.transport) {
-      this.walletClient = (0, import_viem4.createWalletClient)({
-        account: provider.account,
-        chain: chainConfig.chain,
-        transport: provider.transport
-      });
-      return provider.account.address;
     }
-    throw new Error(
-      "Invalid wallet provider. Expected EIP-1193 provider or viem WalletClient."
-    );
+    await this.authenticateUser();
+    return connectedAddress;
+  }
+  /**
+   * Disconnect account and clear authentication state
+   * Resets wallet connection, JWT token, and all authentication-related state
+   *
+   * @example
+   * ```typescript
+   * await sdk.disconnectAccount();
+   * console.log("Account disconnected");
+   * ```
+   */
+  async disconnectAccount() {
+    this.signer = null;
+    this.walletClient = null;
+    this.isAuthenticated = false;
+    this.authenticatedUserId = null;
+    this.hasActiveSessionKey = false;
+    this.httpClient.clearAuthToken();
   }
   /**
    * Get wallet client (throws if not connected)
@@ -1172,18 +1194,20 @@ var ZyfaiSDK = class {
   }
   /**
    * Withdraw funds from Safe smart wallet
-   * Triggers a withdrawal request to the ZyFAI API
+   * Initiates a withdrawal request to the ZyFAI API
+   * Note: The withdrawal is processed asynchronously, so txHash may not be immediately available
    *
    * @param userAddress - User's address (owner of the Safe)
    * @param chainId - Target chain ID
    * @param amount - Optional: Amount in least decimal units to withdraw (partial withdrawal). If not specified, withdraws all funds
    * @param receiver - Optional: Receiver address. If not specified, sends to Safe owner
-   * @returns Withdraw response with transaction hash
+   * @returns Withdraw response with message and optional transaction hash (available once processed)
    *
    * @example
    * ```typescript
    * // Full withdrawal
    * const result = await sdk.withdrawFunds("0xUser...", 42161);
+   * console.log(result.message); // "Withdrawal request sent"
    *
    * // Partial withdrawal of 50 USDC (6 decimals)
    * const result = await sdk.withdrawFunds(
@@ -1234,9 +1258,12 @@ var ZyfaiSDK = class {
         });
       }
       const success = response?.success ?? true;
+      const message = response?.message || "Withdrawal request sent";
+      const txHash = response?.txHash || response?.transactionHash;
       return {
         success,
-        txHash: response?.txHash || response?.transactionHash || "pending",
+        message,
+        txHash,
         type: amount ? "partial" : "full",
         amount: amount || "all",
         receiver: receiver || userAddress,

package/dist/index.mjs

@@ -736,6 +736,7 @@ var ZyfaiSDK = class {
     this.isAuthenticated = false;
     this.httpClient.clearAuthToken();
     const chainConfig = getChainConfig(chainId);
+    let connectedAddress;
     if (typeof account === "string") {
       let privateKey = account;
       if (!privateKey.startsWith("0x")) {
@@ -747,39 +748,60 @@ var ZyfaiSDK = class {
         chain: chainConfig.chain,
         transport: http3(chainConfig.rpcUrl)
       });
-      return this.signer.address;
-    }
-    const provider = account;
-    if (!provider) {
-      throw new Error(
-        "Invalid account parameter. Expected private key string or wallet provider."
-      );
-    }
-    if (provider.request) {
-      const accounts = await provider.request({
-        method: "eth_requestAccounts"
-      });
-      if (!accounts || accounts.length === 0) {
-        throw new Error("No accounts found in wallet provider");
+      connectedAddress = this.signer.address;
+    } else {
+      const provider = account;
+      if (!provider) {
+        throw new Error(
+          "Invalid account parameter. Expected private key string or wallet provider."
+        );
+      }
+      if (provider.request) {
+        const accounts = await provider.request({
+          method: "eth_requestAccounts"
+        });
+        if (!accounts || accounts.length === 0) {
+          throw new Error("No accounts found in wallet provider");
+        }
+        this.walletClient = createWalletClient({
+          account: accounts[0],
+          chain: chainConfig.chain,
+          transport: custom(provider)
+        });
+        connectedAddress = accounts[0];
+      } else if (provider.account && provider.transport) {
+        this.walletClient = createWalletClient({
+          account: provider.account,
+          chain: chainConfig.chain,
+          transport: provider.transport
+        });
+        connectedAddress = provider.account.address;
+      } else {
+        throw new Error(
+          "Invalid wallet provider. Expected EIP-1193 provider or viem WalletClient."
+        );
       }
-      this.walletClient = createWalletClient({
-        account: accounts[0],
-        chain: chainConfig.chain,
-        transport: custom(provider)
-      });
-      return accounts[0];
-    }
-    if (provider.account && provider.transport) {
-      this.walletClient = createWalletClient({
-        account: provider.account,
-        chain: chainConfig.chain,
-        transport: provider.transport
-      });
-      return provider.account.address;
     }
-    throw new Error(
-      "Invalid wallet provider. Expected EIP-1193 provider or viem WalletClient."
-    );
+    await this.authenticateUser();
+    return connectedAddress;
+  }
+  /**
+   * Disconnect account and clear authentication state
+   * Resets wallet connection, JWT token, and all authentication-related state
+   *
+   * @example
+   * ```typescript
+   * await sdk.disconnectAccount();
+   * console.log("Account disconnected");
+   * ```
+   */
+  async disconnectAccount() {
+    this.signer = null;
+    this.walletClient = null;
+    this.isAuthenticated = false;
+    this.authenticatedUserId = null;
+    this.hasActiveSessionKey = false;
+    this.httpClient.clearAuthToken();
   }
   /**
    * Get wallet client (throws if not connected)
@@ -1151,18 +1173,20 @@ var ZyfaiSDK = class {
   }
   /**
    * Withdraw funds from Safe smart wallet
-   * Triggers a withdrawal request to the ZyFAI API
+   * Initiates a withdrawal request to the ZyFAI API
+   * Note: The withdrawal is processed asynchronously, so txHash may not be immediately available
    *
    * @param userAddress - User's address (owner of the Safe)
    * @param chainId - Target chain ID
    * @param amount - Optional: Amount in least decimal units to withdraw (partial withdrawal). If not specified, withdraws all funds
    * @param receiver - Optional: Receiver address. If not specified, sends to Safe owner
-   * @returns Withdraw response with transaction hash
+   * @returns Withdraw response with message and optional transaction hash (available once processed)
    *
    * @example
    * ```typescript
    * // Full withdrawal
    * const result = await sdk.withdrawFunds("0xUser...", 42161);
+   * console.log(result.message); // "Withdrawal request sent"
    *
    * // Partial withdrawal of 50 USDC (6 decimals)
    * const result = await sdk.withdrawFunds(
@@ -1213,9 +1237,12 @@ var ZyfaiSDK = class {
         });
       }
       const success = response?.success ?? true;
+      const message = response?.message || "Withdrawal request sent";
+      const txHash = response?.txHash || response?.transactionHash;
       return {
         success,
-        txHash: response?.txHash || response?.transactionHash || "pending",
+        message,
+        txHash,
         type: amount ? "partial" : "full",
         amount: amount || "all",
         receiver: receiver || userAddress,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zyfai/sdk",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "TypeScript SDK for ZyFAI Yield Optimization Engine - Deploy Safe smart wallets, manage session keys, and interact with DeFi protocols",
   "main": "dist/index.js",
   "module": "dist/index.mjs",