@juande_pl/rocketleague-stats-api-client 0.0.0-stage → 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,918 @@
+/**
+ * Shared structures used across Stats API events.
+ *
+ * Field visibility markers used in the docs below (mirroring the official documentation):
+ * - `CONDITIONAL`: only present when relevant.
+ * - `SPECTATOR`: only sent while spectating.
+ * - `REPLAY`: only relevant during replays.
+ *
+ * @see https://www.rocketleague.com/developer/stats-api
+ */
+/** Team index. `0` = Blue, `1` = Orange. */
+type TeamNum = number;
+/** Well-known team indexes. */
+declare const Team: {
+    readonly Blue: 0;
+    readonly Orange: 1;
+};
+/** Value of `Game.Ball.TeamNum` when the ball has not been touched yet. */
+declare const BALL_UNTOUCHED_TEAM_NUM = 255;
+/** A 3D world position in Unreal Units. */
+interface Vector {
+    X: number;
+    Y: number;
+    Z: number;
+}
+/** Minimal reference to a player, used by most events. */
+interface PlayerRef {
+    /** Display name. */
+    Name: string;
+    /** Spectator shortcut number. */
+    Shortcut: number;
+    /** Team index (0 = Blue, 1 = Orange). */
+    TeamNum: TeamNum;
+}
+/** The last touch of the ball before an event (goal, crossbar hit...). */
+interface BallLastTouch {
+    /** The player who made the last touch. */
+    Player: PlayerRef;
+    /** Speed of the ball resulting from this touch. */
+    Speed: number;
+}
+/**
+ * Platform identifier in the format `Platform|Uid|Splitscreen`
+ * (e.g. `"Steam|123|0"`, `"Epic|456|0"`).
+ */
+type PrimaryId = string;
+/** Full player state, sent in every `UpdateState` tick. */
+interface Player extends PlayerRef {
+    /** Platform identifier in the format `Platform|Uid|Splitscreen`. */
+    PrimaryId: PrimaryId;
+    /** Total match score. */
+    Score: number;
+    /** Goals scored this match. */
+    Goals: number;
+    /** Shot attempts this match. */
+    Shots: number;
+    /** Assists earned this match. */
+    Assists: number;
+    /** Saves made this match. */
+    Saves: number;
+    /** Total ball touches. */
+    Touches: number;
+    /** Touches by the car body (not ball). */
+    CarTouches: number;
+    /** Demolitions inflicted. */
+    Demos: number;
+    /**
+     * Asset names of the equipped loadout for the player's current team, sorted by product slot.
+     * Typed as optional because older game builds did not send it.
+     */
+    Loadout?: string[];
+    /** `SPECTATOR` True if the player currently has a vehicle. */
+    bHasCar?: boolean;
+    /** `SPECTATOR` Vehicle speed in Unreal Units/second. */
+    Speed?: number;
+    /** `SPECTATOR` Boost amount 0–100. */
+    Boost?: number;
+    /** `SPECTATOR` True if the player is currently boosting. */
+    bBoosting?: boolean;
+    /** `SPECTATOR` True if at least 3 wheels are touching the world. */
+    bOnGround?: boolean;
+    /** `SPECTATOR` True if the vehicle is on a wall. */
+    bOnWall?: boolean;
+    /** `SPECTATOR` True if the player is holding handbrake. */
+    bPowersliding?: boolean;
+    /** `SPECTATOR` True if the vehicle is currently destroyed. */
+    bDemolished?: boolean;
+    /** `SPECTATOR` True if the vehicle is at supersonic speed. */
+    bSupersonic?: boolean;
+    /**
+     * `SPECTATOR` Class name of the player's currently available Rumble pickup
+     * (e.g. `"SpecialPickup_GrapplingHook_TA"`). Omitted when not playing with rumble powerups.
+     */
+    PickupClass?: string;
+    /** `CONDITIONAL` The player who demolished this player. Present only when demolished. */
+    Attacker?: PlayerRef;
+}
+/** A team entry inside `UpdateState.Game.Teams`. */
+interface GameTeam {
+    /** Team name. */
+    Name: string;
+    /** Team index. */
+    TeamNum: TeamNum;
+    /** Team goal count. */
+    Score: number;
+    /** Hex color code (no `#`) for the team's primary color, e.g. `"0000FF"`. */
+    ColorPrimary: string;
+    /** Hex color code (no `#`) for the team's secondary color. */
+    ColorSecondary: string;
+}
+/** Current ball state inside `UpdateState.Game.Ball`. */
+interface GameBall {
+    /** Current ball speed in Unreal Units/second. */
+    Speed: number;
+    /** Index of the last team to touch the ball. `255` if the ball has not been touched. */
+    TeamNum: TeamNum;
+}
+/** Match metadata, sent in every `UpdateState` tick. */
+interface Game {
+    /** One entry per team, ordered by TeamNum. */
+    Teams: GameTeam[];
+    /**
+     * Playlist Id of the current match.
+     * Typed as optional because older game builds did not send it.
+     */
+    PlaylistId?: number;
+    /** Seconds remaining in the match. */
+    TimeSeconds: number;
+    /** True if the match is in overtime. */
+    bOvertime: boolean;
+    /** Current ball state. */
+    Ball: GameBall;
+    /** True if a goal replay or history replay is active. */
+    bReplay: boolean;
+    /** True if a team has won. */
+    bHasWinner: boolean;
+    /** Name of the winning team. Empty string if no winner yet. */
+    Winner: string;
+    /** Asset name of the current map (e.g. `"Stadium_P"`). */
+    Arena: string;
+    /** True if the client is currently viewing a specific vehicle. */
+    bHasTarget: boolean;
+    /**
+     * `CONDITIONAL` Player currently being viewed. Members are an empty string or `0`
+     * if the player does not have a spectator target.
+     */
+    Target?: PlayerRef;
+    /** `CONDITIONAL` `REPLAY` Current frame number if a replay is active. */
+    Frame?: number;
+    /** `CONDITIONAL` `REPLAY` Seconds elapsed since game start if a replay is active. */
+    Elapsed?: number;
+}
+
+/** Every event name the Stats API can emit. */
+declare const EVENT_NAMES: readonly ["UpdateState", "BallHit", "BoostPickup", "ClockUpdatedSeconds", "CountdownBegin", "CrossbarHit", "GoalReplayEnd", "GoalReplayStart", "GoalReplayWillEnd", "GoalScored", "MatchCreated", "MatchDestroyed", "MatchEnded", "MatchInitialized", "MatchPaused", "MatchUnpaused", "PlayerJoined", "PlayerLeft", "PodiumStart", "ReplayCreated", "RoundStarted", "StatfeedEvent"];
+/** Union of every event name the Stats API can emit. */
+type EventName = (typeof EVENT_NAMES)[number];
+/** Fields present in every event payload. */
+interface BaseEventData {
+    /** Match identifier. Only set for online or LAN matches. */
+    MatchGuid?: string;
+}
+/** Sent X times per second, based on the player's `PacketSendRate` setting. */
+interface UpdateStateData extends BaseEventData {
+    /** One entry per player in the match. */
+    Players: Player[];
+    /** Match metadata. */
+    Game: Game;
+}
+/** Sent one frame after the ball is hit. */
+interface BallHitData extends BaseEventData {
+    /** Players that hit the ball that frame. */
+    Players: PlayerRef[];
+    /** Ball state at the moment of the hit. */
+    Ball: {
+        /** Ball speed before the hit (Unreal Units/second). */
+        PreHitSpeed: number;
+        /** Ball speed after the hit (Unreal Units/second). */
+        PostHitSpeed: number;
+        /** World position of the ball at impact. */
+        Location: Vector;
+    };
+}
+/** Known boost pickup classes. */
+type BoostType = 'BoostType_Pad' | 'BoostType_Pill';
+/** `SPECTATOR` Sent when a vehicle collects a boost pad or pill. */
+interface BoostPickupData extends BaseEventData {
+    /** The player who collected the boost. */
+    Player: PlayerRef;
+    /** World location of the pickup. */
+    Location: Vector;
+    /** Amount of boost granted by the pickup. */
+    BoostAmount: number;
+    /** Pickup class: `BoostType_Pad` (small pad), `BoostType_Pill` (full/big boost). */
+    BoostType: BoostType;
+    /** True if the pickup occurred during replay playback. */
+    bReplay: boolean;
+}
+/** Sent when the in-game clock has changed. */
+interface ClockUpdatedSecondsData extends BaseEventData {
+    /** Seconds remaining in the match. */
+    TimeSeconds: number;
+    /** True if the game is in overtime. */
+    bOvertime: boolean;
+}
+/** Sent at the start of each round when the countdown starts. */
+interface CountdownBeginData extends BaseEventData {
+}
+/** Sent when the ball hits a crossbar. */
+interface CrossbarHitData extends BaseEventData {
+    /** World position of the ball when the impact occurred. */
+    BallLocation: Vector;
+    /** Ball speed on impact. */
+    BallSpeed: number;
+    /** Impact force of the ball relative to the crossbar normal. */
+    ImpactForce: number;
+    /** The last touch of the ball before the crossbar hit. */
+    BallLastTouch: BallLastTouch;
+}
+/** Sent when a goal replay ends. */
+interface GoalReplayEndData extends BaseEventData {
+}
+/** Sent when a goal replay starts. */
+interface GoalReplayStartData extends BaseEventData {
+}
+/** Sent when the ball explodes during a goal replay. Does not fire if the replay is skipped. */
+interface GoalReplayWillEndData extends BaseEventData {
+}
+/** Sent when a goal is scored. */
+interface GoalScoredData extends BaseEventData {
+    /** Speed of the ball (Unreal Units/second) when it crossed the goal line. */
+    GoalSpeed: number;
+    /** Length of the previous round in seconds (not the match clock). */
+    GoalTime: number;
+    /** World position of the ball when the goal was scored. */
+    ImpactLocation: Vector;
+    /** The player who scored the goal. */
+    Scorer: PlayerRef;
+    /** `CONDITIONAL` Present only when an assist was recorded. */
+    Assister?: PlayerRef;
+    /** The last touch of the ball before the goal. */
+    BallLastTouch: BallLastTouch;
+}
+/** Sent when all teams are created and replicated. */
+interface MatchCreatedData extends BaseEventData {
+}
+/** Sent when leaving the game. */
+interface MatchDestroyedData extends BaseEventData {
+}
+/** Sent when the match ends and a winner is chosen. */
+interface MatchEndedData extends BaseEventData {
+    /** Team index of the winning team. */
+    WinnerTeamNum: TeamNum;
+}
+/** Sent when the first countdown starts. */
+interface MatchInitializedData extends BaseEventData {
+}
+/** Sent when the game is paused by a match admin. */
+interface MatchPausedData extends BaseEventData {
+}
+/** Sent when the game is unpaused by a match admin. */
+interface MatchUnpausedData extends BaseEventData {
+}
+/** Sent when a player is added to the current match. */
+interface PlayerJoinedData extends BaseEventData {
+    /** Display name of the player who joined. */
+    PlayerName: string;
+    /** Platform identifier in the format `Platform|Uid|Splitscreen`. */
+    PrimaryId: PrimaryId;
+}
+/** Sent when a player is removed from the current match. */
+interface PlayerLeftData extends BaseEventData {
+    /** Display name of the player who left. */
+    PlayerName: string;
+    /** Platform identifier in the format `Platform|Uid|Splitscreen`. */
+    PrimaryId: PrimaryId;
+}
+/** Sent when the game enters the podium state after the match ends. */
+interface PodiumStartData extends BaseEventData {
+}
+/**
+ * Sent when a replay is initialized. Does not pertain to goal replays,
+ * only replays loaded via the Match History menu.
+ */
+interface ReplayCreatedData extends BaseEventData {
+    /** File name of the replay. */
+    FileName: string;
+    /** Timestamp the replay was created (e.g. `"2026-06-05 18:42:13"`). */
+    Date: string;
+}
+/** Sent when the game enters the active state (after the countdown finishes). */
+interface RoundStartedData extends BaseEventData {
+}
+/**
+ * Known `StatfeedEvent.EventName` values. The type stays open (`string & {}`)
+ * so new stats added by the game don't break consumers.
+ */
+type StatEventName = 'Demolish' | 'Demolition' | 'Goal' | 'Win' | 'MVP' | 'AerialGoal' | 'BackwardsGoal' | 'BicycleGoal' | 'LongGoal' | 'TurtleGoal' | 'PoolShot' | 'OvertimeGoal' | 'HatTrick' | 'Assist' | 'Playmaker' | 'Save' | 'EpicSave' | 'Savior' | 'Shot' | 'Center' | 'Clear' | 'FirstTouch' | 'BreakoutDamage' | 'BreakoutDamageLarge' | 'LowFive' | 'HighFive' | 'HoopsSwishGoal' | 'BicycleHit' | 'OwnGoal' | 'FlipReset' | (string & {});
+/** Sent when someone earns a stat. */
+interface StatfeedEventData extends BaseEventData {
+    /** Asset name of the StatEvent (e.g. `"Demolish"`, `"Save"`). Prefer this over `Type` for logic. */
+    EventName: StatEventName;
+    /** Localized display label for the stat (e.g. `"Demolition"`). */
+    Type: string;
+    /** Player who earned the stat. */
+    MainTarget: PlayerRef;
+    /** `CONDITIONAL` Player involved in the stat (e.g. the demolished player). */
+    SecondaryTarget?: PlayerRef;
+}
+/** Maps every event name to its payload type. */
+interface EventDataMap {
+    UpdateState: UpdateStateData;
+    BallHit: BallHitData;
+    BoostPickup: BoostPickupData;
+    ClockUpdatedSeconds: ClockUpdatedSecondsData;
+    CountdownBegin: CountdownBeginData;
+    CrossbarHit: CrossbarHitData;
+    GoalReplayEnd: GoalReplayEndData;
+    GoalReplayStart: GoalReplayStartData;
+    GoalReplayWillEnd: GoalReplayWillEndData;
+    GoalScored: GoalScoredData;
+    MatchCreated: MatchCreatedData;
+    MatchDestroyed: MatchDestroyedData;
+    MatchEnded: MatchEndedData;
+    MatchInitialized: MatchInitializedData;
+    MatchPaused: MatchPausedData;
+    MatchUnpaused: MatchUnpausedData;
+    PlayerJoined: PlayerJoinedData;
+    PlayerLeft: PlayerLeftData;
+    PodiumStart: PodiumStartData;
+    ReplayCreated: ReplayCreatedData;
+    RoundStarted: RoundStartedData;
+    StatfeedEvent: StatfeedEventData;
+}
+/** A decoded event message with its name and typed payload. */
+interface StatsApiEventOf<E extends EventName> {
+    Event: E;
+    Data: EventDataMap[E];
+}
+/**
+ * Discriminated union of every decoded event message.
+ * Narrow it by checking `event.Event`:
+ *
+ * ```ts
+ * if (event.Event === 'GoalScored') event.Data.Scorer.Name;
+ * ```
+ */
+type StatsApiEvent = {
+    [E in EventName]: StatsApiEventOf<E>;
+}[EventName];
+/**
+ * The raw envelope as it arrives over the socket. The game encodes `Data`
+ * as a JSON string; some tools forward it as an object, so both are accepted.
+ */
+interface RawEventEnvelope {
+    Event: string;
+    Data: string | Record<string, unknown>;
+}
+
+/** Every command name the Stats API accepts. */
+declare const COMMAND_NAMES: readonly ["ChangePOV", "LoadReplay", "SeekReplay", "SetGameSpeed", "SetHUDVisibility", "SetMatchPaused"];
+/** Union of every command name the Stats API accepts. */
+type CommandName = (typeof COMMAND_NAMES)[number];
+/** Accepted camera perspectives for `ChangePOV`. */
+declare const PERSPECTIVES: readonly ["Fly", "SoftAttach", "HardAttach", "PlayerView", "AutoCam", "Camera_Director"];
+/** Camera mode for `ChangePOV`. */
+type Perspective = (typeof PERSPECTIVES)[number];
+/**
+ * What to look at for `ChangePOV`: `"Ball"`, or a player's spectator shortcut
+ * as an all-digit string (e.g. `"1"`). Any other value is rejected by the game.
+ */
+type Focus = 'Ball' | `${number}`;
+/**
+ * `SPECTATOR` `REPLAY` Changes the spectator/replay viewpoint.
+ * At least one of `Focus` or `Perspective` must be supplied; both may be combined.
+ */
+type ChangePOVData = {
+    Focus: Focus;
+    Perspective?: Perspective;
+} | {
+    Focus?: Focus;
+    Perspective: Perspective;
+};
+/**
+ * Loads and begins playback of a replay by file name or by file path.
+ * At least one of `FileName` or `Path` must be supplied. `FileName` takes precedence.
+ */
+type LoadReplayData = {
+    FileName: string;
+    Path?: string;
+} | {
+    FileName?: string;
+    Path: string;
+};
+/**
+ * `REPLAY` Jumps replay playback to a target frame or time.
+ * At least one of `Frame` or `TimeSeconds` must be supplied. `Frame` takes precedence.
+ */
+type SeekReplayData = {
+    Frame: number;
+    TimeSeconds?: number;
+} | {
+    Frame?: number;
+    TimeSeconds: number;
+};
+/** `REPLAY` Sets replay playback speed. */
+interface SetGameSpeedData {
+    /** Playback multiplier. 1.0 = normal, 0.5 = half speed, 2.0 = double. Must be ≥ 0. */
+    Speed: number;
+}
+/** Shows or hides the in-game HUD. */
+interface SetHUDVisibilityData {
+    /** `true` shows the HUD; `false` hides it. */
+    bVisible: boolean;
+}
+/** Pauses or unpauses the current match or replay. */
+interface SetMatchPausedData {
+    /** `true` pauses; `false` resumes. */
+    bPaused: boolean;
+}
+/** Maps every command name to its payload type. */
+interface CommandDataMap {
+    ChangePOV: ChangePOVData;
+    LoadReplay: LoadReplayData;
+    SeekReplay: SeekReplayData;
+    SetGameSpeed: SetGameSpeedData;
+    SetHUDVisibility: SetHUDVisibilityData;
+    SetMatchPaused: SetMatchPausedData;
+}
+/** A command envelope with its name and typed payload. */
+interface StatsApiCommandOf<C extends CommandName> {
+    Command: C;
+    Data: CommandDataMap[C];
+}
+/** Discriminated union of every command envelope. */
+type StatsApiCommand = {
+    [C in CommandName]: StatsApiCommandOf<C>;
+}[CommandName];
+
+/**
+ * Small, dependency-free building blocks for runtime type guards.
+ * They are exported so consumers can compose their own guards too.
+ */
+/** A runtime type guard. */
+type Guard<T> = (value: unknown) => value is T;
+/** Extracts the guarded type from a {@link Guard}. */
+type GuardedType<G> = G extends Guard<infer T> ? T : never;
+/** Checks that a value is a non-null, non-array object. */
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+declare const isString: Guard<string>;
+/** Checks for a finite number (rejects `NaN` and `Infinity`). */
+declare const isNumber: Guard<number>;
+/** Checks for a finite integer. */
+declare const isInteger: Guard<number>;
+declare const isBoolean: Guard<boolean>;
+/** Accepts `undefined` or a value matching `guard`. */
+declare function optional<T>(guard: Guard<T>): Guard<T | undefined>;
+/** Checks for an array whose items all match `guard`. */
+declare function arrayOf<T>(guard: Guard<T>): Guard<T[]>;
+/** Checks that a value is one of the given literals. */
+declare function oneOf<const T extends readonly (string | number | boolean)[]>(values: T): Guard<T[number]>;
+/** Specification for {@link shape}: one guard per property of `T`, optional ones included. */
+type ShapeSpec<T> = {
+    [K in keyof Required<T>]: Guard<T[K]>;
+};
+/**
+ * Builds a guard for an object type from one guard per property.
+ * Extra properties are allowed so new fields added by the game don't break validation.
+ * The spec is checked against `T` at compile time, so a missing property is a type error.
+ */
+declare function shape<T extends object>(spec: ShapeSpec<T>): Guard<T>;
+/** Combines guards with logical AND. */
+declare function allOf<T>(guard: Guard<T>, ...checks: ((value: T) => boolean)[]): Guard<T>;
+
+declare const isVector: Guard<Vector>;
+declare const isPlayerRef: Guard<PlayerRef>;
+declare const isBallLastTouch: Guard<BallLastTouch>;
+declare const isPlayer: Guard<Player>;
+declare const isGameTeam: Guard<GameTeam>;
+declare const isGameBall: Guard<GameBall>;
+declare const isGame: Guard<Game>;
+declare const isUpdateStateData: Guard<UpdateStateData>;
+declare const isBallHitData: Guard<BallHitData>;
+declare const isBoostPickupData: Guard<BoostPickupData>;
+declare const isClockUpdatedSecondsData: Guard<ClockUpdatedSecondsData>;
+declare const isCrossbarHitData: Guard<CrossbarHitData>;
+declare const isGoalScoredData: Guard<GoalScoredData>;
+declare const isMatchEndedData: Guard<MatchEndedData>;
+declare const isPlayerJoinedData: Guard<PlayerJoinedData>;
+declare const isPlayerLeftData: Guard<PlayerLeftData>;
+declare const isReplayCreatedData: Guard<ReplayCreatedData>;
+declare const isStatfeedEventData: Guard<StatfeedEventData>;
+declare const isCountdownBeginData: Guard<EventDataMap['CountdownBegin']>;
+declare const isGoalReplayEndData: Guard<EventDataMap['GoalReplayEnd']>;
+declare const isGoalReplayStartData: Guard<EventDataMap['GoalReplayStart']>;
+declare const isGoalReplayWillEndData: Guard<EventDataMap['GoalReplayWillEnd']>;
+declare const isMatchCreatedData: Guard<EventDataMap['MatchCreated']>;
+declare const isMatchDestroyedData: Guard<EventDataMap['MatchDestroyed']>;
+declare const isMatchInitializedData: Guard<EventDataMap['MatchInitialized']>;
+declare const isMatchPausedData: Guard<EventDataMap['MatchPaused']>;
+declare const isMatchUnpausedData: Guard<EventDataMap['MatchUnpaused']>;
+declare const isPodiumStartData: Guard<EventDataMap['PodiumStart']>;
+declare const isRoundStartedData: Guard<EventDataMap['RoundStarted']>;
+/** Payload guard for every event, keyed by event name. */
+declare const eventDataGuards: {
+    readonly [E in EventName]: Guard<EventDataMap[E]>;
+};
+/** Checks that a string is a known event name. */
+declare const isEventName: Guard<EventName>;
+/** Checks that `data` is a valid payload for the event `name`. */
+declare function isEventData<E extends EventName>(name: E, data: unknown): data is EventDataMap[E];
+/** Checks the raw envelope shape (`Event` string + `Data` string or object), without validating the payload. */
+declare function isRawEventEnvelope(value: unknown): value is RawEventEnvelope;
+/**
+ * Checks that a value is a fully valid, decoded event message (with `Data` already parsed),
+ * optionally restricted to a single event name.
+ *
+ * ```ts
+ * if (isStatsApiEvent(msg, 'GoalScored')) msg.Data.Scorer.Name;
+ * ```
+ */
+declare function isStatsApiEvent(value: unknown): value is StatsApiEvent;
+declare function isStatsApiEvent<E extends EventName>(value: unknown, name: E): value is StatsApiEventOf<E>;
+
+/** Checks for `"Ball"` or an all-digit spectator shortcut string. */
+declare const isFocus: Guard<Focus>;
+declare const isPerspective: Guard<Perspective>;
+declare const isChangePOVData: Guard<ChangePOVData>;
+/** `FileName` / `Path` must be strings; at least one must be non-empty. */
+declare const isLoadReplayData: Guard<LoadReplayData>;
+/** `Frame` must be a non-negative integer, `TimeSeconds` a non-negative number; at least one is required. */
+declare const isSeekReplayData: Guard<SeekReplayData>;
+/** `Speed` must be a finite number ≥ 0. */
+declare const isSetGameSpeedData: Guard<SetGameSpeedData>;
+declare const isSetHUDVisibilityData: Guard<SetHUDVisibilityData>;
+declare const isSetMatchPausedData: Guard<SetMatchPausedData>;
+/** Payload guard for every command, keyed by command name. */
+declare const commandDataGuards: {
+    readonly [C in CommandName]: Guard<CommandDataMap[C]>;
+};
+/** Checks that a string is a known command name. */
+declare const isCommandName: Guard<CommandName>;
+/** Checks that `data` is a valid payload for the command `name`. */
+declare function isCommandData<C extends CommandName>(name: C, data: unknown): data is CommandDataMap[C];
+/**
+ * Checks that a value is a fully valid command envelope, optionally restricted to a single command name.
+ */
+declare function isStatsApiCommand(value: unknown): value is StatsApiCommand;
+declare function isStatsApiCommand<C extends CommandName>(value: unknown, name: C): value is StatsApiCommandOf<C>;
+
+/** Why a message could not be turned into a {@link StatsApiEvent}. */
+type ParseFailureReason = 
+/** The message is not valid JSON. */
+'invalid-json'
+/** The message is JSON but not an `{ Event, Data }` envelope. */
+ | 'invalid-envelope'
+/** `Data` is a string that is not valid JSON, or does not decode to an object. */
+ | 'invalid-data-json'
+/** `Event` is not one of the documented event names. */
+ | 'unknown-event'
+/** `Data` does not match the documented shape for that event. */
+ | 'invalid-data';
+/** A message that failed to parse or validate. */
+interface ParseFailure {
+    ok: false;
+    reason: ParseFailureReason;
+    /** The original input. */
+    raw: unknown;
+    /** Event name, when it could be read. */
+    event?: string;
+    /** Decoded payload, when it could be read. */
+    data?: unknown;
+}
+/** A message that was decoded (and validated, unless disabled). */
+interface ParseSuccess {
+    ok: true;
+    event: StatsApiEvent;
+}
+type ParseResult = ParseSuccess | ParseFailure;
+interface ParseOptions {
+    /**
+     * Run the payload type guard for the event.
+     * When `false`, only the envelope and event name are checked and `Data` is trusted as-is.
+     * @default true
+     */
+    validate?: boolean;
+}
+/**
+ * Decodes a message coming from the Stats API socket.
+ *
+ * Accepts the raw JSON text, or an already `JSON.parse`d envelope. The game encodes
+ * `Data` as a JSON string inside the envelope; it is decoded here. If `Data` is already
+ * an object it is used directly.
+ *
+ * Never throws: check `result.ok`.
+ */
+declare function parseEventMessage(raw: unknown, options?: ParseOptions): ParseResult;
+
+/** Base class for every error thrown or emitted by this library. */
+declare class StatsApiError extends Error {
+    name: string;
+}
+/** Thrown by `send()` when the socket is not open. */
+declare class NotConnectedError extends StatsApiError {
+    name: string;
+    constructor(message?: string);
+}
+/** Thrown by `send()` when a command name or payload fails validation. */
+declare class CommandValidationError extends StatsApiError {
+    /** The command name that was passed. */
+    readonly command: unknown;
+    /** The payload that was passed. */
+    readonly data: unknown;
+    name: string;
+    constructor(message: string, 
+    /** The command name that was passed. */
+    command: unknown, 
+    /** The payload that was passed. */
+    data: unknown);
+}
+/** Emitted on `error` when the WebSocket reports a failure. */
+declare class ConnectionError extends StatsApiError {
+    name: string;
+}
+/** Emitted on `error` when an event listener throws. */
+declare class ListenerError extends StatsApiError {
+    /** The listener event name that was being dispatched. */
+    readonly eventName: string;
+    name: string;
+    constructor(
+    /** The listener event name that was being dispatched. */
+    eventName: string, cause: unknown);
+}
+
+/** Section of the Stats API `.ini` file that holds the exporter settings. */
+declare const STATS_API_SECTION = "TAGame.MatchStatsExporter_TA";
+/** `PacketSendRate` written when the current value is invalid (`<= 0`, missing, or above the maximum). */
+declare const DEFAULT_PACKET_SEND_RATE = 30;
+/** Highest `PacketSendRate` the game accepts. */
+declare const MAX_PACKET_SEND_RATE = 120;
+/** `.ini` file names, in lookup order. `TAStatsAPI.ini` wins over `DefaultStatsAPI.ini`. */
+declare const STATS_API_INI_FILES: readonly ["TAStatsAPI.ini", "DefaultStatsAPI.ini"];
+interface EnsureStatsApiOptions {
+    /** Rocket League install directory (the folder containing `TAGame`). Auto-detected on Windows when omitted. */
+    installDir?: string;
+    /** Exact path of the `.ini` file to check. Overrides `installDir` and auto-detection. */
+    iniPath?: string;
+    /** `PacketSendRate` written when the current value is `0` or less, missing, or above `120`. Must be 1–120. @default 30 */
+    packetSendRate?: number;
+    /**
+     * Called with a human-readable message when the file was changed (restart required) or could not be written.
+     * Pass `false` to stay silent.
+     * @default console.warn
+     */
+    warn?: ((message: string) => void) | false;
+}
+type EnsureStatsApiResult = 
+/** No Stats API `.ini` file was found. */
+{
+    status: 'not-found';
+    searched: string[];
+}
+/** `PacketSendRate` was already between 1 and 120. */
+ | {
+    status: 'enabled';
+    iniPath: string;
+    packetSendRate: number;
+}
+/** `PacketSendRate` was `0` or less, missing, or above 120, and has been set. The game must be restarted. */
+ | {
+    status: 'updated';
+    iniPath: string;
+    previous: number | undefined;
+    packetSendRate: number;
+    restartRequired: true;
+}
+/** The file needed a change but could not be written (e.g. no permission under `Program Files`). */
+ | {
+    status: 'write-failed';
+    iniPath: string;
+    previous: number | undefined;
+    error: unknown;
+};
+interface PacketSendRateEdit {
+    /** Current value, or `undefined` if the key is missing (the game then uses `0`). */
+    previous: number | undefined;
+    /** `true` when `PacketSendRate` is `0` or less, missing (Stats API disabled), or above {@link MAX_PACKET_SEND_RATE}. */
+    needsUpdate: boolean;
+    /** The file contents with `PacketSendRate` set to the requested rate. Equals the input when `needsUpdate` is false. */
+    content: string;
+}
+/**
+ * Reads `PacketSendRate` from the `[TAGame.MatchStatsExporter_TA]` section of an `.ini` file
+ * and, if it is `0` or less (or missing), returns the contents with it set to `rate`.
+ * Keeps comments, the other keys, the BOM and the line endings untouched.
+ */
+declare function editPacketSendRate(content: string, rate?: number): PacketSendRateEdit;
+/**
+ * Candidate Rocket League install directories (Epic Games Store and Steam, Windows only).
+ * Not every returned directory necessarily exists.
+ */
+declare function findRocketLeagueInstallDirs(): Promise<string[]>;
+/** Paths of the Stats API `.ini` files inside an install directory, in lookup order. */
+declare function statsApiIniPaths(installDir: string): string[];
+/** Returns the Stats API `.ini` file in use (`TAStatsAPI.ini`, else `DefaultStatsAPI.ini`), or `undefined`. */
+declare function findStatsApiIni(installDir?: string): Promise<{
+    iniPath: string | undefined;
+    searched: string[];
+}>;
+/**
+ * Looks for the Stats API `.ini` file (`TAStatsAPI.ini` or `DefaultStatsAPI.ini`). If `PacketSendRate`
+ * is `0` or less, missing, or above `120`, sets it to `30` (or `options.packetSendRate`) and warns that the game must be restarted,
+ * since Rocket League only reads this file at launch.
+ *
+ * Never throws: every outcome is reported in the returned result.
+ */
+declare function ensureStatsApiEnabled(options?: EnsureStatsApiOptions): Promise<EnsureStatsApiResult>;
+
+/**
+ * The subset of the standard `WebSocket` API this client relies on.
+ * Satisfied by the browser/Node.js (>= 22) global `WebSocket` and by the `ws` package.
+ */
+interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: 'open', listener: () => void): void;
+    addEventListener(type: 'close', listener: (event: {
+        code: number;
+        reason: string;
+    }) => void): void;
+    addEventListener(type: 'error', listener: (event: unknown) => void): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+}
+/** A constructor producing a {@link WebSocketLike}. */
+type WebSocketConstructor = new (url: string) => WebSocketLike;
+interface ReconnectOptions {
+    /** Delay before the first reconnection attempt, in ms. @default 1000 */
+    initialDelay?: number;
+    /** Upper bound for the delay between attempts, in ms. @default 30000 */
+    maxDelay?: number;
+    /** Multiplier applied to the delay after every failed attempt. @default 2 */
+    factor?: number;
+    /** Maximum consecutive attempts before giving up. @default Infinity */
+    maxAttempts?: number;
+}
+interface StatsApiClientOptions {
+    /** Host of the Rocket League client. @default '127.0.0.1' */
+    host?: string;
+    /** The `WebPort` configured in `TAStatsAPI.ini`. @default 49124 */
+    port?: number;
+    /** Use `wss://` instead of `ws://`. @default false */
+    secure?: boolean;
+    /** Full WebSocket URL. Overrides `host`, `port` and `secure` when set. */
+    url?: string;
+    /**
+     * Connect automatically after construction. Set to `false` to call {@link RocketLeagueStatsClient.connect} yourself.
+     * The connection starts on the next microtask, so listeners attached right after `new` still receive `connect`.
+     * @default true
+     */
+    autoConnect?: boolean;
+    /**
+     * Reconnect automatically when the connection drops or cannot be established
+     * (e.g. the game is not running yet). `false` disables it.
+     * @default true
+     */
+    reconnect?: boolean | ReconnectOptions;
+    /**
+     * Validate every incoming event with its type guard. Invalid events are not dispatched
+     * and are reported on `invalidMessage` instead.
+     * @default true
+     */
+    validateEvents?: boolean;
+    /**
+     * WebSocket implementation. Defaults to `globalThis.WebSocket`
+     * (browsers, Node.js >= 22). Pass `WebSocket` from the `ws` package for older runtimes.
+     */
+    WebSocket?: WebSocketConstructor;
+    /**
+     * **Node.js only** (ignored in browsers). Check the Stats API `.ini` file (`TAStatsAPI.ini`, else
+     * `DefaultStatsAPI.ini`) on construction and, if `PacketSendRate` is `0` or less, missing, or above `120`, set it to `30` and
+     * warn that the game must be restarted. Pass options to customize it, or `false` to disable it.
+     * @default true
+     */
+    ensureStatsApi?: boolean | EnsureStatsApiOptions;
+}
+/** Connection state of the client. */
+type ConnectionState = 'idle' | 'connecting' | 'open' | 'closed';
+interface DisconnectInfo {
+    code: number;
+    reason: string;
+    /** `true` when a reconnection attempt has been scheduled. */
+    willReconnect: boolean;
+}
+interface ReconnectInfo {
+    /** 1-based attempt number. */
+    attempt: number;
+    /** Delay before this attempt, in ms. */
+    delay: number;
+}
+/** Listener for a specific game event. Receives the typed payload and the whole decoded message. */
+type GameEventListener<E extends EventName> = (data: EventDataMap[E], event: StatsApiEventOf<E>) => void;
+/** Listener receiving every game event as a discriminated union. */
+type AnyEventListener = (event: StatsApiEvent) => void;
+/** Client lifecycle events (lowercase, so they never collide with game events). */
+interface LifecycleListenerMap {
+    /** The socket is open. */
+    connect: () => void;
+    /** The socket closed. */
+    disconnect: (info: DisconnectInfo) => void;
+    /** A reconnection attempt has been scheduled. */
+    reconnecting: (info: ReconnectInfo) => void;
+    /** A connection error or a listener error happened. */
+    error: (error: Error) => void;
+    /** A message could not be decoded, has an unknown event name, or failed validation. */
+    invalidMessage: (failure: ParseFailure) => void;
+}
+/** Every listener accepted by {@link RocketLeagueStatsClient.on}. */
+type ClientListenerMap = {
+    [E in EventName]: GameEventListener<E>;
+} & LifecycleListenerMap;
+/** Any name accepted by {@link RocketLeagueStatsClient.on}. */
+type ClientEventName = keyof ClientListenerMap;
+/** Call it to remove the listener. */
+type Unsubscribe = () => void;
+/**
+ * WebSocket client for the Rocket League Stats API.
+ *
+ * ```ts
+ * const client = new RocketLeagueStatsClient();
+ *
+ * client.on('GoalScored', (data) => console.log(`${data.Scorer.Name} scored!`));
+ * client.onAny((event) => console.log(event.Event));
+ * client.send('ChangePOV', { Focus: 'Ball' });
+ * ```
+ *
+ * @see https://www.rocketleague.com/developer/stats-api
+ */
+declare class RocketLeagueStatsClient {
+    #private;
+    /** The WebSocket URL this client connects to. */
+    readonly url: string;
+    /**
+     * Result of the `.ini` check (see the `ensureStatsApi` option). `undefined` outside Node.js or when
+     * `ensureStatsApi: false`. Never rejects.
+     */
+    readonly statsApiConfig: Promise<EnsureStatsApiResult> | undefined;
+    constructor(options?: StatsApiClientOptions);
+    /** Current connection state. */
+    get state(): ConnectionState;
+    /** `true` when the socket is open and commands can be sent. */
+    get isConnected(): boolean;
+    /**
+     * Opens the connection. Does nothing if already connecting or connected.
+     * Called automatically unless `autoConnect: false` was passed.
+     */
+    connect(): void;
+    /** Closes the connection and stops any pending reconnection. */
+    disconnect(code?: number, reason?: string): void;
+    /**
+     * Decodes, validates and dispatches one raw message. Called for every socket message;
+     * exposed so messages from another transport (e.g. the TCP port, a recording) can be fed in.
+     */
+    handleMessage(raw: unknown): void;
+    /**
+     * Listens to a game event (e.g. `'GoalScored'`) or a lifecycle event (e.g. `'connect'`).
+     * The listener's arguments are typed from the event name.
+     *
+     * @returns A function that removes the listener.
+     */
+    on<K extends ClientEventName>(name: K, listener: ClientListenerMap[K]): Unsubscribe;
+    /** Like {@link on}, but the listener is removed after its first call. */
+    once<K extends ClientEventName>(name: K, listener: ClientListenerMap[K]): Unsubscribe;
+    /** Removes a listener added with {@link on}. */
+    off<K extends ClientEventName>(name: K, listener: ClientListenerMap[K]): void;
+    /**
+     * Listens to **every** game event. The argument is a discriminated union: narrow it with `event.Event`.
+     *
+     * ```ts
+     * client.onAny((event) => {
+     *   if (event.Event === 'StatfeedEvent') console.log(event.Data.EventName);
+     * });
+     * ```
+     *
+     * @returns A function that removes the listener.
+     */
+    onAny(listener: AnyEventListener): Unsubscribe;
+    /** Removes a listener added with {@link onAny}. */
+    offAny(listener: AnyEventListener): void;
+    /** Removes every listener, or every listener of one name. */
+    removeAllListeners(name?: ClientEventName): void;
+    /**
+     * Resolves with the payload of the next occurrence of a game event.
+     * Rejects after `timeout` ms if provided.
+     */
+    waitFor<E extends EventName>(name: E, options?: {
+        timeout?: number;
+    }): Promise<EventDataMap[E]>;
+    /**
+     * Sends a command to the game. The payload is type-checked at compile time and
+     * validated with its guard at runtime before being sent.
+     *
+     * ```ts
+     * client.send('ChangePOV', { Focus: '1', Perspective: 'PlayerView' });
+     * client.send({ Command: 'SetHUDVisibility', Data: { bVisible: false } });
+     * ```
+     *
+     * @throws {CommandValidationError} If the command name or payload is invalid.
+     * @throws {NotConnectedError} If the socket is not open.
+     */
+    send<C extends CommandName>(command: C, data: CommandDataMap[C]): void;
+    send(command: StatsApiCommand): void;
+}
+
+export { BALL_UNTOUCHED_TEAM_NUM, COMMAND_NAMES, CommandValidationError, ConnectionError, DEFAULT_PACKET_SEND_RATE as D, EVENT_NAMES, ListenerError, MAX_PACKET_SEND_RATE as M, NotConnectedError, PERSPECTIVES, RocketLeagueStatsClient, STATS_API_INI_FILES as S, StatsApiError, Team, STATS_API_SECTION as a, allOf, arrayOf, ensureStatsApiEnabled as b, findStatsApiIni as c, commandDataGuards, RocketLeagueStatsClient as default, editPacketSendRate as e, eventDataGuards, findRocketLeagueInstallDirs as f, isBallHitData, isBallLastTouch, isBoolean, isBoostPickupData, isChangePOVData, isClockUpdatedSecondsData, isCommandData, isCommandName, isCountdownBeginData, isCrossbarHitData, isEventData, isEventName, isFocus, isGame, isGameBall, isGameTeam, isGoalReplayEndData, isGoalReplayStartData, isGoalReplayWillEndData, isGoalScoredData, isInteger, isLoadReplayData, isMatchCreatedData, isMatchDestroyedData, isMatchEndedData, isMatchInitializedData, isMatchPausedData, isMatchUnpausedData, isNumber, isPerspective, isPlayer, isPlayerJoinedData, isPlayerLeftData, isPlayerRef, isPodiumStartData, isRawEventEnvelope, isRecord, isReplayCreatedData, isRoundStartedData, isSeekReplayData, isSetGameSpeedData, isSetHUDVisibilityData, isSetMatchPausedData, isStatfeedEventData, isStatsApiCommand, isStatsApiEvent, isString, isUpdateStateData, isVector, oneOf, optional, parseEventMessage, statsApiIniPaths as s, shape };
+export type { AnyEventListener, BallHitData, BallLastTouch, BaseEventData, BoostPickupData, BoostType, ChangePOVData, ClientEventName, ClientListenerMap, ClockUpdatedSecondsData, CommandDataMap, CommandName, ConnectionState, CountdownBeginData, CrossbarHitData, DisconnectInfo, EnsureStatsApiOptions, EnsureStatsApiResult, EventDataMap, EventName, Focus, Game, GameBall, GameEventListener, GameTeam, GoalReplayEndData, GoalReplayStartData, GoalReplayWillEndData, GoalScoredData, Guard, GuardedType, LifecycleListenerMap, LoadReplayData, MatchCreatedData, MatchDestroyedData, MatchEndedData, MatchInitializedData, MatchPausedData, MatchUnpausedData, PacketSendRateEdit as P, ParseFailure, ParseFailureReason, ParseOptions, ParseResult, ParseSuccess, Perspective, Player, PlayerJoinedData, PlayerLeftData, PlayerRef, PodiumStartData, PrimaryId, RawEventEnvelope, ReconnectInfo, ReconnectOptions, ReplayCreatedData, RoundStartedData, SeekReplayData, SetGameSpeedData, SetHUDVisibilityData, SetMatchPausedData, ShapeSpec, StatEventName, StatfeedEventData, StatsApiClientOptions, StatsApiCommand, StatsApiCommandOf, StatsApiEvent, StatsApiEventOf, TeamNum, Unsubscribe, UpdateStateData, Vector, WebSocketConstructor, WebSocketLike };