npm package: @phygitallabs/tapquest-core
Description: A comprehensive React SDK that provides unified access to all Tapquest platform services including authentication, achievements, rewards, notifications, and certificate generation.
Latest version: 6.7.18

# @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
- @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.

```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.