refactor!: remove useWalletAPIServer React hook from server package (#494)

BREAKING CHANGE: The useWalletAPIServer React hook has been removed from
@ledgerhq/wallet-api-server (v3.0.0). Users should instantiate WalletAPIServer
directly using the constructor or implement their own React hook.

Changes:
- Remove useWalletAPIServer hook and react.ts file from server package
- Remove React peer dependencies from package.json
- Update documentation to reflect removal and provide migration guide
- Update examples to use WalletAPIServer constructor directly
- Remove setAccounts() and setCurrencies() references (v2.0.0 changes)
- Add callouts explaining new account.list and currency.list handler requirements
- Update Ledger Live integration docs to clarify custom hook implementation

Migration:
- Use WalletAPIServer constructor directly for simple use cases
- Implement custom React hook for advanced state management (see Ledger Live example)

Author: Justkant

.changeset/famous-apricots-tan.md

@@ -0,0 +1,22 @@
+---
+"@ledgerhq/wallet-api-server": major
+---
+
+refactor!: remove useWalletAPIServer React hook from server package
+
+BREAKING CHANGE: The useWalletAPIServer React hook has been removed from
+@ledgerhq/wallet-api-server (v3.0.0). Users should instantiate WalletAPIServer
+directly using the constructor or implement their own React hook.
+
+Changes:
+- Remove useWalletAPIServer hook and react.ts file from server package
+- Remove React peer dependencies from package.json
+- Update documentation to reflect removal and provide migration guide
+- Update examples to use WalletAPIServer constructor directly
+- Remove setAccounts() and setCurrencies() references (v2.0.0 changes)
+- Add callouts explaining new account.list and currency.list handler requirements
+- Update Ledger Live integration docs to clarify custom hook implementation
+
+Migration:
+- Use WalletAPIServer constructor directly for simple use cases
+- Implement custom React hook for advanced state management (see Ledger Live example)

apps/docs/pages/docs/discover/wallet-api/server/index.mdx

@@ -29,17 +29,13 @@ shows how a server can be used, instantiating it via its constructor
 
 how to instantiate a server via its constructor
 
-### Check out [here](./server/wallet-api-server/react-hook)
-
-(optional, useful if using react) how to instantiate a server via a react hook
-
 ### Check out [this example](./server/usage-examples/with-constructor)
 
 shows how a server can be used, instantiating it via its constructor
 
 ### Check out [the usage of a server made within Ledger Live](./server/usage-examples/within-ledger-live)
 
-shows how a server can be used, instantiating it via the react hook
+shows how Ledger Live implements its own React hook to instantiate and manage the server
 
 </Steps>
 

apps/docs/pages/docs/discover/wallet-api/server/usage-examples/with-constructor.mdx

@@ -1,3 +1,5 @@
+import { Callout } from "nextra/components";
+
 ## Example usage of the walletAPIServer
 
 Here's how you can instantiate a new `WalletAPIServer` using its [constructor](../wallet-api-server#constructor)
@@ -29,43 +31,56 @@ const wapiServer = new WalletAPIServer(transport, config);
 
 two required arguments are passed, [transport](../wallet-api-server#transport) and [config](../wallet-api-server#walletcontextconfig).
 
-### setup accounts, currencies and permissions via setters
+### setup permissions
 
 ```ts
-wapiServer.setAccounts(accounts);
-wapiServer.setCurrencies(currencies);
 wapiServer.setPermissions({
-  currencyIds: ["**"],
-  methodIds: ["account.list", "account.receive", "account.request"],
+  methodIds: [
+    "account.list",
+    "account.receive",
+    "account.request",
+    "currency.list",
+  ],
 });
 ```
 
-Call setters to set the [accounts](../wallet-api-server#allaccounts),
-[currencies](../wallet-api-server#allcurrencies),
-and [permissions](../wallet-api-server#permissions)
+Set the [permissions](../wallet-api-server#permissions) to control which methods the app can access.
+
+<Callout type="info" emoji="ℹ️">
+  **Note:** As of version 2.0.0, `setAccounts()` and `setCurrencies()` have been
+  removed. You must now implement `account.list` and `currency.list` handlers
+  instead.
+</Callout>
 
 ### set wallet handlers
 
 ```ts
-    wapiServer.setHandler("account.request", async ({ accounts$, currencies$ }) => {
-      return new Promise((resolve, reject) => {
-        uiAccountRequest({
-          accounts$,
-          currencies: currencies.map({id} => id),
-          onSuccess: (account: AccountLike, parentAccount: Account | undefined) => {
-            resolve(accountToWalletAPIAccount(account, parentAccount));
-          },
-          onCancel: () => {
-            reject(new Error("Canceled by user"));
-          },
-        });
-      });
-    })
+// Handler to list all accounts
+wapiServer.setHandler("account.list", async () => {
+  return accounts.map((account) => accountToWalletAPIAccount(account));
+});
 
+// Handler to list all currencies
+wapiServer.setHandler("currency.list", async () => {
+  return currencies;
+});
+
+// Handler to request an account
+wapiServer.setHandler("account.request", async ({ accountIds }) => {
+  return new Promise((resolve, reject) => {
+    uiAccountRequest({
+      onSuccess: (account: AccountLike, parentAccount: Account | undefined) => {
+        resolve(accountToWalletAPIAccount(account, parentAccount));
+      },
+      onCancel: () => {
+        reject(new Error("Canceled by user"));
+      },
+    });
+  });
+});
 ```
 
-Set a [walletHandler](../wallet-api-server#wallethandlers) to handle
-actions that would request an account from the wallet.
+Set [walletHandlers](../wallet-api-server#wallethandlers) to handle wallet operations. The `account.list` and `currency.list` handlers are now required.
 
 ### wire up transport
 

apps/docs/pages/docs/discover/wallet-api/server/usage-examples/within-ledger-live.mdx

@@ -3,17 +3,16 @@ import { Steps } from "nextra/components";
 
 ## Usage of the walletAPIServer in Ledger Live
 
-The react hook [useWalletAPIServer](../wallet-api-server/react-hook)
-is used within [Ledger Live](https://github.com/LedgerHQ/ledger-live/)
-to create a walletAPIServer
+[Ledger Live](https://github.com/LedgerHQ/ledger-live/) implements its own React hook `useWalletAPIServer` to create and manage a `WalletAPIServer` instance.
 
-It is used in _ledger-live-common_ here
-**ledger-live-common/src/wallet-api/react.ts**  
-In this file, a walletAPIServer
-is created, and exposed through another hook (also called
-`useWalletAPIServer`)
+<Callout type="info" emoji="ℹ️">
+  The `useWalletAPIServer` hook is implemented directly in Ledger Live (in
+  **ledger-live-common/src/wallet-api/react.ts**), not in the wallet-api
+  library. This allows Ledger Live to have full control over the server
+  instantiation and configuration.
+</Callout>
 
-This (LLC hook) is in turn used in both
+This Ledger Live hook is used in both
 [LLD](https://github.com/LedgerHQ/ledger-live/blob/43aeb2a1c650c6231c14149b74e4a42135b15766/apps/ledger-live-desktop/src/renderer/components/Web3AppWebview/WalletAPIWebview.tsx#L10)
 and [LLM](https://github.com/LedgerHQ/ledger-live/blob/43aeb2a1c650c6231c14149b74e4a42135b15766/apps/ledger-live-mobile/src/components/Web3AppWebview/helpers.ts#L8)
 
@@ -74,18 +73,14 @@ here's a list of actions it triggers in LLD:
 
 ### LLC useWalletAPIServer() gets called
 
-The goal of LLC's `useWalletAPIServer` is simply to call the walletAPIServer hook (also called `useWalletAPIServer`)
+Ledger Live's `useWalletAPIServer` hook instantiates a `WalletAPIServer` directly using its [constructor](../wallet-api-server#constructor).
 
 Before doing so it:
 
-- Extracts [permissions](../wallet-api-server#permissions) From the manifest
-
-- Converts accounts sent from [useWebView](./within-ledger-live#usewebview) (coming from redux store) to [a format readable by walletAPIServer](../wallet-api-server#allaccounts)
+- Extracts [permissions](../wallet-api-server#permissions) from the manifest
 
 - Fetches and filters currencies (coming from `libs/ledger-live-common/src/currencies/helpers.ts` `listCurrencies`)
 
-- Converts filtered currencies to a format readable by wallet-api-server. More on that format [here](../wallet-api-server/react-hook#currencies)
-
 - Creates a [transport](../wallet-api-server#transport)
 
 ```js
@@ -103,17 +98,16 @@ function useTransport(postMessage: (message: string) => void | undefined): Trans
 
 ### walletAPIServer gets instantiated
 
-via the react hook [useWalletAPIServer](../wallet-api-server/react-hook)
+The `WalletAPIServer` is instantiated using the [WalletAPIServer constructor](../wallet-api-server#constructor) with the prepared transport, config, logger, and custom handlers.
 
 ### post-instantiation transport setup
 
 walletAPIServer sends back its `onMessage` callback, the webview will use
 it to send message to it.
 
 ```ts {1,12-13, 20}
-const { onMessage } = useWalletAPIServer({
+const { server, onMessage } = useWalletAPIServer({
   manifest,
-  accounts,
   config,
   webviewHook,
   uiHook,
@@ -126,7 +120,7 @@ const handleMessage = useCallback(
       onMessage(event.args[0]);
     }
   },
-  [onMessage]
+  [onMessage],
 );
 
 useEffect(() => {
@@ -143,13 +137,9 @@ to setup Ledger Live Wallet/UI/Store callbacks.
   <summary>Simplified example of setHandler() call</summary>
 
 ```js filename="libs/ledger-live-common/src/wallet-api/react.ts"
-    server.setHandler("account.request", async ({ accounts$, currencies$ }) => {
-      const currencies = await firstValueFrom(currencies$);
+    server.setHandler("account.request", async ({ accountIds }) => {
       return new Promise((resolve, reject) => {
-        let currencyList = currencyList = allCurrenciesAndTokens.filter(({ id }) => currencyIds.includes(id));
         uiAccountRequest({
-          accounts$,
-          currencies: currencyList,
           onSuccess: (account: AccountLike, parentAccount: Account | undefined) => {
             resolve(accountToWalletAPIAccount(account, parentAccount));
           },
@@ -197,11 +187,10 @@ flowchart TD
     SENDS:
 
     transport: so server can communicate TO webview
-    accounts
-    currencies
+    config
     permissions
     customHandlers
-    | B{wallet-api-server useWalletAPIServer}
+    | B{WalletAPIServer constructor}
     B --> |
       GETS BACK:
 

apps/docs/pages/docs/discover/wallet-api/server/wallet-api-server/index.mdx

@@ -50,9 +50,11 @@ export type Account = {
 
 </details>
 
-| Created via | name            |
-| ----------- | --------------- |
-| _setter_    | **setAccounts** |
+<Callout type="warning" emoji="⚠️">
+  **Note:** As of version 2.0.0, accounts are no longer managed by the server.
+  Instead, wallet implementations must provide an `account.list` handler that
+  returns the list of available accounts.
+</Callout>
 
 ### allCurrencies$
 
@@ -76,9 +78,11 @@ type Currency = {
 
 </details>
 
-| Created via | name              |
-| ----------- | ----------------- |
-| _setter_    | **setCurrencies** |
+<Callout type="warning" emoji="⚠️">
+  **Note:** As of version 2.0.0, currencies are no longer managed by the server.
+  Instead, wallet implementations must provide a `currency.list` handler that
+  returns the list of available currencies.
+</Callout>
 
 ---
 

apps/docs/pages/docs/discover/wallet-api/server/wallet-api-server/react-hook.mdx

@@ -1,62 +1,48 @@
 import { Callout } from "nextra/components";
 
-## useWalletAPIServer
+## useWalletAPIServer Hook (Removed)
 
-[source code](https://github.com/LedgerHQ/wallet-api/blob/main/packages/server/src/react.ts)
+<Callout type="warning" emoji="⚠️">
+  **This React hook has been removed from the wallet-api library as of version
+  3.0.0** The `useWalletAPIServer` hook is no longer exported from
+  `@ledgerhq/wallet-api-server`.
+</Callout>
 
-For convenience in a react environment, the hook `useWalletAPIServer`, is available.
+### Migration Guide
 
-It is used to setup a WalletAPIServer
+If you were using this hook, you have two options:
 
-<Callout type="info" emoji="ℹ️">
-  [It is how wallet API Server are created in ledger
-  live](../usage-examples/within-ledger-live)
-</Callout>
+1. **Use the WalletAPIServer constructor directly** (recommended)
 
-```js filename="packages/server/src/WalletAPIServer.ts"
-
-export function useWalletAPIServer({
-  transport,
-  config,
-  logger,
-  accounts,
-  currencies,
-  permission,
-  customHandlers,
-}){...}
-
-```
-
-| Parameter (destructured from single object) | required? | note                                                                            |
-| ------------------------------------------- | --------- | ------------------------------------------------------------------------------- |
-| _transport_                                 | ✅        | sets the [transport](../wallet-api-server#transport)                            |
-| _config_                                    | ✅        | sets the [walletContext.config](../wallet-api-server#walletcontextconfig) value |
-| _logger_                                    | ❌        | (optional) sets the logger                                                      |
-| _accounts_                                  | ✅        | sets the [accounts](../wallet-api-server#allaccounts)                           |
-| _currencies_                                | ✅        | sets the [currencies](../wallet-api-server#allcurrencies)                       |
-| _permissions_                               | ✅        | sets the [permissions](../wallet-api-server#permissions)                        |
-| _customHandlers_                            | ❌        | (optional) sets [customHandlers](../wallet-api-server#walletcontextconfig)      |
-
-Once instantiated, it
-
-- Sets custom handlers, in all cases (even if no custom handlers are sent from LLC),
-  it will be called to set the [requestHandlers](../wallet-api-server#requesthandlers)
-- Sets config, permissions, currencies and accounts.
-
-Then, it returns:
-
-```ts
-return {
-  server,
-  onMessage,
-};
-```
-
-`server` is our walletAPIServer instance.  
-`onMessage`, which will allow _APP -> SERVER_ communication.
-
-<Callout type="info" emoji="ℹ️">
-  Note that WalletAPIServer is instantiated as a ref
-  [useRef](https://react.dev/reference/react/useRef) we actually return
-  ```server: server.current```
-</Callout>
+   Instantiate the server using the [WalletAPIServer constructor](../wallet-api-server#constructor):
+
+   ```ts
+   import { WalletAPIServer } from "@ledgerhq/wallet-api-server";
+
+   const server = new WalletAPIServer(
+     transport,
+     config,
+     logger,
+     customHandlers,
+   );
+   ```
+
+2. **Implement your own React hook** (advanced use case)
+
+   You can create your own React hook similar to how [Ledger Live implements it](../usage-examples/within-ledger-live). This gives you full control over the server lifecycle and state management.
+
+### Breaking Changes in v2.0.0
+
+- Removed RxJS dependency from the server package
+- Removed observable-based state management (accounts$, currencies$, etc.)
+- Removed `setAccounts()` and `setCurrencies()` methods from WalletAPIServer
+- Wallet handlers now accept `accountId` strings instead of Account objects
+- New required wallet handlers: `account.list` and `currency.list`
+
+For more details, see the [changelog](https://github.com/LedgerHQ/wallet-api/blob/main/packages/server/CHANGELOG.md).
+
+### Reference Implementation
+
+To see how Ledger Live implements server management in a React environment, check out:
+
+- [Ledger Live's usage example](../usage-examples/within-ledger-live)

packages/server/package.json

@@ -22,11 +22,9 @@
     "@types/jest": "^29.5.12",
     "@types/node": "^24.10.0",
     "@types/picomatch": "^2.3.3",
-    "@types/react": "^18.2.57",
     "eslint": "^8.56.0",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
-    "react": "^18.2.0",
     "ts-jest": "^29.1.2",
     "ts-node": "^10.9.2",
     "typescript": "^5.3.3"
@@ -35,13 +33,5 @@
     "@ledgerhq/wallet-api-core": "workspace:*",
     "bignumber.js": "^9.1.2",
     "picomatch": "^4.0.1"
-  },
-  "peerDependencies": {
-    "react": "^17.x || ^18.x || ^19.x"
-  },
-  "peerDependenciesMeta": {
-    "react": {
-      "optional": true
-    }
   }
 }

packages/server/src/index.ts

@@ -1,3 +1,2 @@
-export * from "./react";
 export * from "./types";
 export * from "./WalletAPIServer";