@agg-build/hooks 1.0.0

package/README.md

@@ -0,0 +1,403 @@
+# @agg-build/hooks
+
+React hooks and providers for the [AGG](https://docs.agg.market/) prediction market aggregator.
+Wraps [`@agg-build/sdk`](https://www.npmjs.com/package/@agg-build/sdk) with React context, shared auth/session
+state, TanStack Query–powered data fetching, and live WebSocket streams.
+
+## What it is
+
+`@agg-build/hooks` is the React bindings layer. It owns the `AggClient` inside a provider, keeps auth
+and balance state in sync across your component tree, and exposes hooks for every AGG surface —
+markets, orderbooks, charts, live trades, execution, managed wallets, deposits, search, and UI
+config. Data hooks are backed by [TanStack Query](https://tanstack.com/query), and live-data hooks
+are backed by the SDK's `AggWebSocket`.
+
+## When to use this package
+
+- You are building a React app and want hooks instead of calling the SDK directly.
+- You want a single provider that manages session, UI config, balances, and WebSocket lifecycle.
+- You plan to render AGG trading UI with [`@agg-build/ui`](https://www.npmjs.com/package/@agg-build/ui) or the
+  modular auth UI in [`@agg-build/auth`](https://www.npmjs.com/package/@agg-build/auth) — both require this
+  package.
+
+If you are not using React, use [`@agg-build/sdk`](https://www.npmjs.com/package/@agg-build/sdk) directly.
+
+## Install
+
+```bash
+npm install @agg-build/sdk @agg-build/hooks
+```
+
+## Quick start
+
+```tsx
+import { AggProvider } from "@agg-build/hooks";
+import { createAggClient } from "@agg-build/sdk";
+
+const client = createAggClient({
+  baseUrl: "https://api.agg.market",
+  appId: "your-app-id",
+  wsUrl: "wss://ws.agg.market",
+});
+
+export function App() {
+  return (
+    <AggProvider
+      client={client}
+      config={{
+        general: { locale: "en-US", theme: "dark" },
+        features: { enableAnimations: true, enableLiveUpdates: true },
+      }}
+    >
+      <YourApp />
+    </AggProvider>
+  );
+}
+```
+
+`AggProvider` composes the SDK, UI config, balance, and WebSocket contexts into one. If you
+prefer to compose them yourself, the individual providers (`AggSdkProvider`, `AggUiProvider`,
+`AggBalanceProvider`) are exported too.
+
+> `AggProvider` creates its own internal `QueryClientProvider` if one is not already in the tree,
+> so you don't need to install or configure TanStack Query to get started. Drop in your own
+> `<QueryClientProvider>` if you want to share a cache with the rest of your app.
+
+### Signing in with a wallet
+
+`useAggAuth` is a lower-level hook for wiring your own wallet UI. Pass a `signMessage` callback
+from wagmi (Ethereum) or a Solana wallet adapter:
+
+```tsx
+import { useAggAuth } from "@agg-build/hooks";
+import { useAccount, useSignMessage } from "wagmi";
+
+function SignIn() {
+  const { address, chainId } = useAccount();
+  const { signMessageAsync } = useSignMessage();
+  const { signIn, signOut, isAuthenticated, user, isLoading, error } = useAggAuth({
+    signMessage: (message) => signMessageAsync({ message }),
+    address,
+    chainId,
+  });
+
+  if (isAuthenticated) {
+    return (
+      <div>
+        <p>Signed in as {user?.id}</p>
+        <button onClick={() => signOut()}>Sign out</button>
+      </div>
+    );
+  }
+
+  return (
+    <button disabled={isLoading} onClick={() => signIn("Sign in to AGG")}>
+      Sign in with Ethereum
+    </button>
+  );
+}
+```
+
+For Solana, pass a `signMessage` that signs the raw UTF-8 bytes and returns a base58-encoded
+signature:
+
+```tsx
+import bs58 from "bs58";
+import { useWallet } from "@solana/wallet-adapter-react";
+import { useAggAuth } from "@agg-build/hooks";
+
+function SolanaSignIn() {
+  const { publicKey, signMessage } = useWallet();
+  const { signIn, isLoading } = useAggAuth({
+    address: publicKey?.toBase58(),
+    chain: "solana",
+    chainId: "mainnet",
+    signMessage: async (message) => {
+      const bytes = await signMessage!(new TextEncoder().encode(message));
+      return bs58.encode(bytes);
+    },
+  });
+
+  return (
+    <button disabled={isLoading} onClick={() => signIn("Sign in to AGG")}>
+      Sign in with Solana
+    </button>
+  );
+}
+```
+
+For a fully packaged connect/sign-in UI with SIWE, SIWS, Google, Apple, Twitter/X, and email
+magic-link support, use [`@agg-build/auth`](https://www.npmjs.com/package/@agg-build/auth).
+
+### Rendering market data
+
+```tsx
+import { useVenueEvents, useMarketOrderbook } from "@agg-build/hooks";
+
+function MarketList() {
+  const { data, isLoading, fetchNextPage, hasNextPage } = useVenueEvents({
+    limit: 20,
+  });
+
+  if (isLoading) return <p>Loading…</p>;
+
+  return (
+    <>
+      {data?.pages
+        .flatMap((page) => page.data)
+        .map((event) => (
+          <article key={event.id}>{event.title}</article>
+        ))}
+      {hasNextPage ? <button onClick={() => fetchNextPage()}>Load more</button> : null}
+    </>
+  );
+}
+
+function LiveOrderbook({ venueMarketIds }: { venueMarketIds: string[] }) {
+  const { book, isLoading } = useMarketOrderbook({ venueMarketIds });
+  if (isLoading) return null;
+  return <pre>{JSON.stringify(book, null, 2)}</pre>;
+}
+```
+
+### Linking an external partner user ID
+
+Generate the signed assertion on your backend with `signExternalId()` from `@agg-build/sdk/server`, then
+call `useExternalId()` on the frontend:
+
+```tsx
+import { useEffect, useRef } from "react";
+import { useExternalId } from "@agg-build/hooks";
+
+function LinkPartnerAccount({
+  assertion,
+}: {
+  assertion: { externalId: string; timestamp: number; hmac: string } | null;
+}) {
+  const { linkExternalId } = useExternalId();
+  const lastLinked = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (!assertion) return;
+    const key = `${assertion.externalId}:${assertion.timestamp}`;
+    if (lastLinked.current === key) return;
+    lastLinked.current = key;
+    void linkExternalId(assertion).catch(() => {
+      lastLinked.current = null;
+    });
+  }, [assertion, linkExternalId]);
+
+  return null;
+}
+```
+
+## Main hooks
+
+### Core
+
+| Hook                  | Description                                                   |
+| --------------------- | ------------------------------------------------------------- |
+| `useAggClient()`      | Access the underlying `AggClient` instance                    |
+| `useAggAuth(options)` | Wallet-signature helper for SIWE/SIWS sign-in                 |
+| `useAggAuthContext()` | Full auth context (isAuthenticated, user, signIn, signOut, …) |
+| `useAggAuthState()`   | Read-only auth state                                          |
+| `useLinkAccount()`    | Link an additional auth provider to the current account       |
+| `useExternalId()`     | Link a backend-signed partner user ID                         |
+| `useGeoBlock()`       | Reactive geo-block state for restricted regions               |
+
+### Market data
+
+| Hook                             | Description                                         |
+| -------------------------------- | --------------------------------------------------- |
+| `useVenueEvents(options?)`       | Events with cursor-based infinite pagination        |
+| `useVenueEvent({ eventId })`     | Fetch a single event by ID                          |
+| `useEnrichedVenueEvent(options)` | Event + enriched venueMarkets with full market data |
+| `useVenueMarkets(options?)`      | Markets with filters (infinite pagination)          |
+| `useCategories(options?)`        | Market categories (infinite pagination)             |
+| `useSearch(options?)`            | Typeahead search across events                      |
+
+### Orderbooks & routing
+
+| Hook                          | Description                                         |
+| ----------------------------- | --------------------------------------------------- |
+| `useMarketOrderbook(options)` | Canonical orderbook with live WS updates            |
+| `useOrderBook(options)`       | Batch multiple venue orderbooks into one result     |
+| `useOrderbookQuote(options)`  | Compute a quote from the orderbook for a size/side  |
+| `useSmartRoute(options)`      | Optimal order routing across venues via MILP solver |
+
+### Charts
+
+| Hook                            | Description                                         |
+| ------------------------------- | --------------------------------------------------- |
+| `useMarketChart(options)`       | Historical candles with live WS updates             |
+| `useLiveCandles(options)`       | Merge REST historical + live `CandleBuilder` output |
+| `useLiveCandleOverlay(options)` | Scale candles for chart rendering with live overlay |
+
+### Live data
+
+| Hook                                 | Description                                       |
+| ------------------------------------ | ------------------------------------------------- |
+| `useLiveMarket(canonicalMarketId)`   | Subscribe to live orderbook + trades for a market |
+| `useLiveTrades(canonicalMarketId)`   | Recent trades only (max 50, newest first)         |
+| `useLiveOutcomePrices(venueMarkets)` | Derive live display prices for all outcomes       |
+| `useVenueMarketMidpoints(options)`   | Midpoints for visible markets                     |
+| `useViewportMidpoints(options)`      | Midpoints batched for the visible viewport        |
+| `useVisibleIds(options)`             | Track IDs currently visible in a scroll container |
+
+### WebSocket
+
+| Hook                                                    | Description                                      |
+| ------------------------------------------------------- | ------------------------------------------------ |
+| `useAggWebSocket()`                                     | Access the raw `AggWebSocket` instance           |
+| `useOnOrderSubmitted(callback)`                         | Subscribe to order submission events             |
+| `useOnBalanceUpdate(callback)`                          | Subscribe to balance update events               |
+| `useOnRedeemEvent(callback)`                            | Subscribe to redeem events                       |
+| `useEventOrderbookData(venueMarkets, selectedMarketId)` | WS orderbook subscription for an event's markets |
+
+### Balances
+
+| Hook                     | Description                                       |
+| ------------------------ | ------------------------------------------------- |
+| `useAggBalance()`        | Balance context (totalBalance, breakdown, venues) |
+| `useAggBalanceContext()` | Full balance context with refetch                 |
+| `useAggBalanceState()`   | Read-only balance state                           |
+| `useManagedBalances()`   | Query unified managed wallet balances             |
+
+### Orders & positions
+
+| Hook                              | Description                                       |
+| --------------------------------- | ------------------------------------------------- |
+| `useOrders(options?)`             | List trade-executor orders (offset pagination)    |
+| `useExecutionOrders(options?)`    | List execution orders (cursor pagination)         |
+| `useExecutionPositions(options?)` | List execution positions (cursor pagination)      |
+| `useUserHoldings(options)`        | Fetch venue-specific holdings                     |
+| `usePositions(options?)`          | Query user positions grouped by matched market    |
+| `useUserActivity(options?)`       | Unified activity feed (trades, deposits, bridges) |
+
+### Managed execution
+
+| Hook                            | Description                                                    |
+| ------------------------------- | -------------------------------------------------------------- |
+| `useQuoteManaged(options?)`     | Request a managed execution quote (2-min TTL)                  |
+| `useExecuteManaged(options?)`   | Execute a previously quoted managed trade                      |
+| `useValidateManaged(options?)`  | Pre-validate balances/bridge without quoting                   |
+| `useWithdrawManaged(options?)`  | Withdraw from managed wallets                                  |
+| `useSyncBalances(options?)`     | Trigger on-chain balance sync                                  |
+| `useExecutionProgress(options)` | Track execution through phases (pending → submitted → updated) |
+| `useRedeem()`                   | Claim winnings from resolved markets                           |
+| `useRedeemEligibleCount()`      | Count of positions eligible to redeem                          |
+
+### Deposits (subpath)
+
+Import from `@agg-build/hooks/deposit` to keep wallet-heavy hooks out of your main bundle:
+
+| Hook                            | Description                                             |
+| ------------------------------- | ------------------------------------------------------- |
+| `useDepositFlow(options?)`      | End-to-end deposit flow (select token → send → confirm) |
+| `useWalletTokenBalance(params)` | Read ERC-20 / SPL balance for the connected wallet      |
+| `useWalletSendToken(params)`    | Execute a transfer using the connected wallet           |
+| `useWalletTransactionStatus()`  | Poll on-chain status for a transfer                     |
+| `useDepositAddresses(options?)` | Managed wallet deposit addresses                        |
+| `useSyncBalances(options?)`     | Re-expose from the main entry for colocated imports     |
+| `normalizeWalletError(error)`   | Convert wallet-library errors to a friendly shape       |
+
+### Ramps
+
+| Hook               | Description                  |
+| ------------------ | ---------------------------- |
+| `useRampQuotes()`  | Query on/off-ramp quotes     |
+| `useRampSession()` | Create a ramp widget session |
+
+### UI config & utilities
+
+| Hook                             | Description                              |
+| -------------------------------- | ---------------------------------------- |
+| `useSdkUiConfig()`               | Read the SDK-level UI config             |
+| `useAggUiConfig()`               | Read the full AGG UI config              |
+| `useAggLabels()` / `useLabels()` | Access UI label strings                  |
+| `useEventTradingContext()`       | Event/market/outcome selection           |
+| `useDebouncedValue(value, ms)`   | Debounce a value by delay                |
+| `useAppConfig()`                 | Partner app config (feature flags, etc.) |
+
+## Providers
+
+| Provider                 | Purpose                                                  |
+| ------------------------ | -------------------------------------------------------- |
+| `AggProvider`            | One-stop provider: SDK + UI config + balance + WebSocket |
+| `AggSdkProvider`         | SDK + auth state only                                    |
+| `AggUiProvider`          | UI config (labels, theme, feature flags, search state)   |
+| `AggBalanceProvider`     | Balance context (totals, breakdown)                      |
+| `EventListStateProvider` | Shared pagination/filter state for event lists           |
+
+### UI config
+
+`AggProvider` accepts a sectioned config object:
+
+- `enableLogs` / `enableWebsocketsLogs` — turn on debug logging
+- `general` — `locale`, `theme` (`"light" | "dark"`), `rootClassName`, `labels`
+- `features` — `showVenueLogo`, `enableAnimations`, `enableLiveUpdates`, `enableGradients`
+- `market` — `arbitrageThreshold`
+- `chart` — `defaultChartTimeRange`, `selectedChartTimeRange`
+- `search` — provider-owned search state + callbacks for host-app routing/analytics
+
+`locale`, `theme`, and `selectedChartTimeRange` are automatically persisted to `localStorage`.
+
+## Query keys
+
+For direct React Query cache access (e.g. `queryClient.invalidateQueries()`):
+
+```typescript
+import { executionKeys } from "@agg-build/hooks";
+
+queryClient.invalidateQueries({ queryKey: executionKeys.balances() });
+queryClient.invalidateQueries({ queryKey: executionKeys.positions() });
+queryClient.invalidateQueries({ queryKey: executionKeys.orders() });
+```
+
+`executionKeys` is the only key builder exported publicly — market data queries are managed
+internally by the WebSocket provider.
+
+## Behavior notes
+
+- `useOrderbookQuote` debounces `size` changes by 300 ms before querying.
+- `useDepositAddresses` polls every 3 s while the managed wallet is being provisioned
+  (`ready === false`), then switches to 60 s stale time.
+- `useLiveCandles` merges REST historical candles with live `CandleBuilder` output; on collision
+  the live version wins.
+- For binary markets, the first outcome gets the midpoint and the second gets `1 − midpoint`.
+- `CandleBuilder` batches `onChange` callbacks at ~16 ms (rAF in browsers, setTimeout otherwise).
+- Execution mutations (`useExecuteManaged`, `useWithdrawManaged`, `useSyncBalances`)
+  auto-invalidate related balance/position/order queries on success.
+
+## Entrypoints
+
+| Entry                      | Purpose                                             |
+| -------------------------- | --------------------------------------------------- |
+| `@agg-build/hooks`         | All providers and hooks                             |
+| `@agg-build/hooks/deposit` | Wallet-heavy deposit hooks (tree-shakeable subpath) |
+
+## Peer dependencies
+
+Required:
+
+- `@agg-build/sdk`
+- `react` ^18.0.0 or ^19.0.0
+
+Optional (only needed for wallet-based sign-in / deposits):
+
+- `wagmi` ^2.0.0 (SIWE + ERC-20 deposits)
+- `viem` ^2.0.0 (paired with `wagmi`)
+- `@solana/wallet-adapter-react` ^0.15.0 (SIWS + SPL deposits)
+- `@solana/web3.js` ^1.95.0
+
+## Links
+
+- Documentation — <https://docs.agg.market/>
+- Demo app — <https://demo.agg.market/>
+- Vanilla SDK — [`@agg-build/sdk`](https://www.npmjs.com/package/@agg-build/sdk)
+- Trading UI — [`@agg-build/ui`](https://www.npmjs.com/package/@agg-build/ui)
+- Connect / sign-in UX — [`@agg-build/auth`](https://www.npmjs.com/package/@agg-build/auth)
+
+## License
+
+MIT