feat: define competition domain contracts

This commit is contained in:
dahyeon committed 2026-07-12 18:44:26 +00:00
1 parent f4ba3d524f
commit 05a83db886
13 files changed
+843

No files matched your search

+60
View File
@@ -0,0 +1,60 @@
import type { CompetitionDetailResponse } from "./competition.js";
import type { SeriesAdjudicationDecision } from "./facts.js";
import type {
CompetitionFactId,
GameSlotId,
SeriesId,
TeamId,
} from "./ids.js";
export interface SwapCompetitionSeedsRequest {
firstSeedNumber: number;
secondSeedNumber: number;
}
export interface CreateSeriesAdjudicationRequest {
decision: SeriesAdjudicationDecision;
reason: string;
}
export type SeriesReversalMode = "strict" | "cascade";
export interface SeriesReversalPreviewRequest {
mode: SeriesReversalMode;
reason: string;
}
export interface SeriesReversalImpact {
seriesIds: SeriesId[];
factIds: CompetitionFactId[];
gameSlotIds: GameSlotId[];
teamIds: TeamId[];
releasesReservedCodes: number;
voidsUsedCodes: number;
requiresStatsRebuild: boolean;
}
export interface SeriesReversalPreviewResponse {
sourceRevision: number;
impactHash: string;
impact: SeriesReversalImpact;
}
export interface ReverseSeriesResultRequest {
mode: SeriesReversalMode;
reason: string;
impactHash: string;
}
export interface CompetitionCommandResponse {
competition: CompetitionDetailResponse;
}
export interface ApiErrorResponse {
error: {
code: string;
message: string;
details?: unknown;
};
}
+165
View File
@@ -0,0 +1,165 @@
import type { CompetitionFormat } from "./format.js";
import type { CompetitionGameView, GameSlotView } from "./game.js";
import type {
CommunityId,
CompetitionId,
MatchId,
SeriesId,
TeamId,
UserId,
} from "./ids.js";
import type {
IsoDateTime,
SeriesDefinition,
SeriesProjection,
SeriesSlot,
SeriesStageType,
} from "./series.js";
export type CompetitionPhase =
| "ready"
| "running"
| "completed"
| "cancelled";
export type PlayerPosition = "TOP" | "JGL" | "MID" | "ADC" | "SUP";
export interface CompetitionTeamMemberView {
userId: UserId;
displayName: string;
gameName?: string;
tagLine?: string;
profileIconId?: number;
assignedPosition?: PlayerPosition;
cost?: number;
}
export interface CompetitionTeamView {
teamId: TeamId;
displayOrder: number;
name: string;
captainUserId?: UserId;
members: CompetitionTeamMemberView[];
}
export interface RoundRobinStandingView {
rank: number;
teamId: TeamId;
seriesPlayed: number;
seriesWins: number;
seriesLosses: number;
seriesDraws: number;
gameWins: number;
gameLosses: number;
gameDiff: number;
}
export interface CompetitionPlacementView {
rank: number;
teamId: TeamId;
}
export type CompetitionOutcome =
| {
type: "paired-series";
completedSeriesIds: SeriesId[];
drawnSeriesIds: SeriesId[];
completedAt: IsoDateTime;
}
| {
type: "round-robin";
standings: RoundRobinStandingView[];
leaderTeamIds: TeamId[];
completedAt: IsoDateTime;
}
| {
type: "double-elimination";
placements: CompetitionPlacementView[];
championTeamId: TeamId;
completedAt: IsoDateTime;
};
export interface BracketRoundView {
stage: SeriesStageType;
roundNumber?: number;
displayOrder: number;
label: string;
seriesIds: SeriesId[];
}
export interface SeriesConnectorView {
from: {
seriesId: SeriesId;
select: "winner" | "loser" | "slot-a" | "slot-b";
};
to: {
seriesId: SeriesId;
slot: SeriesSlot;
};
}
interface CompetitionProjectionBase {
sourceRevision: number;
projectorVersion: number;
phase: CompetitionPhase;
series: SeriesProjection[];
games: CompetitionGameView[];
gameSlots: GameSlotView[];
rounds: BracketRoundView[];
connectors: SeriesConnectorView[];
}
export interface PairedSeriesCompetitionProjection
extends CompetitionProjectionBase {
formatType: "paired-series";
standings?: never;
placements?: never;
outcome?: Extract<CompetitionOutcome, { type: "paired-series" }>;
}
export interface RoundRobinCompetitionProjection
extends CompetitionProjectionBase {
formatType: "round-robin";
standings: RoundRobinStandingView[];
placements?: never;
outcome?: Extract<CompetitionOutcome, { type: "round-robin" }>;
}
export interface DoubleEliminationCompetitionProjection
extends CompetitionProjectionBase {
formatType: "double-elimination";
standings?: never;
placements: CompetitionPlacementView[];
outcome?: Extract<CompetitionOutcome, { type: "double-elimination" }>;
}
export type CompetitionProjection =
| PairedSeriesCompetitionProjection
| RoundRobinCompetitionProjection
| DoubleEliminationCompetitionProjection;
export interface CompetitionDefinitionView {
id: CompetitionId;
matchId: MatchId;
communityId: CommunityId;
schemaVersion: number;
revision: number;
phase: CompetitionPhase;
teams: CompetitionTeamView[];
format: CompetitionFormat;
seriesGraph: SeriesDefinition[];
}
export interface CompetitionDetailResponse {
id: CompetitionId;
matchId: MatchId;
communityId: CommunityId;
schemaVersion: number;
revision: number;
phase: CompetitionPhase;
teams: CompetitionTeamView[];
format: CompetitionFormat;
projection: CompetitionProjection;
createdAt: IsoDateTime;
updatedAt: IsoDateTime;
}
+85
View File
@@ -0,0 +1,85 @@
import type {
CommandId,
CompetitionFactId,
CompetitionId,
GameId,
GameSlotId,
RiotMatchId,
SeriesId,
TeamId,
UserId,
} from "./ids.js";
import type { IsoDateTime } from "./series.js";
export type CompetitionFactActor =
| { type: "system" }
| { type: "user"; userId: UserId }
| { type: "migration"; migrationRunId: string };
interface CompetitionFactViewBase {
id: CompetitionFactId;
competitionId: CompetitionId;
revision: number;
ordinalWithinRevision: number;
commandId: CommandId;
schemaVersion: number;
actor: CompetitionFactActor;
occurredAt: IsoDateTime;
recordedAt: IsoDateTime;
causationId?: string;
}
export interface GameAcceptedFactView extends CompetitionFactViewBase {
type: "game-accepted";
gameId: GameId;
seriesId: SeriesId;
gameSlotId: GameSlotId;
ordinal: number;
evidence:
| { type: "riot"; riotMatchId: RiotMatchId; payloadHash: string }
| { type: "legacy"; legacyReference: string };
mapping: {
mappingVersion: number;
confidence: number;
blueTeamId: TeamId;
redTeamId: TeamId;
winnerTeamId: TeamId;
};
}
export interface GameVoidedFactView extends CompetitionFactViewBase {
type: "game-voided";
gameAcceptedFactId: CompetitionFactId;
reason: string;
}
export type SeriesAdjudicationDecision =
| { type: "walkover"; winnerTeamId: TeamId }
| { type: "forfeit"; winnerTeamId: TeamId }
| { type: "administrative"; winnerTeamId: TeamId }
| { type: "administrative-draw" };
export interface SeriesAdjudicatedFactView extends CompetitionFactViewBase {
type: "series-adjudicated";
seriesId: SeriesId;
decision: SeriesAdjudicationDecision;
reason: string;
}
export interface AdjudicationReversedFactView extends CompetitionFactViewBase {
type: "adjudication-reversed";
adjudicationFactId: CompetitionFactId;
reason: string;
}
export type CompetitionFactView =
| GameAcceptedFactView
| GameVoidedFactView
| SeriesAdjudicatedFactView
| AdjudicationReversedFactView;
export interface CompetitionFactsResponse {
facts: CompetitionFactView[];
nextCursor: string | null;
}
+56
View File
@@ -0,0 +1,56 @@
import type { TeamId } from "./ids.js";
import type {
FirstToSeriesRule,
FixedGamesSeriesRule,
} from "./series.js";
export type CompetitionFormatType =
| "paired-series"
| "round-robin"
| "double-elimination";
export interface PairedSeriesCompetitionFormat {
type: "paired-series";
rule: FixedGamesSeriesRule;
}
export type RoundRobinTieBreaker =
| "series-wins"
| "game-diff"
| "head-to-head";
export interface RoundRobinCompetitionFormat {
type: "round-robin";
rule: FixedGamesSeriesRule;
maxRounds?: number;
tieBreakers: [
"series-wins",
"game-diff",
"head-to-head",
];
}
export interface DoubleEliminationSeriesRules {
upper: FirstToSeriesRule;
lower: FirstToSeriesRule;
grandFinal: FirstToSeriesRule;
resetFinal: FirstToSeriesRule;
}
export interface DoubleEliminationCompetitionFormat {
type: "double-elimination";
teamCount: 4 | 8;
resetFinalEnabled: boolean;
rules: DoubleEliminationSeriesRules;
}
export type CompetitionFormat =
| PairedSeriesCompetitionFormat
| RoundRobinCompetitionFormat
| DoubleEliminationCompetitionFormat;
export interface CompetitionSeedView {
seedNumber: number;
teamId: TeamId;
}
+80
View File
@@ -0,0 +1,80 @@
import type {
GameId,
GameSlotId,
RiotMatchId,
SeriesId,
TeamId,
UserId,
} from "./ids.js";
import type { IsoDateTime, SeriesSlot } from "./series.js";
export type TeamSide = "blue" | "red";
export type GameEvidenceView =
| {
type: "riot";
riotMatchId: RiotMatchId;
}
| {
type: "legacy";
legacyReference: string;
};
export interface GameParticipantView {
userId: UserId | null;
teamId: TeamId;
side: TeamSide;
summonerName: string;
tagLine: string;
championId: number;
kills: number;
deaths: number;
assists: number;
}
export interface GameTeamView {
teamId: TeamId;
side: TeamSide;
}
export interface CompetitionGameView {
id: GameId;
seriesId: SeriesId;
gameSlotId: GameSlotId;
ordinal: number;
displayNumber: number;
evidence: GameEvidenceView;
teams: {
blue: GameTeamView & { side: "blue" };
red: GameTeamView & { side: "red" };
};
winnerTeamId: TeamId;
startedAt: IsoDateTime;
durationSeconds: number;
participants: GameParticipantView[];
}
export type GameSlotStatus =
| "inactive"
| "waiting"
| "ready"
| "reserved"
| "used"
| "completed"
| "voided";
export interface GameSlotEntryView {
slot: SeriesSlot;
teamId: TeamId | null;
}
export interface GameSlotView {
id: GameSlotId;
seriesId: SeriesId;
ordinal: number;
displayNumber: number;
status: GameSlotStatus;
entries: [GameSlotEntryView, GameSlotEntryView];
gameId?: GameId;
}
+22
View File
@@ -0,0 +1,22 @@
declare const contractIdBrand: unique symbol;
export type BrandedId<Name extends string> = string & {
readonly [contractIdBrand]: Name;
};
export type CommunityId = BrandedId<"CommunityId">;
export type MatchId = BrandedId<"MatchId">;
export type CompetitionId = BrandedId<"CompetitionId">;
export type TeamId = BrandedId<"TeamId">;
export type UserId = BrandedId<"UserId">;
export type SeriesId = BrandedId<"SeriesId">;
export type GameSlotId = BrandedId<"GameSlotId">;
export type GameId = BrandedId<"GameId">;
export type CompetitionFactId = BrandedId<"CompetitionFactId">;
export type TournamentCodeId = BrandedId<"TournamentCodeId">;
export type TournamentCodeAssignmentId =
BrandedId<"TournamentCodeAssignmentId">;
export type RiotMatchId = BrandedId<"RiotMatchId">;
export type CommandId = BrandedId<"CommandId">;
export type UserPuuid = BrandedId<"UserPuuid">;
+8
View File
@@ -0,0 +1,8 @@
export type * from "./commands.js";
export type * from "./competition.js";
export type * from "./facts.js";
export type * from "./ids.js";
export type * from "./match.js";
export type * from "./format.js";
export type * from "./game.js";
export type * from "./series.js";
+95
View File
@@ -0,0 +1,95 @@
import type { CompetitionDetailResponse, CompetitionPhase } from "./competition.js";
import type { CompetitionFormatType } from "./format.js";
import type {
CommunityId,
CompetitionId,
GameSlotId,
MatchId,
SeriesId,
TeamId,
UserId,
} from "./ids.js";
import type { IsoDateTime, SeriesProjection } from "./series.js";
export type MatchLifecycleStatus =
| "recruiting"
| "team-building"
| "ready"
| "running"
| "completed"
| "cancelled";
export interface MatchCompetitionSummaryView {
id: CompetitionId;
phase: CompetitionPhase;
formatType: CompetitionFormatType;
}
export interface MatchSummaryResponse {
id: MatchId;
communityId: CommunityId;
shortCode?: string;
title: string;
description: string;
scheduledAt: IsoDateTime;
status: MatchLifecycleStatus;
maxParticipants: number;
participantCount: number;
joined: boolean;
competition?: MatchCompetitionSummaryView;
createdAt: IsoDateTime;
updatedAt: IsoDateTime;
}
export interface MatchParticipantView {
userId: UserId;
displayName: string;
gameName?: string;
tagLine?: string;
profileIconId?: number;
joinedAt: IsoDateTime;
excluded: boolean;
}
export interface MatchScheduleItemView {
time: string;
label: string;
}
export interface MatchDetailResponse
extends Omit<MatchSummaryResponse, "competition"> {
mapId: number;
hostUserId?: UserId;
participants: MatchParticipantView[];
prizes: string[];
notices: string[];
schedule: MatchScheduleItemView[];
competition?: CompetitionDetailResponse;
}
export interface TeamTournamentCodeView {
gameSlotId: GameSlotId;
seriesId: SeriesId;
ordinal: number;
displayNumber: number;
state: "pending" | "reserved" | "used";
code: string | null;
expiresAt: IsoDateTime | null;
}
export interface TeamCompetitionViewResponse {
competitionId: CompetitionId;
revision: number;
phase: CompetitionPhase;
teamId: TeamId;
activeSeries: SeriesProjection[];
tournamentCodes: TeamTournamentCodeView[];
}
export interface MatchListResponse {
matches: MatchSummaryResponse[];
page: number;
pageSize: number;
totalItems: number;
totalPages: number;
}
+183
View File
@@ -0,0 +1,183 @@
import type {
CompetitionFactId,
GameId,
GameSlotId,
SeriesId,
TeamId,
} from "./ids.js";
export type IsoDateTime = string;
export type SeriesSlot = "A" | "B";
export type SeriesStageType =
| "pair"
| "round-robin"
| "upper"
| "lower"
| "grand-final"
| "reset-final";
export interface FirstToSeriesRule {
type: "first-to";
winsRequired: number;
maxGames: number;
}
export interface FixedGamesSeriesRule {
type: "fixed-games";
gameCount: number;
drawPolicy: "allow" | "tiebreak-required";
}
export type SeriesRule = FirstToSeriesRule | FixedGamesSeriesRule;
export type ParticipantSource =
| { type: "team"; teamId: TeamId }
| { type: "seed"; seedNumber: number }
| {
type: "series-outcome";
seriesId: SeriesId;
select: "winner" | "loser";
}
| {
type: "series-slot";
seriesId: SeriesId;
slot: SeriesSlot;
};
export interface SeriesStage {
type: SeriesStageType;
roundNumber?: number;
displayOrder: number;
}
export interface SeriesSlotDefinition {
position: SeriesSlot;
source: ParticipantSource;
}
export interface GameSlotDefinition {
id: GameSlotId;
seriesId: SeriesId;
ordinal: number;
}
export interface GrandFinalResetActivationRule {
type: "grand-final-reset-required";
grandFinalSeriesId: SeriesId;
}
export type SeriesActivationRule = GrandFinalResetActivationRule;
export interface SeriesDefinition {
id: SeriesId;
code?: string;
stage: SeriesStage;
slots: [SeriesSlotDefinition, SeriesSlotDefinition];
rule: SeriesRule;
activation?: SeriesActivationRule;
gameSlots: GameSlotDefinition[];
}
export interface PendingSeriesEntry {
slot: SeriesSlot;
teamId: TeamId | null;
gameWins: 0;
}
export interface ResolvedSeriesEntry {
slot: SeriesSlot;
teamId: TeamId;
gameWins: number;
}
export interface ReadySeriesEntry extends ResolvedSeriesEntry {
gameWins: 0;
}
export type PendingSeriesEntries = [PendingSeriesEntry, PendingSeriesEntry];
export type ReadySeriesEntries = [ReadySeriesEntry, ReadySeriesEntry];
export type ResolvedSeriesEntries = [
ResolvedSeriesEntry,
ResolvedSeriesEntry,
];
interface SeriesProjectionBase {
seriesId: SeriesId;
code?: string;
stage: SeriesStage;
rule: SeriesRule;
}
export interface PlayedSeriesOutcome {
type: "played";
winnerTeamId: TeamId;
loserTeamId: TeamId;
decidedByGameIds: GameId[];
completedAt: IsoDateTime;
}
export interface AdjudicatedSeriesOutcome {
type: "walkover" | "forfeit" | "administrative";
winnerTeamId: TeamId;
loserTeamId: TeamId;
decisionFactId: CompetitionFactId;
completedAt: IsoDateTime;
}
export type DrawDecisionBasis =
| { type: "played"; decidedByGameIds: GameId[] }
| { type: "administrative"; decisionFactId: CompetitionFactId };
export interface DrawSeriesOutcome {
type: "draw";
basis: DrawDecisionBasis;
completedAt: IsoDateTime;
}
export type SeriesOutcome =
| PlayedSeriesOutcome
| AdjudicatedSeriesOutcome
| DrawSeriesOutcome;
export interface InactiveSeriesProjection extends SeriesProjectionBase {
status: "inactive";
entries: PendingSeriesEntries;
leaderTeamId?: never;
outcome?: never;
}
export interface WaitingSeriesProjection extends SeriesProjectionBase {
status: "waiting";
entries: PendingSeriesEntries;
leaderTeamId?: never;
outcome?: never;
}
export interface ReadySeriesProjection extends SeriesProjectionBase {
status: "ready";
entries: ReadySeriesEntries;
leaderTeamId?: never;
outcome?: never;
}
export interface InProgressSeriesProjection extends SeriesProjectionBase {
status: "in-progress";
entries: ResolvedSeriesEntries;
leaderTeamId?: TeamId;
outcome?: never;
}
export interface CompletedSeriesProjection extends SeriesProjectionBase {
status: "completed";
entries: ResolvedSeriesEntries;
leaderTeamId?: never;
outcome: SeriesOutcome;
}
export type SeriesProjection =
| InactiveSeriesProjection
| WaitingSeriesProjection
| ReadySeriesProjection
| InProgressSeriesProjection
| CompletedSeriesProjection;