@emblemvault/emblem-auth-react 1.0.0

package/README.md

@@ -0,0 +1,132 @@
+# @emblemvault/emblem-auth-react
+
+React hooks and components for Emblem wallet authentication.
+
+## Installation
+
+```bash
+npm install @emblemvault/emblem-auth-react
+```
+
+## Quick Start
+
+```tsx
+import {
+  EmblemAuthProvider,
+  ConnectButton,
+  useEmblemAuth,
+} from '@emblemvault/emblem-auth-react';
+
+function App() {
+  return (
+    <EmblemAuthProvider appId="your-app-id">
+      <Header />
+      <Content />
+    </EmblemAuthProvider>
+  );
+}
+
+function Header() {
+  return <ConnectButton showVaultInfo />;
+}
+
+function Content() {
+  const { isAuthenticated, walletAddress, vaultId } = useEmblemAuth();
+
+  if (!isAuthenticated) {
+    return <p>Please connect to continue</p>;
+  }
+
+  return (
+    <div>
+      <p>Wallet: {walletAddress}</p>
+      <p>Vault: {vaultId}</p>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### EmblemAuthProvider
+
+Wrap your app to provide authentication context.
+
+```tsx
+<EmblemAuthProvider
+  appId="your-app-id"
+  apiUrl="https://api.emblemvault.ai"      // optional
+  modalUrl="https://auth.emblemvault.ai/connect"  // optional
+>
+  {children}
+</EmblemAuthProvider>
+```
+
+### useEmblemAuth
+
+Access auth state and actions.
+
+```tsx
+const {
+  // State
+  isAuthenticated,  // boolean
+  isLoading,        // boolean
+  error,            // Error | null
+  session,          // AuthSession | null
+  walletAddress,    // string | null
+  vaultId,          // string | null
+  authSDK,          // EmblemAuthSDK instance
+
+  // Actions
+  openAuthModal,    // () => Promise<void>
+  logout,           // () => void
+  refreshSession,   // () => Promise<void>
+} = useEmblemAuth();
+```
+
+### useEmblemAuthOptional
+
+Same as `useEmblemAuth` but returns `null` when used outside provider (instead of throwing).
+
+```tsx
+const auth = useEmblemAuthOptional();
+if (!auth) {
+  return <p>Auth not available</p>;
+}
+```
+
+### ConnectButton
+
+Pre-styled connect/disconnect button.
+
+```tsx
+<ConnectButton
+  showVaultInfo    // Show vault dropdown when connected
+  className=""     // Additional CSS classes
+/>
+```
+
+### AuthStatus
+
+Display authentication status.
+
+```tsx
+<AuthStatus
+  showVaultInfo   // Show vault ID
+  showLogout      // Show logout button
+/>
+```
+
+## Underlying SDK
+
+This package wraps [emblem-auth-sdk](https://github.com/nicktaylor-/emblem-auth-sdk) for React. The SDK handles:
+
+- JWT lifecycle and token refresh
+- Wallet connection modal
+- Session management
+
+For advanced usage, access the SDK directly via `useEmblemAuth().authSDK`.
+
+## License
+
+MIT