@rango-dev/wallets-core 0.0.0-experimental-936229e8-20251208

package/src/hub/store/extend.ts

@@ -0,0 +1,125 @@
+import type {
+  Event,
+  ProviderConnectedEvent,
+  ProviderConnectingEvent,
+  ProviderDisconnectedEvent,
+} from './events.js';
+import type { RawStore, State } from './store.js';
+
+import { guessProviderStateSelector } from './selectors.js';
+
+export interface Store extends Omit<RawStore, 'subscribe'> {
+  subscribe(listener: (event: Event, state: State, prevState: State) => void): {
+    flushEvents(): void;
+  };
+}
+
+/**
+ * Zustand's store provides a set of built-in functionalities,
+ * but it may not meet all our requirements.
+ * This function modifies the interface and adds or updates the available methods.
+ */
+export function extend(store: RawStore): Store {
+  const extendedSubscribe: (store: RawStore) => Store['subscribe'] =
+    (store) => (listener) => {
+      const executeListener = (
+        events: Event[],
+        state: State,
+        prevState: State
+      ) => {
+        for (const ev of events) {
+          listener(ev, state, prevState);
+        }
+      };
+
+      /*
+       * only known changes will fire event for lib users
+       * so all the changes in store won't trigger a user-face event
+       */
+      store.subscribe((state, prevState) => {
+        const eventsLike = getEventsLike(state, prevState);
+        const events = tryConsumeEvents(state);
+        const allQueuedEvents = [...events, ...eventsLike];
+        executeListener(allQueuedEvents, state, prevState);
+      });
+
+      return {
+        /**
+         * Manually run pending events.
+         * This useful when use `subscribe` method after sometime and when store initialized.
+         *
+         * Note: Please consider both current and previous state will be same and we don't have access to previous state in a such scenario.
+         */
+        flushEvents: () => {
+          const state = store.getState();
+          const events = tryConsumeEvents(state);
+          executeListener(events, state, state);
+        },
+      };
+    };
+
+  return new Proxy(store, {
+    get: function (target, prop, receiver) {
+      if (prop === 'subscribe') {
+        return extendedSubscribe(target);
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+  }) as unknown as Store;
+}
+
+/**
+ * Retrieves the ConsumableEvent from the store and returns its values.
+ * The values will be consumed by iterating over the field.
+ */
+function tryConsumeEvents(state: State): Event[] {
+  return [...state.providers.events, ...state.namespaces.events];
+}
+
+/**
+ * In certain cases, adding events to the store is not possible (e.g., namespace or provider layer).
+ * In these cases, we observe store changes and treat specific patterns as events when detected.
+ *
+ * Note: This approach should be avoided in most cases. It is used here to maintain backward compatibility
+ * with the provider's legacy interface.
+ */
+function getEventsLike(state: State, prevState: State): Event[] {
+  const events: Event[] = [];
+
+  for (const providerId of Object.keys(state.providers.list)) {
+    const currentProviderState = guessProviderStateSelector(state, providerId);
+    const previousProviderState = guessProviderStateSelector(
+      prevState,
+      providerId
+    );
+
+    if (previousProviderState.connecting !== currentProviderState.connecting) {
+      const ev: ProviderConnectingEvent = {
+        type: 'provider_connecting',
+        provider: providerId,
+        value: currentProviderState.connecting,
+      };
+      events.push(ev);
+    }
+
+    if (!previousProviderState.connected && currentProviderState.connected) {
+      const ev: ProviderConnectedEvent = {
+        type: 'provider_connected',
+        provider: providerId,
+      };
+
+      events.push(ev);
+    }
+
+    if (previousProviderState.connected && !currentProviderState.connected) {
+      const ev: ProviderDisconnectedEvent = {
+        type: 'provider_disconnected',
+        provider: providerId,
+      };
+
+      events.push(ev);
+    }
+  }
+
+  return events;
+}

package/src/hub/store/hub.ts

@@ -0,0 +1,18 @@
+/************ Hub ************/
+
+import type { State } from './mod.js';
+import type { StateCreator } from 'zustand';
+
+type HubConfig = object;
+
+export interface HubStore {
+  config: HubConfig;
+}
+
+type HubStateCreator = StateCreator<State, [], [], HubStore>;
+
+const hubStore: HubStateCreator = () => ({
+  config: {},
+});
+
+export { hubStore };

package/src/hub/store/mod.ts

@@ -0,0 +1,25 @@
+export {
+  guessProviderStateSelector,
+  namespaceStateSelector,
+} from './selectors.js';
+export type { Store } from './extend.js';
+export type { State } from './store.js';
+export type {
+  Event,
+  // Providers
+  ProviderDetectedEvent,
+  ProviderConnectingEvent,
+  ProviderConnectedEvent,
+  ProviderDisconnectedEvent,
+  // Namespaces
+  NamespaceDisconnectedEvent,
+  NamespaceConnectedEvent,
+  NamespaceSwitchedAccountEvent,
+} from './events.js';
+export type {
+  ProviderMetadata,
+  ProviderConfig,
+  ProviderInfo,
+} from './providers.js';
+export type { NamespaceConfig, NamespaceData } from './namespaces.js';
+export { createStore } from './store.js';

package/src/hub/store/namespaces.ts

@@ -0,0 +1,177 @@
+/************ Namespace ************/
+
+import type { StateCreator } from 'zustand';
+
+import { produce } from 'immer';
+
+import {
+  ConsumableEvents,
+  type NamespaceConnectedEvent,
+  type NamespaceDisconnectedEvent,
+  type NamespaceSwitchedAccountEvent,
+  type NamespaceSwitchedNetworkEvent,
+} from './events.js';
+import { namespaceStateSelector, type State } from './mod.js';
+
+// Currently, namespace doesn't has any config.
+export type NamespaceConfig = object;
+
+export interface NamespaceData {
+  accounts: null | string[];
+  network: null | string;
+  connected: boolean;
+  connecting: boolean;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  connectArgs: Record<string, any> | null;
+}
+
+interface NamespaceInfo {
+  providerId: string;
+  namespaceId: string;
+}
+
+interface NamespaceItem {
+  info: NamespaceInfo;
+  data: NamespaceData;
+  error: unknown;
+}
+
+type NamespaceState = {
+  events: InstanceType<typeof ConsumableEvents>;
+  list: Record<string, NamespaceItem>;
+};
+
+interface NamespaceActions {
+  addNamespace: (id: string, config: NamespaceInfo) => void;
+  updateStatus: <K extends keyof NamespaceData>(
+    id: string,
+    key: K,
+    value: NamespaceData[K]
+  ) => void;
+
+  _produceEventsWhenUpdatingStatus: <K extends keyof NamespaceData>(
+    namespace: NamespaceItem,
+    id: string,
+    key: K,
+    value: NamespaceData[K]
+  ) => void;
+}
+interface NamespaceSelectors {
+  getNamespaceData(storeId: string): NamespaceData;
+}
+
+export type NamespaceStore = NamespaceState &
+  NamespaceActions &
+  NamespaceSelectors;
+type NamespaceStateCreator = StateCreator<State, [], [], NamespaceStore>;
+
+const namespacesStore: NamespaceStateCreator = (set, get) => ({
+  events: new ConsumableEvents(),
+
+  list: {},
+  addNamespace: (id, info) => {
+    const data: NamespaceData = {
+      accounts: null,
+      network: null,
+      connected: false,
+      connecting: false,
+      connectArgs: null,
+    };
+
+    const item = {
+      data,
+      error: '',
+      info,
+    };
+
+    set(
+      produce((state: State) => {
+        state.namespaces.list[id] = item;
+      })
+    );
+  },
+  updateStatus: (id, key, value) => {
+    const ns = get().namespaces.list[id];
+    if (!ns) {
+      throw new Error(`No namespace with '${id}' found.`);
+    }
+
+    get().namespaces._produceEventsWhenUpdatingStatus(ns, id, key, value);
+
+    // Updating state
+    set(
+      produce((state: State) => {
+        state.namespaces.list[id].data[key] = value;
+      })
+    );
+  },
+  getNamespaceData(storeId) {
+    return namespaceStateSelector(get(), storeId);
+  },
+
+  _produceEventsWhenUpdatingStatus: (namespace, id, key, value) => {
+    if (key === 'accounts') {
+      // check for both null and empty array
+      const isAccountsEmpty =
+        Object.is(value, null) || (Array.isArray(value) && value.length === 0);
+
+      if (isAccountsEmpty) {
+        const currentConnectedStatus = get().namespaces.list[id].data.connected;
+        if (currentConnectedStatus) {
+          const event: NamespaceDisconnectedEvent = {
+            type: 'namespace_disconnected',
+            provider: namespace.info.providerId,
+            namespace: namespace.info.namespaceId,
+          };
+
+          get().namespaces.events.push(event);
+        }
+        // Skip emitting disconnect event, if the `connected` is false
+      } else {
+        const currentAccounts = get().namespaces.list[id].data.accounts;
+
+        if (!currentAccounts) {
+          const event: NamespaceConnectedEvent = {
+            type: 'namespace_connected',
+            provider: namespace.info.providerId,
+            namespace: namespace.info.namespaceId,
+            accounts: value as string[],
+          };
+
+          get().namespaces.events.push(event);
+        } else {
+          const areSameAccounts =
+            // Clone the object from the Zustand store, as it's immutable, to avoid errors during sorting.
+            [...currentAccounts].sort().toString() ===
+            (value as string[]).sort().toString();
+
+          if (!areSameAccounts) {
+            const event: NamespaceSwitchedAccountEvent = {
+              type: 'namespace_account_switched',
+              provider: namespace.info.providerId,
+              namespace: namespace.info.namespaceId,
+              previousAccounts: currentAccounts,
+              accounts: value as string[],
+            };
+
+            get().namespaces.events.push(event);
+          }
+        }
+      }
+    } else if (key === 'network') {
+      const currentNetwork = get().namespaces.list[id].data.network;
+
+      const event: NamespaceSwitchedNetworkEvent = {
+        type: 'namespace_network_switched',
+        provider: namespace.info.providerId,
+        namespace: namespace.info.namespaceId,
+        network: value as string,
+        previousNetwork: currentNetwork,
+      };
+
+      get().namespaces.events.push(event);
+    }
+  },
+});
+
+export { namespacesStore };

package/src/hub/store/providers.ts

@@ -0,0 +1,169 @@
+import type { Namespace } from '../../namespaces/common/types.js';
+import type { State as InternalProviderState } from '../provider/mod.js';
+import type { BlockchainMeta, SignerFactory } from 'rango-types';
+import type { StateCreator } from 'zustand';
+
+import { produce } from 'immer';
+
+import { ConsumableEvents, type ProviderDetectedEvent } from './events.js';
+import { guessProviderStateSelector, type State } from './mod.js';
+
+type Browsers = 'firefox' | 'chrome' | 'edge' | 'brave' | 'homepage';
+type Property<N extends string, V> = { name: N; value: V };
+
+type NamespacesProperty = Property<
+  'namespaces',
+  {
+    selection: 'single' | 'multiple';
+    data: {
+      label: string;
+      id: string;
+      value: Namespace;
+      unsupported?: boolean;
+      getSupportedChains: (chains: BlockchainMeta[]) => BlockchainMeta[];
+    }[];
+  }
+>;
+type DerivationPathProperty = Property<
+  'derivationPath',
+  {
+    data: {
+      id: string;
+      label: string;
+      namespace: Namespace;
+      generateDerivationPath: (index: string) => string;
+    }[];
+  }
+>;
+type DetailsProperty = Property<
+  'details',
+  {
+    mobileWallet?: boolean;
+    showOnMobile?: boolean;
+    isContractWallet?: boolean;
+  }
+>;
+type SignersProperty = Property<
+  'signers',
+  {
+    getSigners: () => Promise<SignerFactory>;
+  }
+>;
+
+export type ProviderMetadata = {
+  name: string;
+  icon: string;
+  extensions: Partial<Record<Browsers, string>>;
+  properties?: Array<
+    | NamespacesProperty
+    | DerivationPathProperty
+    | DetailsProperty
+    | SignersProperty
+  >;
+};
+
+export interface ProviderConfig {
+  metadata: ProviderMetadata;
+}
+
+export type ProviderInfo = ProviderConfig;
+
+interface ProviderData {
+  installed: boolean;
+}
+
+interface ProviderItem {
+  config: ProviderConfig;
+  data: ProviderData;
+  error: unknown;
+}
+
+type ProviderState = {
+  events: ConsumableEvents;
+  list: Record<string, ProviderItem>;
+};
+interface ProviderActions {
+  addProvider: (id: string, config: ProviderConfig) => void;
+  removeProvider: (id: string) => void;
+  updateStatus: <K extends keyof ProviderData>(
+    id: string,
+    key: K,
+    value: ProviderData[K]
+  ) => void;
+
+  _produceEventsWhenUpdatingStatus: <K extends keyof ProviderData>(
+    provider: ProviderItem,
+    id: string,
+    key: K,
+    value: ProviderData[K]
+  ) => void;
+}
+
+interface ProviderSelectors {
+  /**
+   * Provider has a limited state to itself, to be compatible with legacy, we try to produce same object as legacy
+   * which includes namespace state as well.
+   */
+  guessNamespacesState: (id: string) => InternalProviderState;
+}
+
+export type ProviderStore = ProviderState & ProviderActions & ProviderSelectors;
+type ProvidersStateCreator = StateCreator<State, [], [], ProviderStore>;
+
+const providersStore: ProvidersStateCreator = (set, get) => ({
+  events: new ConsumableEvents(),
+
+  list: {},
+  addProvider: (id, config) => {
+    const item = {
+      data: {
+        installed: false,
+      },
+      error: '',
+      config,
+    };
+
+    set(
+      produce((state: State) => {
+        state.providers.list[id] = item;
+      })
+    );
+  },
+  removeProvider: (id) => {
+    set(
+      produce((state: State) => {
+        delete state.providers.list[id];
+      })
+    );
+  },
+  updateStatus: (id, key, value) => {
+    const provider = get().providers.list[id];
+    if (!provider) {
+      throw new Error(`No namespace namespace with '${id}' found.`);
+    }
+
+    get().providers._produceEventsWhenUpdatingStatus(provider, id, key, value);
+
+    set(
+      produce((state: State) => {
+        state.providers.list[id].data[key] = value;
+      })
+    );
+  },
+  guessNamespacesState: (providerId: string): InternalProviderState => {
+    return guessProviderStateSelector(get(), providerId);
+  },
+
+  _produceEventsWhenUpdatingStatus: (_provider, id, key, _value) => {
+    if (key === 'installed') {
+      const event: ProviderDetectedEvent = {
+        type: 'provider_detected',
+        provider: id,
+      };
+
+      get().providers.events.push(event);
+    }
+  },
+});
+
+export { providersStore };

package/src/hub/store/selectors.ts

@@ -0,0 +1,59 @@
+/**
+ * Note: Zustand has some difficulty when you are trying to `previous` state on `subscribe`.
+ * If these selectors define inside store directly and use `get()` for accessing state, it will get the latest state
+ * instead of previous state which desired.
+ * So make them a helper will let us to reuse them both in store and outside of store in a `subscribe`.
+ */
+import type { State } from '../mod.js';
+import type { State as InternalProviderState } from '../provider/mod.js';
+
+/**
+ * Legacy provider state includes `connecting` and `connected` values. It hadn't a separation layer for `namespaces`.
+ * For compatibility reasons, we should produce these two values somehow.
+ *
+ * Currently, We return `true` if any of namespaces return true. We are missing failed namespace here.
+ * But if we want to solve that, we should migrate our client code to use `namespace` state directly and not from `provider`
+ */
+export function guessProviderStateSelector(
+  state: State,
+  providerId: string
+): InternalProviderState {
+  /*
+   * We keep namespaces in a separate branch than providers.
+   * We should look at all of them and find all the namespaces that for our current proivder.
+   */
+  const allNamespaces = state.namespaces.list;
+  const currentProviderNamespaces = Object.keys(allNamespaces).filter(
+    (key) => allNamespaces[key].info.providerId === providerId
+  );
+
+  // Returning provider state value directly.
+  const installed = !!state.providers.list[providerId]?.data.installed;
+
+  /*
+   * If any namespaces returns `true`, we consider the whole provider for this field to be `true`.
+   * it has a downside regarding errors which explained on top of the function.
+   */
+  const connected =
+    currentProviderNamespaces.length > 0
+      ? currentProviderNamespaces.some(
+          (key) => allNamespaces[key].data.connected
+        )
+      : false;
+  const connecting =
+    currentProviderNamespaces.length > 0
+      ? currentProviderNamespaces.some(
+          (key) => allNamespaces[key].data.connecting
+        )
+      : false;
+
+  return {
+    installed,
+    connected,
+    connecting,
+  };
+}
+
+export function namespaceStateSelector(state: State, storeId: string) {
+  return state.namespaces.list[storeId].data;
+}

package/src/hub/store/store.test.ts

@@ -0,0 +1,50 @@
+import type { Store } from './mod.js';
+
+import { beforeEach, describe, expect, test } from 'vitest';
+
+import { createStore } from './store.js';
+
+describe('checking store', () => {
+  let hubStore: Store;
+
+  beforeEach(() => {
+    hubStore = createStore();
+  });
+
+  test('new providers can be added to store', () => {
+    const id = 'sol-or-something';
+    const info = {
+      metadata: {
+        name: 'sol grabage wallet',
+        icon: 'http://somewhere.world',
+        extensions: {
+          homepage: 'http://somewhere.world',
+        },
+      },
+    };
+
+    const { getState } = hubStore;
+    getState().providers.addProvider(id, info);
+
+    expect(getState().providers.list[id]).toBeDefined();
+    expect(Object.keys(getState().providers.list).length).toBe(1);
+  });
+  test('provider can be removed from store', () => {
+    const id = 'sol-or-something';
+    const metadata = {
+      name: 'sol grabage wallet',
+      icon: 'http://somewhere.world',
+      extensions: {
+        homepage: 'http://somewhere.world',
+      },
+    };
+
+    const { getState } = hubStore;
+    getState().providers.addProvider(id, { metadata });
+    expect(getState().providers.list[id]).toBeDefined();
+    expect(Object.keys(getState().providers.list).length).toBe(1);
+    getState().providers.removeProvider(id);
+    expect(getState().providers.list[id]).toBeUndefined();
+    expect(Object.keys(getState().providers.list).length).toBe(0);
+  });
+});

package/src/hub/store/store.ts

@@ -0,0 +1,30 @@
+import type { StoreApi } from 'zustand/vanilla';
+
+import { createStore as createZustandStore } from 'zustand/vanilla';
+
+import { extend, type Store } from './extend.js';
+import { hubStore, type HubStore } from './hub.js';
+import { namespacesStore, type NamespaceStore } from './namespaces.js';
+import { providersStore, type ProviderStore } from './providers.js';
+
+/************ State ************/
+
+export interface State {
+  hub: HubStore;
+  providers: ProviderStore;
+  namespaces: NamespaceStore;
+}
+
+export type RawStore = StoreApi<State>;
+
+export const createStore = (): Store => {
+  const store = createZustandStore<State>((...api) => {
+    return {
+      hub: hubStore(...api),
+      providers: providersStore(...api),
+      namespaces: namespacesStore(...api),
+    };
+  });
+
+  return extend(store);
+};