@phygitallabs/tapquest-core 2.0.0

package/README.md

@@ -0,0 +1,210 @@
+# @phygitallabs/tapquest-core
+
+A comprehensive React SDK that provides unified access to all Tapquest platform services including authentication, achievements, rewards, notifications, and certificate generation.
+
+## Overview
+
+Tapquest Core is the central SDK for building applications on the Phygital Labs Tapquest platform. It consolidates multiple specialized services into a single, easy-to-use React provider that handles authentication, service configuration, and API communication across different environments.
+
+## Features
+
+- **Unified Provider Architecture**: Single `TapquestCoreProvider` that wraps all platform services
+- **Multi-Environment Support**: Seamless switching between DEV, STAGING, and PRODUCTION environments
+- **Service Modules**:
+  - Authentication & Firebase integration (v1.0)
+  - Scan chip
+  - Location
+  - Campaign
+  - Achievement
+  - Reward
+  - Notifications
+  - Generate Certificate
+  - Ads
+  - Data tracking
+- **Built-in State Management**: Uses Zustand for efficient state management
+- **React Query Integration**: Optimized API caching and synchronization
+- **TypeScript Support**: Full type safety with generated type definitions
+
+## Installation
+
+```bash
+# Using pnpm (recommended for monorepo)
+pnpm add @phygitallabs/tapquest-core
+
+# Using npm
+npm install @phygitallabs/tapquest-core
+
+# Using yarn
+yarn add @phygitallabs/tapquest-core
+```
+
+## Quick Start
+
+### 1. Basic Setup
+
+```tsx
+import React from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { TapquestCoreProvider } from '@phygitallabs/tapquest-core';
+
+// Create a query client instance
+const queryClient = new QueryClient();
+
+// Define your API configuration
+const apiConfig = {
+  environment: 'DEV', // 'DEV' | 'STAGING' | 'PRODUCTION'
+  version: 'v1' // 'v1' | 'v2'
+};
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <TapquestCoreProvider
+        queryClient={queryClient}
+        apiConfig={apiConfig}
+      >
+        {/* Your app components */}
+        <YourAppContent />
+      </TapquestCoreProvider>
+    </QueryClientProvider>
+  );
+}
+```
+
+### 2. Using Services
+
+Once wrapped with `TapquestCoreProvider`, all Tapquest services are available throughout your application:
+
+```tsx
+import {
+  // Achievement services
+  useAchievements,
+
+  // Reward services
+  useRewards,
+
+  // Notification services
+  useNotifications,
+
+  // Certificate services
+  useCertificateGeneration,
+
+  // Auth services (when implemented)
+  // useAuth
+} from '@phygitallabs/tapquest-core';
+
+function YourComponent() {
+  const { achievements, loading } = useAchievements();
+  const { rewards } = useRewards();
+
+  return (
+    <div>
+      {/* Render your content using the services */}
+    </div>
+  );
+}
+```
+
+## Configuration
+
+### API Configuration
+
+The `apiConfig` object configures which environment and API version to use:
+
+```tsx
+interface APIConfig {
+  environment: 'DEV' | 'STAGING' | 'PRODUCTION';
+  version: 'v1' | 'v2';
+}
+```
+
+### Environment URLs
+
+The SDK automatically routes requests to the appropriate endpoints based on your environment:
+
+- **Development**: `https://api.dev.phygital.vn`
+- **Staging**: `https://api.staging.phygital.vn`
+- **Production**: `https://api.phygital.vn`
+
+## Architecture
+
+### Provider Hierarchy
+
+```
+TapquestCoreProvider
+├── FirebaseProvider (Authentication & Real-time features)
+├── AuthProvider (User authentication state)
+└── ServicesProvider (API services & configuration)
+    ├── Achievement Service
+    ├── Reward Service
+    ├── Notification Service
+    └── Certificate Service
+```
+
+### Module Structure
+
+```
+src/
+├── constants/          # Environment and service configurations
+├── modules/            # Service-specific modules
+│   ├── achievement/    # Achievement system integration
+│   ├── auth/          # Authentication utilities (in development)
+│   ├── notification/  # Push notification services
+│   ├── reward/        # Reward management
+│   └── generate-certificate/ # Certificate generation
+├── providers/         # React providers and context
+└── types/            # TypeScript type definitions
+```
+
+## Development
+
+### Building
+
+```bash
+# Build the package
+pnpm build
+
+# Build in watch mode for development
+pnpm dev
+```
+
+### Dependencies
+
+**Core Dependencies:**
+- React 18.2+
+- @tanstack/react-query ^5.66.8
+- Zustand ^5.0.8
+- Axios ^1.8.4
+
+**Internal Workspace Dependencies:**
+- @phygitallabs/achievement
+- @phygitallabs/api-core
+- @phygitallabs/generate-certificate
+- @phygitallabs/notification-api
+- @phygitallabs/reward
+- pgl-platform
+
+## TypeScript Support
+
+This package is built with TypeScript and includes full type definitions. All exported functions, hooks, and components are fully typed for the best development experience.
+
+```tsx
+import type { APIConfig, ServiceConfig } from '@phygitallabs/tapquest-core';
+```
+
+## Contributing
+
+This package is part of the Phygital Labs monorepo. When contributing:
+
+1. Ensure all new features include TypeScript types
+2. Follow the existing module structure for new services
+3. Update this README when adding new functionality
+4. Run tests and build before submitting changes
+
+## License
+
+Private package - All rights reserved by Phygital Labs.
+
+## Support
+
+For questions or issues, please contact the Phygital Labs development team or create an issue in the project repository.

package/index.ts

@@ -0,0 +1 @@
+export * from "./src";

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@phygitallabs/tapquest-core",
+  "version": "2.0.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "scripts": {
+    "preversion": "npm run build",
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "dependencies": {
+    "@phygitallabs/achievement": "^2.2.0",
+    "@phygitallabs/api-core": "^2.0.0",
+    "@phygitallabs/generate-certificate": "^2.0.0",
+    "@phygitallabs/notification-api": "^2.0.0",
+    "@phygitallabs/reward": "^2.0.0",
+    "@phygitallabs/helpers": "^2.0.0",
+    "@reduxjs/toolkit": "^1.9.5",
+    "@tanstack/react-query": "^5.66.8",
+    "axios": "^1.8.4",
+    "mem": "^10.0.0",
+    "posthog-js": "^1.246.0",
+    "react": ">=18.2",
+    "react-redux": "^8.0.7",
+    "redux-persist": "^6.0.0",
+    "typescript": "latest",
+    "uuid": "^13.0.0",
+    "zustand": "^5.0.8"
+  },
+  "peerDependencies": {
+    "firebase": "^10.0.0",
+    "react": ">=18.2"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.79",
+    "@types/react-redux": "^7.1.33",
+    "tsup": "latest",
+    "typescript": "latest"
+  }
+}

package/src/constants/firebase.ts

@@ -0,0 +1,36 @@
+import { EnvironmentType } from "../types/common";
+
+const FIREBASE_ENV = {
+    dev:{
+        "apiKey": "AIzaSyBFReJURBrU3hyiVvHHhMKcruiyy3mkEks",
+        "authDomain": "phy-nomion-staging.firebaseapp.com",
+        "projectId": "phy-nomion-staging",
+        "storageBucket": "phy-nomion-staging.appspot.com",
+        "messagingSenderId": "445937266499",
+        "appId": "1:445937266499:web:9ce9b49c13dcecd9b889f6",
+        "measurementId": "G-GWYSS45K15"
+    },
+    staging:{
+        "apiKey": "AIzaSyAXrJB8n4eZyq43kb9pUSelz9vfkJLHRK8",
+        "authDomain": "phygital-388705.firebaseapp.com",
+        "projectId": "phygital-388705",
+        "storageBucket": "assets-fygito",
+        "messagingSenderId": "174350081236",
+        "appId": "1:174350081236:web:da29144bf47cf775a5af41",
+        "measurementId": "G-JVHVWXMDC9"
+    },
+    production:{
+        "apiKey": "AIzaSyAXrJB8n4eZyq43kb9pUSelz9vfkJLHRK8",
+        "authDomain": "phygital-388705.firebaseapp.com",
+        "projectId": "phygital-388705",
+        "storageBucket": "assets-fygito",
+        "messagingSenderId": "174350081236",
+        "appId": "1:174350081236:web:da29144bf47cf775a5af41",
+        "measurementId": "G-JVHVWXMDC9"
+    },
+}
+
+export const firebaseConfig = (env: EnvironmentType) => {
+    return FIREBASE_ENV[env];
+  };
+  

package/src/constants/service.ts

@@ -0,0 +1,30 @@
+const serviceApiUrl = {
+    dev: {
+        API_BASE_URL: "https://backend-dev.nomion.io",
+        API_BASE_CORE_URL: "https://backend-dev.nomion.io/core",
+        API_ACHIEVEMENT_URL: "https://backend-dev.nomion.io/achievement",
+        API_REWARD_URL: "https://backend-dev.nomion.io/reward",
+        API_GENERATE_CERTIFICATE_URL: "https://media-prc-dev.nomion.io/api",
+        API_NOTIFICATION_SOCKET_URL: "https://backend-dev.nomion.io/notification-ws/ws",
+    },
+    staging: {
+        API_BASE_URL: "https://backend-staging.nomion.io",
+        API_BASE_CORE_URL: "https://backend-staging.nomion.io/core",
+        API_ACHIEVEMENT_URL: "https://backend-staging.nomion.io/achievement",
+        API_REWARD_URL: "https://backend-staging.nomion.io/reward",
+        API_GENERATE_CERTIFICATE_URL: "https://media-prc-staging.nomion.io/api",
+        API_NOTIFICATION_SOCKET_URL: "https://backend-staging.nomion.io/notification-ws/ws",
+
+    },
+    production: {
+        API_BASE_URL: "https://backend.nomion.io",
+        API_BASE_CORE_URL: "https://backend.nomion.io/core",
+        API_ACHIEVEMENT_URL: "https://backend.nomion.io/achievement",
+        API_REWARD_URL: "https://backend.nomion.io/reward",
+        API_GENERATE_CERTIFICATE_URL: "https://media-prc.nomion.io/api",
+        API_NOTIFICATION_SOCKET_URL: "https://backend.nomion.io/notification-ws/ws",
+
+    },
+}
+
+export default serviceApiUrl;

package/src/helper/helpers.ts

@@ -0,0 +1,3 @@
+import { cn, parse, fileToBase64 } from "@phygitallabs/helpers";
+
+export { cn, parse, fileToBase64 };

package/src/helper/index.ts

@@ -0,0 +1 @@
+export * from "./helpers";

package/src/index.ts

@@ -0,0 +1,25 @@
+// Export all modules
+export * from "./modules/achievement";
+export * from "./modules/reward";
+export * from "./modules/notification";
+export * from "./modules/memory";
+
+export * from "./modules/auth";
+export * from "./modules/user-profile";
+
+export * from "./modules/scan-chip";
+export * from "./modules/campaign";
+
+export * from "./modules/location";
+
+export * from "./modules/generate-certificate";
+
+export * from "./modules/data-tracking";
+
+export * from "./providers";
+
+export * from "./modules/achivementWithReward";
+
+export * from "./modules/send-email";
+
+export * from "./helper";

package/src/modules/achievement/helpers/index.ts

@@ -0,0 +1,98 @@
+import { Achievement, UserAchievementProgress } from "../types";
+
+const getLocationIdsFromAchievementRule = (achievement: Achievement) => {
+    if (!achievement.rule) return [];
+    const locationIds: string[] = [];
+    Object.values(achievement.rule).forEach((ruleList) => {
+        if (!ruleList.rules) return;
+        ruleList.rules.forEach((rule) => {
+            if (!rule.filter) return;
+            Object.values(rule.filter).forEach((filterList) => {
+                if (!filterList.filters) return;
+                filterList.filters.forEach((filter) => {
+                    if (filter.label === "location_id" && filter.value) {
+                        if (Array.isArray(filter.value)) {
+                            locationIds.push(...filter.value);
+                        } else {
+                            locationIds.push(filter.value);
+                        }
+                    }
+                });
+            });
+        });
+    });
+    return Array.from(new Set(locationIds)) as string[];
+};
+
+const getActionsFromAchievementRule = (achievement: Achievement) => {
+    if (!achievement.rule) return [];
+    const actions: string[] = [];
+    Object.values(achievement.rule).forEach((ruleList) => {
+        if (!ruleList.rules) return;
+        ruleList.rules.forEach((rule) => {
+            if (rule.action) {
+                actions.push(rule.action)
+            }
+        });
+    });
+    return Array.from(new Set(actions)) as string[];
+};
+
+const isAchievementCompleted = (achievement: UserAchievementProgress) => {
+    return achievement.isCompleted || achievement.overallPercentage === 100;
+}
+
+type SnakeToCamelCase<S extends string> = S extends `${infer T}_${infer U}`
+  ? `${T}${Capitalize<SnakeToCamelCase<U>>}`
+  : S;
+
+type ConvertSnakeToCamel<T> = T extends (infer U)[]
+  ? ConvertSnakeToCamel<U>[]
+  : T extends Record<string, unknown>
+  ? {
+      [K in keyof T as K extends string
+        ? SnakeToCamelCase<K>
+        : K]: ConvertSnakeToCamel<T[K]>;
+    }
+  : T;
+
+/**
+ * Converts snake_case keys to camelCase keys in an object or array of objects
+ */
+export function convertSnakeToCamel<T>(obj: T): ConvertSnakeToCamel<T> {
+    if (obj === null || obj === undefined) {
+      return obj as ConvertSnakeToCamel<T>;
+    }
+  
+    if (Array.isArray(obj)) {
+      return obj.map((item) =>
+        convertSnakeToCamel(item)
+      ) as ConvertSnakeToCamel<T>;
+    }
+  
+    if (typeof obj === "object" && obj.constructor === Object) {
+      const converted: Record<string, unknown> = {};
+  
+      for (const key in obj) {
+        if (obj.hasOwnProperty(key)) {
+          const camelKey = key.replace(/_([a-z])/g, (_, letter) =>
+            letter.toUpperCase()
+          );
+          converted[camelKey] = convertSnakeToCamel(
+            (obj as Record<string, unknown>)[key]
+          );
+        }
+      }
+  
+      return converted as ConvertSnakeToCamel<T>;
+    }
+  
+    return obj as ConvertSnakeToCamel<T>;
+  }
+  
+
+export {
+    getLocationIdsFromAchievementRule,
+    getActionsFromAchievementRule,
+    isAchievementCompleted
+}

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

@@ -0,0 +1,171 @@
+import { GetManyAchievementProgressParams, GetManyDeviceUidAchievementProgressParams, GetManyUserOrDeviceAchievementProgressParams } from "@phygitallabs/achievement";
+
+import {
+    GetManyAchievementProgressByDeviceParams,
+} from "@phygitallabs/api-core";
+
+import { useManyAchievementProgress as useManyAchievementProgressCore } from "@phygitallabs/achievement";
+import { useManyAchievementProgressByDevice as useManyAchievementProgressByDeviceCore } from "@phygitallabs/api-core";
+
+//  Core react query hooks
+import {
+    useAchievementProgress,
+    useManyAchievements,
+    useUserAchievementAction,
+    useManyChildrenAchievements,
+    useOneAchievement,
+    useManyAchievementsRewardModels,
+} from "@phygitallabs/achievement";
+
+import { isAchievementCompleted, convertSnakeToCamel } from "../helpers";
+
+export {
+    useAchievementProgress,
+    useManyAchievements,
+    useUserAchievementAction,
+    useManyChildrenAchievements,
+    useOneAchievement,
+    useManyAchievementsRewardModels,
+}
+
+// Customize react query hooks
+
+// Get achievement progress list by userid or deviceuid base on login status
+export const useManyAchievementProgress = (
+    params: GetManyUserOrDeviceAchievementProgressParams,
+    options?: any
+) => {
+
+    const isLoggedIn = !!params.userId;
+
+    const queryParams = isLoggedIn
+        ? {
+            achievementIds: params.achievementIds,
+            userId: params.userId!,
+            applicationId: params.applicationId,
+        } as GetManyAchievementProgressParams
+        : {
+            achievement_ids: params.achievementIds,
+            device_uid: params.deviceUid!,
+            applicationId: params.applicationId,
+        } as GetManyDeviceUidAchievementProgressParams;
+
+    if (isLoggedIn) {
+        return useManyAchievementProgressCore(queryParams as GetManyAchievementProgressParams,
+            {
+                ...options,
+                select: (data) => data.map((item) => ({
+                    ...item,
+                    isCompleted: isAchievementCompleted(item),
+                })),
+            }
+        );
+    }
+
+    return useManyAchievementProgressByDeviceCore(
+        queryParams as GetManyAchievementProgressByDeviceParams, {
+        ...options,
+        select: (data) => {
+            const camelCaseData = convertSnakeToCamel(data);
+            return camelCaseData.map((item) => ({
+                ...item,
+                isCompleted: isAchievementCompleted(item),
+            }));
+        },
+    });
+};
+
+// export const useManyAchievementWithProgress = (
+//     params: UseManyAchievementWithProgressParams,
+//     options?: {
+//         achievementOptions?: Partial<UseQueryOptions>;
+//         progressOptions?: Partial<UseQueryOptions>;
+//     }
+// ): UseManyAchievementWithProgressReturn => {
+//     // Fetch achievements with retry logic
+//     const achievementsQuery = useManyAchievements(
+//         {
+//             ...(params.achievementIds?.length && { ids: params.achievementIds }),
+//         },
+//         {
+//             retry: (failureCount: number, error: Error) => {
+//                 // Retry up to 3 times with exponential backoff
+//                 if (failureCount < 3) {
+//                     console.warn(`Achievement fetch failed, retrying... (${failureCount + 1}/3)`, error);
+//                     return true;
+//                 }
+//                 return false;
+//             },
+//             retryDelay: (attemptIndex: number) => Math.min(1000 * 2 ** attemptIndex, 30000),
+//             staleTime: 5 * 60 * 1000, // 5 minutes
+//             gcTime: 10 * 60 * 1000, // 10 minutes
+//             ...options?.achievementOptions,
+//         }
+//     );
+
+//     // Prepare achievement IDs for progress query
+//     const achievementIds = useMemo(() => {
+//         if (params.achievementIds?.length) {
+//             return params.achievementIds;
+//         }
+//         return achievementsQuery.data?.data?.map((a: any) => a.id) || [];
+//     }, [params.achievementIds, achievementsQuery.data]);
+
+//     // Fetch progress with retry logic (dependent on achievements)
+//     const progressQuery = useManyAchievementProgress(
+//         {
+//             achievementIds,
+//             userId: params.userId,
+//             deviceUid: params.deviceUid,
+//             applicationId: params.applicationId,
+//         },
+//         {
+//             enabled: achievementIds.length > 0
+//         }
+//     );
+
+//     // Combine data with error flags
+//     const combinedData = useMemo((): AchievementWithProgress[] => {
+//         const achievements = achievementsQuery.data?.data || [];
+//         const progressData = progressQuery.data || [];
+
+//         return achievements.map((achievement: any) => {
+//             const progress = progressData.find((p: any) => p.achievementId === achievement.id) || null;
+
+//             return {
+//                 achievement,
+//                 progress,
+//                 hasAchievementError: !!achievementsQuery.error,
+//                 hasProgressError: !!progressQuery.error,
+//             };
+//         });
+//     }, [achievementsQuery.data, progressQuery.data, achievementsQuery.error, progressQuery.error]);
+
+//     // Refetch functions
+//     const refetchAchievements = () => {
+//         console.log("Manually refetching achievements...");
+//         achievementsQuery.refetch();
+//     };
+
+//     const refetchProgress = () => {
+//         console.log("Manually refetching progress...");
+//         progressQuery.refetch();
+//     };
+
+//     const refetchAll = () => {
+//         console.log("Manually refetching all data...");
+//         Promise.all([achievementsQuery.refetch(), progressQuery.refetch()]);
+//     };
+
+//     return {
+//         data: combinedData,
+//         isLoading: achievementsQuery.isLoading || (achievementIds.length > 0 && progressQuery.isLoading),
+//         isSuccess: achievementsQuery.isSuccess && (achievementIds.length === 0 || progressQuery.isSuccess),
+//         achievementsError: achievementsQuery.error as Error | null,
+//         progressError: progressQuery.error as Error | null,
+//         refetchAchievements,
+//         refetchProgress,
+//         refetchAll,
+//     };
+// };
+

package/src/modules/achievement/index.ts

@@ -0,0 +1,5 @@
+export * from "./hooks";
+
+export * from "./types";
+
+export * from "./helpers";

package/src/modules/achievement/types/index.ts

@@ -0,0 +1,45 @@
+export {
+    AchievementRuleActionType,
+    AchievementServiceProvider,
+} from "@phygitallabs/achievement";
+
+import type { Achievement, GetAchievementProgressResponse, UserAchievementProgress } from "@phygitallabs/achievement";
+
+export {
+    Achievement,
+    GetAchievementProgressResponse,
+    UserAchievementProgress,
+}
+
+// Combined types for hooks
+export interface AchievementWithProgress {
+    achievement: Achievement;
+    progress: UserAchievementProgress | null;
+    hasProgressError?: boolean;
+    hasAchievementError?: boolean;
+}
+
+export interface UseManyAchievementWithProgressParams {
+    userId?: string;
+    deviceUid?: string;
+    applicationId?: string;
+    achievementIds?: string[];
+}
+
+export interface UseManyAchievementWithProgressReturn {
+    data: AchievementWithProgress[];
+    isLoading: boolean;
+    isSuccess: boolean;
+    achievementsError: Error | null;
+    progressError: Error | null;
+    refetchAchievements: () => void;
+    refetchProgress: () => void;
+    refetchAll: () => void;
+}
+
+export enum AchievementType {
+    DEFAULT = "default",
+    MULTIPLE_CHECK_INS = "multiple_check_ins",
+    RANDOM_CHECK_INS = "random_check_ins",
+    GROUP_MISSION = "group_mission",
+}