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

package/docs/guides/MULTIPLAYER.md

@@ -0,0 +1,303 @@
+# MultiplayerApi
+
+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`, gọi đúng sequence matchmaking, và không nhầm `MultiplayerApi` với flow socket realtime.
+
+## 1. Scope
+
+- Áp dụng cho:
+  - `GNNetwork.multiplayer`
+  - `GNNetwork.multiplayer.server`
+  - `GNNetwork.multiplayer.admin`
+- Toàn bộ method hiện tại của `MultiplayerApi` đều gửi qua HTTP.
+- `MultiplayerApi` có đủ 3 role thật:
+  - `GNNetwork.multiplayer` -> `RequestRole.Client`
+  - `GNNetwork.multiplayer.server` -> `RequestRole.Server`
+  - `GNNetwork.multiplayer.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 semantics permission xem [RULES](../RULES.md#3-route--trust-boundary-của-caller). Với nhóm này, không tự suy diễn route chỉ từ target ownership.
+- `MultiplayerApi` xử lý matchmaking ticket, queue statistics và dữ liệu match. Nó không thay thế socket transport của SDK.
+
+## 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.
+- Không dùng socket để tạo, join, cancel hay query matchmaking ticket. Tất cả wrapper hiện tại đều là HTTP.
+- Nếu code chạy trong game client, ưu tiên `GNNetwork.multiplayer`.
+- Nếu code chạy ở trusted backend/worker, ưu tiên `GNNetwork.multiplayer.server`.
+- Nếu code chạy ở dashboard/tool vận hành, ưu tiên `GNNetwork.multiplayer.admin`.
+- Với `server` và `admin`, một số operation thao tác theo user khác bắt buộc có `userId`.
+- `createMatchmakingTicketAsync` không trả match ngay; nó chỉ trả `ticketId`.
+- `joinMatchmakingTicketAsync` và `cancelMatchmakingTicketAsync` trả `EmptyResponseData`; muốn biết state mới phải gọi API query tiếp.
+- Không giả định `GetMatchResponseData` có IP/port server. Model hiện tại của response không expose `ServerDetail`.
+
+## 3. Chọn Namespace
+
+| Namespace | Role thật | Dùng khi nào |
+| --- | --- | --- |
+| `GNNetwork.multiplayer` | `Client` | player app tự thao tác ticket của chính user hiện tại |
+| `GNNetwork.multiplayer.server` | `Server` | backend service thao tác ticket/match của user cụ thể |
+| `GNNetwork.multiplayer.admin` | `Admin` | dashboard, GM tool, vận hành |
+
+Rule nhanh:
+
+- Nếu thao tác gắn với auth token hiện tại của player: dùng `GNNetwork.multiplayer`.
+- Nếu backend/admin cần thao tác ticket của user khác: dùng `server` hoặc `admin`.
+- Với `server/admin`, nếu model có thêm `userId` thì phải truyền.
+
+## 4. Chọn Method
+
+| Method | Dùng khi nào | Cần truyền gì | Nhận được gì | Ghi chú | ErrorCode
+| --- | --- | --- | --- | --- | --- |
+| `createMatchmakingTicketAsync` | Tạo ticket mới để bắt đầu matchmaking | `giveUpAfterSeconds`, `queueName`, `attribute?`, `members?` | `CreateMatchmakingTicketResponseData` | Trả `ticketId`; với `server/admin` cần thêm `userId` | `Ok`, `MatchmakingPlayerJoinedOtherTicket`, `MatchmakingQueueNotFound`, `TicketSizeError` |
+| `joinMatchmakingTicketAsync` | Thêm user vào ticket đã tồn tại | `ticketId`, `attribute?` | `EmptyResponseData` | Với `server/admin` cần thêm `userId` | `Ok`, `MatchmakingTicketNotFound`, `MatchmakingTicketAlreadyCompleted`, `MatchmakingPlayerJoinedOtherTicket`, `MatchmakingQueueNotFound` |
+| `cancelMatchmakingTicketAsync` | Hủy 1 ticket cụ thể | `ticketId` | `EmptyResponseData` | Với `server/admin` cần thêm `userId` | `Ok`, `MatchmakingTicketNotFound`, `MatchmakingTicketAlreadyCompleted`, `MatchmakingPlayerNotJoinedTicket` |
+| `cancelAllMatchmakingTicketAsync` | Hủy toàn bộ ticket của 1 queue | `queueName` | `CancelAllMatchmakingTicketResponseData` | Với `server/admin` cần thêm `userId`; response trả `ticketIds` | `Ok`, `MatchmakingQueueNotFound` |
+| `getMatchmakingTicketAsync` | Poll trạng thái ticket cụ thể | `ticketId`, `returnMember?` | `GetMatchmakingTicketResponseData` | Khi `status` đổi sang matched có thể có `matchId` | `Ok`, `MatchmakingTicketNotFound` |
+| `listMatchmakingTicketsForPlayerAsync` | Liệt kê ticket của user trong một queue | `queueName` | `ListMatchmakingTicketsForPlayerResponseData` | Với `server/admin` cần thêm `userId` | `Ok`, `MatchmakingQueueNotFound` |
+| `getMatchAsync` | Lấy chi tiết 1 match theo `matchId` | `matchId`, `returnMember?` | `GetMatchResponseData` | Không giả định có server endpoint | `Ok`, `MatchNotFound` |
+| `getAllMatchAsync` | Liệt kê match hiện có | `returnMember?`, `skip?`, `limit?` | `GetAllMatchResponseData` | Dùng cho admin/ops/listing | `Ok` |
+| `getAllMatchmakingTicketAsync` | Liệt kê ticket hiện có | `status?`, `returnMember?`, `skip?`, `limit?` | `GetAllMatchmakingTicketResponseData` | `status` nên map bằng enum | `Ok` |
+| `getQueueStatisticsAsync` | Lấy thống kê queue trong một time window | `queueName`, `timeInSeconds` | `GetQueueStatisticsResponseData` | `timeInSeconds >= 20` | `Ok`, `MatchmakingQueueNotFound` |
+
+## 5. Matchmaking Sequence
+
+### Flow chuẩn cho client
+
+1. `createMatchmakingTicketAsync(...)`
+2. Lấy `ticketId`
+3. Poll `getMatchmakingTicketAsync(...)`
+4. Khi `status` cho biết đã match và response có `matchId`, gọi `getMatchAsync(...)`
+
+### Flow join ticket đã có
+
+1. `joinMatchmakingTicketAsync(...)`
+2. Poll `getMatchmakingTicketAsync(...)`
+3. Khi có `matchId`, gọi `getMatchAsync(...)`
+
+### Flow hủy
+
+1. `cancelMatchmakingTicketAsync(...)` hoặc `cancelAllMatchmakingTicketAsync(...)`
+2. Nếu cần xác nhận state hiện tại, gọi `getMatchmakingTicketAsync(...)` hoặc `listMatchmakingTicketsForPlayerAsync(...)`
+
+Rule cứng:
+
+- Không chờ `createMatchmakingTicketAsync` trả match data.
+- Không chờ `joinMatchmakingTicketAsync` trả ticket state mới.
+- Không bỏ bước poll nếu flow của bạn cần biết đã match hay chưa.
+
+## 6. Request Rules và Reference
+
+- DTO fields: [reference/dto/MULTIPLAYER.md](../reference/dto/MULTIPLAYER.md). Method table: [reference/API_MULTIPLAYER.md](../reference/API_MULTIPLAYER.md).
+- Enums: [MatchmakingTicketStatus](../reference/ENUMS.md#matchmakingticketstatus), [MatchmakingMemberStatus](../reference/ENUMS.md#matchmakingmemberstatus).
+- Fallback `dist` chỉ khi reference docs chưa đủ: `dist/runtime/entity/models/Multiplayer*.d.ts`.
+- `CreateMatchmakingTicketRequestData.giveUpAfterSeconds` có min `20`.
+- `GetQueueStatisticsRequestData.timeInSeconds` có min `20`.
+- `queueName` có min `6`, max `32`.
+- `ticketId` có độ dài `10`.
+- `matchId` có độ dài `15`.
+- `GetAllMatchmakingTicketRequestData.status` là numeric field tùy chọn; nên map bằng `MatchmakingTicketStatus`, không đoán số bừa.
+- `returnMember` mặc định là `false`; chỉ bật khi thật sự cần member list.
+- Với `server/admin`, các model sau có thêm `userId`:
+  - `createMatchmakingTicket`
+  - `joinMatchmakingTicket`
+  - `cancelMatchmakingTicket`
+  - `cancelAllMatchmakingTicket`
+  - `listMatchmakingTicketsForPlayer`
+
+## 7. Response Rules
+
+Tất cả typed response của `MultiplayerApi` đề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ớ:
+
+- `createMatchmakingTicketAsync` trả `responseData.ticketId`.
+- `cancelAllMatchmakingTicketAsync` trả `responseData.ticketIds`.
+- `getMatchmakingTicketAsync` trả `responseData.matchmakingTicket`.
+- `getMatchAsync` trả `responseData.match`.
+- `getQueueStatisticsAsync` trả `pendingMemberCount`, `pendingTicketCount`, `averageMatchmakingTimeInSeconds`.
+- `getAllMatchAsync` trả `results`.
+- `getAllMatchmakingTicketAsync` trả `results`.
+- `cancelMatchmakingTicketAsync` và `joinMatchmakingTicketAsync` trả `EmptyResponseData`.
+
+Ghi chú quan trọng:
+
+- `MatchmakingTicketResponseData.status` nên đọc bằng enum `MatchmakingTicketStatus`.
+- `MatchmakingTicketMember.status` nên đọc bằng enum `MatchmakingMemberStatus`.
+- `GetMatchResponseData.match` hiện chỉ có `tsCreate`, `queueName`, `members?`, `timeToMatchInSeconds`; không có server IP/port trong response model hiện tại.
+
+## 8. Decision Rules
+
+- Muốn bắt đầu tìm trận: dùng `createMatchmakingTicketAsync`.
+- Muốn ghép thêm player vào ticket đang có: dùng `joinMatchmakingTicketAsync`.
+- Muốn xem ticket đã matched chưa: dùng `getMatchmakingTicketAsync`.
+- Đã có `matchId` và muốn lấy match detail: dùng `getMatchAsync`.
+- Muốn xem tất cả ticket của current player trong queue: dùng `listMatchmakingTicketsForPlayerAsync`.
+- Muốn xem snapshot queue hiện tại: dùng `getQueueStatisticsAsync`.
+- Muốn duyệt toàn bộ ticket hoặc match để vận hành: dùng `getAllMatchmakingTicketAsync` hoặc `getAllMatchAsync`.
+- Muốn hủy một ticket: dùng `cancelMatchmakingTicketAsync`.
+- Muốn hủy hàng loạt ticket trong queue: dùng `cancelAllMatchmakingTicketAsync`.
+
+## 9. Best Practices
+
+- Giữ `returnMember = false` nếu bạn chỉ cần status hoặc id.
+- Chỉ truyền `members` khi bạn thật sự tạo ticket cho nhiều member ngay từ đầu.
+- Với `server/admin`, truyền `userId` rõ ràng thay vì kỳ vọng auth token ngầm chỉ tới user đích.
+- Poll `getMatchmakingTicketAsync` với nhịp hợp lý, không spam quá dày.
+- Khi cần filter ticket theo status, dùng enum `MatchmakingTicketStatus` thay vì hardcode số.
+- Không suy diễn `GetMatchResponseData` là đủ để connect game server. Nếu bạn cần endpoint runtime, phải xác minh từ API/flow khác.
+
+## 10. Ví dụ Khuyến Nghị
+
+### Client tạo ticket rồi poll tới khi có match
+
+```ts
+import {
+    ErrorCode,
+    GNNetwork,
+    MultiplayerModels,
+    MatchmakingTicketStatus,
+} from "@xmobitea/gn-typescript-client";
+
+const createRequest = new MultiplayerModels.CreateMatchmakingTicketRequestData();
+createRequest.giveUpAfterSeconds = 60;
+createRequest.queueName = "ranked01";
+
+const createResponse = await GNNetwork.multiplayer.createMatchmakingTicketAsync(createRequest);
+
+if (createResponse.hasReturnCodeError()) {
+    throw new Error(createResponse.debugMessage);
+}
+
+if (createResponse.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${createResponse.errorCode}`);
+}
+
+const ticketId = createResponse.responseData.ticketId;
+
+const ticketRequest = new MultiplayerModels.GetMatchmakingTicketRequestData();
+ticketRequest.ticketId = ticketId;
+
+const ticketResponse = await GNNetwork.multiplayer.getMatchmakingTicketAsync(ticketRequest);
+
+if (ticketResponse.hasReturnCodeError()) {
+    throw new Error(ticketResponse.debugMessage);
+}
+
+if (ticketResponse.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${ticketResponse.errorCode}`);
+}
+
+const ticket = ticketResponse.responseData.matchmakingTicket;
+if (ticket.status === MatchmakingTicketStatus.Matched && ticket.matchId) {
+    const matchRequest = new MultiplayerModels.GetMatchRequestData();
+    matchRequest.matchId = ticket.matchId;
+
+    const matchResponse = await GNNetwork.multiplayer.getMatchAsync(matchRequest);
+
+    if (matchResponse.hasReturnCodeError()) {
+        throw new Error(matchResponse.debugMessage);
+    }
+
+    if (matchResponse.errorCode !== ErrorCode.Ok) {
+        throw new Error(`Business error: ${matchResponse.errorCode}`);
+    }
+
+    const match = matchResponse.responseData.match;
+}
+```
+
+### Server tạo ticket cho user cụ thể
+
+```ts
+import {
+    ErrorCode,
+    GNNetwork,
+    MultiplayerModels,
+} from "@xmobitea/gn-typescript-client";
+
+const request = new MultiplayerModels.ServerCreateMatchmakingTicketRequestData();
+request.userId = "1234567890";
+request.giveUpAfterSeconds = 60;
+request.queueName = "ranked01";
+
+const response = await GNNetwork.multiplayer.server.createMatchmakingTicketAsync(request);
+
+if (response.hasReturnCodeError()) {
+    throw new Error(response.debugMessage);
+}
+
+if (response.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${response.errorCode}`);
+}
+
+const ticketId = response.responseData.ticketId;
+```
+
+### Admin list ticket theo status
+
+```ts
+import {
+    ErrorCode,
+    GNNetwork,
+    MultiplayerModels,
+    MatchmakingTicketStatus,
+} from "@xmobitea/gn-typescript-client";
+
+const request = new MultiplayerModels.AdminGetAllMatchmakingTicketRequestData();
+request.status = MatchmakingTicketStatus.WaitingForMatch;
+request.limit = 20;
+request.returnMember = false;
+
+const response = await GNNetwork.multiplayer.admin.getAllMatchmakingTicketAsync(request);
+
+if (response.hasReturnCodeError()) {
+    throw new Error(response.debugMessage);
+}
+
+if (response.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${response.errorCode}`);
+}
+
+const tickets = response.responseData.results;
+```
+
+## 11. Anti-Patterns
+
+- Không dùng socket để tạo hoặc query matchmaking ticket.
+- Không chờ `createMatchmakingTicketAsync` trả match object.
+- Không hardcode numeric status nếu enum đã có.
+- Không giả định `GetMatchResponseData` có IP/port server.
+- Không bỏ qua `userId` ở namespace `server/admin` khi model yêu cầu.
+- Không bật `returnMember` cho mọi request nếu không cần.
+- Không bỏ qua kiểm tra `returnCode` và `errorCode`.
+
+## 12. AI Checklist
+
+- Đã `GNNetwork.init(settings)` chưa.
+- Có chọn đúng namespace `multiplayer` / `multiplayer.server` / `multiplayer.admin` chưa.
+- Có nhớ rằng `MultiplayerApi` hiện chỉ đi qua HTTP không.
+- Nếu đang tạo ticket, có hiểu rằng response chỉ trả `ticketId` không.
+- Nếu cần biết đã matched chưa, có poll `getMatchmakingTicketAsync` chưa.
+- Nếu đang ở `server/admin`, model hiện tại có yêu cầu `userId` không.
+- Nếu đang lọc status, có dùng enum `MatchmakingTicketStatus` không.
+- Có tránh giả định response match sẽ trả server endpoint không.

package/docs/guides/STORE_INVENTORY.md

@@ -0,0 +1,313 @@
+# StoreInventoryApi
+
+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`, dùng đúng enum cho store flow, và không sinh sai request ở các nhóm mua/quà/receipt/log.
+
+## 1. Scope
+
+- Áp dụng cho:
+  - `GNNetwork.storeInventory`
+  - `GNNetwork.storeInventory.server`
+  - `GNNetwork.storeInventory.admin`
+- Toàn bộ method hiện tại của `StoreInventoryApi` đều gửi qua HTTP.
+- `StoreInventoryApi` có đủ 3 role thật:
+  - `GNNetwork.storeInventory` -> `RequestRole.Client`
+  - `GNNetwork.storeInventory.server` -> `RequestRole.Server`
+  - `GNNetwork.storeInventory.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 semantics permission xem [RULES](../RULES.md#3-route--trust-boundary-của-caller). Với nhóm này, không tự suy diễn route chỉ từ target ownership.
+- Khác với `MultiplayerApi`, namespace `server/admin` ở đây không thêm field `userId`; payload shape giữa 3 role hiện gần như giống nhau.
+
+## 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.
+- Không dùng socket cho `StoreInventoryApi`.
+- Không hardcode số cho `storeItemType`, `storeReceiveTypes` hoặc `type` nếu enum đã có.
+- `getStoreItemInformationAsync`, `getStoreItemsWithTagAsync` và `getCreateLeaderboardAsync` đều bắt buộc có `infoRequestParam`.
+- `getStoreLogAsync` dùng `token` để phân trang tiếp, không dùng `skip`.
+- `createStoreItemAsync` có `storeId` optional; nếu bạn bỏ trống, backend có thể tự sinh `storeId`.
+- `removeStoreUsedAsync` có `ownerIds` optional; nếu chưa có backend spec rõ ràng, không được bỏ trống trường này một cách mù quáng.
+
+## 3. Chọn Namespace
+
+| Namespace | Role thật | Dùng khi nào |
+| --- | --- | --- |
+| `GNNetwork.storeInventory` | `Client` | client/player mua item hoặc đọc store catalog cho chính session hiện tại |
+| `GNNetwork.storeInventory.server` | `Server` | trusted backend, server worker, purchase fulfillment |
+| `GNNetwork.storeInventory.admin` | `Admin` | dashboard, ops, GM tool, quản trị store |
+
+Rule nhanh:
+
+- Nếu flow mua/validate diễn ra từ player app: ưu tiên `GNNetwork.storeInventory`.
+- Nếu flow này chạy ở backend tin cậy: ưu tiên `GNNetwork.storeInventory.server`.
+- Nếu thao tác vận hành hoặc quản trị catalog/log: ưu tiên `GNNetwork.storeInventory.admin`.
+
+## 4. Chọn Method
+
+### Catalog và discovery
+
+| Method | Dùng khi nào | Cần truyền gì | Nhận được gì | Ghi chú | ErrorCode
+| --- | --- | --- | --- | --- | --- |
+| `createStoreItemAsync` | Tạo store item mới | `storeId?`, `displayName?` | `CreateStoreItemResponseData` | Nếu bỏ `storeId`, backend có thể sinh id | `Ok`, `StoreItemExists` |
+| `setStoreItemInformationAsync` | Cập nhật catalog, giá, IAP mapping, metadata | `storeId` và field cần đổi | `StoreInventoryResponseData` | `storeItemType` nên map bằng enum | `Ok`, `StoreItemNotFound`, `StoreInvalid` |
+| `setRemoveStatusAsync` | Đánh dấu remove/hide store item | `storeId`, `reason?` | `EmptyResponseData` | Thường dùng để disable item | `Ok`, `StoreItemNotFound` |
+| `getStoreItemInformationAsync` | Đọc chi tiết một store item | `storeId`, `infoRequestParam` | `StoreInventoryResponseData` | Chỉ bật field thật sự cần trong `infoRequestParam` | `Ok`, `StoreItemNotFound` |
+| `getStoreItemsWithTagAsync` | Tìm store item theo tag | `key`, `value`, `infoRequestParam`, `skip?`, `limit?` | `StoreInventoriesWithStoreIdResponseData` | Hữu ích cho listing/filter | `Ok` |
+| `getCreateLeaderboardAsync` | Lấy leaderboard create của store item | `infoRequestParam`, `skip?`, `limit?`, `loadFromCache?` | `GetCreateLeaderboardResponseData` | Response có `position` | `Ok` |
+
+### Purchase, gift và receipt
+
+| Method | Dùng khi nào | Cần truyền gì | Nhận được gì | Ghi chú | ErrorCode
+| --- | --- | --- | --- | --- | --- |
+| `buyStoreItemAsync` | Mua store item bằng flow nội bộ | `storeId`, `id`, `type`, `log?` | `BuyStoreInventoryResponseData` | `type` nên map bằng `OwnerType` | `Ok`, `NotEnoughCurrency`, `StoreItemNotFound`, `BuyerNotFound`, `CanNotBuyThisStoreItem`, `StoreItemRemoved`, `StoreItemPurchasedAndNonConsumable` |
+| `presentStoreItemAsync` | Tặng/phát store item | `storeId`, `id`, `type`, `log?` | `PresentStoreInventoryResponseData` | `type` nên map bằng `OwnerType` | `Ok`, `StoreItemNotFound`, `BuyerNotFound`, `StoreItemRemoved`, `StoreItemPurchasedAndNonConsumable` |
+| `validateAppleAppStoreReceiptAsync` | Validate receipt Apple và fulfill purchase | `receipt`, `id`, `type`, `log?` | `BuyStoreInventoryResponseData` | `type` nên map bằng `OwnerType` | `Ok`, `StoreItemNotFound`, `BuyerNotFound`, `ExceptionWhenValidateReceipt`, `StoreInvalid`, `ReceiptInvalid`, `StoreItemRemoved`, `StoreItemPurchasedAndNonConsumable` |
+| `validateFacebookStoreReceiptAsync` | Validate receipt Facebook và fulfill purchase | `receipt`, `id`, `type`, `log?` | `BuyStoreInventoryResponseData` | `type` nên map bằng `OwnerType` | `Ok`, `StoreItemNotFound`, `BuyerNotFound`, `ExceptionWhenValidateReceipt`, `StoreInvalid`, `ReceiptInvalid`, `StoreItemRemoved`, `StoreItemPurchasedAndNonConsumable` |
+| `validateGooglePlayStoreReceiptAsync` | Validate receipt Google Play và fulfill purchase | `receipt`, `id`, `type`, `log?` | `BuyStoreInventoryResponseData` | `type` nên map bằng `OwnerType` | `Ok`, `StoreItemNotFound`, `BuyerNotFound`, `ExceptionWhenValidateReceipt`, `StoreInvalid`, `ReceiptInvalid`, `StoreItemRemoved`, `StoreItemPurchasedAndNonConsumable` |
+
+### Audit và used state
+
+| Method | Dùng khi nào | Cần truyền gì | Nhận được gì | Ghi chú |
+| --- | --- | --- | --- | --- |
+| `getStoreLogAsync` | Đọc transaction log của store | `storeId?`, `storeReceiveTypes?`, `id?`, `limit?`, `token?` | `GetStoreLogResponseData` | `token` là cursor cho page tiếp |
+| `getStoreUsedAsync` | Xem owner nào đã dùng store item | `storeId` | `GetStoreUsedResponseData` | Trả list owner id/type |
+| `removeStoreUsedAsync` | Xóa used state của một hoặc nhiều owner | `storeId`, `ownerIds?` | `EmptyResponseData` | Chỉ gọi khi hiểu rõ hậu quả |
+
+## 5. Enum và Reference
+
+- DTO fields: [reference/dto/STORE_INVENTORY.md](../reference/dto/STORE_INVENTORY.md). Method table: [reference/API_STORE_INVENTORY.md](../reference/API_STORE_INVENTORY.md).
+- Enums: [StoreItemType](../reference/ENUMS.md#storeitemtype), [StoreReceiveType](../reference/ENUMS.md#storereceivetype), [OwnerType](../reference/ENUMS.md#ownertype).
+- Fallback `dist` chỉ khi reference docs chưa đủ: `dist/runtime/entity/models/StoreInventory*.d.ts`.
+- `SetStoreItemInformationRequestData.storeItemType` có range `1..2`, nên map bằng `StoreItemType`.
+- `GetStoreLogRequestData.storeReceiveTypes` nên map bằng `StoreReceiveType`.
+- `BuyStoreItemRequestData.type`, `PresentStoreItemRequestData.type` và các request validate receipt, là OwnerType; theo model/response hiện tại map bằng `OwnerType`.
+
+## 6. InfoRequestParam Rules
+
+`StoreInventoryModels.InfoRequestParam` điều khiển payload trả về trong:
+
+- `getStoreItemInformationAsync`
+- `getStoreItemsWithTagAsync`
+- `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à màn hình hoặc flow hiện tại thật sự cần.
+
+Các field thường dùng:
+
+- `storeItems`
+- `storeItemType`
+- `storeCurrencies`
+- `priceCurrencies`
+- `inAppPurchase`
+- `removeStatus`
+- `displayName`
+- `avatar`
+- `tsCreate`
+- `tags`
+- `storeDatas`
+
+## 7. Decision Rules
+
+- Cần tạo catalog item mới: dùng `createStoreItemAsync`, rồi nếu cần cấu hình chi tiết thì `setStoreItemInformationAsync`.
+- Cần lấy chi tiết một store item: dùng `getStoreItemInformationAsync`.
+- Cần listing theo tag: dùng `getStoreItemsWithTagAsync`.
+- Cần đánh dấu item bị remove/hide: dùng `setRemoveStatusAsync`.
+- Cần mua item theo flow nội bộ: dùng `buyStoreItemAsync`.
+- Cần tặng item: dùng `presentStoreItemAsync`.
+- Cần xác thực IAP receipt: dùng đúng method theo provider, không dùng chéo provider.
+- Cần audit transaction: dùng `getStoreLogAsync`.
+- Cần xem trạng thái used hoặc reset used: dùng `getStoreUsedAsync` và `removeStoreUsedAsync`.
+
+## 8. Response Rules
+
+Tất cả typed response của `StoreInventoryApi` đề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ớ:
+
+- `createStoreItemAsync` trả `responseData.storeId`.
+- `getStoreItemInformationAsync` trả `responseData.infoResponseParameters`.
+- `getStoreItemsWithTagAsync` trả `responseData.results`.
+- `setStoreItemInformationAsync` trả lại `StoreInventoryResponseData`.
+- `buyStoreItemAsync` và các method validate receipt trả `BuyStoreInventoryResponseData`.
+- `presentStoreItemAsync` trả `PresentStoreInventoryResponseData`.
+- `getCreateLeaderboardAsync` trả `results` có `position` và store info.
+- `getStoreLogAsync` trả `results` và có thể có `token` để gọi page tiếp.
+- `getStoreUsedAsync` trả `results`.
+
+### Cảnh báo implementation hiện tại
+
+- Trong model hiện tại, `BuyStoreInventoryResponseData.storeItems` và `PresentStoreInventoryResponseData.storeItems` đang được decorate bằng `ParameterCode.StoreCurrencies`.
+- Đây có thể là issue mapping của package hiện tại.
+- Nếu bạn phụ thuộc mạnh vào field `storeItems`, hãy verify runtime thực tế thay vì giả định deserialize luôn đúng.
+
+## 9. Best Practices
+
+- Dùng enum thay vì số thô cho `StoreItemType`, `StoreReceiveType`, `OwnerType`.
+- Với catalog query, giữ `infoRequestParam` tối giản.
+- Với receipt validation, luôn gọi đúng provider method theo source receipt.
+- Với `getStoreLogAsync`, dùng `token` để page tiếp thay vì tự suy diễn offset.
+- Với `removeStoreUsedAsync`, chỉ truyền `ownerIds` đã được xác nhận rõ.
+- Với `createStoreItemAsync`, nếu backend đã có convention sinh `storeId`, đừng tự phát minh format id mới trong client nếu không cần.
+
+## 10. Ví dụ Khuyến Nghị
+
+### Đọc store item với infoRequestParam tối giản
+
+```ts
+import {
+    ErrorCode,
+    GNNetwork,
+    StoreInventoryModels,
+} from "@xmobitea/gn-typescript-client";
+
+const infoRequestParam = new StoreInventoryModels.InfoRequestParam();
+infoRequestParam.displayName = true;
+infoRequestParam.priceCurrencies = true;
+infoRequestParam.storeItemType = true;
+
+const request = new StoreInventoryModels.GetStoreItemInformationRequestData();
+request.storeId = "store-item-001";
+request.infoRequestParam = infoRequestParam;
+
+const response = await GNNetwork.storeInventory.getStoreItemInformationAsync(request);
+
+if (response.hasReturnCodeError()) {
+    throw new Error(response.debugMessage);
+}
+
+if (response.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${response.errorCode}`);
+}
+
+const storeInfo = response.responseData.infoResponseParameters;
+```
+
+### Mua store item
+
+```ts
+import {
+    ErrorCode,
+    GNNetwork,
+    OwnerType,
+    StoreInventoryModels,
+} from "@xmobitea/gn-typescript-client";
+
+const request = new StoreInventoryModels.BuyStoreItemRequestData();
+request.storeId = "store-item-001";
+request.id = "1234567890";
+request.type = OwnerType.MasterPlayer;
+request.log = "buy from shop popup";
+
+const response = await GNNetwork.storeInventory.buyStoreItemAsync(request);
+
+if (response.hasReturnCodeError()) {
+    throw new Error(response.debugMessage);
+}
+
+if (response.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${response.errorCode}`);
+}
+
+const result = response.responseData;
+```
+
+### Validate Google Play receipt
+
+```ts
+import {
+    ErrorCode,
+    GNNetwork,
+    OwnerType,
+    StoreInventoryModels,
+} from "@xmobitea/gn-typescript-client";
+
+const request = new StoreInventoryModels.ValidateGooglePlayStoreReceiptRequestData();
+request.receipt = googleReceiptPayload;
+request.id = "1234567890";
+request.type = OwnerType.MasterPlayer;
+request.log = "google-play-checkout";
+
+const response = await GNNetwork.storeInventory.validateGooglePlayStoreReceiptAsync(request);
+
+if (response.hasReturnCodeError()) {
+    throw new Error(response.debugMessage);
+}
+
+if (response.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${response.errorCode}`);
+}
+```
+
+### Đọc store log với filter và cursor
+
+```ts
+import {
+    ErrorCode,
+    GNNetwork,
+    StoreInventoryModels,
+    StoreReceiveType,
+} from "@xmobitea/gn-typescript-client";
+
+const request = new StoreInventoryModels.GetStoreLogRequestData();
+request.storeId = "store-item-001";
+request.storeReceiveTypes = [StoreReceiveType.Buy, StoreReceiveType.GooglePlayStore];
+request.limit = 20;
+
+const response = await GNNetwork.storeInventory.getStoreLogAsync(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;
+```
+
+## 11. Anti-Patterns
+
+- Không hardcode số cho `storeItemType`, `storeReceiveTypes`, `type`.
+- Không bỏ `infoRequestParam` ở các method bắt buộc.
+- Không dùng receipt của provider này cho method validate của provider khác.
+- Không dùng `getStoreLogAsync` như offset pagination khi API đã có `token`.
+- Không bỏ trống `ownerIds` trong `removeStoreUsedAsync` nếu chưa hiểu backend sẽ xử lý thế nào.
+- Không giả định `storeItems` trong response buy/present luôn deserialize đúng nếu bạn chưa verify runtime.
+- Không bỏ qua kiểm tra `returnCode` và `errorCode`.
+
+## 12. AI Checklist
+
+- Đã `GNNetwork.init(settings)` chưa.
+- Có chọn đúng namespace `storeInventory` / `storeInventory.server` / `storeInventory.admin` chưa.
+- Có nhớ rằng `StoreInventoryApi` hiện chỉ đi qua HTTP không.
+- Nếu request có numeric enum field, có dùng enum export thay vì số thô không.
+- Nếu đang gọi `getStoreItemInformationAsync`, `getStoreItemsWithTagAsync` hoặc `getCreateLeaderboardAsync`, có truyền `infoRequestParam` chưa.
+- Nếu đang đọc log, có dùng `token` cho page tiếp chưa.
+- Nếu đang validate receipt, method có đúng provider không.
+- Có kiểm tra `hasReturnCodeError()` trước `errorCode` chưa.

package/docs/llms-full.txt

@@ -0,0 +1,43 @@
+llms-full.txt — optional generated bundle placeholder
+
+Status: deprecated-safe stub.
+
+This repository no longer treats this file as a primary AI reading source because
+stale concatenated bundles can preserve outdated examples and broken relative
+links. Use the source documents below instead; they are the canonical inputs.
+
+Canonical reading order:
+
+1. ../AGENTS.md
+2. AI_CHEATSHEET.md
+3. RULES.md
+4. ai-manifest.json
+5. reference/API_INDEX.md
+6. guides/<DOMAIN>.md for the target domain
+7. reference/dto/<DOMAIN>.md or grep reference/DTO_INDEX.md for DTO fields
+8. dist/**/*.d.ts only when docs do not cover the public contract
+
+Conflict rule:
+
+- Cross-cutting route, permission, auth/socket, override, and error rules:
+  RULES.md wins.
+- Method signatures, DTO fields, and enum names:
+  reference/API_<GROUP>.md, reference/dto/<DOMAIN>.md, reference/ENUMS.md, then
+  dist/**/*.d.ts win.
+- This bundle placeholder never wins over source docs.
+
+Important direct links:
+
+- AI cheatsheet: AI_CHEATSHEET.md
+- Cross-cutting rules: RULES.md
+- Machine manifest: ai-manifest.json
+- API index: reference/API_INDEX.md
+- DTO index: reference/DTO_INDEX.md
+- Enums: reference/ENUMS.md
+- Config: reference/CONFIG.md
+- Events: reference/EVENTS.md
+- Error handling: reference/ERROR_HANDLING.md
+- Cookbook: COOKBOOK.md
+
+If a release needs a true full concatenated bundle again, regenerate it from the
+current source docs and include a generation timestamp plus source commit hash.