@provex/react 1.2.3

package/README.md

@@ -0,0 +1,441 @@
+# @provex/react
+
+Portable React buy-flow component and hooks for the Provex protocol. Framework-agnostic (no Chakra, no styled-components) — works in any React app.
+
+## Install
+
+```bash
+npm install @provex/react @provex/indexer-client react viem
+# or
+yarn add @provex/react @provex/indexer-client react viem
+```
+
+### Peer Dependencies
+
+| Package | Version |
+|---------|---------|
+| `react` | `^18.0.0` |
+| `viem` | `^2.0.0` |
+| `wagmi` | `^2.0.0` (optional — only needed for `useWagmiWallet`) |
+
+## Quick Start
+
+### 1. Wrap your app with ProvexProvider
+
+```tsx
+import { ProvexProvider } from '@provex/react'
+import { createPonderAdapter } from '@provex/indexer-client'
+import { pulsechain } from 'viem/chains'
+
+const indexer = createPonderAdapter()
+
+function App() {
+  return (
+    <ProvexProvider
+      config={{
+        apiUrl: 'https://app.provex.com',
+        chain: pulsechain,        // viem Chain object
+      }}
+      indexer={indexer}
+    >
+      <YourApp />
+    </ProvexProvider>
+  )
+}
+```
+
+### 2. Add the buy widget
+
+**With wagmi (easiest):**
+
+```tsx
+import { ProvexBuyWagmi } from '@provex/react'
+import '@provex/react/styles'
+
+function BuyPage() {
+  return (
+    <ProvexBuyWagmi
+      onIntentSignaled={(hash, chainId) => console.log('Order placed:', hash)}
+      onComplete={(hash, chainId) => console.log('Purchase complete:', hash)}
+    />
+  )
+}
+```
+
+`ProvexBuyWagmi` reads the connected wallet from wagmi context automatically. Your app just needs `WagmiProvider` and `ProvexProvider` above it.
+
+**With any wallet:**
+
+```tsx
+import { ProvexBuy } from '@provex/react'
+import '@provex/react/styles'
+
+function BuyPage() {
+  const wallet = {
+    address: connectedAddress,
+    sendTransaction: async (tx) => {
+      // Your wallet's sendTransaction implementation
+      return txHash
+    },
+  }
+
+  return (
+    <ProvexBuy
+      wallet={wallet}
+      onComplete={(hash, chainId) => console.log('Done!', hash)}
+    />
+  )
+}
+```
+
+## Three Layers
+
+Use whichever layer matches your needs:
+
+| Layer | Export | Use case |
+|-------|--------|----------|
+| 3 | `<ProvexBuy>` / `<ProvexBuyWagmi>` | Drop-in widget, zero UI code |
+| 2 | `<ProvexBuyProvider>` + phase components | Custom layout, same state machine |
+| 1 | `useProvexBuy()` | Fully custom UI, just the state machine |
+
+### Layer 2 — Custom layout
+
+```tsx
+import {
+  ProvexBuyProvider,
+  BrowsePhase,
+  CommittedPhase,
+  ProvingPhase,
+  CompletePhase,
+} from '@provex/react'
+
+function CustomBuy({ wallet }) {
+  return (
+    <ProvexBuyProvider wallet={wallet} onComplete={handleDone}>
+      <div className="my-layout">
+        <BrowsePhase />
+        <CommittedPhase />
+        <ProvingPhase />
+        <CompletePhase />
+      </div>
+    </ProvexBuyProvider>
+  )
+}
+```
+
+### Layer 1 — Headless hook
+
+```tsx
+import { useProvexBuy } from '@provex/react'
+
+function CustomBuy({ wallet }) {
+  const {
+    phase,
+    amount, setAmount,
+    deposits, selectedDeposit,
+    rate, rateDisplay,
+    canSubmit, validationMessage,
+    submitOrder, confirmPayment, reset,
+  } = useProvexBuy({ wallet })
+
+  // Render your own UI using the state machine
+}
+```
+
+## ProveXClient (Framework-Agnostic)
+
+For Node.js, serverless, or non-React apps, use the core client directly:
+
+```ts
+import { createProveXClient } from '@provex/react'
+import { pulsechain } from 'viem/chains'
+
+const client = createProveXClient({
+  chain: pulsechain,
+  wallet: myWalletAdapter,
+})
+
+// Create a deposit
+const { hash } = await client.createDeposit({
+  token: USDC_ADDRESS,
+  amount: 1000_000000n,
+  paymentMethods: [
+    { provider: 'venmo', payeeId: '@myvenmo', currencies: [{ code: 'USD', minRate: 0n }] },
+  ],
+})
+
+// Signal intent (buy side)
+const { intentHash } = await client.signalIntent({
+  deposit: { escrow: '0x...', localId: 1n },
+  paymentMethod: paymentMethodHash,
+  tokenAmount: 100_000000n,
+  toAddress: buyerAddress,
+  fiatCurrencyCode: currencyHash,
+  conversionRate: rate,
+})
+
+// Prepare-only mode (for smart accounts, relayers, multisigs)
+const prepared = await client.addFunds.prepare({ depositId: 1n, amount: 500_000000n })
+// → { to, data, value, chainId } — hand to Safe SDK, Privy, etc.
+```
+
+## Hooks API
+
+### useDeposits
+
+Fetch available deposits matching a payment method and token.
+
+```tsx
+import { useDeposits, getRate } from '@provex/react'
+
+const { deposits, isLoading, getMatchableDeposits } = useDeposits({
+  token: usdcToken,
+  paymentMethod: 'venmo',
+})
+
+const matches = getMatchableDeposits('100') // $100
+```
+
+### useSignalIntent
+
+Signal intent to buy tokens (lock USDC in escrow).
+
+```tsx
+import { useSignalIntent } from '@provex/react'
+
+const { startOrder, status, message, isLoading } = useSignalIntent({
+  wallet,
+  chainId: 369,
+  deposit: selectedDeposit,
+  onSuccess: (intentHash) => navigate(`/verify/${intentHash}`),
+})
+```
+
+### useReputation
+
+Fetch the connected user's reputation tier and cooldown status.
+
+```tsx
+import { useReputation, getTierDisplayInfo } from '@provex/react'
+
+const { reputation, isLoading } = useReputation({
+  address: walletAddress,
+  chainId: 369,
+})
+
+const tierInfo = getTierDisplayInfo(reputation.tier)
+```
+
+### useReputationLimits
+
+Calculate trading limits based on reputation and payment method.
+
+```tsx
+import { useReputationLimits } from '@provex/react'
+
+const { effectiveCap, isOnCooldown, cooldownRemaining } = useReputationLimits({
+  chainId: 369,
+  selectedPaymentMethod: 'venmo',
+  tier: reputation.tier,
+  amountInInt: parseUnits('100', { decimals: 2 }),
+})
+```
+
+### useProtocolFees
+
+Read protocol fees from the on-chain Orchestrator contract.
+
+```tsx
+import { useProtocolFees } from '@provex/react'
+
+const { feeInfo, isLoading } = useProtocolFees({
+  chainId: 8453,
+  escrowAddress: '0x...',
+})
+```
+
+### usePayeeDetails
+
+Fetch intent details and payee information for the verification flow.
+
+```tsx
+import { usePayeeDetails } from '@provex/react'
+
+const { intent, intentStatus, payeeDetails, isFetching } = usePayeeDetails({
+  intentHash: '0xabc...',
+  chainId: 369,
+})
+```
+
+### useWagmiWallet
+
+Bridge wagmi's wallet to the `WalletAdapter` interface.
+
+```tsx
+import { useWagmiWallet } from '@provex/react'
+
+const wallet = useWagmiWallet()
+// Returns WalletAdapter | null (null when disconnected)
+```
+
+## WalletAdapter Interface
+
+The `WalletAdapter` decouples @provex/react from any specific wallet SDK.
+
+```ts
+interface WalletAdapter {
+  address?: `0x${string}`
+  sendTransaction(tx: {
+    to: `0x${string}`
+    data: `0x${string}`
+    value?: bigint
+    chainId: number
+    maxFeePerGas?: bigint
+    maxPriorityFeePerGas?: bigint
+  }): Promise<`0x${string}`>
+  readContract?(params: {
+    address: `0x${string}`
+    abi: readonly unknown[]
+    functionName: string
+    args?: readonly unknown[]
+    chainId?: number
+  }): Promise<unknown>
+}
+```
+
+Only `sendTransaction` is required. `readContract` is optional — the client falls back to public RPC.
+
+## IndexerAdapter
+
+The `IndexerAdapter` decouples data fetching from any specific indexer backend. Use `createPonderAdapter()` from `@provex/indexer-client` for the standard Provex setup, or implement your own against The Graph, a REST API, or direct RPC.
+
+```ts
+import { createPonderAdapter } from '@provex/indexer-client'
+
+const indexer = createPonderAdapter()
+```
+
+## Styling
+
+### Default Stylesheet
+
+Import the built-in styles for a functional baseline:
+
+```tsx
+import '@provex/react/styles'
+```
+
+### CSS Custom Properties
+
+Override any CSS variable on the `[data-provex-root]` selector:
+
+```css
+[data-provex-root] {
+  --provex-color-bg: #0f0f23;
+  --provex-color-primary: #00d4aa;
+  --provex-color-text: #ffffff;
+  --provex-border-radius: 12px;
+  --provex-max-width: 480px;
+}
+```
+
+Available variables:
+
+| Variable | Default (light) | Description |
+|----------|----------------|-------------|
+| `--provex-color-bg` | `#ffffff` | Background color |
+| `--provex-color-surface` | `#f8f9fa` | Surface/card color |
+| `--provex-color-border` | `#e2e8f0` | Border color |
+| `--provex-color-text` | `#1a202c` | Primary text color |
+| `--provex-color-text-secondary` | `#718096` | Secondary text |
+| `--provex-color-primary` | `#3b82f6` | Primary accent |
+| `--provex-color-primary-hover` | `#2563eb` | Hover state |
+| `--provex-color-success` | `#10b981` | Success color |
+| `--provex-color-error` | `#ef4444` | Error color |
+| `--provex-space-*` | various | Spacing (xs, sm, md, lg, xl) |
+| `--provex-font-family` | system stack | Font family |
+| `--provex-font-size-*` | various | Font sizes (sm, md, lg, xl) |
+| `--provex-border-radius` | `0.5rem` | Border radius |
+| `--provex-max-width` | `420px` | Max component width |
+
+### Theme Prop
+
+Pass theme overrides directly to the widget:
+
+```tsx
+<ProvexBuy
+  wallet={wallet}
+  theme={{
+    accent: '#00d4aa',
+    background: '#0f0f23',
+    text: '#ffffff',
+    radius: '12px',
+  }}
+/>
+```
+
+### className Prop
+
+Pass a `className` to the root element for framework-specific styling:
+
+```tsx
+<ProvexBuy wallet={wallet} className="my-custom-buy-widget" />
+```
+
+### Data Attributes
+
+All elements use `data-provex-*` attributes for CSS targeting:
+
+```css
+[data-provex-button="buy"] { ... }
+[data-provex-input="amount"] { ... }
+[data-provex-phase="browse"] { ... }
+[data-provex-phase="committed"] { ... }
+[data-provex-phase="complete"] { ... }
+[data-provex-message="error"] { ... }
+[data-provex-message="validation"] { ... }
+```
+
+### Dark Mode
+
+The default stylesheet responds to `prefers-color-scheme: dark` automatically. To force a theme, override the CSS variables.
+
+## Configuration
+
+### ProvexConfig
+
+```ts
+interface ProvexConfig {
+  apiUrl: string   // Provex backend API URL
+  chain: Chain     // viem Chain object (from viem/chains)
+}
+```
+
+### ProvexProviderProps
+
+```ts
+interface ProvexProviderProps {
+  config: ProvexConfig
+  indexer: IndexerAdapter      // Data source (use createPonderAdapter())
+  queryClient?: QueryClient    // Optional external React Query client
+  children: React.ReactNode
+}
+```
+
+### BuyProps
+
+```ts
+interface BuyProps {
+  wallet: WalletAdapter
+  onIntentSignaled?: (intentHash: string, chainId: number) => void
+  onComplete?: (intentHash: string, chainId: number) => void
+  paymentMethods?: ProviderKey[]
+  className?: string
+  style?: React.CSSProperties
+  theme?: ProvexTheme
+}
+```
+
+## License
+
+Private — Provex Protocol