Implement Reputation Data Types, API Layer, and React Query Hooks #64
Description
Build the foundational infrastructure for the contributor reputation system including TypeScript types, database schema considerations, API service layer, React Query hooks, and backend API endpoints. This establishes the data contracts and fetching mechanisms that UI components will consume.
Problem Statement
Currently, there's no way to track or assess a contributor's history, reliability, or expertise. Project maintainers cannot make informed decisions when assigning bounties, and contributors have no way to build a verifiable track record.
Acceptance Criteria
TypeScript Types
-[ ] Create ReputationTier enum (NEWCOMER, CONTRIBUTOR, ESTABLISHED, EXPERT, LEGEND)
-[ ] Create ContributorReputation type with full profile data
-[ ] Create ReputationBreakdown type for category-wise scores
-[ ] Create BountyStats type for activity metrics
-[ ] Create BountyCompletionRecord type for history entries
-[ ] Create API request/response types
API Service Layer
-[ ] Implement fetchContributorReputation() by user ID
-[ ] Implement fetchContributorByWallet() by wallet address
-[ ] Implement fetchMyReputation() for current user
-[ ] Implement rateContributor() mutation for maintainers
-[ ] Implement linkWalletToReputation() mutation
-[ ] Add proper error handling and response typing
React Query Hooks
-[ ] Create useContributorReputation() hook with caching
-[ ] Create useMyReputation() hook for current user
-[ ] Create useRateContributor() mutation hook
-[ ] Create useLinkWallet() mutation hook
-[ ] Create usePrefetchReputation() for hover previews
-[ ] Configure appropriate stale times and cache invalidation
Backend API Endpoints
-[ ] Create GET /api/reputation/[userId] endpoint
-[ ] Create GET /api/reputation/wallet/[address] endpoint
-[ ] Create GET /api/reputation/me endpoint (authenticated)
-[ ] Create POST /api/reputation/rate endpoint (maintainers only)
-[ ] Create POST /api/reputation/link-wallet endpoint
-[ ] Add input validation and authorization checks
Reputation Calculation Service
- Create score calculation logic based on difficulty
- Implement tier threshold determination
- Add completion rate multipliers
- Add speed bonus calculations
- Add quality rating multipliers
- Implement streak bonus logic
TypeScript Types
export type ReputationTier =
| 'NEWCOMER'
| 'CONTRIBUTOR'
| 'ESTABLISHED'
| 'EXPERT'
| 'LEGEND';
export interface ReputationBreakdown {
features: number;
bugs: number;
documentation: number;
refactoring: number;
other: number;
}
export interface BountyStats {
totalClaimed: number;
totalCompleted: number;
totalEarnings: number;
earningsCurrency: string;
averageCompletionTime: number; // hours
completionRate: number; // percentage 0-100
currentStreak: number;
longestStreak: number;
}
export interface BountyCompletionRecord {
id: string;
bountyId: string;
bountyTitle: string;
projectName: string;
projectLogoUrl: string | null;
difficulty: 'BEGINNER' | 'INTERMEDIATE' | 'ADVANCED';
rewardAmount: number;
rewardCurrency: string;
claimedAt: string;
completedAt: string;
completionTimeHours: number;
maintainerRating: number | null; // 1-5 or null
maintainerFeedback: string | null;
pointsEarned: number;
}
export interface ContributorReputation {
id: string;
userId: string;
walletAddress: string | null;
displayName: string;
avatarUrl: string | null;
// Reputation Metrics
totalScore: number;
tier: ReputationTier;
tierProgress: number; // 0-100 progress to next tier
breakdown: ReputationBreakdown;
// Activity Stats
stats: BountyStats;
// Expertise
topTags: string[];
specializations: string[];
// Timestamps
firstBountyAt: string | null;
lastActiveAt: string | null;
createdAt: string;
updatedAt: string;
}
export interface RateContributorInput {
bountyId: string;
contributorId: string;
rating: number; // 1-5
feedback?: string;
}
export interface ReputationHistoryParams {
userId: string;
limit?: number;
offset?: number;
}
export interface ReputationHistoryResponse {
records: BountyCompletionRecord[];
totalCount: number;
hasMore: boolean;
}