feat: add a universal user struct with generic data type

Author: BLANK-13

example/main.go

@@ -15,7 +15,6 @@ import (
 )
 
 func main() {
-
 	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 	defer cancel()
 
@@ -29,6 +28,9 @@ func main() {
 	// Example: Firebase Authentication
 	firebaseExample(ctx, auth)
 
+	// Example: BaseUser model
+	userModelExample(ctx, auth)
+
 	// Example: Cloudflare Storage
 	cloudflareExample(ctx)
 
@@ -83,6 +85,83 @@ func firebaseExample(ctx context.Context, auth *firebase.FirebaseAuth) {
 	}
 }
 
+func userModelExample(ctx context.Context, auth *firebase.FirebaseAuth) {
+	fmt.Println("\n=== BaseUser Model Example ===")
+
+	// Define an application-specific user data type
+	type AppUserData struct {
+		Preferences     map[string]string `json:"preferences"`
+		LastActive      time.Time         `json:"lastActive"`
+		ProfileComplete bool              `json:"profileComplete"`
+	}
+
+	// Create a test user
+	userParams := (&officialFirebaseAuth.UserToCreate{}).
+		Email("[email protected]").
+		Password("password123").
+		DisplayName("Base User Test")
+
+	uid, err := auth.CreateUser(ctx, userParams)
+	if err != nil {
+		log.Printf("Failed to create user: %v", err)
+		return
+	}
+	log.Printf("Created user with Firebase UID: %s", uid)
+
+	// Set some custom claims
+	claims := map[string]interface{}{
+		"admin": true,
+		"roles": []interface{}{"editor", "viewer"},
+		"level": 5,
+	}
+
+	if err := auth.SetCustomClaims(ctx, uid, claims); err != nil {
+		log.Printf("Failed to set custom claims: %v", err)
+	}
+
+	// Get the Firebase user
+	fbUser, err := auth.GetUserByUID(ctx, uid)
+	if err != nil {
+		log.Printf("Failed to get user: %v", err)
+		return
+	}
+
+	// Create app-specific user data
+	userData := AppUserData{
+		Preferences: map[string]string{
+			"theme":    "dark",
+			"language": "en",
+		},
+		LastActive:      time.Now(),
+		ProfileComplete: false,
+	}
+
+	// Convert to our BaseUser model
+	baseUser := firebase.FromFirebaseUser[AppUserData](fbUser, userData)
+
+	// Display the user model
+	log.Printf("BaseUser created with ID: %s (different from Firebase UID: %s)",
+		baseUser.ID, baseUser.FirebaseUID)
+
+	// Demonstrate claims/roles helpers
+	isAdmin, _ := baseUser.GetClaim("admin")
+	log.Printf("User is admin: %v", isAdmin)
+
+	log.Printf("User has editor role: %v", baseUser.HasRole("editor"))
+	log.Printf("User has admin role: %v", baseUser.HasRole("admin"))
+
+	// Show app-specific data
+	log.Printf("User preferences: %v", baseUser.Data.Preferences)
+	log.Printf("Profile complete: %v", baseUser.Data.ProfileComplete)
+
+	// Clean up - delete user
+	if err := auth.DeleteUser(ctx, uid); err != nil {
+		log.Printf("Failed to delete user: %v", err)
+	} else {
+		log.Printf("Deleted user: %s", uid)
+	}
+}
+
 func cloudflareExample(ctx context.Context) {
 	fmt.Println("\n=== Cloudflare Storage Example ===")
 

firebase/user.go

@@ -0,0 +1,108 @@
+package firebase
+
+import (
+	"time"
+
+	"firebase.google.com/go/v4/auth"
+	"github.com/google/uuid"
+)
+
+// BaseUser contains universal user properties across any application
+type BaseUser[T any] struct {
+	// Core identifiers
+	ID          string `json:"id"`          // Database primary key/ID
+	FirebaseUID string `json:"firebaseUid"` // Firebase authentication UID
+	Email       string `json:"email"`       // User's email address
+	
+	// Common user metadata
+	DisplayName string     `json:"displayName,omitempty"`
+	PhotoURL    string     `json:"photoUrl,omitempty"`
+	CreatedAt   time.Time  `json:"createdAt"`
+	UpdatedAt   time.Time  `json:"updatedAt"`
+	LastLoginAt *time.Time `json:"lastLoginAt,omitempty"`
+	Disabled    bool       `json:"disabled"`
+	
+	// Authentication properties
+	EmailVerified bool              `json:"emailVerified"`
+	Claims        map[string]interface{} `json:"claims,omitempty"`
+	
+	// Application-specific user data
+	Data T `json:"data"`
+}
+
+// FromFirebaseUser converts a Firebase UserRecord to a BaseUser
+func FromFirebaseUser[T any](user *auth.UserRecord, data T) *BaseUser[T] {
+	lastLogin := user.UserMetadata.LastLogInTimestamp
+	var lastLoginTime *time.Time
+	
+	if lastLogin > 0 {
+		t := time.Unix(lastLogin/1000, 0)
+		lastLoginTime = &t
+	}
+	
+	createdAt := time.Unix(user.UserMetadata.CreationTimestamp/1000, 0)
+	
+	return &BaseUser[T]{
+		ID:            uuid.New().String(),
+		FirebaseUID:   user.UID,
+		Email:         user.Email,
+		DisplayName:   user.DisplayName,
+		PhotoURL:      user.PhotoURL,
+		CreatedAt:     createdAt,
+		UpdatedAt:     createdAt,
+		LastLoginAt:   lastLoginTime,
+		Disabled:      user.Disabled,
+		EmailVerified: user.EmailVerified,
+		Claims:        user.CustomClaims,
+		Data:          data,
+	}
+}
+
+// ToFirebaseUpdate converts a BaseUser to auth.UserToUpdate for Firebase updates
+func (u *BaseUser[T]) ToFirebaseUpdate() *auth.UserToUpdate {
+	update := (&auth.UserToUpdate{}).
+		Email(u.Email).
+		DisplayName(u.DisplayName).
+		PhotoURL(u.PhotoURL).
+		EmailVerified(u.EmailVerified).
+		Disabled(u.Disabled)
+		
+	return update
+}
+
+// GetClaim retrieves a specific claim value with type safety
+func (u *BaseUser[T]) GetClaim(key string) (interface{}, bool) {
+	if u.Claims == nil {
+		return nil, false
+	}
+	
+	val, ok := u.Claims[key]
+	return val, ok
+}
+
+// HasRole checks if a user has a specific role
+func (u *BaseUser[T]) HasRole(role string) bool {
+	if u.Claims == nil {
+		return false
+	}
+	
+	// Check roles array if it exists
+	if roles, ok := u.Claims["roles"]; ok {
+		if rolesArr, ok := roles.([]interface{}); ok {
+			for _, r := range rolesArr {
+				if r == role {
+					return true
+				}
+			}
+		}
+	}
+	
+	// Check direct role claim
+	if val, ok := u.Claims[role]; ok {
+		if boolVal, ok := val.(bool); ok {
+			return boolVal
+		}
+	}
+	
+	return false
+}