Fans United App Boilerplate Core

A comprehensive React package that provides core functionalities for integrating with the Fans United ecosystem. This package offers a clean, type-safe interface for working with Fans United APIs, Firebase authentication, and analytics tracking.

Features

• 🚀 Easy Setup: Simple configuration with automatic SDK initialization
• 🔐 Firebase Authentication: Built-in Firebase auth integration with Google sign-in support
• ⚛️ React Integration: Ready-to-use React context providers and hooks
• 📊 Analytics Tracking: Firebase Analytics integration with consent management
• 🛡️ Type Safety: Full TypeScript support with comprehensive type definitions
• 🔄 Error Handling: Robust error handling with retry logic and graceful fallbacks
• 🎯 Profile Management: Automatic profile fetching and management
• 🔧 Flexible Auth Providers: Support for cookies, localStorage, and custom auth providers

Installation

Install the package along with its required peer dependencies:

npm install fansunited-app-boilerplate-core fansunited-sdk-esm firebase
# or
yarn add fansunited-app-boilerplate-core fansunited-sdk-esm firebase
# or
pnpm add fansunited-app-boilerplate-core fansunited-sdk-esm firebase

Peer Dependencies

This package requires the following peer dependencies:

• fansunited-sdk-esm (>=1.0.0)
• react (^18.0.0 || ^19.0.0)
• react-dom (^18.0.0 || ^19.0.0)
• firebase (^10.0.0 || ^11.0.0)

Environment Variables

This package requires both Fans United and Firebase configuration. Set up the following environment variables in your project:

Fans United Configuration

NEXT_PUBLIC_FANS_UNITED_API_KEY=your-api-key
NEXT_PUBLIC_FANS_UNITED_CLIENT_ID=your-client-id
NEXT_PUBLIC_FANS_UNITED_ENV=prod
NEXT_PUBLIC_FANS_UNITED_LANGUAGE=en
NEXT_PUBLIC_FANS_UNITED_ID_SCHEMA=sportal365

Firebase Configuration

NEXT_PUBLIC_FIREBASE_API_KEY=your-firebase-api-key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
NEXT_PUBLIC_FIREBASE_APP_ID=your-app-id
NEXT_PUBLIC_GA_MEASUREMENT_ID=your-measurement-id

Quick Start

1. Wrap Your App with Providers

The package provides two main providers that should wrap your application:

import {
  FansUnitedSDKProvider,
  AuthProvider,
} from "fansunited-app-boilerplate-core";

const config = {
  apiKey: process.env.NEXT_PUBLIC_FANS_UNITED_API_KEY!,
  clientId: process.env.NEXT_PUBLIC_FANS_UNITED_CLIENT_ID!,
  environment: process.env.NEXT_PUBLIC_FANS_UNITED_ENV,
  lang: process.env.NEXT_PUBLIC_FANS_UNITED_LANGUAGE,
  idSchema: process.env.NEXT_PUBLIC_FANS_UNITED_ID_SCHEMA,
};

function App() {
  return (
    <AuthProvider>
      <FansUnitedSDKProvider config={config}>
        <YourApp />
      </FansUnitedSDKProvider>
    </AuthProvider>
  );
}

2. Use Authentication Hooks

import { useAuth } from "fansunited-app-boilerplate-core";

function LoginComponent() {
  const { user, signIn, signInWithGoogle, signUp, logout, loading } = useAuth();

  const handleEmailSignIn = async (email: string, password: string) => {
    try {
      await signIn(email, password);
    } catch (error) {
      console.error("Sign in failed:", error);
    }
  };

  const handleGoogleSignIn = async () => {
    try {
      await signInWithGoogle();
    } catch (error) {
      console.error("Google sign in failed:", error);
    }
  };

  if (loading) return <div>Loading...</div>;

  return (
    <div>
      {user ? (
        <div>
          <p>Welcome, {user.displayName || user.email}!</p>
          <button onClick={logout}>Logout</button>
        </div>
      ) : (
        <div>
          <button onClick={handleGoogleSignIn}>Sign in with Google</button>
          {/* Your email/password form here */}
        </div>
      )}
    </div>
  );
}

3. Access Fans United SDK and Profile

import {
  useFansUnitedSDK,
  useFansUnitedProfile,
} from "fansunited-app-boilerplate-core";

function ProfileComponent() {
  const { sdk, isAuthenticated, isLoading, error } = useFansUnitedSDK();
  const { profile, refreshProfile } = useFansUnitedProfile();

  if (isLoading) return <div>Loading SDK...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h2>SDK Status</h2>
      <p>Authenticated: {isAuthenticated ? "Yes" : "No"}</p>

      {profile && (
        <div>
          <h3>Profile</h3>
          <p>ID: {profile.id}</p>
          <p>Email: {profile.email}</p>
          <button onClick={refreshProfile}>Refresh Profile</button>
        </div>
      )}

      {sdk && <p>SDK initialized and ready to use</p>}
    </div>
  );
}

Configuration Options

SDK Configuration

The FansUnitedSDKProvider accepts a configuration object with the following properties:

interface SDKConfiguraitonModel {
  apiKey: string;
  clientId: string;
  environment?: EnvironmentType; // Optional: 'dev' | 'prod' | 'staging' | 'watg' | 'yolo' | 'cska'
  lang?: LangType; // Optional: 'bg' | 'en' | 'ro' | 'el' | 'sk'
  idSchema?: IdSchemaType; // Optional: 'native' | 'enetpulse' | 'sportal365' | 'sportradar'
  errorHandlingMode?: ErrorHandlingModeType; // Optional: 'default' | 'standard'
}

Alternative Auth Providers

While the package uses Firebase authentication by default, you can also use standalone auth providers for direct SDK integration:

Cookie-based Authentication

import { CookieAuthProvider } from "fansunited-app-boilerplate-core";

const authProvider = new CookieAuthProvider("auth-token", () => {
  console.log("User logged out");
});

localStorage Authentication

import { LocalStorageAuthProvider } from "fansunited-app-boilerplate-core";

const authProvider = new LocalStorageAuthProvider("fans-united-token");

Custom Authentication

import { CustomAuthProvider } from "fansunited-app-boilerplate-core";

const authProvider = new CustomAuthProvider(
  () => getTokenFromYourAuthSystem(),
  () => handleLogoutInYourSystem()
);

API Reference

Core Functions

initializeFansUnitedSDK(config: SDKConfiguraitonModel)

Initialize the global SDK factory with configuration.

import { initializeFansUnitedSDK } from "fansunited-app-boilerplate-core";

const factory = initializeFansUnitedSDK({
  apiKey: "your-api-key",
  clientId: "your-client-id",
  environment: "prod",
});

getFansUnitedSDKFactory()

Get the global SDK factory instance.

getFansUnitedSDK(type?: "private" | "public")

Get an SDK instance. Legacy compatibility function.

React Context Providers

AuthProvider

Provides Firebase authentication context.

import { AuthProvider } from "fansunited-app-boilerplate-core";

<AuthProvider useAuthTracking={true}>{children}</AuthProvider>;

FansUnitedSDKProvider

Provides Fans United SDK context with automatic initialization.

import { FansUnitedSDKProvider } from "fansunited-app-boilerplate-core";

<FansUnitedSDKProvider config={sdkConfig}>{children}</FansUnitedSDKProvider>;

React Hooks

useAuth()

Access Firebase authentication state and methods.

const {
  user,
  loading,
  signIn,
  signUp,
  signInWithGoogle,
  logout,
  resetPassword,
  refreshToken,
} = useAuth();

useFansUnitedSDK()

Access the main SDK context.

const { sdk, profile, isAuthenticated, isLoading, error, refreshProfile } =
  useFansUnitedSDK();

useFansUnitedProfile()

Convenience hook for accessing just the profile data.

const { profile, isLoading, error, refreshProfile } = useFansUnitedProfile();

Analytics Hooks

useAnalyticsTracking()

Hook for tracking analytics events.

import { useAnalyticsTracking } from "fansunited-app-boilerplate-core";

const { trackAuth } = useAnalyticsTracking();

// Track authentication events
trackAuth("google", "login");
trackAuth("email", "sign_up");

Error Handling

The package provides robust error handling with automatic retries and graceful fallbacks:

import { useFansUnitedSDK } from "fansunited-app-boilerplate-core";

function MyComponent() {
  const { sdk, error, isLoading } = useFansUnitedSDK();

  if (isLoading) return <div>Loading...</div>;

  if (error) {
    return (
      <div>
        <p>Error: {error.message}</p>
        {error.message.includes("Profile not found") && (
          <p>
            Your profile is still being set up. Please try again in a moment.
          </p>
        )}
      </div>
    );
  }

  return <div>SDK ready!</div>;
}

Firebase Integration

The package automatically handles Firebase initialization and provides:

• Authentication: Email/password and Google sign-in
• Analytics: Event tracking with consent management
• Token Management: Automatic token refresh and validation

Analytics Events

The package automatically tracks authentication events:

// These events are tracked automatically:
// - sign_up (method: 'email' | 'google')
// - login (method: 'email' | 'google')
// - logout (method: 'email' | 'google')

TypeScript Support

The package is built with TypeScript and provides comprehensive type definitions:

import type {
  FansUnitedSDKContextType,
  SDKConfiguraitonModel,
  AuthContextType,
} from "fansunited-app-boilerplate-core";

// All Firebase types are also re-exported
import type { User } from "fansunited-app-boilerplate-core";

Advanced Usage

Using the SDK Factory Directly

For advanced use cases, you can use the SDK factory directly:

import {
  initializeFansUnitedSDK,
  getFansUnitedSDKFactory,
  CookieAuthProvider,
} from "fansunited-app-boilerplate-core";

// Initialize the factory
const factory = initializeFansUnitedSDK(config);

// Create SDK instances with different auth providers
const cookieAuth = new CookieAuthProvider("my-token");
const privateSdk = factory.createWithAuthProvider(cookieAuth);
const publicSdk = factory.createPublic();

Environment-based Configuration

Create configuration from environment variables:

import { createConfigFromEnv } from "fansunited-app-boilerplate-core";

const config = createConfigFromEnv(process.env);
// Automatically maps NEXT_PUBLIC_FANS_UNITED_* variables

Support

For support and questions, please refer to the Fans United documentation and submit a ticket.