) {
event.preventDefault();
@@ -121,7 +148,7 @@ export default function TipForm({ recipient }: TipFormProps) {
/>
- {error ? (
+ {error && (
{
+ beforeEach(() => {
+ // Clear mock storage before each test
+ const mockReferralCodes = (global as any).mockReferralCodes || new Map();
+ mockReferralCodes.clear();
+ (global as any).mockReferralCodes = mockReferralCodes;
+ });
+
+ afterEach(() => {
+ // Clean up after each test
+ const mockReferralCodes = (global as any).mockReferralCodes;
+ if (mockReferralCodes) {
+ mockReferralCodes.clear();
+ }
+ });
+
+ describe('generateReferralCode', () => {
+ it('should generate a code of correct length', () => {
+ const code = generateReferralCode();
+ expect(code).toHaveLength(8);
+ });
+
+ it('should generate unique codes', () => {
+ const codes = new Set();
+ for (let i = 0; i < 100; i++) {
+ codes.add(generateReferralCode());
+ }
+ expect(codes.size).toBe(100);
+ });
+
+ it('should only use valid characters', () => {
+ const validChars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+ for (let i = 0; i < 50; i++) {
+ const code = generateReferralCode();
+ for (const char of code) {
+ expect(validChars).toContain(char);
+ }
+ }
+ });
+
+ it('should not include confusing characters', () => {
+ const confusingChars = ['I', 'O', '0', '1'];
+ for (let i = 0; i < 50; i++) {
+ const code = generateReferralCode();
+ for (const char of code) {
+ expect(confusingChars).not.toContain(char);
+ }
+ }
+ });
+ });
+
+ describe('isValidReferralCodeFormat', () => {
+ it('should return true for valid codes', () => {
+ expect(isValidReferralCodeFormat('ABCDEFGH')).toBe(true);
+ expect(isValidReferralCodeFormat('12345678')).toBe(true);
+ expect(isValidReferralCodeFormat('AB12CD34')).toBe(true);
+ });
+
+ it('should return false for invalid length', () => {
+ expect(isValidReferralCodeFormat('')).toBe(false);
+ expect(isValidReferralCodeFormat('ABC')).toBe(false);
+ expect(isValidReferralCodeFormat('ABCDEFGH1')).toBe(false);
+ });
+
+ it('should return false for invalid characters', () => {
+ expect(isValidReferralCodeFormat('ABCDEF0H')).toBe(false); // Contains 0
+ expect(isValidReferralCodeFormat('ABCDEFI1')).toBe(false); // Contains I
+ expect(isValidReferralCodeFormat('ABCDEFO1')).toBe(false); // Contains O
+ expect(isValidReferralCodeFormat('ABCDEF1I')).toBe(false); // Contains 1
+ });
+
+ it('should return false for lowercase letters', () => {
+ expect(isValidReferralCodeFormat('abcdefgh')).toBe(false);
+ expect(isValidReferralCodeFormat('ABCDEFGh')).toBe(false);
+ });
+ });
+
+ describe('validateReferralCode', () => {
+ it('should validate correct codes', () => {
+ const result = validateReferralCode('ABCDEFGH');
+ expect(result.isValid).toBe(true);
+ expect(result.error).toBeUndefined();
+ });
+
+ it('should return error for empty code', () => {
+ const result = validateReferralCode('');
+ expect(result.isValid).toBe(false);
+ expect(result.error).toBe('Referral code is required');
+ });
+
+ it('should return error for wrong length', () => {
+ const result = validateReferralCode('ABC');
+ expect(result.isValid).toBe(false);
+ expect(result.error).toBe('Referral code must be 8 characters');
+ });
+
+ it('should return error for invalid characters', () => {
+ const result = validateReferralCode('ABCDEF0H');
+ expect(result.isValid).toBe(false);
+ expect(result.error).toBe('Referral code contains invalid characters');
+ });
+ });
+
+ describe('canUseReferralCode', () => {
+ it('should return true for valid scenario', () => {
+ expect(canUseReferralCode('ABCDEFGH', 'user@example.com')).toBe(true);
+ });
+
+ it('should return true by default (placeholder implementation)', () => {
+ // In the mock implementation, this always returns true
+ // In production, this would check against the database
+ expect(canUseReferralCode('CODE1234', 'user@example.com')).toBe(true);
+ });
+ });
+
+ describe('storeReferralCode', () => {
+ it('should store a referral code for a user', () => {
+ storeReferralCode('user@example.com', 'ABCDEFGH');
+ expect(referralCodeExists('ABCDEFGH')).toBe(true);
+ });
+
+ it('should store the correct owner email', () => {
+ storeReferralCode('user@example.com', 'ABCDEFGH');
+ expect(getReferralCodeOwner('ABCDEFGH')).toBe('user@example.com');
+ });
+ });
+
+ describe('referralCodeExists', () => {
+ it('should return false for non-existent codes', () => {
+ expect(referralCodeExists('NONEXIST')).toBe(false);
+ });
+
+ it('should return true for stored codes', () => {
+ storeReferralCode('user@example.com', 'ABCDEFGH');
+ expect(referralCodeExists('ABCDEFGH')).toBe(true);
+ });
+ });
+
+ describe('getReferralCodeOwner', () => {
+ it('should return undefined for non-existent codes', () => {
+ expect(getReferralCodeOwner('NONEXIST')).toBeUndefined();
+ });
+
+ it('should return the owner email for stored codes', () => {
+ storeReferralCode('user@example.com', 'ABCDEFGH');
+ expect(getReferralCodeOwner('ABCDEFGH')).toBe('user@example.com');
+ });
+ });
+
+ describe('incrementReferralCount', () => {
+ it('should increment the referral count', () => {
+ storeReferralCode('user@example.com', 'ABCDEFGH');
+ expect(getReferralCount('ABCDEFGH')).toBe(0);
+
+ incrementReferralCount('ABCDEFGH');
+ expect(getReferralCount('ABCDEFGH')).toBe(1);
+
+ incrementReferralCount('ABCDEFGH');
+ expect(getReferralCount('ABCDEFGH')).toBe(2);
+ });
+
+ it('should not throw for non-existent codes', () => {
+ expect(() => incrementReferralCount('NONEXIST')).not.toThrow();
+ });
+ });
+
+ describe('getReferralCount', () => {
+ it('should return 0 for non-existent codes', () => {
+ expect(getReferralCount('NONEXIST')).toBe(0);
+ });
+
+ it('should return the correct count for stored codes', () => {
+ storeReferralCode('user@example.com', 'ABCDEFGH');
+ expect(getReferralCount('ABCDEFGH')).toBe(0);
+
+ incrementReferralCount('ABCDEFGH');
+ expect(getReferralCount('ABCDEFGH')).toBe(1);
+ });
+ });
+});
\ No newline at end of file
diff --git a/src/lib/referral.ts b/src/lib/referral.ts
new file mode 100644
index 00000000..ba15f6a9
--- /dev/null
+++ b/src/lib/referral.ts
@@ -0,0 +1,133 @@
+/**
+ * Referral Code Utilities
+ *
+ * This module provides utilities for generating and validating referral codes
+ * as part of the Authentication Flow Referral Program implementation.
+ */
+
+const REFERRAL_CODE_LENGTH = 8;
+const REFERRAL_CODE_CHARSET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'; // No I, O, 0, 1 to avoid confusion
+
+/**
+ * Generates a unique referral code
+ * @returns A unique 8-character referral code
+ */
+export function generateReferralCode(): string {
+ let code = '';
+ for (let i = 0; i < REFERRAL_CODE_LENGTH; i++) {
+ const randomIndex = Math.floor(Math.random() * REFERRAL_CODE_CHARSET.length);
+ code += REFERRAL_CODE_CHARSET[randomIndex];
+ }
+ return code;
+}
+
+/**
+ * Validates a referral code format
+ * @param code The referral code to validate
+ * @returns true if the code format is valid, false otherwise
+ */
+export function isValidReferralCodeFormat(code: string): boolean {
+ if (!code || code.length !== REFERRAL_CODE_LENGTH) {
+ return false;
+ }
+
+ // Check that all characters are valid
+ for (const char of code) {
+ if (!REFERRAL_CODE_CHARSET.includes(char)) {
+ return false;
+ }
+ }
+
+ return true;
+}
+
+/**
+ * Validates a referral code format and provides error details
+ * @param code The referral code to validate
+ * @returns An object with isValid flag and error message if invalid
+ */
+export function validateReferralCode(code: string): { isValid: boolean; error?: string } {
+ if (!code) {
+ return { isValid: false, error: 'Referral code is required' };
+ }
+
+ if (code.length !== REFERRAL_CODE_LENGTH) {
+ return { isValid: false, error: 'Referral code must be 8 characters' };
+ }
+
+ for (const char of code) {
+ if (!REFERRAL_CODE_CHARSET.includes(char)) {
+ return { isValid: false, error: 'Referral code contains invalid characters' };
+ }
+ }
+
+ return { isValid: true };
+}
+
+/**
+ * Checks if a referral code belongs to a specific user (prevents self-referral)
+ * @param referralCode The referral code to check
+ * @param userEmail The email of the user attempting to use the code
+ * @returns true if the user can use this referral code, false if it's their own
+ */
+export function canUseReferralCode(referralCode: string, userEmail: string): boolean {
+ // In a real implementation, this would check against the database
+ // For now, we'll implement a basic check that can be extended
+ // This is a placeholder - actual implementation would query the database
+ // to ensure the referral code doesn't belong to the same user
+ return true;
+}
+
+/**
+ * Mock storage for referral codes (in production, this would be a database)
+ * This is used for the mock implementation in the authentication flow
+ */
+const mockReferralCodes = new Map();
+
+/**
+ * Stores a referral code for a user (mock implementation)
+ * @param email The user's email
+ * @param referralCode The referral code
+ */
+export function storeReferralCode(email: string, referralCode: string): void {
+ mockReferralCodes.set(referralCode, { email, referralCount: 0 });
+}
+
+/**
+ * Validates if a referral code exists (mock implementation)
+ * @param referralCode The referral code to check
+ * @returns true if the referral code exists, false otherwise
+ */
+export function referralCodeExists(referralCode: string): boolean {
+ return mockReferralCodes.has(referralCode);
+}
+
+/**
+ * Gets the owner of a referral code (mock implementation)
+ * @param referralCode The referral code
+ * @returns The email of the owner, or undefined if not found
+ */
+export function getReferralCodeOwner(referralCode: string): string | undefined {
+ return mockReferralCodes.get(referralCode)?.email;
+}
+
+/**
+ * Increments the referral count for a referral code (mock implementation)
+ * @param referralCode The referral code
+ */
+export function incrementReferralCount(referralCode: string): void {
+ const data = mockReferralCodes.get(referralCode);
+ if (data) {
+ data.referralCount++;
+ mockReferralCodes.set(referralCode, data);
+ }
+}
+
+/**
+ * Gets the referral count for a referral code (mock implementation)
+ * @param referralCode The referral code
+ * @returns The number of referrals made with this code
+ */
+export function getReferralCount(referralCode: string): number {
+ return mockReferralCodes.get(referralCode)?.referralCount || 0;
+}
\ No newline at end of file
diff --git a/src/lib/settings/__tests__/integration.test.ts b/src/lib/settings/__tests__/integration.test.ts
index bd81274a..6a4086d5 100644
--- a/src/lib/settings/__tests__/integration.test.ts
+++ b/src/lib/settings/__tests__/integration.test.ts
@@ -514,5 +514,69 @@ describe('Settings System Integration', () => {
expect(validation.valid).toBe(true);
});
+
+ // ── Documentation Update Integration ───────────────────────────────────────────
+
+ describe('Documentation Update Integration', () => {
+ it('integrates documentation validation with settings workflow', () => {
+ const settings = createDefaultSettings();
+ const validation = SettingsService.validateSettings(settings);
+
+ expect(validation.valid).toBe(true);
+
+ const docValidation = SettingsService.validateDocumentationCompleteness();
+ expect(docValidation.valid).toBe(true);
+ });
+
+ it('ensures documentation metadata stays in sync with schema', () => {
+ const metadata = SettingsService.getDocumentationMetadata();
+ const settings = createDefaultSettings();
+
+ expect(metadata.schemaVersion).toBe(settings.version);
+ expect(Object.keys(metadata.fields)).toEqual(Object.keys(settings));
+ });
+
+ it('generates documentation update recommendations', () => {
+ const update = SettingsService.generateDocumentationUpdate();
+
+ expect(update).toHaveProperty('needsUpdate');
+ expect(update).toHaveProperty('summary');
+ expect(update).toHaveProperty('suggestions');
+
+ // Verify suggestions are actionable
+ if (update.needsUpdate) {
+ update.suggestions.forEach((suggestion) => {
+ expect(typeof suggestion).toBe('string');
+ expect(suggestion.length).toBeGreaterThan(0);
+ });
+ }
+ });
+
+ it('validates documentation completeness end-to-end', () => {
+ const metadata = SettingsService.getDocumentationMetadata();
+ const validation = SettingsService.validateDocumentationCompleteness();
+
+ expect(validation.valid).toBe(true);
+ expect(metadata.fields).toBeDefined();
+
+ // All schema fields should be documented
+ const defaultSettings = createDefaultSettings();
+ Object.keys(defaultSettings).forEach((field) => {
+ expect(metadata.fields[field]).toBeDefined();
+ expect(typeof metadata.fields[field]).toBe('string');
+ });
+ });
+
+ it('maintains documentation version consistency', () => {
+ const metadata = SettingsService.getDocumentationMetadata();
+
+ expect(metadata.version).toBeTruthy();
+ expect(metadata.lastUpdated).toBeTruthy();
+ expect(metadata.schemaVersion).toBe(SETTINGS_SCHEMA_VERSION);
+ });
+ });
+ });
+});
+ });
});
});
diff --git a/src/lib/settings/constants.ts b/src/lib/settings/constants.ts
index 23730c2b..95a588b8 100644
--- a/src/lib/settings/constants.ts
+++ b/src/lib/settings/constants.ts
@@ -1,5 +1,8 @@
export const SETTINGS_SCHEMA_VERSION = 3 as const;
+/** Documentation version tracking for settings features */
+export const SETTINGS_DOCUMENTATION_VERSION = '1.0.0' as const;
+
/** Zustand persist key for local persistence */
export const SETTINGS_STORAGE_KEY = 'teachlink-app-settings-v3';
diff --git a/src/lib/settings/service.ts b/src/lib/settings/service.ts
index 9fc0b32b..c3789613 100644
--- a/src/lib/settings/service.ts
+++ b/src/lib/settings/service.ts
@@ -11,7 +11,7 @@ import {
createDefaultSettings,
appSettingsSchema,
} from './types';
-import { SETTINGS_SCHEMA_VERSION } from './constants';
+import { SETTINGS_SCHEMA_VERSION, SETTINGS_DOCUMENTATION_VERSION } from './constants';
export interface SettingsValidationResult {
valid: boolean;
@@ -19,6 +19,13 @@ export interface SettingsValidationResult {
data?: AppSettings;
}
+export interface DocumentationMetadata {
+ version: string;
+ lastUpdated: string;
+ schemaVersion: number;
+ fields: Record;
+}
+
export interface SettingsSyncResult {
success: boolean;
message: string;
@@ -280,6 +287,96 @@ export class SettingsService {
return capabilities[permissionMap[key]] || false;
}
+ /**
+ * Get documentation metadata for current settings implementation
+ */
+ static getDocumentationMetadata(): DocumentationMetadata {
+ return {
+ version: SETTINGS_DOCUMENTATION_VERSION,
+ lastUpdated: '2025-05-30',
+ schemaVersion: SETTINGS_SCHEMA_VERSION,
+ fields: {
+ version: 'Schema version for settings structure',
+ theme: 'User color scheme preference',
+ language: 'Interface language (BCP-47 locale)',
+ notificationsEnabled: 'Master toggle for in-app notifications',
+ emailNotifications: 'Email notification preferences',
+ prefetchingEnabled: 'Link prefetching for performance',
+ reducedMotion: 'Reduced motion for accessibility',
+ electronicSignatureEnabled: 'Electronic signature feature toggle',
+ signatureName: 'User full name for signatures',
+ requireSignatureOnCertificates: 'Signature confirmation for certificates',
+ virtualBackgroundEnabled: 'Virtual background master toggle',
+ virtualBackgroundType: 'Type of virtual background effect',
+ virtualBackgroundImage: 'Custom background image URL',
+ virtualBackgroundBlur: 'Blur intensity (0-100)',
+ virtualBackgroundColor: 'Hex color for solid background',
+ },
+ };
+ }
+
+ /**
+ * Validate documentation completeness against current schema
+ */
+ static validateDocumentationCompleteness(): {
+ valid: boolean;
+ missingFields: string[];
+ outdatedFields: string[];
+ } {
+ const metadata = this.getDocumentationMetadata();
+ const defaultSettings = createDefaultSettings();
+ const schemaFields = Object.keys(defaultSettings);
+ const documentedFields = Object.keys(metadata.fields);
+
+ const missingFields = schemaFields.filter((field) => !documentedFields.includes(field));
+ const outdatedFields = documentedFields.filter((field) => !schemaFields.includes(field));
+
+ return {
+ valid: missingFields.length === 0 && outdatedFields.length === 0,
+ missingFields,
+ outdatedFields,
+ };
+ }
+
+ /**
+ * Generate documentation update summary
+ */
+ static generateDocumentationUpdate(): {
+ needsUpdate: boolean;
+ summary: string;
+ suggestions: string[];
+ } {
+ const validation = this.validateDocumentationCompleteness();
+ const metadata = this.getDocumentationMetadata();
+
+ if (validation.valid) {
+ return {
+ needsUpdate: false,
+ summary: 'Documentation is up-to-date with current schema',
+ suggestions: [],
+ };
+ }
+
+ const suggestions: string[] = [];
+
+ if (validation.missingFields.length > 0) {
+ suggestions.push(`Add documentation for missing fields: ${validation.missingFields.join(', ')}`);
+ }
+
+ if (validation.outdatedFields.length > 0) {
+ suggestions.push(`Remove documentation for deprecated fields: ${validation.outdatedFields.join(', ')}`);
+ }
+
+ suggestions.push(`Update documentation version to reflect changes`);
+ suggestions.push(`Update lastUpdated timestamp in constants`);
+
+ return {
+ needsUpdate: true,
+ summary: `Documentation update required. ${validation.missingFields.length} missing fields, ${validation.outdatedFields.length} outdated fields.`,
+ suggestions,
+ };
+ }
+
/**
* Apply settings migration if needed (for future version changes)
*/
diff --git a/src/lib/settings/types.ts b/src/lib/settings/types.ts
index c55d4d70..54e8771d 100644
--- a/src/lib/settings/types.ts
+++ b/src/lib/settings/types.ts
@@ -1,5 +1,5 @@
import { z } from 'zod';
-import { SETTINGS_SCHEMA_VERSION } from './constants';
+import { SETTINGS_SCHEMA_VERSION, SETTINGS_DOCUMENTATION_VERSION } from './constants';
/** User-selectable colour scheme. `'system'` follows the OS preference. */
export const themePreferenceSchema = z.enum(['light', 'dark', 'system']);
diff --git a/src/schemas/user.schema.ts b/src/schemas/user.schema.ts
index 0174f7a0..e98947cd 100644
--- a/src/schemas/user.schema.ts
+++ b/src/schemas/user.schema.ts
@@ -7,6 +7,9 @@ export const UserSchema = z.object({
name: z.string().min(2, 'Name must be at least 2 characters'),
email: z.string().email('Invalid email address'),
role: UserRoleSchema,
+ referralCode: z.string().optional(),
+ referredBy: z.string().optional(),
+ referralCount: z.number().default(0),
});
export type User = z.infer;
diff --git a/src/types/api/auth.dto.ts b/src/types/api/auth.dto.ts
index 1ea20d58..64c5c5d0 100644
--- a/src/types/api/auth.dto.ts
+++ b/src/types/api/auth.dto.ts
@@ -20,6 +20,7 @@ export const SignupRequestSchema = z
confirmPassword: z
.string({ required_error: 'Confirm password is required' })
.min(1, 'Confirm password is required'),
+ referralCode: z.string().optional(),
})
.refine((data) => data.password === data.confirmPassword, {
message: "Passwords don't match",
diff --git a/tsconfig.json b/tsconfig.json
index b8d9f0c1..cbb9e27d 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -5,6 +5,7 @@
"paths": {
"@/*": ["./src/*"]
},
+ "ignoreDeprecations": "6.0",
"plugins": [
{
"name": "next"