@atzentis/auth-expo 0.0.15 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-02-19
+
+### Added
+
+- `AuthProvider` with Better Auth client, SecureStore token persistence, expo-localization integration
+- `AuthContainer` layout with KeyboardAvoidingView and safe area handling
+- 8 auth screens: `LoginScreen` (with biometric auth), `SignupScreen`, `PhoneLoginScreen` (2-step OTP), `MagicLinkScreen` (multi-step with token), `TwoFactorScreen` (TOTP + backup codes), `ForgotPasswordScreen` (email + cooldown resend), `ResetPasswordScreen` (token-based), `EmailVerificationScreen` (auto-verify)
+- `AuthView` route-based renderer for flexible screen navigation
+- 7 settings screens: `ChangePasswordScreen`, `ChangeEmailScreen`, `UpdateNameScreen`, `UpdateUsernameScreen`, `UpdateAvatarScreen`, `SessionsScreen`, `DeleteAccountScreen`
+- `TwoFactorSettingsScreen` for 2FA management
+- 2 organization screens: `OrganizationSwitcherScreen`, `OrganizationMembersScreen`
+- `OAuthButton` component (Google, Apple, GitHub providers)
+- `FormInput` and `FormPasswordInput` form components
+- `ErrorFeedback` and `SuccessFeedback` status components
+- `SubmitButton` with loading state
+- `AuthGate` for session-based conditional rendering
+- `ProtectedScreen` for role/permission guards
+- Hooks: `useAuthClient`, `useAuthLocalization`, `useBiometric`, `useAuthRedirect`
+- Mutation hooks: `useLogin`, `useSignup`, `useLogout`, `useRequestPasswordReset`, `useResetPassword`
+- Query hooks: `useUser`, `useSession`
+- React 19 patterns (React.use, Context value=)
+- expo-router integration
+
+[Unreleased]: https://github.com/atzentis/atzentis-auth-sdk/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/atzentis/atzentis-auth-sdk/releases/tag/v0.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Atzentis
+Copyright (c) 2026 Atzentis
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,56 +1,220 @@
 # @atzentis/auth-expo
 
-React Native/Expo integration for [Atzentis Authentication](https://auth.atzentis.com).
+[![npm version](https://img.shields.io/npm/v/@atzentis/auth-expo)](https://www.npmjs.com/package/@atzentis/auth-expo)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
 
-Extends `@atzentis/auth-sdk` with native device signals, biometric authentication, and secure token storage.
+React Native/Expo auth screens and components for [auth.atzentis.com](https://auth.atzentis.com). Provides 18 ready-to-use native screens, biometric authentication, secure token storage via `expo-secure-store`, and first-class expo-router integration.
+
+## Features
+
+- **18 native screens** — complete auth, settings, and organization flows for React Native
+- **Biometric authentication** — FaceID/TouchID via `expo-local-authentication`
+- **Secure storage** — tokens stored in the device keychain via `expo-secure-store`
+- **expo-router integration** — `AuthView` maps route strings to screens; `useAuthRedirect` wraps `router.replace`
+- **Session-based conditional rendering** — `AuthGate` and `ProtectedScreen` with role/permission guards
+- **TanStack Query** — 5 mutation hooks and 2 query hooks backed by the same cache as `@atzentis/auth-react`
+- **React 19 patterns** — uses `React.use(Context)` and `<Context value={}>` provider syntax
 
 ## Installation
 
 ```bash
-pnpm add @atzentis/auth-sdk @atzentis/auth-expo
+npx expo install @atzentis/auth-expo @atzentis/auth-sdk
+```
 
-# Peer dependencies
-npx expo install expo-device expo-application expo-secure-store
+Then install the required peer dependencies:
+
+```bash
+npx expo install \
+  better-auth \
+  @better-auth/expo \
+  expo-secure-store \
+  expo-local-authentication \
+  expo-localization \
+  expo-router \
+  expo-application \
+  expo-device \
+  expo-haptics
 ```
 
+And install the JS peer dependencies:
+
+```bash
+npm install @tanstack/react-query react-hook-form @hookform/resolvers
+```
+
+## Peer Dependencies
+
+| Package | Version | Required |
+| --- | --- | --- |
+| `better-auth` | >= 1.2.0 | Yes |
+| `@better-auth/expo` | >= 1.2.0 | Yes |
+| `expo-secure-store` | >= 14.0.0 | Yes |
+| `expo-localization` | >= 16.0.0 | Yes |
+| `expo-router` | >= 4.0.0 | Yes |
+| `expo-application` | >= 6.0.0 | Yes |
+| `expo-device` | >= 7.0.0 | Yes |
+| `react-native` | >= 0.76.0 | Yes |
+| `@tanstack/react-query` | >= 5.0.0 | Yes |
+| `react-hook-form` | >= 7.45.0 | Yes |
+| `@hookform/resolvers` | >= 3.3.0 | Yes |
+| `lucide-react-native` | >= 0.400.0 | Yes |
+| `@expo/ui` | >= 0.6.0 | Optional |
+| `expo-local-authentication` | >= 15.0.0 | Optional |
+| `expo-haptics` | >= 14.0.0 | Optional |
+| `react-native-reanimated` | >= 3.0.0 | Optional |
+
 ## Quick Start
 
-```typescript
-import { AuthClient } from "@atzentis/auth-sdk";
-import { withExpoAuth } from "@atzentis/auth-expo";
+Wrap your auth flow with `AuthProvider` and render screens via `AuthView`:
 
-const auth = new AuthClient({
-  apiKey: "atz_live_xxxxx",
-  baseUrl: "https://auth.atzentis.com",
-});
+```tsx
+import { AuthProvider, AuthView } from "@atzentis/auth-expo";
 
-const expoAuth = withExpoAuth(auth, {
-  scheme: "myapp-auth",
-  storagePrefix: "myapp-auth",
-  collectDeviceInfo: true,
-});
+export default function AuthScreen() {
+  return (
+    <AuthProvider baseUrl="https://auth.atzentis.com">
+      <AuthView initialRoute="login" />
+    </AuthProvider>
+  );
+}
 ```
 
-## Features
+For settings or organization screens, render them directly:
 
-- Secure token storage via `expo-secure-store`
-- Native device signal collection for security fingerprinting
-- OAuth deep linking support
-- Biometric authentication for session refresh (FaceID/TouchID)
+```tsx
+import { AuthProvider, ChangePasswordScreen } from "@atzentis/auth-expo";
 
-## Peer Dependencies
+export default function ChangePasswordPage() {
+  return (
+    <AuthProvider baseUrl="https://auth.atzentis.com">
+      <ChangePasswordScreen />
+    </AuthProvider>
+  );
+}
+```
+
+## Screens
+
+### Auth Screens
+
+| Screen | Description |
+| --- | --- |
+| `LoginScreen` | Email/password login with optional biometric sign-in |
+| `SignupScreen` | New account registration |
+| `PhoneLoginScreen` | Two-step phone number + OTP verification |
+| `MagicLinkScreen` | Multi-step passwordless magic link flow |
+| `TwoFactorScreen` | TOTP code entry with backup code fallback |
+| `ForgotPasswordScreen` | Email input with timed cooldown for resend |
+| `ResetPasswordScreen` | Token-based new password form |
+| `EmailVerificationScreen` | Auto-verify via deep link or manual OTP entry |
+
+Use `AuthView` to render any auth screen by route name:
 
-- `react` >= 18.0.0
-- `react-native` >= 0.73.0
-- `expo-device` >= 7.0.0
-- `expo-application` >= 6.0.0
-- `expo-secure-store` >= 14.0.0
+```tsx
+import { AuthView } from "@atzentis/auth-expo";
+
+// Renders the LoginScreen
+<AuthView initialRoute="login" />
+
+// Renders the SignupScreen
+<AuthView initialRoute="signup" />
+
+// Supported routes: "login" | "signup" | "phone-login" | "magic-link"
+//   "two-factor" | "forgot-password" | "reset-password" | "email-verification"
+```
+
+### Settings Screens
+
+| Screen | Description |
+| --- | --- |
+| `ChangePasswordScreen` | Update account password |
+| `ChangeEmailScreen` | Update email address with verification |
+| `UpdateNameScreen` | Update display name |
+| `UpdateUsernameScreen` | Update username |
+| `UpdateAvatarScreen` | Upload or select a profile avatar |
+| `SessionsScreen` | View and revoke active sessions |
+| `DeleteAccountScreen` | Multi-step account deletion with confirmation |
+| `TwoFactorSettingsScreen` | Enable, verify, or disable two-factor authentication |
+
+### Organization Screens
+
+| Screen | Description |
+| --- | --- |
+| `OrganizationSwitcherScreen` | List organizations and switch the active one |
+| `OrganizationMembersScreen` | View members, update roles, and remove members |
+
+## Components
+
+| Component | Description |
+| --- | --- |
+| `AuthGate` | Renders children only when a session exists; renders a fallback otherwise |
+| `ProtectedScreen` | RBAC guard — accepts `role` and `permission` props with a fallback |
+| `OAuthButton` | Native OAuth provider button (google, apple, github) |
+| `FormInput` | Styled text input for use inside auth forms |
+| `FormPasswordInput` | Password input with show/hide toggle |
+| `SubmitButton` | Loading-aware submit button |
+| `ErrorFeedback` | Accessible error message display |
+| `SuccessFeedback` | Accessible success message display |
+| `AuthContainer` | `KeyboardAvoidingView` layout wrapper for auth screens |
+
+## Hooks
+
+| Hook | Purpose |
+| --- | --- |
+| `useAuthClient()` | Access the underlying Better Auth client instance |
+| `useAuthLocalization()` | Access the active localization strings |
+| `useBiometric()` | Check biometric availability and trigger authentication |
+| `useAuthRedirect()` | Programmatic navigation using `expo-router`'s `router.replace` |
+
+### Mutation Hooks
+
+| Hook | Purpose |
+| --- | --- |
+| `useLogin()` | Sign in with email and password |
+| `useSignup()` | Create a new account |
+| `useLogout()` | Sign out the current session |
+| `useRequestPasswordReset()` | Request a password reset email |
+| `useResetPassword()` | Submit a new password using a reset token |
+
+### Query Hooks
+
+| Hook | Purpose |
+| --- | --- |
+| `useUser()` | Fetch the current user profile |
+| `useSession()` | Fetch the current session |
+
+## AuthProvider Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `baseUrl` | `string` | Required. The auth.atzentis.com URL |
+| `initialUser` | `User` | Optional. Pre-hydrated user for SSR |
+| `onSessionExpired` | `() => void` | Called when the session expires |
+| `onTokenRefreshed` | `(session: Session) => void` | Called after a successful token refresh |
+| `onNewDeviceAlert` | `(alert: LoginAlert) => void` | Called when a new device login is detected |
+
+## Localization
+
+All screens and components read from the shared `@atzentis/auth-locales` package. Override strings by passing a `localization` prop to `AuthProvider`:
+
+```tsx
+<AuthProvider
+  baseUrl="https://auth.atzentis.com"
+  localization={{
+    loginScreen: {
+      title: "Welcome back",
+      submitButton: "Continue",
+    },
+  }}
+>
+```
 
 ## Related Packages
 
-- [`@atzentis/auth-sdk`](https://www.npmjs.com/package/@atzentis/auth-sdk) - Core SDK (required)
-- [`@atzentis/auth-react`](https://www.npmjs.com/package/@atzentis/auth-react) - React hooks and components
+- [`@atzentis/auth-sdk`](https://www.npmjs.com/package/@atzentis/auth-sdk) — Core TypeScript client (required)
+- [`@atzentis/auth-react`](https://www.npmjs.com/package/@atzentis/auth-react) — React hooks and components for web
 
 ## License
 
-MIT
+MIT — see [LICENSE](../../LICENSE) for details.