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

package/docs/COOKBOOK.md

@@ -0,0 +1,912 @@
+# Cookbook
+
+16 scenario end-to-end phổ biến. Mỗi scenario có: problem, prerequisites, APIs used, code snippet, return path handling, pitfall.
+
+> Tất cả snippet dùng import từ package name `@xmobitea/gn-typescript-client`. Ví dụ dùng dạng `async/await` (form `*Async()`). Các comment trong snippet là điểm nối vào logic ứng dụng của bạn.
+
+## Index
+
+1. [Init SDK + bootstrap tối thiểu](#scenario-1-init-sdk--bootstrap-tối-thiểu)
+2. [Login by account + retrieve profile](#scenario-2-login-by-account--retrieve-profile)
+3. [Refresh token và persist session](#scenario-3-refresh-token-và-persist-session)
+4. [Login by social (Google/Apple/Facebook)](#scenario-4-login-by-social-googleapplefacebook)
+5. [Connect socket + handle reconnect](#scenario-5-connect-socket--handle-reconnect)
+6. [Subscribe friend updates](#scenario-6-subscribe-friend-updates)
+7. [Subscribe + send group message](#scenario-7-subscribe--send-group-message)
+8. [Group member lifecycle (join / leave / kick) + realtime update](#scenario-8-group-member-lifecycle-join--leave--kick--realtime-update)
+9. [Matchmaking ticket flow](#scenario-9-matchmaking-ticket-flow)
+10. [Inventory: query + grant item (server role)](#scenario-10-inventory-query--grant-item-server-role)
+11. [Store: list catalog → purchase → validate receipt](#scenario-11-store-list-catalog--purchase--validate-receipt)
+12. [CloudScript: execute function + customTags](#scenario-12-cloudscript-execute-function--customtags)
+13. [Override authToken / secret (impersonate, cross-role)](#scenario-13-override-authtoken--secret-impersonate-cross-role)
+14. [Admin login qua DashboardApi](#scenario-14-admin-login-qua-dashboardapi)
+15. [Cleanup & shutdown flow](#scenario-15-cleanup--shutdown-flow)
+16. [Diagnose `OperationNotAllow`](#scenario-16-diagnose-operationnotallow)
+
+---
+
+## Scenario 1: Init SDK + bootstrap tối thiểu
+
+**Problem:** Lần đầu khởi chạy ứng dụng — cần init SDK để bất kỳ API nào hoạt động.
+
+**Prerequisites:** biết server address/port và `secretKey` backend cấp.
+
+**APIs used:** `GNNetwork.init()`, `GNServerSettings`.
+
+Code mẫu đầy đủ (có comment từng field): [README § 4](../README.MD#4-khởi-tạo-cơ-bản). Minimal pattern: [AI_CHEATSHEET § 1](AI_CHEATSHEET.md#1-mandatory-pattern-sao-chép--dùng).
+
+### Return paths
+
+- `init()` là void và **idempotent** — gọi lần thứ 2 chỉ log warning rồi return.
+- Không có network call ở bước này; lỗi cấu hình thường gặp là gọi `settings.config({...})` thiếu field required trong `GNServerSettingsOptions`.
+
+### Pitfalls
+
+- `logType: LogType.All` trong production làm console spam. Dùng `LogType.Error` hoặc `LogType.Off`.
+- Gọi lại `GNNetwork.init()` để đổi settings không có hiệu lực. Setter trên cùng `settings` object sau init chỉ ảnh hưởng một số request mới và không tự reconnect socket.
+- Full anti-patterns: [RULES § 10](RULES.md#10-anti-patterns--pitfalls). Full field schema: [reference/CONFIG.md](reference/CONFIG.md).
+
+---
+
+## Scenario 2: Login by account + retrieve profile
+
+**Problem:** User nhập username/password → gọi login → nhận profile + cache auth token để request sau tự động attach.
+
+**Prerequisites:** đã `init()`.
+
+**APIs used:** [`GNNetwork.authenticate.loginByAccountAsync`](reference/API_AUTHENTICATE.md), [`AuthenticateModels.LoginByAccountRequestData`](reference/dto/AUTHENTICATE.md#loginbyaccountrequestdata), [`AuthenticateModels.InfoRequestParam`](reference/dto/AUTHENTICATE.md#inforequestparam).
+
+### Code
+
+```typescript
+import {
+  GNNetwork,
+  ReturnCode,
+  ErrorCode,
+  AuthenticateModels,
+} from "@xmobitea/gn-typescript-client";
+
+async function loginWithAccount(username: string, password: string) {
+  const infoRequestParam = new AuthenticateModels.InfoRequestParam();
+  infoRequestParam.displayName = true;
+  infoRequestParam.avatar = true;
+  infoRequestParam.playerCurrencies = true;
+  infoRequestParam.tsCreate = true;
+
+  const request = new AuthenticateModels.LoginByAccountRequestData();
+  request.username = username;
+  request.password = password;
+  request.infoRequestParam = infoRequestParam;
+
+  const res = await GNNetwork.authenticate.loginByAccountAsync(request);
+
+  if (res.returnCode !== ReturnCode.Ok) {
+    console.error("transport error", res.returnCode, res.debugMessage);
+    return null;
+  }
+  if (res.errorCode !== ErrorCode.Ok) {
+    console.warn("business error", res.errorCode, res.invalidMembers);
+    return null;
+  }
+
+  // AuthenticateApi success auto-caches authToken + userId into AuthenticateStatus/StorageService.
+  return res.responseData; // AuthenticateResponseData
+}
+```
+
+### Return paths
+
+- Happy: `ReturnCode.Ok` + `ErrorCode.Ok` → SDK cache `authToken` + `userId`; response có profile fields enabled trong `InfoRequestParam`.
+- `ReturnCode.OperationTimeout` (-1) → retry sau nếu idempotent.
+- `ErrorCode.AccountNotFound` (2) hoặc `ErrorCode.AccountPasswordWrong` → báo user.
+- `ReturnCode.InvalidRequestParameters` với `invalidMembers` → có field request sai format (ví dụ username < 6 chars).
+
+### Pitfalls
+
+- Đọc `responseData` trước khi check đủ 2 tầng → có thể dùng payload chưa đáng tin.
+- Set `infoRequestParam.customDatas = true` nhưng không set `customDataKeys` → backend có thể trả TẤT CẢ custom data, tốn bandwidth.
+- `username`/`password` < 6 ký tự → backend reject với `ReturnCode.InvalidRequestParameters` trước khi query DB.
+
+---
+
+## Scenario 3: Refresh token và persist session
+
+**Problem:** Token sắp hết hạn (hoặc user mở lại app sau 1 ngày) → refresh để lấy token mới, tránh bắt login lại.
+
+**Prerequisites:** đã có `authToken` cache từ lần login trước (stored ở `StorageService`).
+
+**APIs used:** [`GNNetwork.authenticate.refreshAuthTokenAsync`](reference/API_AUTHENTICATE.md).
+
+### Code
+
+```typescript
+import { GNNetwork, ReturnCode, ErrorCode, AuthenticateModels } from "@xmobitea/gn-typescript-client";
+
+async function ensureValidToken() {
+  // refreshAuthToken uses cached auth context — không cần truyền field nào
+  const res = await GNNetwork.authenticate.refreshAuthTokenAsync(
+    new AuthenticateModels.RefreshAuthTokenRequestData(),
+  );
+
+  if (res.returnCode !== ReturnCode.Ok) return false;
+  if (res.errorCode !== ErrorCode.Ok) return false;
+
+  return true;
+}
+
+// On app start:
+if (!(await ensureValidToken())) {
+  // redirect về login screen
+}
+```
+
+### Return paths
+
+- Happy → `authToken` mới được SDK cache, session tiếp tục.
+- `ReturnCode.OperationNotAuthorized` hoặc `ErrorCode.VerifyTokenError` → token cũ invalid/expired; cần login lại.
+- `ErrorCode.PlayerBan` → user bị ban; xem `res.responseData.playerBan` (BanItem với tsExpire + reason).
+
+### Pitfalls
+
+- Không có `authToken` cache → request gửi đi thiếu auth, reject.
+- Refresh thành công nhưng app vẫn dùng token tự lưu bên ngoài SDK → đồng bộ lại storage riêng của app từ `GNNetwork.getAuthenticateStatus()` nếu có.
+
+---
+
+## Scenario 4: Login by social (Google/Apple/Facebook)
+
+**Problem:** User chọn đăng nhập bằng Google (hoặc Apple, Facebook, Game Center, GooglePlayGameService …).
+
+**Prerequisites:** đã init; đã có ID token từ social SDK native.
+
+**APIs used:** `loginByGoogleAsync`, `loginByAppleAsync`, `loginByFacebookAsync`, `loginByGameCenterAsync`, `loginByGooglePlayGameServiceAsync` — cùng pattern. Xem [API_AUTHENTICATE.md](reference/API_AUTHENTICATE.md).
+
+### Code
+
+```typescript
+import {
+  GNNetwork,
+  ReturnCode,
+  ErrorCode,
+  AuthenticateModels,
+  GoogleLoginType,
+} from "@xmobitea/gn-typescript-client";
+
+async function loginWithGoogle(idToken: string) {
+  const infoRequestParam = new AuthenticateModels.InfoRequestParam();
+  infoRequestParam.displayName = true;
+  infoRequestParam.avatar = true;
+
+  const request = new AuthenticateModels.LoginByGoogleRequestData();
+  request.token = idToken;
+  request.type = GoogleLoginType.IdToken;
+  request.createPlayerIfNotExists = true;
+  request.infoRequestParam = infoRequestParam;
+
+  const res = await GNNetwork.authenticate.loginByGoogleAsync(request);
+
+  if (res.returnCode !== ReturnCode.Ok || res.errorCode !== ErrorCode.Ok) return null;
+
+  // AuthenticateApi success auto-caches authToken + userId.
+  if (res.responseData.newlyCreated) console.log("new player created");
+  return res.responseData;
+}
+```
+
+### Return paths
+
+- Happy → `authToken` + `newlyCreated` flag cho biết user mới hay đã tồn tại.
+- `ErrorCode.VerifyTokenError` hoặc `ErrorCode.VerifyFailed` → ID token social invalid/expired.
+- `ErrorCode.ExternalLinkedOtherAccount` hoặc `ErrorCode.ExternalLinkedOtherValue` → social id đã liên kết account khác.
+
+### Pitfalls
+
+- `createPlayerIfNotExists: false` với social id chưa từng login → `ErrorCode.AccountNotFound`. Set `true` cho flow "login hoặc register" tự động.
+- Apple ID token có lifetime rất ngắn; lấy xong phải call ngay.
+
+---
+
+## Scenario 5: Connect socket + handle reconnect
+
+**Problem:** Cần realtime event (group message, friend update, …) — phải connect socket.
+
+**Prerequisites:** đã login (có `authToken` cache); `useSocket: true` trong settings.
+
+**APIs used:** `GNNetwork.connectSocket`, `GNNetwork.sendRequestAuthSocket`, `GNNetwork.subscriberOnConnectHandler`, `GNNetwork.subscriberOnDisconnectHandler`.
+
+### Code
+
+```typescript
+import { GNNetwork } from "@xmobitea/gn-typescript-client";
+
+GNNetwork.subscriberOnConnectHandler(() => {
+  console.log("socket connected, sid=", GNNetwork.getSocketSId());
+  // SDK auto-auths the socket if an auth token is already cached.
+  // Call GNNetwork.sendRequestAuthSocket() manually only when login/token refresh happens after this connect.
+});
+
+GNNetwork.subscriberOnDisconnectHandler(() => {
+  console.warn("socket disconnected — SDK will auto-reconnect after reconnectDelay ms");
+});
+
+GNNetwork.connectSocket(() => {
+  // optional one-shot callback on first connect
+});
+```
+
+### Return paths
+
+- Connect thành công → `onConnect` callback fire; `isSocketConnected()` trả `true`.
+- Disconnect do network → SDK tự retry sau `reconnectDelay` (default 5000ms). Mỗi lần reconnect sẽ fire `onConnect` handler lại.
+
+### Pitfalls
+
+- Nếu socket connect trước khi login/token refresh, cần gọi `sendRequestAuthSocket()` sau khi token có trong cache để re-auth thủ công.
+- `subscriberOnConnectHandler` gắn MULTIPLE callback, mỗi lần reconnect đều fire tất cả. Dùng `unscriberOnConnectHandler` khi cleanup.
+- `connectSocket()` gọi trước `init()` → crash.
+
+---
+
+## Scenario 6: Subscribe friend updates
+
+**Problem:** Hiển thị UI danh sách bạn bè realtime (thêm/xóa/thay đổi status).
+
+**Prerequisites:** socket đã connected + authenticated (scenario 5).
+
+**APIs used:** [`OnGamePlayerFriendUpdateEventHandler`](reference/EVENTS.md#ongameplayerfriendupdateeventhandler).
+
+### Code
+
+```typescript
+import { OnGamePlayerFriendUpdateEventHandler, FriendStatus } from "@xmobitea/gn-typescript-client";
+
+OnGamePlayerFriendUpdateEventHandler.onUpdate = (payload) => {
+  // payload.playerFriends: Array<GenericModels.FriendItem>
+  for (const f of payload.playerFriends ?? []) {
+    switch (f.status) {
+      case FriendStatus.Friend: {
+        upsertFriendInUI(f);
+        break;
+      }
+      case FriendStatus.WaitingAccept:
+      case FriendStatus.SentRequestAndWaitingAccept: {
+        showFriendRequest(f);
+        break;
+      }
+      case FriendStatus.NotFriend: {
+        removeFriendFromUI(f.friendId);
+        break;
+      }
+    }
+  }
+};
+
+// Cleanup khi user logout hoặc navigate đi
+function unsubscribe() {
+  OnGamePlayerFriendUpdateEventHandler.onUpdate = () => {};
+}
+```
+
+### Return paths
+
+- Event fire mỗi khi friend relation thay đổi — hot path, đừng làm heavy work trong handler.
+- Không có ACK trả về; delivery là at-most-once khi socket up.
+
+### Pitfalls
+
+- `onUpdate` là field `static` — gán nhiều component sẽ **ghi đè lẫn nhau**, chỉ handler cuối cùng fire. Dùng wrapper pattern (xem [EVENTS.md](reference/EVENTS.md)) nếu cần fan-out.
+- Khi socket tạm mất kết nối → event trong interval đó KHÔNG được replay. App nên resync bằng `GNNetwork.gamePlayer.getFriendList*` sau reconnect.
+
+---
+
+## Scenario 7: Subscribe + send group message
+
+**Problem:** Chat trong group — lắng nghe message đến + gửi message đi.
+
+**Prerequisites:** đã login + connect socket + là member của `groupId`.
+
+**APIs used:** [`OnGroupMessageUpdateEventHandler`](reference/EVENTS.md#ongroupmessageupdateeventhandler), [`GNNetwork.group.sendGroupMessageAsync`](reference/API_GROUP.md).
+
+### Code
+
+```typescript
+import {
+  GNNetwork,
+  OnGroupMessageUpdateEventHandler,
+  ReturnCode,
+  ErrorCode,
+  GroupModels,
+} from "@xmobitea/gn-typescript-client";
+
+// 1. Subscribe incoming messages
+OnGroupMessageUpdateEventHandler.onUpdate = (payload) => {
+  if (payload.groupId !== currentGroupId) return;
+  for (const msg of payload.groupMessages ?? []) {
+    appendMessageToUI(msg);
+  }
+};
+
+// 2. Send a new message
+async function sendGroupChat(groupId: string, text: string) {
+  const request = new GroupModels.SendGroupMessageRequestData();
+  request.senderId = GNNetwork.getAuthenticateStatus().getUserId();
+  request.groupId = groupId;
+  request.message = text;
+
+  const res = await GNNetwork.group.sendGroupMessageAsync(request);
+
+  if (res.returnCode !== ReturnCode.Ok || res.errorCode !== ErrorCode.Ok) {
+    console.warn("send failed", res.errorCode, res.debugMessage);
+    return false;
+  }
+  return true;
+}
+```
+
+### Return paths
+
+- Response `sendGroupMessageAsync` trả về nhanh khi server đã nhận — event `OnGroupMessageUpdate` sẽ fire cho TẤT CẢ member trong group (bao gồm sender).
+- `ErrorCode.PlayerNotMember` hoặc `ReturnCode.OperationNotAllow` → user không phải member hoặc secret thiếu permission gửi message.
+- `ErrorCode.GroupNotFound` → `groupId` sai.
+
+### Pitfalls
+
+- Optimistic UI: nếu append message ngay sau khi gọi send thành công, và event handler cũng append → duplicate. Dùng messageId server trả về để dedupe.
+- Event `OnGroupMessageUpdate` có thể payload nhiều message cùng lúc (khi backend batch) — luôn lặp `payload.groupMessages`.
+
+---
+
+## Scenario 8: Group member lifecycle (join / leave / kick) + realtime update
+
+**Problem:** User join/leave group, và mọi member khác thấy roster update realtime.
+
+**Prerequisites:** đã login + connect socket.
+
+**APIs used:** `GNNetwork.gamePlayer.joinGroupAsync`, `GNNetwork.gamePlayer.leaveGroupAsync`, `GNNetwork.group.server.removeMemberAsync`, [`OnGroupMemberUpdateEventHandler`](reference/EVENTS.md#ongroupmemberupdateeventhandler).
+
+### Code
+
+```typescript
+import {
+  GNNetwork,
+  OnGroupMemberUpdateEventHandler,
+  ReturnCode,
+  ErrorCode,
+  GamePlayerModels,
+} from "@xmobitea/gn-typescript-client";
+
+OnGroupMemberUpdateEventHandler.onUpdate = (payload) => {
+  if (payload.groupId !== currentGroupId) return;
+  for (const m of payload.members ?? []) {
+    // MemberItem.status is backend-defined; update idempotently and resync roster after reconnect.
+    roster.upsert(m);
+  }
+};
+
+async function join(groupId: string) {
+  const request = new GamePlayerModels.JoinGroupRequestData();
+  request.groupId = groupId;
+
+  const res = await GNNetwork.gamePlayer.joinGroupAsync(request);
+  if (res.returnCode !== ReturnCode.Ok || res.errorCode !== ErrorCode.Ok) {
+    if (res.errorCode === ErrorCode.GroupNotFound) return "group_not_found";
+    return "error";
+  }
+  return "ok";
+}
+
+async function leave(groupId: string) {
+  const request = new GamePlayerModels.LeaveGroupRequestData();
+  request.groupId = groupId;
+
+  await GNNetwork.gamePlayer.leaveGroupAsync(request);
+}
+```
+
+### Return paths
+
+- Join OK → event `OnGroupMemberUpdate` fire với status `Joined`.
+- `ErrorCode.GroupNotFound`, `ErrorCode.GamePlayerNotFound`, `ErrorCode.PlayerBan`, hoặc `ReturnCode.OperationNotAllow` → xử lý theo context.
+
+### Pitfalls
+
+- `removeMember` là method `.server` namespace — chỉ call được nếu có `secretKey` có `permission rules` có `group.removeMember.serverSelfEnable`. Từ client thường expose qua CloudScript.
+
+---
+
+## Scenario 9: Matchmaking ticket flow
+
+**Problem:** User bấm "Find match" → enqueue ticket → poll status → vào match khi ghép xong.
+
+**Prerequisites:** đã login + connect socket.
+
+**APIs used:** `GNNetwork.multiplayer.createMatchmakingTicketAsync`, `getMatchmakingTicketAsync`, `cancelMatchmakingTicketAsync`. Xem [API_MULTIPLAYER.md](reference/API_MULTIPLAYER.md).
+
+### Code
+
+```typescript
+import {
+  GNNetwork,
+  ReturnCode,
+  ErrorCode,
+  GNHashtable,
+  MultiplayerModels,
+  MatchmakingTicketStatus,
+} from "@xmobitea/gn-typescript-client";
+
+async function findMatch(queueName: string) {
+  const createRequest = new MultiplayerModels.CreateMatchmakingTicketRequestData();
+  createRequest.queueName = queueName;
+  createRequest.giveUpAfterSeconds = 60;
+  createRequest.attribute = GNHashtable.builder().build();
+
+  const createRes = await GNNetwork.multiplayer.createMatchmakingTicketAsync(createRequest);
+  if (createRes.returnCode !== ReturnCode.Ok || createRes.errorCode !== ErrorCode.Ok) {
+    return null;
+  }
+  const ticketId = createRes.responseData.ticketId;
+
+  // Poll mỗi 2s cho tới khi matched hoặc timeout
+  for (let i = 0; i < 30; i++) {
+    await new Promise((r) => setTimeout(r, 2000));
+    const pollRequest = new MultiplayerModels.GetMatchmakingTicketRequestData();
+    pollRequest.ticketId = ticketId;
+    pollRequest.returnMember = true;
+
+    const poll = await GNNetwork.multiplayer.getMatchmakingTicketAsync(pollRequest);
+    if (poll.returnCode !== ReturnCode.Ok || poll.errorCode !== ErrorCode.Ok) continue;
+
+    const ticket = poll.responseData.matchmakingTicket;
+    const status = ticket.status;
+    if (status === MatchmakingTicketStatus.Matched) {
+      return ticket.matchId;
+    }
+    if (status === MatchmakingTicketStatus.Canceled) {
+      return null;
+    }
+  }
+
+  // Timeout: cancel ticket để queue không giữ slot
+  const cancelRequest = new MultiplayerModels.CancelMatchmakingTicketRequestData();
+  cancelRequest.ticketId = ticketId;
+
+  await GNNetwork.multiplayer.cancelMatchmakingTicketAsync(cancelRequest);
+  return null;
+}
+```
+
+### Return paths
+
+- `MatchmakingTicketStatus.Matched` → có `matchId`, chuyển sang scene game.
+- `WaitingForMembers`, `WaitingForMatch`, `WaitingForServer` → tiếp tục poll.
+- `Canceled` → abort.
+
+### Pitfalls
+
+- Không cancel khi user hủy → ticket vẫn trong queue, occupy slot tới khi server timeout.
+- Poll interval quá ngắn (<1s) → rate-limit reject.
+
+---
+
+## Scenario 10: Inventory query + grant item (server role)
+
+**Problem:** Client xem inventory; backend/CloudScript grant item cho player khác.
+
+**Prerequisites:** client login; `secretKey` có `permission rules` là `admin` hoặc `server` cấu hình ở backend/CloudScript.
+
+**APIs used:** [`GNNetwork.gamePlayer.getPlayerInventoryAsync`](reference/API_GAME_PLAYER.md) (client), `GNNetwork.gamePlayer.server.createPlayerItemAsync` (server).
+
+### Code
+
+```typescript
+import { GNNetwork, ReturnCode, ErrorCode, GamePlayerModels } from "@xmobitea/gn-typescript-client";
+
+// Client: xem inventory của chính mình
+async function loadMyInventory() {
+  const request = new GamePlayerModels.GetPlayerInventoryRequestData();
+  request.itemCatalogIds = ["weapon"];
+
+  const res = await GNNetwork.gamePlayer.getPlayerInventoryAsync(request);
+  if (res.returnCode !== ReturnCode.Ok || res.errorCode !== ErrorCode.Ok) return [];
+  return res.responseData.infoResponseParameters?.playerInventories ?? [];
+}
+
+// Server: create/grant 1 sword cho player targetUserId
+async function grantSword(targetUserId: string) {
+  const request = new GamePlayerModels.ServerCreatePlayerItemRequestData();
+  request.userId = targetUserId;
+  request.catalogId = "weapon";
+  request.classId = "sword_001";
+  request.displayName = "Starter Sword";
+  request.amount = 1;
+
+  const res = await GNNetwork.gamePlayer.server.createPlayerItemAsync(request);
+  return res.returnCode === ReturnCode.Ok && res.errorCode === ErrorCode.Ok;
+}
+```
+
+### Return paths
+
+- Client query → không truyền `userId` nên backend resolve inventory của game player đang authenticate.
+- Server grant → nếu `secretKey` sai/thiếu → `ReturnCode.SecretInvalid`; nếu secret hợp lệ nhưng thiếu flag → `ReturnCode.OperationNotAllow`.
+
+### Pitfalls
+
+- NÊN gọi `.server` trong backend Node service hoặc CloudScript.
+
+---
+
+## Scenario 11: Store list catalog → purchase → validate receipt
+
+**Problem:** User mở shop → chọn item → mua → xác nhận nhận hàng.
+
+**Prerequisites:** đã login.
+
+**APIs used:** [`GNNetwork.storeInventory.getStoreItemsWithTagAsync`](reference/API_STORE_INVENTORY.md), `buyStoreItemAsync`, `server.validateGooglePlayStoreReceiptAsync` / `server.validateAppleAppStoreReceiptAsync`.
+
+### Code
+
+```typescript
+import { GNNetwork, ReturnCode, ErrorCode, OwnerType, StoreInventoryModels } from "@xmobitea/gn-typescript-client";
+
+async function listCatalog() {
+  const infoRequestParam = new StoreInventoryModels.InfoRequestParam();
+  infoRequestParam.displayName = true;
+  infoRequestParam.tags = true;
+
+  const request = new StoreInventoryModels.GetStoreItemsWithTagRequestData();
+  request.key = "visible";
+  request.value = "true";
+  request.infoRequestParam = infoRequestParam;
+  request.skip = 0;
+  request.limit = 50;
+
+  const res = await GNNetwork.storeInventory.getStoreItemsWithTagAsync(request);
+  if (res.returnCode !== ReturnCode.Ok || res.errorCode !== ErrorCode.Ok) return [];
+  return res.responseData.results ?? [];
+}
+
+async function buyItem(storeItemId: string) {
+  const request = new StoreInventoryModels.BuyStoreItemRequestData();
+  request.storeId = storeItemId;
+  request.id = GNNetwork.getAuthenticateStatus().getUserId();
+  request.type = OwnerType.GamePlayer;
+  request.log = "shop_purchase";
+
+  const res = await GNNetwork.storeInventory.buyStoreItemAsync(request);
+
+  if (res.returnCode !== ReturnCode.Ok) return "transport_error";
+  switch (res.errorCode) {
+    case ErrorCode.Ok:
+      return "ok";
+    case ErrorCode.NotEnoughCurrency:
+      return "not_enough_currency";
+    case ErrorCode.StoreItemRemoved:
+    case ErrorCode.CanNotBuyThisStoreItem:
+      return "not_buyable";
+    default:
+      return "unhandled_" + res.errorCode;
+  }
+}
+```
+
+### Return paths
+
+- `ErrorCode.Ok` → item đã grant vào inventory player; currency đã trừ.
+- `ErrorCode.NotEnoughCurrency` (8) → cần topup.
+- `ErrorCode.StoreItemRemoved` hoặc `ErrorCode.CanNotBuyThisStoreItem` → item không còn mua được ở state hiện tại.
+
+### Pitfalls
+
+- In-app purchase (IAP) có receipt native — validate qua method cụ thể theo store, ví dụ `storeInventory.server.validateGooglePlayStoreReceiptAsync` hoặc `validateAppleAppStoreReceiptAsync`, trước khi tin kết quả grant.
+
+---
+
+## Scenario 12: CloudScript execute function + customTags
+
+**Problem:** Trigger function server-side custom (ví dụ "claim daily reward") từ client.
+
+**Prerequisites:** đã login; CloudScript function đã publish ở backend.
+
+**APIs used:** [`GNNetwork.cloudScript.executeFunctionAsync`](reference/API_CLOUDSCRIPT.md).
+
+### Code
+
+```typescript
+import { GNNetwork, ReturnCode, ErrorCode, CloudScriptModels, ExecuteResponseStatus, GNHashtable } from "@xmobitea/gn-typescript-client";
+
+async function claimDailyReward() {
+  const request = new CloudScriptModels.ExecuteFunctionRequestData();
+  request.functionName = "claimDailyReward";
+  request.functionParameters = { date: new Date().toISOString().slice(0, 10) };
+
+  const res = await GNNetwork.cloudScript.executeFunctionAsync(
+    request,
+    undefined,        // overrideAuthToken
+    undefined,        // overrideSecretKey
+    GNHashtable.builder().add("source", "daily_popup").build(), // customTags
+    30,               // timeout (seconds)
+  );
+
+  if (res.returnCode !== ReturnCode.Ok || res.errorCode !== ErrorCode.Ok) return null;
+
+  const exec = res.responseData;
+  if (exec.status !== ExecuteResponseStatus.Ok) {
+    console.warn("function failed", exec.errorMessage);
+    return null;
+  }
+  return exec.functionResult; // raw payload từ function
+}
+```
+
+### Return paths
+
+- `ExecuteResponseStatus.Ok` → function chạy xong, `functionResult` là value function trả về.
+- `ExecuteResponseStatus.Exception` → function throw; `exec.errorMessage` chứa message.
+- `ExecuteResponseStatus.FunctionNameNotFound` → function chưa publish/export hoặc sai tên.
+
+### Pitfalls
+
+- `customTags` là `GNHashtable`; dùng `GNHashtable.builder()` để giữ đúng public type. Giá trị nên là primitive hoặc string; không nhét object lồng.
+- Timeout function mặc định 20s — function nặng (query DB lớn) nên tăng timeout param.
+
+---
+
+## Scenario 13: Override authToken / secret (impersonate, cross-role)
+
+**Problem:** Đang ở role admin/server, cần gọi API như một player cụ thể (impersonate) hoặc override secret key của request cụ thể.
+
+**APIs used:** mọi method — async form nhận `overrideAuthToken`, `overrideSecretKey` là param thứ 2-3; callback form là param thứ 3-4 vì có `onResponse`.
+
+### Code
+
+```typescript
+import { GNNetwork, ContentModels, MasterPlayerModels } from "@xmobitea/gn-typescript-client";
+
+// Impersonate player để query profile của họ
+async function fetchProfileAs(playerAuthToken: string, playerId: string) {
+  const infoRequestParam = new MasterPlayerModels.InfoRequestParam();
+  infoRequestParam.displayName = true;
+  infoRequestParam.avatar = true;
+
+  const request = new MasterPlayerModels.GetPlayerInformationRequestData();
+  request.userId = playerId;
+  request.infoRequestParam = infoRequestParam;
+
+  const res = await GNNetwork.masterPlayer.getPlayerInformationAsync(
+    request,
+    playerAuthToken,   // overrideAuthToken — thay token cache
+    undefined,         // overrideSecretKey — giữ secret key mặc định của role
+    undefined,         // customTags
+    undefined,         // timeout
+  );
+  return res.responseData;
+}
+
+// Dùng secret key khác (ví dụ một game khác cùng backend)
+async function callOtherGame(gameSecret: string) {
+  const request = new ContentModels.GetContentDataRequestData();
+  request.keys = ["config"];
+
+  return GNNetwork.content.getContentDataAsync(
+    request,
+    undefined,
+    gameSecret,
+  );
+}
+```
+
+### Return paths
+
+- Token override bypass cache; request này KHÔNG update cached token.
+- Secret override bypass `secretKey` mặc định.
+
+### Pitfalls
+
+- Override không persist — mỗi request phải truyền lại.
+- Truyền `overrideAuthToken = ""` (rỗng) → request đi KHÔNG CÓ auth header, thường fail với `ReturnCode.OperationNotAuthorized`. Muốn dùng auth cache hiện tại thì truyền `null`/`undefined`.
+
+---
+
+## Scenario 14: Admin login qua DashboardApi
+
+**Problem:** Tool dashboard web — cần admin login bằng username/password admin, rồi query game list / analytics.
+
+**Prerequisites:** đã init; biết admin username/password backend cấp.
+
+**APIs used:** [`GNNetwork.dashboard.loginByAdminAccountAsync`](reference/API_DASHBOARD.md), `getGameListAsync`, `getAnalyticsAsync`, …
+
+> **Lưu ý thiết kế:** Dashboard API CHỈ có namespace client (`GNNetwork.dashboard`, không có `.server` / `.admin`). Transport dùng `RequestRole.Client`. Admin context backend resolve TỪ auth token trả về sau `loginByAdminAccount` — token này khác token của player thường.
+
+### Code
+
+```typescript
+import { GNNetwork, ReturnCode, ErrorCode, DashboardModels } from "@xmobitea/gn-typescript-client";
+
+async function adminLogin(username: string, password: string) {
+  const request = new DashboardModels.LoginByAdminAccountRequestData();
+  request.username = username;
+  request.password = password;
+
+  const res = await GNNetwork.dashboard.loginByAdminAccountAsync(request);
+  if (res.returnCode !== ReturnCode.Ok || res.errorCode !== ErrorCode.Ok) return false;
+
+  // Dashboard response carries authToken; SDK caches it for later dashboard calls.
+  return true;
+}
+
+async function listGames() {
+  const res = await GNNetwork.dashboard.getGameListAsync(new DashboardModels.GetGameListRequestData());
+  return res.responseData?.games ?? [];
+}
+```
+
+### Return paths
+
+- Happy → admin token được SDK cache; mọi dashboard method sau đó dùng token này.
+- `ErrorCode.AccountNotFound` / `ErrorCode.AccountPasswordWrong` → giống player login.
+
+### Pitfalls
+
+- Trộn admin token với player flow → backend reject. Sau admin logout, clear token trước khi login player.
+- Dashboard KHÔNG cần socket — có thể set `useSocket: false` trong settings cho web dashboard.
+
+---
+
+## Scenario 15: Cleanup & shutdown flow
+
+**Problem:** User logout hoặc app shutdown — cần close socket + clear auth để session sau không leak state.
+
+### Code
+
+```typescript
+import { GNNetwork, AuthenticateStatus, OnGroupMessageUpdateEventHandler, OnGroupMemberUpdateEventHandler, OnGamePlayerFriendUpdateEventHandler, OnGamePlayerGroupUpdateEventHandler, OnCharacterPlayerFriendUpdateEventHandler, OnCharacterPlayerGroupUpdateEventHandler } from "@xmobitea/gn-typescript-client";
+
+function logoutAndCleanup() {
+  // 1. Clear all event handler callbacks (chúng là static, không tự gc)
+  const noop = () => {};
+  OnGroupMessageUpdateEventHandler.onUpdate = noop;
+  OnGroupMemberUpdateEventHandler.onUpdate = noop;
+  OnGamePlayerFriendUpdateEventHandler.onUpdate = noop;
+  OnGamePlayerGroupUpdateEventHandler.onUpdate = noop;
+  OnCharacterPlayerFriendUpdateEventHandler.onUpdate = noop;
+  OnCharacterPlayerGroupUpdateEventHandler.onUpdate = noop;
+
+  // 2. Close socket
+  GNNetwork.disconnectSocket(() => {
+    console.log("socket closed");
+  });
+
+  // 3. Clear auth state
+  const empty = new AuthenticateStatus();
+  empty.setAuthToken("");
+  empty.setUserId("");
+  GNNetwork.setNewAuthenticateStatus(empty);
+}
+```
+
+### Return paths
+
+- `disconnectSocket` callback fire khi connection closed. Sau đó socket không auto-reconnect (stop reconnect loop).
+- `setNewAuthenticateStatus` với token rỗng xóa state + localStorage entry.
+
+### Pitfalls
+
+- Không clear event handler → new session fire vào callback cũ trỏ tới UI component đã unmount, gây crash.
+- Không đợi `disconnectSocket` callback mà shutdown process ngay → socket có thể không gửi packet `logout` tới server → backend phải đợi timeout để cleanup session.
+
+---
+
+## Scenario 16: Diagnose `OperationNotAllow`
+
+**Problem:** Một API call trả `ReturnCode.OperationNotAllow`. Cần xác định root cause và fix.
+
+**Prerequisites:** biết method đang gọi, namespace (`client` / `.server` / `.admin`), target user (nếu có), secret key đang dùng.
+
+**Key insight:** `OperationNotAllow` **không** phải thiếu secret hoặc operation không tồn tại (đó là `SecretInvalid` và `OperationInvalid`). Đây là: secret hợp lệ, operation tồn tại, nhưng **permission rule** của secret không cho phép operation trong target context. Xem [RULES § 5](RULES.md#5-phân-biệt-3-returncode-dễ-nhầm).
+
+### Decision tree
+
+```
+Gặp returnCode === OperationNotAllow
+│
+├─ Bước 1: Xác định route đang gọi
+│    • GNNetwork.<group>.<method>(...)         → route = client
+│    • GNNetwork.<group>.server.<method>(...)  → route = server
+│    • GNNetwork.<group>.admin.<method>(...)   → route = admin
+│
+├─ Bước 2: Xác định target (chỉ áp dụng route client)
+│    • Bỏ userId HOẶC userId trùng auth       → target = self
+│    • userId khác auth user                   → target = other-self
+│    • Domain không có ownership (Content,
+│      StoreInventory, Multiplayer, CloudScript) → bỏ qua bước 2
+│
+├─ Bước 3: Map route + target → flag cần (RULES § 6.1)
+│    • client + self        → selfEnable
+│    • client + other-self  → otherSelfEnable
+│    • server               → serverSelfEnable
+│    • admin                → adminSelfEnable
+│
+├─ Bước 4: Check secret active có flag đó cho operation đang gọi không?
+│    → xem dashboard GearN Server hoặc hỏi backend admin
+│    → danh sách operation: reference/PERMISSION_RULES.md + API_<GROUP>.md
+│
+└─ Bước 5: Nếu không có flag, chọn 1 trong 3 action:
+     (a) Dùng secret khác qua GNServerSettings.secretKey (cần restart process)
+     (b) Override per-request: truyền overrideSecretKey vào method
+     (c) Yêu cầu backend admin bật flag trong GearN Dashboard tương ứng cho secret hiện tại
+```
+
+### Code
+
+```ts
+import {
+  GNNetwork,
+  ReturnCode,
+  InventoryModels,
+} from "@xmobitea/gn-typescript-client";
+
+async function grantItem(userId: string, itemId: string, amount: number) {
+  const req = new InventoryModels.SetAmountRequestData();
+  req.itemId = itemId;
+  req.amount = amount;
+
+  // Attempt 1: route admin với secret mặc định của app
+  let res = await GNNetwork.inventory.admin.setAmountAsync(req);
+
+  if (res.returnCode === ReturnCode.OperationNotAllow) {
+    console.warn("OperationNotAllow on admin route — secret thiếu adminSelfEnable cho inventory.setAmount");
+    console.warn("debugMessage:", res.debugMessage);
+
+    // Attempt 2: fallback override secret admin cho 1 request
+    const ADMIN_SECRET = process.env.GEARN_ADMIN_SECRET; // KHÔNG hardcode
+    if (ADMIN_SECRET) {
+      res = await GNNetwork.inventory.admin.setAmountAsync(
+        req,
+        undefined,      // overrideAuthToken
+        ADMIN_SECRET,   // overrideSecretKey
+      );
+    }
+  }
+
+  if (res.returnCode !== ReturnCode.Ok) {
+    // Vẫn fail sau fallback → báo ops, KHÔNG retry
+    throw new Error(`grant failed: returnCode=${res.returnCode}, debug=${res.debugMessage}`);
+  }
+  return res.responseData;
+}
+```
+
+### Return paths
+
+- `OperationNotAllow` → **không retry cùng secret**, đó là config fix.
+- Sau fallback `overrideSecretKey` vẫn `OperationNotAllow` → secret admin cũng thiếu flag, phải liên hệ backend admin thêm flag trong GearN Dashboard.
+- Nếu chuyển sang `SecretInvalid` sau fallback → override secret sai format / không khớp game context (khác lỗi, xem [RULES § 5](RULES.md#5-phân-biệt-3-returncode-dễ-nhầm)).
+
+### Pitfalls
+
+- **Nhầm `OperationNotAllow` với `SecretInvalid`** → sửa sai hướng, đổi secret vô nghĩa khi rule chưa được bật.
+- **Dùng `.server` / `.admin` từ frontend app để vượt permission** → trust boundary leak, secret bị expose. Route phải match caller thực tế (xem [RULES § 3](RULES.md#3-route--trust-boundary-của-caller)).
+- **Retry tự động khi gặp `OperationNotAllow`** → không bao giờ giải quyết được, chỉ tốn request budget.
+- **Giả định rule `selfEnable` tự bật** → backend admin config per-operation, không default bật tất cả.
+- **Không check self vs other-self khi ở route `client`** → ví dụ gọi `masterPlayer.getPlayerInformationAsync(otherId)` mà nghĩ vẫn là self → sai flag → debug lâu.
+
+### Liên kết
+
+- Mapping rule đầy đủ: [RULES § 6.1](RULES.md#61-mapping-route-target--required-flag)
+- Scenario điển hình (5 case): [RULES § 6.3](RULES.md#63-scenario-điển-hình-trigger-operationnotallow)
+- Checklist nhanh: [RULES § 6.4](RULES.md#64-checklist-nhanh-khi-gặp-returncodeoperationnotallow)
+- Danh sách operation per-domain: [reference/PERMISSION_RULES.md](reference/PERMISSION_RULES.md)
+
+---
+
+## Pattern chung xuyên scenarios
+
+| Pattern | Khi nào | Tham khảo |
+|---------|---------|-----------|
+| Check `returnCode` → `errorCode` → đọc `responseData` | Mọi `*Async()` | [ERROR_HANDLING.md](reference/ERROR_HANDLING.md) |
+| SDK auto-cache `authToken` / `userId` sau authenticate success | Login/refresh player; dashboard login cache `authToken` | Scenario 2, 3, 4, 14 |
+| Subscribe event handler trước `connectSocket`; chỉ gọi `sendRequestAuthSocket` khi cần re-auth thủ công | Realtime | Scenario 5, 6, 7, 8 |
+| `.server` / `.admin` chỉ ở backend, không bao giờ ở frontend | Mọi cross-role call | Scenario 10, 13 |
+| `customTags` để backend log/route | Khi cần phân loại source | Scenario 12 |
+| Clear event handler + `disconnectSocket` + `setNewAuthenticateStatus(empty)` khi logout | Unload/logout | Scenario 15 |