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

package/src/hub/provider/provider.test.ts

@@ -0,0 +1,232 @@
+import type { EvmActions } from '../../namespaces/evm/types.js';
+import type { SolanaActions } from '../../namespaces/solana/types.js';
+import type { Store } from '../store/mod.js';
+
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { NamespaceBuilder } from '../../builders/namespace.js';
+import { ProviderBuilder } from '../../builders/provider.js';
+import {
+  garbageWalletInfo,
+  garbageWalletMetaData,
+} from '../../test-utils/fixtures.js';
+import { createStore } from '../store/mod.js';
+
+import { Provider } from './provider.js';
+
+describe('check providers', () => {
+  let namespaces: {
+    evm: NamespaceBuilder<EvmActions>;
+    solana: NamespaceBuilder<SolanaActions>;
+  };
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let namespacesMap: Map<any, any>;
+  let store: Store;
+
+  beforeEach(() => {
+    store = createStore();
+    const evmNamespace = new NamespaceBuilder<EvmActions>('eip155', 'garbage');
+    const solanaNamespace = new NamespaceBuilder<SolanaActions>(
+      'solana',
+      'garbage'
+    );
+
+    namespaces = {
+      evm: evmNamespace,
+      solana: solanaNamespace,
+    };
+
+    namespacesMap = new Map();
+    namespacesMap.set('evm', evmNamespace.build());
+    namespacesMap.set('solana', solanaNamespace.build());
+
+    return () => {
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore-next-line
+      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+      (store = undefined), (namespaces = undefined);
+    };
+  });
+
+  test('Initialize providers correctly', () => {
+    const provider = new Provider('garbage', namespacesMap, garbageWalletInfo);
+
+    const allNamespaces = provider.getAll();
+
+    expect(allNamespaces.size).toBe(2);
+  });
+
+  test('throw error if state() is called before store initialization', () => {
+    const provider = new Provider('garbage', namespacesMap, garbageWalletInfo);
+
+    expect(() => provider.state()).toThrowError();
+  });
+
+  test('should return wallet info via info() without store initialization', () => {
+    const provider = new Provider('garbage', namespacesMap, garbageWalletInfo);
+
+    expect(provider.info()).toBe(garbageWalletInfo);
+  });
+
+  test('should return wallet info via info() after store initialization', () => {
+    const store = createStore();
+    const provider = new Provider('garbage', namespacesMap, garbageWalletInfo, {
+      store,
+    });
+
+    expect(provider.info()).toMatchObject(
+      store.getState().providers.list['garbage'].config
+    );
+  });
+
+  test('access state correctly', () => {
+    const provider = new Provider('garbage', namespacesMap, garbageWalletInfo, {
+      store: createStore(),
+    });
+
+    const [getState, setState] = provider.state();
+
+    expect(getState().connected).toBe(false);
+    expect(getState('connected')).toBe(false);
+    expect(() => {
+      // @ts-expect-error intentionally using an state that doesn't exist.
+      getState('not_exist_state');
+    }).toThrowError();
+    expect(() => {
+      // @ts-expect-error intentionally using an state that doesn't exist and try to update.
+      setState('another_not_exist_state');
+    }).toThrowError();
+  });
+  test('update state properly', () => {
+    const store = createStore();
+    const provider = new Provider('garbage', namespacesMap, garbageWalletInfo, {
+      store,
+    });
+
+    const [getState, setState] = provider.state();
+
+    provider.store(store);
+    setState('installed', true);
+    const isInstalled = getState('installed');
+    expect(isInstalled).toBe(true);
+  });
+
+  test('run namespace actions from provider', async () => {
+    const { evm, solana } = namespaces;
+    solana.action('connect', async () => [
+      'solana:mainnet:0x000000000000000000000000000000000000dead',
+    ]);
+    const testNamespaces = new Map();
+    testNamespaces.set('evm', evm.build());
+    testNamespaces.set('solana', solana.build());
+
+    const provider = new Provider('garbage', testNamespaces, garbageWalletInfo);
+
+    const result = await provider.get('solana')?.connect();
+
+    expect(result).toStrictEqual([
+      'solana:mainnet:0x000000000000000000000000000000000000dead',
+    ]);
+    // Since we didn't add any action regarding connect for `evm`
+    await expect(async () =>
+      provider.get('evm')?.connect('0x1')
+    ).rejects.toThrowError();
+  });
+
+  test('sets config properly', () => {
+    const builder = new ProviderBuilder('garbage');
+    builder.config('metadata', garbageWalletMetaData);
+    const provider = builder.build().store(store);
+
+    expect(provider.info()?.metadata).toStrictEqual(garbageWalletMetaData);
+  });
+
+  test('.init should works on Provider', () => {
+    const builder = new ProviderBuilder('garbage').config(
+      'metadata',
+      garbageWalletMetaData
+    );
+    let count = 0;
+    builder.init(() => {
+      count++;
+    });
+    const provider = builder.build().store(store);
+    expect(count).toBe(0);
+    provider.init();
+    provider.init();
+    provider.init();
+    expect(count).toBe(1);
+  });
+
+  test(".init shouldn't do anything when use hasn't set anything", () => {
+    const builder = new ProviderBuilder('garbage').config(
+      'metadata',
+      garbageWalletMetaData
+    );
+    const provider = builder.build().store(store);
+    expect(() => {
+      provider.init();
+      provider.init();
+      provider.init();
+    }).not.toThrow();
+  });
+
+  test('A provider can be found using its namespace', () => {
+    const builder = new ProviderBuilder('garbage', { store }).config(
+      'metadata',
+      garbageWalletMetaData
+    );
+
+    const { evm, solana } = namespaces;
+    builder.add('evm', evm.build()).add('solana', solana.build());
+    const provider = builder.build();
+
+    const result = provider.findByNamespace('solana');
+    expect(result).toBeDefined();
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore-next-line
+    expect(result?.namespaceId).toBe('solana');
+
+    const result2 = provider.findByNamespace('evm');
+    expect(result2).toBeUndefined();
+  });
+
+  test('`before/after` is calling with correct context ', () => {
+    const connect = vi.fn();
+    const before = vi.fn(function (context) {
+      const [, setState] = context.state();
+      setState('installed', true);
+    });
+    const after = vi.fn(function (context) {
+      const [, setState] = context.state();
+      setState('installed', false);
+    });
+
+    const { evm } = namespaces;
+    const evmNamespace = evm.action('connect', connect).build();
+
+    const builder = new ProviderBuilder('garbage', { store })
+      .add('evm', evmNamespace)
+      .config('metadata', garbageWalletMetaData);
+    const provider = builder.build();
+
+    const [getState] = provider.state();
+    const result = provider.get('evm');
+
+    // Adding `after` then make it will run
+    provider.before('connect', before);
+    void result?.connect('whatever');
+
+    expect(connect).toBeCalledTimes(1);
+    expect(before).toBeCalledTimes(1);
+    expect(getState('installed')).toBe(true);
+
+    // Adding `after` then make it will run
+    provider.after('connect', after);
+    void result?.connect('whatever');
+    expect(connect).toBeCalledTimes(2);
+    expect(after).toBeCalledTimes(1);
+
+    expect(getState('installed')).toBe(false);
+  });
+});

package/src/hub/provider/provider.ts

@@ -0,0 +1,335 @@
+import type {
+  CommonNamespaces,
+  Context,
+  ExtendableInternalActions,
+  GetState,
+  RegisteredNamespaces,
+  SetState,
+  State,
+} from './types.js';
+import type { FindProxiedNamespace } from '../../builders/mod.js';
+import type { AnyFunction, FunctionWithContext } from '../../types/actions.js';
+import type { ProviderConfig, ProviderInfo, Store } from '../store/mod.js';
+
+const VERSION = '1.0';
+
+export class Provider {
+  public readonly id: string;
+  public readonly version = VERSION;
+
+  #namespaces: RegisteredNamespaces<keyof CommonNamespaces, CommonNamespaces>;
+  #initiated = false;
+  #extendInternalActions: ExtendableInternalActions = {};
+  #store: Store | undefined;
+  #configs: ProviderConfig;
+
+  constructor(
+    id: string,
+    namespaces: RegisteredNamespaces<keyof CommonNamespaces, CommonNamespaces>,
+    configs: ProviderConfig,
+    options?: {
+      /**
+       * There are some cases we need to have a behavior like initializing a provider which will be run when we are creating an instance.
+       * These internal steps and behaviors will be useful for library user to extend the behavior by running a specific code.
+       */
+      extendInternalActions?: ExtendableInternalActions;
+      store?: Store;
+    }
+  ) {
+    this.id = id;
+    this.#configs = configs;
+    // it should be only created here, to make sure `after/before` will work properly.
+    this.#extendInternalActions = options?.extendInternalActions || {};
+    this.#namespaces = namespaces;
+
+    /**
+     * Our assumption is that the store will be optional for the provider.
+     * If a store is provided in the options, it will be initialized and set up.
+     */
+    if (options?.store) {
+      this.#store = options.store;
+      this.#setupStore();
+    }
+  }
+
+  /**
+   * This is an special callback that will be called **only once**.
+   * We don't call this in `constructor` and developer should call this manually. we only ensure it will be called once.
+   *
+   * ```ts
+   * const myInit = () => {  whatever; }   *
+   * const provider = new Provider(..., {extendInternalActions: {init: myInit} });
+   *
+   * // Will run `myInit`
+   * provider.init()
+   *
+   * // Will not run `myInit` anymore.
+   * provider.init()
+   * provider.init()
+   * ```
+   */
+  public init(): void {
+    if (this.#initiated) {
+      return;
+    }
+
+    const definedInitByUser = this.#extendInternalActions.init;
+    if (definedInitByUser) {
+      definedInitByUser(this.#context());
+    }
+
+    this.#initiated = true;
+  }
+
+  /**
+   * Getting state of a provider
+   *
+   * **Note:**
+   *    Each namespace has it's own state as well, in Legacy we didn't have this separation and all of them was accessible through Provider itself
+   *    To be compatible with legacy, `getState` has a logic to guess the final state to produce same state as legacy.
+   *
+   * @example
+   * ```ts
+   * const provider = new Provider(...);
+   * const [getState, setState] = provider.state();
+   *
+   * getState('installed');
+   * // or
+   * getState().installed;
+   * ```
+   *
+   */
+  public state(): [GetState, SetState] {
+    const store = this.#store;
+    if (!store) {
+      throw new Error(
+        `Any store detected for ${this.id}. You need to set your store using '.store' method first.`
+      );
+    }
+
+    /**
+     * State updater
+     */
+    const setState: SetState = (name, value) => {
+      switch (name) {
+        case 'installed':
+          return store.getState().providers.updateStatus(this.id, name, value);
+        default:
+          throw new Error(
+            `Unhandled state update for provider. (provider id: ${this.id}, state name: ${name})`
+          );
+      }
+    };
+
+    /**
+     * State getter
+     */
+    const getState: GetState = <K extends keyof State>(name?: K) => {
+      const state: State = store
+        .getState()
+        .providers.guessNamespacesState(this.id);
+
+      if (!name) {
+        return state;
+      }
+
+      switch (name) {
+        case 'installed':
+        case 'connected':
+        case 'connecting':
+          return state[name];
+        default:
+          throw new Error('Unhandled state for provider');
+      }
+    };
+
+    return [getState, setState];
+  }
+
+  /**
+   * For keeping state, we need a store. all the states will be write to/read from store.
+   *
+   * **Note: When you are setting an store for provider, it will be set for its namespaces automatically as well**
+   *
+   * @example
+   * ```ts
+   * const myStore = createStore();
+   * const provider = new Provider(...);
+   * provider.store(myStore); // or it can be passed to Provider constructor;
+   * ```
+   */
+  public store(store: Store): this {
+    if (this.#store) {
+      console.warn(
+        "You've already set an store for your Provider. Old store will be replaced by the new one."
+      );
+    }
+    this.#store = store;
+    this.#setupStore();
+    return this;
+  }
+
+  /**
+   * Getting information about a provider which has been set on constructing Provider.
+   *
+   * @example
+   * ```ts
+   * const walletInfo = {name: "Garbage wallet", ...}
+   * const provider = new Provider(..., {info: walletInfo});
+   *
+   * provider.info();
+   * ```
+   */
+  public info(): ProviderInfo | undefined {
+    const store = this.#store;
+    if (!store) {
+      return this.#configs;
+    }
+    const config = store.getState().providers.list[this.id].config;
+
+    return { metadata: config.metadata };
+  }
+
+  /**
+   * A list of registered _proxied_ namespaces.
+   *
+   * @example
+   * ```ts
+   *  const provider = new Provider(...);
+   *  const allNamespaces = provider.getAll();
+   * ```
+   */
+  public getAll(): RegisteredNamespaces<
+    keyof CommonNamespaces,
+    CommonNamespaces
+  > {
+    return this.#namespaces;
+  }
+
+  /**
+   * Get a registered namespace in provider by its **namespace key**.
+   *
+   * Note: difference between namespace key and namespace id is the first one is setting from a predefined list the second one can be anything and will be chosen by library's user.
+   *
+   * @param {string} id - evm, solana, cosmos, ... (CommonActions)
+   */
+  public get<K extends keyof CommonNamespaces>(
+    id: K
+  ): FindProxiedNamespace<K, CommonNamespaces> | undefined {
+    return this.#namespaces.get(id) as unknown as
+      | FindProxiedNamespace<K, CommonNamespaces>
+      | undefined;
+  }
+
+  /**
+   *
+   * Get a registered namespace by its **namespaceId**.
+   *
+   * Note: difference between namespace key and namespace id is the first one is setting from a predefined list the second one can be anything and will be chosen by library's user.
+   *
+   * @example
+   * ```ts
+   * const provider = new Provider(...);
+   * provider.findByNamespace("whatever-id-i-set-for-namespace")
+   * ```
+   */
+  public findByNamespace<K extends keyof CommonNamespaces>(
+    namespaceLookingFor: K | string
+  ): FindProxiedNamespace<K, CommonNamespaces> | undefined {
+    // If we didn't found any match, we will return `undefined`.
+    let result: object | undefined = undefined;
+
+    this.#namespaces.forEach((namespace) => {
+      if (namespace.namespaceId === namespaceLookingFor) {
+        result = namespace;
+      }
+    });
+
+    return result;
+  }
+
+  /**
+   * Running a hook function _after_ a specific action for **all registered namespaces**.
+   *
+   * **Note:** the context can be set from outside as well. this is useful for Provider to set its context instead of namespace context.
+   *
+   * @example
+   * ```ts
+   *  const provider = new Provider(...);
+   *
+   *  provider.after("connect", (context) => {});
+   * ```
+   */
+  public before(
+    actionName: string,
+    hookFn: FunctionWithContext<AnyFunction, Context>
+  ): this {
+    this.#addHook('before', actionName, hookFn);
+    return this;
+  }
+
+  /**
+   * Running a hook function _before_ a specific action for **all registered namespaces**.
+   *
+   * **Note:** the context can be set from outside as well. this is useful for Provider to set its context instead of namespace context.
+   *
+   * @example
+   * ```ts
+   *  const provider = new Provider(...);
+   *
+   *  provider.after("connect", (context) => {});
+   * ```
+   */
+  public after(
+    actionName: string,
+    hookFn: FunctionWithContext<AnyFunction, Context>
+  ): this {
+    this.#addHook('after', actionName, hookFn);
+    return this;
+  }
+
+  #addHook(
+    hookName: 'after' | 'before',
+    actionName: string,
+    cb: FunctionWithContext<AnyFunction, Context>
+  ): this {
+    const context = {
+      state: this.state.bind(this),
+    };
+
+    this.#namespaces.forEach((namespace) => {
+      if (hookName === 'after') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        namespace.after(actionName as any, cb, {
+          context,
+        });
+      } else if (hookName === 'before') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        namespace.before(actionName as any, cb, {
+          context,
+        });
+      } else {
+        throw new Error(`You hook name is invalid: ${hookName}`);
+      }
+    });
+
+    return this;
+  }
+
+  #setupStore(): void {
+    const store = this.#store;
+    if (!store) {
+      throw new Error('For setup store, you should set `store` first.');
+    }
+    store.getState().providers.addProvider(this.id, this.#configs);
+    this.#namespaces.forEach((provider) => {
+      provider.store(store);
+    });
+  }
+
+  #context(): Context {
+    return {
+      state: this.state.bind(this),
+    };
+  }
+}

package/src/hub/provider/types.ts

@@ -0,0 +1,50 @@
+import type { FindProxiedNamespace } from '../../builders/mod.js';
+import type { Store } from '../../hub/mod.js';
+import type { LegacyState } from '../../legacy/mod.js';
+import type { CosmosActions } from '../../namespaces/cosmos/mod.js';
+import type { EvmActions } from '../../namespaces/evm/mod.js';
+import type { SolanaActions } from '../../namespaces/solana/mod.js';
+import type { SuiActions } from '../../namespaces/sui/mod.js';
+import type { TronActions } from '../../namespaces/tron/types.js';
+import type { UtxoActions } from '../../namespaces/utxo/mod.js';
+import type { AnyFunction, FunctionWithContext } from '../../types/actions.js';
+import type { Prettify } from '../../types/utils.js';
+
+export type Context = {
+  state: () => [GetState, SetState];
+};
+
+export type State = Omit<
+  LegacyState,
+  'reachable' | 'accounts' | 'network' | 'derivationPath'
+>;
+export type SetState = <K extends keyof Pick<State, 'installed'>>(
+  name: K,
+  value: State[K]
+) => void;
+export type GetState = {
+  (): State;
+  <K extends keyof State>(name: K): State[K];
+};
+
+export interface CommonNamespaces {
+  evm: EvmActions;
+  solana: SolanaActions;
+  cosmos: CosmosActions;
+  sui: SuiActions;
+  utxo: UtxoActions;
+  tron: TronActions;
+}
+
+export type CommonNamespaceKeys = Prettify<keyof CommonNamespaces>;
+
+export interface ExtendableInternalActions {
+  init?: FunctionWithContext<AnyFunction, Context>;
+}
+
+export type RegisteredNamespaces<K extends keyof T, T> = Map<
+  K,
+  FindProxiedNamespace<K, T>
+>;
+
+export type ProviderBuilderOptions = { store?: Store };

package/src/hub/store/events.ts

@@ -0,0 +1,89 @@
+export type NamespaceDisconnectedEvent = {
+  type: 'namespace_disconnected';
+  provider: string;
+  namespace: string;
+};
+
+export type NamespaceConnectedEvent = {
+  type: 'namespace_connected';
+  provider: string;
+  namespace: string;
+  accounts: string[];
+};
+
+export type NamespaceSwitchedAccountEvent = {
+  type: 'namespace_account_switched';
+  provider: string;
+  namespace: string;
+  accounts: string[];
+  previousAccounts: string[];
+};
+
+export type NamespaceSwitchedNetworkEvent = {
+  type: 'namespace_network_switched';
+  provider: string;
+  namespace: string;
+  network: string;
+  previousNetwork: string | null;
+};
+
+export type ProviderDetectedEvent = {
+  type: 'provider_detected';
+  provider: string;
+};
+
+export type ProviderConnectingEvent = {
+  type: 'provider_connecting';
+  provider: string;
+  value: boolean;
+};
+
+export type ProviderConnectedEvent = {
+  type: 'provider_connected';
+  provider: string;
+};
+
+export type ProviderDisconnectedEvent = {
+  type: 'provider_disconnected';
+  provider: string;
+};
+
+export type Event =
+  | NamespaceDisconnectedEvent
+  | NamespaceConnectedEvent
+  | NamespaceSwitchedAccountEvent
+  | NamespaceSwitchedNetworkEvent
+  | ProviderDetectedEvent
+  | ProviderConnectingEvent
+  | ProviderConnectedEvent
+  | ProviderDisconnectedEvent;
+
+/**
+ *
+ * Keeping an array of Event and when iterates over its values, it will be removed (consume) from the array.
+ *
+ */
+export class ConsumableEvents {
+  #data: Event[] = [];
+
+  push(val: Event) {
+    this.#data.push(val);
+  }
+
+  [Symbol.iterator](): Iterator<Event> {
+    return {
+      next: (): IteratorResult<Event> => {
+        if (this.#data.length == 0) {
+          return { done: true, value: undefined };
+        }
+
+        // Typescript can not narrow the type, but we have a runtime check to ensure it will never be an empty list
+        const value = this.#data.shift()!;
+        return {
+          done: false,
+          value,
+        };
+      },
+    };
+  }
+}