Task#00000 Referral Tracking implementation

src/adapters/postgres/postgres-module.ts

@@ -24,6 +24,7 @@ import { AcademicYear } from 'src/academicyears/entities/academicyears-entity';
 import { CohortAcademicYearService } from './cohortAcademicYear-adapter';
 import { AuthUtils } from '@utils/auth-util';
 import { ElasticsearchModule } from 'src/elasticsearch/elasticsearch.module';
+import { ReferralsModule } from 'src/referrals/referrals.module';
 
 @Module({
   imports: [
@@ -44,6 +45,7 @@ import { ElasticsearchModule } from 'src/elasticsearch/elasticsearch.module';
       AcademicYear,
     ]),
     ElasticsearchModule,
+    ReferralsModule,
   ],
   providers: [
     PostgresUserService,

src/adapters/postgres/user-adapter.ts

@@ -52,6 +52,8 @@
 import { UserElasticsearchService } from '../../elasticsearch/user-elasticsearch.service';
 import { IUser } from '../../elasticsearch/interfaces/user.interface';
 import { isElasticsearchEnabled } from 'src/common/utils/elasticsearch.util';
+import { ReferralsService } from 'src/referrals/referrals.service';
+import { buildReferLink } from 'src/referrals/utils/referral-slug.util';
 
 interface UpdateField {
   userId: string; // Required
@@ -96,7 +98,8 @@
     private postgresAcademicYearService: PostgresAcademicYearService,
     private readonly cohortAcademicYearService: CohortAcademicYearService,
     private readonly authUtils: AuthUtils,
-    private readonly userElasticsearchService: UserElasticsearchService
+    private readonly userElasticsearchService: UserElasticsearchService,
+    private readonly referralsService: ReferralsService
   ) {
     this.jwt_secret = this.configService.get<string>('RBAC_JWT_SECRET');
     this.jwt_password_reset_expires_In = this.configService.get<string>(
@@ -1794,7 +1797,7 @@
     }
   }
 
   async createUser(
     request: any,
     userCreateDto: UserCreateDto,
     academicYearId: string,
@@ -1991,6 +1994,21 @@
       }
       LoggerUtil.log(API_RESPONSES.USER_CREATE_SUCCESSFULLY, apiId);
 
+      // Referral attribution (first-touch provided by client; do not block registration)
+      let referLinkForElastic: string | null = null;
+      try {
+        const incomingSlug = (userCreateDto as any)?.referralSlug ?? null;
+        const attr = await this.referralsService.createUserAttribution({
+          userId: result.userId,
+          incomingSlug,
+        });
+        referLinkForElastic =
+          attr.referLink ??
+          (attr.resolvedSlug ? buildReferLink(attr.resolvedSlug) : null);
+      } catch (refError: any) {
+        LoggerUtil.error('Referral attribution failed', refError);
+      }
+
       // Add Elasticsearch sync with custom fields
       try {
         if (isElasticsearchEnabled()) {
@@ -2029,6 +2047,7 @@
               email: result.email || '',
               mobile: result.mobile ? result.mobile.toString() : '',
               mobile_country_code: result.mobile_country_code || '',
+              referLink: referLinkForElastic ?? undefined,
               gender: result.gender,
               dob:
                 result.dob instanceof Date
@@ -2039,7 +2058,7 @@
               currentCountry: result.currentCountry || '',
               status: result.status,
               customFields: elasticCustomFields,
-            },
+            } as any,
             applications: [],
             courses: [],
             createdAt: result.createdAt

src/app.module.ts

@@ -35,6 +35,7 @@ import { PaymentsModule } from './payments/payments.module';
 import { PathwaysModule } from './pathways/pathways.module';
 import { CountriesModule } from './countries/countries.module';
 import { ContentModule } from './content/content.module';
+import { ReferralsModule } from './referrals/referrals.module';
 
 /**
  * Main Application Module
@@ -93,6 +94,7 @@ import { ContentModule } from './content/content.module';
     PathwaysModule,
     CountriesModule,
     ContentModule,
+    ReferralsModule,
   ],
   controllers: [AppController, HealthController],
   providers: [

src/common/utils/api-id.config.ts

@@ -30,6 +30,15 @@ export const APIID = {
   USER_DELETE: "api.user.delete",
   USER_BULK_IMPORT: "api.user.bulkImport",
 
+  // Referral Management APIs
+  REFERRAL_CREATE: "api.referral.create",
+  REFERRAL_LIST: "api.referral.list",
+  REFERRAL_RESOLVE: "api.referral.resolve",
+  REFERRAL_UPDATE: "api.referral.update",
+  REFERRAL_IMPORT: "api.referral.import",
+  REFERRAL_BULK: "api.referral.bulk",
+  REFERRAL_REPORT: "api.referral.report",
+
   // Role Management APIs
   ROLE_GET: "api.role.get",
   ROLE_CREATE: "api.role.create",

src/common/utils/response.messages.ts

@@ -280,4 +280,13 @@ export const API_RESPONSES = {
 
   // Country Management Messages
   COUNTRY_LIST_SUCCESS: "Countries retrieved successfully",
+
+  // Referral Management Messages
+  REFERRAL_CREATED_SUCCESSFULLY: "Referral created successfully",
+  REFERRAL_LIST_SUCCESS: "Referrals retrieved successfully",
+  REFERRAL_RESOLVED_SUCCESSFULLY: "Referral resolved successfully",
+  REFERRAL_UPDATED_SUCCESSFULLY: "Referral updated successfully",
+  REFERRAL_IMPORT_SUCCESS: "Referrals imported successfully",
+  REFERRAL_BULK_SUCCESS: "Bulk referrals processed successfully",
+  REFERRAL_REPORT_SUCCESS: "Referral report retrieved successfully",
 };

src/elasticsearch/elasticsearch.service.ts

@@ -182,6 +182,7 @@ export class ElasticsearchService {
               email: source?.profile?.email || '',
               mobile: source?.profile?.mobile || '',
               mobile_country_code: source?.profile?.mobile_country_code || '',
+              ...(source?.profile?.referLink ? { referLink: source.profile.referLink } : {}),
               gender: source?.profile?.gender || '',
               dob:source?.profile?.dob || '',
               country:source?.profile?.country || '',

src/elasticsearch/interfaces/user.interface.ts

@@ -48,6 +48,7 @@ export interface IProfile {
   email: string;
   mobile: string;
   mobile_country_code: string;
+  referLink?: string;
   gender: string;
   dob: string;
   country: string;

src/elasticsearch/user-elasticsearch.service.ts

@@ -81,6 +81,7 @@
                 email: { type: 'keyword' },
                 mobile: { type: 'keyword' },
                 mobile_country_code: { type: 'keyword' },
+                referLink: { type: 'keyword' },
                 gender: { type: 'keyword' },
                 dob: { type: 'date', null_value: null },
                 country: {
@@ -379,6 +380,7 @@
       email: profile.email,
       mobile: profile.mobile,
       mobile_country_code: profile.mobile_country_code,
+      ...(profile.referLink ? { referLink: profile.referLink } : {}),
       gender: profile.gender,
       dob: profile.dob,
       country: this.normalizeCountryKeyword(profile.country),
@@ -759,7 +761,7 @@
       if (query.filters && typeof query.filters === 'object') {
         // Special handling for cohortId and cohortmemberstatus in applications
         const appFilters: any = {};
         Object.entries(query.filters).forEach(([field, value]) => {
           if (value !== undefined && value !== null && value !== '') {
             // Handle cohortId, cohortmemberstatus, and completionPercentage as nested application filters
             if (
@@ -771,6 +773,17 @@
               return;
             }
 
+            // Handle referLink filtering — match by slug or full URL
+            if (field === 'referLink') {
+              const referLinkValue = typeof value === 'string' ? value : JSON.stringify(value);
+              searchQuery.bool.filter.push({
+                wildcard: {
+                  'profile.referLink': `*${referLinkValue.toLowerCase()}*`,
+                },
+              });
+              return;
+            }
+
             // Handle auto_tags filtering
             if (field === 'auto_tags') {
               const tags = Array.isArray(value) ? value : [value];

src/forms/forms.module.ts

@@ -24,6 +24,7 @@ import { HttpModule } from '@nestjs/axios';
 import { ConfigModule } from '@nestjs/config';
 import { NotificationRequest } from 'src/common/utils/notification.axios';
 import { CohortModule } from 'src/cohort/cohort.module';
+import { ReferralsModule } from 'src/referrals/referrals.module';
 @Module({
   controllers: [FormsController, FormSubmissionController],
   imports: [
@@ -44,6 +45,7 @@ import { CohortModule } from 'src/cohort/cohort.module';
     HttpModule,
     ConfigModule,
     forwardRef(() => CohortModule),
+    ReferralsModule,
   ],
   providers: [
     FormsService,

src/forms/services/form-submission.service.ts

@@ -37,6 +37,7 @@
 import { CohortMembers } from 'src/cohortMembers/entities/cohort-member.entity';
 import { Cohort } from 'src/cohort/entities/cohort.entity';
 import { FieldValueConverter } from 'src/utils/field-value-converter';
+import { ReferralsService } from 'src/referrals/referrals.service';
 
 interface DateRange {
   start: string;
@@ -94,7 +95,8 @@
     private readonly userElasticsearchService: UserElasticsearchService,
     private readonly formsService: FormsService,
     @Inject(forwardRef(() => PostgresCohortService))
-    private readonly postgresCohortService: PostgresCohortService
+    private readonly postgresCohortService: PostgresCohortService,
+    private readonly referralsService: ReferralsService
   ) {}
 
   async create(
@@ -2140,7 +2142,7 @@
    *
    * Made public so it can be used as an upsert callback from other services (e.g., cohortMembers-adapter).
    */
   public async buildUserDocumentForElasticsearch(
     userId: string
   ): Promise<IUser | null> {
     // Fetch user profile from Users table
@@ -3158,6 +3160,8 @@
         }
       }
     }
+    const referLink = await this.referralsService.getUserReferLink(user.userId);
+
     // Build the IUser object
     return {
       userId: user.userId,
@@ -3170,6 +3174,7 @@
         email: user.email || '',
         mobile: user.mobile ? user.mobile.toString() : '',
         mobile_country_code: user.mobile_country_code || '',
+        ...(referLink ? { referLink } : {}),
         gender: user.gender,
         dob: user.dob instanceof Date ? user.dob.toISOString() : user.dob || '',
         country: user.country,

src/referrals/dto/create-referral-entity.dto.ts

@@ -0,0 +1,69 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsArray, IsEmail, IsEnum, IsOptional, IsString, MaxLength } from 'class-validator';
+import {
+  ReferralEntityStatus,
+  ReferralEntitySubType,
+  ReferralEntityType,
+} from '../referrals.types';
+
+export class CreateReferralEntityDto {
+  @ApiPropertyOptional({ description: 'Custom slug (any format accepted; will be normalized to lowercase a-z0-9_). If omitted, auto-generated.' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  slug?: string;
+
+  @ApiProperty({ description: 'First name (or full org/university name)' })
+  @IsString()
+  @MaxLength(255)
+  firstName: string;
+
+  @ApiPropertyOptional({ description: 'Last name (optional for org/university)' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  lastName?: string;
+
+  @ApiProperty({ enum: ReferralEntityType })
+  @IsEnum(ReferralEntityType)
+  type: ReferralEntityType;
+
+  @ApiProperty({ enum: ReferralEntitySubType })
+  @IsEnum(ReferralEntitySubType)
+  subType: ReferralEntitySubType;
+
+  @ApiPropertyOptional({ description: 'Region (optional)' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  region?: string;
+
+  @ApiPropertyOptional({ description: 'Linked internal entity UUID (optional)' })
+  @IsOptional()
+  @IsString()
+  linkedEntityId?: string;
+
+  @ApiPropertyOptional({ description: 'Primary contact email (optional)' })
+  @IsOptional()
+  @IsEmail()
+  @MaxLength(255)
+  contactEmail?: string;
+
+  @ApiPropertyOptional({ description: 'Additional emails (array of email strings)', type: [String] })
+  @IsOptional()
+  @IsArray()
+  @IsEmail({}, { each: true })
+  additionalEmails?: string[];
+
+  @ApiPropertyOptional({ description: 'Country (optional)' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  country?: string;
+
+  @ApiPropertyOptional({ enum: ReferralEntityStatus, default: ReferralEntityStatus.ACTIVE })
+  @IsOptional()
+  @IsEnum(ReferralEntityStatus)
+  status?: ReferralEntityStatus;
+}
+

src/referrals/dto/import-referrals.dto.ts

@@ -0,0 +1,13 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsNotEmpty, IsString } from 'class-validator';
+
+export class ImportReferralsDto {
+  @ApiProperty({
+    description:
+      'CSV content with header: firstName,lastName,type,subType,region,contactEmail,country',
+  })
+  @IsString()
+  @IsNotEmpty()
+  csv: string;
+}
+

src/referrals/dto/list-referrals.dto.ts

@@ -0,0 +1,55 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import { IsArray, IsEnum, IsNumber, IsObject, IsOptional, IsString, Min } from 'class-validator';
+import { ReferralEntitySubType, ReferralEntityType } from '../referrals.types';
+
+export class ReferralFiltersDto {
+  @ApiPropertyOptional({ enum: ReferralEntityType, description: 'Filter by referral type' })
+  @IsOptional()
+  @IsEnum(ReferralEntityType)
+  type?: ReferralEntityType;
+
+  @ApiPropertyOptional({ enum: ReferralEntitySubType, description: 'Filter by referral sub-type' })
+  @IsOptional()
+  @IsEnum(ReferralEntitySubType)
+  subType?: ReferralEntitySubType;
+
+  @ApiPropertyOptional({ type: String, description: 'Search across firstName, lastName, contactEmail, and slug' })
+  @IsOptional()
+  @IsString()
+  search?: string;
+
+  @ApiPropertyOptional({ type: [String], description: 'Filter by regions' })
+  @IsOptional()
+  @IsArray()
+  @IsString({ each: true })
+  regions?: string[];
+
+  @ApiPropertyOptional({ type: [String], description: 'Filter by countries' })
+  @IsOptional()
+  @IsArray()
+  @IsString({ each: true })
+  countries?: string[];
+}
+
+export class ListReferralsDto {
+  @ApiPropertyOptional({ description: 'Number of records to return', default: 10 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsNumber()
+  @Min(1)
+  limit?: number;
+
+  @ApiPropertyOptional({ description: 'Number of records to skip', default: 0 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsNumber()
+  @Min(0)
+  offset?: number;
+
+  @ApiPropertyOptional({ type: ReferralFiltersDto, description: 'Filters to apply' })
+  @IsOptional()
+  @IsObject()
+  @Type(() => ReferralFiltersDto)
+  filters?: ReferralFiltersDto;
+}