@phygitallabs/tapquest-core 2.0.0

package/src/modules/achivementWithReward/hooks/achivementPlusRewardModel.ts

@@ -0,0 +1,83 @@
+import { Achievement, useManyAchievements } from "@phygitallabs/achievement";
+import { EntityRewardModel } from "@phygitallabs/reward";
+import { useCreateModelGroupReward } from "@phygitallabs/reward/src/hooks/useGroupReward";
+import { useEffect, useMemo } from "react";
+
+interface UseAchivementPlusRewardModelParams {
+  campaignId: string;
+}
+interface GroupRewardData {
+  reward_models: EntityRewardModel[][];
+}
+
+function buildMappedAchievements(achievements: Achievement[], groupRewardData: GroupRewardData) {
+  if (!groupRewardData?.reward_models) return [];
+
+  const rewardModels = groupRewardData.reward_models;
+
+  return achievements.map((achievement, achievementIndex) => {
+    const parentReward = rewardModels[achievementIndex]?.[0] || null;
+
+    const subAchievements =
+      achievement.subAchievementIds?.map((subId: string, subIndex: number) => {
+        const reward =
+          rewardModels[
+          achievementIndex * (achievement.subAchievementIds?.length || 0) +
+          subIndex +
+          1
+          ]?.[0] || null;
+
+        return {
+          id: subId,
+          reward_model: reward,
+        };
+      }) || [];
+
+    return {
+      id: achievement.id,
+      name: achievement.name,
+      reward_model: parentReward,
+      subAchievements,
+    };
+  });
+}
+
+const useAchivementPlusRewardModel = ({ campaignId }: UseAchivementPlusRewardModelParams) => {
+  const { data: achievements, isLoading: isLoadingAchievements } =
+    useManyAchievements(
+      {
+        "filter.labels": { campaign_id: campaignId },
+        "filter.type": "group_mission",
+        "pagination.limit": 200,
+      },
+      { enabled: !!campaignId }
+    );
+
+  const groupRewardIds = useMemo(() => {
+    if (!achievements?.data) return [];
+    return achievements.data
+      .map((achievement) => achievement.groupRewardId)
+      .filter((id): id is string => id !== undefined);
+  }, [achievements?.data]);
+  const {
+    mutate: fetchGroupRewardModels,
+    data: groupRewardModelsData,
+    isPending: isPendingGroupRewardModels,
+  } = useCreateModelGroupReward();
+  useEffect(() => {
+    if (groupRewardIds.length > 0) {
+      fetchGroupRewardModels({ group_reward_ids: groupRewardIds });
+    }
+  }, [groupRewardIds, fetchGroupRewardModels]);
+
+  const mappedAchievements = useMemo(() => {
+    if (!groupRewardModelsData?.data || !achievements?.data) return [];
+    return buildMappedAchievements(achievements.data, groupRewardModelsData.data);
+  }, [groupRewardModelsData, achievements?.data]);
+  return {
+    mappedAchievements,
+    isLoading: isLoadingAchievements || isPendingGroupRewardModels,
+  };
+};
+
+export default useAchivementPlusRewardModel;

package/src/modules/achivementWithReward/hooks/index.ts

@@ -0,0 +1,5 @@
+import useAchivementPlusRewardModel from "./achivementPlusRewardModel";
+
+export {
+  useAchivementPlusRewardModel,
+};

package/src/modules/achivementWithReward/index.ts

@@ -0,0 +1,5 @@
+import { useAchivementPlusRewardModel } from "./hooks";
+
+export {
+  useAchivementPlusRewardModel,
+};

package/src/modules/auth/README.md

@@ -0,0 +1,527 @@
+# Authentication Module
+
+The auth module provides a comprehensive authentication system for TapQuest applications with support for multiple authentication providers, centralized state management, and flexible integration patterns.
+
+## Overview
+
+This module implements a provider-agnostic authentication system that supports:
+- Email/password authentication
+- Google OAuth integration
+- User session persistence
+- Real-time authentication state management
+- Type-safe authentication interfaces
+
+## Architecture
+
+```
+auth/
+├── constants/          # Authentication constants and keys
+├── helpers/           # Storage utilities and helper functions
+├── hooks/             # Authentication hooks
+├── providers/         # React context providers
+├── services/          # Authentication service implementations
+├── store/             # Redux state management
+├── types/             # TypeScript type definitions
+└── index.ts           # Public API exports
+```
+
+## Core Components
+
+### 1. Authentication Service Interface
+
+The `AuthService` interface defines a contract for authentication providers:
+
+```typescript
+interface AuthService {
+  // Authentication methods
+  signInWithEmailAndPassword(email: string, password: string): Promise<AuthResponse>;
+  signInWithGoogle(): Promise<AuthResponse>;
+  signUp(email: string, password: string): Promise<AuthResponse>;
+  signOut(): Promise<void>;
+
+  // Password management
+  sendPasswordResetEmail(email: string): Promise<void>;
+  sendEmailVerification(): Promise<void>;
+  changePassword(newPassword: string): Promise<void>;
+
+  // Auth state monitoring
+  onAuthStateChanged(callback: (user: UserData | null) => void): () => void;
+  getCurrentUser(): UserData | null;
+}
+```
+
+### 2. User Data Structure
+
+```typescript
+type UserData = {
+  uid?: string;
+  id: string;
+  userName: string;
+  displayName?: string;
+  avatar: string;
+  exp: number;
+  email: string;
+  emailVerified: boolean;
+  accessToken: string;
+  refreshToken: string;
+  signInProvider?: SignInProvider;
+  role?: UserRole;
+  scanStatus?: boolean;
+};
+```
+
+### 3. State Management
+
+The module uses Redux Toolkit for state management with the following structure:
+
+```typescript
+interface AuthState {
+  user: UserData;
+  isSignedIn: boolean;
+  pending: boolean;
+}
+```
+
+**Available Actions:**
+- `signIn` - Store user data and mark as signed in
+- `signOut` - Clear user data and mark as signed out
+- `updateScanStatus` - Update user's scan status
+- `refreshUser` - Update user data
+- `setPending` - Set loading state
+- `initializeFromStorage` - Restore authentication state from storage
+
+## Quick Start
+
+### 1. Basic Setup
+
+```typescript
+import { TapquestCoreProvider, FirebaseAuthService } from '@phygitallabs/tapquest-core';
+import { QueryClient } from '@tanstack/react-query';
+
+const authConfig = {
+  apiKey: "your-api-key",
+  authDomain: "your-auth-domain",
+  projectId: "your-project-id",
+  // ... other Firebase config
+};
+
+const authService = new FirebaseAuthService(authConfig);
+const queryClient = new QueryClient();
+
+function App() {
+  return (
+    <TapquestCoreProvider
+      queryClient={queryClient}
+      apiConfig={apiConfig}
+      authService={authService}
+      authCallbacks={{
+        onSignInSuccess: (userData) => console.log('User signed in:', userData),
+        onSignOutSuccess: () => console.log('User signed out'),
+      }}
+    >
+      <YourApp />
+    </TapquestCoreProvider>
+  );
+}
+```
+
+### 2. Using the Auth Hook
+
+```typescript
+import { useAuth } from '@phygitallabs/tapquest-core';
+
+function LoginComponent() {
+  const {
+    user,
+    isSignedIn,
+    isLoading,
+    signIn,
+    signInWithGoogle,
+    signOut
+  } = useAuth();
+
+  const handleEmailSignIn = async () => {
+    const result = await signIn(email, password);
+    if (result.errorCode) {
+      console.error('Sign in failed:', result.errorCode);
+    }
+  };
+
+  const handleGoogleSignIn = async () => {
+    const result = await signInWithGoogle();
+    if (result.errorCode) {
+      console.error('Google sign in failed:', result.errorCode);
+    }
+  };
+
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+
+  if (isSignedIn) {
+    return (
+      <div>
+        <h1>Welcome, {user.displayName}!</h1>
+        <button onClick={signOut}>Sign Out</button>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      <button onClick={handleEmailSignIn}>Sign In with Email</button>
+      <button onClick={handleGoogleSignIn}>Sign In with Google</button>
+    </div>
+  );
+}
+```
+
+## Advanced Usage
+
+### 1. Custom Authentication Service
+
+You can implement your own authentication service by implementing the `AuthService` interface:
+
+```typescript
+import { AuthService, AuthResponse, UserData } from '@phygitallabs/tapquest-core';
+
+class CustomAuthService implements AuthService {
+  async signInWithEmailAndPassword(email: string, password: string): Promise<AuthResponse> {
+    // Your custom implementation
+    const response = await fetch('/api/auth/signin', {
+      method: 'POST',
+      body: JSON.stringify({ email, password }),
+    });
+
+    const data = await response.json();
+    return {
+      errorCode: data.error || '',
+      data: data.user || null,
+    };
+  }
+
+  // Implement other required methods...
+}
+```
+
+### 2. Authentication Callbacks
+
+Use callbacks to integrate with analytics, tracking, or other services:
+
+```typescript
+const authCallbacks = {
+  onUserIdentify: ({ email, name, avatar, uid }) => {
+    // Identify user in analytics
+    analytics.identify(uid, { email, name, avatar });
+  },
+
+  onSignInSuccess: (userData) => {
+    // Track sign-in event
+    analytics.track('User Signed In', {
+      method: userData.signInProvider,
+      email: userData.email,
+    });
+  },
+
+  onSignOutSuccess: () => {
+    // Track sign-out and reset tracking
+    analytics.track('User Signed Out');
+    analytics.reset();
+  },
+};
+```
+
+### 3. Storage Helpers
+
+The module provides centralized storage utilities for managing authentication data:
+
+```typescript
+import {
+  setUserInfo,
+  getUserInfo,
+  removeUserInfo,
+  setAccessToken,
+  getAccessToken,
+  removeAccessToken
+} from '@phygitallabs/tapquest-core';
+
+// Store user information
+setUserInfo(userData);
+
+// Retrieve user information
+const userData = getUserInfo();
+
+// Clear user information
+removeUserInfo();
+```
+
+## Storage Management
+
+The auth module uses centralized storage helpers that provide:
+
+- **Type Safety**: Proper typing for stored data
+- **Error Handling**: Safe JSON parsing with error recovery
+- **SSR Support**: Proper handling of server-side rendering
+- **Consistency**: Standardized storage keys and methods
+
+### Storage Keys
+
+The following keys are used for localStorage:
+
+- `phygital-user-info` - User profile data
+- `accessToken` - API access token
+- `refreshToken` - Token refresh credentials
+- `Device-UID` - Device identifier
+- `chip-auth-token` - Chip authentication token
+
+## Firebase Integration
+
+The `FirebaseAuthService` provides a complete Firebase Authentication implementation:
+
+### Features
+
+- **Lazy Loading**: Firebase modules are loaded only when needed
+- **SSR Safe**: Proper handling of server-side rendering
+- **Error Translation**: User-friendly error messages in Vietnamese
+- **Email Verification**: Enforced email verification for security
+- **Dynamic Imports**: Reduces bundle size by loading Firebase dynamically
+
+### Configuration
+
+```typescript
+const firebaseConfig = {
+  apiKey: "your-api-key",
+  authDomain: "your-project.firebaseapp.com",
+  projectId: "your-project",
+  storageBucket: "your-project.appspot.com",
+  messagingSenderId: "123456789",
+  appId: "1:123456789:web:abcdef",
+  measurementId: "G-XXXXXXXXXX"
+};
+
+const authService = new FirebaseAuthService(firebaseConfig);
+```
+
+## Type Definitions
+
+### User Roles
+
+```typescript
+enum UserRole {
+  NULL = "NULL",
+  SUPERADMIN = "SUPER_ADMIN",
+  ORGADMIN = "ORG_ADMIN",
+}
+```
+
+### Sign-in Providers
+
+```typescript
+type SignInProvider = "password" | "google.com";
+```
+
+### Authentication Response
+
+```typescript
+interface AuthResponse {
+  errorCode: string;
+  data: UserData | null;
+}
+```
+
+## Best Practices
+
+### 1. Error Handling
+
+Always handle authentication errors appropriately:
+
+```typescript
+const { signIn } = useAuth();
+
+const handleSignIn = async () => {
+  try {
+    const result = await signIn(email, password);
+    if (result.errorCode) {
+      // Display user-friendly error message
+      setError(result.errorCode);
+      return;
+    }
+    // Handle successful sign-in
+  } catch (error) {
+    // Handle unexpected errors
+    console.error('Sign in error:', error);
+    setError('An unexpected error occurred');
+  }
+};
+```
+
+### 2. Loading States
+
+Use the loading state to provide user feedback:
+
+```typescript
+const { isLoading, signIn } = useAuth();
+
+const handleSignIn = async () => {
+  if (isLoading) return; // Prevent double submissions
+
+  await signIn(email, password);
+};
+
+return (
+  <button disabled={isLoading} onClick={handleSignIn}>
+    {isLoading ? 'Signing in...' : 'Sign In'}
+  </button>
+);
+```
+
+### 3. Route Protection
+
+Create protected routes using authentication state:
+
+```typescript
+import { useAuth } from '@phygitallabs/tapquest-core';
+
+function ProtectedRoute({ children }) {
+  const { isSignedIn, isLoading } = useAuth();
+
+  if (isLoading) {
+    return <LoadingSpinner />;
+  }
+
+  if (!isSignedIn) {
+    return <Navigate to="/login" />;
+  }
+
+  return children;
+}
+```
+
+## API Reference
+
+### Hooks
+
+#### `useAuth()`
+
+Returns the complete authentication context with user state and actions.
+
+**Returns:**
+```typescript
+{
+  // State
+  user: UserData;
+  isSignedIn: boolean;
+  isLoading: boolean;
+
+  // Actions
+  signIn: (email: string, password: string) => Promise<AuthResponse>;
+  signInWithGoogle: () => Promise<AuthResponse>;
+  signUp: (email: string, password: string) => Promise<AuthResponse>;
+  signOut: () => Promise<void>;
+  forgotPassword: (email: string) => Promise<void>;
+  sendEmailVerification: () => Promise<void>;
+  changePassword: (newPassword: string) => Promise<void>;
+  updateScanStatus: (status: boolean) => void;
+  refreshUser: (userData: UserData) => void;
+}
+```
+
+### Providers
+
+#### `AuthProvider`
+
+Provides authentication context to child components.
+
+**Props:**
+```typescript
+{
+  children: React.ReactNode;
+  authService: AuthService;
+  authCallbacks?: AuthCallbacks;
+}
+```
+
+### Services
+
+#### `FirebaseAuthService`
+
+Firebase implementation of the AuthService interface.
+
+**Constructor:**
+```typescript
+new FirebaseAuthService(config: FirebaseConfig)
+```
+
+### Storage Helpers
+
+#### User Info
+- `getUserInfo(): UserData | null`
+- `setUserInfo(userData: UserData): void`
+- `removeUserInfo(): void`
+
+#### Tokens
+- `getAccessToken(): string | null`
+- `setAccessToken(token: string): void`
+- `removeAccessToken(): void`
+- `getRefreshToken(): string | null`
+- `setRefreshToken(token: string): void`
+- `removeRefreshToken(): void`
+
+#### Device Management
+- `getDeviceUid(): string | null`
+- `setDeviceUid(deviceId: string): void`
+- `removeDeviceUid(): void`
+- `checkDeviceUid(): Promise<string>`
+
+## Migration Guide
+
+If you're migrating from direct localStorage usage to the auth helpers:
+
+### Before
+```typescript
+// Direct localStorage usage
+localStorage.setItem('phygital-user-info', JSON.stringify(userData));
+const userInfo = JSON.parse(localStorage.getItem('phygital-user-info') || '{}');
+localStorage.removeItem('phygital-user-info');
+```
+
+### After
+```typescript
+// Using auth helpers
+import { setUserInfo, getUserInfo, removeUserInfo } from '@phygitallabs/tapquest-core';
+
+setUserInfo(userData);
+const userInfo = getUserInfo();
+removeUserInfo();
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Firebase not loading**: Ensure you're using the service in a client-side environment
+2. **Email verification required**: Check that email verification is properly handled
+3. **Storage errors**: Verify that localStorage is available and accessible
+4. **Type errors**: Ensure proper TypeScript configuration and type imports
+
+### Debug Mode
+
+Enable debug logging by setting localStorage debug flag:
+
+```typescript
+localStorage.setItem('debug', 'tapquest:auth');
+```
+
+## Contributing
+
+When contributing to the auth module:
+
+1. Maintain backward compatibility in public APIs
+2. Add proper TypeScript types for new features
+3. Include comprehensive tests for new functionality
+4. Update this documentation for any API changes
+5. Follow the existing code patterns and conventions
+
+## License
+
+This module is part of the TapQuest Core package and follows the same licensing terms.

package/src/modules/auth/constants/index.ts

@@ -0,0 +1,9 @@
+export const userInfoKey = "phygital-user-info";
+export const accessTokenKey = "accessToken";
+export const refreshTokenKey = "refreshToken";
+export const httpMaxRetries = 3;
+export const retryAttemptsRefreshToken = "retryAttemptsRefreshToken";
+
+export const deviceUIDKey = "Device-UID";
+export const chipAuthTokenKey = "chip-auth-token";
+