@croacroa/react-native-template 1.0.0 → 2.0.1

package/docs/adr/004-auth-adapter-pattern.md

@@ -1,144 +1,144 @@
-# ADR-004: Auth Adapter Pattern for Authentication
-
-## Status
-
-Accepted
-
-## Date
-
-2024-01-15
-
-## Context
-
-The template needs to support multiple authentication providers (Supabase, Firebase, Auth0, custom backends) without requiring significant code changes. We need:
-
-1. Easy switching between auth providers
-2. Consistent API regardless of provider
-3. Type safety
-4. Testability with mock implementations
-
-## Decision
-
-Implement an **Adapter Pattern** for authentication that abstracts the auth provider behind a common interface.
-
-## Rationale
-
-1. **Flexibility**: Change auth providers without touching app code
-2. **Testing**: Easy to mock for unit tests
-3. **Consistency**: Same API for all providers
-4. **Gradual Migration**: Can switch providers incrementally
-
-## Implementation
-
-### Interface Definition
-
-```typescript
-// services/authAdapter.ts
-export interface AuthAdapter {
-  signIn(email: string, password: string): Promise<AuthResult>;
-  signUp(email: string, password: string, name: string): Promise<AuthResult>;
-  signOut(): Promise<void>;
-  refreshToken(refreshToken: string): Promise<AuthTokens>;
-  forgotPassword(email: string): Promise<void>;
-  resetPassword(token: string, newPassword: string): Promise<void>;
-  getSession(): Promise<AuthResult | null>;
-  onAuthStateChange?(callback: (user: User | null) => void): () => void;
-}
-
-export interface AuthResult {
-  user: User;
-  tokens: AuthTokens;
-}
-```
-
-### Mock Implementation
-
-```typescript
-export const mockAuthAdapter: AuthAdapter = {
-  async signIn(email, password) {
-    await delay(1000); // Simulate network
-    return {
-      user: { id: '1', email, name: email.split('@')[0] },
-      tokens: { accessToken: 'mock', refreshToken: 'mock', expiresAt: ... },
-    };
-  },
-  // ... other methods
-};
-```
-
-### Supabase Implementation
-
-```typescript
-export const supabaseAuthAdapter: AuthAdapter = {
-  async signIn(email, password) {
-    const { data, error } = await supabase.auth.signInWithPassword({
-      email,
-      password,
-    });
-    if (error) throw error;
-    return transformSupabaseSession(data);
-  },
-  // ... other methods
-};
-```
-
-### Usage
-
-```typescript
-// services/authAdapter.ts
-// Change this line to switch providers
-export const authAdapter: AuthAdapter = mockAuthAdapter;
-// export const authAdapter: AuthAdapter = supabaseAuthAdapter;
-// export const authAdapter: AuthAdapter = firebaseAuthAdapter;
-```
-
-## Consequences
-
-### Positive
-
-- Provider-agnostic code
-- Easy to test with mocks
-- Clear contract for auth operations
-- Can support multiple providers simultaneously
-
-### Negative
-
-- Some provider-specific features may not fit the interface
-- Additional abstraction layer
-- Need to maintain multiple implementations
-
-### Mitigation
-
-- Allow optional methods in interface
-- Document provider-specific extensions
-- Keep interface focused on common operations
-
-## Testing
-
-```typescript
-// __tests__/auth.test.ts
-import { mockAuthAdapter } from "@/services/authAdapter";
-
-describe("Auth", () => {
-  it("signs in successfully", async () => {
-    const result = await mockAuthAdapter.signIn("test@example.com", "password");
-    expect(result.user.email).toBe("test@example.com");
-    expect(result.tokens.accessToken).toBeDefined();
-  });
-});
-```
-
-## Migration Guide
-
-To switch from mock to Supabase:
-
-1. Install Supabase: `npx expo install @supabase/supabase-js`
-2. Configure environment variables
-3. Implement `supabaseAuthAdapter`
-4. Update export in `authAdapter.ts`
-
-## References
-
-- [Adapter Pattern](https://refactoring.guru/design-patterns/adapter)
-- [Supabase Auth](https://supabase.com/docs/guides/auth)
-- [Firebase Auth](https://firebase.google.com/docs/auth)
+# ADR-004: Auth Adapter Pattern for Authentication
+
+## Status
+
+Accepted
+
+## Date
+
+2024-01-15
+
+## Context
+
+The template needs to support multiple authentication providers (Supabase, Firebase, Auth0, custom backends) without requiring significant code changes. We need:
+
+1. Easy switching between auth providers
+2. Consistent API regardless of provider
+3. Type safety
+4. Testability with mock implementations
+
+## Decision
+
+Implement an **Adapter Pattern** for authentication that abstracts the auth provider behind a common interface.
+
+## Rationale
+
+1. **Flexibility**: Change auth providers without touching app code
+2. **Testing**: Easy to mock for unit tests
+3. **Consistency**: Same API for all providers
+4. **Gradual Migration**: Can switch providers incrementally
+
+## Implementation
+
+### Interface Definition
+
+```typescript
+// services/authAdapter.ts
+export interface AuthAdapter {
+  signIn(email: string, password: string): Promise<AuthResult>;
+  signUp(email: string, password: string, name: string): Promise<AuthResult>;
+  signOut(): Promise<void>;
+  refreshToken(refreshToken: string): Promise<AuthTokens>;
+  forgotPassword(email: string): Promise<void>;
+  resetPassword(token: string, newPassword: string): Promise<void>;
+  getSession(): Promise<AuthResult | null>;
+  onAuthStateChange?(callback: (user: User | null) => void): () => void;
+}
+
+export interface AuthResult {
+  user: User;
+  tokens: AuthTokens;
+}
+```
+
+### Mock Implementation
+
+```typescript
+export const mockAuthAdapter: AuthAdapter = {
+  async signIn(email, password) {
+    await delay(1000); // Simulate network
+    return {
+      user: { id: '1', email, name: email.split('@')[0] },
+      tokens: { accessToken: 'mock', refreshToken: 'mock', expiresAt: ... },
+    };
+  },
+  // ... other methods
+};
+```
+
+### Supabase Implementation
+
+```typescript
+export const supabaseAuthAdapter: AuthAdapter = {
+  async signIn(email, password) {
+    const { data, error } = await supabase.auth.signInWithPassword({
+      email,
+      password,
+    });
+    if (error) throw error;
+    return transformSupabaseSession(data);
+  },
+  // ... other methods
+};
+```
+
+### Usage
+
+```typescript
+// services/authAdapter.ts
+// Change this line to switch providers
+export const authAdapter: AuthAdapter = mockAuthAdapter;
+// export const authAdapter: AuthAdapter = supabaseAuthAdapter;
+// export const authAdapter: AuthAdapter = firebaseAuthAdapter;
+```
+
+## Consequences
+
+### Positive
+
+- Provider-agnostic code
+- Easy to test with mocks
+- Clear contract for auth operations
+- Can support multiple providers simultaneously
+
+### Negative
+
+- Some provider-specific features may not fit the interface
+- Additional abstraction layer
+- Need to maintain multiple implementations
+
+### Mitigation
+
+- Allow optional methods in interface
+- Document provider-specific extensions
+- Keep interface focused on common operations
+
+## Testing
+
+```typescript
+// __tests__/auth.test.ts
+import { mockAuthAdapter } from "@/services/authAdapter";
+
+describe("Auth", () => {
+  it("signs in successfully", async () => {
+    const result = await mockAuthAdapter.signIn("test@example.com", "password");
+    expect(result.user.email).toBe("test@example.com");
+    expect(result.tokens.accessToken).toBeDefined();
+  });
+});
+```
+
+## Migration Guide
+
+To switch from mock to Supabase:
+
+1. Install Supabase: `npx expo install @supabase/supabase-js`
+2. Configure environment variables
+3. Implement `supabaseAuthAdapter`
+4. Update export in `authAdapter.ts`
+
+## References
+
+- [Adapter Pattern](https://refactoring.guru/design-patterns/adapter)
+- [Supabase Auth](https://supabase.com/docs/guides/auth)
+- [Firebase Auth](https://firebase.google.com/docs/auth)

package/docs/adr/README.md

@@ -1,78 +1,78 @@
-# Architecture Decision Records (ADRs)
-
-This directory contains Architecture Decision Records (ADRs) documenting significant technical decisions made in this project.
-
-## What is an ADR?
-
-An ADR is a document that captures an important architectural decision made along with its context and consequences.
-
-## ADR Template
-
-```markdown
-# ADR-XXX: Title
-
-## Status
-
-[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
-
-## Date
-
-YYYY-MM-DD
-
-## Context
-
-[What is the issue that we're seeing that is motivating this decision?]
-
-## Decision
-
-[What is the change that we're proposing and/or doing?]
-
-## Consequences
-
-### Positive
-
-[What are the benefits?]
-
-### Negative
-
-[What are the drawbacks?]
-
-### Mitigation
-
-[How do we address the drawbacks?]
-
-## References
-
-[Links to relevant documentation, articles, or discussions]
-```
-
-## Index
-
-| ADR                                  | Title                             | Status   | Date       |
-| ------------------------------------ | --------------------------------- | -------- | ---------- |
-| [001](./001-state-management.md)     | Use Zustand for State Management  | Accepted | 2024-01-01 |
-| [002](./002-styling-approach.md)     | Use NativeWind for Styling        | Accepted | 2024-01-01 |
-| [003](./003-data-fetching.md)        | Use React Query for Data Fetching | Accepted | 2024-01-01 |
-| [004](./004-auth-adapter-pattern.md) | Auth Adapter Pattern              | Accepted | 2024-01-15 |
-
-## When to Write an ADR
-
-Write an ADR when:
-
-1. Making a significant architectural decision
-2. Choosing between multiple valid options
-3. The decision will be hard to change later
-4. Team members need to understand "why"
-
-## How to Create a New ADR
-
-1. Copy the template above
-2. Number it sequentially (e.g., `005-your-decision.md`)
-3. Fill in all sections
-4. Add it to the index in this README
-5. Submit for review with your PR
-
-## Resources
-
-- [ADR GitHub Organization](https://adr.github.io/)
-- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
+# Architecture Decision Records (ADRs)
+
+This directory contains Architecture Decision Records (ADRs) documenting significant technical decisions made in this project.
+
+## What is an ADR?
+
+An ADR is a document that captures an important architectural decision made along with its context and consequences.
+
+## ADR Template
+
+```markdown
+# ADR-XXX: Title
+
+## Status
+
+[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
+
+## Date
+
+YYYY-MM-DD
+
+## Context
+
+[What is the issue that we're seeing that is motivating this decision?]
+
+## Decision
+
+[What is the change that we're proposing and/or doing?]
+
+## Consequences
+
+### Positive
+
+[What are the benefits?]
+
+### Negative
+
+[What are the drawbacks?]
+
+### Mitigation
+
+[How do we address the drawbacks?]
+
+## References
+
+[Links to relevant documentation, articles, or discussions]
+```
+
+## Index
+
+| ADR                                  | Title                             | Status   | Date       |
+| ------------------------------------ | --------------------------------- | -------- | ---------- |
+| [001](./001-state-management.md)     | Use Zustand for State Management  | Accepted | 2024-01-01 |
+| [002](./002-styling-approach.md)     | Use NativeWind for Styling        | Accepted | 2024-01-01 |
+| [003](./003-data-fetching.md)        | Use React Query for Data Fetching | Accepted | 2024-01-01 |
+| [004](./004-auth-adapter-pattern.md) | Auth Adapter Pattern              | Accepted | 2024-01-15 |
+
+## When to Write an ADR
+
+Write an ADR when:
+
+1. Making a significant architectural decision
+2. Choosing between multiple valid options
+3. The decision will be hard to change later
+4. Team members need to understand "why"
+
+## How to Create a New ADR
+
+1. Copy the template above
+2. Number it sequentially (e.g., `005-your-decision.md`)
+3. Fill in all sections
+4. Add it to the index in this README
+5. Submit for review with your PR
+
+## Resources
+
+- [ADR GitHub Organization](https://adr.github.io/)
+- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)

package/hooks/index.ts

@@ -1,25 +1,27 @@
-export { useAuth, AuthProvider, getAuthToken } from "./useAuth";
-export { useTheme, ThemeProvider } from "./useTheme";
-export { useNotifications } from "./useNotifications";
-export {
-  useCurrentUser,
-  useUser,
-  useUpdateUser,
-  queryKeys,
-  createCrudHooks,
-  postsApi,
-} from "./useApi";
-export {
-  useDeepLinking,
-  createDeepLink,
-  getDeepLinkPrefix,
-} from "./useDeepLinking";
-export { useBiometrics, getBiometricName } from "./useBiometrics";
-export { useOffline, usePendingMutations } from "./useOffline";
-export { useUpdates, getUpdateInfo, forceUpdate } from "./useUpdates";
-export {
-  usePerformance,
-  measureAsync,
-  measureSync,
-  runAfterInteractions,
-} from "./usePerformance";
+export { useAuth, AuthProvider, getAuthToken } from "./useAuth";
+export { useTheme, ThemeProvider } from "./useTheme";
+export { useNotifications } from "./useNotifications";
+export {
+  useCurrentUser,
+  useUser,
+  useUpdateUser,
+  queryKeys,
+  createCrudHooks,
+  postsApi,
+} from "./useApi";
+export {
+  useDeepLinking,
+  createDeepLink,
+  getDeepLinkPrefix,
+} from "./useDeepLinking";
+export { useBiometrics, getBiometricName } from "./useBiometrics";
+export { useOffline, usePendingMutations } from "./useOffline";
+export { useUpdates, getUpdateInfo, forceUpdate } from "./useUpdates";
+export {
+  usePerformance,
+  measureAsync,
+  measureSync,
+  runAfterInteractions,
+} from "./usePerformance";
+export { useMFA, generateTOTP } from "./useMFA";
+export type { MFAMethod, MFASetupData } from "./useMFA";

package/hooks/useApi.ts

@@ -1,3 +1,9 @@
+/**
+ * @fileoverview Data fetching hooks built on TanStack Query
+ * Provides type-safe query keys, user hooks, and a CRUD factory for rapid API integration.
+ * @module hooks/useApi
+ */
+
 import {
   useQuery,
   useMutation,
@@ -8,7 +14,19 @@ import {
 import { api } from "@/services/api";
 import { toast, handleApiError } from "@/utils/toast";
 
-// Query keys factory for type-safe and organized cache management
+/**
+ * Query keys factory for type-safe and organized cache management.
+ * Use these keys with React Query to ensure consistent cache invalidation.
+ *
+ * @example
+ * ```ts
+ * // Invalidate all user queries
+ * queryClient.invalidateQueries({ queryKey: queryKeys.users.all });
+ *
+ * // Invalidate specific user
+ * queryClient.invalidateQueries({ queryKey: queryKeys.users.detail('123') });
+ * ```
+ */
 export const queryKeys = {
   all: ["api"] as const,
   users: {
@@ -45,7 +63,23 @@ interface User {
 }
 
 /**
- * Fetch current user profile
+ * Fetch current user profile.
+ * Automatically caches the result for 5 minutes.
+ *
+ * @param options - Additional React Query options
+ * @returns Query result with user data, loading state, and error
+ *
+ * @example
+ * ```tsx
+ * function Profile() {
+ *   const { data: user, isLoading, error } = useCurrentUser();
+ *
+ *   if (isLoading) return <Skeleton />;
+ *   if (error) return <ErrorMessage error={error} />;
+ *
+ *   return <Text>Hello, {user.name}</Text>;
+ * }
+ * ```
  */
 export function useCurrentUser(
   options?: Omit<UseQueryOptions<User, Error>, "queryKey" | "queryFn">
@@ -59,7 +93,20 @@ export function useCurrentUser(
 }
 
 /**
- * Fetch user by ID
+ * Fetch a user by their ID.
+ * Query is automatically disabled if no userId is provided.
+ *
+ * @param userId - The unique identifier of the user to fetch
+ * @param options - Additional React Query options
+ * @returns Query result with user data, loading state, and error
+ *
+ * @example
+ * ```tsx
+ * function UserProfile({ userId }: { userId: string }) {
+ *   const { data: user, isLoading } = useUser(userId);
+ *   return isLoading ? <Skeleton /> : <Avatar name={user?.name} />;
+ * }
+ * ```
  */
 export function useUser(
   userId: string,
@@ -74,7 +121,27 @@ export function useUser(
 }
 
 /**
- * Update user profile
+ * Update the current user's profile.
+ * Automatically updates the cache and shows a success/error toast.
+ *
+ * @returns Mutation object with mutate function and state
+ *
+ * @example
+ * ```tsx
+ * function EditProfile() {
+ *   const updateUser = useUpdateUser();
+ *
+ *   const handleSave = () => {
+ *     updateUser.mutate({ name: 'New Name' });
+ *   };
+ *
+ *   return (
+ *     <Button onPress={handleSave} isLoading={updateUser.isPending}>
+ *       Save
+ *     </Button>
+ *   );
+ * }
+ * ```
  */
 export function useUpdateUser() {
   const queryClient = useQueryClient();
@@ -103,7 +170,37 @@ interface CrudHooksConfig<T, CreateDTO, UpdateDTO> {
 }
 
 /**
- * Factory to create CRUD hooks for any resource
+ * Factory to create CRUD hooks for any resource.
+ * Generates useList, useById, useCreate, useUpdate, and useDelete hooks
+ * with automatic cache management and toast notifications.
+ *
+ * @typeParam T - The entity type (must have an 'id' field)
+ * @typeParam CreateDTO - The type for create operations (defaults to Omit<T, 'id'>)
+ * @typeParam UpdateDTO - The type for update operations (defaults to Partial<T>)
+ * @param config - Configuration object with baseKey, endpoint, and entityName
+ * @returns Object containing all CRUD hooks
+ *
+ * @example
+ * ```ts
+ * interface Product {
+ *   id: string;
+ *   name: string;
+ *   price: number;
+ * }
+ *
+ * export const productsApi = createCrudHooks<Product>({
+ *   baseKey: ['products'],
+ *   endpoint: '/products',
+ *   entityName: 'Product',
+ * });
+ *
+ * // Usage in components:
+ * const { data: products } = productsApi.useList();
+ * const { data: product } = productsApi.useById('123');
+ * const createProduct = productsApi.useCreate();
+ * const updateProduct = productsApi.useUpdate();
+ * const deleteProduct = productsApi.useDelete();
+ * ```
  */
 export function createCrudHooks<
   T extends { id: string },