@auth-gate/react-native 0.9.2 → 0.10.0

package/README.md

@@ -0,0 +1,203 @@
+<p align="center">
+  <img src="icon.png" alt="AuthGate" width="120" height="120" />
+</p>
+
+# @auth-gate/react-native
+
+React Native / Expo SDK for [AuthGate](https://www.authgate.dev) — drop-in authentication with OAuth, email, SMS, and MFA for mobile apps.
+
+## Installation
+
+```bash
+npm install @auth-gate/react-native
+```
+
+**Peer dependencies:** `react >= 18`, `react-native >= 0.72`, `expo-secure-store`, `expo-web-browser`, `expo-linking`
+
+```bash
+npx expo install expo-secure-store expo-web-browser expo-linking
+```
+
+## Quick Start
+
+### 1. Configure Deep Links
+
+Add your custom URL scheme to `app.json`:
+
+```json
+{
+  "expo": {
+    "scheme": "myapp"
+  }
+}
+```
+
+Register the callback URL `myapp://auth/callback` in the [Callbacks tab](/dashboard#registering-callback-urls) of your AuthGate dashboard.
+
+### 2. Wrap Your App
+
+```tsx
+import { AuthProvider } from "@auth-gate/react-native";
+
+export default function App() {
+  return (
+    <AuthProvider
+      config={{
+        apiKey: "ag_...",
+        baseUrl: "https://www.authgate.dev",
+        scheme: "myapp",
+      }}
+    >
+      <Navigation />
+    </AuthProvider>
+  );
+}
+```
+
+### 3. Use the Hooks
+
+```tsx
+import { useAuth } from "@auth-gate/react-native";
+
+function ProfileScreen() {
+  const { user, loading, login, logout } = useAuth();
+
+  if (loading) return <ActivityIndicator />;
+  if (!user) return <LoginScreen />;
+
+  return (
+    <View>
+      <Text>Hello, {user.name}</Text>
+      <Button title="Sign out" onPress={logout} />
+    </View>
+  );
+}
+```
+
+## Authentication Methods
+
+### OAuth
+
+Opens the system browser for the OAuth flow and returns via deep link.
+
+```tsx
+const { login } = useAuth();
+
+// Google, GitHub, Discord, Azure (Microsoft), Apple
+await login.withOAuth("google");
+```
+
+### Email
+
+```tsx
+const { login } = useAuth();
+
+// Sign up
+await login.signUp("alice@example.com", "password123", "Alice");
+
+// Sign in
+const result = await login.withEmail("alice@example.com", "password123");
+
+if (result?.mfaRequired) {
+  // Handle MFA challenge
+  await login.verifyMfa(result.challenge, totpCode, "totp");
+}
+```
+
+### Magic Link
+
+```tsx
+await login.withMagicLink("alice@example.com");
+// User receives a link that opens the app via deep link
+```
+
+### SMS
+
+```tsx
+await login.withSms("+15551234567");
+await login.verifySmsCode("+15551234567", "123456");
+```
+
+### MFA
+
+```tsx
+// After email sign-in returns mfaRequired
+await login.verifyMfa(challenge, code, "totp");   // TOTP
+await login.verifyMfa(challenge, code, "sms");    // SMS
+await login.verifyMfa(challenge, code, "backup_code"); // Backup code
+```
+
+## Route Protection
+
+```tsx
+import { AuthGuard } from "@auth-gate/react-native";
+
+function App() {
+  return (
+    <AuthProvider config={config}>
+      <AuthGuard
+        redirectTo="Login" // navigation route name
+        loadingFallback={<ActivityIndicator />}
+      >
+        <ProtectedScreens />
+      </AuthGuard>
+    </AuthProvider>
+  );
+}
+```
+
+## Configuration
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `apiKey` | `string` | Yes | Your AuthGate API key |
+| `baseUrl` | `string` | Yes | AuthGate instance URL |
+| `scheme` | `string` | Yes | Deep link scheme (e.g. `"myapp"`) |
+| `sessionMaxAge` | `number` | No | Session TTL in seconds (default: `604800` / 7 days) |
+| `callbackPath` | `string` | No | Deep link callback path (default: `"auth/callback"`) |
+
+## Hooks
+
+### `useAuth()`
+
+```ts
+const { user, loading, login, logout, refresh } = useAuth();
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `user` | `AuthGateUser \| null` | Current user or null |
+| `loading` | `boolean` | True while restoring session |
+| `login` | `LoginMethods` | OAuth, email, SMS, magic link, and MFA methods |
+| `logout` | `() => Promise<void>` | Sign out and clear secure storage |
+| `refresh` | `() => Promise<void>` | Re-verify the stored token |
+
+### `useSession()`
+
+```ts
+const user = useSession(); // AuthGateUser | null
+```
+
+## How It Works
+
+- Tokens are stored in **Expo Secure Store** (Keychain on iOS, EncryptedSharedPreferences on Android)
+- OAuth flows open the **system browser** via `expo-web-browser` and return via deep link
+- Session is automatically restored on app launch by verifying the stored token
+- Token refresh is scheduled automatically before expiry
+
+## Types
+
+```ts
+import type {
+  AuthGateUser,
+  AuthGateNativeConfig,
+  AuthContextValue,
+  LoginMethods,
+  MfaChallengeResult,
+  OAuthProvider,
+} from "@auth-gate/react-native";
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auth-gate/react-native",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "type": "module",
   "exports": {
     ".": {
@@ -13,10 +13,11 @@
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "icon.png"
   ],
   "dependencies": {
-    "@auth-gate/core": "0.9.2"
+    "@auth-gate/core": "0.10.0"
   },
   "peerDependencies": {
     "react": ">=18",