@xmobitea/gn-typescript-client 2.6.13-tsc → 2.6.14

package/docs/guides/GROUP.md

@@ -0,0 +1,412 @@
+# GroupApi
+
+Tài liệu này dành cho AI code assistant và AI agent nội bộ. Mục tiêu là chọn đúng namespace `client/server/admin`, phân biệt đúng operation HTTP với event socket, và không sinh sai flow ở các nhóm member, message, currency, statistics, inventory và `infoRequestParam`.
+
+## 1. Scope
+
+- Áp dụng cho:
+  - `GNNetwork.group`
+  - `GNNetwork.group.server`
+  - `GNNetwork.group.admin`
+- Toàn bộ method hiện tại của `GroupApi` đều gửi qua HTTP.
+- `GroupApi` có đủ 3 role thật:
+  - `GNNetwork.group` -> `RequestRole.Client`
+  - `GNNetwork.group.server` -> `RequestRole.Server`
+  - `GNNetwork.group.admin` -> `RequestRole.Admin`
+- Nếu không truyền `overrideSecretKey`, SDK sẽ tự lấy secret key theo role tương ứng.
+- Chỉ dùng namespace `.server` khi bạn đã cấu hình `secretKey` với `permission rules` `server` hợp lệ trong `GNServerSettings`, hoặc chủ động truyền `overrideSecretKey`.
+- Chỉ dùng namespace `.admin` khi bạn đã cấu hình `secretKey` với `permission rules` `admin` hợp lệ trong `GNServerSettings`, hoặc chủ động truyền `overrideSecretKey`.
+- Rule chuẩn để chọn `client/server/admin` và hiểu `self/other-self` xem [RULES](../RULES.md#3-route--trust-boundary-của-caller). Không tự suy diễn route chỉ từ target ownership.
+- `GroupApi` thao tác trên group đã tồn tại. Không có public operation `createGroup`, `joinGroup`, `leaveGroup`, `removeGroup` trong nhóm này.
+- Realtime update của group là luồng riêng qua socket event, không phải transport của các method `GroupApi`.
+
+## 2. Hard Rules
+
+- Luôn ưu tiên `async/await`. Mặc định dùng `*Async()`.
+- Bắt buộc đã `GNNetwork.init(settings)` trước khi gọi.
+- Chọn namespace theo trust boundary:
+  - app/player -> `GNNetwork.group`
+  - trusted backend/service -> `GNNetwork.group.server`
+  - dashboard/ops/tooling -> `GNNetwork.group.admin`
+- Không được gọi `GroupApi` để tạo group hoặc join/leave group. Các flow đó nằm ở API player khác.
+- Toàn bộ operation trong `GroupApi` hiện đi qua HTTP, kể cả `sendGroupMessageAsync`.
+- Realtime update group tuân theo [rule socket chuẩn trong RULES](../RULES.md#7-auth--socket-flow).
+- `getGroupInformationAsync`, `getGroupsWithDisplayNameAsync`, `getGroupsWithSegmentAsync`, `getGroupsWithTagAsync`, `getStatisticsLeaderboardAroundGroupAsync`, `getStatisticsLeaderboardAsync`, `getCurrencyLeaderboardAsync` và `getCreateLeaderboardAsync` đều bắt buộc có `infoRequestParam`.
+- `getGroupStatisticsAsync` dùng `statisticsKeys`, còn `infoRequestParam` dùng `groupStatisticsKeys`. Không được dùng lẫn hai field này.
+- `getGroupDataAsync` dùng `groupDataKeys`, `getGroupCurrencyAsync` dùng `groupCurrencyKeys`, `getGroupInventoryAsync` dùng `itemCatalogIds`.
+- `getGroupMessageAsync` dùng `skip/limit`. `getCurrencyLogAsync` và `getStatisticsLogAsync` dùng `token`.
+- `sendGroupMessageAsync` bắt buộc có `senderId`. SDK không tự suy ra field này từ auth state.
+- `changeGroupCurrencyAsync` và `changeGroupStatisticsAsync` là delta change theo key, không phải set tuyệt đối.
+- `createGroupItemAsync` tạo item thuộc group, nhưng response hiện không expose `itemId` mới tạo.
+- `setAvatarAsync`, `GroupMessageResponseData.senderType` và `MemberItem.status` hiện là số thô; package không export enum public tương ứng để map an toàn.
+
+## 3. HTTP Và Socket
+
+Rule cứng:
+
+- Nếu cần đọc/ghi dữ liệu group: dùng `GNNetwork.group*` qua HTTP.
+- Nếu cần realtime member/message update: dùng event handler qua socket.
+- Không được giả định gọi `sendGroupMessageAsync` là đủ để nhận push message realtime.
+- Không được giả định socket event có đầy đủ dữ liệu như HTTP response.
+
+Event handler public: xem [reference/EVENTS.md](../reference/EVENTS.md#ongroupmessageupdateeventhandler) và [reference/EVENTS.md](../reference/EVENTS.md#ongroupmemberupdateeventhandler).
+
+Realtime rule:
+
+- `OnGroupMessageUpdateEventHandler.onUpdate`:
+  - payload có `groupId`
+  - có `groupMessages`
+  - có thể có `characterId` nếu người gửi là CharacterPlayer
+- `OnGroupMemberUpdateEventHandler.onUpdate`:
+  - payload có `groupId`
+  - payload có `members`
+
+## 4. Chọn Namespace
+
+| Namespace | Role thật | Dùng khi nào |
+| --- | --- | --- |
+| `GNNetwork.group` | `Client` | player app thao tác với group thuộc session hiện tại |
+| `GNNetwork.group.server` | `Server` | trusted backend, game server, worker xử lý group |
+| `GNNetwork.group.admin` | `Admin` | GM tool, dashboard, migration, vận hành dữ liệu group |
+
+Rule nhanh:
+
+- Nếu logic chạy trong client app: ưu tiên `GNNetwork.group`.
+- Nếu logic chạy trong backend tin cậy: ưu tiên `GNNetwork.group.server`.
+- Nếu thao tác quản trị hoặc vận hành dữ liệu: ưu tiên `GNNetwork.group.admin`.
+
+## 5. Chọn Method
+
+### Đọc 1 group hoặc 1 phần dữ liệu group
+
+| Method | Dùng khi nào | Cần truyền gì | Nhận được gì | Ghi chú | ErrorCode
+| --- | --- | --- | --- | --- | --- |
+| `getAvatarAsync` | Cần đọc avatar group | `groupId` | `GroupResponseData` | `avatar.type` hiện là số thô | `Ok`, `GroupNotFound` |
+| `getCatalogIdAsync` | Cần đọc `catalogId` | `groupId` | `GroupResponseData` | Kết quả ở `infoResponseParameters.catalogId` | `Ok`, `GroupNotFound` |
+| `getCustomDataAsync` | Cần đọc custom data | `groupId`, `customDataKeys?` | `GroupResponseData` | Có thể filter theo key | `Ok`, `GroupNotFound` |
+| `getDisplayNameAsync` | Cần đọc display name | `groupId` | `GroupResponseData` | Kết quả ở `infoResponseParameters.displayName` | `Ok`, `GroupNotFound` |
+| `getGroupCurrencyAsync` | Cần đọc group currencies | `groupId`, `groupCurrencyKeys?` | `GroupResponseData` | Có thể filter theo key | `Ok`, `GroupNotFound` |
+| `getGroupDataAsync` | Cần đọc group data | `groupId`, `groupDataKeys?` | `GroupResponseData` | Có thể filter theo key | `Ok`, `GroupNotFound` |
+| `getGroupInformationAsync` | Cần lấy nhiều field group trong một lần gọi | `groupId`, `infoRequestParam` | `GroupResponseData` | Flow đọc tổng hợp quan trọng nhất | `Ok`, `GroupNotFound` |
+| `getGroupInventoryAsync` | Cần đọc inventory của group | `groupId`, `itemCatalogIds?` | `GroupResponseData` | Không dùng `infoRequestParam` | `Ok`, `GroupNotFound` |
+| `getGroupStatisticsAsync` | Cần đọc group statistics theo key | `groupId`, `statisticsKeys?` | `GroupResponseData` | Không dùng `groupStatisticsKeys` ở đây | `Ok`, `GroupNotFound` |
+| `getMembersAsync` | Cần đọc danh sách member | `groupId` | `GroupResponseData` | Kết quả ở `infoResponseParameters.members` | `Ok`, `GroupNotFound` |
+| `getRemoveStatusAsync` | Cần đọc trạng thái remove | `groupId` | `GroupResponseData` | Kết quả ở `infoResponseParameters.removeStatus` | `Ok`, `GroupNotFound` |
+| `getSegmentAsync` | Cần đọc segment của group | `groupId` | `GroupResponseData` | Kết quả ở `infoResponseParameters.segments` | `Ok`, `GroupNotFound` |
+| `getTagAsync` | Cần đọc tag theo key | `groupId`, `tagKeys` | `GroupResponseData` | Không query theo value | `Ok`, `GroupNotFound` |
+| `getTsCreateAsync` | Cần đọc thời điểm tạo group | `groupId` | `GroupResponseData` | Kết quả ở `infoResponseParameters.tsCreate` | `Ok`, `GroupNotFound` |
+
+### Query danh sách, leaderboard, log và message history
+
+| Method | Dùng khi nào | Cần truyền gì | Nhận được gì | Ghi chú | ErrorCode
+| --- | --- | --- | --- | --- | --- |
+| `getGroupsWithDisplayNameAsync` | Tìm group theo tên hiển thị | `keyword`, `infoRequestParam`, `skip?`, `limit?` | `GroupsWithGroupIdResponseData` | `keyword` tối thiểu 2 ký tự | `Ok` |
+| `getGroupsWithSegmentAsync` | Tìm group theo segment | `value`, `infoRequestParam`, `skip?`, `limit?` | `GroupsWithGroupIdResponseData` | Query theo exact segment value | `Ok` |
+| `getGroupsWithTagAsync` | Tìm group theo tag | `key`, `value`, `infoRequestParam`, `skip?`, `limit?` | `GroupsWithGroupIdResponseData` | Query theo cặp `key/value` | `Ok`, `KeyNotFound` |
+| `getStatisticsLeaderboardAroundGroupAsync` | Cần bảng xếp hạng quanh một group cụ thể | `groupId`, `key`, `infoRequestParam`, `skip?`, `limit?`, `loadFromCache?`, `catalogId?` | `GetStatisticsLeaderboardResponseData` | Leaderboard theo statistics key | `Ok`, `KeyNotFound` |
+| `getStatisticsLeaderboardAsync` | Cần bảng xếp hạng statistics toàn cục theo key | `key`, `infoRequestParam`, `skip?`, `limit?`, `loadFromCache?`, `version?`, `catalogId?` | `GetStatisticsLeaderboardResponseData` | `version` chỉ có ở method này | `Ok`, `KeyNotFound`, `VersionInvalid` |
+| `getCurrencyLeaderboardAsync` | Cần bảng xếp hạng currency theo key | `key`, `infoRequestParam`, `skip?`, `limit?`, `loadFromCache?`, `catalogId?` | `GetCurrencyLeaderboardResponseData` | Không có `version` | `Ok`, `KeyNotFound` |
+| `getCreateLeaderboardAsync` | Cần bảng xếp hạng theo thời điểm tạo group | `infoRequestParam`, `skip?`, `limit?`, `loadFromCache?` | `GetCreateLeaderboardResponseData` | Không cần key | `Ok` |
+| `getStatisticsLogAsync` | Cần audit statistics log | `keys?`, `groupId?`, `limit?`, `token?` | `GetStatisticsLogResponseData` | Phân trang bằng `token` | `Ok` |
+| `getCurrencyLogAsync` | Cần audit currency log | `keys?`, `groupId?`, `limit?`, `token?` | `GetCurrencyLogResponseData` | Phân trang bằng `token` | `Ok` |
+| `getGroupMessageAsync` | Cần đọc lịch sử message | `groupId`, `skip?`, `limit?` | `GroupMessagesResponseData` | Phân trang bằng `skip/limit`, không phải `token` | `Ok`, `GroupNotFound`, `PlayerNotMember` |
+
+### Mutation
+
+| Method | Dùng khi nào | Cần truyền gì | Nhận được gì | Ghi chú | ErrorCode
+| --- | --- | --- | --- | --- | --- |
+| `addMemberAsync` | Thêm một user vào group | `userId`, `groupId` | `EmptyResponseData` | Chỉ thêm 1 member mỗi lần | `Ok`, `GroupNotFound`, `MemberNotFound` |
+| `removeMemberAsync` | Gỡ một user khỏi group | `userId`, `groupId` | `EmptyResponseData` | Không phải bulk remove | `Ok`, `GroupNotFound`, `MemberNotFound` |
+| `addSegmentAsync` | Gắn thêm segment cho group | `groupId`, `value` | `EmptyResponseData` | Thêm một segment value | `Ok`, `GroupNotFound` |
+| `removeSegmentAsync` | Gỡ một segment khỏi group | `groupId`, `value` | `EmptyResponseData` | Xóa theo exact value | `Ok`, `GroupNotFound` |
+| `setTagAsync` | Set hoặc upsert một tag | `groupId`, `key`, `value` | `EmptyResponseData` | Thao tác theo một cặp key/value | `Ok`, `KeyNotFound`, `GroupNotFound` |
+| `removeTagAsync` | Xóa tag theo key | `groupId`, `key` | `EmptyResponseData` | Không truyền `value` | `Ok`, `GroupNotFound` |
+| `setAvatarAsync` | Set avatar của group | `groupId`, `type`, `value` | `EmptyResponseData` | `type` chưa có enum public | `Ok`, `GroupNotFound` |
+| `setCustomDataAsync` | Set custom data của group | `groupId`, `customDatas[]` | `GroupResponseData` | Mỗi phần tử là `key/value` | `Ok`, `KeyNotFound`, `GroupNotFound` |
+| `setDisplayNameAsync` | Set display name | `groupId`, `displayName` | `EmptyResponseData` | Display name có min length 5 | `Ok`, `GroupNotFound` |
+| `setGroupDataAsync` | Set group data của group | `groupId`, `groupDatas[]` | `GroupResponseData` | Mỗi phần tử là `key/value` | `Ok`, `KeyNotFound`, `GroupNotFound` |
+| `changeGroupCurrencyAsync` | Cộng/trừ currency | `groupId`, `groupCurrencies[]`, `log?` | `GroupResponseData` | Đây là delta change | `Ok`, `NotEnoughCurrency`, `KeyNotFound`, `GroupNotFound` |
+| `changeGroupStatisticsAsync` | Cộng/trừ statistics | `groupId`, `groupStatistics[]`, `log?` | `GroupResponseData` | Đây là delta change | `Ok`, `KeyNotFound`, `GroupNotFound` |
+| `setRemoveStatusAsync` | Đánh dấu group bị remove | `groupId`, `reason?` | `EmptyResponseData` | Không phải hard delete | `Ok`, `GroupNotFound` |
+| `createGroupItemAsync` | Tạo inventory item thuộc group | `groupId`, `catalogId`, `classId`, `displayName?`, `amount?` | `GroupResponseData` | `amount` mặc định `1` | `Ok`, `CatalogIdNotFound`, `GroupNotFound`, `ClassIdNotFound` |
+| `removeGroupItemAsync` | Xóa item khỏi group theo `itemId` | `groupId`, `itemId` | `EmptyResponseData` | Dùng khi đã có `itemId` cụ thể | `Ok`, `ItemNotFound`, `GroupNotFound` |
+| `sendGroupMessageAsync` | Gửi message vào group | `senderId`, `groupId`, `message` | `GroupMessagesResponseData` | Operation là HTTP, không phải socket send | `Ok`, `GroupNotFound`, `PlayerNotMember` |
+
+## 6. Reference
+
+- DTO fields: [reference/dto/GROUP.md](../reference/dto/GROUP.md). Method table: [reference/API_GROUP.md](../reference/API_GROUP.md).
+- Events: [reference/EVENTS.md](../reference/EVENTS.md#ongroupmemberupdateeventhandler).
+- Enums: [GroupStatus](../reference/ENUMS.md#groupstatus).
+- Fallback `dist` chỉ khi reference docs chưa đủ: `dist/runtime/entity/models/Group*.d.ts`, `dist/runtime/entity/models/GenericModels.d.ts`.
+- Lưu ý:
+  - `GroupStatus` là enum publish có thật, nhưng `MemberItem.status` trong `GroupApi` không được ràng buộc bằng enum public riêng.
+  - `senderType`, `avatar.type` và `MemberItem.status` hiện vẫn là số thô trong public surface.
+
+## 7. InfoRequestParam Rules
+
+`GroupModels.InfoRequestParam` điều khiển payload trả về trong:
+
+- `getGroupInformationAsync`
+- `getGroupsWithDisplayNameAsync`
+- `getGroupsWithSegmentAsync`
+- `getGroupsWithTagAsync`
+- `getStatisticsLeaderboardAroundGroupAsync`
+- `getStatisticsLeaderboardAsync`
+- `getCurrencyLeaderboardAsync`
+- `getCreateLeaderboardAsync`
+
+Rule cứng:
+
+- Không truyền `null`.
+- Không bật toàn bộ field một cách mù quáng.
+- Chỉ bật field mà flow hiện tại thật sự cần.
+- Nếu cần filter dữ liệu con, dùng đúng field filter:
+  - `groupDataKeys`
+  - `groupCurrencyKeys`
+  - `groupStatisticsKeys`
+  - `customDataKeys`
+  - `tagKeys`
+  - `itemCatalogIds`
+- Nếu chỉ cần một mảng con riêng lẻ như members, group data, group currency, group statistics hoặc group inventory, ưu tiên getter chuyên biệt thay vì `getGroupInformationAsync`.
+
+Các field thường dùng:
+
+- `catalogId`
+- `members`
+- `removeStatus`
+- `segments`
+- `customDatas`
+- `displayName`
+- `avatar`
+- `tsCreate`
+- `tags`
+- `groupCurrencies`
+- `groupStatistics`
+- `groupDatas`
+- `groupInventories`
+
+## 8. Decision Rules
+
+- Cần đọc đúng một field nhỏ của group: ưu tiên getter chuyên biệt.
+- Cần lấy nhiều field group trong một lần gọi: dùng `getGroupInformationAsync`.
+- Cần search group theo tên: dùng `getGroupsWithDisplayNameAsync`.
+- Cần search group theo segment: dùng `getGroupsWithSegmentAsync`.
+- Cần search group theo tag: dùng `getGroupsWithTagAsync`.
+- Cần đọc member list: dùng `getMembersAsync`.
+- Cần đọc history message: dùng `getGroupMessageAsync`.
+- Cần gửi message: dùng `sendGroupMessageAsync`.
+- Cần realtime chat/member update: dùng socket event handler, không dùng polling giả làm realtime.
+- Cần cộng/trừ currency: dùng `changeGroupCurrencyAsync`.
+- Cần cộng/trừ statistics: dùng `changeGroupStatisticsAsync`.
+- Cần tạo item thuộc group: dùng `createGroupItemAsync`.
+- Cần audit currency/statistics: dùng `getCurrencyLogAsync` hoặc `getStatisticsLogAsync`.
+
+## 9. Response Rules
+
+Tất cả typed response của `GroupApi` đều có:
+
+- `returnCode`
+- `debugMessage`
+- `invalidMembers`
+- `errorCode`
+- `responseData`
+
+Rule kiểm tra response:
+
+```ts
+if (response.hasReturnCodeError()) {
+    throw new Error(response.debugMessage);
+}
+
+if (response.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${response.errorCode}`);
+}
+```
+
+Những response chính AI cần nhớ:
+
+- Hầu hết getter đơn lẻ trả `GroupResponseData` và dữ liệu nằm trong `responseData.infoResponseParameters`.
+- Các method list `getGroupsWith*Async` trả `responseData.results`, mỗi phần tử có `groupId` và `infoResponseParameters`.
+- `getStatisticsLeaderboardAroundGroupAsync` và `getStatisticsLeaderboardAsync` trả `responseData.results` có `groupId`, `position`, `backupValue?`, `infoResponseParameters`.
+- `getCurrencyLeaderboardAsync` và `getCreateLeaderboardAsync` trả `responseData.results`.
+- `getCurrencyLogAsync` và `getStatisticsLogAsync` trả `responseData.results` và có thể có `responseData.token`.
+- `getGroupMessageAsync` và `sendGroupMessageAsync` trả `responseData.groupMessages`, không phải `results`.
+- `addMemberAsync`, `addSegmentAsync`, `removeMemberAsync`, `removeSegmentAsync`, `removeTagAsync`, `setAvatarAsync`, `setDisplayNameAsync`, `setRemoveStatusAsync`, `setTagAsync`, `removeGroupItemAsync` trả `EmptyResponseData`.
+- `setCustomDataAsync`, `setGroupDataAsync`, `changeGroupCurrencyAsync`, `changeGroupStatisticsAsync`, `createGroupItemAsync` trả `GroupResponseData`.
+
+## 10. Cảnh Báo Implementation Hiện Tại
+
+- `AddSegmentRequestData.value` đang có `minLength: 6`, trong khi `RemoveSegmentRequestData.value` chỉ có `minLength: 2`.
+- Đây là validation không nhất quán trong model hiện tại.
+- `createGroupItemAsync` hiện trả `GroupResponseData`, không có contract public rõ ràng cho `itemId` mới tạo.
+- Nếu flow sau đó cần `itemId`, bạn phải đọc lại inventory hoặc xác minh backend contract riêng.
+- `OnGroupMemberUpdateEventHandler` theo public d.ts chỉ trả `members`, không có `groupId`.
+- Nếu UI của bạn đang theo dõi nhiều group cùng lúc, không được giả định event này tự cho biết group nào thay đổi.
+
+## 11. Best Practices
+
+- Dùng getter chuyên biệt khi chỉ cần một phần dữ liệu group.
+- Với query lớn, giữ `infoRequestParam` tối giản để giảm payload.
+- Với `getCurrencyLogAsync` và `getStatisticsLogAsync`, nên truyền ít nhất `keys` hoặc `groupId` trong production để tránh query quá rộng.
+- Với leaderboard, giữ `loadFromCache` mặc định nếu chấp nhận dữ liệu cache.
+- Với `changeGroupCurrencyAsync` và `changeGroupStatisticsAsync`, luôn truyền `log` nếu flow cần audit.
+- Với chat UI, dùng `getGroupMessageAsync` cho history và `OnGroupMessageUpdateEventHandler` cho push update.
+- Với member UI, dùng `getMembersAsync` cho initial state và `OnGroupMemberUpdateEventHandler` cho realtime update nếu có socket.
+- Với `sendGroupMessageAsync`, luôn truyền `senderId` đúng theo actor hiện tại; đừng giả định SDK tự nhét vào.
+
+## 12. Ví dụ Khuyến Nghị
+
+### Đọc group information với `infoRequestParam` tối giản
+
+```ts
+import {
+    ErrorCode,
+    GNNetwork,
+    GroupModels,
+} from "@xmobitea/gn-typescript-client";
+
+const infoRequestParam = new GroupModels.InfoRequestParam();
+infoRequestParam.displayName = true;
+infoRequestParam.members = true;
+infoRequestParam.groupCurrencies = true;
+infoRequestParam.groupCurrencyKeys = ["gold"];
+
+const request = new GroupModels.GetGroupInformationRequestData();
+request.groupId = "GROUP00001";
+request.infoRequestParam = infoRequestParam;
+
+const response = await GNNetwork.group.getGroupInformationAsync(request);
+
+if (response.hasReturnCodeError()) {
+    throw new Error(response.debugMessage);
+}
+
+if (response.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${response.errorCode}`);
+}
+
+const groupInfo = response.responseData.infoResponseParameters;
+```
+
+### Gửi message và nhận realtime update
+
+```ts
+import {
+    ErrorCode,
+    GNNetwork,
+    GroupModels,
+    OnGroupMessageUpdateEventHandler,
+} from "@xmobitea/gn-typescript-client";
+
+OnGroupMessageUpdateEventHandler.onUpdate = (update) => {
+    if (update.groupId !== "GROUP00001") {
+        return;
+    }
+
+    const pushedMessages = update.groupMessages;
+    console.log(pushedMessages);
+};
+
+GNNetwork.connectSocket(); // Follow README socket rule before expecting realtime updates.
+
+const request = new GroupModels.SendGroupMessageRequestData();
+request.senderId = "1234567890";
+request.groupId = "GROUP00001";
+request.message = "hello team";
+
+const response = await GNNetwork.group.sendGroupMessageAsync(request);
+
+if (response.hasReturnCodeError()) {
+    throw new Error(response.debugMessage);
+}
+
+if (response.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${response.errorCode}`);
+}
+
+const sentMessages = response.responseData.groupMessages;
+```
+
+### Tạo item cho group
+
+```ts
+import {
+    ErrorCode,
+    GNNetwork,
+    GroupModels,
+} from "@xmobitea/gn-typescript-client";
+
+const request = new GroupModels.CreateGroupItemRequestData();
+request.groupId = "GROUP00001";
+request.catalogId = "weapon";
+request.classId = "sword";
+request.displayName = "Guild Sword";
+request.amount = 1;
+
+const response = await GNNetwork.group.createGroupItemAsync(request);
+
+if (response.hasReturnCodeError()) {
+    throw new Error(response.debugMessage);
+}
+
+if (response.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${response.errorCode}`);
+}
+
+const groupInfo = response.responseData.infoResponseParameters;
+```
+
+### Đọc currency log với cursor
+
+```ts
+import {
+    ErrorCode,
+    GNNetwork,
+    GroupModels,
+} from "@xmobitea/gn-typescript-client";
+
+const request = new GroupModels.GetCurrencyLogRequestData();
+request.groupId = "GROUP00001";
+request.keys = ["gold"];
+request.limit = 20;
+
+const response = await GNNetwork.group.getCurrencyLogAsync(request);
+
+if (response.hasReturnCodeError()) {
+    throw new Error(response.debugMessage);
+}
+
+if (response.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${response.errorCode}`);
+}
+
+const logs = response.responseData.results;
+const nextToken = response.responseData.token;
+```
+
+## 13. Anti-Patterns
+
+- Không dùng `GroupApi` để create/join/leave/remove group nếu method đó không nằm trong public surface hiện tại.
+- Không dùng `getGroupInformationAsync` chỉ để đọc một field nhỏ nếu getter chuyên biệt đã có.
+- Không bỏ `infoRequestParam` ở các method bắt buộc.
+- Không dùng `groupStatisticsKeys` thay cho `statisticsKeys` hoặc ngược lại.
+- Không dùng `skip` để phân trang log.
+- Không dùng `token` để phân trang history message.
+- Không giả định `sendGroupMessageAsync` là socket operation.
+- Không giả định `sendGroupMessageAsync` tự lấy `senderId` từ auth state.
+- Không hardcode enum cho `senderType`, `member.status` hoặc `avatar.type` khi package chưa export enum public tương ứng.
+- Không giả định `createGroupItemAsync` trả `itemId` mới tạo.
+- Không bỏ qua kiểm tra `hasReturnCodeError()` và `errorCode`.
+
+## 14. AI Checklist
+
+- Đã `GNNetwork.init(settings)` chưa.
+- Có chọn đúng namespace `group` / `group.server` / `group.admin` chưa.
+- Có nhớ rằng operation của `GroupApi` hiện đi qua HTTP không.
+- Nếu flow cần realtime, đã tuân theo [rule socket chuẩn trong RULES](../RULES.md#7-auth--socket-flow) chưa.
+- Nếu đang gọi method có `infoRequestParam`, đã truyền object này chưa.
+- Nếu đang đọc statistics bằng getter chuyên biệt, có dùng đúng `statisticsKeys` chưa.
+- Nếu đang đọc history message, có dùng `skip/limit` chưa.
+- Nếu đang đọc currency/statistics log, có dùng `token` cho page tiếp chưa.
+- Nếu đang gửi message, có truyền `senderId` chưa.
+- Có kiểm tra `hasReturnCodeError()` trước `errorCode` chưa.