feat: referrals

[CodeWithShreyans]

No description provided.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	supermemory-app	593bb25	Commit Preview URL Branch Preview URL	Sep 04 2025, 11:57 PM

[CodeWithShreyans]

• feat: referrals #413 👈 (View in Graphite)
• feat: add mcp migrate route #410
• feat: openai python sdk #409
• main

---

How to use the Graphite Merge Queue

Add the label Main to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

Code Review: Referral System Implementation

Thank you for implementing the referral system! This is a solid feature addition that follows the repository's patterns well. Here's my comprehensive feedback:

✅ Strengths

Code Quality & Best Practices:

• Excellent adherence to TypeScript patterns with proper type definitions in packages/validation/api.ts
• Consistent use of existing UI components and design system (Radix UI, custom Card/Button components)
• Clean separation of concerns with dedicated hooks (useReferralTracking) and reusable components
• Good API design with proper schema validation using Zod
• Follows the repository's import alias conventions (@repo/*, @lib/*, @ui/*)

Architecture:

• Smart use of React Query for caching referral data
• Proper localStorage integration for referral code persistence
• Clean component composition in ReferralLink component

⚠️ Areas for Improvement

Potential Bugs & Issues:

1. Error Handling in useReferralTracking (packages/lib/use-referral-tracking.ts:42-48):

   • Silent error catching might hide important issues
   • Consider adding proper error reporting or user feedback

2. Race Condition Risk (packages/lib/use-referral-tracking.ts:25):

   • If user logs in quickly on multiple tabs, referral might be tracked multiple times
   • Consider adding a flag to prevent duplicate tracking

3. URL Manipulation (apps/web/app/ref/[code]/page.tsx:89):

   • Direct URL manipulation without proper validation could cause issues
   • Consider using Next.js router for URL updates

Security Concerns:

1. Input Validation (packages/ui/pages/login.tsx:55-62):

   • Redirect URL validation is basic - consider more robust URL validation
   • Referral codes should be validated for format/length to prevent injection

2. XSS Prevention:

   • Ensure referral codes are properly sanitized before storage/display
   • Consider adding rate limiting for referral tracking API calls

Performance Considerations:

1. React Query Configuration (packages/ui/components/referral-link.tsx:29-42):

   • 5-minute stale time is reasonable, but consider adding refetchOnWindowFocus: false
   • Add error retry configuration

2. localStorage Access (packages/lib/use-referral-tracking.ts:12-19):

   • Multiple localStorage reads - consider batching or caching
   • Add try-catch for localStorage access (Safari private mode issues)

🧪 Test Coverage Recommendations

Critical Test Cases Missing:

• Unit tests for useReferralTracking hook with various edge cases
• Integration tests for the referral flow end-to-end
• Error boundary tests for failed API calls
• Tests for localStorage fallbacks and URL parameter handling

Suggested Test Files:

packages/lib/__tests__/use-referral-tracking.test.ts
packages/ui/components/__tests__/referral-link.test.tsx
apps/web/app/ref/[code]/__tests__/page.test.tsx

📋 Action Items

High Priority:

• Add proper error handling and user feedback in useReferralTracking
• Implement duplicate referral tracking prevention
• Add input validation for referral codes

Medium Priority:

• Add comprehensive test coverage
• Improve error states in UI components
• Add rate limiting considerations

Low Priority:

• Consider adding analytics/metrics for referral performance
• Add loading states for better UX

🏆 Overall Assessment

This is a well-implemented feature that follows the codebase conventions effectively. The architecture is sound and the code is clean. With the suggested improvements around error handling and security validation, this will be a robust addition to the platform.

The referral system integrates nicely with the existing authentication flow and provides good user experience with proper loading states and error handling in the UI components.

[claude]

Code Review Feedback

I've reviewed this referral system implementation. Here's my comprehensive feedback:

✅ Strengths

Code Quality & Best Practices:

• Follows existing codebase conventions well (TypeScript, React Query patterns, Zod validation)
• Good separation of concerns with dedicated hook, API routes, and UI components
• Consistent file organization following the monorepo structure
• Proper use of existing UI components and design system

Architecture:

• Smart use of localStorage for referral persistence across login flow
• Clean API schema definitions with proper TypeScript types
• Good error handling patterns throughout

🔧 Issues & Improvements Needed

Critical Issues:

1. Missing Backend Implementation - The API routes are defined but backend handlers are missing:

   • @get/referral/:code
   • @get/referral/user/code
   • @post/referral/track

2. Potential Race Condition in use-referral-tracking.ts:51-52:

   // Only track referral for new users (you might want to add a check here)
   // For now, we'll attempt to track for any user that has a pending referral

   This could result in duplicate referral tracking for existing users.

Security Concerns:

3. URL Validation Missing - No validation of referral codes for XSS or injection attacks
4. Rate Limiting - No apparent rate limiting on referral tracking API calls
5. Referral Code Generation - No visible entropy/security considerations for referral code generation

Bugs & Edge Cases:

6. Error Handling - Silent failures in several places:

   • packages/lib/use-referral-tracking.ts:47 - Network errors are only logged
   • packages/ui/components/referral-link.tsx:71 - Share API failures fall back to copy without user feedback

7. Memory Leaks - useReferralTracking effect doesn't clean up properly if component unmounts during async operation

Performance:

8. Unnecessary Re-renders - useReferralTracking runs on every user change, not just auth state changes
9. Query Optimization - Referral code query has no error retry strategy, could fail permanently

🧪 Test Coverage

Missing Tests:

• No unit tests for referral tracking logic
• No integration tests for referral flow
• No tests for edge cases (invalid codes, network failures, etc.)

📋 Action Items

Must Fix Before Merge:

1. Implement backend API handlers for referral endpoints
2. Add proper user filtering to prevent duplicate referral tracking
3. Add input validation for referral codes
4. Add comprehensive error handling with user feedback

Recommended Improvements:

1. Add unit tests for the referral hook and components
2. Implement rate limiting on referral tracking
3. Add referral analytics/metrics tracking
4. Consider adding referral code expiration
5. Add proper cleanup in useEffect hooks

Minor Enhancements:

1. Add loading states to referral link sharing
2. Improve error messages for better UX
3. Add referral success confirmation to users
4. Consider adding referral rewards/benefits display

🎯 Overall Assessment

This is a solid foundation for a referral system with good architectural choices. The main blocker is the missing backend implementation. Once that's addressed along with the security and error handling improvements, this will be a great feature addition.

The code follows supermemory's conventions well and integrates nicely with the existing auth flow. Great work on the UX design and component structure!

[claude]

Code Review: Referral System Implementation

I've reviewed the referral system implementation and have the following feedback:

✅ Code Quality & Best Practices

Strengths:

• Clean component structure: Well-organized React components with proper separation of concerns
• Consistent styling: Follows the established design system with dark theme colors (#0f1419, #1a1f2a)
• Proper TypeScript usage: Good type definitions with Zod schemas for API validation
• Modern React patterns: Uses hooks, React Query, and functional components appropriately
• Error handling: Proper error boundaries and user feedback mechanisms

Areas for improvement:

• Type safety: useReferralTracking(user: any) uses any type - should use proper user type from auth system
• Magic strings: Hard-coded localStorage keys and URLs could be moved to constants

⚠️ Potential Issues

Critical Issues:

1. Race condition in referral tracking (use-referral-tracking.ts:53): The hook runs on every user change, potentially tracking the same referral multiple times if user object reference changes
2. URL mismatch: referral-link.tsx:45 uses app.supermemory.ai but other parts use supermemory.ai - this could break referral links
3. Missing validation: No server-side validation that referral codes exist before allowing tracking

Minor Issues:

1. Console logs in production (use-referral-tracking.ts:39,42): Should use proper logging service
2. No retry mechanism: Failed API calls aren't retried, which could lose referral attribution
3. Component naming inconsistency: ReferralInvitePage vs ReferralPage - should be consistent

🔒 Security Concerns

Good practices:

• Input validation with Zod schemas
• Safe URL construction with proper error handling
• localStorage cleanup after successful tracking

Recommendations:

• Add rate limiting considerations for referral tracking endpoint
• Consider adding referral code expiration
• Validate referral codes server-side before storing in localStorage

⚡ Performance Considerations

Efficient patterns:

• React Query caching with 5-minute staleTime
• Proper cleanup of URL parameters and localStorage
• Loading states and error handling

Optimization opportunities:

• Consider debouncing the useReferralTracking hook to prevent excessive API calls
• Add proper error retry logic with exponential backoff

🧪 Test Coverage

Missing test coverage:

• No unit tests for the referral components
• No integration tests for the referral flow
• No error scenario testing

Recommended tests:

// Example test cases needed:
describe('ReferralLink', () => {
  it('should copy referral link to clipboard')
  it('should handle API errors gracefully')
  it('should show loading state while fetching code')
})

describe('useReferralTracking', () => {
  it('should track referral only once per user')
  it('should clean up localStorage after successful tracking')
  it('should handle network failures gracefully')
})

🚀 Recommendations

High Priority:

1. Fix race condition: Add a check to prevent duplicate referral tracking
2. Unify URLs: Standardize on either app.supermemory.ai or supermemory.ai
3. Add proper typing: Replace any with proper user type
4. Server-side validation: Validate referral codes exist before allowing tracking

Medium Priority:

1. Add tests: Implement unit and integration tests for the referral system
2. Improve error handling: Add retry logic and better error states
3. Add logging: Replace console.log with proper logging service integration
4. Consider analytics: Track referral conversion rates and usage

Low Priority:

1. Extract constants: Move hard-coded strings to configuration
2. Add JSDoc: Document complex functions and hooks
3. Consider PWA: Add referral sharing to native share menu

📊 Overall Assessment

This is a solid implementation of a referral system that follows modern React best practices. The code is generally well-structured and handles the core referral flow effectively. The main concerns are around race conditions and URL consistency, which should be addressed before merging.

Approval Status: ✅ Approve with minor changes requested

The implementation provides good user experience with proper loading states, error handling, and a clean UI that matches the application's design system.

[claude]

Code Review: Referral System Implementation

Thanks for implementing the referral system! I've reviewed the changes and here's my feedback:

✅ Strengths

1. Clean Architecture: The code follows a good separation of concerns with dedicated hooks, components, and API schemas
2. Type Safety: Proper TypeScript types and Zod validation schemas are implemented
3. User Experience: Good UX with loading states, error handling, and progressive enhancement
4. Code Style: Follows the existing codebase conventions and uses Biome formatting

🐛 Potential Issues & Bugs

1. Type Safety Issue (packages/lib/use-referral-tracking.ts:4)

   • user: any should be properly typed. Consider using the actual user type from your auth system

2. Missing Error Boundaries (apps/web/app/ref/[code]/page.tsx:27-50)

   • The referral invite page could benefit from better error boundary handling for network failures

3. Hardcoded URL (packages/ui/components/referral-link.tsx:45)

   • URL is hardcoded to app.supermemory.ai - should use environment variable or config

4. Race Condition Risk (packages/lib/use-referral-tracking.ts:53)

   • Multiple rapid user changes could trigger concurrent referral tracking requests

🔒 Security Concerns

1. Input Validation: Referral codes should be validated on both client and server side for format/length
2. Rate Limiting: Consider implementing rate limiting for referral tracking to prevent abuse
3. XSS Prevention: While using React helps, ensure referral codes are properly sanitized

🚀 Performance Considerations

1. Caching Strategy (packages/ui/components/referral-link.tsx:41)

   • Good use of React Query with 5-minute staleTime
   • Consider adding retry logic for failed requests

2. Bundle Size: New components add minimal bundle size impact

3. Memory Leaks: The 2-second timeout in clipboard copy could cause memory leaks if component unmounts

🧪 Test Coverage

• Missing Tests: No test files found for the new referral functionality
• Recommendation: Add unit tests for:
  • useReferralTracking hook behavior
  • ReferralLink component interactions
  • API schema validation
  • Error scenarios

📝 Code Quality Suggestions

1. Improve Error Messages: Make error messages more user-friendly
2. Loading States: Consider skeleton loading for better perceived performance
3. Accessibility: Add proper ARIA labels for screen readers
4. Documentation: Add JSDoc comments for the public API functions

🔧 Recommended Fixes

// Fix type safety
export function useReferralTracking(user: User | null) {
  // ... existing code
}

// Add environment config
const REFERRAL_BASE_URL = process.env.NEXT_PUBLIC_APP_URL || 'https://app.supermemory.ai';

🎯 Overall Assessment

This is a solid implementation that follows good practices. The main areas for improvement are:

• Adding proper TypeScript types
• Implementing comprehensive tests
• Enhancing error handling
• Adding security validations

The code is production-ready with these minor improvements. Great work on the clean component structure and user experience! 🚀

[claude]

Code Review - Referral System Implementation

I've reviewed the referral system implementation and overall it's well-structured with good separation of concerns. Here's my detailed feedback:

🟢 Strengths

Code Organization & Architecture:

• Clean separation between UI components, API logic, and validation schemas
• Proper use of monorepo structure with shared packages
• Good TypeScript usage with proper Zod validation schemas

User Experience:

• Smooth referral tracking flow with localStorage fallback
• Automatic URL cleanup after referral tracking
• Good error handling and loading states in UI components
• Proper share API integration with clipboard fallback

🟡 Areas for Improvement

Security & Validation:

• Critical: No referral code validation format in packages/validation/api.ts:1404 - consider adding pattern validation (e.g., alphanumeric, length limits)
• Medium: The hardcoded domain https://app.supermemory.ai in packages/ui/components/referral-link.tsx:45 should use environment variables
• Low: Type safety could be improved - user: any in packages/lib/use-referral-tracking.ts:4 should have proper typing

Error Handling & Performance:

• Medium: The tracking hook in packages/lib/use-referral-tracking.ts:53 attempts to track for any user with pending referral - consider adding duplicate tracking prevention
• Low: Consider adding rate limiting or debouncing for referral tracking requests
• Low: Missing error boundaries around referral components

Code Quality:

• Low: Console.log statements should be removed or replaced with proper logging in production (packages/lib/use-referral-tracking.ts:39,41,47)
• Low: Consider using React Query's error retry configuration for network failures

🔍 Potential Issues

Referral Page Migration:
The apps/web/app/ref/[code]/page.tsx file was significantly refactored:

• ✅ Good: Simplified UI and better error handling
• ⚠️ Check: Ensure the API endpoint @get/referral/:code is implemented on the backend
• ⚠️ Verify: The removed sharing functionality might be missed by users

Import Changes:

• ✅ Consistent use of @repo/lib/api imports
• ✅ Proper React Query integration

📋 Testing Recommendations

The following should be tested:

1. Unit Tests: Referral code validation, localStorage handling, URL parameter parsing
2. Integration Tests: End-to-end referral flow from invite to signup
3. Edge Cases: Invalid codes, network failures, concurrent tracking attempts
4. Cross-browser: Clipboard API and Web Share API compatibility

🚀 Performance Considerations

• React Query caching is well implemented (5-minute stale time)
• Consider preloading referral data on profile page mount
• The referral tracking effect runs on every user change - ensure this doesn't cause unnecessary API calls

📝 Minor Suggestions

1. Add JSDoc comments for the public API functions
2. Consider extracting the referral link generation logic to a utility function
3. Add loading states for the share/copy actions
4. Consider adding analytics tracking for referral interactions

✅ Overall Assessment

This is a solid implementation that follows the codebase conventions well. The main concerns are around security validation and ensuring the backend APIs are properly implemented. The UX flow is intuitive and the code is maintainable.

Recommendation: Approve after addressing the referral code validation and environment variable issues.