feat: GetHypetrainStatus and refactor EventSub for Hype Train V2 events

[jackmcguire1]

Notes

• refactored existing EventSub events to v2
• added new GetHypetrainStatus endpoint

Breaking

V1 of the following HypeTrain EventSub subscriptions have been deprecated and V2 subscription with different versions are now available for migration:

Existing structs have been refactored, as opposed to introducing new structs

2025‑06‑13

This pull request introduces significant improvements and extensions to the handling of Hype Train events and status in the codebase. The main changes include the addition of new data structures and API methods for retrieving detailed Hype Train status, updates to event types to support new features, and comprehensive tests for the new functionality.

Hype Train Status API and Data Structures

• Added new types to hype_train.go to represent Hype Train status, contributions, shared train participants, all-time high records, and response wrappers. Introduced the GetHypeTrainStatus API method for retrieving the current and historical Hype Train status for a broadcaster, with a note that the previous GetHypeTrainEvents method is now deprecated. [1] [2]

Event Data Model Enhancements

• Updated Hype Train event structs in eventsub.go (EventSubHypeTrainBeginEvent, EventSubHypeTrainProgressEvent, EventSubHypeTrainEndEvent) to support new fields such as ID, Level, AllTimeHighLevel, AllTimeHighTotal, SharedTrainParticipants, Type, and IsSharedTrain, reflecting the latest event schema (V2).
• Added the EventSubSharedTrainParticipant type to eventsub.go and updated EventSubContribution to use int for Total instead of int64, aligning with new event payloads.

Test Coverage

• Added a comprehensive test TestGetHypeTrainStatus in hype_train_test.go to verify correct API behavior, including error handling, response parsing, and edge cases for broadcasters with and without active Hype Trains.

Miscellaneous Data Model Updates

• Updated EventSubCharityAmount in eventsub.go to include an Amount field alongside Value, supporting additional charity event data.

[coveralls]

Pull Request Test Coverage Report for Build 17500025555

Details

• 10 of 10 (100.0%) changed or added relevant lines in 1 file are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage increased (+0.04%) to 92.777%

---

Totals
Change from base Build 14026929583:	0.04%
Covered Lines:	1734
Relevant Lines:	1869

---

💛 - Coveralls

[jackmcguire1]

@nicklaw5 hope all is well

[nicklaw5]

@jackmcguire1 does this PR introduce breaking changes? Or can both v1 and v2 hype train events co-exist with your implementation?

[Copilot]

Pull Request Overview

This PR adds a new GetHypeTrainStatus API method to replace the deprecated GetHypeTrainEvents method, and updates EventSub Hype Train event structures to version 2 with enhanced shared train support.

• Introduces GetHypeTrainStatus function with corresponding types for the Hype Train status API
• Deprecates the existing GetHypeTrainEvents function
• Updates EventSub Hype Train event types (begin, progress, end) to v2 with new fields for shared trains

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
hype_train.go	Adds new types and GetHypeTrainStatus function; marks GetHypeTrainEvents as deprecated
hype_train_test.go	Adds comprehensive test coverage for GetHypeTrainStatus including success, error, and edge cases
eventsub.go	Updates EventSub Hype Train event types to v2, adds shared train participant type, and modifies contribution/charity amount types

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Type inconsistency: HypeTrainStatusContribution.Total is int64, but the equivalent EventSubContribution.Total in eventsub.go (line 756) is int. This creates unnecessary type conversion overhead when mapping between API and EventSub structures. Consider using consistent types across related structures.

[Copilot]

The EventSubCharityAmount struct now has both Value and Amount fields which appear to serve the same purpose. This is confusing and potentially error-prone. If both fields are required by the API, add a comment explaining the difference between them.

Suggested change

	// EventSubCharityAmount represents a monetary amount in a charity event.
	// Both Value and Amount are present in the API response:
	// - Value: The raw amount value, typically used for calculations.
	// - Amount: May be a duplicate of Value, or used for display purposes; refer to API documentation for exact usage.
	// If both fields are required by the API, ensure to use the correct field as per context.

[nicklaw5]

@jackmcguire1 Review copilot's suggestions. I'm going to give this a ✅ as I don't believing this introduces breaking changes.