@agg-build/auth 1.0.0

package/README.md

@@ -0,0 +1,251 @@
+# @agg-build/auth
+
+Modular connect / sign-in UI and auth-method adapters for the
+[AGG](https://docs.agg.market/) prediction market aggregator. Drop in a `ConnectButton`, pick the
+auth methods you want to enable (SIWE, SIWS, Google, Apple, Twitter/X, email magic-link), and ship.
+
+## What it is
+
+`@agg-build/auth` keeps provider-specific auth integrations out of
+[`@agg-build/ui`](https://www.npmjs.com/package/@agg-build/ui). Each auth method ships as a separate adapter
+— wallet providers (SIWE, SIWS) stay behind subpath imports so their peer dependencies are only
+pulled in when you actually enable them. `AggAuthProvider` orchestrates the flow end-to-end:
+opening the chooser, driving wallet sign-in, redirecting to OAuth providers, emailing magic
+links, handling the post-redirect code exchange, and transparently solving Cloudflare Turnstile
+challenges when the API requires them.
+
+## When to use this package
+
+- You want AGG's connect / sign-in UX without rebuilding it.
+- You want to enable only the auth methods your app supports.
+- You want redirect callback handling (OAuth + email magic-link) solved for you.
+- You want Cloudflare Turnstile challenge handling built in.
+
+If you prefer to roll your own wallet UI, skip this package and use `useAggAuth` from
+[`@agg-build/hooks`](https://www.npmjs.com/package/@agg-build/hooks) directly.
+
+## Install
+
+Core packages:
+
+```bash
+npm install @agg-build/sdk @agg-build/hooks @agg-build/ui @agg-build/auth liveline
+```
+
+Add only the optional peers you need:
+
+```bash
+# SIWE / Ethereum
+npm install wagmi viem
+
+# SIWS / Solana
+npm install @solana/wallet-adapter-react bs58
+```
+
+Google, Apple, Twitter/X, and email magic-link flows don't require any extra peers — they are
+plain redirect-based flows driven by the SDK.
+
+## Quick start
+
+```tsx
+import "@agg-build/ui/styles.css";
+import { AggProvider } from "@agg-build/hooks";
+import { createAggClient } from "@agg-build/sdk";
+import {
+  AggAuthProvider,
+  ConnectButton,
+  createAppleAuthMethod,
+  createEmailAuthMethod,
+  createGoogleAuthMethod,
+  createTwitterAuthMethod,
+} from "@agg-build/auth";
+import { useSiweAuthMethod } from "@agg-build/auth/siwe";
+import { useSiwsAuthMethod } from "@agg-build/auth/siws";
+import { WagmiProvider } from "wagmi";
+import { wagmiConfig } from "./wagmi-config";
+
+const client = createAggClient({
+  appId: "your-app-id",
+  baseUrl: "https://api.agg.market",
+});
+
+function AuthActions() {
+  const siwe = useSiweAuthMethod({ statement: "Sign in to AGG" });
+  const siws = useSiwsAuthMethod({ cluster: "mainnet", statement: "Sign in to AGG" });
+
+  return (
+    <AggAuthProvider
+      methods={[
+        siwe,
+        siws,
+        createGoogleAuthMethod(),
+        createAppleAuthMethod(),
+        createTwitterAuthMethod(),
+        createEmailAuthMethod(),
+      ]}
+    >
+      <ConnectButton />
+    </AggAuthProvider>
+  );
+}
+
+export default function App() {
+  return (
+    <WagmiProvider config={wagmiConfig}>
+      <AggProvider client={client}>
+        <AuthActions />
+      </AggProvider>
+    </WagmiProvider>
+  );
+}
+```
+
+`AggAuthProvider` watches the current URL on mount. For redirect-based methods it reads the
+`code` query parameter, calls `client.exchangeAuthCode(code)`, then cleans the URL. No extra
+setup required if the user lands back on the same app.
+
+## Dedicated callback route
+
+If your app routes redirects to a separate callback page, hydrate the exchange yourself with
+`useAggAuthCallback`:
+
+```tsx
+import { useAggAuthCallback } from "@agg-build/auth";
+
+export function AuthCallbackPage() {
+  const { error, isHandled, isHandling, user } = useAggAuthCallback();
+
+  if (isHandling) return <p>Finishing sign-in…</p>;
+  if (error) return <p>{error.message}</p>;
+  if (isHandled) return <p>Signed in as {user?.id}</p>;
+
+  return <p>No AGG auth callback data was found.</p>;
+}
+```
+
+The callback hook follows the same recipe:
+
+1. Parse the `code` query parameter.
+2. Call `client.exchangeAuthCode(code)`.
+3. Remove `code` from the URL via `window.history.replaceState(...)`.
+
+## Turnstile challenges
+
+When the AGG API returns `challenge_required`, `AggAuthProvider` automatically renders a
+Cloudflare Turnstile widget, submits the solved token, and retries the request. The widget is
+invisible on success and degrades gracefully if a user's environment blocks Turnstile. You do not
+need to render or configure the widget directly.
+
+## Available auth methods
+
+| Import path            | Export                      | Peer deps                              | Notes                                    |
+| ---------------------- | --------------------------- | -------------------------------------- | ---------------------------------------- |
+| `@agg-build/auth`      | `createEmailAuthMethod()`   | —                                      | Magic-link email flow                    |
+| `@agg-build/auth`      | `createGoogleAuthMethod()`  | —                                      | Redirect-based OAuth                     |
+| `@agg-build/auth`      | `createAppleAuthMethod()`   | —                                      | Redirect-based OAuth                     |
+| `@agg-build/auth`      | `createTwitterAuthMethod()` | —                                      | Redirect-based OAuth                     |
+| `@agg-build/auth/siwe` | `useSiweAuthMethod()`       | `wagmi`                                | Ethereum wallet sign-in                  |
+| `@agg-build/auth/siws` | `useSiwsAuthMethod()`       | `@solana/wallet-adapter-react`, `bs58` | Solana wallet sign-in; Ledger-compatible |
+
+Pass the methods you want to enable to `AggAuthProvider` — the `ConnectButton` chooser only lists
+methods you include.
+
+### Custom redirect URL / navigation
+
+Redirect-based adapters accept a `redirectUrl` and optional `navigate` function:
+
+```tsx
+createGoogleAuthMethod({
+  redirectUrl: "https://yourapp.com/auth/callback",
+  navigate: (url) => window.top?.location.assign(url),
+});
+```
+
+### Custom wallet picker (SIWE)
+
+`useSiweAuthMethod` accepts an optional `connectorPicker` to render your own wallet chooser modal
+instead of `wagmi`'s default:
+
+```tsx
+const siwe = useSiweAuthMethod({
+  connectorPicker: async (connectors) => showMyWalletModal(connectors),
+});
+```
+
+## `ConnectButton` props
+
+| Prop                 | Type                                                | Description                                  |
+| -------------------- | --------------------------------------------------- | -------------------------------------------- |
+| `buttonProps`        | `ConnectButtonButtonProps`                          | Props passed to the inner `Button` component |
+| `classNames`         | `ConnectButtonClassNames`                           | Style overrides for sub-elements             |
+| `disabled`           | `boolean`                                           | Disable the button                           |
+| `onAuthMethodSelect` | `(methodId: AuthMethodId) => void \| Promise<void>` | Called when user picks an auth method        |
+| `onDepositClick`     | `() => void \| Promise<void>`                       | Called when user clicks deposit              |
+| `onDisconnect`       | `() => void \| Promise<void>`                       | Called on disconnect                         |
+| `onProfileClick`     | `() => void \| Promise<void>`                       | Called when user clicks profile              |
+| `onWithdrawClick`    | `() => void \| Promise<void>`                       | Called when user clicks withdraw             |
+
+When authenticated, the button collapses into the user's profile chip with action buttons
+(deposit, withdraw, profile, disconnect). Use the callback props to wire them to your app's
+navigation or modal system.
+
+## Main exports
+
+| Import path            | Export                    | Description                                                     |
+| ---------------------- | ------------------------- | --------------------------------------------------------------- |
+| `@agg-build/auth`      | `AggAuthProvider`         | Orchestrates the chooser, redirect callback, and Turnstile      |
+| `@agg-build/auth`      | `ConnectButton`           | Drop-in connect / account chip                                  |
+| `@agg-build/auth`      | `useAggAuthFlow`          | Access the chooser/flow state (used by custom UIs)              |
+| `@agg-build/auth`      | `useAggAuthCallback`      | Manually hydrate the redirect callback page                     |
+| `@agg-build/auth`      | `createEmailAuthMethod`   | Magic-link email adapter                                        |
+| `@agg-build/auth`      | `createGoogleAuthMethod`  | Google OAuth adapter                                            |
+| `@agg-build/auth`      | `createAppleAuthMethod`   | Apple OAuth adapter                                             |
+| `@agg-build/auth`      | `createTwitterAuthMethod` | Twitter/X OAuth adapter                                         |
+| `@agg-build/auth/siwe` | `useSiweAuthMethod`       | SIWE adapter (requires `wagmi`)                                 |
+| `@agg-build/auth/siws` | `useSiwsAuthMethod`       | SIWS adapter (requires `@solana/wallet-adapter-react` + `bs58`) |
+
+## Architecture
+
+- `@agg-build/sdk` owns auth API calls and session-token storage.
+- `@agg-build/hooks` owns shared auth/session state inside `AggProvider`.
+- `@agg-build/ui` ships generic UI primitives only.
+- `@agg-build/auth` ships auth-method adapters + the connect/sign-in UX.
+
+## Entrypoints
+
+| Entry                            | Purpose                                                                      |
+| -------------------------------- | ---------------------------------------------------------------------------- |
+| `@agg-build/auth`                | `AggAuthProvider`, `ConnectButton`, OAuth + email adapters                   |
+| `@agg-build/auth/connect-button` | `ConnectButton` component only (narrow import)                               |
+| `@agg-build/auth/oauth`          | `createAppleAuthMethod`, `createGoogleAuthMethod`, `createTwitterAuthMethod` |
+| `@agg-build/auth/email`          | `createEmailAuthMethod`                                                      |
+| `@agg-build/auth/siwe`           | `useSiweAuthMethod` (requires `wagmi`)                                       |
+| `@agg-build/auth/siws`           | `useSiwsAuthMethod` (requires Solana wallet adapter)                         |
+
+## Peer dependencies
+
+Required:
+
+- `@agg-build/hooks`
+- `@agg-build/ui`
+- `react` ^18.0.0 or ^19.0.0
+- `react-dom` ^18.0.0 or ^19.0.0
+
+Optional (tied to specific adapters):
+
+- `wagmi` ^3.5.0 — SIWE
+- `@solana/wallet-adapter-react` ^0.15.39 — SIWS
+- `bs58` ^6.0.0 — SIWS signature encoding
+
+## Links
+
+- Documentation — <https://docs.agg.market/>
+- Storybook — <https://storybook.agg.market/>
+- Demo app — <https://demo.agg.market/>
+- Vanilla SDK — [`@agg-build/sdk`](https://www.npmjs.com/package/@agg-build/sdk)
+- React hooks — [`@agg-build/hooks`](https://www.npmjs.com/package/@agg-build/hooks)
+- Trading UI — [`@agg-build/ui`](https://www.npmjs.com/package/@agg-build/ui)
+
+## License
+
+MIT