Implement Referral System with Schema, Controllers, Routes, and Logging

[IkkiOcean]

Overview

This PR introduces the Referral schema, controller, and routes to handle referral functionalities in the application. It includes logging for important actions and a utility function to generate unique referral codes.

• Closes Implement Loyalty Points and Referral System: Schema, Controllers, Middleware, and Routes #961

Schema

The Referral schema defines the necessary fields for tracking referrals:

• referralCode: A unique code generated for each referral.
• referrerId: User ID of the person who created the referral code.
• refereeId: ID of the user who uses the referral code, if applicable.
• status: Status of the referral (e.g., pending, completed, expired).
• expiryDate: Date when the referral expires.
• createdAt and updatedAt: Timestamps for tracking referral lifecycle.

New Endpoints and Controllers

1. POST /api/referrals:

   • Controller: createReferral
   • Description: This endpoint generates a new referral code and saves it in the database. It accepts the referrerId in the request body and returns the generated referralCode along with a success message.
   • Logic:
     • The controller generates a unique referral code.
     • A new referral entry is created in the database with referrerId and the generated referral code.
     • Logs the referral creation action.
     • Returns the referral code in the response.

2. GET /api/referrals/:code/status:

   • Controller: checkReferralStatus
   • Description: This endpoint checks if a referral code is valid and returns its current status (e.g., pending, completed). The referral code is passed as a parameter in the URL.
   • Logic:
     • The controller checks the referralCode in the database.
     • If found, it returns the status of the referral.
     • If not found, it returns an error message.

3. POST /api/referrals/complete:

   • Controller: completeReferral
   • Description: This endpoint marks a referral as completed when a referee uses the referral code. It expects both referralCode and refereeId in the request body. It ensures that the referral code is valid and hasn't already been used.
   • Logic:
     • The controller finds the referral record by referralCode.
     • If the referral is valid and has not already been completed, it updates the status to completed and links the refereeId.
     • Logs the completion of the referral.
     • Returns a success message if the referral is completed.

4. GET /api/referrals/expired/:code:

   • Controller: checkReferralExpiry
   • Description: This endpoint checks if a referral code has expired based on its expiryDate. It returns the status (expired or valid) along with an appropriate message.
   • Logic:
     • The controller checks the referralCode and compares the expiryDate with the current date.
     • If the referral code has expired, it returns an "expired" status.
     • If valid, it returns the status as "valid."

5. GET /api/referrals/:referrerId:

   • Controller: getReferralsByReferrer
   • Description: This endpoint returns all referral records created by a specific referrerId. It lists the generated referral codes and their current status.
   • Logic:
     • The controller fetches all referrals where the referrerId matches the provided value.
     • Returns the list of referral codes along with their status and expiry dates.

6. GET /api/referrals/all:

   • Controller: getAllReferrals
   • Description: This endpoint returns a list of all referrals in the system, including details such as referral codes, referrer ID, referee ID, status, and expiry date.
   • Logic:
     • The controller fetches all referral records from the database.
     • Returns the list of all referral codes with their details.

7. POST /api/referrals/log:

   • Controller: logReferralAction
   • Description: This endpoint logs any significant actions related to referrals, such as when a referral is created, completed, or expired.
   • Logic:
     • The controller receives action data (like action type and referral code) and logs it for auditing and monitoring purposes.

8. POST /api/referrals/validate:

   • Controller: validateReferralCode
   • Description: This endpoint validates a referral code before it's used by a referee. It checks if the referral code exists and is still valid.
   • Logic:
     • The controller checks if the referral code exists and if it is still in a valid state (not expired or completed).
     • Returns a success message if the code is valid or an error if it's invalid.

Utility Functions

• generateUniqueCode: A utility function to generate a random alphanumeric referral code. This function is used in the createReferral controller to ensure that each referral code is unique and not repetitive.

Logger Integration

Each critical action, such as creating a referral, completing a referral, or checking the status, is logged with relevant data. This helps with tracking the referral process, debugging, and ensuring that referral activities are auditable. The logging includes details like the referral code, the user involved, and the action taken.

Summary of Endpoints

• POST /api/referrals: Generate a new referral code.
• GET /api/referrals/:code/status: Check the status of a referral code.
• POST /api/referrals/complete: Mark a referral as completed.
• GET /api/referrals/expired/:code: Check if a referral code has expired.
• GET /api/referrals/:referrerId: Get all referrals created by a specific referrer.
• GET /api/referrals/all: Get all referral records.
• POST /api/referrals/log: Log referral actions.
• POST /api/referrals/validate: Validate if a referral code is usable.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
agro-tech-ai	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Nov 10, 2024 3:55am

[github-actions]

Thank you for submitting your pull request! 🙌 We'll review it as soon as possible. In the meantime, please ensure that your changes align with our CONTRIBUTING.md. If there are any specific instructions or feedback regarding your PR, we'll provide them here. Thanks again for your contribution! 😊

[github-actions]

🎉 Your pull request has been successfully merged! 🎉 Thank you for your valuable contribution to our project. Your efforts are greatly appreciated. Feel free to reach out if you have any more contributions or if there's anything else we can assist you with. Keep up the fantastic work! 🚀