This page documents all TypeScript interfaces and data models used throughout the GitHub Wrapped API.
All interfaces are defined in types/index.ts.
Repository Models
RepositoryInfo
Basic repository metadata.
Repository owner username or organization name
Full repository name in owner/repo format
Repository description (null if not set)
Primary programming language (null if not detected)
export interface RepositoryInfo {
owner: string;
repo: string;
name: string;
description: string | null;
stars: number;
forks: number;
language: string | null;
}
User Models
UserProfile
GitHub user profile information.
URL to user’s avatar image
User’s display name (null if not set)
User’s bio (null if not set)
Number of public repositories
Total stars across all repositories owned by the user
export interface UserProfile {
username: string;
avatar_url: string;
name: string | null;
bio: string | null;
public_repos: number;
followers: number;
total_stars: number;
}
Contributor Models
Contributor
Contributor statistics for a repository.
URL to contributor’s avatar image
Number of contributions (commits)
Total lines of code added
Total lines of code removed
export interface Contributor {
login: string;
avatar_url: string;
contributions: number;
linesAdded?: number;
linesRemoved?: number;
}
Activity Models
CommitStats
Commit activity statistics and patterns.
Commits grouped by month nameExample: { "Jan": 45, "Feb": 67, "Mar": 89 }
Commits grouped by day of weekExample: { "Sunday": 12, "Monday": 45, "Tuesday": 67 }
Commits grouped by hour of day (0-23)Example: { "0": 5, "9": 45, "14": 67, "23": 12 }
Month with highest activity
Week with highest activity
ISO week format (e.g., “2024-W12”)
export interface CommitStats {
total: number;
byMonth: Record<string, number>;
byDayOfWeek: Record<string, number>;
byHour: Record<string, number>;
busiestMonth: { month: string; count: number };
busiestWeek: { week: string; count: number };
averagePerDay: number;
}
LanguageStats
Programming language usage statistics.
Programming language name (e.g., “TypeScript”, “JavaScript”)
Total bytes of code in this language
Percentage of total codebase (0-100)
export interface LanguageStats {
language: string;
bytes: number;
percentage: number;
}
Release Models
ReleaseInfo
GitHub release information.
Git tag name (e.g., “v1.0.0”)
ISO timestamp when the release was published
Release name (null if not set)
Whether this is a major version release (e.g., v2.0.0 vs v1.2.3)
export interface ReleaseInfo {
tag_name: string;
published_at: string;
name: string | null;
isMajor: boolean;
}
Snapshot Models
MonthlySnapshot
Month-by-month activity breakdown.
Month name (e.g., “Jan”, “Feb”)
Pull requests merged in this month
Issues opened in this month
Issues closed in this month
PR reviews performed in this month
Stars gained in this month (repository wrapped only)
Forks gained in this month (repository wrapped only)
Repository views in this month
Repository clones in this month
Unique contributors in this month
Top repositories for this month (user wrapped only)
Issues opened in this repo
Top languages used in this month
export interface MonthlySnapshot {
month: string; // e.g., "Jan"
commits: number;
prsMerged: number;
issuesOpened: number;
issuesClosed: number;
reviews: number;
stars: number;
forks: number;
trafficViews?: number;
trafficClones?: number;
contributors: number;
topRepos?: Array<{
name: string;
commits: number;
prsMerged: number;
issuesOpened: number;
}>;
topLanguages?: LanguageStats[];
}
Wrapped Data Models
WrappedData
Complete repository year-in-review data returned by /api/wrapped.
The year this wrapped data covers
Contributor statistics
Top contributors sorted by commit count
Top contributors sorted by lines changed
Number of first-time contributors this year
Contributor who performed the most PR reviews
Total number of contributors
Programming language breakdown
Releases published this year
Files with the most changes
ISO timestamp when data was generated
export interface WrappedData {
repository: RepositoryInfo;
year: number;
contributors: {
topByCommits: Contributor[];
topByLines: Contributor[];
newContributors: number;
mostActiveReviewer?: Contributor;
total: number;
};
activity: CommitStats;
community: {
starsGained: number;
forksGained: number;
issuesOpened: number;
issuesClosed: number;
prsMerged: number;
watchersGained: number;
};
languages: LanguageStats[];
releases: ReleaseInfo[];
mostEditedFiles: Array<{ path: string; changes: number }>;
monthly?: MonthlySnapshot[];
generatedAt: string;
}
UserWrappedData
Complete user year-in-review data returned by /api/wrapped/user, /api/performance, and /api/summary.
The year this wrapped data covers
High-level activity summary
Commits by hour of day (keys: “0” to “23”)
Commits by day of week (keys: “Sunday” to “Saturday”)
Contribution streak statistics
Longest consecutive days with contributions
Total days with at least one contribution
Single day with most contributions
ISO date (e.g., “2024-03-15”)
Month-by-month activity breakdown
Most contributed repositories
Repository owner username
ISO timestamp when data was generated
export interface UserWrappedData {
user: UserProfile;
year: number;
overview: {
totalCommits: number;
totalPRs: number;
totalIssues: number;
topLanguages: LanguageStats[];
busiestMonth: { month: string; count: number };
};
hourlyActivity: Record<string, number>; // "0" to "23"
dailyActivity: Record<string, number>; // "Sunday" to "Saturday"
streak: {
longest: number;
totalActiveDays: number;
mostActiveDay: { date: string; count: number };
};
monthly?: MonthlySnapshot[];
topRepos: {
name: string;
owner: { login: string };
description: string | null;
stars: number;
language: string | null;
}[];
generatedAt: string;
}
Cache Models
CacheEntry
Internal cache structure (not exposed in API responses).
data
WrappedData | UserWrappedData
Cached wrapped data
Unix timestamp when cache entry expires
export interface CacheEntry {
data: WrappedData | UserWrappedData;
expiresAt: number;
}
Type Usage Examples
TypeScript Client
import type { WrappedData, UserWrappedData, RepositoryInfo } from '@/types';
async function fetchRepositoryWrapped(
owner: string,
repo: string,
year: number
): Promise<WrappedData> {
const response = await fetch(
`/api/wrapped?owner=${owner}&repo=${repo}&year=${year}`
);
const { data } = await response.json();
return data as WrappedData;
}
async function fetchUserWrapped(
username: string,
year: number
): Promise<UserWrappedData> {
const response = await fetch(
`/api/wrapped/user?username=${username}&year=${year}`
);
const { data } = await response.json();
return data as UserWrappedData;
}
React Component with Types
import type { UserWrappedData } from '@/types';
import { useState, useEffect } from 'react';
function UserDashboard({ username }: { username: string }) {
const [data, setData] = useState<UserWrappedData | null>(null);
useEffect(() => {
fetch(`/api/wrapped/user?username=${username}&year=2024`)
.then(r => r.json())
.then(result => setData(result.data));
}, [username]);
if (!data) return <div>Loading...</div>;
return (
<div>
<h1>{data.user.name || data.user.username}</h1>
<p>Commits: {data.overview.totalCommits}</p>
<p>Longest streak: {data.streak.longest} days</p>
</div>
);
}
Source Code
All interfaces: types/index.ts
Related Pages
Repository Wrapped
See WrappedData in action
User Wrapped
See UserWrappedData in action
API Overview
General API documentation