@naculus/connect-appkit-react 0.1.2

package/src/hooks/useSIWxSession.ts

@@ -0,0 +1,290 @@
+/**
+ * useSIWxSession — Unified SIWx session management hook.
+ *
+ * Combines the sign-in flow with session persistence, expiry tracking,
+ * and automatic restoration. Replaces the older useSiwxAuthSession.
+ *
+ * Provides:
+ *  - signIn / signOut / refresh lifecycle
+ *  - Auto-restore from storage on mount
+ *  - isExpired / timeUntilExpiry query
+ *  - Loading/error state
+ */
+
+import { useState, useCallback, useEffect, useRef } from "react";
+import { useSIWxLogin } from "./useSIWxLogin";
+import type { UseSIWxLoginOptions } from "./useSIWxLogin";
+import { LocalStorageAdapter, logger } from "@naculus/connect-core";
+import type {
+  SiwxResult,
+  SiwxMessage,
+} from "@naculus/siwx";
+import { checkSessionExpired, createLocalStorageSiwxSessionStorage, SiwxSessionManager } from "@naculus/siwx";
+import type { SiwxSession } from "@naculus/siwx";
+import { useWeb3 } from "../provider/Web3ConnectProvider";
+import { getClient } from "../client";
+
+// ── Constants ────────────────────────────────────────────────────
+
+const SIWX_SESSION_KEY = "naculus_siwx_session";
+
+// ── Types ────────────────────────────────────────────────────────
+
+export interface UseSIWxSessionOptions {
+  /** Storage key prefix (default: "naculus_") */
+  storagePrefix?: string;
+  /** Auto-restore session from storage on mount (default: true) */
+  autoRestore?: boolean;
+  /** Default chain ID when signing in (default: current chain from context) */
+  defaultChainId?: string;
+  /** Default session lifetime in seconds (default: 86400 = 24h) */
+  defaultExpirySeconds?: number;
+}
+
+export interface UseSIWxSessionReturn {
+  /** The current SIWx session, or null */
+  session: SiwxSession | null;
+  /** Whether a valid session exists */
+  isAuthenticated: boolean;
+  /** Whether we're still checking persisted auth on mount */
+  isRestoring: boolean;
+  /** Whether a sign-in is in progress */
+  isSigningIn: boolean;
+  /** Whether the current session has expired */
+  isExpired: boolean;
+  /** Milliseconds until session expires, or null */
+  timeUntilExpiry: number | null;
+
+  /** Sign in with optional overrides */
+  signIn: (options?: UseSIWxLoginOptions) => Promise<SiwxSession>;
+  /** Sign out: clears session from memory and storage */
+  signOut: () => Promise<void>;
+  /** Refresh the current session */
+  refresh: () => Promise<SiwxSession>;
+
+  /** Last error */
+  error: Error | null;
+  /** Clear the last error */
+  clearError: () => void;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+function siwxResultToSession(result: SiwxResult): SiwxSession {
+  return {
+    id: `siwx_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+    chainId: result.message.chainId,
+    address: result.message.address,
+    domain: result.message.domain,
+    message: result.message,
+    signature: result.signature,
+    issuedAt: result.message.issuedAt ?? new Date().toISOString(),
+    expiresAt: result.message.expirationTime,
+    refreshedAt: null,
+  };
+}
+
+// ── Hook ─────────────────────────────────────────────────────────
+
+export function useSIWxSession(
+  options?: UseSIWxSessionOptions
+): UseSIWxSessionReturn {
+  const {
+    storagePrefix = "naculus_",
+    autoRestore = true,
+    defaultExpirySeconds = 86_400,
+  } = options ?? {};
+
+  const [session, setSession] = useState<SiwxSession | null>(null);
+  const [isRestoring, setIsRestoring] = useState(autoRestore);
+  const [isSigningIn, setIsSigningIn] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const { session: web3Session, chainId: currentChainId } = useWeb3();
+  const login = useSIWxLogin();
+  const storageRef = useRef(
+    createLocalStorageSiwxSessionStorage(`${storagePrefix}siwx_session`)
+  );
+
+  const clearError = useCallback(() => setError(null), []);
+
+  // ── Restore from storage on mount ──────────────────────────────
+
+  useEffect(() => {
+    if (!autoRestore) {
+      setIsRestoring(false);
+      return;
+    }
+
+    let cancelled = false;
+
+    (async () => {
+      try {
+        const storage = storageRef.current;
+        const saved = await storage.get();
+
+        if (cancelled) return;
+
+        if (saved) {
+          logger.info("react/useSIWxSession", "Restored persisted SIWx session");
+          setSession(saved);
+          setError(null);
+        } else {
+          // No valid session in storage
+          setSession(null);
+        }
+      } catch (err) {
+        logger.warn("react/useSIWxSession", "Failed to restore SIWx session:", err);
+        setSession(null);
+      } finally {
+        if (!cancelled) setIsRestoring(false);
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [autoRestore]);
+
+  // ── Expiry refresh timer ───────────────────────────────────────
+
+  useEffect(() => {
+    if (!session?.expiresAt) return;
+
+    const timeUntilExpiry = new Date(session.expiresAt).getTime() - Date.now();
+    if (timeUntilExpiry <= 0) {
+      // Already expired — clear session
+      setSession(null);
+      return;
+    }
+
+    // Schedule clearing when expired
+    const timer = setTimeout(() => {
+      setSession((prev) => {
+        if (prev && prev.id === session.id) {
+          return null;
+        }
+        return prev;
+      });
+    }, timeUntilExpiry);
+
+    return () => clearTimeout(timer);
+  }, [session?.id, session?.expiresAt]);
+
+  // ── Sign In ────────────────────────────────────────────────────
+
+  const signIn = useCallback(
+    async (signOptions?: UseSIWxLoginOptions): Promise<SiwxSession> => {
+      setIsSigningIn(true);
+      setError(null);
+
+      try {
+        // Merge default options with provided overrides
+        const effectiveOptions: UseSIWxLoginOptions = {
+          expirySeconds: defaultExpirySeconds,
+          chainId: currentChainId ?? undefined,
+          ...signOptions,
+        };
+
+        const result = await login.signIn(effectiveOptions);
+
+        // Convert SiwxResult to SiwxSession
+        const siwxSession = siwxResultToSession(result);
+
+        // Persist to storage
+        const storage = storageRef.current;
+        await storage.set(siwxSession);
+
+        setSession(siwxSession);
+        setIsSigningIn(false);
+        return siwxSession;
+      } catch (err) {
+        const wrapped = err instanceof Error ? err : new Error("SIWx sign-in failed");
+        setError(wrapped);
+        setIsSigningIn(false);
+        throw wrapped;
+      }
+    },
+    [login, currentChainId, defaultExpirySeconds]
+  );
+
+  // ── Sign Out ───────────────────────────────────────────────────
+
+  const signOut = useCallback(async () => {
+    try {
+      const storage = storageRef.current;
+      await storage.remove();
+    } catch (err) {
+      logger.warn("react/useSIWxSession", "Failed to clear session:", err);
+    }
+    setSession(null);
+    setError(null);
+  }, []);
+
+  // ── Refresh ────────────────────────────────────────────────────
+
+  const refresh = useCallback(async (): Promise<SiwxSession> => {
+    if (!session) {
+      throw new Error("No active session to refresh");
+    }
+
+    setIsSigningIn(true);
+    setError(null);
+
+    try {
+      // Re-sign with updated timestamps
+      const result = await login.signIn({
+        domain: session.domain,
+        statement: session.message.statement ?? undefined,
+        uri: session.message.uri,
+        chainId: session.chainId,
+        expirySeconds: defaultExpirySeconds,
+        resources: session.message.resources.length > 0 ? session.message.resources : undefined,
+        requestId: session.message.requestId ?? undefined,
+      });
+
+      const refreshedSession: SiwxSession = {
+        ...siwxResultToSession(result),
+        id: session.id, // preserve the original session ID
+        refreshedAt: new Date().toISOString(),
+      };
+
+      // Persist
+      const storage = storageRef.current;
+      await storage.set(refreshedSession);
+
+      setSession(refreshedSession);
+      setIsSigningIn(false);
+      return refreshedSession;
+    } catch (err) {
+      const wrapped = err instanceof Error ? err : new Error("Session refresh failed");
+      setError(wrapped);
+      setIsSigningIn(false);
+      throw wrapped;
+    }
+  }, [session, login, defaultExpirySeconds]);
+
+  // ── Computed state ─────────────────────────────────────────────
+
+  const isAuthenticated = session !== null && !checkSessionExpired(session);
+  const expired = checkSessionExpired(session);
+  const timeUntilExpiry = session?.expiresAt
+    ? Math.max(0, new Date(session.expiresAt).getTime() - Date.now())
+    : null;
+
+  return {
+    session: isAuthenticated ? session : null,
+    isAuthenticated,
+    isRestoring,
+    isSigningIn,
+    isExpired: expired,
+    timeUntilExpiry,
+
+    signIn,
+    signOut,
+    refresh,
+
+    error,
+    clearError,
+  };
+}

package/src/hooks/useSendCalls.ts

@@ -0,0 +1,103 @@
+import { useState, useCallback } from "react";
+import { useWeb3 } from "../provider/Web3ConnectProvider";
+import { getClient } from "../client";
+import { WalletError } from "@naculus/connect-core";
+import type { BatchCall, CallsStatus } from "@naculus/connect-core";
+
+export type SendCallsStatus = "idle" | "awaiting_approval" | "confirmed" | "failed";
+
+export function useSendCalls() {
+  const { session, chainId } = useWeb3();
+  const [status, setStatus] = useState<SendCallsStatus>("idle");
+  const [error, setError] = useState<Error | null>(null);
+  const [batchHash, setBatchHash] = useState<string | null>(null);
+  const [callsStatus, setCallsStatus] = useState<CallsStatus | null>(null);
+
+  const sendCalls = useCallback(
+    async (calls: BatchCall[], options?: { chainId?: string }): Promise<string> => {
+      if (!session) {
+        setStatus("failed");
+        const err = new WalletError("wallet_unavailable", "No active session");
+        setError(err);
+        throw err;
+      }
+
+      const client = getClient();
+      if (!client) {
+        setStatus("failed");
+        const err = new WalletError("wallet_unavailable", "Client not initialized");
+        setError(err);
+        throw err;
+      }
+
+      if (calls.length === 0) {
+        setStatus("failed");
+        const err = new WalletError("invalid_input", "At least one call is required");
+        setError(err);
+        throw err;
+      }
+
+      setStatus("awaiting_approval");
+      setError(null);
+      setBatchHash(null);
+
+      try {
+        const result = await client.sendCalls(
+          session,
+          calls,
+          options?.chainId ?? chainId ?? undefined,
+        );
+        setStatus("confirmed");
+        setBatchHash(result);
+        return result;
+      } catch (err) {
+        setStatus("failed");
+        const errorMessage = err instanceof Error ? err.message : "sendCalls failed";
+        setError(err instanceof Error ? err : new Error(errorMessage));
+        throw err;
+      }
+    },
+    [session, chainId],
+  );
+
+  const getCallsStatus = useCallback(
+    async (hash?: string): Promise<CallsStatus> => {
+      if (!session) {
+        throw new WalletError("wallet_unavailable", "No active session");
+      }
+
+      const client = getClient();
+      if (!client) {
+        throw new WalletError("wallet_unavailable", "Client not initialized");
+      }
+
+      const bundleHash = hash ?? batchHash;
+      if (!bundleHash) {
+        throw new WalletError("invalid_input", "No bundle hash available");
+      }
+
+      const result = await client.getCallsStatus(session, bundleHash);
+      setCallsStatus(result);
+      return result;
+    },
+    [session, batchHash],
+  );
+
+  const reset = useCallback(() => {
+    setStatus("idle");
+    setError(null);
+    setBatchHash(null);
+    setCallsStatus(null);
+  }, []);
+
+  return {
+    sendCalls,
+    getCallsStatus,
+    status,
+    error,
+    batchHash,
+    callsStatus,
+    reset,
+    isSending: status === "awaiting_approval",
+  };
+}

package/src/hooks/useSendTransaction.test.ts

@@ -0,0 +1,175 @@
+/// <reference types="vitest" />
+/// @vitest-environment jsdom
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+
+const mockUseWeb3 = vi.fn();
+vi.mock("../provider/Web3ConnectProvider", () => ({
+  useWeb3: () => mockUseWeb3(),
+  Web3ConnectProvider: ({ children }: { children: React.ReactNode }) => children,
+}));
+
+const mockGetClient = vi.fn();
+vi.mock("../client", () => ({
+  getClient: () => mockGetClient(),
+}));
+
+import { useSendTransaction } from "./useSendTransaction";
+
+function createEvmSession() {
+  return {
+    topic: "test-topic",
+    namespaces: {
+      eip155: {
+        chains: ["eip155:1"],
+        accounts: ["eip155:1:0x1234567890123456789012345678901234567890"],
+      },
+    },
+  };
+}
+
+describe("useSendTransaction", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should have initial idle state", () => {
+    mockUseWeb3.mockReturnValue({ session: null, chainId: null });
+    mockGetClient.mockReturnValue(null);
+
+    const { result } = renderHook(() => useSendTransaction());
+
+    expect(result.current.isSending).toBe(false);
+    expect(result.current.error).toBeNull();
+  });
+
+  it("should throw when no session", async () => {
+    mockUseWeb3.mockReturnValue({ session: null, chainId: null });
+    mockGetClient.mockReturnValue({
+      sendTransaction: vi.fn(),
+    });
+
+    const { result } = renderHook(() => useSendTransaction());
+
+    await expect(async () => {
+      await act(async () => {
+        await result.current.sendTransaction({ to: "0xabcd" });
+      });
+    }).rejects.toThrow("No active session");
+
+    // Pre-condition checks throw directly without setting state
+    expect(result.current.error).toBeNull();
+  });
+
+  it("should throw when client not initialized", async () => {
+    mockUseWeb3.mockReturnValue({ session: createEvmSession(), chainId: "eip155:1" });
+    mockGetClient.mockReturnValue(null);
+
+    const { result } = renderHook(() => useSendTransaction());
+
+    await expect(async () => {
+      await act(async () => {
+        await result.current.sendTransaction({ to: "0xabcd" });
+      });
+    }).rejects.toThrow("Client not initialized");
+  });
+
+  it("should send transaction successfully", async () => {
+    const mockSendTransaction = vi.fn().mockResolvedValue("0xtxhash123");
+    mockUseWeb3.mockReturnValue({ session: createEvmSession(), chainId: "eip155:1" });
+    mockGetClient.mockReturnValue({
+      sendTransaction: mockSendTransaction,
+    });
+
+    const { result } = renderHook(() => useSendTransaction());
+
+    let txHash: string;
+    await act(async () => {
+      txHash = await result.current.sendTransaction({
+        to: "0xabcd",
+        value: "0xde0b6b3a7640000",
+      });
+    });
+
+    expect(txHash!).toBe("0xtxhash123");
+    expect(mockSendTransaction).toHaveBeenCalledTimes(1);
+    expect(mockSendTransaction).toHaveBeenCalledWith(createEvmSession(), {
+      transaction: {
+        to: "0xabcd",
+        value: "0xde0b6b3a7640000",
+        from: "0x1234567890123456789012345678901234567890",
+      },
+      chainId: "eip155:1",
+    });
+    expect(result.current.isSending).toBe(false);
+  });
+
+  it("should throw when no EVM account found", async () => {
+    const sessionWithoutEvm = {
+      topic: "test",
+      namespaces: {},
+    };
+    mockUseWeb3.mockReturnValue({ session: sessionWithoutEvm, chainId: null });
+    mockGetClient.mockReturnValue({
+      sendTransaction: vi.fn(),
+    });
+
+    const { result } = renderHook(() => useSendTransaction());
+
+    await expect(async () => {
+      await act(async () => {
+        await result.current.sendTransaction({ to: "0xabcd" });
+      });
+    }).rejects.toThrow("No EVM account found");
+  });
+
+  it("should set loading state during sending", async () => {
+    let resolvePromise: (v: string) => void;
+    const sendPromise = new Promise<string>((resolve) => {
+      resolvePromise = resolve;
+    });
+    const mockSendTransaction = vi.fn().mockReturnValue(sendPromise);
+    mockUseWeb3.mockReturnValue({ session: createEvmSession(), chainId: "eip155:1" });
+    mockGetClient.mockReturnValue({
+      sendTransaction: mockSendTransaction,
+    });
+
+    const { result } = renderHook(() => useSendTransaction());
+
+    let callPromise: Promise<string>;
+    act(() => {
+      callPromise = result.current.sendTransaction({ to: "0xabcd" });
+    });
+
+    expect(result.current.isSending).toBe(true);
+
+    await act(async () => {
+      resolvePromise!("0xtx");
+      await callPromise!;
+    });
+
+    expect(result.current.isSending).toBe(false);
+  });
+
+  it("should capture error on failed send", async () => {
+    const mockSendTransaction = vi.fn().mockRejectedValue(new Error("Transaction rejected"));
+    mockUseWeb3.mockReturnValue({ session: createEvmSession(), chainId: "eip155:1" });
+    mockGetClient.mockReturnValue({
+      sendTransaction: mockSendTransaction,
+    });
+
+    const { result } = renderHook(() => useSendTransaction());
+
+    await act(async () => {
+      try {
+        await result.current.sendTransaction({ to: "0xabcd" });
+      } catch {
+        // Expected
+      }
+    });
+
+    expect(result.current.error).not.toBeNull();
+    expect(result.current.error?.message).toBe("Transaction rejected");
+  });
+});

package/src/hooks/useSendTransaction.ts

@@ -0,0 +1,80 @@
+import { useState, useCallback } from "react";
+import { useWeb3 } from "../provider/Web3ConnectProvider";
+import { getClient } from "../client";
+import { WalletError } from "@naculus/connect-core";
+import type { EvmTransaction } from "../types";
+
+export type SendTransactionStatus = "idle" | "awaiting_approval" | "confirmed" | "failed";
+
+export function useSendTransaction() {
+  const { session, chainId } = useWeb3();
+  const [status, setStatus] = useState<SendTransactionStatus>("idle");
+  const [error, setError] = useState<Error | null>(null);
+
+  const sendTransaction = useCallback(
+    async (transaction: EvmTransaction): Promise<string> => {
+      if (!session) {
+        setStatus("failed");
+        const err = new WalletError("wallet_unavailable", "No active session");
+        setError(err);
+        throw err;
+      }
+
+      const client = getClient();
+      if (!client) {
+        setStatus("failed");
+        const err = new WalletError("wallet_unavailable", "Client not initialized");
+        setError(err);
+        throw err;
+      }
+
+      const evmAccount = Object.values(session.namespaces)
+        .flatMap((ns) => ns.accounts)
+        .find((acc) => acc.includes("0x"));
+
+      if (!evmAccount) {
+        setStatus("failed");
+        const err = new WalletError("wallet_unavailable", "No EVM account found");
+        setError(err);
+        throw err;
+      }
+
+      setStatus("awaiting_approval");
+      setError(null);
+
+      try {
+        const txWithFrom = {
+          ...transaction,
+          from: transaction.from ?? evmAccount.split(":").pop()
+        };
+
+        const result = (await client.sendTransaction(session, {
+          transaction: txWithFrom,
+          chainId: chainId ?? undefined
+        })) as string;
+
+        setStatus("confirmed");
+        return result;
+      } catch (err) {
+        setStatus("failed");
+        const errorMessage = err instanceof Error ? err.message : "Transaction failed";
+        setError(err instanceof Error ? err : new Error(errorMessage));
+        throw err;
+      }
+    },
+    [session, chainId]
+  );
+
+  const reset = useCallback(() => {
+    setStatus("idle");
+    setError(null);
+  }, []);
+
+  return {
+    sendTransaction,
+    status,
+    error,
+    reset,
+    isSending: status === "awaiting_approval"
+  };
+}