Chore authentication flow referral program

[omolobamoyinoluwa-max]

Summary

• Implement comprehensive Referral Program for the Authentication Flow
• Add referral code generation and validation utilities
• Extend user schema with referral fields (referralCode, referredBy, referralCount)
• Update signup API to handle optional referral codes
• Add referral validation endpoint (/api/referral/validate)
• Update signup frontend to include referral code input field
• Add comprehensive unit tests for referral utilities
• Add integration tests for referral API endpoints
• Update e2e tests to cover referral flow scenarios
• Create detailed documentation for the referral program

Features Implemented

• Referral Code Generation: Each user receives a unique 8-character referral code upon signup
• Referral Tracking: Users can enter a referral code during signup to track who referred them
• Referral Validation: The system validates referral codes before accepting them
• Referral Counting: Track the number of successful referrals for each user
• Self-Referral Prevention: Users cannot use their own referral code

Changes Made

• Created /src/lib/referral.ts with referral code utilities
• Modified /src/schemas/user.schema.ts to include referral fields
• Modified /src/types/api/auth.dto.ts to include referral code in signup request
• Modified /src/app/api/auth/signup/route.ts to handle referral codes
• Created /src/app/api/referral/validate/route.ts for referral code validation
• Modified /src/app/(auth)/signup/page.tsx to include referral code input field
• Modified /src/app/lib/validationSchemas.ts to include referral code validation
• Created /src/lib/__tests__/referral.test.ts for unit tests
• Created /src/app/api/referral/__tests__/validate.test.ts for integration tests
• Modified /e2e/auth/signup.spec.ts to include referral flow tests
• Created /docs/REFERRAL_PROGRAM.md for comprehensive documentation

Testing

• ✅ Unit tests for referral code utilities
• ✅ Integration tests for referral validation endpoint
• ✅ E2E tests for referral flow in signup process
• ✅ Documentation updated

Security Considerations

• Referral codes are validated for format before checking existence
• Self-referral prevention implemented
• Rate limiting on referral validation endpoint
• No confusing characters (I, O, 0, 1) in referral codes

Compatibility

• Backward compatible - referral fields are optional
• Existing users will receive referral codes on next login/update
• Mock implementation can be easily replaced with database integration

Closes #475

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Checklist

• Code follows project style guidelines
• Self-review completed
• No console errors
• Uses Lucide icons consistently
• Responsive design implemented
• Starknet best practices followed

[drips-wave]

@omolobamoyinoluwa-max Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits