@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

# 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

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:

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:

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

# 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
• @phygitallabs/portal-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.

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.