@kheopskit/core 1.0.1 → 5.0.0

package/dist/index.d.mts

@@ -1,220 +1,9 @@
-import { AppKit, ThemeMode, ThemeVariables } from '@reown/appkit/core';
-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';
+export { c as clearAllCachedObservables } from './getCachedObservable-C4E8dfMp.mjs';
+import { K as KheopskitPlatform, d as KheopskitConfig, a as WalletId, e as createKheopskitStore, f as KheopskitState } from './types-C7V7DGlg.mjs';
+export { A as AccountOf, g as AppKitInstance, B as BaseWallet, h as BaseWalletAccount, C as CachedAccount, j as CachedWallet, P as PlatformContext, k as PolkadotAccountType, W as WalletAccountId, l as WalletConnectConfig, m as WalletConnectMetadata, n as WalletConnectProvider, b as WalletConnectWallet, o as WalletOf, p as WalletPlatform, q as WalletType, r as getDefaultStore, s as getWalletAccountId, t as getWalletId, i as isInjectedWallet, u as isValidWalletId, c as isWalletConnectWallet, v as parseWalletAccountId, w as parseWalletId } from './types-C7V7DGlg.mjs';
 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;
-
-type KheopskitConfig = {
-    autoReconnect: boolean;
-    platforms: WalletPlatform[];
-    /**
-     * Allowed Polkadot account key types.
-     * Accounts with other key types are filtered out from kheopskit state.
-     *
-     * @default ["sr25519", "ed25519", "ecdsa"]
-     */
-    polkadotAccountTypes: PolkadotAccountType[];
-    walletConnect?: {
-        projectId: string;
-        metadata: Metadata;
-        /** Defaults to wss://relay.walletconnect.com */
-        relayUrl?: string;
-        /**
-         * list of CAIP-13 ids of polkadot-sdk chains
-         * see https://docs.reown.com/advanced/multichain/polkadot/dapp-integration-guide#walletconnect-code%2Fcomponent-setup
-         */
-        networks: [AppKitNetwork, ...AppKitNetwork[]];
-        themeMode?: ThemeMode;
-        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;
-    platform: "polkadot";
-    type: "injected";
-    extensionId: string;
-    extension: InjectedExtension | undefined;
-    name: string;
-    icon: string;
-    isConnected: boolean;
-    connect: () => Promise<void>;
-    disconnect: () => void;
-};
-type PolkadotAppKitWallet = {
-    id: WalletId;
-    platform: "polkadot";
-    type: "appKit";
-    appKit: AppKit;
-    name: string;
-    icon: string;
-    isConnected: boolean;
-    connect: () => Promise<void>;
-    disconnect: () => void;
-};
-type PolkadotWallet = PolkadotInjectedWallet | PolkadotAppKitWallet;
-type EthereumInjectedWallet = {
-    platform: "ethereum";
-    type: "injected";
-    id: WalletId;
-    providerId: string;
-    provider: EIP1193Provider;
-    name: string;
-    icon: string;
-    isConnected: boolean;
-    connect: () => Promise<void>;
-    disconnect: () => void;
-};
-type EthereumAppKitWallet = {
-    platform: "ethereum";
-    type: "appKit";
-    id: WalletId;
-    appKit: AppKit;
-    name: string;
-    icon: string;
-    isConnected: boolean;
-    connect: () => Promise<void>;
-    disconnect: () => void;
-};
-type EthereumWallet = EthereumInjectedWallet | EthereumAppKitWallet;
-type Wallet = PolkadotWallet | EthereumWallet;
-type WalletPlatform = Wallet["platform"];
-type PolkadotAccountType = "sr25519" | "ed25519" | "ecdsa" | "ethereum";
-type PolkadotAccount = Omit<InjectedPolkadotAccount, "type"> & {
-    type: PolkadotAccountType;
-    id: WalletAccountId;
-    platform: "polkadot";
-    walletName: string;
-    walletId: string;
-};
-type EthereumAccount = {
-    id: WalletAccountId;
-    platform: "ethereum";
-    client: WalletClient<CustomTransport, undefined, Account, undefined>;
-    address: `0x${string}`;
-    /** Current chain ID the wallet is connected to. `undefined` while loading or after provider disconnect. */
-    chainId: number | undefined;
-    walletName: string;
-    walletId: string;
-    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;
-    /** Cached chain ID for Ethereum accounts. */
-    chainId?: number;
-    /** Cached key type for Polkadot accounts. */
-    polkadotAccountType?: PolkadotAccountType;
-    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;
+declare const isValidAddress: (address: string) => boolean;
 
 /**
  * Clears the cached AppKit observable.
@@ -229,65 +18,64 @@ declare const resetAppKitCache: () => void;
  * when running multiple dapps on the same domain.
  */
 declare const DEFAULT_STORAGE_KEY = "kheopskit";
-declare const resolveConfig: (config: Partial<KheopskitConfig> | undefined) => KheopskitConfig;
+declare const resolveConfig: <const P extends readonly KheopskitPlatform[] = readonly KheopskitPlatform[]>(config?: Partial<KheopskitConfig<P>>) => KheopskitConfig<P>;
 
-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
+ * Stable error codes thrown by kheopskit. Catch a {@link KheopskitError} and
+ * branch on `error.code` instead of matching message strings.
  */
-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>;
+type KheopskitErrorCode = 
+/** `connect()` called on a wallet that is already connected. */
+"WALLET_ALREADY_CONNECTED"
+/** `disconnect()` called on a wallet that is not connected. */
+ | "WALLET_NOT_CONNECTED"
+/** The wallet does not advertise a capability kheopskit needs to proceed. */
+ | "FEATURE_NOT_SUPPORTED"
+/** No active WalletConnect session for the requested operation. */
+ | "NO_SESSION"
+/** No provider available for the requested namespace. */
+ | "NO_PROVIDER"
+/** The requested chain cannot be used for this operation (e.g. a Solana cluster with no CAIP-2 id over WalletConnect). */
+ | "UNSUPPORTED_CHAIN";
 /**
- * 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.
+ * Error thrown by kheopskit wallet/account operations. Carries a stable
+ * {@link KheopskitErrorCode} and, when relevant, the offending wallet id.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await wallet.connect();
+ * } catch (error) {
+ *   if (error instanceof KheopskitError && error.code === "WALLET_ALREADY_CONNECTED") {
+ *     // ignore
+ *   } else throw error;
+ * }
+ * ```
  */
-declare const getDefaultStore: () => KheopskitStore;
+declare class KheopskitError extends Error {
+    readonly code: KheopskitErrorCode;
+    /** The wallet id this error relates to, when applicable. */
+    readonly walletId?: WalletId;
+    constructor(code: KheopskitErrorCode, message: string, options?: {
+        walletId?: WalletId;
+        cause?: unknown;
+    });
+}
 
-type KheopskitState = {
-    wallets: Wallet[];
-    accounts: WalletAccount[];
-    config: KheopskitConfig;
+/** Options for {@link getKheopskit$}. */
+type GetKheopskitOptions = {
+    /**
+     * Cookie string for SSR hydration. When provided, state is read from cookies
+     * instead of localStorage so the server can hydrate without a flash. Pass the
+     * request's `cookie` header.
+     */
+    ssrCookies?: string;
     /**
-     * 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.
+     * An existing store to reuse instead of creating one. Advanced escape hatch —
+     * most callers omit it. (`@kheopskit/react` passes its provider-scoped store.)
      */
-    isHydrating: boolean;
+    store?: ReturnType<typeof createKheopskitStore>;
 };
-declare const getKheopskit$: (config?: Partial<KheopskitConfig>, ssrCookies?: string, existingStore?: ReturnType<typeof createKheopskitStore>) => Observable<KheopskitState>;
+declare const getKheopskit$: <const P extends readonly KheopskitPlatform[] = readonly KheopskitPlatform[]>(config?: Partial<KheopskitConfig<P>>, options?: GetKheopskitOptions) => Observable<KheopskitState<P>>;
 
-export { type CachedAccount, type CachedWallet, DEFAULT_STORAGE_KEY, type EthereumAccount, type EthereumAppKitWallet, type EthereumInjectedWallet, type EthereumWallet, type KheopskitConfig, type KheopskitState, type PolkadotAccount, type PolkadotAccountType, type PolkadotAppKitWallet, type PolkadotInjectedWallet, type PolkadotWallet, type Wallet, type WalletAccount, type WalletPlatform, clearAllCachedObservables, clearCachedObservable, createKheopskitStore, getCachedIcon, getDefaultStore, getKheopskit$, getSafeLocalStorage, hydrateAccount, hydrateWallet, resetAppKitCache, resolveConfig };
+export { DEFAULT_STORAGE_KEY, type GetKheopskitOptions, KheopskitConfig, KheopskitError, type KheopskitErrorCode, KheopskitPlatform, KheopskitState, WalletId, createKheopskitStore, getKheopskit$, isValidAddress, resetAppKitCache, resolveConfig };