feat: add match game detail analytics

This commit is contained in:
dahyeon committed 2026-06-20 07:26:20 +09:00
1 parent c6da2013bd
commit 7b5604873e
18 files changed
+3452 -46

No files matched your search

@@ -106,4 +106,112 @@ describe('RiotMatchService', () => {
expect(match.info.participants[0].teamPosition).toBe('');
expect(match.info.participants[0].individualPosition).toBe('');
});
it('fetches and parses match timeline frames', async () => {
const payload = {
metadata: {
dataVersion: '2',
matchId: 'KR_8188913502',
participants: ['puuid-1'],
},
info: {
frameInterval: 60_000,
gameId: 8188913502,
participants: [{ participantId: 1, puuid: 'puuid-1' }],
frames: [
{
timestamp: 60_000,
events: [
{
type: 'ELITE_MONSTER_KILL',
timestamp: 30_000,
killerTeamId: 100,
monsterType: 'DRAGON',
monsterSubType: 'ELDER_DRAGON',
},
{
type: 'ITEM_PURCHASED',
timestamp: 40_000,
participantId: 1,
itemId: 1054,
},
{
type: 'ITEM_UNDO',
timestamp: 45_000,
participantId: 1,
beforeId: 1054,
afterId: 3071,
},
{
type: 'SKILL_LEVEL_UP',
timestamp: 50_000,
participantId: 1,
skillSlot: 3,
levelUpType: 'NORMAL',
},
],
participantFrames: {
'1': {
currentGold: 650,
jungleMinionsKilled: 0,
level: 2,
minionsKilled: 6,
participantId: 1,
totalGold: 1_150,
xp: 550,
},
},
},
],
},
};
const riotClientService = {
get: jest.fn(
async <T>(
_path: string,
_options: unknown,
parser?: RiotResponseParser<T>,
) => (parser ? parser(payload) : (payload as T)),
),
} as unknown as RiotClientService;
const service = new RiotMatchService(riotClientService);
const timeline = await service.getMatchTimeline('KR_8188913502', {
region: 'asia',
});
expect(riotClientService.get).toHaveBeenCalledWith(
'/lol/match/v5/matches/KR_8188913502/timeline',
expect.objectContaining({ region: 'asia' }),
expect.any(Function),
);
expect(timeline.info.frames[0].participantFrames['1']).toMatchObject({
participantId: 1,
totalGold: 1_150,
xp: 550,
});
expect(timeline.info.frames[0].events[0]).toMatchObject({
type: 'ELITE_MONSTER_KILL',
killerTeamId: 100,
monsterType: 'DRAGON',
monsterSubType: 'ELDER_DRAGON',
});
expect(timeline.info.frames[0].events[1]).toMatchObject({
type: 'ITEM_PURCHASED',
participantId: 1,
itemId: 1054,
});
expect(timeline.info.frames[0].events[2]).toMatchObject({
type: 'ITEM_UNDO',
participantId: 1,
beforeId: 1054,
afterId: 3071,
});
expect(timeline.info.frames[0].events[3]).toMatchObject({
type: 'SKILL_LEVEL_UP',
participantId: 1,
skillSlot: 3,
levelUpType: 'NORMAL',
});
});
});
@@ -15,6 +15,12 @@ import {
RiotMatchPerkStyleSelectionDto,
RiotMatchStatPerksDto,
RiotMatchTeamDto,
RiotMatchTimelineDto,
RiotMatchTimelineEventDto,
RiotMatchTimelineFrameDto,
RiotMatchTimelineInfoDto,
RiotMatchTimelineParticipantDto,
RiotMatchTimelineParticipantFrameDto,
RiotMatchType,
} from './riot.types';
@@ -66,6 +72,20 @@ export class RiotMatchService {
parseMatchResponse,
);
}
public async getMatchTimeline(
matchId: string,
options: RiotMatchLookupOptions = {},
): Promise<RiotMatchTimelineDto> {
return this.riotClientService.get<RiotMatchTimelineDto>(
`/lol/match/v5/matches/${encodeURIComponent(matchId)}/timeline`,
{
region: options.region,
signal: options.signal,
},
parseMatchTimelineResponse,
);
}
}
function validateMatchIdsLookupOptions(
@@ -115,6 +135,48 @@ function parseMatchResponse(value: unknown): RiotMatchDto {
};
}
function parseMatchTimelineResponse(value: unknown): RiotMatchTimelineDto {
if (!isRecord(value)) {
throw new TypeError('Riot match timeline response must be an object.');
}
return {
metadata: parseMatchMetadata(value.metadata),
info: parseMatchTimelineInfo(value.info),
};
}
function parseMatchTimelineInfo(value: unknown): RiotMatchTimelineInfoDto {
if (!isRecord(value)) {
throw new TypeError('Riot match timeline info must be an object.');
}
const frames = value.frames;
if (!Array.isArray(frames)) {
throw new TypeError('Riot match timeline info.frames must be an array.');
}
const participants = value.participants;
if (participants !== undefined && !Array.isArray(participants)) {
throw new TypeError(
'Riot match timeline info.participants must be an array when present.',
);
}
return {
...value,
frameInterval: requireNumber(
value.frameInterval,
'timeline.info.frameInterval',
),
frames: frames.map((frame, index) => parseTimelineFrame(frame, index)),
gameId: optionalNumber(value.gameId, 'timeline.info.gameId'),
participants: participants?.map((participant, index) =>
parseTimelineParticipant(participant, index),
),
};
}
function parseMatchMetadata(value: unknown): RiotMatchMetadataDto {
if (!isRecord(value)) {
throw new TypeError('Riot match metadata must be an object.');
@@ -211,6 +273,195 @@ function parseMatchInfo(value: unknown): RiotMatchInfoDto {
};
}
function parseTimelineParticipant(
value: unknown,
index: number,
): RiotMatchTimelineParticipantDto {
if (!isRecord(value)) {
throw new TypeError(`timeline.info.participants[${index}] must be an object.`);
}
return {
...value,
participantId: requireNumber(
value.participantId,
`timeline.info.participants[${index}].participantId`,
),
puuid: requireString(value.puuid, `timeline.info.participants[${index}].puuid`),
};
}
function parseTimelineFrame(
value: unknown,
index: number,
): RiotMatchTimelineFrameDto {
if (!isRecord(value)) {
throw new TypeError(`timeline.info.frames[${index}] must be an object.`);
}
const participantFrames = value.participantFrames;
if (!isRecord(participantFrames)) {
throw new TypeError(
`timeline.info.frames[${index}].participantFrames must be an object.`,
);
}
const events = value.events;
if (events !== undefined && !Array.isArray(events)) {
throw new TypeError(
`timeline.info.frames[${index}].events must be an array when present.`,
);
}
return {
...value,
events: (events ?? []).map((event, eventIndex) =>
parseTimelineEvent(event, index, eventIndex),
),
timestamp: requireNumber(
value.timestamp,
`timeline.info.frames[${index}].timestamp`,
),
participantFrames: Object.fromEntries(
Object.entries(participantFrames).map(([key, participantFrame]) => [
key,
parseTimelineParticipantFrame(participantFrame, index, key),
]),
),
};
}
function parseTimelineEvent(
value: unknown,
frameIndex: number,
eventIndex: number,
): RiotMatchTimelineEventDto {
if (!isRecord(value)) {
throw new TypeError(
`timeline.info.frames[${frameIndex}].events[${eventIndex}] must be an object.`,
);
}
const assistingParticipantIds = value.assistingParticipantIds;
if (
assistingParticipantIds !== undefined &&
(!Array.isArray(assistingParticipantIds) ||
!assistingParticipantIds.every(isFiniteNumber))
) {
throw new TypeError(
`timeline.info.frames[${frameIndex}].events[${eventIndex}].assistingParticipantIds must be an array of numbers when present.`,
);
}
return {
...value,
afterId: optionalNumber(
value.afterId,
`timeline.info.frames[${frameIndex}].events[${eventIndex}].afterId`,
),
assistingParticipantIds,
beforeId: optionalNumber(
value.beforeId,
`timeline.info.frames[${frameIndex}].events[${eventIndex}].beforeId`,
),
buildingType: optionalString(
value.buildingType,
`timeline.info.frames[${frameIndex}].events[${eventIndex}].buildingType`,
),
itemId: optionalNumber(
value.itemId,
`timeline.info.frames[${frameIndex}].events[${eventIndex}].itemId`,
),
killerId: optionalNumber(
value.killerId,
`timeline.info.frames[${frameIndex}].events[${eventIndex}].killerId`,
),
killerTeamId: optionalNumber(
value.killerTeamId,
`timeline.info.frames[${frameIndex}].events[${eventIndex}].killerTeamId`,
),
levelUpType: optionalString(
value.levelUpType,
`timeline.info.frames[${frameIndex}].events[${eventIndex}].levelUpType`,
),
monsterSubType: optionalString(
value.monsterSubType,
`timeline.info.frames[${frameIndex}].events[${eventIndex}].monsterSubType`,
),
monsterType: optionalString(
value.monsterType,
`timeline.info.frames[${frameIndex}].events[${eventIndex}].monsterType`,
),
participantId: optionalNumber(
value.participantId,
`timeline.info.frames[${frameIndex}].events[${eventIndex}].participantId`,
),
skillSlot: optionalNumber(
value.skillSlot,
`timeline.info.frames[${frameIndex}].events[${eventIndex}].skillSlot`,
),
teamId: optionalNumber(
value.teamId,
`timeline.info.frames[${frameIndex}].events[${eventIndex}].teamId`,
),
timestamp: requireNumber(
value.timestamp,
`timeline.info.frames[${frameIndex}].events[${eventIndex}].timestamp`,
),
towerType: optionalString(
value.towerType,
`timeline.info.frames[${frameIndex}].events[${eventIndex}].towerType`,
),
type: requireString(
value.type,
`timeline.info.frames[${frameIndex}].events[${eventIndex}].type`,
),
};
}
function parseTimelineParticipantFrame(
value: unknown,
frameIndex: number,
key: string,
): RiotMatchTimelineParticipantFrameDto {
if (!isRecord(value)) {
throw new TypeError(
`timeline.info.frames[${frameIndex}].participantFrames.${key} must be an object.`,
);
}
return {
...value,
currentGold: optionalNumber(
value.currentGold,
`timeline.info.frames[${frameIndex}].participantFrames.${key}.currentGold`,
),
jungleMinionsKilled: optionalNumber(
value.jungleMinionsKilled,
`timeline.info.frames[${frameIndex}].participantFrames.${key}.jungleMinionsKilled`,
),
level: optionalNumber(
value.level,
`timeline.info.frames[${frameIndex}].participantFrames.${key}.level`,
),
minionsKilled: optionalNumber(
value.minionsKilled,
`timeline.info.frames[${frameIndex}].participantFrames.${key}.minionsKilled`,
),
participantId: requireNumber(
value.participantId,
`timeline.info.frames[${frameIndex}].participantFrames.${key}.participantId`,
),
totalGold: requireNumber(
value.totalGold,
`timeline.info.frames[${frameIndex}].participantFrames.${key}.totalGold`,
),
xp: requireNumber(
value.xp,
`timeline.info.frames[${frameIndex}].participantFrames.${key}.xp`,
),
};
}
function parseParticipant(
value: unknown,
index: number,
@@ -504,12 +755,22 @@ function parseObjectives(
baron: parseObjective(value.baron, teamIndex, 'baron'),
champion: parseObjective(value.champion, teamIndex, 'champion'),
dragon: parseObjective(value.dragon, teamIndex, 'dragon'),
horde: optionalObjective(value.horde, teamIndex, 'horde'),
inhibitor: parseObjective(value.inhibitor, teamIndex, 'inhibitor'),
riftHerald: parseObjective(value.riftHerald, teamIndex, 'riftHerald'),
tower: parseObjective(value.tower, teamIndex, 'tower'),
};
}
function optionalObjective(
value: unknown,
teamIndex: number,
key: keyof RiotMatchObjectivesDto,
): RiotMatchObjectiveDto | undefined {
if (value === undefined || value === null) return undefined;
return parseObjective(value, teamIndex, key);
}
function parseObjective(
value: unknown,
teamIndex: number,
+54
View File
@@ -134,6 +134,11 @@ export interface RiotMatchDto {
info: RiotMatchInfoDto;
}
export interface RiotMatchTimelineDto {
metadata: RiotMatchMetadataDto;
info: RiotMatchTimelineInfoDto;
}
export interface RiotMatchMetadataDto {
dataVersion: string;
matchId: string;
@@ -240,6 +245,7 @@ export interface RiotMatchObjectivesDto {
baron: RiotMatchObjectiveDto;
champion: RiotMatchObjectiveDto;
dragon: RiotMatchObjectiveDto;
horde?: RiotMatchObjectiveDto;
inhibitor: RiotMatchObjectiveDto;
riftHerald: RiotMatchObjectiveDto;
tower: RiotMatchObjectiveDto;
@@ -249,3 +255,51 @@ export interface RiotMatchObjectiveDto {
first: boolean;
kills: number;
}
export interface RiotMatchTimelineInfoDto extends Record<string, unknown> {
frameInterval: number;
frames: RiotMatchTimelineFrameDto[];
gameId?: number;
participants?: RiotMatchTimelineParticipantDto[];
}
export interface RiotMatchTimelineParticipantDto extends Record<string, unknown> {
participantId: number;
puuid: string;
}
export interface RiotMatchTimelineFrameDto extends Record<string, unknown> {
timestamp: number;
events: RiotMatchTimelineEventDto[];
participantFrames: Record<string, RiotMatchTimelineParticipantFrameDto>;
}
export interface RiotMatchTimelineEventDto extends Record<string, unknown> {
type: string;
timestamp: number;
afterId?: number;
assistingParticipantIds?: number[];
beforeId?: number;
buildingType?: string;
itemId?: number;
killerId?: number;
killerTeamId?: number;
levelUpType?: string;
monsterSubType?: string;
monsterType?: string;
participantId?: number;
skillSlot?: number;
teamId?: number;
towerType?: string;
}
export interface RiotMatchTimelineParticipantFrameDto
extends Record<string, unknown> {
participantId: number;
totalGold: number;
xp: number;
currentGold?: number;
jungleMinionsKilled?: number;
level?: number;
minionsKilled?: number;
}