refactor: split api.ts

src/api/balance.test-d.ts

@@ -0,0 +1,19 @@
+import { expectAssignable, expectNotAssignable } from 'tsd';
+
+import type { Balance } from './balance';
+
+expectAssignable<Balance>({ amount: '1.0', unit: 'ETH' });
+expectAssignable<Balance>({ amount: '0.1', unit: 'BTC' });
+expectAssignable<Balance>({ amount: '.1', unit: 'gwei' });
+expectAssignable<Balance>({ amount: '.1', unit: 'wei' });
+expectAssignable<Balance>({ amount: '1.', unit: 'sat' });
+
+expectNotAssignable<Balance>({ amount: 1, unit: 'ETH' });
+expectNotAssignable<Balance>({ amount: true, unit: 'ETH' });
+expectNotAssignable<Balance>({ amount: undefined, unit: 'ETH' });
+expectNotAssignable<Balance>({ amount: null, unit: 'ETH' });
+
+expectNotAssignable<Balance>({ amount: '1.0', unit: 1 });
+expectNotAssignable<Balance>({ amount: '1.0', unit: true });
+expectNotAssignable<Balance>({ amount: '1.0', unit: undefined });
+expectNotAssignable<Balance>({ amount: '1.0', unit: null });

src/api/balance.ts

@@ -0,0 +1,11 @@
+import type { Infer } from 'superstruct';
+import { string } from 'superstruct';
+
+import { object } from '../superstruct';
+
+export const BalanceStruct = object({
+  amount: string(),
+  unit: string(),
+});
+
+export type Balance = Infer<typeof BalanceStruct>;

src/api/index.ts

@@ -1,4 +1,5 @@
 export * from './account';
+export * from './balance';
 export * from './export';
 export * from './keyring';
 export * from './request';

src/api/keyring.ts

@@ -1,6 +1,7 @@
 import type { Json } from '@metamask/utils';
 
 import type { KeyringAccount } from './account';
+import type { Balance } from './balance';
 import type { KeyringAccountData } from './export';
 import type { KeyringRequest } from './request';
 import type { KeyringResponse } from './response';
@@ -44,6 +45,32 @@ export type Keyring = {
    */
   createAccount(options?: Record<string, Json>): Promise<KeyringAccount>;
 
+  /**
+   * Retrieve the balances of given account.
+   *
+   * @example
+   * ```ts
+   * keyring.getAccountBalances(
+   *   '43550276-c7d6-4fac-87c7-00390ad0ce90',
+   *   ['bip122:000000000019d6689c085ae165831e93/slip44:0']
+   * );
+   *
+   * // Returns:
+   * // {
+   * //   'bip122:000000000019d6689c085ae165831e93/slip44:0': {
+   * //     amount: '0.0001',
+   * //     unit: 'BTC',
+   * //   }
+   * // }
+   * ```
+   * @param id - The ID of the account to the balance of.
+   * @param assets - List of asset IDs (CAIP-19) to retrieve the balances of.
+   */
+  getAccountBalances?(
+    id: string,
+    assets: string[],
+  ): Promise<Record<string, Balance>>;
+
   /**
    * Filter supported chains for a given account.
    *