@pafi-dev/app-ui 0.3.1

package/README.md

@@ -0,0 +1,584 @@
+# @pafi-dev/app-ui
+
+[![npm](https://img.shields.io/npm/v/@pafi-dev/app-ui)](https://www.npmjs.com/package/@pafi-dev/app-ui)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+Mobile SDK for PAFI-integrated issuer apps. Provides a thin HTTP client,
+embedded Privy wallet management, and React hooks for React Native / Expo
+apps to integrate claim (mint), redeem (burn), and PAFI Web handoff flows.
+
+Issuer app developers do not need to understand blockchain, wallets, or
+cryptographic signing — the SDK handles everything.
+
+### Platform support
+
+| Platform | Supported | Notes |
+| --- | --- | --- |
+| iOS | ✅ | Requires Xcode 16+ |
+| Android | ✅ | Requires API 26+ |
+| Web | ❌ | Not supported — SDK depends on native Privy embedded wallet |
+
+## Requirements
+
+- Node.js ≥ 18
+- TypeScript ≥ 5.0
+- Expo SDK 52+ (SDK 54 recommended)
+- React Native ≥ 0.73.0
+
+## Install
+
+```bash
+pnpm add @pafi-dev/app-ui
+```
+
+### Peer dependencies
+
+Issuer apps must install the following as peer dependencies:
+
+| Package | Version | Note |
+| --- | --- | --- |
+| `react` | `^18.0.0 \|\| ^19.0.0` | React 19 recommended for Expo 54+ |
+| `react-native` | `>=0.73.0` | |
+| `expo` | `>=52.0.0` | Expo SDK 54 recommended |
+| `@privy-io/expo` | `^0.64.0 \|\| ^0.65.0` | Wallet management + signing |
+| `react-native-get-random-values` | `>=1.0.0` | Required polyfill for `crypto.getRandomValues` |
+
+> **No web3 libraries required.** The SDK does not depend on `viem`, `ethers`, `permissionless`, or any other blockchain library. The backend builds all UserOps and returns EIP-712 typed data; the mobile SDK signs it via `eth_signTypedData_v4`.
+
+## At a glance
+
+```tsx
+import { PafiProvider, usePafiAuth, usePafiUser, usePafiClaim } from "@pafi-dev/app-ui";
+
+// ── App root ──────────────────────────────────────────────────────
+export default function App() {
+  return (
+    <PafiProvider
+      baseUrl="https://api.example.com"
+      getIssuerAccessToken={getIssuerAccessToken}
+    >
+      <Main />
+    </PafiProvider>
+  );
+}
+
+// ── Main screen ───────────────────────────────────────────────────
+function Main() {
+  const { login, isAuthenticated, walletAddress } = usePafiAuth();
+  const { totalBalance, offChainBalance, onChainBalance, gasFeeUsdt } = usePafiUser();
+  const { claim, isSubmitting } = usePafiClaim();
+
+  if (!isAuthenticated) {
+    return <Button onPress={login} title="Login" />;
+  }
+
+  return (
+    <>
+      <Text>Wallet: {walletAddress}</Text>
+      <Text>Total Balance: {totalBalance} PT</Text>
+      <Text>Claimable: {offChainBalance} PT</Text>
+      <Text>On-chain: {onChainBalance} PT</Text>
+      <Button
+        onPress={() => claim({ amount: offChainBalance! })}
+        title={isSubmitting ? "Claiming..." : "Claim"}
+        disabled={isSubmitting}
+      />
+    </>
+  );
+}
+```
+
+That's the entire integration. No wallets, no UserOps, no signing.
+
+## What you get
+
+| Export | Type | Description |
+| --- | --- | --- |
+| `PafiProvider` | Component | Root provider — wraps PrivyProvider + PafiClient context |
+| `usePafiAuth` | Hook | Login / logout with embedded Privy wallet + SIWE |
+| `usePafiUser` | Hook | Balances (off-chain, on-chain, total), pools, gas fee |
+| `usePafiClaim` | Hook | 2-step claim (mint): prepare → sign → submit |
+| `usePafiRedeem` | Hook | 2-step redeem (burn): prepare → sign → submit |
+| `usePafiRedemptionPreview` | Hook | v1.6 redemption policy preview + client-side validation |
+| `usePafiDelegation` | Hook | EIP-7702 delegation (handled automatically during claim/redeem) |
+| `usePafiClaimStatus` | Hook | Poll for claim (mint) transaction status |
+| `usePafiRedeemStatus` | Hook | Poll for redeem (burn) transaction status |
+| `usePafiTransactions` | Hook | Paginated transaction history |
+| `usePafiEmailLink` | Hook | Link email to Privy wallet (for PAFI Web handoff) |
+| `usePafiWebHandoff` | Hook | Open PAFI Web for swap / perp deposit |
+| `useTos` | Hook | Observe issuer-owned TOS acceptance state |
+| `TosGate` | Component | Conditionally renders children based on TOS acceptance |
+| `PafiClient` | Class | Thin HTTP client (use directly if not using React) |
+| `PafiApiError` | Class | Typed error for all backend responses |
+| `PafiTosDeclinedError` | Class | Thrown when user declines the TOS modal |
+| `PafiTosRequiredError` | Class | Thrown when claim/redeem is called before TOS acceptance |
+
+## The login flow
+
+The issuer app calls `login()` — one function, no arguments. Internally:
+
+```
+login()
+  ├── 1. Privy custom auth         → silent, returns privyUserId (no modal)
+  ├── 2. TOS check / accept        → uses privyUserId, built-in modal if not yet accepted
+  ├── 3. Wait for wallet ready     → reactive, max 30s timeout (creates embedded wallet)
+  ├── 4. GET /auth/nonce           → backend returns random nonce
+  ├── 5. buildSiweMessage(nonce)   → SDK builds EIP-4361 message
+  ├── 6. wallet.signMessage(siwe)  → Privy signs (personal_sign)
+  ├── 7. POST /auth/login          → backend verifies → JWT
+  └── 8. client.setJwt(token)      → authenticated
+```
+
+TOS is checked **before** wallet creation because `privyUserId` is available
+immediately after Privy custom auth, while the embedded wallet is created
+asynchronously. This avoids blocking the user behind both flows simultaneously.
+
+```tsx
+const { login, logout, isAuthenticated, isReady, walletAddress, error } = usePafiAuth();
+
+// Block UI until Privy SDK is initialized
+if (!isReady) return <ActivityIndicator />;
+
+// One call — SDK handles everything
+<Button onPress={login} title="Login" />
+```
+
+`logout()` calls `POST /auth/logout` to revoke the session server-side before
+clearing the local JWT and Privy session.
+
+## Terms of Service (TOS)
+
+TOS is an issuer-owned legal state. The SDK ships a built-in modal and orchestrates
+the flow; the issuer backend is the source of truth for whether a user has accepted
+a given TOS version. Claim, redeem, and delegation actions throw
+`PafiTosRequiredError` until TOS is accepted.
+
+The issuer backend must host two endpoints:
+
+```
+GET  /tos/status?userId={privyUserId}    → { accepted: boolean, version: string }
+POST /tos/accept  { privyUserId, version } → { success: boolean }
+```
+
+```tsx
+<PafiProvider
+  baseUrl="https://api.example.com"
+  getIssuerAccessToken={getIssuerAccessToken}
+  tos={{
+    tosBaseUrl: "https://api.example.com",
+    version: "v1.0",
+    contentUrl: "https://api.example.com/legal/tos",
+    title: "Terms of Service",
+    branding: { accentColor: "#FF6B35" },
+    onDeclined: async () => {
+      // Optional issuer policy, e.g. navigate away.
+    },
+  }}
+>
+  <TosGate fallback={<ActivityIndicator />} blocked={<TosRequired />}>
+    <PafiPoweredScreen />
+  </TosGate>
+</PafiProvider>
+```
+
+The TOS check runs automatically inside `login()` (after Privy custom auth,
+before wallet creation). If `tos` is omitted, the gate is disabled and all
+operations proceed without a TOS check.
+
+```tsx
+const { isAccepted, isChecking, error, retry } = useTos();
+```
+
+The SDK does not hard-code any TOS copy or URL — `contentUrl` is owned by the
+issuer and rendered as a tappable link inside the built-in modal.
+
+## The claim flow
+
+### One-shot (no confirmation screen)
+
+```tsx
+const { claim, isSubmitting, error } = usePafiClaim();
+
+// One call — prepare + sign + submit
+const { userOpHash } = await claim({ amount: "1000000000000000000" });
+```
+
+### With confirmation screen
+
+```tsx
+const { prepare, confirm, preparedData, isPreparing, isSubmitting } = usePafiClaim();
+
+// Step 1 — get a summary for the UI
+await prepare({ amount: "1000000000000000000" });
+
+// Step 2 — show the user what they'll receive
+// preparedData.summary: { amount, gasFee, netPtMinted, expiresAt }
+<Text>Minting: {preparedData.summary.amount} PT</Text>
+<Text>Gas fee: {preparedData.summary.gasFee} PT</Text>
+<Text>Net: {preparedData.summary.netPtMinted} PT</Text>
+
+// Step 3 — user confirms → SDK signs + submits
+<Button onPress={() => confirm(preparedData.lockId)} title="Confirm" />
+```
+
+### amount field
+
+`amount` is a base-unit string (18 decimals). Pass `offChainBalance` from
+`usePafiUser()` to claim the full claimable balance:
+
+```tsx
+const { offChainBalance } = usePafiUser();
+claim({ amount: offChainBalance! });
+```
+
+## The redeem flow
+
+Redeem mirrors the claim flow — it burns on-chain PT and credits off-chain points.
+
+### One-shot
+
+```tsx
+const { redeem, isSubmitting, error } = usePafiRedeem();
+
+const { userOpHash } = await redeem({ amount: "1000000000000000000" });
+```
+
+### With confirmation screen
+
+```tsx
+const { prepare, confirm, preparedData, isPreparing, isSubmitting } = usePafiRedeem();
+
+// Step 1 — prepare
+await prepare({ amount: "1000000000000000000" });
+
+// Step 2 — show summary
+// preparedData.summary: { amount, gasFee, netPtBurned, expiresAt }
+<Text>Burning: {preparedData.summary.amount} PT</Text>
+
+// Step 3 — user confirms
+<Button onPress={() => confirm(preparedData.lockId)} title="Confirm" />
+```
+
+### Shortfall helper
+
+For voucher redemption where the user may need to burn on-chain PT to cover a shortfall:
+
+```tsx
+const { redeem, calculateShortfall } = usePafiRedeem();
+const { offChainBalance } = usePafiUser();
+
+const shortfall = calculateShortfall(voucherCostWei, offChainBalance!);
+if (shortfall !== "0") {
+  await redeem({ amount: shortfall });
+}
+```
+
+## Email linking
+
+Email linking is deferred — users can view balances and claim immediately
+after login. Email is only linked when the user first needs PAFI Web access
+(e.g., Swap / Invest), and only once.
+
+```tsx
+const { sendCode, confirmCode, status, isEmailLinked } = usePafiEmailLink();
+
+// Gate swap behind email linking
+const handleSwap = async () => {
+  if (!isEmailLinked) {
+    await sendCode(userEmail);   // Privy sends OTP
+    showOtpModal();              // Show your OTP input UI
+    return;
+  }
+  // Proceed to swap
+};
+
+// After user enters OTP
+const handleOtpSubmit = async (code: string) => {
+  await confirmCode({ code, email: userEmail });
+  // Email linked — proceed to swap
+};
+```
+
+| `status` | Meaning |
+| --- | --- |
+| `idle` | Not started |
+| `sending` | Sending OTP to the user's email |
+| `awaiting_code` | OTP sent, waiting for user input |
+| `confirming` | Verifying OTP code with Privy |
+| `linked` | Email successfully linked |
+| `error` | Something went wrong — check `error` |
+
+## Transaction history
+
+Paginated transaction history with infinite scroll support:
+
+```tsx
+const { transactions, isLoading, hasMore, loadMore, refresh } = usePafiTransactions();
+
+// Render list
+<FlatList
+  data={transactions}
+  renderItem={({ item }) => (
+    <Text>{item.type}: {item.amount} PT — {item.status}</Text>
+  )}
+  onEndReached={() => hasMore && loadMore()}
+  refreshing={isLoading}
+  onRefresh={refresh}
+/>
+```
+
+## PAFI Web handoff
+
+Open PAFI Web so the user can swap, deposit, or manage their assets.
+The SDK provides the URL — the issuer app decides when and how to open it.
+
+```tsx
+const { openPafiWeb, webUrl } = usePafiWebHandoff();
+
+// Open PAFI Web homepage
+const url = await openPafiWeb();
+await Linking.openURL(url);
+```
+
+## Transaction polling
+
+After a claim or redeem, the on-chain execution is asynchronous. You can use the dedicated status hooks to poll until the transaction reaches a terminal status:
+
+```tsx
+import { usePafiClaimStatus } from "@pafi-dev/app-ui";
+
+// lockId comes from the prepare() response, NOT userOpHash
+const { status, txHash, isLoading, error } = usePafiClaimStatus(lockId);
+
+if (status === "MINTED") {
+  console.log("Claim successful! txHash:", txHash);
+}
+```
+
+| Status | Meaning |
+| --- | --- |
+| `PENDING` | Tx submitted, awaiting on-chain confirmation |
+| `MINTED` | Mint event indexed — balance deducted from ledger |
+| `EXPIRED` | Prepare TTL expired before submit, or consent expired |
+| `FAILED` | On-chain tx reverted |
+
+## Error handling
+
+All backend errors are wrapped in `PafiApiError`:
+
+```ts
+import { PafiApiError } from "@pafi-dev/app-ui";
+
+try {
+  await claim({ amount });
+} catch (err) {
+  if (err instanceof PafiApiError) {
+    console.log(err.code);        // "INSUFFICIENT_BALANCE", "POLICY_CAP_EXCEEDED", …
+    console.log(err.httpStatus);  // 400, 401, 422, 500, …
+    console.log(err.safeToRetry); // false on claim errors — do NOT retry automatically
+  }
+}
+```
+
+### Retry strategy (built into `PafiClient`)
+
+| Condition | Action |
+| --- | --- |
+| `5xx` + `safeToRetry=true` | Retry up to 3× with exponential backoff (500ms base, 5s cap, ±25% jitter) |
+| `5xx` + `safeToRetry=false` | **Never** retry — tx may be in mempool |
+| `4xx` | Never retry — client error |
+| `401` | Clear JWT + throw — app must call `login()` again |
+| Network error | Retry with same backoff (transient) — **except** `/claim/submit`, `/redeem/submit`, `/delegate/submit`: throw immediately (`safeToRetry=false`) |
+
+## `PafiConfig` reference
+
+```ts
+interface PafiConfig {
+  /** Issuer backend URL. Captured at mount — see "Config immutability" below. */
+  baseUrl: string;
+  /** Issuer JWT callback for Privy custom auth */
+  getIssuerAccessToken: () => Promise<string>;
+  /** Chain ID (default: 8453 — Base mainnet) */
+  chainId?: number;
+  /** Point token contract address */
+  pointTokenAddress?: string;
+  /** PAFI Web URL for swap/invest handoff */
+  pafiWebUrl?: string;
+  /** Custom fetch for testing / RN polyfills. Captured at mount. */
+  fetchFn?: typeof fetch;
+  /** Wallet mode. Default is "embedded". Note: only "embedded" is supported in production at this time. */
+  walletMode?: "embedded" | "external" | "both";
+  /** Additional Privy config overrides */
+  privyConfig?: Partial<PrivyClientConfig>;
+  /** Optional issuer-owned TOS gate (built-in modal + Issuer BE source of truth) */
+  tos?: TosConfig;
+}
+```
+
+### Config immutability
+
+`baseUrl` and `fetchFn` are captured **once at mount** when `PafiClient` is
+constructed. Mutating them on the `PafiProvider` after mount has no effect —
+the underlying client keeps using the original values. Re-mount the provider
+(e.g., via `key={baseUrl}`) if you need to switch backends at runtime.
+
+This is intentional: the JWT lifecycle is tied to a specific backend, and
+swapping `baseUrl` mid-session would silently leak the JWT to a different host.
+
+## Architecture constraints
+
+**Mobile never builds UserOps or batch calls.** The backend is the single
+source of truth for UserOp construction. Mobile sends `{ amount }`, receives
+EIP-712 typed data, the SDK signs it via `eth_signTypedData_v4` internally,
+and the backend handles all blockchain complexity (UserOp assembly, paymaster,
+bundler submission).
+
+**No runtime dependency on blockchain packages.** `@pafi-dev/core`,
+`@pafi-dev/issuer`, `viem`, and `permissionless` are NOT in dependencies.
+No ABI encoding, no RPC calls, no contract reads happen in the mobile bundle.
+
+**JWT is stored in memory only.** The SDK does not persist the JWT to disk.
+If your app needs to survive process restarts without re-login, persist
+`token` from `LoginResponse` yourself (e.g. `expo-secure-store`) and call
+`client.setJwt()` on startup.
+
+## Exports
+
+```ts
+import {
+  // Provider + context
+  PafiProvider,
+  type PafiProviderProps,
+  usePafiClient,
+
+  // Hooks
+  usePafiAuth,
+  type UsePafiAuthReturn,
+  usePafiUser,
+  type UsePafiUserReturn,
+  usePafiClaim,
+  type UsePafiClaimReturn,
+  usePafiRedeem,
+  type UsePafiRedeemReturn,
+  usePafiRedemptionPreview,
+  type UsePafiRedemptionPreviewReturn,
+  usePafiDelegation,
+  type UsePafiDelegationReturn,
+  usePafiClaimStatus,
+  type UsePafiClaimStatusReturn,
+  usePafiRedeemStatus,
+  type UsePafiRedeemStatusReturn,
+  usePafiTransactions,
+  type UsePafiTransactionsReturn,
+  usePafiEmailLink,
+  type UsePafiEmailLinkReturn,
+  type EmailLinkStatus,
+  usePafiWebHandoff,
+  type UsePafiWebHandoffReturn,
+
+  // TOS
+  TosGate,
+  useTos,
+  PafiTosDeclinedError,
+  PafiTosRequiredError,
+  type TosConfig,
+  type TosBrandingConfig,
+  type TosStatus,
+  type TosGateProps,
+  type UseTosReturn,
+  type TosStatusResponse,
+  type TosAcceptResponse,
+
+  // HTTP client
+  PafiClient,
+  PafiApiError,
+  type PafiErrorType,
+  type PafiErrorPayload,
+  type PafiErrorMeta,
+  type PafiErrorResponse,
+
+  // Config types
+  type PafiConfig,
+  type PafiClientConfig,
+
+  // Wire types — auth
+  type NonceResponse,
+  type LoginRequest,
+  type LoginResponse,
+
+  // Wire types — user
+  type UserResponse,
+  type PoolKey,
+  type PoolsResponse,
+
+  // Wire types — claim (mint)
+  type PrepareClaimRequest,
+  type PrepareClaimResponse,
+  type ClaimSummary,
+  type SubmitClaimRequest,
+  type SubmitClaimResponse,
+  type ClaimStatusResponse,
+
+  // Wire types — redeem (burn)
+  type PrepareRedeemRequest,
+  type PrepareRedeemResponse,
+  type RedeemSummary,
+  type SubmitRedeemRequest,
+  type SubmitRedeemResponse,
+  type RedeemStatusResponse,
+
+  // Wire types — redemption policy (v1.6)
+  type RedemptionDenialCode,
+  type RedemptionClientValidationCode,
+  type RedemptionPreviewResponse,
+  type RedemptionEvaluateRequest,
+  type RedemptionEvaluateResponse,
+  type RedemptionDenial,
+
+  // Wire types — delegation
+  type DelegationStatusResponse,
+  type PrepareDelegationRequest,
+  type PrepareDelegationResponse,
+  type SubmitDelegationRequest,
+  type SubmitDelegationResponse,
+
+  // Wire types — web handoff
+  type WebHandoffResponse,
+
+  // Shared types
+  type EIP712TypedData,
+  type TransactionRecord,
+  type TransactionsResponse,
+} from "@pafi-dev/app-ui";
+```
+
+## Tests
+
+```bash
+pnpm --filter @pafi-dev/app-ui test
+```
+
+All tests are hermetic — no network, no on-chain state required.
+
+## Changelog
+
+### 0.2.1
+
+- Added `usePafiClaimStatus` and `usePafiRedeemStatus` for transaction polling
+- Added `usePafiTransactions` for paginated transaction history
+- Added `usePafiRedemptionPreview` for v1.6 redemption policy preview
+- Added `TosGate` component and `useTos` hook (replaces the wallet-consent
+  prototype from earlier drafts — the consent API is no longer exported)
+- EIP-712 `signTypedData` for all signing (replaced `personal_sign`)
+- Added EIP-7702 v normalization (27/28 → 0/1 yParity)
+
+### 0.2.0
+
+- Initial public release
+- `PafiProvider`, `usePafiAuth`, `usePafiUser`, `usePafiClaim`, `usePafiRedeem`
+- `usePafiDelegation`, `usePafiEmailLink`, `usePafiWebHandoff`
+- `PafiClient` HTTP client with retry + exponential backoff
+
+## License
+
+Apache-2.0