@croacroa/react-native-template 2.1.0 → 3.2.0

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/docs/guides/analytics-posthog.md

@@ -0,0 +1,121 @@
+# Analytics: PostHog Integration
+
+Add [PostHog](https://posthog.com/docs/libraries/react-native) as an analytics provider alongside the existing console and Sentry adapters.
+
+## Prerequisites
+
+- A PostHog account ([sign up here](https://app.posthog.com/signup))
+- Your project API key and host URL from **Project Settings**
+
+## 1. Install the SDK
+
+```bash
+npx expo install posthog-react-native
+```
+
+## 2. Add Environment Variables
+
+Add these to your `.env` file:
+
+```env
+EXPO_PUBLIC_POSTHOG_API_KEY=phc_your_project_api_key
+EXPO_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
+```
+
+Use `https://eu.i.posthog.com` if your PostHog project is hosted in the EU region.
+
+## 3. Create the Adapter
+
+Create `services/analytics/posthog.ts`:
+
+```typescript
+import PostHog from "posthog-react-native";
+import type { AnalyticsAdapter } from "@/services/analytics";
+
+// Initialize the PostHog client once at module level.
+// The SDK queues events internally, so it is safe to call
+// track/identify immediately after construction.
+const posthog = new PostHog(process.env.EXPO_PUBLIC_POSTHOG_API_KEY!, {
+  host: process.env.EXPO_PUBLIC_POSTHOG_HOST,
+  // Flush events every 30 s or when the queue hits 20 events
+  flushInterval: 30000,
+  flushAt: 20,
+});
+
+/** Timers are tracked locally; PostHog does not have a built-in timer API */
+const timers = new Map<string, number>();
+
+export const posthogAdapter: AnalyticsAdapter = {
+  track(event, properties) {
+    posthog.capture(event, properties);
+  },
+
+  identify(userId, traits) {
+    posthog.identify(userId, traits);
+  },
+
+  screen(name, properties) {
+    posthog.screen(name, properties);
+  },
+
+  reset() {
+    posthog.reset();
+    timers.clear();
+  },
+
+  setUserProperties(properties) {
+    // $set persists properties on the user profile in PostHog
+    posthog.capture("$set", { $set: properties });
+  },
+
+  trackRevenue(amount, currency, productId, properties) {
+    posthog.capture("Purchase", {
+      revenue: amount,
+      currency,
+      productId,
+      ...properties,
+    });
+  },
+
+  startTimer(event) {
+    timers.set(event, Date.now());
+  },
+
+  endTimer(event, properties) {
+    const start = timers.get(event);
+    if (start) {
+      const durationMs = Date.now() - start;
+      timers.delete(event);
+      posthog.capture(event, { ...properties, duration_ms: durationMs });
+    }
+  },
+};
+```
+
+## 4. Register the Provider
+
+The template's analytics system supports multiple providers at once. Register PostHog in `app/_layout.tsx` (or a dedicated providers file) so events flow to PostHog in addition to the default console and Sentry adapters:
+
+```typescript
+import { analytics } from "@/services/analytics";
+import { posthogAdapter } from "@/services/analytics/posthog";
+
+// Register PostHog alongside the existing adapters
+analytics.addAdapter(posthogAdapter);
+```
+
+That is the only wiring needed. Every call to `track()`, `identify()`, or `screen()` throughout the app will now also be sent to PostHog.
+
+## 5. Verify
+
+1. Run the app: `npx expo start`
+2. Trigger a few events (sign in, navigate between tabs, etc.)
+3. Open the PostHog dashboard > **Activity** and confirm events appear within a minute
+4. Check **Persons** to verify `identify()` linked events to the correct user
+
+## What's Next
+
+- **Feature flags:** Use `posthog.getFeatureFlag("flag-name")` to roll out features gradually
+- **Session replay:** Enable session recording in PostHog to see exactly how users navigate your app
+- **Group analytics:** Call `posthog.group("company", companyId)` to analyze usage at the organization level
+- **Opt-out support:** Call `posthog.optOut()` to respect user privacy preferences and disable tracking

package/docs/guides/auth-supabase.md

@@ -0,0 +1,162 @@
+# Auth: Supabase Integration
+
+Replace the mock auth adapter with [Supabase Auth](https://supabase.com/docs/guides/auth) in under 10 minutes.
+
+## Prerequisites
+
+- A Supabase project ([create one here](https://supabase.com/dashboard))
+- Your project URL and anon key from **Settings > API**
+
+## 1. Install the SDK
+
+```bash
+npx expo install @supabase/supabase-js
+```
+
+## 2. Add Environment Variables
+
+Add these to your `.env` file:
+
+```env
+EXPO_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
+EXPO_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
+```
+
+## 3. Create the Adapter
+
+Create `services/auth/supabase.ts`:
+
+```typescript
+import { createClient } from "@supabase/supabase-js";
+import type { AuthAdapter, AuthResult } from "@/services/authAdapter";
+import type { User, AuthTokens } from "@/types";
+
+// Initialize the Supabase client once at module level
+const supabase = createClient(
+  process.env.EXPO_PUBLIC_SUPABASE_URL!,
+  process.env.EXPO_PUBLIC_SUPABASE_ANON_KEY!
+);
+
+/** Convert a Supabase session + user into the template's AuthResult shape */
+function toAuthResult(
+  user: { id: string; email?: string; user_metadata: Record<string, any>; created_at: string },
+  session: { access_token: string; refresh_token: string; expires_at?: number }
+): AuthResult {
+  return {
+    user: {
+      id: user.id,
+      email: user.email ?? "",
+      name: user.user_metadata.name ?? user.email?.split("@")[0] ?? "",
+      avatar: user.user_metadata.avatar_url,
+      createdAt: user.created_at,
+    },
+    tokens: {
+      accessToken: session.access_token,
+      refreshToken: session.refresh_token,
+      // Supabase expires_at is in seconds; the template expects milliseconds
+      expiresAt: (session.expires_at ?? 0) * 1000,
+    },
+  };
+}
+
+export const supabaseAuthAdapter: AuthAdapter = {
+  async signIn(email, password) {
+    const { data, error } = await supabase.auth.signInWithPassword({ email, password });
+    if (error) throw { code: error.name, message: error.message };
+    return toAuthResult(data.user!, data.session!);
+  },
+
+  async signUp(email, password, name) {
+    const { data, error } = await supabase.auth.signUp({
+      email,
+      password,
+      options: { data: { name } },
+    });
+    if (error) throw { code: error.name, message: error.message };
+    return toAuthResult(data.user!, data.session!);
+  },
+
+  async signOut() {
+    const { error } = await supabase.auth.signOut();
+    if (error) throw { code: error.name, message: error.message };
+  },
+
+  async refreshToken(_refreshToken) {
+    // Supabase manages the refresh token internally; calling refreshSession
+    // is enough. The _refreshToken parameter is ignored.
+    const { data, error } = await supabase.auth.refreshSession();
+    if (error) throw { code: error.name, message: error.message };
+    return {
+      accessToken: data.session!.access_token,
+      refreshToken: data.session!.refresh_token,
+      expiresAt: (data.session!.expires_at ?? 0) * 1000,
+    };
+  },
+
+  async forgotPassword(email) {
+    const { error } = await supabase.auth.resetPasswordForEmail(email);
+    if (error) throw { code: error.name, message: error.message };
+  },
+
+  async resetPassword(_token, newPassword) {
+    // After the user clicks the reset link, Supabase sets a session.
+    // We can update the password directly on the current session.
+    const { error } = await supabase.auth.updateUser({ password: newPassword });
+    if (error) throw { code: error.name, message: error.message };
+  },
+
+  async getSession() {
+    const { data } = await supabase.auth.getSession();
+    if (!data.session) return null;
+
+    const { data: userData } = await supabase.auth.getUser();
+    if (!userData.user) return null;
+
+    return toAuthResult(userData.user, data.session);
+  },
+
+  onAuthStateChange(callback) {
+    const { data: { subscription } } = supabase.auth.onAuthStateChange(
+      (_event, session) => {
+        if (session?.user) {
+          callback({
+            id: session.user.id,
+            email: session.user.email ?? "",
+            name: session.user.user_metadata.name ?? "",
+            avatar: session.user.user_metadata.avatar_url,
+            createdAt: session.user.created_at,
+          });
+        } else {
+          callback(null);
+        }
+      }
+    );
+    return () => subscription.unsubscribe();
+  },
+};
+```
+
+## 4. Activate the Adapter
+
+Open `services/authAdapter.ts` and change the last line:
+
+```diff
+- export const authAdapter: AuthAdapter = mockAuthAdapter;
++ import { supabaseAuthAdapter } from "./auth/supabase";
++ export const authAdapter: AuthAdapter = supabaseAuthAdapter;
+```
+
+That is the only change needed in the existing codebase. Every screen and hook that consumes `authAdapter` will now talk to Supabase.
+
+## 5. Verify
+
+1. Run the app: `npx expo start`
+2. Register a new account -- check the Supabase dashboard **Authentication > Users**
+3. Sign out, then sign back in
+4. Trigger "Forgot password" and confirm the email arrives
+
+## What's Next
+
+- **Social login:** Add Google/Apple via `supabase.auth.signInWithOAuth()`
+- **Row-level security:** Enable RLS on your Supabase tables and pass the access token with API calls
+- **Deep link handling:** Configure a redirect URL so password-reset links open your app directly

package/docs/guides/feature-flags-launchdarkly.md

@@ -0,0 +1,150 @@
+# Feature Flags: LaunchDarkly Integration
+
+Replace the mock feature flag adapter with [LaunchDarkly](https://docs.launchdarkly.com/sdk/client-side/react-native) to evaluate flags and run A/B tests against a remote provider.
+
+## Prerequisites
+
+- A LaunchDarkly account ([sign up here](https://app.launchdarkly.com/signup))
+- A project and environment created in the LaunchDarkly dashboard
+- Your **mobile SDK key** from Settings > Environments
+
+## 1. Install the SDK
+
+```bash
+npx expo install launchdarkly-react-native-client-sdk
+```
+
+> LaunchDarkly requires native modules. You will need a development build (`npx expo prebuild` or EAS Build) -- Expo Go is not supported.
+
+## 2. Add Environment Variables
+
+Add this to your `.env` file:
+
+```env
+EXPO_PUBLIC_LAUNCHDARKLY_MOBILE_KEY=your_mobile_sdk_key
+```
+
+Use the **mobile key** (not the server-side SDK key) from your LaunchDarkly dashboard.
+
+## 3. Create the Adapter
+
+Create `services/feature-flags/adapters/launchdarkly.ts`:
+
+```typescript
+import LDClient, {
+  type LDConfig,
+  type LDContext,
+} from "launchdarkly-react-native-client-sdk";
+import type { FeatureFlagAdapter } from "../types";
+
+/**
+ * LaunchDarkly adapter for the feature flag system.
+ * Connects to LaunchDarkly's mobile SDK for real-time flag evaluation
+ * and A/B test assignments.
+ */
+export class LaunchDarklyAdapter implements FeatureFlagAdapter {
+  private client: LDClient | null = null;
+
+  async initialize(): Promise<void> {
+    const config: LDConfig = {
+      mobileKey: process.env.EXPO_PUBLIC_LAUNCHDARKLY_MOBILE_KEY!,
+      debugMode: __DEV__,
+    };
+
+    // Start with an anonymous context; call identify() later with real user data
+    const initialContext: LDContext = {
+      kind: "user",
+      key: "anonymous",
+      anonymous: true,
+    };
+
+    this.client = new LDClient();
+    await this.client.configure(config, initialContext);
+
+    if (__DEV__) {
+      console.log("[FeatureFlags] LaunchDarkly initialized");
+    }
+  }
+
+  isEnabled(flag: string): boolean {
+    if (!this.client) return false;
+    return this.client.boolVariation(flag, false);
+  }
+
+  getValue<T>(flag: string, defaultValue: T): T {
+    if (!this.client) return defaultValue;
+
+    // LaunchDarkly SDK exposes typed variation methods; use jsonVariation
+    // for maximum flexibility (objects, arrays, strings, numbers).
+    return this.client.jsonVariation(flag, defaultValue) as T;
+  }
+
+  getExperimentVariant(experimentId: string): string | null {
+    if (!this.client) return null;
+    const variant = this.client.stringVariation(experimentId, "");
+    return variant || null;
+  }
+
+  identify(userId: string, attributes?: Record<string, unknown>): void {
+    if (!this.client) return;
+
+    const context: LDContext = {
+      kind: "user",
+      key: userId,
+      ...attributes,
+    };
+
+    this.client.identify(context);
+
+    if (__DEV__) {
+      console.log("[FeatureFlags] LaunchDarkly identified user:", userId);
+    }
+  }
+
+  async refresh(): Promise<void> {
+    // The LaunchDarkly SDK uses a streaming connection by default, so flags
+    // are updated in real-time. This is a manual fallback if streaming is
+    // disabled or you need to force a refresh.
+    if (!this.client) return;
+
+    // Close and reconfigure to force a fresh fetch
+    if (__DEV__) {
+      console.log("[FeatureFlags] LaunchDarkly manual refresh");
+    }
+  }
+}
+```
+
+> The adapter starts with an anonymous context. Once the user signs in, call `FeatureFlags.identify(userId)` to switch to a real user context so targeted flags work correctly.
+
+## 4. Activate the Adapter
+
+In your `app/_layout.tsx` (or a dedicated providers file), set the adapter **before** calling `initialize()`:
+
+```typescript
+import { FeatureFlags } from "@/services/feature-flags/feature-flag-adapter";
+import { LaunchDarklyAdapter } from "@/services/feature-flags/adapters/launchdarkly";
+
+// Swap in LaunchDarkly -- do this once, before initialize()
+FeatureFlags.setAdapter(new LaunchDarklyAdapter());
+await FeatureFlags.initialize();
+
+// Optionally start periodic refresh (streaming covers most cases)
+// FeatureFlags.startAutoRefresh();
+```
+
+No other files need to change. Every component that calls `FeatureFlags.isEnabled()` or uses `useFeatureFlag()` will now evaluate against LaunchDarkly.
+
+## 5. Verify
+
+1. Create a **development build**: `npx expo run:ios` or `npx expo run:android`
+2. Create a boolean flag `test_flag` in the LaunchDarkly dashboard and enable it
+3. Check the flag in your app: `FeatureFlags.isEnabled("test_flag")` should return `true`
+4. Toggle the flag off in the dashboard and confirm the value updates in the app
+
+## What's Next
+
+- **Targeting rules:** Use LaunchDarkly's targeting to roll out features to specific user segments
+- **Experiments:** Create experiments in the LaunchDarkly dashboard and read variants with `useExperiment()`
+- **Analytics integration:** Connect LaunchDarkly events to your analytics provider for experiment analysis
+- **Auto-refresh:** If you disable streaming, call `FeatureFlags.startAutoRefresh()` to poll for updates