@pixygon/auth 1.0.0

package/src/types/index.ts

@@ -0,0 +1,310 @@
+/**
+ * @pixygon/auth - Shared Types
+ * Type definitions for the Pixygon authentication system
+ */
+
+// ============================================================================
+// User Types
+// ============================================================================
+
+export type UserRole = 'user' | 'creator' | 'admin' | 'superadmin';
+
+export type SubscriptionTier = 'free' | 'basic' | 'pro' | 'family' | 'enterprise';
+
+export interface User {
+  _id: string;
+  userName: string;
+  email: string;
+  isVerified: boolean;
+  role: UserRole;
+
+  // Profile
+  firstName?: string;
+  lastName?: string;
+  profilePicture?: string;
+
+  // Subscription
+  subscriptionTier?: SubscriptionTier;
+  stripeCustomerId?: string;
+
+  // Token system
+  dailyTokens?: number;
+  purchasedTokens?: number;
+  bonusTokens?: number;
+  subscriptionTokens?: number;
+
+  // Parental controls (for family plans)
+  isChildAccount?: boolean;
+  parentUserId?: string;
+
+  // API access
+  apiAccess?: boolean;
+
+  // Social links
+  discordUserId?: string;
+  twitchUser?: string;
+
+  // Timestamps
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+// ============================================================================
+// Token Types
+// ============================================================================
+
+export interface TokenPair {
+  accessToken: string;
+  refreshToken: string;
+  expiresIn: number; // seconds until access token expires
+  refreshExpiresIn: number; // seconds until refresh token expires
+}
+
+export interface TokenPayload {
+  id: string;
+  role?: UserRole;
+  iat: number;
+  exp: number;
+}
+
+// ============================================================================
+// Auth State Types
+// ============================================================================
+
+export type AuthStatus =
+  | 'idle'           // Initial state
+  | 'loading'        // Checking auth status
+  | 'authenticated'  // User is logged in
+  | 'unauthenticated' // No valid session
+  | 'verifying';     // Email verification pending
+
+export interface AuthState {
+  user: User | null;
+  accessToken: string | null;
+  refreshToken: string | null;
+  status: AuthStatus;
+  isLoading: boolean;
+  error: AuthError | null;
+}
+
+// ============================================================================
+// Auth Request/Response Types
+// ============================================================================
+
+export interface LoginRequest {
+  userName: string; // Can be username or email
+  password: string;
+}
+
+export interface LoginResponse {
+  user: User;
+  token: string;
+  refreshToken?: string;
+  expiresIn?: number;
+  message?: string;
+}
+
+export interface RegisterRequest {
+  userName: string;
+  email: string;
+  password: string;
+  confirmPassword?: string;
+}
+
+export interface RegisterResponse {
+  user: User;
+  message?: string;
+}
+
+export interface VerifyRequest {
+  userName: string;
+  verificationCode: string;
+}
+
+export interface VerifyResponse {
+  user: User;
+  token: string;
+  refreshToken?: string;
+  message?: string;
+}
+
+export interface ForgotPasswordRequest {
+  email: string;
+}
+
+export interface ForgotPasswordResponse {
+  message: string;
+}
+
+export interface RecoverPasswordRequest {
+  email: string;
+  recoveryCode: string;
+  newPassword: string;
+}
+
+export interface RecoverPasswordResponse {
+  message: string;
+}
+
+export interface RefreshTokenRequest {
+  refreshToken: string;
+}
+
+export interface RefreshTokenResponse {
+  token: string;
+  refreshToken: string;
+  expiresIn: number;
+}
+
+export interface ResendVerificationRequest {
+  userName: string;
+}
+
+export interface ResendVerificationResponse {
+  message: string;
+}
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+export type AuthErrorCode =
+  | 'INVALID_CREDENTIALS'
+  | 'USER_NOT_FOUND'
+  | 'USER_EXISTS'
+  | 'EMAIL_NOT_VERIFIED'
+  | 'INVALID_VERIFICATION_CODE'
+  | 'EXPIRED_VERIFICATION_CODE'
+  | 'INVALID_RECOVERY_CODE'
+  | 'EXPIRED_RECOVERY_CODE'
+  | 'TOKEN_EXPIRED'
+  | 'TOKEN_INVALID'
+  | 'REFRESH_TOKEN_EXPIRED'
+  | 'NETWORK_ERROR'
+  | 'SERVER_ERROR'
+  | 'UNKNOWN_ERROR';
+
+export interface AuthError {
+  code: AuthErrorCode;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Configuration Types
+// ============================================================================
+
+export interface AuthConfig {
+  /** Base URL for the auth API (e.g., https://pixygon-server.onrender.com/v1) */
+  baseUrl: string;
+
+  /** App identifier for token storage keys */
+  appId: string;
+
+  /** App display name for branded components */
+  appName?: string;
+
+  /** Enable automatic token refresh (default: true) */
+  autoRefresh?: boolean;
+
+  /** Time before expiry to trigger refresh in seconds (default: 300 = 5 min) */
+  refreshThreshold?: number;
+
+  /** Callback when user logs in */
+  onLogin?: (user: User) => void;
+
+  /** Callback when user logs out */
+  onLogout?: () => void;
+
+  /** Callback when token is refreshed */
+  onTokenRefresh?: (tokens: TokenPair) => void;
+
+  /** Callback when auth error occurs */
+  onError?: (error: AuthError) => void;
+
+  /** Storage mechanism (default: localStorage) */
+  storage?: AuthStorage;
+
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+}
+
+export interface AuthStorage {
+  getItem: (key: string) => string | null | Promise<string | null>;
+  setItem: (key: string, value: string) => void | Promise<void>;
+  removeItem: (key: string) => void | Promise<void>;
+}
+
+// ============================================================================
+// Context Types
+// ============================================================================
+
+export interface AuthContextValue extends AuthState {
+  // Auth actions
+  login: (credentials: LoginRequest) => Promise<LoginResponse>;
+  register: (data: RegisterRequest) => Promise<RegisterResponse>;
+  logout: () => Promise<void>;
+  verify: (data: VerifyRequest) => Promise<VerifyResponse>;
+  resendVerification: (data: ResendVerificationRequest) => Promise<ResendVerificationResponse>;
+  forgotPassword: (data: ForgotPasswordRequest) => Promise<ForgotPasswordResponse>;
+  recoverPassword: (data: RecoverPasswordRequest) => Promise<RecoverPasswordResponse>;
+  refreshTokens: () => Promise<void>;
+
+  // Utility
+  getAccessToken: () => string | null;
+  isAuthenticated: boolean;
+  isVerified: boolean;
+  hasRole: (role: UserRole | UserRole[]) => boolean;
+
+  // Config
+  config: AuthConfig;
+}
+
+// ============================================================================
+// Component Props Types
+// ============================================================================
+
+export interface LoginFormProps {
+  onSuccess?: (user: User) => void;
+  onError?: (error: AuthError) => void;
+  onNavigateRegister?: () => void;
+  onNavigateForgotPassword?: () => void;
+  showBranding?: boolean;
+  className?: string;
+}
+
+export interface RegisterFormProps {
+  onSuccess?: (user: User) => void;
+  onError?: (error: AuthError) => void;
+  onNavigateLogin?: () => void;
+  showBranding?: boolean;
+  className?: string;
+}
+
+export interface VerifyFormProps {
+  userName: string;
+  onSuccess?: (user: User) => void;
+  onError?: (error: AuthError) => void;
+  onNavigateLogin?: () => void;
+  showBranding?: boolean;
+  className?: string;
+}
+
+export interface ForgotPasswordFormProps {
+  onSuccess?: () => void;
+  onError?: (error: AuthError) => void;
+  onNavigateLogin?: () => void;
+  showBranding?: boolean;
+  className?: string;
+}
+
+export interface PixygonAuthProps {
+  mode: 'login' | 'register' | 'verify' | 'forgot-password' | 'recover-password';
+  onSuccess?: (user?: User) => void;
+  onError?: (error: AuthError) => void;
+  onModeChange?: (mode: string) => void;
+  userName?: string; // For verify mode
+  showBranding?: boolean;
+  theme?: 'dark' | 'light';
+  className?: string;
+}

package/src/utils/storage.ts

@@ -0,0 +1,167 @@
+/**
+ * @pixygon/auth - Token Storage Utilities
+ * Unified storage for auth tokens across all Pixygon apps
+ */
+
+import type { AuthStorage, User, TokenPair } from '../types';
+
+// Storage keys - prefixed with app ID for isolation
+const getKeys = (appId: string) => ({
+  ACCESS_TOKEN: `${appId}_access_token`,
+  REFRESH_TOKEN: `${appId}_refresh_token`,
+  USER: `${appId}_user`,
+  EXPIRES_AT: `${appId}_expires_at`,
+});
+
+// Default storage using localStorage
+const defaultStorage: AuthStorage = {
+  getItem: (key: string) => {
+    if (typeof window === 'undefined') return null;
+    return localStorage.getItem(key);
+  },
+  setItem: (key: string, value: string) => {
+    if (typeof window === 'undefined') return;
+    localStorage.setItem(key, value);
+  },
+  removeItem: (key: string) => {
+    if (typeof window === 'undefined') return;
+    localStorage.removeItem(key);
+  },
+};
+
+/**
+ * Create a token storage manager for a specific app
+ */
+export function createTokenStorage(appId: string, storage: AuthStorage = defaultStorage) {
+  const keys = getKeys(appId);
+
+  return {
+    /**
+     * Get the stored access token
+     */
+    getAccessToken: async (): Promise<string | null> => {
+      const token = await storage.getItem(keys.ACCESS_TOKEN);
+      return token;
+    },
+
+    /**
+     * Get the stored refresh token
+     */
+    getRefreshToken: async (): Promise<string | null> => {
+      const token = await storage.getItem(keys.REFRESH_TOKEN);
+      return token;
+    },
+
+    /**
+     * Get the stored user
+     */
+    getUser: async (): Promise<User | null> => {
+      const userJson = await storage.getItem(keys.USER);
+      if (!userJson) return null;
+      try {
+        return JSON.parse(userJson);
+      } catch {
+        return null;
+      }
+    },
+
+    /**
+     * Get token expiration time
+     */
+    getExpiresAt: async (): Promise<number | null> => {
+      const expiresAt = await storage.getItem(keys.EXPIRES_AT);
+      return expiresAt ? parseInt(expiresAt, 10) : null;
+    },
+
+    /**
+     * Check if access token is expired
+     */
+    isTokenExpired: async (): Promise<boolean> => {
+      const expiresAt = await storage.getItem(keys.EXPIRES_AT);
+      if (!expiresAt) return true;
+      return Date.now() >= parseInt(expiresAt, 10);
+    },
+
+    /**
+     * Check if token will expire within threshold (in seconds)
+     */
+    willExpireSoon: async (thresholdSeconds: number = 300): Promise<boolean> => {
+      const expiresAt = await storage.getItem(keys.EXPIRES_AT);
+      if (!expiresAt) return true;
+      const expiryTime = parseInt(expiresAt, 10);
+      const thresholdMs = thresholdSeconds * 1000;
+      return Date.now() >= expiryTime - thresholdMs;
+    },
+
+    /**
+     * Store tokens and user data
+     */
+    setTokens: async (
+      accessToken: string,
+      refreshToken: string | null,
+      expiresIn: number | null,
+      user: User
+    ): Promise<void> => {
+      await storage.setItem(keys.ACCESS_TOKEN, accessToken);
+
+      if (refreshToken) {
+        await storage.setItem(keys.REFRESH_TOKEN, refreshToken);
+      }
+
+      if (expiresIn) {
+        const expiresAt = Date.now() + expiresIn * 1000;
+        await storage.setItem(keys.EXPIRES_AT, expiresAt.toString());
+      }
+
+      await storage.setItem(keys.USER, JSON.stringify(user));
+    },
+
+    /**
+     * Update tokens after refresh
+     */
+    updateTokens: async (tokens: TokenPair): Promise<void> => {
+      await storage.setItem(keys.ACCESS_TOKEN, tokens.accessToken);
+      await storage.setItem(keys.REFRESH_TOKEN, tokens.refreshToken);
+      const expiresAt = Date.now() + tokens.expiresIn * 1000;
+      await storage.setItem(keys.EXPIRES_AT, expiresAt.toString());
+    },
+
+    /**
+     * Update user data
+     */
+    updateUser: async (user: User): Promise<void> => {
+      await storage.setItem(keys.USER, JSON.stringify(user));
+    },
+
+    /**
+     * Clear all stored auth data
+     */
+    clear: async (): Promise<void> => {
+      await storage.removeItem(keys.ACCESS_TOKEN);
+      await storage.removeItem(keys.REFRESH_TOKEN);
+      await storage.removeItem(keys.USER);
+      await storage.removeItem(keys.EXPIRES_AT);
+    },
+
+    /**
+     * Get all stored auth data
+     */
+    getAll: async () => {
+      const [accessToken, refreshToken, user, expiresAt] = await Promise.all([
+        storage.getItem(keys.ACCESS_TOKEN),
+        storage.getItem(keys.REFRESH_TOKEN),
+        storage.getItem(keys.USER),
+        storage.getItem(keys.EXPIRES_AT),
+      ]);
+
+      return {
+        accessToken,
+        refreshToken,
+        user: user ? JSON.parse(user) : null,
+        expiresAt: expiresAt ? parseInt(expiresAt, 10) : null,
+      };
+    },
+  };
+}
+
+export type TokenStorage = ReturnType<typeof createTokenStorage>;