# Telemetry SDK Event Catalog

Phase 72.5.1.15 defines the SDK-facing event catalog for `maya-telemetry-sdk`.
The catalog policy is `v2-telemetry-sdk-event-catalog-v1`, and the
machine-readable contract lives at
`V2/ue/Build/Telemetry/v2-telemetry-sdk-event-catalog.json`.

The source vocabulary remains `GameEventTaxonomy_V2_Contract.json`. This catalog
maps each standard event to the Rust SDK topic constant, required payload
fields, example payload shape, and reliability mode used by producers.

## SDK Authoring Rules

- Construct events with
  `TelemetryEvent::new(TOPIC_*, session_id, unix_seconds)`.
- Populate required payload fields with `with_value`.
- Leave `TelemetrySdkConfig.validate_standard_topics` enabled for production
  clients.
- Do not emit `FORBIDDEN_PAYLOAD_FIELDS`: `account_id`, `email`, `ip_address`,
  `platform_user_id`, or `raw_log_line`.
- Send batches through the caller-provided `TelemetryTransport`; the SDK does
  not own sockets or background runtimes.

## Standard Event Catalog

| Event          | SDK constant                        | Topic                            | Reliability | Required payload fields                                                        |
| -------------- | ----------------------------------- | -------------------------------- | ----------- | ------------------------------------------------------------------------------ |
| Session Start  | `TOPIC_PLAYER_SESSION_STARTED`      | `v2.player.session.started`      | Reliable    | `account_id_hash`, `session_id`, `platform`, `build_id`                        |
| Session End    | `TOPIC_PLAYER_SESSION_ENDED`        | `v2.player.session.ended`        | Reliable    | `account_id_hash`, `session_id`, `duration_seconds`, `end_reason`              |
| Level Load     | `TOPIC_MATCH_LEVEL_LOADED`          | `v2.match.level.loaded`          | Reliable    | `session_id`, `level_id`, `level_load_id`, `load_time_ms`                      |
| Death          | `TOPIC_MATCH_PLAYER_DEATH`          | `v2.match.player.death`          | Reliable    | `match_id`, `account_id_hash`, `fighter_id`, `cause`                           |
| Achievement    | `TOPIC_PLAYER_ACHIEVEMENT_UNLOCKED` | `v2.player.achievement.unlocked` | Reliable    | `account_id_hash`, `achievement_id`, `unlock_source`, `unlocked_at`            |
| Purchase       | `TOPIC_COSMETIC_PURCHASED`          | `v2.cosmetic.purchased`          | Reliable    | `account_id_hash`, `item_id`, `currency`, `price_minor`                        |
| UI Interaction | `TOPIC_PLAYER_UI_INTERACTED`        | `v2.player.ui.interacted`        | BestEffort  | `account_id_hash`, `session_id`, `screen_id`, `element_id`, `interaction_type` |
| Error          | `TOPIC_PLAYER_ERROR_REPORTED`       | `v2.player.error.reported`       | ReleaseGate | `error_id`, `session_id`, `severity`, `category`, `build_id`                   |

## Example Payloads

Each example is intentionally minimal: producers may add optional fields through
the additive schema migration workflow, but the required fields below must
remain present.

```rust
let event = TelemetryEvent::new(TOPIC_PLAYER_SESSION_STARTED, "session-123", 1_717_171_717)
    .with_value("account_id_hash", "acct_hash_123")
    .with_value("session_id", "session-123")
    .with_value("platform", "Win64")
    .with_value("build_id", "dev-123");
```

Required example keys for the remaining catalog entries:

- `TOPIC_PLAYER_SESSION_ENDED`: `account_id_hash`, `session_id`,
  `duration_seconds`, `end_reason`
- `TOPIC_MATCH_LEVEL_LOADED`: `session_id`, `level_id`, `level_load_id`,
  `load_time_ms`
- `TOPIC_MATCH_PLAYER_DEATH`: `match_id`, `account_id_hash`, `fighter_id`,
  `cause`
- `TOPIC_PLAYER_ACHIEVEMENT_UNLOCKED`: `account_id_hash`, `achievement_id`,
  `unlock_source`, `unlocked_at`
- `TOPIC_COSMETIC_PURCHASED`: `account_id_hash`, `item_id`, `currency`,
  `price_minor`
- `TOPIC_PLAYER_UI_INTERACTED`: `account_id_hash`, `session_id`, `screen_id`,
  `element_id`, `interaction_type`
- `TOPIC_PLAYER_ERROR_REPORTED`: `error_id`, `session_id`, `severity`,
  `category`, `build_id`

## Verification

Targeted verification for this catalog is:

```bash
python V2/ue/Tools/check-v2-telemetry-sdk-event-catalog.py
python -m json.tool V2/ue/Build/Telemetry/v2-telemetry-sdk-event-catalog.json
```