@kheopskit/core 0.0.22 → 0.1.1

package/dist/index.d.mts

@@ -3,8 +3,44 @@ import { AppKitNetwork } from '@reown/appkit/networks';
 import { Metadata } from '@walletconnect/universal-provider';
 import { InjectedExtension, InjectedPolkadotAccount } from 'polkadot-api/pjs-signer';
 import { EIP1193Provider, WalletClient, CustomTransport, Account } from 'viem';
+import * as rxjs from 'rxjs';
 import { Observable } from 'rxjs';
 
+/**
+ * Clears an observable from the cache.
+ * Use when a wallet disconnects or configuration changes.
+ */
+declare const clearCachedObservable: (key: string) => void;
+/**
+ * Clears all cached observables.
+ * Use when resetting the entire kheopskit state.
+ */
+declare const clearAllCachedObservables: () => void;
+
+type Storage = {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem: (key: string) => void;
+};
+/**
+ * Extended storage interface with cross-tab sync support.
+ */
+type SyncableStorage = Storage & {
+    /**
+     * Subscribe to storage changes from other tabs.
+     * Returns an unsubscribe function.
+     */
+    subscribe?: (key: string, callback: (value: string | null) => void) => () => void;
+};
+/**
+ * A safe localStorage wrapper that falls back to noopStorage
+ * when localStorage is not available (e.g., during SSR).
+ * Includes cross-tab sync via the native 'storage' event.
+ *
+ * Lazily initialized on first access to be SSR-safe.
+ */
+declare const getSafeLocalStorage: () => SyncableStorage;
+
 type WalletAccountId = string;
 
 type WalletId = string;
@@ -26,6 +62,30 @@ type KheopskitConfig = {
         themeVariables?: ThemeVariables;
     };
     debug: boolean;
+    /**
+     * Custom storage key for persisting wallet connection state.
+     * Useful when running multiple kheopskit instances on the same domain
+     * to prevent state conflicts between different dapps.
+     *
+     * @default "kheopskit"
+     *
+     * @example
+     * ```ts
+     * // For app "MyDapp" to avoid conflicts
+     * { storageKey: "kheopskit-mydapp" }
+     * ```
+     */
+    storageKey: string;
+    /**
+     * Grace period in milliseconds to wait for wallets to inject before
+     * syncing to actual state. During this period, cached wallet/account
+     * state from storage is preserved to prevent UI flashing.
+     *
+     * Set to 0 to disable hydration buffering.
+     *
+     * @default 500
+     */
+    hydrationGracePeriod: number;
 };
 type PolkadotInjectedWallet = {
     id: WalletId;
@@ -93,14 +153,126 @@ type EthereumAccount = {
     isWalletDefault: boolean;
 };
 type WalletAccount = PolkadotAccount | EthereumAccount;
+/**
+ * Serializable wallet data for SSR hydration cache.
+ * Contains only the data needed to render wallet UI without flash.
+ * Note: icon is NOT stored to save cookie space - it's looked up at hydration time.
+ */
+type CachedWallet = {
+    id: WalletId;
+    platform: WalletPlatform;
+    type: "injected" | "appKit";
+    name: string;
+    isConnected: boolean;
+};
+/**
+ * Serializable account data for SSR hydration cache.
+ * Contains only the data needed to render account UI without flash.
+ */
+type CachedAccount = {
+    id: string;
+    platform: WalletPlatform;
+    address: string;
+    name?: string;
+    walletId: WalletId;
+    walletName: string;
+};
+
+/**
+ * Converts a CachedWallet to a placeholder Wallet object.
+ * The placeholder has the same display properties but connect/disconnect throw errors.
+ *
+ * @param cached - The cached wallet data from storage
+ * @returns A placeholder Wallet object that can be displayed but not interacted with
+ */
+declare const hydrateWallet: (cached: CachedWallet) => Wallet;
+/**
+ * Converts a CachedAccount to a placeholder WalletAccount object.
+ *
+ * @param cached - The cached account data from storage
+ * @returns A placeholder WalletAccount object that can be displayed
+ */
+declare const hydrateAccount: (cached: CachedAccount) => WalletAccount;
+
+/**
+ * Gets a cached icon for a wallet.
+ * @param walletId - The wallet ID (e.g., "ethereum:io.talisman")
+ * @returns The cached icon data URI, or undefined if not cached
+ */
+declare const getCachedIcon: (walletId: string) => string | undefined;
 
+/**
+ * Clears the cached AppKit observable.
+ * Use when configuration changes or for testing purposes.
+ * Note: This does NOT destroy the appKit instance created by Reown.
+ */
+declare const resetAppKitCache: () => void;
+
+/**
+ * Default storage key for persisting wallet connection state.
+ * Can be overridden via config.storageKey to avoid conflicts
+ * when running multiple dapps on the same domain.
+ */
+declare const DEFAULT_STORAGE_KEY = "kheopskit";
 declare const resolveConfig: (config: Partial<KheopskitConfig> | undefined) => KheopskitConfig;
 
+type KheopskitStoreData = {
+    autoReconnect?: WalletId[];
+    /** Cached wallet state for SSR hydration to prevent UI flash */
+    cachedWallets?: CachedWallet[];
+    /** Cached account state for SSR hydration to prevent UI flash */
+    cachedAccounts?: CachedAccount[];
+};
+type CreateKheopskitStoreOptions = {
+    /**
+     * Cookie string for SSR hydration.
+     * When provided, uses cookieStorage instead of localStorage.
+     */
+    ssrCookies?: string;
+    /**
+     * Custom storage key to namespace the stored data.
+     * @default "kheopskit"
+     */
+    storageKey?: string;
+};
+/**
+ * Creates a kheopskit store with the appropriate storage backend.
+ * Uses cookieStorage when ssrCookies is provided (for SSR hydration),
+ * otherwise falls back to safeLocalStorage.
+ *
+ * @param options - Configuration options for the store
+ */
+declare const createKheopskitStore: (options?: CreateKheopskitStoreOptions) => {
+    observable: rxjs.Observable<KheopskitStoreData>;
+    addEnabledWalletId: (walletId: WalletId) => void;
+    removeEnabledWalletId: (walletId: WalletId) => void;
+    getCachedState: () => {
+        wallets: CachedWallet[];
+        accounts: CachedAccount[];
+    };
+    setCachedState: (wallets: CachedWallet[], accounts: CachedAccount[]) => void;
+};
+type KheopskitStore = ReturnType<typeof createKheopskitStore>;
+/**
+ * Gets the default store, creating it on first access.
+ * Uses localStorage on client, noop on server.
+ * Lazily initialized to avoid SSR issues with module-level code.
+ */
+declare const getDefaultStore: () => KheopskitStore;
+
 type KheopskitState = {
     wallets: Wallet[];
     accounts: WalletAccount[];
     config: KheopskitConfig;
+    /**
+     * Whether the state is still being hydrated from cache.
+     * During hydration, cached wallets/accounts may be displayed
+     * before the actual wallet extensions have injected.
+     *
+     * Use this to show loading indicators or disable certain actions.
+     */
+    isHydrating: boolean;
 };
-declare const getKheopskit$: (config?: Partial<KheopskitConfig>) => Observable<KheopskitState>;
+declare const getKheopskit$: (config?: Partial<KheopskitConfig>, ssrCookies?: string, existingStore?: ReturnType<typeof createKheopskitStore>) => Observable<KheopskitState>;
 
-export { type EthereumAccount, type EthereumAppKitWallet, type EthereumInjectedWallet, type EthereumWallet, type KheopskitConfig, type KheopskitState, type PolkadotAccount, type PolkadotAppKitWallet, type PolkadotInjectedWallet, type PolkadotWallet, type Wallet, type WalletAccount, type WalletPlatform, getKheopskit$, resolveConfig };
+export { type CachedAccount, type CachedWallet, DEFAULT_STORAGE_KEY, type EthereumAccount, type EthereumAppKitWallet, type EthereumInjectedWallet, type EthereumWallet, type KheopskitConfig, type KheopskitState, type PolkadotAccount, type PolkadotAppKitWallet, type PolkadotInjectedWallet, type PolkadotWallet, type Wallet, type WalletAccount, type WalletPlatform, clearAllCachedObservables, clearCachedObservable, createKheopskitStore, getCachedIcon, getDefaultStore, getKheopskit$, getSafeLocalStorage, hydrateAccount, hydrateWallet, resetAppKitCache, resolveConfig };

package/dist/index.d.ts

@@ -3,8 +3,44 @@ import { AppKitNetwork } from '@reown/appkit/networks';
 import { Metadata } from '@walletconnect/universal-provider';
 import { InjectedExtension, InjectedPolkadotAccount } from 'polkadot-api/pjs-signer';
 import { EIP1193Provider, WalletClient, CustomTransport, Account } from 'viem';
+import * as rxjs from 'rxjs';
 import { Observable } from 'rxjs';
 
+/**
+ * Clears an observable from the cache.
+ * Use when a wallet disconnects or configuration changes.
+ */
+declare const clearCachedObservable: (key: string) => void;
+/**
+ * Clears all cached observables.
+ * Use when resetting the entire kheopskit state.
+ */
+declare const clearAllCachedObservables: () => void;
+
+type Storage = {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem: (key: string) => void;
+};
+/**
+ * Extended storage interface with cross-tab sync support.
+ */
+type SyncableStorage = Storage & {
+    /**
+     * Subscribe to storage changes from other tabs.
+     * Returns an unsubscribe function.
+     */
+    subscribe?: (key: string, callback: (value: string | null) => void) => () => void;
+};
+/**
+ * A safe localStorage wrapper that falls back to noopStorage
+ * when localStorage is not available (e.g., during SSR).
+ * Includes cross-tab sync via the native 'storage' event.
+ *
+ * Lazily initialized on first access to be SSR-safe.
+ */
+declare const getSafeLocalStorage: () => SyncableStorage;
+
 type WalletAccountId = string;
 
 type WalletId = string;
@@ -26,6 +62,30 @@ type KheopskitConfig = {
         themeVariables?: ThemeVariables;
     };
     debug: boolean;
+    /**
+     * Custom storage key for persisting wallet connection state.
+     * Useful when running multiple kheopskit instances on the same domain
+     * to prevent state conflicts between different dapps.
+     *
+     * @default "kheopskit"
+     *
+     * @example
+     * ```ts
+     * // For app "MyDapp" to avoid conflicts
+     * { storageKey: "kheopskit-mydapp" }
+     * ```
+     */
+    storageKey: string;
+    /**
+     * Grace period in milliseconds to wait for wallets to inject before
+     * syncing to actual state. During this period, cached wallet/account
+     * state from storage is preserved to prevent UI flashing.
+     *
+     * Set to 0 to disable hydration buffering.
+     *
+     * @default 500
+     */
+    hydrationGracePeriod: number;
 };
 type PolkadotInjectedWallet = {
     id: WalletId;
@@ -93,14 +153,126 @@ type EthereumAccount = {
     isWalletDefault: boolean;
 };
 type WalletAccount = PolkadotAccount | EthereumAccount;
+/**
+ * Serializable wallet data for SSR hydration cache.
+ * Contains only the data needed to render wallet UI without flash.
+ * Note: icon is NOT stored to save cookie space - it's looked up at hydration time.
+ */
+type CachedWallet = {
+    id: WalletId;
+    platform: WalletPlatform;
+    type: "injected" | "appKit";
+    name: string;
+    isConnected: boolean;
+};
+/**
+ * Serializable account data for SSR hydration cache.
+ * Contains only the data needed to render account UI without flash.
+ */
+type CachedAccount = {
+    id: string;
+    platform: WalletPlatform;
+    address: string;
+    name?: string;
+    walletId: WalletId;
+    walletName: string;
+};
+
+/**
+ * Converts a CachedWallet to a placeholder Wallet object.
+ * The placeholder has the same display properties but connect/disconnect throw errors.
+ *
+ * @param cached - The cached wallet data from storage
+ * @returns A placeholder Wallet object that can be displayed but not interacted with
+ */
+declare const hydrateWallet: (cached: CachedWallet) => Wallet;
+/**
+ * Converts a CachedAccount to a placeholder WalletAccount object.
+ *
+ * @param cached - The cached account data from storage
+ * @returns A placeholder WalletAccount object that can be displayed
+ */
+declare const hydrateAccount: (cached: CachedAccount) => WalletAccount;
+
+/**
+ * Gets a cached icon for a wallet.
+ * @param walletId - The wallet ID (e.g., "ethereum:io.talisman")
+ * @returns The cached icon data URI, or undefined if not cached
+ */
+declare const getCachedIcon: (walletId: string) => string | undefined;
 
+/**
+ * Clears the cached AppKit observable.
+ * Use when configuration changes or for testing purposes.
+ * Note: This does NOT destroy the appKit instance created by Reown.
+ */
+declare const resetAppKitCache: () => void;
+
+/**
+ * Default storage key for persisting wallet connection state.
+ * Can be overridden via config.storageKey to avoid conflicts
+ * when running multiple dapps on the same domain.
+ */
+declare const DEFAULT_STORAGE_KEY = "kheopskit";
 declare const resolveConfig: (config: Partial<KheopskitConfig> | undefined) => KheopskitConfig;
 
+type KheopskitStoreData = {
+    autoReconnect?: WalletId[];
+    /** Cached wallet state for SSR hydration to prevent UI flash */
+    cachedWallets?: CachedWallet[];
+    /** Cached account state for SSR hydration to prevent UI flash */
+    cachedAccounts?: CachedAccount[];
+};
+type CreateKheopskitStoreOptions = {
+    /**
+     * Cookie string for SSR hydration.
+     * When provided, uses cookieStorage instead of localStorage.
+     */
+    ssrCookies?: string;
+    /**
+     * Custom storage key to namespace the stored data.
+     * @default "kheopskit"
+     */
+    storageKey?: string;
+};
+/**
+ * Creates a kheopskit store with the appropriate storage backend.
+ * Uses cookieStorage when ssrCookies is provided (for SSR hydration),
+ * otherwise falls back to safeLocalStorage.
+ *
+ * @param options - Configuration options for the store
+ */
+declare const createKheopskitStore: (options?: CreateKheopskitStoreOptions) => {
+    observable: rxjs.Observable<KheopskitStoreData>;
+    addEnabledWalletId: (walletId: WalletId) => void;
+    removeEnabledWalletId: (walletId: WalletId) => void;
+    getCachedState: () => {
+        wallets: CachedWallet[];
+        accounts: CachedAccount[];
+    };
+    setCachedState: (wallets: CachedWallet[], accounts: CachedAccount[]) => void;
+};
+type KheopskitStore = ReturnType<typeof createKheopskitStore>;
+/**
+ * Gets the default store, creating it on first access.
+ * Uses localStorage on client, noop on server.
+ * Lazily initialized to avoid SSR issues with module-level code.
+ */
+declare const getDefaultStore: () => KheopskitStore;
+
 type KheopskitState = {
     wallets: Wallet[];
     accounts: WalletAccount[];
     config: KheopskitConfig;
+    /**
+     * Whether the state is still being hydrated from cache.
+     * During hydration, cached wallets/accounts may be displayed
+     * before the actual wallet extensions have injected.
+     *
+     * Use this to show loading indicators or disable certain actions.
+     */
+    isHydrating: boolean;
 };
-declare const getKheopskit$: (config?: Partial<KheopskitConfig>) => Observable<KheopskitState>;
+declare const getKheopskit$: (config?: Partial<KheopskitConfig>, ssrCookies?: string, existingStore?: ReturnType<typeof createKheopskitStore>) => Observable<KheopskitState>;
 
-export { type EthereumAccount, type EthereumAppKitWallet, type EthereumInjectedWallet, type EthereumWallet, type KheopskitConfig, type KheopskitState, type PolkadotAccount, type PolkadotAppKitWallet, type PolkadotInjectedWallet, type PolkadotWallet, type Wallet, type WalletAccount, type WalletPlatform, getKheopskit$, resolveConfig };
+export { type CachedAccount, type CachedWallet, DEFAULT_STORAGE_KEY, type EthereumAccount, type EthereumAppKitWallet, type EthereumInjectedWallet, type EthereumWallet, type KheopskitConfig, type KheopskitState, type PolkadotAccount, type PolkadotAppKitWallet, type PolkadotInjectedWallet, type PolkadotWallet, type Wallet, type WalletAccount, type WalletPlatform, clearAllCachedObservables, clearCachedObservable, createKheopskitStore, getCachedIcon, getDefaultStore, getKheopskit$, getSafeLocalStorage, hydrateAccount, hydrateWallet, resetAppKitCache, resolveConfig };