@provex/react 1.6.2 → 1.7.0-rc.20260522201545.020a3eb

package/dist/wagmi.d.cts

@@ -1,4 +1,4 @@
-import { j as WalletAdapter, s as ProvexProviderProps, o as ProvexTheme } from './ProvexProvider-BQ5vZkHO.cjs';
+import { j as WalletAdapter, s as ProvexProviderProps, o as ProvexTheme } from './ProvexProvider-eG_i0Yz3.cjs';
 import { PublicClient } from 'viem';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React__default from 'react';

package/dist/wagmi.d.ts

@@ -1,4 +1,4 @@
-import { j as WalletAdapter, s as ProvexProviderProps, o as ProvexTheme } from './ProvexProvider-BQ5vZkHO.js';
+import { j as WalletAdapter, s as ProvexProviderProps, o as ProvexTheme } from './ProvexProvider-eG_i0Yz3.js';
 import { PublicClient } from 'viem';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React__default from 'react';

package/dist/wagmi.js

@@ -1,4 +1,4 @@
-import { ProvexProvider, ProvexBuy } from './chunk-VWWANYB2.js';
+import { ProvexProvider, ProvexBuy } from './chunk-NAGOACEK.js';
 import { useMemo } from 'react';
 import { useAccount, useWalletClient, useConfig } from 'wagmi';
 import { getPublicClient } from 'wagmi/actions';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@provex/react",
-  "version": "1.6.2",
+  "version": "1.7.0-rc.20260522201545.020a3eb",
   "description": "Portable React buy-flow component and hooks for the Provex protocol",
   "type": "module",
   "repository": {
@@ -25,10 +25,12 @@
     "./styles": "./dist/styles/default.css"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
+  "license": "MIT",
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "scripts": {
@@ -40,9 +42,9 @@
   },
   "dependencies": {
     "@ponder/client": "^0.16.0",
-    "@provex/abis": "1.6.2",
-    "@provex/utils": "1.6.2",
-    "@valve-tech/wallet-adapter": "^0.13.0"
+    "@provex/abis": "1.7.0-rc.20260522201545.020a3eb",
+    "@provex/utils": "1.7.0-rc.20260522201545.020a3eb",
+    "@valve-tech/wallet-adapter": "^0.15.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.0.0",

package/skills/react-integration/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: react-integration
+description: Use when integrating `@provex/react` — when adding the Provex buy flow to a React app, when choosing between the drop-in widget / composable phases / headless hook / framework-agnostic core, when mounting ProvexProvider, when implementing WalletAdapter against a wagmi/Privy/Walletkit/raw-viem wallet stack, when styling the widget via CSS variables or theme prop, or when handling user-rejection vs real-revert error paths. Covers the four-layer API choice, the canonical provider mount order, the WalletAdapter contract, and the dismiss-vs-fail terminal pattern that's central to the UX.
+---
+
+# `@provex/react` Integration
+
+The Provex buy flow SDK — a state machine, a set of hooks, and three layers of UI on top. Framework-agnostic core; React surface layered on top.
+
+## Four layers — pick the highest that fits
+
+| Layer | Export | Use when |
+|---|---|---|
+| 3 (highest) | `<ProvexBuy>` / `<ProvexBuyWagmi>` | You want a drop-in widget; zero UI code |
+| 2 | `<ProvexBuyProvider>` + `<BrowsePhase>` / `<CommittedPhase>` / `<ProvingPhase>` / `<CompletePhase>` | You want custom layout but our state machine |
+| 1 | `useProvexBuy()` | You want fully custom UI; we manage state |
+| 0 (lowest) | `createProveXClient()` | You're outside React (Node, smart account, relayer) |
+
+Start at layer 3; drop down only when you outgrow the abstraction.
+
+## Mount order (non-negotiable)
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { WagmiProvider } from 'wagmi'              // only if using wagmi
+import { ZKTLSProvider } from '@provex/extension-react'
+import { ProvexProvider } from '@provex/react'
+import { createPonderAdapter } from '@provex/indexer-client'
+
+const queryClient = new QueryClient()
+const indexer = createPonderAdapter()
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <WagmiProvider config={wagmiConfig}>
+        <ZKTLSProvider>
+          <ProvexProvider
+            config={{ apiUrl: 'https://app.provex.com', chain: pulsechain }}
+            indexer={indexer}
+          >
+            <BuyPage />
+          </ProvexProvider>
+        </ZKTLSProvider>
+      </WagmiProvider>
+    </QueryClientProvider>
+  )
+}
+```
+
+Order rationale:
+- `QueryClientProvider` outermost — many hooks need React Query.
+- `WagmiProvider` next — only needed for the wagmi subpath; skip if you're wagmi-free.
+- `ZKTLSProvider` — proof generation context lives above `ProvexProvider` because the SDK pulls it from inside.
+- `ProvexProvider` — the state machine container.
+
+## WalletAdapter contract
+
+The SDK consumes any object satisfying:
+
+```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 — without it, the SDK falls back to a public viem client built from `config.chain`.
+
+### Bridges per wallet stack
+
+| Stack | Bridge |
+|---|---|
+| wagmi | `useWagmiWallet()` from `@provex/react` |
+| Privy | wrap Privy's `sendTransaction` |
+| Walletkit | wrap the active WC session |
+| raw viem | wrap a `WalletClient` |
+| Safe SDK / multisig | use the layer-0 `createProveXClient()` with `prepare`-only methods |
+
+## Drop-in widget — Layer 3
+
+```tsx
+import { ProvexBuy } from '@provex/react'
+import '@provex/react/styles'
+
+<ProvexBuy
+  wallet={wallet}
+  onIntentSignaled={(intentHash, chainId) => track('Locked', { intentHash })}
+  onComplete={(intentHash, chainId) => navigate('/done')}
+  paymentMethods={['venmo', 'zelle']}  // optional filter
+/>
+```
+
+With wagmi:
+
+```tsx
+import { ProvexBuyWagmi } from '@provex/react'
+<ProvexBuyWagmi onComplete={...} />
+```
+
+`ProvexBuyWagmi` reads the connected account from wagmi context — no `wallet` prop needed.
+
+## Composable phases — Layer 2
+
+```tsx
+import { ProvexBuyProvider, BrowsePhase, CommittedPhase, ProvingPhase, CompletePhase } from '@provex/react'
+
+<ProvexBuyProvider wallet={wallet} onComplete={handleDone}>
+  <div className="my-layout">
+    <Header />
+    <BrowsePhase />
+    <CommittedPhase />
+    <ProvingPhase />
+    <CompletePhase />
+    <Footer />
+  </div>
+</ProvexBuyProvider>
+```
+
+Only one phase renders at a time based on internal state — they're already mutually exclusive.
+
+## Headless hook — Layer 1
+
+```tsx
+import { useProvexBuy } from '@provex/react'
+
+function CustomBuy({ wallet }) {
+  const {
+    phase,                                // 'browse' | 'committed' | 'proving' | 'complete'
+    amount, setAmount,
+    deposits, selectedDeposit,
+    rate, rateDisplay,
+    canSubmit, validationMessage,
+    submitOrder, confirmPayment, reset,
+  } = useProvexBuy({ wallet })
+  // Render your own UI
+}
+```
+
+## Framework-agnostic core — Layer 0
+
+```ts
+import { createProveXClient } from '@provex/react'
+import { pulsechain } from 'viem/chains'
+
+const client = createProveXClient({ chain: pulsechain, wallet })
+
+// Standard call (signs and sends)
+const { intentHash } = await client.signalIntent({ ... })
+
+// Prepare-only (for Safe, Privy, multisigs, relayers)
+const prepared = await client.addFunds.prepare({ depositId: 1n, amount: 500_000000n })
+// → { to, data, value, chainId } — hand to any signer
+```
+
+Every write method has a `.prepare(...)` variant returning the calldata without signing. Use this for smart-account batching, EIP-7702 relays, or any flow where the signing happens outside the SDK.
+
+## Specialized hooks
+
+| Hook | Returns | Use case |
+|---|---|---|
+| `useDeposits` | Available deposits filtered by token + payment method | Browse phase |
+| `useSignalIntent` | `startOrder(...)`, status, message | Buyer commits |
+| `useReputation` | Tier and cooldown for an address | Reputation badge |
+| `useReputationLimits` | Effective cap, cooldown remaining | Pre-commit limit display |
+| `useProtocolFees` | Fee info from on-chain Orchestrator | Fee preview |
+| `usePayeeDetails` | Intent + payee info | Verification flow |
+| `useWagmiWallet` | `WalletAdapter \| null` from wagmi | Adapt wagmi to our interface |
+
+## Dismiss vs. fail — terminal contract
+
+The SDK distinguishes two terminal states for transactions, and they look very different to the user:
+
+| Terminal | When | Effect |
+|---|---|---|
+| `dismissTx` | User rejected the wallet popup | Silent — strip drops, no toast. The user knows they cancelled. |
+| `failTx` | Real revert / RPC error | Strip lingers 10s with the error reason; toast surfaces the friendly message |
+
+If you wire `WriteHookParams` for custom write sites, branch on `isUserRejectionError` before deciding which terminal to call. Conflating the two produces a doom-toast on every accidental wallet-popup-X-out, which trains users to ignore real errors.
+
+## Styling
+
+Import the baseline stylesheet:
+
+```tsx
+import '@provex/react/styles'
+```
+
+Override CSS variables on `[data-provex-root]`:
+
+```css
+[data-provex-root] {
+  --provex-color-primary: #00d4aa;
+  --provex-color-bg: #0f0f23;
+  --provex-color-text: #ffffff;
+  --provex-border-radius: 12px;
+  --provex-max-width: 480px;
+}
+```
+
+Or pass theme overrides as a prop:
+
+```tsx
+<ProvexBuy
+  wallet={wallet}
+  theme={{ accent: '#00d4aa', background: '#0f0f23', text: '#ffffff', radius: '12px' }}
+/>
+```
+
+Data attributes (`data-provex-*`) are set on every element for fine-grained CSS targeting. Full reference in the package README.
+
+## Chain support
+
+| Chain | ID | Status |
+|---|---|---|
+| PulseChain | `369` | primary — production protocol |
+| Base | `8453` | peer-trade contracts only |
+
+Use `pulsechain` from `viem/chains` for the canonical setup. The SDK uses `@provex/utils/contracts` internally for address resolution — you don't need to thread addresses through props.
+
+## Common pitfalls
+
+- **Mounting `WagmiProvider` and `WagmiProvexProvider` from different package versions.** Yarn workspaces can dup-bundle wagmi when peer ranges don't align; `WagmiProviderNotFoundError` is the fingerprint. Add wagmi to `resolve.dedupe` if it happens.
+- **Forgetting `QueryClientProvider` above `ProvexProvider`.** Hooks throw "no QueryClient" — non-obvious because the message doesn't mention Provex.
+- **Conflating null indexer values with terminal state.** Intent timing fields can be `null` for a few seconds after submission. Use the helpers in `@provex/utils/intent/timing`.
+- **Using Chakra's `Tooltip` instead of `@provex/components`' `Tooltip`.** The former misbehaves on mobile; this is a recurring footgun.
+
+## When NOT to import from this package
+
+- **You're on Node-only / serverless** → use the layer-0 `createProveXClient()` (also exported from this package) and skip React entirely.
+- **You only need on-chain reads, no buy flow** → use `@provex/abis` + viem directly.
+- **You want indexer queries without the buy state machine** → use `@provex/indexer-client` hooks standalone.