@auth-gate/react 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,241 @@
+# @auth-gate/react
+
+React SDK for [AuthGate](https://authgate.dev) — drop-in authentication with OAuth, email, SMS, and MFA for React apps using Hono as the backend.
+
+## Installation
+
+```bash
+npm install @auth-gate/react
+```
+
+**Peer dependencies:** `react >= 18`, `hono >= 4`
+
+## Quick Start
+
+### 1. Create Auth Routes (Server)
+
+```ts
+// server/auth.ts
+import { createAuthRoutes } from "@auth-gate/react/server";
+
+const auth = createAuthRoutes({
+  apiKey: process.env.AUTHGATE_API_KEY!,
+  projectId: process.env.AUTHGATE_PROJECT_ID!,
+  baseUrl: "https://authgate.dev",
+  sessionSecret: process.env.SESSION_SECRET!,
+  appUrl: "http://localhost:3000",
+});
+```
+
+### 2. Mount in Hono
+
+```ts
+// server/index.ts
+import { Hono } from "hono";
+import { auth } from "./auth";
+
+const app = new Hono();
+app.route("/api/auth", auth);
+
+export default app;
+```
+
+### 3. Add the Provider (Client)
+
+```tsx
+// src/App.tsx
+import { AuthProvider } from "@auth-gate/react";
+
+export default function App() {
+  return (
+    <AuthProvider>
+      <Router />
+    </AuthProvider>
+  );
+}
+```
+
+### 4. Use the Hooks
+
+```tsx
+import { useAuth } from "@auth-gate/react";
+
+function Profile() {
+  const { user, loading, logout } = useAuth();
+
+  if (loading) return <p>Loading...</p>;
+  if (!user) return <p>Not signed in</p>;
+
+  return (
+    <div>
+      <p>Hello, {user.name}</p>
+      <button onClick={logout}>Sign out</button>
+    </div>
+  );
+}
+```
+
+## Route Map
+
+The Hono router registers these routes under your mount path (e.g. `/api/auth/`):
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| GET | `/:provider/login` | Start OAuth flow (google, github, discord, azure, apple) |
+| GET | `/callback` | OAuth / magic link callback |
+| POST | `/email/signup` | Email registration |
+| POST | `/email/signin` | Email sign-in |
+| POST | `/email/forgot-password` | Request password reset |
+| POST | `/email/reset-password` | Confirm password reset |
+| POST | `/email/verify-code` | Verify email with OTP |
+| POST | `/magic-link/send` | Send magic link |
+| POST | `/sms/send-code` | Send SMS code |
+| POST | `/sms/verify-code` | Verify SMS code |
+| POST | `/mfa/verify` | Complete MFA challenge |
+| POST | `/refresh` | Refresh session token |
+| POST | `/logout` | Sign out and revoke session |
+| GET | `/me` | Get current user |
+
+## Client Components
+
+### `<AuthProvider>`
+
+Wraps your app and manages auth state via context.
+
+```tsx
+<AuthProvider
+  meEndpoint="/api/auth/me"       // default
+  logoutEndpoint="/api/auth/logout" // default
+>
+  {children}
+</AuthProvider>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `meEndpoint` | `string` | `"/api/auth/me"` | Endpoint to fetch current user |
+| `logoutEndpoint` | `string` | `"/api/auth/logout"` | Endpoint to call on logout |
+
+### `<AuthGuard>`
+
+Protects routes by redirecting unauthenticated users.
+
+```tsx
+import { AuthGuard } from "@auth-gate/react";
+
+function ProtectedPage() {
+  return (
+    <AuthGuard redirectTo="/login" loadingFallback={<Spinner />}>
+      <Dashboard />
+    </AuthGuard>
+  );
+}
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `redirectTo` | `string` | `"/login"` | Redirect path when not authenticated |
+| `loadingFallback` | `ReactNode` | — | Shown while session is loading |
+
+### Hooks
+
+#### `useAuth()`
+
+Returns the full auth context.
+
+```ts
+const { user, loading, refresh, logout } = useAuth();
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `user` | `AuthGateUser \| null` | Current user or null |
+| `loading` | `boolean` | True while fetching session |
+| `refresh` | `() => Promise<void>` | Re-fetch the session |
+| `logout` | `() => Promise<void>` | Sign out and clear state |
+
+#### `useSession()`
+
+Shorthand that returns just the user.
+
+```ts
+const user = useSession(); // AuthGateUser | null
+```
+
+## Authentication Examples
+
+### OAuth Sign-In
+
+```html
+<a href="/api/auth/google/login">Sign in with Google</a>
+<a href="/api/auth/github/login">Sign in with GitHub</a>
+```
+
+### Email Sign-In
+
+```ts
+const res = await fetch("/api/auth/email/signin", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ email, password }),
+});
+
+const data = await res.json();
+
+if (data.mfa_required) {
+  await fetch("/api/auth/mfa/verify", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      mfa_challenge: data.mfa_challenge,
+      code: totpCode,
+      method: "totp",
+    }),
+  });
+}
+```
+
+### SMS Sign-In
+
+```ts
+await fetch("/api/auth/sms/send-code", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ phone: "+15551234567" }),
+});
+
+await fetch("/api/auth/sms/verify-code", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ phone: "+15551234567", code: "123456" }),
+});
+```
+
+## Server API Reference
+
+### `createAuthRoutes(options)`
+
+Creates a Hono router with all auth endpoints.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `apiKey` | `string` | Yes | AuthGate API key |
+| `projectId` | `string` | Yes | AuthGate project ID |
+| `baseUrl` | `string` | Yes | AuthGate instance URL |
+| `sessionSecret` | `string` | Yes | Encryption secret (min 32 chars) |
+| `appUrl` | `string` | Yes | Your app's URL |
+| `cookieName` | `string` | No | Cookie name (default: `__authgate`) |
+| `sessionMaxAge` | `number` | No | Session TTL in seconds (default: `604800`) |
+| `callbackPath` | `string` | No | Callback path (default: `/api/auth/callback`) |
+
+## Types
+
+```ts
+import type { AuthGateUser, OAuthProvider } from "@auth-gate/react";
+```
+
+Re-exported from `@auth-gate/core` for convenience.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auth-gate/react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": {
@@ -21,7 +21,7 @@
     "dist"
   ],
   "dependencies": {
-    "@auth-gate/core": "0.1.0"
+    "@auth-gate/core": "0.2.0"
   },
   "peerDependencies": {
     "react": ">=18",