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

package/src/namespaces/common/hooks/changeAccountSubscriber.test.ts

@@ -0,0 +1,173 @@
+import type { Actions } from '../../../hub/namespaces/types.js';
+import type { AutoImplementedActionsByRecommended } from '../types.js';
+
+import { waitFor } from '@testing-library/dom';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { createStore, Namespace } from '../../../mod.js';
+
+import { ChangeAccountSubscriberBuilder } from './changeAccountSubscriber.js';
+
+interface TestNamespaceActions {
+  disconnect: () => void;
+}
+
+describe('check changeAccountSubscriber', () => {
+  const garbageProvider = { name: 'garbage provider' };
+
+  const garbageFormatter = async (
+    _instance: typeof garbageProvider,
+    accounts: string[]
+  ) => accounts.map((account) => `Formatted: ${account}`);
+
+  const garbageAddEventListener = (
+    _instance: typeof garbageProvider,
+    callback: (event: string[]) => void
+  ) => {
+    callback(['0']);
+  };
+
+  const garbageRemoveEventListener = (
+    _: typeof garbageProvider,
+    __: (event: string[]) => void
+  ) => {};
+
+  let builder: ChangeAccountSubscriberBuilder<
+    string[],
+    typeof garbageProvider,
+    Actions<AutoImplementedActionsByRecommended>
+  >;
+
+  const setupNamespace = () => {
+    const actions = new Map();
+    const disconnectAction = vi.fn();
+    actions.set('disconnect', disconnectAction);
+
+    const store = createStore();
+    const ns = new Namespace<TestNamespaceActions>('evm', 'garbage provider', {
+      actions,
+      store,
+    });
+
+    const context = { action: ns.run.bind(ns), state: ns.state.bind(ns) };
+
+    return { ns, context, disconnectAction };
+  };
+
+  beforeEach(() => {
+    builder = new ChangeAccountSubscriberBuilder();
+  });
+
+  test('throws error if required operators are not set', () => {
+    expect(() => builder.build()).toThrow(
+      `Required "getInstance" operation has not been set for "changeAccountSubscriber"`
+    );
+
+    builder.getInstance(() => garbageProvider);
+    expect(() => builder.build()).toThrow(
+      `Required "format" operation has not been set for "changeAccountSubscriber"`
+    );
+
+    builder.format(garbageFormatter);
+    expect(() => builder.build()).toThrow(
+      `Required "addEventListener" operation has not been set for "changeAccountSubscriber"`
+    );
+
+    builder.addEventListener(garbageAddEventListener);
+    expect(() => builder.build()).toThrow(
+      `Required "removeEventListener" operation has not been set for "changeAccountSubscriber"`
+    );
+
+    builder.removeEventListener(garbageRemoveEventListener);
+
+    // should not throw now
+    builder.build();
+  });
+
+  test('calls addEventListener and formats accounts correctly', async () => {
+    const { context } = setupNamespace();
+    const spiedAddEventListener = vi.fn(garbageAddEventListener);
+
+    builder
+      .getInstance(() => garbageProvider)
+      .format(garbageFormatter)
+      .addEventListener(spiedAddEventListener)
+      .removeEventListener(garbageRemoveEventListener);
+
+    const [subscriber] = builder.build();
+
+    expect(spiedAddEventListener).toHaveBeenCalledTimes(0);
+    subscriber(context);
+    expect(spiedAddEventListener).toHaveBeenCalledTimes(1);
+
+    const [getState] = context.state();
+    await waitFor(() => {
+      expect(getState('accounts')?.[0]).toBe('Formatted: 0');
+    });
+  });
+
+  test('wont update accounts if preventDefault called', async () => {
+    const { context } = setupNamespace();
+    const spiedAddEventListener = vi.fn(garbageAddEventListener);
+    const [getState, setState] = context.state();
+    setState('accounts', ['Initial State']);
+    builder
+      .getInstance(() => garbageProvider)
+      .format(garbageFormatter)
+      .addEventListener(spiedAddEventListener)
+      .onSwitchAccount((event) => {
+        event.preventDefault();
+      })
+      .removeEventListener(garbageRemoveEventListener);
+
+    const [subscriber] = builder.build();
+
+    subscriber(context);
+    await waitFor(() => {
+      expect(getState('accounts')?.[0]).toBe('Initial State');
+    });
+  });
+
+  test('calls removeEventListener', () => {
+    const { context } = setupNamespace();
+    const spiedRemoveEventListener = vi.fn(garbageRemoveEventListener);
+
+    builder
+      .getInstance(() => garbageProvider)
+      .format(garbageFormatter)
+      .addEventListener(garbageAddEventListener)
+      .removeEventListener(spiedRemoveEventListener);
+
+    const [, clearSubscriber] = builder.build();
+
+    expect(spiedRemoveEventListener).toHaveBeenCalledTimes(0);
+    clearSubscriber(context);
+    expect(spiedRemoveEventListener).toHaveBeenCalledTimes(1);
+  });
+
+  test('calls addEventListener returned function', () => {
+    const { context } = setupNamespace();
+    const unsubscribe = vi.fn();
+
+    const addEventListenerWithReturn = (
+      _: typeof garbageProvider,
+      __: (event: string[]) => void
+    ) => {
+      return unsubscribe;
+    };
+
+    builder
+      .getInstance(() => garbageProvider)
+      .format(garbageFormatter)
+      .addEventListener(addEventListenerWithReturn)
+      .removeEventListener(garbageRemoveEventListener);
+
+    const [subscriber, clearSubscriber] = builder.build();
+
+    subscriber(context);
+    expect(unsubscribe).toHaveBeenCalledTimes(0);
+
+    clearSubscriber(context);
+    expect(unsubscribe).toHaveBeenCalledTimes(1);
+  });
+});

package/src/namespaces/common/hooks/changeAccountSubscriber.ts

@@ -0,0 +1,236 @@
+import type {
+  Actions,
+  Context,
+  SubscriberCleanUp,
+} from '../../../hub/namespaces/types.js';
+import type { Subscriber } from '../../../mod.js';
+import type { AutoImplementedActionsByRecommended } from '../types.js';
+
+type OnSwitchAccountEvent<EventType> = {
+  payload: EventType;
+  preventDefault: () => void;
+};
+
+export class ChangeAccountSubscriberBuilder<
+  EventType,
+  ProviderAPI,
+  ActionsType extends Actions<ActionsType> &
+    Actions<AutoImplementedActionsByRecommended>
+> {
+  #getInstance: (() => ProviderAPI) | null = null;
+  #format:
+    | ((instance: ProviderAPI, event: EventType) => Promise<string[]>)
+    | null = null;
+  #onSwitchAccount:
+    | ((
+        event: OnSwitchAccountEvent<EventType>,
+        context: Context<ActionsType>
+      ) => void)
+    | null = null;
+
+  #addEventListener:
+    | ((
+        instance: ProviderAPI,
+        callback: (event: EventType) => void
+      ) => (() => void) | void)
+    | null = null;
+  #removeEventListener:
+    | ((instance: ProviderAPI, callback: (event: EventType) => void) => void)
+    | null = null;
+
+  /**
+   * Sets the function that provides the provider API instance.
+   *
+   * @param operator - Function that returns the provider API instance
+   * @returns The builder instance for method chaining
+   * @example
+   * ```typescript
+   * builder.getInstance(() => window.ethereum)
+   * ```
+   */
+  public getInstance(operator: () => ProviderAPI) {
+    this.#getInstance = operator;
+    return this;
+  }
+
+  /**
+   * Sets the formatter function that converts provider events to account strings.
+   *
+   * @param operator - Function that takes a provider instance and event, returns array of account strings
+   * @returns The builder instance for method chaining
+   * @example
+   * ```typescript
+   * builder.format(async (instance, event) => event.accounts || [])
+   * ```
+   */
+  public format(
+    operator: (instance: ProviderAPI, event: EventType) => Promise<string[]>
+  ) {
+    this.#format = operator;
+    return this;
+  }
+
+  /**
+   * Set a handler that runs whenever a **switch-account** event occurs.
+   *
+   * The provided operator is called with:
+   * - `event`: An object containing:
+   *    - `payload`: The event payload associated with the account switch.
+   *    - `preventDefault`: A function that prevents the default switch-account
+   *       behavior (e.g., updating the active accounts list).
+   * - `context`: The execution context of the current flow or action.
+   *
+   * Calling `event.preventDefault()` inside the handler cancels the built-in
+   * account switching logic.
+   *
+   * @param operator - A function invoked on each switch-account event.
+   *   It receives `(event, context)` and can call `event.preventDefault()` to
+   *   stop the default behavior.
+   *
+   * @returns The builder instance for method chaining.
+   *
+   * @example
+   * ```ts
+   * builder.onSwitchAccount((event, context) => {
+   *   if (!event.payload.userConfirmed) {
+   *     event.preventDefault(); // cancel default account switch
+   *   }
+   *
+   *   console.log("Switching account:", event.payload.accountId);
+   * });
+   * ```
+   */
+  public onSwitchAccount(
+    operator: (
+      event: OnSwitchAccountEvent<EventType>,
+      context: Context<ActionsType>
+    ) => void
+  ) {
+    this.#onSwitchAccount = operator;
+    return this;
+  }
+
+  /**
+   * Sets the event listener attachment function.
+   *
+   * @param operator - Function that attaches an event listener and optionally returns a cleanup function
+   * @returns The builder instance for method chaining
+   * @example
+   * ```typescript
+   * builder.addEventListener((instance, callback) => {
+   *   return instance.on('accountsChanged', callback);
+   * })
+   * ```
+   */
+  public addEventListener(
+    operator: (
+      instance: ProviderAPI,
+      callback: (event: EventType) => void
+    ) => (() => void) | void
+  ) {
+    this.#addEventListener = operator;
+    return this;
+  }
+
+  /**
+   * Sets the event listener removal function.
+   *
+   * @param operator - Function that removes an event listener from the provider
+   * @returns The builder instance for method chaining
+   * @example
+   * ```typescript
+   * builder.removeEventListener((instance, callback) => instance.off('accountsChanged', callback))
+   * ```
+   */
+  public removeEventListener(
+    operator: (
+      instance: ProviderAPI,
+      callback: (event: EventType) => void
+    ) => void
+  ) {
+    this.#removeEventListener = operator;
+    return this;
+  }
+  public build(): [Subscriber<ActionsType>, SubscriberCleanUp<ActionsType>] {
+    if (this.#getInstance === null) {
+      throw new Error(this.#getErrorMessage('getInstance'));
+    }
+    if (this.#format === null) {
+      throw new Error(this.#getErrorMessage('format'));
+    }
+    if (this.#addEventListener === null) {
+      throw new Error(this.#getErrorMessage('addEventListener'));
+    }
+    if (this.#removeEventListener === null) {
+      throw new Error(this.#getErrorMessage('removeEventListener'));
+    }
+
+    /**
+     * Capture current operator state at build time to ensure immutability.
+     *
+     * This creates a snapshot of all operators, preventing the built subscriber
+     * from being affected by subsequent changes to the builder instance.
+     * Each call to build() gets its own isolated set of operators, allowing
+     * the builder to be reused for creating multiple independent subscribers.
+     */
+    const getInstance = this.#getInstance;
+    const format = this.#format;
+    const addEventListener = this.#addEventListener;
+    const removeEventListener = this.#removeEventListener;
+    const onSwitchAccount = this.#onSwitchAccount;
+
+    let subscriber: (event: EventType) => void;
+    let unsubscribe: (() => void) | void;
+    return [
+      async (context) => {
+        const [, setState] = context.state();
+        const instance = getInstance();
+
+        if (!instance) {
+          throw new Error(
+            'Trying to subscribe to your wallet, but seems its instance is not available.'
+          );
+        }
+        subscriber = async (event) => {
+          let shouldProceedWithDefault = true;
+          onSwitchAccount?.(
+            {
+              payload: event,
+              preventDefault: () => {
+                shouldProceedWithDefault = false;
+              },
+            },
+            context
+          );
+          if (!shouldProceedWithDefault) {
+            return;
+          }
+          setState('accounts', await format(instance, event));
+        };
+        unsubscribe = addEventListener(instance, subscriber);
+      },
+      (_, err) => {
+        /**
+         * Call the cleanup function if addEventListener returned one.
+         * This handles providers that return an unsubscribe function from their event listeners.
+         */
+        if (unsubscribe && typeof unsubscribe === 'function') {
+          unsubscribe();
+        }
+        const instance = getInstance();
+
+        /**
+         * Always call removeEventListener as well to handle the on/off pattern.
+         * This ensures cleanup works regardless of which pattern the provider uses.
+         */
+        removeEventListener(instance, subscriber);
+
+        // subscriber can be passed to `or`, it will get the error and should rethrow error to pass the error to next `or` or throw error.
+        return err;
+      },
+    ];
+  }
+  #getErrorMessage(operatorName: string) {
+    return `Required "${operatorName}" operation has not been set for "changeAccountSubscriber"`;
+  }
+}

package/src/namespaces/common/mod.ts

@@ -0,0 +1,23 @@
+export * as actions from './actions.js';
+export * as builders from './builders.js';
+export { standardizeAndThrowError } from './or.js';
+export { parseErrorAndThrowStandardizeError } from './utils.js';
+export {
+  intoConnectionFinished,
+  recommended as afterRecommended,
+} from './after.js';
+export { ChangeAccountSubscriberBuilder } from './hooks/changeAccountSubscriber.js';
+export {
+  connectAndUpdateStateForMultiNetworks,
+  connectAndUpdateStateForSingleNetwork,
+  recommended as andRecommended,
+} from './and.js';
+export { intoConnecting, recommended as beforeRecommended } from './before.js';
+
+export type {
+  CaipAccount,
+  Accounts,
+  AccountsWithActiveChain,
+} from '../../types/accounts.js';
+
+export type { Namespace } from './types.js';

package/src/namespaces/common/or.ts

@@ -0,0 +1,17 @@
+import type { Context } from '../../hub/namespaces/mod.js';
+
+import { parseErrorAndThrowStandardizeError } from './utils.js';
+
+/**
+ * Standardizes an unknown error into an Error object and throws it.
+ * If the input is already an Error, it's thrown directly.
+ * Otherwise, a new Error is created with the input's message or string representation.
+ * Note: The parseErrorAndThrowStandardizeError function is defined as a separate function, so that it can be used independently.
+ *
+ * @param _context - The context.
+ * @param e - The unknown error object.
+ * @throws {Error} - The standardized Error object.
+ */
+export function standardizeAndThrowError(_context: Context, e: unknown): never {
+  parseErrorAndThrowStandardizeError(e);
+}

package/src/namespaces/common/types.ts

@@ -0,0 +1,25 @@
+/*
+ * These are supported namespaces in Rango that we want to officially support.
+ * This should be private and don't make it public since core can support more namespaces and should be extendable.
+ */
+type RangoNamespace =
+  | 'EVM'
+  | 'Solana'
+  | 'Cosmos'
+  | 'UTXO'
+  | 'Starknet'
+  | 'Tron'
+  | 'Ton'
+  | 'Sui';
+
+export type Namespace = RangoNamespace | (string & {});
+
+export interface CommonActions {
+  init: () => void;
+}
+
+export interface AutoImplementedActionsByRecommended {
+  disconnect: () => void;
+}
+
+export type Provider = Map<string, unknown>;

package/src/namespaces/common/utils.ts

@@ -0,0 +1,43 @@
+/**
+ * Standardizes an unknown error into an Error object and throws it.
+ * If the input is already an Error, it's thrown directly.
+ * Otherwise, a new Error is created with the input's message or string representation.
+ *
+ * @param e - The unknown error object.
+ * @throws {Error} - The standardized Error object.
+ */
+export function parseErrorAndThrowStandardizeError(e: unknown): never {
+  if (e instanceof Error) {
+    throw e;
+  }
+
+  let errorMessage: string;
+  if (
+    typeof e === 'object' &&
+    e !== null &&
+    'message' in e &&
+    typeof e.message === 'string'
+  ) {
+    errorMessage = e.message;
+  } else if (typeof e === 'string') {
+    errorMessage = e;
+  } else {
+    errorMessage = String(e);
+  }
+
+  const err = new Error(errorMessage) as Error & {
+    code?: unknown;
+    data?: unknown;
+  };
+
+  if (typeof e === 'object' && e !== null) {
+    if ('code' in e) {
+      err.code = e.code;
+    }
+    if ('data' in e) {
+      err.data = e.data;
+    }
+  }
+
+  throw err;
+}

package/src/namespaces/cosmos/actions.ts

@@ -0,0 +1,3 @@
+import { recommended as commonRecommended } from '../common/actions.js';
+
+export const recommended = [...commonRecommended];

package/src/namespaces/cosmos/after.ts

@@ -0,0 +1,3 @@
+import { recommended as commonRecommended } from '../common/after.js';
+
+export const recommended = [...commonRecommended];

package/src/namespaces/cosmos/and.ts

@@ -0,0 +1,5 @@
+import { connectAndUpdateStateForMultiNetworks } from '../common/mod.js';
+
+export const recommended = [
+  ['connect', connectAndUpdateStateForMultiNetworks] as const,
+];

package/src/namespaces/cosmos/before.ts

@@ -0,0 +1,3 @@
+import { beforeRecommended } from '../common/mod.js';
+
+export const recommended = [...beforeRecommended];

package/src/namespaces/cosmos/builders.ts

@@ -0,0 +1,15 @@
+import type { CosmosActions } from './types.js';
+
+import { ActionBuilder } from '../../mod.js';
+import {
+  connectAndUpdateStateForSingleNetwork,
+  intoConnecting,
+  intoConnectionFinished,
+} from '../common/mod.js';
+
+// Actions
+export const connect = () =>
+  new ActionBuilder<CosmosActions, 'connect'>('connect')
+    .and(connectAndUpdateStateForSingleNetwork)
+    .before(intoConnecting)
+    .after(intoConnectionFinished);

package/src/namespaces/cosmos/constants.ts

@@ -0,0 +1 @@
+export const CAIP_NAMESPACE = 'cosmos';

package/src/namespaces/cosmos/mod.ts

@@ -0,0 +1,9 @@
+export type { CosmosActions, ProviderAPI } from './types.js';
+export * as actions from './actions.js';
+export * as after from './after.js';
+export * as and from './and.js';
+export * as before from './before.js';
+export * as utils from './utils.js';
+export * as builders from './builders.js';
+
+export { CAIP_NAMESPACE } from './constants.js';

package/src/namespaces/cosmos/types.ts

@@ -0,0 +1,26 @@
+import type { Accounts } from '../common/mod.js';
+import type {
+  AutoImplementedActionsByRecommended,
+  CommonActions,
+} from '../common/types.js';
+
+export interface CosmosActions
+  extends AutoImplementedActionsByRecommended,
+    CommonActions {
+  connect: (options?: ConnectOptions) => Promise<Accounts>;
+  canEagerConnect: () => Promise<boolean>;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ProviderAPI = Record<string, any>;
+export type CosmosChainAccounts = {
+  accounts: string[];
+  chainId: string;
+};
+
+export type ConnectOptions = {
+  chainIds: string[];
+  /**
+   * For chains that may not be natively supported by the provider.
+   */
+  customChainIds?: string[];
+};

package/src/namespaces/cosmos/utils.ts

@@ -0,0 +1,21 @@
+import type { CosmosChainAccounts } from './types.js';
+import type { CaipAccount } from '../common/mod.js';
+
+import { AccountId } from 'caip';
+
+import { CAIP_NAMESPACE } from './constants.js';
+
+export function formatAccountsToCAIP(accounts: CosmosChainAccounts[]) {
+  return accounts.flatMap((networkAccounts) =>
+    networkAccounts.accounts.map(
+      (networkAccount) =>
+        AccountId.format({
+          address: networkAccount,
+          chainId: {
+            namespace: CAIP_NAMESPACE,
+            reference: networkAccounts.chainId,
+          },
+        }) as CaipAccount
+    )
+  );
+}