@croacroa/react-native-template 1.0.0

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

@@ -0,0 +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)

package/docs/adr/README.md

@@ -0,0 +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)

package/eas.json

@@ -0,0 +1,47 @@
+{
+  "cli": {
+    "version": ">= 10.0.0"
+  },
+  "build": {
+    "development": {
+      "developmentClient": true,
+      "distribution": "internal",
+      "env": {
+        "APP_VARIANT": "development"
+      },
+      "ios": {
+        "simulator": true
+      },
+      "android": {
+        "buildType": "apk"
+      }
+    },
+    "preview": {
+      "distribution": "internal",
+      "env": {
+        "APP_VARIANT": "preview"
+      },
+      "android": {
+        "buildType": "apk"
+      }
+    },
+    "production": {
+      "autoIncrement": true,
+      "env": {
+        "APP_VARIANT": "production"
+      }
+    }
+  },
+  "submit": {
+    "production": {
+      "ios": {
+        "appleId": "your-apple-id@email.com",
+        "ascAppId": "your-app-store-connect-app-id"
+      },
+      "android": {
+        "serviceAccountKeyPath": "./google-services.json",
+        "track": "internal"
+      }
+    }
+  }
+}

package/global.css

@@ -0,0 +1,10 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* Custom utility classes */
+@layer utilities {
+  .text-balance {
+    text-wrap: balance;
+  }
+}

package/hooks/index.ts

@@ -0,0 +1,25 @@
+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";

package/hooks/useApi.ts

@@ -0,0 +1,236 @@
+import {
+  useQuery,
+  useMutation,
+  useQueryClient,
+  UseQueryOptions,
+  UseMutationOptions,
+} from "@tanstack/react-query";
+import { api } from "@/services/api";
+import { toast, handleApiError } from "@/utils/toast";
+
+// Query keys factory for type-safe and organized cache management
+export const queryKeys = {
+  all: ["api"] as const,
+  users: {
+    all: ["users"] as const,
+    detail: (id: string) => ["users", id] as const,
+    me: () => ["users", "me"] as const,
+  },
+  posts: {
+    all: ["posts"] as const,
+    list: (filters: Record<string, unknown>) => ["posts", "list", filters] as const,
+    detail: (id: string) => ["posts", id] as const,
+  },
+  // Add more query keys as needed
+} as const;
+
+// Generic types for API responses
+interface PaginatedResponse<T> {
+  data: T[];
+  page: number;
+  pageSize: number;
+  total: number;
+  totalPages: number;
+}
+
+// ===========================================
+// User Hooks
+// ===========================================
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  avatar?: string;
+}
+
+/**
+ * Fetch current user profile
+ */
+export function useCurrentUser(
+  options?: Omit<UseQueryOptions<User, Error>, "queryKey" | "queryFn">
+) {
+  return useQuery({
+    queryKey: queryKeys.users.me(),
+    queryFn: () => api.get<User>("/users/me"),
+    staleTime: 1000 * 60 * 5, // 5 minutes
+    ...options,
+  });
+}
+
+/**
+ * Fetch user by ID
+ */
+export function useUser(
+  userId: string,
+  options?: Omit<UseQueryOptions<User, Error>, "queryKey" | "queryFn">
+) {
+  return useQuery({
+    queryKey: queryKeys.users.detail(userId),
+    queryFn: () => api.get<User>(`/users/${userId}`),
+    enabled: !!userId,
+    ...options,
+  });
+}
+
+/**
+ * Update user profile
+ */
+export function useUpdateUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data: Partial<User>) => api.patch<User>("/users/me", data),
+    onSuccess: (updatedUser) => {
+      // Update cache
+      queryClient.setQueryData(queryKeys.users.me(), updatedUser);
+      toast.success("Profile updated");
+    },
+    onError: (error) => {
+      handleApiError(error, "Failed to update profile");
+    },
+  });
+}
+
+// ===========================================
+// Generic CRUD Hooks Factory
+// ===========================================
+
+interface CrudHooksConfig<T, CreateDTO, UpdateDTO> {
+  baseKey: readonly string[];
+  endpoint: string;
+  entityName: string;
+}
+
+/**
+ * Factory to create CRUD hooks for any resource
+ */
+export function createCrudHooks<
+  T extends { id: string },
+  CreateDTO = Omit<T, "id">,
+  UpdateDTO = Partial<T>
+>(config: CrudHooksConfig<T, CreateDTO, UpdateDTO>) {
+  const { baseKey, endpoint, entityName } = config;
+
+  // Helper to build URL with query params
+  const buildUrl = (base: string, params?: Record<string, unknown>) => {
+    if (!params || Object.keys(params).length === 0) return base;
+    const searchParams = new URLSearchParams();
+    Object.entries(params).forEach(([key, value]) => {
+      if (value !== undefined && value !== null) {
+        searchParams.append(key, String(value));
+      }
+    });
+    return `${base}?${searchParams.toString()}`;
+  };
+
+  return {
+    // List all
+    useList: (
+      filters?: Record<string, unknown>,
+      options?: Omit<UseQueryOptions<T[], Error>, "queryKey" | "queryFn">
+    ) =>
+      useQuery({
+        queryKey: [...baseKey, "list", filters],
+        queryFn: () => api.get<T[]>(buildUrl(endpoint, filters)),
+        ...options,
+      }),
+
+    // Get by ID
+    useById: (
+      id: string,
+      options?: Omit<UseQueryOptions<T, Error>, "queryKey" | "queryFn">
+    ) =>
+      useQuery({
+        queryKey: [...baseKey, id],
+        queryFn: () => api.get<T>(`${endpoint}/${id}`),
+        enabled: !!id,
+        ...options,
+      }),
+
+    // Create
+    useCreate: (
+      options?: Omit<UseMutationOptions<T, Error, CreateDTO>, "mutationFn">
+    ) => {
+      const queryClient = useQueryClient();
+      return useMutation({
+        mutationFn: (data: CreateDTO) =>
+          api.post<T>(endpoint, data as Record<string, unknown>),
+        onSuccess: () => {
+          queryClient.invalidateQueries({ queryKey: baseKey });
+          toast.success(`${entityName} created`);
+        },
+        onError: (error) => {
+          handleApiError(error, `Failed to create ${entityName.toLowerCase()}`);
+        },
+        ...options,
+      });
+    },
+
+    // Update
+    useUpdate: (
+      options?: Omit<
+        UseMutationOptions<T, Error, { id: string; data: UpdateDTO }>,
+        "mutationFn"
+      >
+    ) => {
+      const queryClient = useQueryClient();
+      return useMutation({
+        mutationFn: ({ id, data }: { id: string; data: UpdateDTO }) =>
+          api.patch<T>(`${endpoint}/${id}`, data as Record<string, unknown>),
+        onSuccess: (_, { id }) => {
+          queryClient.invalidateQueries({ queryKey: [...baseKey, id] });
+          queryClient.invalidateQueries({ queryKey: [...baseKey, "list"] });
+          toast.success(`${entityName} updated`);
+        },
+        onError: (error) => {
+          handleApiError(error, `Failed to update ${entityName.toLowerCase()}`);
+        },
+        ...options,
+      });
+    },
+
+    // Delete
+    useDelete: (
+      options?: Omit<UseMutationOptions<void, Error, string>, "mutationFn">
+    ) => {
+      const queryClient = useQueryClient();
+      return useMutation({
+        mutationFn: (id: string) => api.delete<void>(`${endpoint}/${id}`),
+        onSuccess: () => {
+          queryClient.invalidateQueries({ queryKey: baseKey });
+          toast.success(`${entityName} deleted`);
+        },
+        onError: (error) => {
+          handleApiError(error, `Failed to delete ${entityName.toLowerCase()}`);
+        },
+        ...options,
+      });
+    },
+  };
+}
+
+// ===========================================
+// Example: Posts CRUD hooks
+// ===========================================
+
+interface Post {
+  id: string;
+  title: string;
+  content: string;
+  authorId: string;
+  createdAt: string;
+}
+
+export const postsApi = createCrudHooks<Post>({
+  baseKey: queryKeys.posts.all,
+  endpoint: "/posts",
+  entityName: "Post",
+});
+
+// Usage:
+// const { data: posts } = postsApi.useList();
+// const { data: post } = postsApi.useById("123");
+// const createPost = postsApi.useCreate();
+// const updatePost = postsApi.useUpdate();
+// const deletePost = postsApi.useDelete();