@horus-wallet/sdk-react 0.1.0-beta.2

package/README.md

@@ -0,0 +1,398 @@
+# @horus-wallet/sdk-react
+
+React provider + hooks + drop-in components for the Horus embedded-wallet platform. Sign-in, wallets, signing, and on-chain transfers in **15 minutes**.
+
+```tsx
+import { HorusProvider, useHorusAuth, useWallets, HorusLoginButton } from '@horus-wallet/sdk-react';
+
+function App() {
+  return (
+    <HorusProvider appId="app_acme123">
+      <Page />
+    </HorusProvider>
+  );
+}
+
+function Page() {
+  const { authenticated, user, logout } = useHorusAuth();
+  const { wallets } = useWallets();
+
+  if (!authenticated) {
+    return <HorusLoginButton flow="google">Continue with Google</HorusLoginButton>;
+  }
+  return (
+    <>
+      <p>Hi {user?.email}</p>
+      <p>EVM wallet: {wallets.find(w => w.network === 'EVM')?.publicKey}</p>
+      <button onClick={logout}>Sign out</button>
+    </>
+  );
+}
+```
+
+That's it. Sign-in, token persistence, auto-refresh, and wallet fetching all happen inside the provider.
+
+## What you get
+
+- **Drop-in React DX** — one provider, a handful of hooks, no wallet-management code in your app
+- **Built-in auth** — email + password, magic-link email, Google / Apple / phone via popup
+- **Multi-chain wallets** — EVM, Bitcoin, ICP, Casper, Aeternity — same hook, pick `network`
+- **Signing + transfers** — `signMessage`, native + ERC-20 transfers, all behind a hook
+- **Token persistence** — sessions survive page reloads; cross-tab sync; auto-refresh near expiry
+- **Drop-in components** — `<HorusLoginButton>` for one-click signin if you don't want to build the UI yourself
+- **White-label friendly** — partner branding (logo, colors, terms links) flows through to the sign-in popup
+
+## Install
+
+```bash
+npm install @horus-wallet/sdk-react
+```
+
+Peer dependency: React 17+. Works in React 18, Next.js (App Router and Pages), Vite, Remix.
+
+## Quick setup (3 steps)
+
+### 1. Wrap your app in `<HorusProvider>`
+
+```tsx
+import { HorusProvider } from '@horus-wallet/sdk-react';
+
+export function App({ children }) {
+  return (
+    <HorusProvider appId="app_acme123">
+      {children}
+    </HorusProvider>
+  );
+}
+```
+
+You get `appId` from Horus during onboarding.
+
+### 2. Mount a sign-in button
+
+```tsx
+import { HorusLoginButton } from '@horus-wallet/sdk-react';
+
+<HorusLoginButton flow="google">Continue with Google</HorusLoginButton>
+<HorusLoginButton flow="email_link">Email me a link</HorusLoginButton>
+<HorusLoginButton flow="phone">Continue with phone</HorusLoginButton>
+```
+
+Or build your own form and call `useHorusAuth()` methods directly (see hooks below).
+
+### 3. Add a server-side proxy
+
+The React SDK calls **your backend** so your secret API key never reaches the browser:
+
+```
+React app ──► Your backend (~50 lines) ──► api.horuswallet.com
+```
+
+The proxy is a thin pass-through. Reference implementations for Express and Next.js are below.
+
+## Provider config
+
+```tsx
+<HorusProvider
+  appId="app_acme123"             // required — server-assigned during onboarding
+  apiBase="/api/horus"            // where YOUR backend exposes the proxy. Default: /api/horus
+  
+  branding={{                     // optional — passed to the sign-in popup
+    logoUrl: 'https://acme.com/logo.png',
+    brandName: 'Acme',
+    primaryColor: '#FF5733',
+    showPoweredByHorus: false,    // requires the white-label tier
+  }}
+  
+  tokenStorage="localStorage"     // 'localStorage' | 'sessionStorage' | 'memory'
+  autoRefresh={true}              // refresh tokens before expiry; default true
+>
+  <App />
+</HorusProvider>
+```
+
+## Hooks
+
+### `useHorusAuth()` — sign-in, sign-up, sign-out
+
+```tsx
+const {
+  ready,            // true once the provider has hydrated from storage
+  authenticated,    // true if user is signed in
+  user,             // { uid, email, displayName, ... } or undefined
+  
+  // Headless flows — your form, your UI
+  loginWithEmail,   // ({ email, password }) => Promise<User>
+  signUpWithEmail,  // ({ email, password }) => Promise<User>
+  sendEmailLink,    // ({ email, continueUrl }) => Promise<void>
+  verifyEmailLink,  // ({ email, oobCode }) => Promise<User>
+  
+  // Popup flows — Horus-hosted UI for OAuth providers
+  loginWithGoogle,  // () => Promise<User>
+  loginWithEmailLink, // popup variant of email-link
+  loginWithPhone,   // ({ phone? }) => Promise<User>
+  
+  logout,           // clears tokens
+  refresh,          // manual token refresh
+} = useHorusAuth();
+```
+
+### `useUser()` — read the current user
+
+```tsx
+const user = useUser();
+// User | undefined — pure read, no side-effects
+```
+
+### `useWallets()` — the user's wallets
+
+```tsx
+const { wallets, ready, refresh, error } = useWallets();
+// wallets: [{ network: 'EVM', publicKey: '0x…' }, { network: 'BITCOIN', publicKey: 'bc1…' }, …]
+```
+
+### `useSignMessage()` — sign arbitrary messages
+
+```tsx
+const { signMessage, pending, error } = useSignMessage();
+
+const sig = await signMessage({
+  network: 'BASE',
+  networkType: 'MAINNET',
+  message: 'Sign in to Acme — nonce abc123',
+});
+```
+
+### `useTransfer()` — native + token transfers
+
+```tsx
+const { native, token, pending, error } = useTransfer();
+
+// Native (ETH / MATIC / BNB / …)
+const { txHash } = await native({
+  network: 'BASE',
+  networkType: 'MAINNET',
+  recipients: ['0x742d35Cc…'],
+  amount: '1000000000000000',  // wei (string for values > 2^53)
+});
+
+// ERC-20 / chain-equivalent token
+const { txHash } = await token({
+  network: 'BASE',
+  networkType: 'MAINNET',
+  tokenAddress: '0xA0b86…',  // USDC
+  recipient: '0x742d35Cc…',
+  amount: '5000000',          // smallest unit (USDC has 6 decimals)
+});
+```
+
+## Drop-in components
+
+### `<HorusLoginButton>`
+
+```tsx
+<HorusLoginButton flow="google">Continue with Google</HorusLoginButton>
+<HorusLoginButton flow="email_link">Email me a link</HorusLoginButton>
+<HorusLoginButton flow="phone">Continue with phone</HorusLoginButton>
+```
+
+For total UI control, skip the component and call `useHorusAuth()` methods from your own form.
+
+## Backend setup (the proxy)
+
+A thin pass-through that forwards SDK calls to Horus, holding your secret key server-side. Roughly **50 lines**.
+
+### Express / Connect
+
+```ts
+// server/horus-proxy.ts
+import express from 'express';
+import { HorusClient } from '@horus-wallet/sdk';
+
+export function horusProxy() {
+  const router = express.Router();
+
+  // Per-request client — picks up the user's auth token from the SDK header.
+  const clientFor = (req: express.Request) =>
+    new HorusClient({
+      baseUrl: process.env.HORUS_BASE_URL!,
+      apiKey: process.env.HORUS_API_KEY!,           // hk_sk_*
+      getIdToken: async () => req.header('x-horus-id-token') ?? '',
+    });
+
+  // Auth — unauthenticated; mints tokens on success
+  router.post('/auth/email/signup', async (req, res, next) => {
+    try { res.json(await clientFor(req).auth.signUpWithEmail(req.body)); }
+    catch (err) { next(err); }
+  });
+  router.post('/auth/email/signin', async (req, res, next) => {
+    try { res.json(await clientFor(req).auth.signInWithEmail(req.body)); }
+    catch (err) { next(err); }
+  });
+  router.post('/auth/email-link/send', async (req, res, next) => {
+    try { res.json(await clientFor(req).auth.sendEmailLink(req.body)); }
+    catch (err) { next(err); }
+  });
+  router.post('/auth/email-link/verify', async (req, res, next) => {
+    try { res.json(await clientFor(req).auth.verifyEmailLink(req.body)); }
+    catch (err) { next(err); }
+  });
+  router.post('/auth/oauth', async (req, res, next) => {
+    try { res.json(await clientFor(req).auth.signInWithOAuth(req.body)); }
+    catch (err) { next(err); }
+  });
+  router.post('/auth/refresh', async (req, res, next) => {
+    try { res.json(await clientFor(req).auth.refresh(req.body.refreshToken)); }
+    catch (err) { next(err); }
+  });
+
+  // Wallet ops — authenticated; SDK forwards the user's token
+  router.get('/wallets', async (req, res, next) => {
+    try { res.json(await clientFor(req).wallets.get()); }
+    catch (err) { next(err); }
+  });
+  router.post('/sign-message', async (req, res, next) => {
+    try { res.json(await clientFor(req).wallets.signMessage(req.body)); }
+    catch (err) { next(err); }
+  });
+  router.post('/transfer/native', async (req, res, next) => {
+    try { res.json(await clientFor(req).transfers.native(req.body)); }
+    catch (err) { next(err); }
+  });
+  router.post('/transfer/token', async (req, res, next) => {
+    try { res.json(await clientFor(req).transfers.token(req.body)); }
+    catch (err) { next(err); }
+  });
+
+  return router;
+}
+```
+
+Mount it:
+
+```ts
+import express from 'express';
+import { horusProxy } from './horus-proxy';
+
+const app = express();
+app.use(express.json());
+app.use('/api/horus', horusProxy());
+app.listen(3001);
+```
+
+That's the whole backend integration.
+
+### Next.js (App Router)
+
+```tsx
+// app/providers.tsx
+'use client';
+import { HorusProvider } from '@horus-wallet/sdk-react';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <HorusProvider appId={process.env.NEXT_PUBLIC_HORUS_APP_ID!}>
+      {children}
+    </HorusProvider>
+  );
+}
+
+// app/layout.tsx
+import { Providers } from './providers';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return <html><body><Providers>{children}</Providers></body></html>;
+}
+```
+
+```ts
+// app/api/horus/[...path]/route.ts
+import { HorusClient } from '@horus-wallet/sdk';
+
+const client = (req: Request) =>
+  new HorusClient({
+    baseUrl: process.env.HORUS_BASE_URL!,
+    apiKey: process.env.HORUS_API_KEY!,
+    getIdToken: async () => req.headers.get('x-horus-id-token') ?? '',
+  });
+
+const handlers: Record<string, (req: Request, body: any) => Promise<unknown>> = {
+  'auth/email/signin':      (req, body) => client(req).auth.signInWithEmail(body),
+  'auth/email/signup':      (req, body) => client(req).auth.signUpWithEmail(body),
+  'auth/email-link/send':   (req, body) => client(req).auth.sendEmailLink(body),
+  'auth/email-link/verify': (req, body) => client(req).auth.verifyEmailLink(body),
+  'auth/oauth':             (req, body) => client(req).auth.signInWithOAuth(body),
+  'auth/refresh':           (req, body) => client(req).auth.refresh(body.refreshToken),
+  'wallets':                (req)       => client(req).wallets.get(),
+  'sign-message':           (req, body) => client(req).wallets.signMessage(body),
+  'transfer/native':        (req, body) => client(req).transfers.native(body),
+  'transfer/token':         (req, body) => client(req).transfers.token(body),
+};
+
+async function dispatch(req: Request, ctx: { params: { path: string[] } }) {
+  const fn = handlers[ctx.params.path.join('/')];
+  if (!fn) return Response.json({ message: 'Not found' }, { status: 404 });
+  try {
+    const body = req.headers.get('content-type')?.includes('json') ? await req.json() : undefined;
+    return Response.json(await fn(req, body));
+  } catch (err: any) {
+    return Response.json({ message: err.message }, { status: err.status ?? 500 });
+  }
+}
+
+export const GET = dispatch;
+export const POST = dispatch;
+```
+
+## Errors
+
+```tsx
+import { HorusHttpError } from '@horus-wallet/sdk-react';
+
+try {
+  await loginWithEmail({ email, password });
+} catch (err) {
+  if (err instanceof HorusHttpError) {
+    if (err.status === 401) {
+      // Wrong creds, expired token, or token rejected by server
+    }
+    if (err.status === 429) {
+      // Rate limited — back off
+    }
+  }
+}
+```
+
+The hooks (`useWallets`, `useSignMessage`, `useTransfer`) also expose `error` as part of their return shape so you can render error states declaratively.
+
+## Security
+
+- The `hk_sk_*` secret stays on your backend — it never reaches the browser
+- Tokens persist in `localStorage` by default. For stricter privacy, use `sessionStorage` (cleared on tab close) or `memory` (RAM only) via the `tokenStorage` prop
+- The popup flows pin their `postMessage` target origin to the partner's window — tokens cannot be exfiltrated to other origins
+- White-label settings (hiding the Horus footer in the popup) are server-enforced — partners on the standard tier always see the footer regardless of client config
+
+## Coming from Privy / Magic / Web3Auth?
+
+| Privy | Horus |
+|---|---|
+| `<PrivyProvider>` | `<HorusProvider>` |
+| `usePrivy()` | `useHorusAuth()` |
+| `usePrivy().login()` | `useHorusAuth().loginWithGoogle()` (or any flow) |
+| `useWallets()` | `useWallets()` |
+| `usePrivy().user` | `useHorusAuth().user` or `useUser()` |
+| Hosted modal | `<HorusLoginButton>` (popup) |
+| Backend SDK | `@horus-wallet/sdk` |
+
+Conceptual differences:
+- Horus uses a **partner-backend proxy** so your secret never leaves your server. Privy talks to its API directly from the browser.
+- **More chains supported** — EVM + Bitcoin + ICP + Casper + Aeternity all in one SDK.
+
+## What's not yet here
+
+- External wallet connect (MetaMask / WalletConnect) — coming
+- Mobile SDKs (iOS / Android / React Native) — coming
+- Drop-in `<HorusAuthModal>` (inline UI without popup) — coming
+- Pre-generated wallets for unsigned-in users — coming
+
+For partner integration questions: `info@horuswallet.com`.