@liberfi.io/react 0.1.3 → 0.1.5

package/README.md

@@ -0,0 +1,279 @@
+# @liberfi.io/react
+
+React integration layer for the Liberfi SDK. This package provides a `DexClientProvider` for dependency injection, query hooks (powered by TanStack Query) for data fetching, and subscription hooks for real-time WebSocket updates. It is the primary package consumed by Liberfi UI applications and widgets.
+
+## Design Philosophy
+
+- **Provider-based DI** — `DexClientProvider` injects `IClient` and `ISubscribeClient` instances via React context, keeping hooks decoupled from concrete implementations.
+- **Factory-generated hooks** — `createQueryHook` and `createInfiniteQueryHook` generate hooks from a declarative config, ensuring consistent API surface (each hook exports `use*Query`, `*QueryKey`, and `fetch*`).
+- **No built-in side effects** — Hooks do not trigger toasts, modals, or analytics. Errors are surfaced via TanStack Query state or `onError` callbacks, giving the caller full control.
+- **Query key namespacing** — All keys are prefixed with a configurable namespace (default `"liberfi"`) to avoid collisions.
+
+## Installation
+
+```bash
+pnpm add @liberfi.io/react
+```
+
+### Peer Dependencies
+
+The consumer must provide:
+
+| Package                 | Version |
+| ----------------------- | ------- |
+| `react`                 | >= 18   |
+| `react-dom`             | >= 18   |
+| `@tanstack/react-query` | ^5.90.2 |
+
+## API Reference
+
+### Components
+
+#### `DexClientProvider`
+
+Provides the Dex client instances and configuration to all descendant hooks.
+
+| Prop              | Type                   | Default     | Description                             |
+| ----------------- | ---------------------- | ----------- | --------------------------------------- |
+| `client`          | `API.IClient`          | (required)  | REST/HTTP client instance.              |
+| `subscribeClient` | `API.ISubscribeClient` | (required)  | WebSocket subscription client instance. |
+| `queryKeyPrefix`  | `string`               | `"liberfi"` | Prefix for all TanStack Query keys.     |
+| `children`        | `ReactNode`            | (required)  | Child components.                       |
+
+### Hooks — Core
+
+#### `useDexClient`
+
+Returns the `DexClientContextValue` from the nearest `DexClientProvider`.
+
+```typescript
+const { client, subscribeClient, queryKeyPrefix } = useDexClient();
+```
+
+Throws if called outside a `DexClientProvider`.
+
+### Hooks — Query (27 hooks)
+
+Each query hook is generated by `createQueryHook` and exports three items:
+
+- `use*Query(params, options?)` — React hook returning `UseQueryResult<TData, Error>`.
+- `*QueryKey(params, prefix?)` — Builds the full query key array for cache operations.
+- `fetch*(client, params)` — Standalone fetch function for use outside React.
+
+| Hook                                  | Params                                                      | Return Data               |
+| ------------------------------------- | ----------------------------------------------------------- | ------------------------- |
+| `useTokenQuery`                       | `{ chain, address }`                                        | `Token`                   |
+| `useTokensQuery`                      | `{ chain, addresses }`                                      | `Token[]`                 |
+| `useSearchTokensQuery`                | `SearchTokensOptions`                                       | `SearchTokenCursorList`   |
+| `useNewTokensQuery`                   | `{ chain, ...GetTokenListOptions }`                         | `Token[]`                 |
+| `useTrendingTokensQuery`              | `{ chain, resolution, ...GetTokenListOptions }`             | `Token[]`                 |
+| `useMigratedTokensQuery`              | `{ chain, ...GetTokenListOptions }`                         | `Token[]`                 |
+| `useFinalStretchTokensQuery`          | `{ chain, ...GetTokenListOptions }`                         | `Token[]`                 |
+| `useStockTokensQuery`                 | `{ chain, ...GetTokenListOptions }`                         | `Token[]`                 |
+| `useSwapRouteQuery`                   | `SwapParams`                                                | `SwapRoute`               |
+| `useTokenCandlesQuery`                | `{ chain, address, resolution, ...GetTokenCandlesOptions }` | `TokenCandle[]`           |
+| `useTokenMarketDataQuery`             | `{ chain, address }`                                        | `TokenMarketData`         |
+| `useTokenSecurityQuery`               | `{ chain, address }`                                        | `TokenSecurity`           |
+| `useTokenStatsQuery`                  | `{ chain, address }`                                        | `TokenStats`              |
+| `useTokenHoldersQuery`                | `{ chain, address, ...CursorListOptions }`                  | `CursorList<TokenHolder>` |
+| `useTokenTradesQuery`                 | `{ chain, address, ...GetTradesOptions }`                   | `CursorList<Trade>`       |
+| `useTokenActivitiesQuery`             | `{ chain, address, ...GetActivitiesOptions }`               | `CursorList<Activity>`    |
+| `useWalletPnlQuery`                   | `{ chain, address, resolution? }`                           | `WalletPnl`               |
+| `useWalletPortfoliosQuery`            | `{ chain, address, ...paginationOptions }`                  | `WalletPortfolios`        |
+| `useWalletPortfoliosByTokensQuery`    | `{ chain, address, tokenAddresses }`                        | `Portfolio[]`             |
+| `useWalletPortfolioPnlsQuery`         | `{ chain, address, ...paginationOptions }`                  | `WalletPortfolioPnls`     |
+| `useWalletPortfolioPnlsByTokensQuery` | `{ chain, address, tokenAddresses }`                        | `PortfolioPnl[]`          |
+| `useWalletTradesQuery`                | `{ chain, address, ...GetTradesOptions }`                   | `CursorList<Trade>`       |
+| `useWalletActivitiesQuery`            | `{ chain, address, ...GetActivitiesOptions }`               | `CursorList<Activity>`    |
+| `useTxSuccessQuery`                   | `{ chain, txHash, timeout? }`                               | `boolean`                 |
+| `usePresignedUploadUrlQuery`          | (none)                                                      | `string`                  |
+
+#### Special hooks
+
+| Hook                                  | Type           | Description                                                                                 |
+| ------------------------------------- | -------------- | ------------------------------------------------------------------------------------------- |
+| `useSendTxMutation`                   | Mutation       | Sends a signed transaction. Returns `UseMutationResult<SendTxResult, Error, SendTxParams>`. |
+| `useWalletPortfoliosInfiniteQuery`    | Infinite Query | Cursor-paginated wallet holdings with `fetchNextPage()`.                                    |
+| `useWalletPortfolioPnlsInfiniteQuery` | Infinite Query | Cursor-paginated wallet PnLs with `fetchNextPage()`.                                        |
+
+### Hooks — Subscription (14 hooks)
+
+Each subscription hook manages WebSocket lifecycle automatically (subscribe on mount, unsubscribe on unmount or deps change).
+
+**Signature:** `use*Subscription(params, callback, options?)`
+
+| Hook                                 | Params                           | Callback Data              |
+| ------------------------------------ | -------------------------------- | -------------------------- |
+| `useTokenSubscription`               | `{ chain, address }`             | `TokenSubscribed[]`        |
+| `useTokenCandlesSubscription`        | `{ chain, address, resolution }` | `TokenCandle[]`            |
+| `useTokenTradesSubscription`         | `{ chain, address }`             | `Trade[]`                  |
+| `useTokenActivitiesSubscription`     | `{ chain, address }`             | `Activity[]`               |
+| `useWalletPnlSubscription`           | `{ chain, address }`             | `WalletPnlSubscribed[]`    |
+| `useWalletPortfoliosSubscription`    | `{ chain, address }`             | `PortfolioSubscribed[]`    |
+| `useWalletPortfolioPnlsSubscription` | `{ chain, address }`             | `PortfolioPnlSubscribed[]` |
+| `useWalletTradesSubscription`        | `{ chain, address }`             | `Trade[]`                  |
+| `useWalletActivitiesSubscription`    | `{ chain, address }`             | `Activity[]`               |
+| `useNewTokensSubscription`           | `{ chain }`                      | `TokenSubscribed[]`        |
+| `useTrendingTokensSubscription`      | `{ chain }`                      | `TokenSubscribed[]`        |
+| `useMigratedTokensSubscription`      | `{ chain }`                      | `TokenSubscribed[]`        |
+| `useFinalStretchTokensSubscription`  | `{ chain }`                      | `TokenSubscribed[]`        |
+| `useStockTokensSubscription`         | `{ chain }`                      | `TokenSubscribed[]`        |
+
+### Types
+
+| Name                     | Definition                                                        | Description                     |
+| ------------------------ | ----------------------------------------------------------------- | ------------------------------- |
+| `DexClientProviderProps` | `PropsWithChildren<{ client, subscribeClient, queryKeyPrefix? }>` | Props for `DexClientProvider`.  |
+| `DexClientContextValue`  | `{ client, subscribeClient, queryKeyPrefix }`                     | Shape of the context value.     |
+| `SubscriptionOptions`    | `{ enabled?: boolean; onError?: (error: Error) => void }`         | Options for subscription hooks. |
+
+### Constants
+
+| Name                       | Value       | Description                        |
+| -------------------------- | ----------- | ---------------------------------- |
+| `DEFAULT_QUERY_KEY_PREFIX` | `"liberfi"` | Default prefix for all query keys. |
+
+### Utility Functions
+
+| Function             | Signature                                                                     | Description                                                   |
+| -------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `toKeySegment`       | `(value: string \| number \| boolean \| Date \| undefined \| null) => string` | Serializes a primitive into a stable query key segment.       |
+| `toSortedKeySegment` | `(value: unknown[] \| undefined \| null) => string`                           | Serializes an array into a sorted JSON string for query keys. |
+
+## Usage Examples
+
+### Basic setup
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { Client } from "@liberfi.io/client";
+import { DexClientProvider } from "@liberfi.io/react";
+
+const queryClient = new QueryClient();
+const client = new Client("your-api-token");
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <DexClientProvider client={client} subscribeClient={client}>
+        <MyComponent />
+      </DexClientProvider>
+    </QueryClientProvider>
+  );
+}
+```
+
+### Fetching token data
+
+```tsx
+import { useTokenQuery } from "@liberfi.io/react";
+import { Chain } from "@liberfi.io/types";
+
+function TokenPrice({ address }: { address: string }) {
+  const {
+    data: token,
+    isLoading,
+    error,
+  } = useTokenQuery({
+    chain: Chain.SOLANA,
+    address,
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      {token.name}: ${token.marketData?.priceInUsd}
+    </div>
+  );
+}
+```
+
+### Real-time subscription
+
+```tsx
+import { useCallback } from "react";
+import { useTokenSubscription } from "@liberfi.io/react";
+import { Chain, API } from "@liberfi.io/types";
+
+function LiveTokenPrice({ address }: { address: string }) {
+  const handleUpdate = useCallback((updates: API.TokenSubscribed[]) => {
+    for (const update of updates) {
+      console.log("New price:", update.marketData?.priceInUsd);
+    }
+  }, []);
+
+  useTokenSubscription({ chain: Chain.SOLANA, address }, handleUpdate, {
+    enabled: true,
+  });
+
+  return <div>Listening for updates...</div>;
+}
+```
+
+### Manual cache invalidation
+
+```tsx
+import { useQueryClient } from "@tanstack/react-query";
+import { tokenQueryKey } from "@liberfi.io/react";
+import { Chain } from "@liberfi.io/types";
+
+function RefreshButton({ address }: { address: string }) {
+  const queryClient = useQueryClient();
+
+  return (
+    <button
+      onClick={() =>
+        queryClient.invalidateQueries({
+          queryKey: tokenQueryKey({ chain: Chain.SOLANA, address }),
+        })
+      }
+    >
+      Refresh
+    </button>
+  );
+}
+```
+
+### Infinite scrolling
+
+```tsx
+import { useWalletPortfoliosInfiniteQuery } from "@liberfi.io/react";
+import { Chain } from "@liberfi.io/types";
+
+function PortfolioList({ walletAddress }: { walletAddress: string }) {
+  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
+    useWalletPortfoliosInfiniteQuery({
+      chain: Chain.SOLANA,
+      address: walletAddress,
+      limit: 20,
+    });
+
+  const portfolios = data?.pages.flatMap((page) => page.portfolios) ?? [];
+
+  return (
+    <div>
+      {portfolios.map((p) => (
+        <div key={p.address}>
+          {p.symbol}: ${p.amountInUsd}
+        </div>
+      ))}
+      {hasNextPage && (
+        <button onClick={() => fetchNextPage()} disabled={isFetchingNextPage}>
+          Load More
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+## Future Improvements
+
+- Export `createQueryHook` and `createInfiniteQueryHook` factories so consumers can create custom hooks.
+- Add a standalone `fetch` function to infinite query hooks for API consistency.
+- Add a mutation key to `useSendTxMutation` for cache introspection.
+- Consolidate `version.ts` global side effect into a shared utility.
+- Document subscription deps-stability best practices for consumers.
+- Type `useSubscriptionEffect` deps more strictly (currently `unknown[]`).