PinkSurfing In-App Wallet SSO - Frontend Reference

A React + TypeScript reference implementation for the PinkSurfing In-App Wallet SSO system.

🎯 Overview

This frontend demonstrates how to integrate with the PinkSurfing backend's wallet-centric authentication and multi-chain wallet management system. It showcases:

• Crypto-native SSO: Users authenticate via their in-app wallet (no MetaMask/WalletConnect)
• MYBIZ Token Roles: UI adapts based on user's token holdings (Bronze → Platinum)
• Multi-chain Support: Seamless balance and transaction management across 7+ chains
• Secure Transactions: PIN-based authorization for semi-custodial wallets

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (React + Vite)                   │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  Auth Store  │  │ Wallet Store │  │   API Client │      │
│  │  (Zustand)   │  │  (Zustand)   │  │    (Axios)   │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
├─────────────────────────────────────────────────────────────┤
│  Pages: Login | Register | Dashboard | Wallet | Transfer    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                 PinkSurfing Backend API                      │
│  /auth/* (SSO)  │  /wallet/* (Operations)                   │
└─────────────────────────────────────────────────────────────┘

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn
• Backend server running on http://localhost:5000

Installation

# Navigate to the frontend directory
cd frontend-reference

# Install dependencies
npm install

# Start development server
npm run dev

The app will be available at http://localhost:3000

Environment Variables

Create a .env file:

VITE_API_URL=http://localhost:5000

📁 Project Structure

src/
├── main.tsx              # App entry point
├── App.tsx               # Router configuration
├── index.css             # Global styles + Tailwind
├── types/
│   └── index.ts          # TypeScript type definitions
├── services/
│   └── api.ts            # API client with auth interceptors
├── store/
│   ├── authStore.ts      # Authentication state (Zustand)
│   └── walletStore.ts    # Wallet state (Zustand)
├── components/
│   └── Layout.tsx        # App shell with navigation
└── pages/
    ├── LoginPage.tsx     # Email/password login
    ├── RegisterPage.tsx  # Account + wallet creation
    ├── DashboardPage.tsx # Overview with balances
    ├── WalletPage.tsx    # Token list + history
    ├── TransferPage.tsx  # Send crypto
    └── SettingsPage.tsx  # Security settings

🔐 Authentication Flow

1. Registration

// User creates account with wallet type selection
const response = await authApi.register({
  email: 'user@example.com',
  password: 'securePassword123',
  walletType: 'custodial', // or 'semi-custodial'
  pin: '123456',           // Required for semi-custodial
});

// Response includes user, tokens, and wallet
const { user, tokens, wallet } = response;

2. Login

// Standard email/password login
const response = await authApi.login('user@example.com', 'password');

// Tokens are automatically stored and used for subsequent requests

3. Token Refresh

The API client automatically handles token refresh:

// Interceptor in api.ts handles 401 responses
// Attempts refresh, then retries original request

💰 Wallet Operations

Get Balances

// Single chain
const balance = await walletApi.getBalance(137); // Polygon

// All chains
const balances = await walletApi.getAllBalances();

Send Transaction

const result = await walletApi.transfer({
  to: '0x...',
  amount: '1.5',
  chainId: 137,
  tokenAddress: '0x...', // Optional, omit for native token
  pin: '123456',         // Required for semi-custodial
});

🎨 MYBIZ Token Roles

The UI dynamically shows role benefits:

Role	MYBIZ Required	Benefits
Guest	0	Basic features
Bronze	100	Reduced fees, email support
Silver	1,000	Lower fees, priority support
Gold	10,000	Minimal fees, premium features
Platinum	100,000	Zero fees, VIP support

// Access current role
const role = useAuthStore((state) => state.user?.role);
const benefits = ROLE_BENEFITS[role];

⛓️ Supported Chains

• Ethereum (1)
• Polygon (137) - Primary
• BNB Chain (56)
• Arbitrum One (42161)
• Optimism (10)
• Base (8453)
• Avalanche (43114)

import { SUPPORTED_CHAINS } from './types';

// Get chain info
const polygon = SUPPORTED_CHAINS.find(c => c.chainId === 137);

🔒 Security Features

Semi-Custodial PIN

For semi-custodial wallets, transactions require PIN:

<input
  type="password"
  inputMode="numeric"
  maxLength={6}
  value={pin}
  onChange={(e) => setPin(e.target.value.replace(/\D/g, ''))}
  className="tracking-[0.5em] text-center"
/>

Security Settings

// Update security preferences
await walletApi.updateSecuritySettings({
  twoFactorEnabled: true,
  transactionNotifications: true,
  loginNotifications: true,
});

🛠️ Development

Type Safety

All API responses are fully typed:

interface WalletBalance {
  chainId: number;
  chainName: string;
  native: { symbol: string; balance: string; balanceFormatted: string; };
  tokens: TokenBalance[];
  totalUsdValue?: string;
}

State Management

Using Zustand with persistence:

// Auth store persists to localStorage
export const useAuthStore = create<AuthState>()(
  persist(
    (set, get) => ({
      user: null,
      tokens: null,
      // ...actions
    }),
    {
      name: 'pinksurfing-auth',
      storage: createJSONStorage(() => localStorage),
    }
  )
);

📱 Responsive Design

The app is fully responsive with:

• Mobile-first approach
• Bottom navigation on mobile
• Sidebar navigation on desktop
• Touch-friendly inputs

🔧 Customization

Styling

Tailwind CSS with custom theme in tailwind.config.js:

colors: {
  pink: { /* PinkSurfing brand */ },
  brand: {
    primary: '#ec4899',
    secondary: '#8b5cf6',
    accent: '#06b6d4',
  }
}

API Base URL

Configure in vite.config.ts proxy or .env:

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:5000',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, ''),
    },
  },
},

📚 API Reference

See full API documentation in the backend's api/routes/authRoutes.js and api/routes/walletRoutes.js.

Key Endpoints

Endpoint	Method	Description
/auth/login	POST	Email/password login
/auth/register	POST	Create account + wallet
/auth/refresh	POST	Refresh access token
/wallet/create	POST	Create new wallet
/wallet/balance/:chainId	GET	Get chain balance
/wallet/transfer	POST	Send transaction

🤝 Contributing

1. Follow existing code style
2. Use TypeScript strictly
3. Add types for new features
4. Test on multiple chains

📄 License

Proprietary - PinkSurfing © 2024