@pollar/react 0.6.0 → 0.7.0

package/README.md

@@ -1,6 +1,10 @@
 # @pollar/react
 
-React bindings for [Pollar](https://pollar.xyz) — drop-in authentication UI and hooks for Stellar-based applications.
+React bindings for [Pollar](https://pollar.xyz) — drop-in authentication UI, transaction modals, and hooks for
+Stellar-based applications.
+
+> **0.7.0 is a breaking change.** The context's session is now `PollarPersistedSession | null` and PII has moved to
+> `client.getUserProfile()`. Read the [CHANGELOG](../../CHANGELOG.md) before upgrading.
 
 ## Installation
 
@@ -12,7 +16,7 @@ pnpm add @pollar/react @pollar/core
 yarn add @pollar/react @pollar/core
 ```
 
-**Peer dependencies:** `react >= 18`, `react-dom >= 18`
+**Peer dependencies:** `react >= 18`, `react-dom >= 18`. Node ≥ 20 in toolchains.
 
 ## Quick Start
 
@@ -35,7 +39,7 @@ export default function App({ children }: { children: React.ReactNode }) {
 import { usePollar } from '@pollar/react';
 
 export function Profile() {
-  const { isAuthenticated, session, login, logout } = usePollar();
+  const { isAuthenticated, walletAddress, login, logout, getClient } = usePollar();
 
   if (!isAuthenticated) {
     return (
@@ -45,9 +49,13 @@ export function Profile() {
     );
   }
 
+  // PII (email, name, avatar, providers) lives in memory only — fetch it from the client.
+  const profile = getClient().getUserProfile();
+
   return (
     <div>
-      <p>Wallet: {session?.wallet?.publicKey}</p>
+      <p>Wallet: {walletAddress}</p>
+      <p>Email: {profile?.mail}</p>
       <button onClick={logout}>Sign out</button>
     </div>
   );
@@ -64,34 +72,94 @@ Context provider that initialises the Pollar client and makes it available to ch
 <PollarProvider
   config={{
     apiKey: 'your-api-key',
-    baseUrl: 'https://sdk.api.pollar.xyz', // optional
-    stellarNetwork: 'testnet',             // optional, default: 'testnet'
+    baseUrl: 'https://sdk.api.pollar.xyz',  // optional
+    stellarNetwork: 'testnet',              // optional, default: 'testnet'
+    // 0.7.0 options threaded straight through to PollarClient:
+    storage,                                // optional, RN apps inject this
+    keyManager,                             // optional, autodetects on web
+    walletAdapter,                          // optional, external wallet stack
+    deviceLabel: 'iPhone — Safari',         // optional, shown in SessionsModal
+    onStorageDegrade,                       // optional, telemetry hook
   }}
+  styles={{ /* optional style overrides */ }}
+  adapters={{ /* optional named adapter set */ }}
 >
   {children}
 </PollarProvider>
 ```
 
-| Prop     | Type                | Required | Description                              |
-| -------- | ------------------- | -------- | ---------------------------------------- |
-| `config` | `PollarClientConfig`| Yes      | Configuration passed to `PollarClient`   |
+| Prop       | Type                | Required | Description                                                                |
+| ---------- | ------------------- | -------- | -------------------------------------------------------------------------- |
+| `config`   | `PollarClientConfig`| Yes      | Configuration passed verbatim to `PollarClient`                            |
+| `styles`   | `PollarStyles`      | No       | Per-app style overrides; merged on top of `appConfig.styles` from the API   |
+| `adapters` | `PollarAdapters`    | No       | Named set of `PollarAdapter` objects (e.g. Trustless Work). See below       |
 
 ---
 
 ### `usePollar()`
 
-Returns the authentication context.
+Returns the full Pollar context. Every modal opener returned here renders an already-wired modal — no extra mounting
+needed.
 
 ```ts
 const {
-  session,          // PollarApplicationConfigContent | null
-  isLoading,        // boolean — true while a login flow is in progress
-  isAuthenticated,  // boolean — true when a valid session exists
-  login,            // (options: PollarLoginOptions) => void
-  logout,           // () => Promise<void>
+  // Session
+  isAuthenticated,        // boolean — true when a wallet public key is present
+  walletAddress,          // string — '' until authenticated
+  walletType,             // WalletId | null
+
+  // Client escape hatch
+  getClient,              // () => PollarClient — for getUserProfile(), listSessions(), …
+
+  // Auth
+  login,                  // (options: PollarLoginOptions) => void
+  logout,                 // () => void  (fire-and-forget; await getClient().logout() if you need the promise)
+  openLoginModal,         // () => void
+
+  // Sessions (new in 0.7.0)
+  openSessionsModal,      // () => void
+
+  // Transactions
+  tx,                     // TransactionState
+  buildTx,                // (operation, params, options?) => Promise<void>
+  signAndSubmitTx,        // (unsignedXdr: string) => Promise<void>
+  openTxModal,            // () => void
+
+  // Transaction history
+  txHistory,              // TxHistoryState
+  openTxHistoryModal,     // () => void
+
+  // Wallet balance
+  walletBalance,          // WalletBalanceState
+  refreshWalletBalance,   // () => Promise<void>
+  openWalletBalanceModal, // () => void
+
+  // Send / Receive
+  openSendModal,          // () => void
+  openReceiveModal,       // () => void
+
+  // Network
+  network,                // StellarNetwork — 'mainnet' | 'testnet'
+  setNetwork,             // (network: StellarNetwork) => void
+
+  // KYC (UI ready — backend coming soon)
+  openKycModal,           // (options?: { country?, level?, onApproved? }) => void
+
+  // Ramp (UI ready — backend coming soon)
+  openRampModal,          // () => void
+
+  // App config / styles served by the Pollar API
+  appConfig,              // PollarConfig
+  styles,                 // PollarStyles
+
+  // Adapters (from PollarProvider props)
+  adapters,               // PollarAdapters | undefined
 } = usePollar();
 ```
 
+> **0.6.0 renames** — `transaction` → `tx`, `openTransactionModal` → `openTxModal`, `config` → `appConfig`,
+> `openRampWidget` → `openRampModal`, `refreshBalance` → `refreshWalletBalance`. Existing code on 0.5.x must update.
+
 #### Login options
 
 ```ts
@@ -102,17 +170,33 @@ login({ provider: 'github' });
 // Email OTP
 login({ provider: 'email', email: 'user@example.com' });
 
-// Stellar wallet
+// Built-in Stellar wallet adapters
 import { WalletType } from '@pollar/core';
 login({ provider: 'wallet', type: WalletType.FREIGHTER });
 login({ provider: 'wallet', type: WalletType.ALBEDO });
+
+// Any external adapter (e.g. Stellar Wallets Kit) when `walletAdapter` is set on config
+login({ provider: 'wallet', type: 'xbull' });
+login({ provider: 'wallet', type: 'lobstr' });
 ```
 
 ---
 
-### `<WalletButton>`
+### Components
+
+Every modal mounts itself when its `openXModal()` action is called. You don't need to render these directly — they're
+already wired inside `<PollarProvider>` — but they're exported in case you want to mount them yourself.
 
-Pre-built button component that opens the Pollar authentication modal.
+| Component                 | Purpose                                                                                                       |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `<WalletButton>`          | Drop-in button. Opens login when signed out; signed in, shows the wallet address with a dropdown (Send, Receive, balance, history, sign out). Inline arc spinner during in-progress transactions |
+| `<SendModal>`             | Full send flow: asset picker, amount, destination, inline build → sign → success/error                         |
+| `<ReceiveModal>`          | Wallet address as QR code with copy-to-clipboard (no external QR dependency required)                          |
+| `<TxHistoryModal>`        | Paginated transaction history with auto-fetch on open and stellar.expert explorer links                        |
+| `<WalletBalanceModal>`    | Stellar account balances with refresh button                                                                   |
+| `<SessionsModal>`         | **New in 0.7.0.** Lists every active refresh-token family for the current user with device metadata, marks the local session, per-row revoke, and a "Sign out everywhere" button |
+| `<KycModal>`              | Identity verification flow — provider selection + status polling *(UI preview — backend coming soon)*          |
+| `<RampWidget>`            | Buy/sell crypto — direction tabs, route comparison, payment instructions *(UI preview — backend coming soon)*  |
 
 ```tsx
 import { WalletButton } from '@pollar/react';
@@ -122,7 +206,89 @@ export function Header() {
 }
 ```
 
-The modal handles all login providers, loading states, and error feedback out of the box.
+---
+
+### Template components
+
+Every modal ships a pure presentational "template" companion — same name with a `Template` suffix. Use these when you
+want to swap the chrome but keep the data wiring from `usePollar()`.
+
+| Wrapper                | Template                       |
+| ---------------------- | ------------------------------ |
+| `<WalletButton>`       | `<WalletButtonTemplate>`       |
+| *(internal LoginModal)*| `<LoginModalTemplate>`         |
+| `<SendModal>`          | `<SendModalTemplate>`          |
+| `<ReceiveModal>`       | `<ReceiveModalTemplate>`       |
+| `<TransactionModal>`   | `<TransactionModalTemplate>`   |
+| `<TxHistoryModal>`     | `<TxHistoryModalTemplate>`     |
+| `<WalletBalanceModal>` | `<WalletBalanceModalTemplate>` |
+| `<KycModal>`           | `<KycModalTemplate>`           |
+| `<RampWidget>`         | `<RampWidgetTemplate>`         |
+| `<SessionsModal>`      | `<SessionsModalTemplate>`      |
+
+`<TxStatusView>` is the shared status component (build → sign → success/error) reused by `TransactionModal` and
+`SendModal`; it's exported on its own for consumers that want to embed the lifecycle elsewhere.
+
+---
+
+### Custom adapters
+
+The `adapters` prop on `<PollarProvider>` accepts any named set of `PollarAdapter` objects. Each adapter function
+receives params, returns an unsigned XDR, and Pollar handles signing and submission automatically.
+
+```tsx
+import type { PollarAdapter } from '@pollar/core';
+
+const trustlessWork: PollarAdapter = {
+  initialize: async (params) => ({ unsignedTransaction: '…' }),
+  release:    async (params) => ({ unsignedTransaction: '…' }),
+};
+
+<PollarProvider config={{ apiKey }} adapters={{ trustlessWork }}>
+  …
+</PollarProvider>
+```
+
+> **Renamed in 0.7.0** — `EscrowFn` → `AdapterFn` and `EscrowAdapter` → `PollarAdapter`. Runtime contract is
+> unchanged; rename your imports.
+
+#### `createPollarAdapterHook(key)`
+
+Factory that generates a fully-typed hook mirroring an adapter's API with automatic XDR signing built in:
+
+```ts
+import { createPollarAdapterHook } from '@pollar/react';
+
+const useTrustlessWork = createPollarAdapterHook<typeof trustlessWork>('trustlessWork');
+
+function MyComponent() {
+  const tw = useTrustlessWork();
+  await tw.initialize({ /* … */ });  // unsigned XDR is built, signed, and submitted automatically
+}
+```
+
+---
+
+### External wallet stacks (Stellar Wallets Kit, …)
+
+Pass a `WalletAdapterResolver` to `config.walletAdapter` so Pollar can reach wallets that live outside `@pollar/core`:
+
+```tsx
+import { PollarProvider } from '@pollar/react';
+import { stellarWalletsKit } from '@pollar/stellar-wallets-kit-adapter';
+import { Networks } from '@creit.tech/stellar-wallets-kit';
+
+<PollarProvider
+  config={{
+    apiKey: 'your-api-key',
+    walletAdapter: stellarWalletsKit({ network: Networks.PUBLIC }),
+  }}
+>
+  {children}
+</PollarProvider>
+```
+
+Then any `login({ provider: 'wallet', type: '<kit wallet id>' })` is routed through the kit.
 
 ---
 
@@ -150,11 +316,27 @@ import type {
   AuthModalProps,
   PollarConfig,
   PollarStyles,
+
+  // Template props
+  SendModalTemplateProps,
+  ReceiveModalTemplateProps,
+  TransactionModalTemplateProps,
+  TxStatusViewProps,
+  WalletBalanceModalTemplateProps,
+  SessionsModalTemplateProps,
+  SessionsState,
+
+  // Step unions
+  KycStep,
+  RampStep,
 } from '@pollar/react';
 ```
 
+The state types (`TransactionState`, `TxHistoryState`, `WalletBalanceState`, `NetworkState`, `AuthState`,
+`PollarPersistedSession`, `PollarUserProfile`, `SessionInfo`, …) are re-exported from `@pollar/core`.
+
 ---
 
 ## License
 
-MIT
+MIT

package/dist/index.css

@@ -1443,6 +1443,113 @@
   animation: pollar-pulse 1.4s ease-in-out infinite;
 }
 
+/* src/components/sessions-modal/SessionsModal.css */
+.pollar-sessions-modal {
+  max-width: 480px;
+}
+.pollar-sessions-list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.625rem;
+  max-height: 380px;
+  overflow-y: auto;
+  margin-bottom: 1rem;
+}
+.pollar-sessions-item {
+  display: grid;
+  grid-template-columns: 1fr auto;
+  grid-template-rows: auto auto;
+  column-gap: 0.75rem;
+  row-gap: 0.125rem;
+  background: var(--pollar-input-bg);
+  border: 1px solid var(--pollar-border);
+  border-radius: var(--pollar-card-border-radius, 10px);
+  padding: 0.75rem 1rem;
+}
+.pollar-sessions-item[data-current] {
+  border-color: var(--pollar-accent);
+}
+.pollar-sessions-item-main {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  min-width: 0;
+}
+.pollar-sessions-item-device {
+  font-size: 0.875rem;
+  font-weight: 500;
+  color: var(--pollar-text);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.pollar-sessions-item-badge {
+  font-size: 0.6875rem;
+  font-weight: 600;
+  padding: 2px 8px;
+  border-radius: 999px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  background: rgba(0, 93, 180, 0.12);
+  color: var(--pollar-accent);
+  white-space: nowrap;
+}
+.pollar-sessions-item-meta {
+  font-size: 0.75rem;
+  color: var(--pollar-muted);
+  display: flex;
+  gap: 0.5rem;
+  align-items: center;
+  grid-column: 1;
+}
+.pollar-sessions-item-revoke {
+  grid-row: 1 / 3;
+  grid-column: 2;
+  align-self: center;
+  background: none;
+  border: 1px solid var(--pollar-border);
+  border-radius: var(--pollar-buttons-border-radius, 6px);
+  padding: 6px 12px;
+  font-size: 0.75rem;
+  font-weight: 500;
+  color: var(--pollar-error-text, #dc2626);
+  cursor: pointer;
+  transition: background 150ms, border-color 150ms;
+}
+.pollar-sessions-item-revoke:hover:not(:disabled) {
+  background: var(--pollar-error-bg, #fef2f2);
+  border-color: var(--pollar-error-border, #fecaca);
+}
+.pollar-sessions-item-revoke:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+.pollar-sessions-actions {
+  display: flex;
+  justify-content: center;
+  padding-top: 0.5rem;
+  border-top: 1px solid var(--pollar-border);
+  margin-bottom: 0.75rem;
+}
+.pollar-sessions-logout-all {
+  background: none;
+  border: 1px solid var(--pollar-error-border, #fecaca);
+  border-radius: var(--pollar-buttons-border-radius, 6px);
+  padding: 8px 16px;
+  font-size: 0.8125rem;
+  font-weight: 500;
+  color: var(--pollar-error-text, #dc2626);
+  cursor: pointer;
+  transition: background 150ms;
+}
+.pollar-sessions-logout-all:hover:not(:disabled) {
+  background: var(--pollar-error-bg, #fef2f2);
+}
+.pollar-sessions-logout-all:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
 /* src/components/tx-history-modal/TxHistoryModal.css */
 .pollar-hist-modal {
   max-width: 480px;