fairy

type Agent struct {
	// ID is the internal numeric identifier of the Agent.
	ID int `json:"id"`

	// Name is the localized display name of the Agent (e.g. "Ellen", "Zhu Yuan", "Miyabi").
	Name string `json:"name"`

	// Level is the current level of the Agent (1–60).
	Level int `json:"level"`

	// Promotion is the current Promotion (ascension) phase of the Agent (0–5).
	Promotion int `json:"promotion"`

	// MindscapeCinema is the unlocked Mindscape Cinema level of the Agent (0–6).
	MindscapeCinema int `json:"mindscape_cinema"`

	// CoreSkillEnhancement is the Core Skill Enhancement level of the Agent (0–6 / Core A–F).
	CoreSkillEnhancement int `json:"core_skill_enhancement"`

	// Attribute is the elemental combat damage type of the Agent (e.g. [AttributeIce], [AttributeEther]).
	Attribute Attribute `json:"attribute"`

	// AttributeName is the localized display name of the Agent's elemental attribute (e.g. "Ice", "Ether").
	AttributeName string `json:"attribute_name"`

	// Specialty is the combat role of the Agent (e.g. [SpecialtyAttack], [SpecialtyStun]).
	Specialty Specialty `json:"specialty"`

	// SpecialtyName is the localized display name of the Agent's combat specialty (e.g. "Attack", "Stun").
	SpecialtyName string `json:"specialty_name"`

	// Rarity is the rarity rank of the Agent ([RarityS] or [RarityA]).
	Rarity Rarity `json:"rarity"`

	// HighlightProps contains the recommended combat property IDs for this Agent
	// displayed on the agent's profile screen (e.g. [PropBaseATK], [PropBaseCritRate], [PropBasePENRatio]).
	// It is always initialized to a non-nil slice (empty [] if no recommendations exist).
	HighlightProps []PropertyID `json:"highlight_props"`

	// RecommendedSubStats contains the recommended Drive Disc sub-stat property IDs for this Agent
	// (e.g. [PropCritRate], [PropCritDMG], [PropATKPercent]).
	// These values reflect the official in-game Drive Disc recommendation system in Zenless Zone Zero
	// (matching the yellow highlight badges displayed on disc sub-stats in the equipment UI).
	// Used for Drive Disc sub-stat highlighting and calculating the in-game Active Modifier Count.
	// It is always initialized to a non-nil slice (empty [] if no recommendations exist).
	RecommendedSubStats []PropertyID `json:"recommended_sub_stats"`

	// Skin is the currently equipped cosmetic outfit. May be nil if default appearance is used.
	Skin *Skin `json:"skin"`

	// SplashArtURL is the absolute HTTPS URL pointing to the Agent's full splash art on the EnkaNetwork CDN.
	SplashArtURL string `json:"splash_art_url"`

	// Skills is the flat list of all individual combat abilities and passives.
	Skills []Skill `json:"skills"`

	// SkillGroups contains the Agent's skills categorized into 6 UI groups matching in-game skill tabs.
	SkillGroups []SkillGroup `json:"grouped_skills"`

	// Mindscapes contains all 6 [MindscapeNode] levels (Cinema 1–6) with their unlocked status.
	Mindscapes []MindscapeNode `json:"mindscapes"`

	// PotentialVision holds Potential Vision upgrade status and nodes (nil if Agent has no Potential Vision).
	PotentialVision *PotentialVision `json:"potential_vision"`

	// WEngine is the currently equipped W-Engine. May be nil if no weapon is equipped.
	WEngine *WEngine `json:"w_engine"`

	// DriveDiscs holds the equipped Drive Discs (slots 1–6) and active set bonuses.
	DriveDiscs DriveDiscs `json:"drive_discs"`

	// BaseStats contains the Agent's innate combat stats (Agent level growth + W-Engine Base ATK).
	BaseStats Stats `json:"base_stats"`

	// Stats contains the Agent's final calculated combat stats after applying all gear and buffs.
	Stats Stats `json:"stats"`

	// UIStats contains pre-formatted combat stat breakdowns (Base + Added = Total) with localized names and icons ready for frontend rendering.
	UIStats UIStats `json:"ui_stats"`
}

type Attribute string

type Avatar struct {
	// ID is the internal numeric identifier of the avatar asset.
	ID int `json:"id"`

	// URL is the absolute HTTPS URL pointing to the avatar's image asset on the EnkaNetwork CDN.
	URL string `json:"url"`
}

type Badge struct {
	// ID is the internal numeric identifier of the badge icon.
	ID int `json:"id"`

	// Title is the localized title/name of the badge achievement.
	Title string `json:"title"`

	// Value is the progression value or score associated with the badge.
	Value int `json:"value"`

	// IconURL is the absolute HTTPS URL pointing to the badge's visual icon on the EnkaNetwork CDN.
	IconURL string `json:"icon_url"`
}

type Client struct {
	// contains filtered or unexported fields
}

type DriveDisc struct {
	// ID is the internal numeric identifier of the specific disc variation.
	ID int `json:"id"`

	// UID is the unique instance identifier of this specific Drive Disc piece.
	UID string `json:"uid"`

	// Set is the Drive Disc [Set] metadata this disc belongs to.
	Set Set `json:"set"`

	// Slot is the equip partition slot position (1 to 6).
	Slot int `json:"slot"`

	// Level is the current upgrade level of the Drive Disc (0–15).
	Level int `json:"level"`

	// Rarity is the rarity rank of the disc ([RarityS], [RarityA], or [RarityB]).
	Rarity Rarity `json:"rarity"`

	// IconPath is the absolute HTTPS URL pointing to the disc's partition icon on the EnkaNetwork CDN.
	IconPath string `json:"icon_path"`

	// MainStat is the primary stat provided by this disc, scaled by disc level.
	MainStat StatValue `json:"main_stat"`

	// SubStats is the list of randomly rolled sub-stats (up to 4), including upgrade roll counts.
	SubStats []StatValue `json:"sub_stats"`
}

type DriveDiscSetBonus struct {
	// Set is the Drive Disc [Set] metadata (ID and localized name).
	Set Set `json:"set"`

	// Count is the total number of pieces from this set currently equipped on the Agent (e.g. 2, 4, 5).
	Count int `json:"count"`

	// Effects contains the 2-piece and 4-piece [SetEffect] thresholds with their activation status.
	Effects []SetEffect `json:"effects"`
}

type DriveDiscs struct {
	// Slots is the list of equipped [DriveDisc] pieces (up to 6 discs, partition slots 1–6).
	Slots []DriveDisc `json:"slots"`
	// SetBonuses is the list of active 2-piece and 4-piece Drive Disc set bonuses.
	SetBonuses []DriveDiscSetBonus `json:"set_bonuses"`
}

type FormattedStatBreakdown struct {
	// PropertyID is the strongly-typed [PropertyID] of the stat.
	PropertyID PropertyID `json:"property_id"`

	// Name is the localized display name of the stat.
	Name string `json:"name"`

	// Base is the pre-formatted innate base stat value.
	Base string `json:"base"`

	// Added is the pre-formatted added stat value from W-Engines, Drive Discs, and set bonuses.
	Added string `json:"added"`

	// Total is the pre-formatted final combat stat value.
	Total string `json:"total"`

	// IconURL is the base64 Data URI string containing the stat's SVG icon.
	IconURL string `json:"icon_url"`
}

type FormattedStats struct {
	// HP is the formatted Health Points string.
	HP string `json:"hp"`

	// ATK is the formatted Attack string.
	ATK string `json:"atk"`

	// DEF is the formatted Defense string.
	DEF string `json:"def"`

	// Impact is the formatted Impact string.
	Impact string `json:"impact"`

	// CritRate is the formatted Critical Rate percentage string (e.g. "50.0%").
	CritRate string `json:"crit_rate"`

	// CritDMG is the formatted Critical Damage percentage string (e.g. "150.0%").
	CritDMG string `json:"crit_dmg"`

	// AttributeDMGBonus is the formatted Attribute Damage Bonus percentage string (e.g. "30.0%").
	AttributeDMGBonus string `json:"attribute_dmg_bonus"`

	// AnomalyMastery is the formatted Anomaly Mastery string.
	AnomalyMastery string `json:"anomaly_mastery"`

	// AnomalyProficiency is the formatted Anomaly Proficiency string.
	AnomalyProficiency string `json:"anomaly_proficiency"`

	// PenRatio is the formatted Penetration Ratio percentage string (e.g. "24.0%").
	PenRatio string `json:"pen_ratio"`

	// PenFlat is the formatted Flat Penetration string.
	PenFlat string `json:"pen_flat"`

	// EnergyRegen is the formatted Energy Regeneration string (e.g. "1.20").
	EnergyRegen string `json:"energy_regen"`

	// SheerForce is the formatted Sheer Force string.
	SheerForce string `json:"sheer_force"`

	// SharpCritDMG is the formatted Laceration DMG string.
	SharpCritDMG string `json:"sharp_crit_dmg"`
}

type Language string

type MindscapeNode struct {
	// Rank is the Mindscape Cinema level (1 to 6).
	Rank int `json:"rank"`

	// Name is the localized name of the Mindscape Cinema node.
	Name string `json:"name"`

	// Description is the localized description text of the Mindscape Cinema node effect.
	Description string `json:"description"`

	// FormattedHTML is the web-ready HTML description with inline CSS colors.
	FormattedHTML string `json:"formatted_html,omitempty"`

	// Unlocked indicates whether this Mindscape Cinema node is unlocked on the Agent (MindscapeCinema >= Rank).
	Unlocked bool `json:"unlocked"`
}

type Namecard struct {
	// ID is the internal numeric identifier of the namecard asset.
	ID int `json:"id"`

	// URL is the absolute HTTPS URL pointing to the namecard's background asset on the EnkaNetwork CDN.
	URL string `json:"url"`
}

type Option func(*Options)

type Options struct {
	// DefaultLang specifies the default localization language used for profile enrichment.
	// Defaults to [LangEN] if not specified.
	DefaultLang Language

	// EnkaOpts specifies configuration settings for the underlying EnkaNetwork HTTP client,
	// such as custom HTTP transport, User-Agent, retry policies, and cache implementations.
	EnkaOpts zzz.Options
}

type PotentialVision struct {
	// IsUnlocked indicates whether the Potential Vision mechanic is unlocked.
	IsUnlocked bool `json:"is_unlocked"`

	// CurrentID is the currently active upgrade node ID.
	CurrentID int `json:"current_id"`

	// Nodes contains all Potential Vision upgrade nodes for the Agent.
	Nodes []PotentialVisionNode `json:"nodes"`
}

type PotentialVisionNode struct {
	// ID is the internal numeric identifier of the upgrade node.
	ID int `json:"id"`

	// Level is the level threshold of the node (1 to 6).
	Level int `json:"level"`

	// LevelName is the localized level title.
	LevelName string `json:"level_name"`

	// Title is the localized title of the upgrade effect.
	Title string `json:"title"`

	// Description is the localized effect description.
	Description string `json:"description"`

	// FormattedHTML is the web-ready HTML description with inline CSS colors.
	FormattedHTML string `json:"formatted_html,omitempty"`

	// IsActive indicates whether this upgrade node is currently active on the Agent.
	IsActive bool `json:"is_active"`
}

type Profile struct {
	// UID is the unique in-game identifier of the player (typically a 10-digit string).
	UID string `json:"uid"`

	// TTL indicates the remaining cache lifetime in seconds returned by the upstream EnkaNetwork API.
	// Making repeated requests before this TTL expires consumes rate limit quota without yielding newer game data.
	TTL int `json:"ttl"`

	// Nickname is the display name chosen by the player. Can be empty if omitted by upstream API.
	Nickname string `json:"nickname"`

	// InterknotLevel is the player's overall account progression level (Inter-Knot Level).
	InterknotLevel int `json:"interknot_level"`

	// Region is the game server region hosting the player's account.
	Region Region `json:"region"`

	// Title is the active achievement title equipped on the profile. May be nil if no title is equipped.
	Title *Title `json:"title"`

	// Avatar is the active profile picture equipped by the player. May be nil if none is set.
	Avatar *Avatar `json:"avatar"`

	// Namecard is the active profile background image (calling card). May be nil if none is set.
	Namecard *Namecard `json:"namecard"`

	// Badges is the list of collectible showcase medals displayed on the profile. May be empty.
	Badges []Badge `json:"badges"`

	// Agents is the list of up to 6 showcased [Agent] entries configured by the player in-game.
	// May be empty if the player's in-game showcase is empty or has details hidden.
	Agents []Agent `json:"agents"`
}

type PropertyID int

type Rarity string

type Region string

type Set struct {
	// ID is the unique numeric identifier of the Drive Disc set (see [SetID] constants, e.g. [SetWoodpeckerElectro]).
	ID SetID `json:"id"`

	// Name is the localized display name of the set (e.g. "Woodpecker Electro", "Polar Metal", "Fanged Metal").
	Name string `json:"name"`
}

type SetEffect struct {
	// PieceCount is the required piece count threshold (2 or 4).
	PieceCount int `json:"piece_count"`

	// Description is the localized description text of the set bonus effect.
	Description string `json:"description"`

	// FormattedHTML is the web-ready HTML description with inline CSS colors.
	FormattedHTML string `json:"formatted_html,omitempty"`

	// IsActive indicates whether this set effect is currently active on the Agent (Count >= PieceCount).
	IsActive bool `json:"is_active"`
}

type SetID int

type Skill struct {
	// Level is the current progression level of the skill.
	Level int `json:"level"`

	// Name is the localized display name of the skill.
	Name string `json:"name"`

	// Description is the localized description text with Unity Rich Text formatting and formula tags.
	Description string `json:"description"`

	// FormattedHTML is the web-ready HTML description with inline colors, icon tags, and evaluated formulas.
	FormattedHTML string `json:"formatted_html,omitempty"`

	// Type is the categorized [SkillType] of the skill (basic, dodge, assist, special, chain, passive).
	Type SkillType `json:"type"`

	// TypeName is the localized name of the skill category (e.g. "Basic Attack", "EX Special Attack").
	TypeName string `json:"type_name"`

	// Params is the list of calculated numeric parameters and multipliers evaluated for the skill's current level.
	Params []SkillParam `json:"params,omitempty"`
}

type SkillGroup struct {
	// Type is the group category key ([SkillTypeBasic], [SkillTypeSpecial], etc.).
	Type SkillType `json:"type"`

	// TypeName is the localized category tab name.
	TypeName string `json:"type_name"`

	// Level is the progression level of the group (1–12 for active skills, 0–6 for core passives).
	Level int `json:"level"`

	// Skills is the list of individual [Skill] abilities belonging to this category group tab.
	Skills []Skill `json:"skills"`
}

type SkillParam struct {
	// Name is the localized parameter label (e.g. "1-Hit DMG").
	Name string `json:"name"`

	// Value is the pre-formatted value string with level scaling evaluated (e.g. "124.5%").
	Value string `json:"value"`
}

type SkillType string

type Skin struct {
	// ID is the internal numeric identifier of the skin.
	ID int `json:"id"`

	// Name is the localized name of the skin.
	Name string `json:"name"`

	// Description is the localized lore or description of the skin.
	Description string `json:"description"`

	// SplashArtURL is the absolute HTTPS URL pointing to the skin's splash art on the EnkaNetwork CDN.
	SplashArtURL string `json:"splash_art_url"`
}

type Specialty string

type StatValue struct {
	// PropertyID is the internal strongly-typed [PropertyID] (e.g. [PropATKPercent]).
	PropertyID PropertyID `json:"property_id"`

	// Name is the localized display name of the stat (e.g. "ATK", "CRIT Rate").
	Name string `json:"name"`

	// Value is the calculated numerical value of the stat. Percentage stats are stored in decimal format (e.g. 0.048 for 4.8%).
	Value float64 `json:"value"`

	// IsPercent indicates whether the stat represents a percentage value.
	IsPercent bool `json:"is_percent"`

	// Rolls is the number of times this stat was upgraded (1 for base roll, up to 5 with upgrades).
	Rolls int `json:"rolls"`

	// IconURL is the base64 Data URI string ("data:image/svg+xml;base64,...") containing the stat's SVG icon.
	IconURL string `json:"icon_url"`
}

type Stats struct {
	// HP is the total Health Points.
	HP float64 `json:"hp"`

	// ATK is the total Attack.
	ATK float64 `json:"atk"`

	// DEF is the total Defense.
	DEF float64 `json:"def"`

	// Impact is the Impact stat (influences Daze accumulation rate).
	Impact float64 `json:"impact"`

	// CritRate is the Critical Hit Rate as a decimal fraction (e.g. 0.05 for 5%).
	CritRate float64 `json:"crit_rate"`

	// CritDMG is the Critical Hit Damage as a decimal fraction (e.g. 1.50 for 150%).
	CritDMG float64 `json:"crit_dmg"`

	// AttributeDMGBonus is the matching elemental Damage Bonus as a decimal fraction (e.g. 0.30 for 30%).
	AttributeDMGBonus float64 `json:"attribute_dmg_bonus"`

	// AnomalyMastery is the Anomaly Mastery stat (influences Anomaly Buildup speed).
	AnomalyMastery float64 `json:"anomaly_mastery"`

	// AnomalyProficiency is the Anomaly Proficiency stat (scales Anomaly damage).
	AnomalyProficiency float64 `json:"anomaly_proficiency"`

	// PenRatio is the Penetration Ratio as a decimal fraction (ignores a percentage of enemy DEF).
	PenRatio float64 `json:"pen_ratio"`

	// PenFlat is the flat Penetration stat (ignores a flat amount of enemy DEF).
	PenFlat float64 `json:"pen_flat"`

	// EnergyRegen is the Energy Regeneration rate per second (e.g. 1.20).
	EnergyRegen float64 `json:"energy_regen"`

	// SheerForce is the Sheer Force stat (damage multiplier for Rupture agents, ignoring DEF).
	SheerForce float64 `json:"sheer_force"`

	// SharpCritDMG is the Laceration DMG stat (damage multiplier for Armorer agents, scaling with DEF).
	SharpCritDMG float64 `json:"sharp_crit_dmg"`

	// EnergyPropertyID is the specific property ID for the agent's energy regeneration mechanism
	// (PropBaseEnergyRegen for standard agents, PropBaseRpRecover for Rupture, PropBaseEpRecover for Armorer).
	EnergyPropertyID PropertyID `json:"energy_property_id,omitempty"`
}

type Title struct {
	// ID is the internal numeric identifier of the title.
	ID int `json:"id"`

	// Text is the fully localized title text.
	Text string `json:"text"`

	// PrimaryColor is the 6-character hex color code for the starting gradient color (without #).
	PrimaryColor string `json:"primary_color"`

	// SecondaryColor is the 6-character hex color code for the ending gradient color (without #).
	SecondaryColor string `json:"secondary_color"`
}

type UIStats struct {
	// HP is the Health Points breakdown.
	HP FormattedStatBreakdown `json:"hp"`

	// ATK is the Attack breakdown.
	ATK FormattedStatBreakdown `json:"atk"`

	// DEF is the Defense breakdown.
	DEF FormattedStatBreakdown `json:"def"`

	// Impact is the Impact breakdown.
	Impact FormattedStatBreakdown `json:"impact"`

	// CritRate is the Critical Rate breakdown.
	CritRate FormattedStatBreakdown `json:"crit_rate"`

	// CritDMG is the Critical Damage breakdown.
	CritDMG FormattedStatBreakdown `json:"crit_dmg"`

	// AttributeDMGBonus is the matching elemental Damage Bonus breakdown.
	AttributeDMGBonus FormattedStatBreakdown `json:"attribute_dmg_bonus"`

	// AnomalyMastery is the Anomaly Mastery breakdown.
	AnomalyMastery FormattedStatBreakdown `json:"anomaly_mastery"`

	// AnomalyProficiency is the Anomaly Proficiency breakdown.
	AnomalyProficiency FormattedStatBreakdown `json:"anomaly_proficiency"`

	// PenRatio is the Penetration Ratio breakdown.
	PenRatio FormattedStatBreakdown `json:"pen_ratio"`

	// PenFlat is the Flat Penetration breakdown.
	PenFlat FormattedStatBreakdown `json:"pen_flat"`

	// EnergyRegen is the Energy Regeneration breakdown.
	EnergyRegen FormattedStatBreakdown `json:"energy_regen"`

	// SheerForce is the Sheer Force breakdown (for Rupture agents).
	SheerForce FormattedStatBreakdown `json:"sheer_force"`

	// SharpCritDMG is the Laceration DMG breakdown (for Armorer agents).
	SharpCritDMG FormattedStatBreakdown `json:"sharp_crit_dmg"`
}

type WEngine struct {
	// ID is the internal numeric identifier of the W-Engine.
	ID int `json:"id"`

	// UID is the unique instance identifier of this specific W-Engine.
	UID string `json:"uid"`

	// Name is the localized display name of the W-Engine (e.g. "Deep Sea Visitor", "The Brimstone").
	Name string `json:"name"`

	// Level is the current progression level of the W-Engine (1–60).
	Level int `json:"level"`

	// Phase is the ascension / star phase of the W-Engine (0–5).
	Phase int `json:"phase"`

	// Modification is the refinement level of the W-Engine's passive skill (1–5 / M1–M5).
	Modification int `json:"modification"`

	// Rarity is the rarity tier of the W-Engine ([RarityS], [RarityA], or [RarityB]).
	Rarity Rarity `json:"rarity"`

	// Specialty is the recommended combat role for this W-Engine (e.g. [SpecialtyAttack], [SpecialtyStun]).
	Specialty Specialty `json:"specialty"`

	// SpecialtyName is the localized display name of the intended specialty.
	SpecialtyName string `json:"specialty_name"`

	// IconURL is the absolute HTTPS URL pointing to the W-Engine's visual icon on the EnkaNetwork CDN.
	IconURL string `json:"icon_url"`

	// MainStat is the primary stat provided by the W-Engine ([PropBaseATK]), scaled by level and phase.
	MainStat StatValue `json:"main_stat"`

	// SecondaryStat is the secondary stat provided by the W-Engine (e.g. CRIT Rate, ATK%, PEN Ratio), scaled by level.
	SecondaryStat StatValue `json:"secondary_stat"`

	// PassiveDescription is the localized description text of the W-Engine's passive ability.
	PassiveDescription string `json:"passive_description"`

	// FormattedHTML is the web-ready HTML description with inline CSS colors and evaluated modification parameters.
	FormattedHTML string `json:"formatted_html,omitempty"`
}