docs(earnings): document renderer packet contract

docs/earnings-packet-contract.md

@@ -0,0 +1,90 @@
+# Earnings Center Packet Contract
+
+This document is the emulator-side contract for the "Guadagni" UI.
+
+## Incoming
+
+### `RequestEarningsCenterEvent`
+
+- Header: `9308`
+- Body: empty
+- Response: `EarningsCenterComposer`
+
+### `ClaimEarningsRewardEvent`
+
+- Header: `9309`
+- Body:
+  - `String categoryKey`
+- Response: `EarningsClaimResultComposer`
+
+### `ClaimAllEarningsRewardsEvent`
+
+- Header: `9310`
+- Body: empty
+- Response: `EarningsClaimResultComposer`
+
+## Outgoing
+
+### `EarningsCenterComposer`
+
+- Header: `9407`
+- Body:
+  - `int entryCount`
+  - repeated entry:
+    - `String categoryKey`
+    - `boolean enabled`
+    - `boolean claimable`
+    - `int nextClaimAt`
+    - `int rewardCount`
+    - repeated reward:
+      - `String type`
+      - `int amount`
+      - `int pointsType`
+      - `String data`
+
+### `EarningsClaimResultComposer`
+
+- Header: `9408`
+- Body:
+  - `int resultCount`
+  - repeated result:
+    - `String categoryKey`
+    - `String status`
+    - `boolean success`
+    - `boolean hasEntry`
+    - entry body when `hasEntry=true`, same shape as `EarningsCenterComposer`
+
+## Categories
+
+- `daily_gift`
+- `games`
+- `achievements`
+- `marketplace`
+- `hc_payday`
+- `level_progress`
+- `donations`
+- `bonus_bag`
+- `mystery_boxes`
+- `club_job`
+
+## Reward Types
+
+- `credits`
+- `pixels`
+- `points`
+- `badge`
+- `item`
+- `hc_days`
+
+For `points`, `pointsType` carries the currency type. For `badge`, `data` carries the badge code. For `item`, `data` carries the `items_base.id`. Other reward types keep `data` empty.
+
+## Result Status
+
+- `success`
+- `disabled`
+- `unknown_category`
+- `already_claimed`
+- `no_reward`
+- `error`
+
+The client must not send reward amounts. Claim eligibility and rewards are always server authoritative.