@kiosinc/commons-rn 0.15.6 → 0.16.0

package/src/hooks/useCustomer.ts

@@ -1,15 +1,9 @@
-import { useEffect } from 'react';
 import { Alert } from '../components';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import firestore from '@react-native-firebase/firestore';
-import uuid from 'react-native-uuid';
-
 import {
-  connectSquareCustomer,
-  connectSquareLoyalty,
   createCustomer,
   fetchLoyaltyRewards,
-  fetchSquareLoyalty,
   getCustomer,
   saveCustomerAddress,
   saveCustomerCard,
@@ -27,12 +21,6 @@ export const useCustomerQueries = () => {
   const [selectedBusinessId] = useMMKVString(MMKV_KEYS.BUSINESS_ID);
   const isLoggedIn = user && !user.isAnonymous;
 
-  useEffect(() => {
-    if (!isLoggedIn) {
-      queryClient.invalidateQueries([queryKeys.LOYALTY, user?.uid]);
-    }
-  }, [isLoggedIn, queryClient, user?.uid]);
-
   return {
     useFetchCustomer: () =>
       useQuery(
@@ -160,63 +148,6 @@ export const useCustomerQueries = () => {
           enabled: Boolean(isLoggedIn),
         }
       ),
-    useFetchSquareProgram: (queryOptions?: object) =>
-      useQuery(
-        [queryKeys.PROGRAM, user?.uid, selectedBusinessId],
-        async () => {
-          if (isLoggedIn) {
-            const programs = await firestore()
-              .collection(`customers/${user?.uid}/programs`)
-              .where('type', '==', 'customer')
-              .where('businessId', '==', selectedBusinessId)
-              .orderBy('updated', 'asc')
-              .get();
-            if (programs.docs.length > 0) {
-              return programs.docs.map((program: any) => program.data())[0];
-            } else {
-              return null;
-            }
-          } else {
-            return null;
-          }
-        },
-        {
-          enabled: Boolean(isLoggedIn && selectedBusinessId),
-          ...queryOptions,
-        }
-      ),
-    useFetchSquareLoyalty: (queryOptions?: object) =>
-      useQuery(
-        [
-          queryKeys.LOYALTY,
-          user?.uid ?? 'no-user',
-          selectedBusinessId ?? 'no-biz',
-        ],
-        async () => {
-          const response = await fetchSquareLoyalty(
-            user!.uid,
-            selectedBusinessId!
-          );
-
-          if (response?.data?.error) {
-            throw new Error(
-              response.data.error.message || 'Unknown error occurred'
-            );
-          }
-          return response;
-        },
-        {
-          enabled: Boolean(isLoggedIn && user?.uid && selectedBusinessId),
-          refetchOnWindowFocus: false,
-          refetchOnReconnect: false,
-          refetchOnMount: false,
-          staleTime: 5 * 60 * 1000,
-          cacheTime: 30 * 60 * 1000,
-          retry: 0,
-          select: (res) => res?.data,
-          ...(queryOptions || {}),
-        }
-      ),
     useSaveCustomerCard: () => {
       const mutation = useMutation(
         async (data: SaveCardRequest) => {
@@ -273,71 +204,6 @@ export const useCustomerQueries = () => {
         disableCardLoading: mutation.isLoading,
       };
     },
-    useConnectSquareLoyalty: () => {
-      const mutation = useMutation(
-        async () => {
-          if (isLoggedIn && selectedBusinessId) {
-            const response = await connectSquareLoyalty(user?.uid, {
-              businessId: selectedBusinessId,
-              idempotentKey: uuid.v4() as string,
-              uid: user?.uid,
-            });
-
-            if (response?.data?.error) {
-              throw new Error(
-                response.data.error.message || 'Unknown error occurred'
-              );
-            }
-
-            return response;
-          }
-          return null;
-        },
-        {
-          onError: (err: { code: string; message: string }) =>
-            Alert.show({
-              title: err?.code ? 'Code ' + err?.code : '',
-              description: err?.message,
-            }),
-          onSuccess: () => {
-            queryClient.invalidateQueries([queryKeys.LOYALTY, user?.uid]);
-          },
-        }
-      );
-
-      return {
-        connectSquareLoyalty: mutation.mutate,
-        connectLoyaltyLoading: mutation.isLoading,
-      };
-    },
-    useConnectSquareCustomer: () => {
-      const mutation = useMutation(
-        async () => {
-          if (isLoggedIn && selectedBusinessId) {
-            await connectSquareCustomer(user?.uid, {
-              businessId: selectedBusinessId,
-              idempotentKey: uuid.v4() as string,
-              uid: user?.uid,
-            });
-          }
-        },
-        {
-          onError: (err: { code: string; message: string }) =>
-            Alert.show({
-              title: 'Code ' + err?.code,
-              description: err?.message,
-            }),
-          onSuccess: () => {
-            queryClient.invalidateQueries([queryKeys.PROGRAM, user?.uid]);
-          },
-        }
-      );
-
-      return {
-        connectSquare: mutation.mutate,
-        connectSquareLoading: mutation.isLoading,
-      };
-    },
     useFetchLoyaltyRewards: (options?: { enabled?: boolean }) =>
       useQuery(
         [queryKeys.REWARDS, selectedBusinessId],

package/src/providers/customer/CustomerProvider.tsx

@@ -0,0 +1,272 @@
+import React, {
+  createContext,
+  useCallback,
+  useEffect,
+  useState,
+  type FC,
+  type PropsWithChildren,
+} from 'react';
+import auth, { type FirebaseAuthTypes } from '@react-native-firebase/auth';
+import firestore from '@react-native-firebase/firestore';
+import { useMMKVString } from 'react-native-mmkv';
+import { useQueryClient } from '@tanstack/react-query';
+import uuid from 'react-native-uuid';
+
+import {
+  connectSquareCustomer,
+  connectSquareLoyalty,
+  createCustomer,
+  fetchSquareLoyalty,
+  getCustomer,
+} from '../../api/customer';
+import { MMKV_KEYS } from '../../constants';
+import { queryKeys } from '../../hooks/queryKeys';
+import { classifyLoyaltyError } from './classifyLoyaltyError';
+import type {
+  CustomerContextValue,
+  CustomerLoyalty,
+  CustomerStatus,
+  LoyaltyStatus,
+} from './types';
+
+export interface CustomerProviderProps {
+  autoEnroll: boolean;
+  loyaltyEnabled: boolean;
+}
+
+const customerSetupAttempted = new Set<string>();
+
+export const CustomerContext = createContext<CustomerContextValue | null>(null);
+
+export const CustomerProvider: FC<PropsWithChildren<CustomerProviderProps>> = ({
+  children,
+  autoEnroll,
+  loyaltyEnabled,
+}) => {
+  const queryClient = useQueryClient();
+  const [selectedBusinessId] = useMMKVString(MMKV_KEYS.BUSINESS_ID);
+
+  const [uid, setUid] = useState<string | null>(null);
+  const uidRef = React.useRef<string | null>(null);
+  const [customerStatus, setCustomerStatus] = useState<CustomerStatus>('idle');
+  const [squareCustomerId, setSquareCustomerId] = useState<string | null>(null);
+  const [customerError, setCustomerError] = useState<string | null>(null);
+  const [loyaltyStatus, setLoyaltyStatus] = useState<LoyaltyStatus>('idle');
+  const [loyalty, setLoyaltyData] = useState<CustomerLoyalty | null>(null);
+  const [loyaltyError, setLoyaltyError] = useState<string | null>(null);
+
+  const resetState = useCallback(
+    (userId: string | null) => {
+      setCustomerStatus('idle');
+      setSquareCustomerId(null);
+      setCustomerError(null);
+      setLoyaltyStatus('idle');
+      setLoyaltyData(null);
+      setLoyaltyError(null);
+      if (userId) {
+        for (const key of [...customerSetupAttempted]) {
+          if (key.startsWith(`${userId}:`)) {
+            customerSetupAttempted.delete(key);
+          }
+        }
+      }
+      queryClient.removeQueries([queryKeys.LOYALTY]);
+      queryClient.removeQueries([queryKeys.PROGRAM]);
+    },
+    [queryClient]
+  );
+
+  useEffect(() => {
+    const unsubscribe = auth().onAuthStateChanged(
+      (user: FirebaseAuthTypes.User | null) => {
+        const loggedIn = Boolean(user && !user.isAnonymous);
+        if (loggedIn && user) {
+          setUid(user.uid);
+          uidRef.current = user.uid;
+        } else {
+          resetState(uidRef.current);
+          setUid(null);
+          uidRef.current = null;
+        }
+      }
+    );
+    return unsubscribe;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    if (!uid || !selectedBusinessId) {
+      return;
+    }
+    const key = `${uid}:${selectedBusinessId}`;
+    if (customerSetupAttempted.has(key)) {
+      return;
+    }
+    customerSetupAttempted.add(key);
+    runCustomerSetup(uid, selectedBusinessId);
+  }, [uid, selectedBusinessId]);
+
+  const runCustomerSetup = async (userId: string, businessId: string) => {
+    const key = `${userId}:${businessId}`;
+    setCustomerStatus('loading');
+    try {
+      const customerRes = await getCustomer(userId);
+      if (customerRes?.data?.customer === null) {
+        await createCustomer({ uid: userId });
+      }
+      const programs = await firestore()
+        .collection(`customers/${userId}/programs`)
+        .where('type', '==', 'customer')
+        .where('businessId', '==', businessId)
+        .get();
+
+      let custId: string | null = null;
+      if (programs.empty) {
+        await connectSquareCustomer(userId, {
+          businessId,
+          uid: userId,
+          idempotentKey: uuid.v4() as string,
+        });
+        const updated = await firestore()
+          .collection(`customers/${userId}/programs`)
+          .where('type', '==', 'customer')
+          .where('businessId', '==', businessId)
+          .get();
+        if (!updated.empty) {
+          custId = updated.docs[0].data().linkedObjectId ?? null;
+        }
+      } else {
+        custId = programs.docs[0].data().linkedObjectId ?? null;
+      }
+      setSquareCustomerId(custId);
+      setCustomerStatus('ready');
+      console.log(`[CustomerProvider] Customer ready for ${key}`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(
+        `[CustomerProvider] Customer setup failed for ${key}: ${msg}`
+      );
+      customerSetupAttempted.delete(key);
+      setCustomerError(msg);
+      setCustomerStatus('error');
+    }
+  };
+
+  const fetchLoyaltyData = useCallback(
+    async (userId: string, businessId: string) => {
+      try {
+        const response = await fetchSquareLoyalty(userId, businessId);
+        if (response?.data?.error) {
+          throw new Error(
+            response.data.error.message || 'Unknown loyalty error'
+          );
+        }
+        setLoyaltyData(response?.data ?? null);
+        setLoyaltyStatus('ready');
+        setLoyaltyError(null);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.log(`[CustomerProvider] Loyalty fetch failed: ${msg}`);
+        if (msg.includes('does not have loyalty')) {
+          if (autoEnroll) {
+            await attemptEnroll(userId, businessId);
+          } else {
+            setLoyaltyStatus('not_enrolled');
+          }
+        } else {
+          setLoyaltyError(msg);
+          setLoyaltyStatus('error');
+        }
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [autoEnroll]
+  );
+
+  const attemptEnroll = useCallback(
+    async (userId: string, businessId: string) => {
+      setLoyaltyStatus('enrolling');
+      try {
+        const response = await connectSquareLoyalty(userId, {
+          businessId,
+          uid: userId,
+          idempotentKey: uuid.v4() as string,
+        });
+        if (response?.data?.error) {
+          throw new Error(
+            response.data.error.message || 'Unknown connect error'
+          );
+        }
+        await fetchLoyaltyData(userId, businessId);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.log(`[CustomerProvider] Loyalty connect failed: ${msg}`);
+        const outcome = classifyLoyaltyError(msg);
+        if (outcome === 'refetch') {
+          await fetchLoyaltyData(userId, businessId);
+        } else if (outcome === 'duplicate') {
+          setLoyaltyError('Multiple account records found. Contact support.');
+          setLoyaltyStatus('error');
+        } else if (outcome === 'no_loyalty') {
+          setLoyaltyStatus('no_loyalty');
+        } else {
+          setLoyaltyError(msg);
+          setLoyaltyStatus('error');
+        }
+      }
+    },
+    [fetchLoyaltyData]
+  );
+
+  const runLoyaltySetup = useCallback(
+    async (userId: string, businessId: string) => {
+      setLoyaltyStatus('loading');
+      await fetchLoyaltyData(userId, businessId);
+    },
+    [fetchLoyaltyData]
+  );
+
+  useEffect(() => {
+    if (customerStatus !== 'ready' || !uid || !selectedBusinessId) {
+      return;
+    }
+    if (!loyaltyEnabled) {
+      setLoyaltyStatus('no_loyalty');
+      return;
+    }
+    runLoyaltySetup(uid, selectedBusinessId);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [customerStatus, loyaltyEnabled, uid, selectedBusinessId]);
+
+  const enroll = useCallback(() => {
+    if (!uid || !selectedBusinessId || loyaltyStatus === 'enrolling') {
+      return;
+    }
+    attemptEnroll(uid, selectedBusinessId);
+  }, [uid, selectedBusinessId, loyaltyStatus, attemptEnroll]);
+
+  const refetchLoyalty = useCallback(() => {
+    if (!uid || !selectedBusinessId) {
+      return;
+    }
+    fetchLoyaltyData(uid, selectedBusinessId);
+  }, [uid, selectedBusinessId, fetchLoyaltyData]);
+
+  const value: CustomerContextValue = {
+    customerStatus,
+    squareCustomerId,
+    customerError,
+    loyaltyStatus,
+    loyalty,
+    points: loyalty?.program?.loyaltyDetails?.points ?? 0,
+    loyaltyError,
+    enroll,
+    refetchLoyalty,
+  };
+
+  return (
+    <CustomerContext.Provider value={value}>
+      {children}
+    </CustomerContext.Provider>
+  );
+};

package/src/providers/customer/README.md

@@ -0,0 +1,122 @@
+# CustomerProvider
+
+Owns the full customer + loyalty lifecycle. Replaces the old scattered hooks (`useCheckCustomer`, `useFetchSquareLoyalty`, `useConnectSquareLoyalty`, `useFetchSquareProgram`, `useConnectSquareCustomer`).
+
+## What it does
+
+1. Subscribes to Firebase auth — starts setup on login, clears state on logout
+2. Ensures the customer record exists (`getCustomer` / `createCustomer`)
+3. Ensures the Square customer program doc exists (`connectSquareCustomer`) — guarded by a module-level `Set` so it never fires twice for the same `uid:businessId`, even across remounts
+4. Fetches loyalty data — on "does not have loyalty":
+   - `autoEnroll=true` (kiosk): calls `connectSquareLoyalty` automatically
+   - `autoEnroll=false` (Gusteau): sets `not_enrolled`, waits for `enroll()` call
+5. Classifies all `connectSquareLoyalty` errors so checkout is never blocked
+
+## Setup
+
+Wrap your authenticated navigator with the provider:
+
+```tsx
+import { CustomerProvider } from '@kiosinc/commons-rn';
+
+// autoEnroll=true for kiosk (auto-enroll on login)
+// autoEnroll=false for Gusteau (manual enroll via button)
+<CustomerProvider
+  autoEnroll
+  loyaltyEnabled={isSquareLoyaltyEnabled}>
+  <YourNavigator />
+</CustomerProvider>
+```
+
+`businessId` is read internally from MMKV (`MMKV_KEYS.BUSINESS_ID`) — no prop needed.
+
+## Consumer hooks
+
+### `useSquareCustomer()` — for checkout
+
+```tsx
+import { useSquareCustomer } from '@kiosinc/commons-rn';
+
+const { squareCustomerId, customerStatus, customerError } = useSquareCustomer();
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `squareCustomerId` | `string \| null` | Pass to `useOptimizedCheckout`. Available even if loyalty is broken. |
+| `customerStatus` | `CustomerStatus` | `idle \| loading \| ready \| error` |
+| `customerError` | `string \| null` | Error message if setup failed |
+
+### `useLoyalty()` — for rewards screens
+
+```tsx
+import { useLoyalty } from '@kiosinc/commons-rn';
+
+const {
+  loyaltyStatus,
+  isReady,
+  loyalty,
+  points,
+  loyaltyError,
+  enroll,
+  refetchLoyalty,
+} = useLoyalty();
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `loyaltyStatus` | `LoyaltyStatus` | See status machine below |
+| `isReady` | `boolean` | `loyaltyStatus === 'ready'` |
+| `loyalty` | `CustomerLoyalty \| null` | Full loyalty object |
+| `points` | `number` | Available points (0 if not ready) |
+| `loyaltyError` | `string \| null` | Show on error/no_loyalty screens |
+| `enroll()` | `() => void` | Gusteau: call from "Join" button. Noop if already enrolling or autoEnroll=true. |
+| `refetchLoyalty()` | `() => void` | Call after payment to refresh points |
+
+## Status machines
+
+### `customerStatus`
+```
+idle → loading → ready
+                → error
+```
+
+### `loyaltyStatus`
+```
+idle → loading → ready
+               → not_enrolled  (autoEnroll=false, no loyalty account)
+               → enrolling → ready
+                           → error
+               → no_loyalty   (merchant has no loyalty program)
+               → error        (duplicate customer docs, etc.)
+```
+
+## Error handling
+
+`connectSquareLoyalty` errors are classified automatically:
+
+| Error message | Outcome |
+|---|---|
+| contains `already has` / `ALREADY_EXISTS` / `already exists` | Refetch → `ready` |
+| contains `More than one` / `more than one` | `loyaltyStatus = 'error'`, message: "Multiple account records found. Contact support." |
+| contains `Square Loyalty not enabled` / `not enabled` | `loyaltyStatus = 'no_loyalty'` |
+| anything else | `loyaltyStatus = 'error'`, raw message shown |
+
+## Session reset
+
+Provider resets automatically on Firebase auth state change (logout). For kiosk sleep/wake cycles that don't sign out Firebase, sign the user out via `firebase().auth().signOut()` to trigger a full reset.
+
+## Gusteau usage
+
+```tsx
+// In your business selector screen:
+<CustomerProvider autoEnroll={false} loyaltyEnabled={true}>
+  <AppNavigator />
+</CustomerProvider>
+
+// In your loyalty join screen:
+const { loyaltyStatus, enroll } = useLoyalty();
+
+if (loyaltyStatus === 'not_enrolled') {
+  return <Button onPress={enroll} title="Join Loyalty Program" />;
+}
+```

package/src/providers/customer/classifyLoyaltyError.ts

@@ -0,0 +1,25 @@
+export type LoyaltyConnectOutcome =
+  | 'refetch'
+  | 'duplicate'
+  | 'no_loyalty'
+  | 'error';
+
+export function classifyLoyaltyError(message: string): LoyaltyConnectOutcome {
+  if (
+    message.includes('already has') ||
+    message.includes('ALREADY_EXISTS') ||
+    message.toLowerCase().includes('already exists')
+  ) {
+    return 'refetch';
+  }
+  if (message.includes('More than one') || message.includes('more than one')) {
+    return 'duplicate';
+  }
+  if (
+    message.includes('Square Loyalty not enabled') ||
+    message.toLowerCase().includes('not enabled')
+  ) {
+    return 'no_loyalty';
+  }
+  return 'error';
+}

package/src/providers/customer/index.ts

@@ -0,0 +1,4 @@
+export { CustomerProvider } from './CustomerProvider';
+export { useSquareCustomer } from './useSquareCustomer';
+export { useLoyalty } from './useLoyalty';
+export type { CustomerStatus, LoyaltyStatus, CustomerLoyalty } from './types';

package/src/providers/customer/types.ts

@@ -0,0 +1,34 @@
+export type CustomerStatus = 'idle' | 'loading' | 'ready' | 'error';
+
+export type LoyaltyStatus =
+  | 'idle'
+  | 'loading'
+  | 'not_enrolled'
+  | 'enrolling'
+  | 'ready'
+  | 'no_loyalty'
+  | 'error';
+
+export interface CustomerLoyalty {
+  programId?: string;
+  program?: {
+    linkedObjectId?: string;
+    loyaltyDetails?: {
+      points?: number;
+      customerId?: string;
+      mainProgramId?: string;
+    };
+  } | null;
+}
+
+export interface CustomerContextValue {
+  customerStatus: CustomerStatus;
+  squareCustomerId: string | null;
+  customerError: string | null;
+  loyaltyStatus: LoyaltyStatus;
+  loyalty: CustomerLoyalty | null;
+  points: number;
+  loyaltyError: string | null;
+  enroll: () => void;
+  refetchLoyalty: () => void;
+}

package/src/providers/customer/useLoyalty.ts

@@ -0,0 +1,27 @@
+import { useContext } from 'react';
+import { CustomerContext } from './CustomerProvider';
+import type { CustomerLoyalty, LoyaltyStatus } from './types';
+
+export const useLoyalty = (): {
+  loyaltyStatus: LoyaltyStatus;
+  isReady: boolean;
+  loyalty: CustomerLoyalty | null;
+  points: number;
+  loyaltyError: string | null;
+  enroll: () => void;
+  refetchLoyalty: () => void;
+} => {
+  const ctx = useContext(CustomerContext);
+  if (!ctx) {
+    throw new Error('useLoyalty must be used within CustomerProvider');
+  }
+  return {
+    loyaltyStatus: ctx.loyaltyStatus,
+    isReady: ctx.loyaltyStatus === 'ready',
+    loyalty: ctx.loyalty,
+    points: ctx.points,
+    loyaltyError: ctx.loyaltyError,
+    enroll: ctx.enroll,
+    refetchLoyalty: ctx.refetchLoyalty,
+  };
+};

package/src/providers/customer/useSquareCustomer.ts

@@ -0,0 +1,19 @@
+import { useContext } from 'react';
+import { CustomerContext } from './CustomerProvider';
+import type { CustomerStatus } from './types';
+
+export const useSquareCustomer = (): {
+  customerStatus: CustomerStatus;
+  squareCustomerId: string | null;
+  customerError: string | null;
+} => {
+  const ctx = useContext(CustomerContext);
+  if (!ctx) {
+    throw new Error('useSquareCustomer must be used within CustomerProvider');
+  }
+  return {
+    customerStatus: ctx.customerStatus,
+    squareCustomerId: ctx.squareCustomerId,
+    customerError: ctx.customerError,
+  };
+};

package/src/providers/index.ts

@@ -4,3 +4,9 @@ export {
   useAuthenticationDispatch,
   AuthenticationProvider,
 } from './authentication/AuthenticationProvider';
+export { CustomerProvider, useSquareCustomer, useLoyalty } from './customer';
+export type {
+  CustomerStatus,
+  LoyaltyStatus,
+  CustomerLoyalty,
+} from './customer';