@wattsoft/auth-app 1.0.1 → 1.0.2

package/README.md

@@ -1,33 +1,257 @@
-# Welcome to your Expo app 👋
+# @wattsoft/auth-app
 
-This is an [Expo](https://expo.dev) project created with [`create-expo-app`](https://www.npmjs.com/package/create-expo-app).
+A complete, production-ready authentication library for React Native and Expo apps.
 
-## Get started
+**Zero authentication code needed. Just import and use.** 🎉
 
-1. Install dependencies
+[![npm version](https://img.shields.io/npm/v/@wattsoft/auth-app.svg)](https://www.npmjs.com/package/@wattsoft/auth-app)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-   ```bash
-   npm install
-   ```
+## Features
 
-2. Start the app
+- ✅ **Pre-built Auth Screens** - Sign-in & sign-up screens, ready to use
+- ✅ **Email & Password Authentication** - Standard authentication flow
+- ✅ **Google Sign-In** - OAuth 2.0 integration
+- ✅ **Biometric Authentication** - Fingerprint & Face ID
+- ✅ **Passkey Support** - Passwordless authentication
+- ✅ **TypeScript** - Full type safety
+- ✅ **Secure Storage** - Encrypted token storage
+- ✅ **Clerk Integration** - Powered by Clerk
+- ✅ **Custom Hooks** - For advanced use cases
+- ✅ **Zero Config** - Works out of the box
 
-   ```bash
-   npx expo start
-   ```
+## Quick Start
 
-In the output, you'll find options to open the app in a
+### 1. Install
 
-- [development build](https://docs.expo.dev/develop/development-builds/introduction/)
-- [Android emulator](https://docs.expo.dev/workflow/android-studio-emulator/)
-- [iOS simulator](https://docs.expo.dev/workflow/ios-simulator/)
-- [Expo Go](https://expo.dev/go), a limited sandbox for trying out app development with Expo
+```bash
+npm install @wattsoft/auth-app
+```
+
+### 2. Setup
+
+```tsx
+import { AuthProvider } from "@wattsoft/auth-app";
+
+export default function App() {
+  return (
+    <AuthProvider publishableKey="pk_test_....">{/* Your app */}</AuthProvider>
+  );
+}
+```
+
+### 3. Use Screens
+
+```tsx
+import { SignInScreen, SignUpScreen } from '@wattsoft/auth-app';
+
+// In your navigation
+<Stack.Screen name="sign-in" component={SignInScreen} />
+<Stack.Screen name="sign-up" component={SignUpScreen} />
+```
+
+**That's it!** Your app now has complete authentication. ✅
+
+## Documentation
+
+- **[SETUP_GUIDE.md](./SETUP_GUIDE.md)** - Complete setup instructions
+- **[INTEGRATION_EXAMPLE.md](./INTEGRATION_EXAMPLE.md)** - Step-by-step integration guide
+- **[PUBLISHING_GUIDE.md](./PUBLISHING_GUIDE.md)** - How to publish to npm
+
+## Available Exports
+
+### Screens (Ready to Use)
+
+- `SignInScreen` - Complete sign-in UI
+- `SignUpScreen` - Complete sign-up UI
+
+### Components
+
+- `BiometricSignIn` - Biometric authentication UI
+- `GoogleSignIn` - Google OAuth UI
+- `Passkey` - Passkey authentication UI
+- `SignOut` - Sign-out button
+
+### Hooks (Custom Implementation)
+
+- `useAuth()` - Get auth state
+- `useSignInForm()` - Email/password sign-in
+- `useSignUpForm()` - Email/password sign-up
+- `useBiometric()` - Biometric auth
+- `useSignOutUser()` - Sign-out logic
+
+### Provider
+
+- `AuthProvider` - Setup component
+- `initializeAuth()` - Initialize auth
+
+## Example App Structure
+
+```tsx
+import {
+  AuthProvider,
+  useAuth,
+  SignInScreen,
+  SignUpScreen,
+} from "@wattsoft/auth-app";
+
+function AuthStack() {
+  return (
+    <Stack.Navigator screenOptions={{ headerShown: false }}>
+      <Stack.Screen name="sign-in" component={SignInScreen} />
+      <Stack.Screen name="sign-up" component={SignUpScreen} />
+    </Stack.Navigator>
+  );
+}
+
+function AppStack() {
+  return (
+    <Stack.Navigator>
+      <Stack.Screen name="home" component={HomeScreen} />
+    </Stack.Navigator>
+  );
+}
+
+function RootNavigator() {
+  const { isLoaded, isSignedIn } = useAuth();
+
+  if (!isLoaded) return null;
+
+  return (
+    <NavigationContainer>
+      {isSignedIn ? <AppStack /> : <AuthStack />}
+    </NavigationContainer>
+  );
+}
+
+export default function App() {
+  return (
+    <AuthProvider publishableKey={CLERK_PUBLISHABLE_KEY}>
+      <RootNavigator />
+    </AuthProvider>
+  );
+}
+```
+
+## Requirements
+
+- React 18.0+
+- React Native 0.70+
+- Expo 50+
+- Clerk account (free tier available)
+
+## Installation with Dependencies
+
+```bash
+npm install @wattsoft/auth-app expo-router @clerk/clerk-expo \
+  expo-local-authentication expo-secure-store @react-navigation/native \
+  react-native-gesture-handler react-native-reanimated \
+  react-native-safe-area-context react-native-screens
+```
+
+## Setup Clerk
+
+1. Create free account at [clerk.com](https://clerk.com)
+2. Create new application
+3. Get your Publishable Key
+4. Add to your app
+
+```tsx
+<AuthProvider publishableKey="pk_test_your_key_here">
+```
+
+## What's NOT Needed
+
+❌ No authentication logic to write  
+❌ No form validation to build  
+❌ No secure storage setup  
+❌ No OAuth configuration code  
+❌ No biometric handling code  
+❌ No error handling to implement
+
+✅ All included and ready to use!
+
+## API Reference
+
+### `<AuthProvider />`
+
+Wraps your app to enable authentication.
+
+```tsx
+<AuthProvider publishableKey={string}>{children}</AuthProvider>
+```
+
+### `useAuth()`
+
+Returns current authentication state.
+
+```tsx
+const { isLoaded, isSignedIn, user, session } = useAuth();
+```
+
+### `useSignInForm()`
+
+Returns sign-in methods.
+
+```tsx
+const { signInWithEmail, loading, error } = useSignInForm();
+await signInWithEmail("user@example.com", "password");
+```
+
+### `useSignOutUser()`
+
+Returns sign-out method.
+
+```tsx
+const { signOutUser, loading } = useSignOutUser();
+await signOutUser();
+```
+
+## Browser Support
+
+- ✅ iOS 11+
+- ✅ Android 6+
+- ✅ Web (experimental)
+
+## TypeScript
+
+Fully typed with TypeScript. All types exported from `@wattsoft/auth-app`.
+
+```tsx
+import type {
+  AuthState,
+  SignInResult,
+  UseSignInFormResult,
+} from "@wattsoft/auth-app";
+```
+
+## Troubleshooting
+
+See [SETUP_GUIDE.md#Troubleshooting](./SETUP_GUIDE.md#troubleshooting)
+
+## Contributing
+
+Found a bug? Have a feature request? Open an issue!
+
+## License
+
+MIT
+
+## Support
+
+- 📧 Email: support@wattsoft.com
+- 🐛 GitHub Issues: [Report a bug](https://github.com/wattsoft/auth-app/issues)
+- 📖 Docs: [SETUP_GUIDE.md](./SETUP_GUIDE.md)
+
+---
 
-You can start developing by editing the files inside the **app** directory. This project uses [file-based routing](https://docs.expo.dev/router/introduction).
+Made with ❤️ by Wattsoft
 
-## Get a fresh project
+**Quick Links:**
 
-When you're ready, run:
+- [npm Package](https://www.npmjs.com/package/@wattsoft/auth-app)
+- [GitHub Repository](https://github.com/wattsoft/auth-app)
+- [Clerk Documentation](https://clerk.com/docs)
 
 ```bash
 npm run reset-project

package/index.ts

@@ -0,0 +1,33 @@
+// Export all components from the auth-app package
+
+// ===== AUTHENTICATION PROVIDER & SETUP =====
+export { AuthProvider, initializeAuth } from "./lib/AuthProvider";
+
+// ===== CUSTOM HOOKS =====
+export {
+  useAuth, useBiometric, useSignInForm, useSignOutUser, useSignUpForm
+} from "./lib/hooks";
+
+// ===== TYPE DEFINITIONS =====
+export type {
+  AuthProviderProps,
+  AuthState, BiometricSignInProps, GoogleSignInProps,
+  PasskeyProps, SignInResult, SignOutButtonProps, SignOutResult, SignUpResult, UseBiometricResult, UseSignInFormResult, UseSignOutUserResult, UseSignUpFormResult
+} from "./lib/types";
+
+// ===== UI COMPONENTS =====
+export {
+  default as BiometricSignIn,
+  saveCredentialsForBiometric
+} from "./components/BiometricSignIn";
+export {
+  default as GoogleSignIn,
+  useWarmUpBrowser
+} from "./components/GoogleSignIn";
+export { SignInWithPasskeyButton as Passkey } from "./components/Passkey";
+export { SignOutButton as SignOut } from "./components/SignOut";
+
+// ===== READY-TO-USE SCREENS =====
+export { default as SignInScreen } from "./app/(app)/sign-in";
+export { default as SignUpScreen } from "./app/(app)/sign-up";
+

package/lib/AuthProvider.tsx

@@ -0,0 +1,70 @@
+import { ClerkProvider } from "@clerk/clerk-expo";
+import * as SecureStore from "expo-secure-store";
+import React, { ReactNode } from "react";
+
+interface AuthProviderProps {
+  children: ReactNode;
+  publishableKey: string;
+}
+
+/**
+ * AuthProvider - Setup component for the auth library
+ * Wrap your app with this provider
+ *
+ * Usage example:
+ * import { AuthProvider } from '@wattsoft/auth-app';
+ *
+ * export default function App() {
+ *   return (
+ *     <AuthProvider publishableKey={CLERK_PUBLISHABLE_KEY}>
+ *       {children}
+ *     </AuthProvider>
+ *   );
+ * }
+ */
+export function AuthProvider({ children, publishableKey }: AuthProviderProps) {
+  const tokenCache = {
+    async getToken(key: string) {
+      try {
+        const item = await SecureStore.getItemAsync(key);
+        if (item) {
+          console.log(`${key} was used securely`);
+        } else {
+          console.log("No values stored under key: " + key);
+        }
+        return item;
+      } catch (error) {
+        console.error("SecureStore read error: ", error);
+        await SecureStore.deleteItemAsync(key);
+        return null;
+      }
+    },
+    async saveToken(key: string, value: string) {
+      try {
+        await SecureStore.setItemAsync(key, value);
+      } catch (err) {
+        console.error("SecureStore error: ", err);
+      }
+    },
+  };
+
+  return (
+    <ClerkProvider publishableKey={publishableKey} tokenCache={tokenCache}>
+      {children}
+    </ClerkProvider>
+  );
+}
+
+/**
+ * Initialize auth library - Call this once in your app
+ * @param publishableKey - Your Clerk publishable key from https://dashboard.clerk.com
+ * @returns AuthProvider component
+ */
+export function initializeAuth(publishableKey: string) {
+  if (!publishableKey) {
+    throw new Error(
+      "Clerk publishable key is required. Get it from https://dashboard.clerk.com",
+    );
+  }
+  return publishableKey;
+}

package/lib/hooks.ts

@@ -0,0 +1,245 @@
+import {
+    useClerk,
+    useAuth as useClerkAuth,
+    useSession,
+    useSignIn,
+    useSignUp,
+    useUser,
+} from "@clerk/clerk-expo";
+import * as LocalAuthentication from "expo-local-authentication";
+import { useRouter } from "expo-router";
+import React from "react";
+
+/**
+ * useAuth - Get current authentication state
+ * @returns Object with user, isLoaded, isSignedIn
+ */
+export function useAuth() {
+  const { isLoaded, isSignedIn } = useClerkAuth();
+  const { user } = useUser();
+  const { session } = useSession();
+
+  return {
+    isLoaded,
+    isSignedIn,
+    user,
+    session,
+  };
+}
+
+/**
+ * useSignInForm - Handle email/password sign in
+ * @returns Object with methods and state for sign in
+ */
+export function useSignInForm() {
+  const { signIn, setActive, isLoaded } = useSignIn();
+  const router = useRouter();
+  const [loading, setLoading] = React.useState(false);
+  const [error, setError] = React.useState<string | null>(null);
+
+  const signInWithEmail = React.useCallback(
+    async (email: string, password: string) => {
+      if (!isLoaded) return;
+      setLoading(true);
+      setError(null);
+
+      try {
+        const signInAttempt = await signIn.create({
+          identifier: email,
+          password,
+        });
+
+        if (signInAttempt.status === "complete") {
+          await setActive({
+            session: signInAttempt.createdSessionId,
+          });
+          router.replace("/");
+          return { success: true };
+        } else {
+          setError("Sign in incomplete. Please try again.");
+          return { success: false, status: signInAttempt.status };
+        }
+      } catch (err: any) {
+        const errorMessage =
+          err?.errors?.[0]?.message || err.message || "Sign in failed";
+        setError(errorMessage);
+        return { success: false, error: errorMessage };
+      } finally {
+        setLoading(false);
+      }
+    },
+    [isLoaded, signIn, setActive, router],
+  );
+
+  return {
+    signInWithEmail,
+    loading,
+    error,
+    setError,
+  };
+}
+
+/**
+ * useSignUpForm - Handle email/password sign up
+ * @returns Object with methods and state for sign up
+ */
+export function useSignUpForm() {
+  const { signUp, setActive, isLoaded } = useSignUp();
+  const router = useRouter();
+  const [loading, setLoading] = React.useState(false);
+  const [error, setError] = React.useState<string | null>(null);
+
+  const signUpWithEmail = React.useCallback(
+    async (
+      email: string,
+      password: string,
+      firstName?: string,
+      lastName?: string,
+    ) => {
+      if (!isLoaded) return;
+      setLoading(true);
+      setError(null);
+
+      try {
+        const signUpAttempt = await signUp.create({
+          emailAddress: email,
+          password,
+          firstName,
+          lastName,
+        });
+
+        if (signUpAttempt.status === "complete") {
+          await setActive?.({
+            session: signUpAttempt.createdSessionId,
+          });
+          router.replace("/");
+          return { success: true };
+        }
+
+        router.push({
+          pathname: "/sign-up",
+          params: { email },
+        });
+
+        return { success: true };
+      } catch (err: any) {
+        const errorMessage =
+          err?.errors?.[0]?.message || err.message || "Sign up failed";
+        setError(errorMessage);
+        return { success: false, error: errorMessage };
+      } finally {
+        setLoading(false);
+      }
+    },
+    [isLoaded, signUp, router, setActive],
+  );
+
+  return {
+    signUpWithEmail,
+    loading,
+    error,
+    setError,
+  };
+}
+
+/**
+ * useBiometric - Handle biometric authentication
+ * @returns Object with methods for biometric sign in
+ */
+export function useBiometric() {
+  const { signIn, setActive, isLoaded } = useSignIn();
+  const router = useRouter();
+  const [loading, setLoading] = React.useState(false);
+  const [error, setError] = React.useState<string | null>(null);
+  const [isBiometricAvailable, setIsBiometricAvailable] = React.useState(false);
+
+  React.useEffect(() => {
+    checkBiometricAvailability();
+  }, []);
+
+  const checkBiometricAvailability = async () => {
+    try {
+      const compatible = await LocalAuthentication.hasHardwareAsync();
+      const enrolled = await LocalAuthentication.isEnrolledAsync();
+      setIsBiometricAvailable(compatible && enrolled);
+    } catch (err) {
+      setIsBiometricAvailable(false);
+    }
+  };
+
+  const signInWithBiometric = React.useCallback(
+    async (email: string, password: string) => {
+      if (!isLoaded) return;
+      setLoading(true);
+      setError(null);
+
+      try {
+        const authenticated = await LocalAuthentication.authenticateAsync({
+          disableDeviceFallback: false,
+          fallbackLabel: "Use passcode",
+        });
+
+        if (authenticated.success) {
+          const signInAttempt = await signIn.create({
+            identifier: email,
+            password,
+          });
+
+          if (signInAttempt.status === "complete") {
+            await setActive({
+              session: signInAttempt.createdSessionId,
+            });
+            router.replace("/");
+            return { success: true };
+          }
+        } else {
+          setError("Biometric authentication cancelled");
+          return { success: false, error: "Cancelled" };
+        }
+      } catch (err: any) {
+        const errorMessage = err?.message || "Biometric sign in failed";
+        setError(errorMessage);
+        return { success: false, error: errorMessage };
+      } finally {
+        setLoading(false);
+      }
+    },
+    [isLoaded, signIn, setActive, router],
+  );
+
+  return {
+    signInWithBiometric,
+    isBiometricAvailable,
+    loading,
+    error,
+    setError,
+  };
+}
+
+/**
+ * useSignOutUser - Handle user sign out
+ * @returns Object with sign out method
+ */
+export function useSignOutUser() {
+  const { signOut } = useClerk();
+  const router = useRouter();
+  const [loading, setLoading] = React.useState(false);
+
+  const signOutUser = React.useCallback(async () => {
+    setLoading(true);
+    try {
+      await signOut();
+      router.replace("/sign-in");
+      return { success: true };
+    } catch (err: any) {
+      return { success: false, error: err.message };
+    } finally {
+      setLoading(false);
+    }
+  }, [signOut, router]);
+
+  return {
+    signOutUser,
+    loading,
+  };
+}

package/lib/types.ts

@@ -0,0 +1,131 @@
+/**
+ * Type definitions for @wattsoft/auth-app
+ */
+
+import { ReactNode } from "react";
+
+/**
+ * Props for AuthProvider component
+ */
+export interface AuthProviderProps {
+  children: ReactNode;
+  publishableKey: string;
+}
+
+/**
+ * Return type for sign-in operations
+ */
+export interface SignInResult {
+  success: boolean;
+  status?: string;
+  error?: string;
+  createdSessionId?: string;
+}
+
+/**
+ * Return type for sign-up operations
+ */
+export interface SignUpResult {
+  success: boolean;
+  error?: string;
+  emailAddress?: string;
+}
+
+/**
+ * Return type for sign-out operations
+ */
+export interface SignOutResult {
+  success: boolean;
+  error?: string;
+}
+
+/**
+ * Authentication state from useAuth hook
+ */
+export interface AuthState {
+  isLoaded: boolean;
+  isSignedIn: boolean | undefined;
+  user: any;
+  session: any;
+}
+
+/**
+ * Sign-in form hook return type
+ */
+export interface UseSignInFormResult {
+  signInWithEmail: (email: string, password: string) => Promise<SignInResult>;
+  loading: boolean;
+  error: string | null;
+  setError: (error: string | null) => void;
+}
+
+/**
+ * Sign-up form hook return type
+ */
+export interface UseSignUpFormResult {
+  signUpWithEmail: (
+    email: string,
+    password: string,
+    firstName?: string,
+    lastName?: string,
+  ) => Promise<SignUpResult>;
+  loading: boolean;
+  error: string | null;
+  setError: (error: string | null) => void;
+}
+
+/**
+ * Biometric authentication hook return type
+ */
+export interface UseBiometricResult {
+  signInWithBiometric: (
+    email: string,
+    password: string,
+  ) => Promise<SignInResult>;
+  isBiometricAvailable: boolean;
+  loading: boolean;
+  error: string | null;
+  setError: (error: string | null) => void;
+}
+
+/**
+ * Sign-out hook return type
+ */
+export interface UseSignOutUserResult {
+  signOutUser: () => Promise<SignOutResult>;
+  loading: boolean;
+}
+
+/**
+ * Google Sign-In props
+ */
+export interface GoogleSignInProps {
+  onSuccess?: (result: any) => void;
+  onError?: (error: any) => void;
+}
+
+/**
+ * Passkey authentication props
+ */
+export interface PasskeyProps {
+  onSuccess?: (result: any) => void;
+  onError?: (error: any) => void;
+}
+
+/**
+ * Sign-out button props
+ */
+export interface SignOutButtonProps {
+  onSuccess?: () => void;
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Biometric sign-in component props
+ */
+export interface BiometricSignInProps {
+  onSuccess?: (result: any) => void;
+  onError?: (error: Error) => void;
+  email?: string;
+  password?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wattsoft/auth-app",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Reusable authentication components for Expo/React Native apps with Clerk, biometric, Google sign-in, and passkey support",
   "license": "MIT",
   "author": "Wattsoft",
@@ -47,8 +47,10 @@
   "files": [
     "dist",
     "components",
+    "lib",
     "app",
-    "assets"
+    "assets",
+    "index.ts"
   ],
   "keywords": [
     "react",