@naculus/connect-appkit-react 0.1.2

package/src/hooks/useLookupAddress.ts

@@ -0,0 +1,131 @@
+import { useState, useEffect, useCallback, useRef } from "react";
+import { NameResolver } from "@naculus/connect-core";
+import type { NameResult, NameResolverConfig } from "@naculus/connect-core";
+
+/**
+ * Options for the useLookupAddress hook.
+ */
+export interface UseLookupAddressOptions {
+  /** Optional CAIP-2 chain ID to hint which provider to use. */
+  chainId?: string;
+  /** Whether to skip lookup. Default: false. */
+  skip?: boolean;
+  /** Custom resolver configuration (overrides default RPC URLs). */
+  resolverConfig?: NameResolverConfig;
+}
+
+/**
+ * Result of an address reverse-lookup query.
+ */
+export interface UseLookupAddressResult {
+  /** Resolved name, or null if not found / not started. */
+  data: NameResult | null;
+  /** Whether the lookup is in progress. */
+  isLoading: boolean;
+  /** Error that occurred during lookup, if any. */
+  error: Error | null;
+  /** Manually trigger re-lookup of the current address. */
+  refetch: () => void;
+}
+
+// Lazy singleton resolver to avoid creating one per component instance.
+let sharedResolver: NameResolver | null = null;
+
+function getResolver(config?: NameResolverConfig): NameResolver {
+  if (config) {
+    return new NameResolver(config);
+  }
+  if (!sharedResolver) {
+    sharedResolver = new NameResolver();
+  }
+  return sharedResolver;
+}
+
+/**
+ * React hook to reverse-lookup a blockchain address to find its human-readable name.
+ *
+ * Supports ENS (.eth) and SNS (.sol) names.
+ * Auto-detects the name service from the address format or chainId hint.
+ *
+ * @example
+ * ```tsx
+ * function TransactionRow({ address }: { address: string }) {
+ *   const { data, isLoading } = useLookupAddress(address);
+ *   return <span>{data?.name ?? address}</span>;
+ * }
+ * ```
+ */
+export function useLookupAddress(
+  address: string,
+  options?: UseLookupAddressOptions,
+): UseLookupAddressResult {
+  const [data, setData] = useState<NameResult | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const chainId = options?.chainId;
+  const skip = options?.skip ?? false;
+  const resolverRef = useRef<NameResolver | null>(null);
+  const activeAddrRef = useRef<string>("");
+  const mountedRef = useRef(true);
+
+  // Keep mounted ref current
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const resolver = resolverRef.current ?? getResolver(options?.resolverConfig);
+  resolverRef.current = resolver;
+
+  const lookup = useCallback(() => {
+    const cleanAddr = address.trim();
+
+    if (!cleanAddr || skip) {
+      setData(null);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    // Avoid re-looking-up the same address
+    if (activeAddrRef.current === cleanAddr && data) {
+      return;
+    }
+
+    activeAddrRef.current = cleanAddr;
+    setIsLoading(true);
+    setError(null);
+
+    resolver
+      .lookupAddress(cleanAddr, chainId)
+      .then((result) => {
+        if (mountedRef.current) {
+          setData(result);
+          setIsLoading(false);
+        }
+      })
+      .catch((err: unknown) => {
+        if (mountedRef.current) {
+          const resolutionError =
+            err instanceof Error ? err : new Error(String(err));
+          setError(resolutionError);
+          setData(null);
+          setIsLoading(false);
+        }
+      });
+  }, [address, chainId, skip]);
+
+  // Lookup when address or chainId changes
+  useEffect(() => {
+    lookup();
+  }, [lookup]);
+
+  const refetch = useCallback(() => {
+    activeAddrRef.current = "";
+    lookup();
+  }, [lookup]);
+
+  return { data, isLoading, error, refetch };
+}

package/src/hooks/useNotification.ts

@@ -0,0 +1,308 @@
+/**
+ * useNotification — React hook for push notification state.
+ *
+ * Provides notifications, settings, and control methods for the
+ * in-app notification center.
+ *
+ * @example
+ * ```tsx
+ * import { useNotification } from "@naculus/connect-appkit-react";
+ *
+ * function NotificationCenter() {
+ *   const { notifications, unreadCount, clear, markAsRead } = useNotification();
+ *   return (
+ *     <div>
+ *       <span>Unread: {unreadCount}</span>
+ *       <ul>
+ *         {notifications.map(n => (
+ *           <li key={n.id} onClick={() => markAsRead(n.id)}>
+ *             {n.title} — {n.body}
+ *           </li>
+ *         ))}
+ *       </ul>
+ *       <button onClick={clear}>Clear all</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+
+import { useState, useCallback, useMemo, useEffect, useRef } from "react";
+import {
+  InAppChannel,
+  type NotificationItem,
+  type NotificationSettings,
+  type NotificationFrequency,
+  type TxStatus,
+} from "@naculus/connect-core";
+import { createStorageAdapter } from "@naculus/connect-core";
+
+// ─── Default settings ─────────────────────────────────────────────────
+
+const DEFAULT_SETTINGS: NotificationSettings = {
+  telegram: false,
+  webpush: false,
+  inapp: true,
+  frequency: "final-only" as NotificationFrequency,
+  mutedChains: [],
+  mutedTypes: [],
+};
+
+const STORAGE_KEY_SETTINGS = "naculus_notif_react_settings";
+
+// ─── Hook ──────────────────────────────────────────────────────────────
+
+/**
+ * Hook for consuming in-app notifications in React components.
+ *
+ * Uses InAppChannel internally to manage the notification queue.
+ * All persistent state is stored via localStorage.
+ */
+export function useNotification(options?: {
+  /** External InAppChannel instance (for sharing between hooks). If omitted, creates one. */
+  channel?: InAppChannel;
+  /** Custom storage for settings (defaults to localStorage) */
+  storage?: {
+    getItem: <T>(key: string) => Promise<T | null>;
+    setItem: <T>(key: string, value: T) => Promise<void>;
+    removeItem: (key: string) => Promise<void>;
+  };
+}) {
+  // ── Channel ──────────────────────────────────────────────────────
+
+  const channelRef = useRef<InAppChannel | null>(null);
+
+  if (!channelRef.current) {
+    channelRef.current = options?.channel ?? new InAppChannel();
+  }
+
+  const channel = channelRef.current;
+
+  // ── State ────────────────────────────────────────────────────────
+
+  const [notifications, setNotifications] = useState<NotificationItem[]>(() =>
+    channel.getHistory(),
+  );
+
+  const [settings, setSettingsState] = useState<NotificationSettings>(() => {
+    // Try to load from storage, fall back to default
+    return DEFAULT_SETTINGS;
+  });
+
+  // ── Load persisted settings on mount ──────────────────────────────
+
+  useEffect(() => {
+    const storage = options?.storage ?? createReactStorage();
+    storage.getItem<NotificationSettings>(STORAGE_KEY_SETTINGS).then((saved) => {
+      if (saved) {
+        setSettingsState(saved);
+      }
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // ── Sync notifications with channel ──────────────────────────────
+
+  useEffect(() => {
+    // Set up callback to reactively update state when new notifications arrive
+    channel.onNotification = (item) => {
+      setNotifications((prev) => [...prev, item]);
+    };
+
+    // Restore persisted history
+    channel.restore().then(() => {
+      setNotifications(channel.getHistory());
+    });
+
+    return () => {
+      // Cleanup: deregister callback on unmount
+      channel.onNotification = undefined;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // ── Computed ─────────────────────────────────────────────────────
+
+  const unreadCount = useMemo(() => {
+    return notifications.filter((n) => !n.read).length;
+  }, [notifications]);
+
+  // ── Actions ──────────────────────────────────────────────────────
+
+  const clear = useCallback(() => {
+    channel.clear();
+    setNotifications([]);
+  }, [channel]);
+
+  const clearOne = useCallback((id: string) => {
+    const updated = channel.getHistory().filter((n) => n.id !== id);
+    // Mutate channel history in place (we recreate from the in-memory history)
+    channel.clear();
+    // Re-add the ones we want to keep
+    Promise.all(
+      updated.map((item) =>
+        channel.send({
+          id: item.id,
+          userId: "",
+          txHash: item.txHash,
+          chainId: "",
+          chainName: item.chainName,
+          status: item.status,
+          title: item.title,
+          body: item.body,
+          valueFormatted: item.valueFormatted,
+          explorerUrl: item.explorerUrl,
+          timestamp: item.timestamp,
+        }),
+      ),
+    ).then(() => {
+      // Force re-sync
+      setNotifications(channel.getHistory());
+    });
+  }, [channel]);
+
+  const markAsRead = useCallback(
+    (id: string) => {
+      channel.markAsRead(id);
+      setNotifications((prev) =>
+        prev.map((n) => (n.id === id ? { ...n, read: true } : n)),
+      );
+    },
+    [channel],
+  );
+
+  const markAllAsRead = useCallback(() => {
+    channel.markAllAsRead();
+    setNotifications((prev) => prev.map((n) => ({ ...n, read: true })));
+  }, [channel]);
+
+  // ── Add single notification ──────────────────────────────────────
+
+  const addNotification = useCallback(
+    (item: Omit<NotificationItem, "id" | "timestamp">) => {
+      const full: NotificationItem = {
+        ...item,
+        id: `notif_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+        timestamp: Date.now(),
+      };
+      channel.send({
+        id: full.id,
+        userId: "",
+        txHash: full.txHash,
+        chainId: "",
+        chainName: full.chainName,
+        status: full.status,
+        title: full.title,
+        body: full.body,
+        valueFormatted: full.valueFormatted,
+        explorerUrl: full.explorerUrl,
+        timestamp: full.timestamp,
+      });
+      // The onNotification callback will update state
+    },
+    [channel],
+  );
+
+  // ── Settings ──────────────────────────────────────────────────────
+
+  const updateSettings = useCallback(
+    (update: Partial<NotificationSettings>) => {
+      setSettingsState((prev) => {
+        const next = { ...prev, ...update };
+        const storage = options?.storage ?? createReactStorage();
+        storage.setItem(STORAGE_KEY_SETTINGS, next).catch(() => {});
+        return next;
+      });
+    },
+    [options?.storage],
+  );
+
+  const setChannels = useCallback(
+    (channels: string[]) => {
+      const update: Partial<NotificationSettings> = {};
+      if (channels.includes("telegram")) update.telegram = true;
+      if (channels.includes("webpush")) update.webpush = true;
+      if (channels.includes("inapp")) update.inapp = true;
+      updateSettings(update);
+    },
+    [updateSettings],
+  );
+
+  const muteChain = useCallback(
+    (chainId: string) => {
+      updateSettings({
+        mutedChains: [...new Set([...settings.mutedChains, chainId])],
+      });
+    },
+    [settings.mutedChains, updateSettings],
+  );
+
+  const unmuteChain = useCallback(
+    (chainId: string) => {
+      updateSettings({
+        mutedChains: settings.mutedChains.filter((c) => c !== chainId),
+      });
+    },
+    [settings.mutedChains, updateSettings],
+  );
+
+  // ── Return ───────────────────────────────────────────────────────
+
+  return {
+    /** All in-app notifications (newest last) */
+    notifications,
+    /** Number of unread notifications */
+    unreadCount,
+    /** Add a single notification manually */
+    addNotification,
+    /** Clear all in-app notifications */
+    clear,
+    /** Clear a single notification */
+    clearOne,
+    /** Mark a notification as read */
+    markAsRead,
+    /** Mark all as read */
+    markAllAsRead,
+    /** Current notification settings */
+    settings,
+    /** Update notification settings */
+    updateSettings,
+    /** Set active channels by id */
+    setChannels,
+    /** Mute a chain */
+    muteChain,
+    /** Unmute a chain */
+    unmuteChain,
+  };
+}
+
+// ─── Storage helper ───────────────────────────────────────────────────
+
+function createReactStorage() {
+  const storage = createStorageAdapter("local", "naculus_notif_");
+
+  return {
+    getItem: async <T>(key: string): Promise<T | null> => {
+      try {
+        return await storage.get<T>(key);
+      } catch (e) {
+        console.warn("useNotification: failed to read from storage:", e);
+        return null;
+      }
+    },
+    setItem: async <T>(key: string, value: T): Promise<void> => {
+      try {
+        await storage.set(key, value);
+      } catch (e) {
+        console.warn("useNotification: failed to write to storage:", e);
+      }
+    },
+    removeItem: async (key: string): Promise<void> => {
+      try {
+        await storage.remove(key);
+      } catch (e) {
+        console.warn("useNotification: failed to remove from storage:", e);
+      }
+    },
+  };
+}

package/src/hooks/useResolveName.ts

@@ -0,0 +1,128 @@
+import { useState, useEffect, useCallback, useRef } from "react";
+import { NameResolver } from "@naculus/connect-core";
+import type { AddressResult, NameResolverConfig } from "@naculus/connect-core";
+
+/**
+ * Options for the useResolveName hook.
+ */
+export interface UseResolveNameOptions {
+  /** Whether to skip resolution (e.g. if input is invalid). Default: false. */
+  skip?: boolean;
+  /** Custom resolver configuration (overrides default RPC URLs). */
+  resolverConfig?: NameResolverConfig;
+}
+
+/**
+ * Result of a name resolution query.
+ */
+export interface UseResolveNameResult {
+  /** Resolved address, or null if not found / not started. */
+  data: AddressResult | null;
+  /** Whether the resolution is in progress. */
+  isLoading: boolean;
+  /** Error that occurred during resolution, if any. */
+  error: Error | null;
+  /** Manually trigger re-resolution of the current name. */
+  refetch: () => void;
+}
+
+// Lazy singleton resolver to avoid creating one per component instance.
+let sharedResolver: NameResolver | null = null;
+
+function getResolver(config?: NameResolverConfig): NameResolver {
+  if (config) {
+    return new NameResolver(config);
+  }
+  if (!sharedResolver) {
+    sharedResolver = new NameResolver();
+  }
+  return sharedResolver;
+}
+
+/**
+ * React hook to resolve a human-readable name to a blockchain address.
+ *
+ * Supports ENS (.eth) and SNS (.sol) names.
+ * Automatically detects the name service from the suffix.
+ *
+ * @example
+ * ```tsx
+ * function AddressInput() {
+ *   const { data, isLoading, error } = useResolveName('vitalik.eth');
+ *   return <div>{data?.address ?? 'Enter a name'}</div>;
+ * }
+ * ```
+ */
+export function useResolveName(
+  name: string,
+  options?: UseResolveNameOptions,
+): UseResolveNameResult {
+  const [data, setData] = useState<AddressResult | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const skip = options?.skip ?? false;
+  const resolverRef = useRef<NameResolver | null>(null);
+  const activeNameRef = useRef<string>("");
+  const mountedRef = useRef(true);
+
+  // Keep mounted ref current
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const resolver = resolverRef.current ?? getResolver(options?.resolverConfig);
+  resolverRef.current = resolver;
+
+  const resolve = useCallback(() => {
+    const cleanName = name.trim();
+
+    if (!cleanName || skip) {
+      setData(null);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    // Avoid re-resolving the same name
+    if (activeNameRef.current === cleanName && data) {
+      return;
+    }
+
+    activeNameRef.current = cleanName;
+    setIsLoading(true);
+    setError(null);
+
+    resolver
+      .resolveName(cleanName)
+      .then((result) => {
+        if (mountedRef.current) {
+          setData(result);
+          setIsLoading(false);
+        }
+      })
+      .catch((err: unknown) => {
+        if (mountedRef.current) {
+          const resolutionError =
+            err instanceof Error ? err : new Error(String(err));
+          setError(resolutionError);
+          setData(null);
+          setIsLoading(false);
+        }
+      });
+  }, [name, skip]);
+
+  // Resolve when name changes
+  useEffect(() => {
+    resolve();
+  }, [resolve]);
+
+  const refetch = useCallback(() => {
+    activeNameRef.current = "";
+    resolve();
+  }, [resolve]);
+
+  return { data, isLoading, error, refetch };
+}