docs: align DataItems usage examples with server-side GameDataItemsEnum

Update helper docstring, helpers.md API reference, and the Sync/Async
get_game_data example scripts to use the server-accepted SEGMENT1-4
aggregates rather than raw single-collection bit values
(DataItems.UNITS, "UnitDefinitions"), which the Comlink server rejects
with HTTP 400.

Also adds a new "GameDataItems server alignment" section to the v1 to
v2 migration guide documenting the Segment2 and Segment4 aggregate
value changes and the new DataItems members (ABILITY_DECISION_TREE,
ERA_DEFINITION, UBS_UPDATE) introduced when re-syncing against the live
enum.

Fixes a pre-existing typo in the migration guide where the
Constants.get Segment1 example was annotated as returning '206158430208'
(Segment3's value) instead of '2097151'.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MarTrepodi

docs/api/helpers.md

@@ -22,16 +22,23 @@ from swgoh_comlink.helpers import DataItems
 
 comlink = SwgohComlink()
 
-# Single collection
-units = comlink.get_game_data(items=DataItems.UNITS)
+# Single segment (server-accepted)
+segment1 = comlink.get_game_data(items=DataItems.SEGMENT1)
 
-# Multiple collections via addition
-data = comlink.get_game_data(items=DataItems.SKILL + DataItems.EQUIPMENT)
+# Multiple segments combined
+data = comlink.get_game_data(items=DataItems.SEGMENT1 + DataItems.SEGMENT2)
 
 # All collections
 everything = comlink.get_game_data(items=DataItems.ALL)
 ```
 
+!!! note
+    Comlink servers validate `items` against the server-side `GameDataItemsEnum`. They
+    accept the `SEGMENT1`–`SEGMENT4` aggregates and `DataItems.ALL`, but may reject raw
+    single-collection bit values (e.g. `DataItems.UNITS`) with an HTTP 400. Prefer the
+    segment aggregates for `get_game_data()` calls. The single-bit members remain useful
+    for inspecting / composing custom bitfields and for `Constants.get()` lookups.
+
 Use `DataItems.members()` to list all available member names.
 
 ::: swgoh_comlink.helpers._data_items.DataItems

docs/migration.md

@@ -159,15 +159,17 @@ from swgoh_comlink.helpers import Constants
 # All three forms still work:
 Constants.get("UnitDefinitions")  # -> '137438953472' (legacy name)
 Constants.get("UNITS")            # -> '137438953472' (DataItems name)
-Constants.get("Segment1")         # -> '206158430208' (class attribute)
+Constants.get("Segment1")         # -> '2097151' (class attribute)
 ```
 
-**Recommendation:** Prefer using `DataItems` enum values directly for type safety:
+**Recommendation:** Prefer using `DataItems` enum values directly for type safety, and
+use the segment aggregates (`SEGMENT1`–`SEGMENT4`) when calling `get_game_data()` — see
+[GameDataItems server alignment](#9-gamedataitems-server-alignment) below:
 
 ```python
 from swgoh_comlink.helpers import DataItems
 
-items = DataItems.UNITS | DataItems.CATEGORY
+items = DataItems.SEGMENT1 + DataItems.SEGMENT2
 data = comlink.get_game_data(items=items)
 ```
 
@@ -263,6 +265,41 @@ default to `None`.
    brackets in parallel batches via `asyncio.gather`. No code changes are needed
    on your side — the return format is identical.
 
+## 9. GameDataItems server alignment
+
+`DataItems` and `Constants` were re-synced against the live `GameDataItemsEnum` that
+`get_enums()` now exposes. Two practical impacts:
+
+**`Segment2` and `Segment4` aggregate values changed.** If you hardcoded the integers
+in your own code (rather than referencing the constants by name), update them:
+
+| Constant | Old value | New value |
+|----------|-----------|-----------|
+| `DataItems.SEGMENT2` / `Constants.Segment2` | `68717379584` | `1125968624222208` |
+| `DataItems.SEGMENT4` / `Constants.Segment4` | `281200098803712` | `3377424842620928` |
+
+`SEGMENT1` (`2097151`) and `SEGMENT3` (`206158430208`) are unchanged.
+
+Code that references the constant by name (`DataItems.SEGMENT2`, `Constants.Segment2`,
+`Constants.get("Segment2")`) picks up the new values automatically.
+
+**`get_game_data(items=...)` now requires server-accepted values.** Comlink servers
+validate `items` against the server-side `GameDataItemsEnum` and may reject raw
+single-collection bit values with an HTTP 400. Prefer the `SEGMENT1`–`SEGMENT4`
+aggregates and `DataItems.ALL`:
+
+```diff
+- comlink.get_game_data(items=DataItems.UNITS)
++ comlink.get_game_data(items=DataItems.SEGMENT1)
+```
+
+The single-bit `DataItems` members (e.g. `UNITS`, `SKILL`, `EQUIPMENT`) remain useful
+for inspecting / composing custom bitfields and for `Constants.get()` lookups.
+
+**New members added** (from the live `GameDataItemsEnum`): `ABILITY_DECISION_TREE`,
+`ERA_DEFINITION`, `UBS_UPDATE`. New legacy-name aliases: `AbilityDecisionTrees`,
+`EraDefinitions`, `UBSUpdate`, `EpisodeDefinitions` (plural), `AccountLinking`.
+
 ## Summary of changes
 
 | Area | Before (v1.x) | After |
@@ -281,3 +318,6 @@ default to `None`.
 | `get_gac_brackets(limit=)` | Sentinel default | `int` default `0` (0 = no limit) |
 | GAC bracket scanning | Linear O(n) | Exponential probe + binary search O(log n) |
 | Migration checker | Not available | `swgoh-migrate` CLI / `python -m swgoh_comlink.migrate` |
+| `DataItems.SEGMENT2` value | `68717379584` | `1125968624222208` (server-aligned) |
+| `DataItems.SEGMENT4` value | `281200098803712` | `3377424842620928` (server-aligned) |
+| `get_game_data(items=)` single-bit values | Accepted | Rejected (HTTP 400); use segment aggregates |

examples/Async/get_game_data.py

@@ -7,7 +7,7 @@
 import asyncio
 
 from swgoh_comlink import SwgohComlinkAsync
-from swgoh_comlink.helpers import Constants
+from swgoh_comlink.helpers import Constants, DataItems
 
 
 async def main():
@@ -16,13 +16,15 @@ async def main():
         # Retrieve all of the available game data
         game_data = await cl.get_game_data(items="ALL")
 
-        # Alternatively, retrieve only the unit information collection
-        unit_data = await cl.get_game_data(items="UnitDefinitions")
+        # Retrieve a single segment. The Comlink server validates `items` against its
+        # GameDataItemsEnum and accepts the Segment1-4 aggregates; raw single-collection
+        # bit values (e.g. DataItems.UNITS) may be rejected with an HTTP 400.
+        segment1_data = await cl.get_game_data(items=DataItems.SEGMENT1)
 
-        # This is the same call as above but without the PVE units
-        unit_data_no_pve = await cl.get_game_data(items="UnitDefinitions", include_pve_units=False)
+        # The same call without the PVE units
+        segment1_no_pve = await cl.get_game_data(items=DataItems.SEGMENT1, include_pve_units=False)
 
-        # If you want to get more than one collection at once, simply combine the collection values
+        # Combine segments to request multiple collections at once
         game_data_segments_1_and_2 = await cl.get_game_data(items=Constants.Segment1 + Constants.Segment2)
 
         # Note that the 'items' and legacy 'request_segment' parameters are mutually exclusive.

examples/Sync/get_game_data.py

@@ -5,21 +5,23 @@
 """
 
 from swgoh_comlink import SwgohComlink
-from swgoh_comlink.helpers import Constants
+from swgoh_comlink.helpers import Constants, DataItems
 
 # Create an instance of SwgohComlink
 cl = SwgohComlink()
 
 # Retrieve all of the available game data
 game_data = cl.get_game_data(items="ALL")
 
-# Alternatively, retrieve only the unit information collection
-unit_data = cl.get_game_data(items="UnitDefinitions")
+# Retrieve a single segment. The Comlink server validates `items` against its
+# GameDataItemsEnum and accepts the Segment1-4 aggregates; raw single-collection
+# bit values (e.g. DataItems.UNITS) may be rejected with an HTTP 400.
+segment1_data = cl.get_game_data(items=DataItems.SEGMENT1)
 
-# This is the same call as above but without the PVE units
-unit_data_no_pve = cl.get_game_data(items="UnitDefinitions", include_pve_units=False)
+# The same call without the PVE units
+segment1_no_pve = cl.get_game_data(items=DataItems.SEGMENT1, include_pve_units=False)
 
-# If you want to get more than one collection at once, simply combine the collection values
+# Combine segments to request multiple collections at once
 game_data_segments_1_and_2 = cl.get_game_data(items=Constants.Segment1 + Constants.Segment2)
 
 # Note that the 'items' and legacy 'request_segment' parameters are mutually exclusive.

src/swgoh_comlink/helpers/_data_items.py

@@ -16,9 +16,14 @@ class DataItems(IntFlag):
     more than one collection in a single call.
 
     Examples:
-        effect = comlink.get_game_data(items=DataItems.EFFECT)
-        skill_equipment = comlink.get_game_data(items=(DataItems.SKILL + DataItems.EQUIPMENT))
-        units_no_pve = comlink.get_game_data(items=DataItems.UNITS, include_pve_units=False)
+        segment1 = comlink.get_game_data(items=DataItems.SEGMENT1)
+        segments_1_and_2 = comlink.get_game_data(items=(DataItems.SEGMENT1 + DataItems.SEGMENT2))
+        segment3_no_pve = comlink.get_game_data(items=DataItems.SEGMENT3, include_pve_units=False)
+
+    Note:
+        Comlink servers validate `items` against the server-side `GameDataItemsEnum` and may reject
+        raw single-collection bit values (e.g. `DataItems.UNITS`) with an HTTP 400. The `SEGMENT1`–
+        `SEGMENT4` aggregates (and `DataItems.ALL`) are the values the server explicitly accepts.
 
     Some of the DataItems members are actually aliases for other members. For example, the `TABLE` member is an
     alias for the `XP_TABLE` member. This is done because both members represent the same collection in the game data.