@xmobitea/gn-typescript-client 2.6.13 → 2.6.14

package/docs/reference/ENUMS.md

@@ -0,0 +1,433 @@
+# Reference: Enums
+
+Toàn bộ enum public export từ `@xmobitea/gn-typescript-client`. Mỗi bảng liệt kê tên, giá trị numeric thật, và ý nghĩa business.
+
+**Rule cứng cho AI consumer:**
+
+- So sánh giá trị bằng chính symbol của enum (`ReturnCode.Ok`), không hardcode số.
+- Không giả định success là `0`. Success ở cả 2 tầng là `1` (`ReturnCode.Ok === 1`, `ErrorCode.Ok === 1`).
+- Nếu backend trả về giá trị không có trong bảng này, xử lý như unknown và log lại; không suy diễn.
+
+## Mục lục
+
+- [ReturnCode](#returncode) — transport/gateway
+- [ErrorCode](#errorcode) — business domain
+- [RequestRole](#requestrole)
+- [RequestType](#requesttype)
+- [MessageType](#messagetype)
+- [PostType](#posttype)
+- [LogType](#logtype)
+- [FriendStatus](#friendstatus)
+- [GroupStatus](#groupstatus)
+- [GoogleLoginType](#googlelogintype)
+- [InvalidMemberType](#invalidmembertype)
+- [ItemType](#itemtype)
+- [OwnerType](#ownertype)
+- [PushPlatformType](#pushplatformtype)
+- [MatchmakingMemberStatus](#matchmakingmemberstatus)
+- [MatchmakingTicketStatus](#matchmakingticketstatus)
+- [MatchStatus](#matchstatus)
+- [ExecuteResponseStatus](#executeresponsestatus)
+- [StoreItemType](#storeitemtype)
+- [StoreReceiveType](#storereceivetype)
+- [PermissionDataItem](#permissiondataitem)
+- [FieldDataType](#fielddatatype)
+
+---
+
+## ReturnCode
+
+Transport/gateway return code trả trong `OperationResponse.getReturnCode()`. **Luôn kiểm tra trước `errorCode`.**
+
+Class import: `import { ReturnCode } from "@xmobitea/gn-typescript-client"` — các member là static readonly numbers.
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| `SecretInvalid` | -10 | Secret key sai / thiếu / không khớp route hoặc game context |
+| `MaxSizeRequestReject` | -9 | Payload vượt size tối đa backend chấp nhận |
+| `MaxRequestReject` | -8 | Caller vượt rate limit |
+| `MaxCCUReject` | -7 | Vượt giới hạn concurrent user/session |
+| `OperationNotAuthorized` | -6 | Operation tồn tại nhưng caller không đủ quyền với role/target |
+| `InvalidRequestParameters` | -5 | Request shape hoặc field invalid; inspect `invalidMembers` |
+| `OperationInvalid` | -4 | Operation code không tồn tại hoặc không hợp lệ với request type/role |
+| `InternalServerError` | -3 | Backend lỗi unhandled trước khi produce valid business response |
+| `OperationNotAllow` | -2 | Operation tồn tại + secret hợp lệ, nhưng permission rule không cho chạy ở target context |
+| `OperationTimeout` | -1 | Request timeout; có thể do SDK timeout layer hoặc backend |
+| `UnknownError` | 0 | Request fail, không có mapped return code cụ thể |
+| `Ok` | 1 | Protocol-level thành công; vẫn phải check `errorCode` trong response |
+
+Xem thêm: [ERROR_HANDLING.md](ERROR_HANDLING.md).
+
+---
+
+## ErrorCode
+
+Business domain error code, nằm trong response payload khi `returnCode === ReturnCode.Ok`. Chỉ trust khi đã pass tầng `ReturnCode`.
+
+Class import: `import { ErrorCode } from "@xmobitea/gn-typescript-client"` — các member là static readonly numbers.
+
+| Name | Value | Meaning | Typical context |
+|------|-------|---------|-----------------|
+| `Ok` | 1 | Business operation thành công | mọi response happy path |
+| `AccountNotFound` | 2 | Username/account không tồn tại | login flows |
+| `AccountPasswordWrong` | 3 | Password sai | login by account |
+| `AccountUsernameExists` | 4 | Username đã tồn tại | register |
+| `VerifyTokenError` | 5 | Token không verify/decode được | refresh token, social login |
+| `VerifyFailed` | 6 | External/provider verification fail | social login, receipt |
+| `CharacterPlayerNotFound` | 7 | Character player không tồn tại | character APIs |
+| `NotEnoughCurrency` | 8 | Wallet/owner thiếu currency | store purchase, transfer |
+| `KeyNotFound` | 9 | Key không tồn tại trong target data set | data/profile get |
+| `ItemNotFound` | 10 | Inventory item không tồn tại | inventory APIs |
+| `CatalogIdNotFound` | 11 | Catalog id không tồn tại | content/store |
+| `GroupNotFound` | 12 | Group không tồn tại | group APIs |
+| `OwnerNotFound` | 13 | Owner entity không tồn tại | cross-domain writes |
+| `ClassIdNotFound` | 14 | Class id không tồn tại | content config |
+| `MemberNotFound` | 15 | Group member / relation member không tồn tại | group / friend APIs |
+| `PlayerNotMember` | 16 | Player không phải member của group | group write APIs |
+| `GamePlayerNotFound` | 17 | Game player không tồn tại | game player APIs |
+| `FileNotFound` | 18 | File metadata hoặc physical file không tồn tại | content APIs |
+| `FileNotUpload` | 19 | File metadata tồn tại nhưng content chưa upload | content APIs |
+| `OwnerTypeNotSupport` | 20 | Owner type không support cho operation | cross-domain writes |
+| `ItemNotStackable` | 21 | Item không stackable, thao tác amount invalid | inventory APIs |
+| `GameNotFound` | 22 | Game không tồn tại | dashboard APIs |
+| `GameExists` | 23 | Game đã tồn tại (không tạo lại được) | dashboard create game |
+| `SecretInfoNotFound` | 24 | Secret-info record không tồn tại | dashboard secret mgmt |
+| `SecretInfoExists` | 25 | Secret-info record đã tồn tại | dashboard secret mgmt |
+| `ExternalNotLinked` | 26 | External identity chưa link account hiện tại | external identity unlink |
+| `ExternalLinkedOtherAccount` | 27 | External identity đã link account khác | external identity link |
+| `ExternalLinkedOtherValue` | 28 | External provider/value pair conflict giá trị đã link | external identity link |
+| `MasterPlayerNotFound` | 29 | Master player không tồn tại | master player APIs |
+| `StoreItemNotFound` | 30 | Store item không tồn tại | store APIs |
+| `BuyerNotFound` | 31 | Buyer entity không tồn tại | store buy/present |
+| `CanNotBuyThisStoreItem` | 32 | Store item không mua được ở state/buyer hiện tại | store buy |
+| `ExceptionWhenValidateReceipt` | 33 | Exception khi validate receipt | store receipt validate |
+| `StoreInvalid` | 34 | Store/provider config invalid | store receipt validate |
+| `ReceiptInvalid` | 35 | Receipt invalid | store receipt validate |
+| `StoreItemRemoved` | 36 | Store item đã removed, không dùng purchase flow nữa | store APIs |
+| `DisplayNameUsed` | 37 | Display name đã có người dùng | player profile update |
+| `PlayerBan` | 38 | Player hiện bị ban | login / gameplay |
+| `MatchmakingTicketNotFound` | 39 | Matchmaking ticket không tồn tại | multiplayer APIs |
+| `MatchmakingTicketAlreadyCompleted` | 40 | Ticket đã completed, không modify được | multiplayer APIs |
+| `MatchmakingPlayerNotJoinedTicket` | 41 | Player không phải member của ticket | multiplayer APIs |
+| `MatchNotFound` | 42 | Match không tồn tại | multiplayer query match |
+| `MatchmakingPlayerJoinedOtherTicket` | 43 | Player đã join ticket khác (conflict) | multiplayer create ticket |
+| `MatchmakingQueueNotFound` | 44 | Matchmaking queue không tồn tại | multiplayer APIs |
+| `TicketSizeError` | 45 | Ticket size vi phạm queue config | multiplayer create ticket |
+| `ExecuteError` | 46 | CloudScript function fail khi execute | cloudscript execute |
+| `VersionInvalid` | 47 | CloudScript version invalid/unavailable | cloudscript APIs |
+| `EmailInvalid` | 48 | Email sai format/semantically invalid | register, profile update |
+| `StoreItemPurchasedAndNonConsumable` | 49 | Buyer đã own non-consumable này rồi | store buy |
+| `StoreItemExists` | 50 | Store item đã tồn tại (không tạo lại được) | dashboard store mgmt |
+
+Xem thêm: [ERROR_HANDLING.md](ERROR_HANDLING.md).
+
+---
+
+## RequestRole
+
+Trust boundary của caller. Chọn route theo caller thật (client app / trusted backend / admin tool), không theo mối quan hệ với target.
+
+```ts
+export enum RequestRole {
+	Admin = 1,
+	Server = 2,
+	Client = 3,
+}
+```
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| `Admin` | 1 | Admin tool / backoffice / GM tool / migration tool |
+| `Server` | 2 | Trusted backend: game server, internal service, worker, cron, webhook |
+| `Client` | 3 | Player app / client code |
+
+---
+
+## RequestType
+
+Top-level domain phân loại route khi build transport path.
+
+```ts
+export enum RequestType {
+	Custom = 0,
+	Authenticate = 1,
+	CharacterPlayer = 2,
+	Content = 3,
+	GamePlayer = 4,
+	Group = 5,
+	Inventory = 6,
+	MasterPlayer = 7,
+	StoreInventory = 8,
+	Dashboard = 9,
+	Multiplayer = 10,
+	CloudScript = 11,
+}
+```
+
+| Name | Value |
+|------|-------|
+| `Custom` | 0 |
+| `Authenticate` | 1 |
+| `CharacterPlayer` | 2 |
+| `Content` | 3 |
+| `GamePlayer` | 4 |
+| `Group` | 5 |
+| `Inventory` | 6 |
+| `MasterPlayer` | 7 |
+| `StoreInventory` | 8 |
+| `Dashboard` | 9 |
+| `Multiplayer` | 10 |
+| `CloudScript` | 11 |
+
+---
+
+## MessageType
+
+Payload encoding preferred bởi transport.
+
+```ts
+export enum MessageType {
+	Json = 1,
+	MsgPack = 2,
+}
+```
+
+| Name | Value | Notes |
+|------|-------|-------|
+| `Json` | 1 | Browser-safe mọi trường hợp |
+| `MsgPack` | 2 | Compact binary; browser HTTP tự fallback sang JSON |
+
+---
+
+## PostType
+
+Low-level HTTP body encoding dùng bởi `HttpPeer`. App tích hợp thông thường không cần truyền trực tiếp enum này.
+
+| Name | Value | Notes |
+|------|-------|-------|
+| `Json` | 0 | UTF-8 JSON request/response body |
+| `MsgPack` | 1 | Binary MessagePack request/response body |
+
+---
+
+## LogType
+
+Verbosity cho `GNDebug`.
+
+```ts
+export enum LogType {
+	Off = 0,
+	Exception = 1,
+	Error = 2,
+	Warning = 3,
+	All = 4,
+}
+```
+
+| Name | Value |
+|------|-------|
+| `Off` | 0 |
+| `Exception` | 1 |
+| `Error` | 2 |
+| `Warning` | 3 |
+| `All` | 4 |
+
+---
+
+## FriendStatus
+
+Lifecycle state của quan hệ bạn bè.
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| `Friend` | 1 | Đã là bạn |
+| `WaitingAccept` | 2 | Đang chờ mình accept incoming request |
+| `SentRequestAndWaitingAccept` | 3 | Mình đã gửi request, chờ bên kia accept |
+| `NotFriend` | 4 | Không có quan hệ bạn bè |
+
+---
+
+## GroupStatus
+
+Lifecycle state của quan hệ group membership.
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| `Member` | 1 | Đã là member active |
+| `WaitingAccept` | 2 | Đang chờ group accept join request từ bên mình |
+| `SentRequestAndWaitingAccept` | 3 | Đã gửi join request, chờ group approve |
+| `NotMember` | 4 | Chưa là member |
+
+---
+
+## GoogleLoginType
+
+Loại credential Google được cung cấp cho login/link flow.
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| `AccessToken` | 1 | OAuth access token |
+| `IdToken` | 2 | OpenID Connect ID token |
+
+---
+
+## InvalidMemberType
+
+Category lỗi validation expose qua `res.invalidMembers`. Chỉ xuất hiện khi `res.returnCode === ReturnCode.InvalidRequestParameters`.
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| `UnknownError` | 1 | Không map được category cụ thể |
+| `DataRequired` | 2 | Field required nhưng thiếu |
+| `TypeInvalid` | 3 | Runtime type không match expected |
+| `StringNull` | 4 | Required string null/empty |
+| `StringMinLength` | 5 | String ngắn hơn min length |
+| `StringMaxLength` | 6 | String dài hơn max length |
+| `NumberMinValue` | 7 | Number thấp hơn min value |
+| `NumberMaxValue` | 8 | Number cao hơn max value |
+| `NumberMustInt` | 9 | Number phải integer nhưng nhận non-integer |
+| `GNHashtableNull` | 10 | `GNHashtable` required null |
+| `GNHashtableMinLength` | 11 | `GNHashtable` ít entry hơn min |
+| `GNHashtableMaxLength` | 12 | `GNHashtable` nhiều entry hơn max |
+| `GNArrayNull` | 13 | `GNArray` required null |
+| `GNArrayMinLength` | 14 | `GNArray` ít item hơn min |
+| `GNArrayMaxLength` | 15 | `GNArray` nhiều item hơn max |
+
+---
+
+## ItemType
+
+Kiểu inventory item hỗ trợ stacking hay không.
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| `NonStackable` | 1 | Mỗi instance unique, track riêng |
+| `Stackable` | 2 | Nhiều unit gộp chung amount |
+
+---
+
+## OwnerType
+
+Top-level entity owner của resource.
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| `MasterPlayer` | 1 | Master-player account |
+| `GamePlayer` | 2 | Game-player entity |
+| `CharacterPlayer` | 3 | Character-player entity |
+| `Group` | 4 | Group entity |
+| `Inventory` | 5 | Inventory item khác |
+| `StoreInventory` | 6 | Store-inventory entity |
+
+---
+
+## PushPlatformType
+
+Mobile push platform.
+
+| Name | Value |
+|------|-------|
+| `Android` | 1 |
+| `iOS` | 2 |
+
+---
+
+## MatchmakingMemberStatus
+
+State của 1 member trong matchmaking ticket.
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| `Pending` | 1 | Declared nhưng chưa join/confirm |
+| `Joined` | 2 | Đã join ticket |
+| `Canceled` | 3 | Hủy tham gia ticket |
+
+---
+
+## MatchmakingTicketStatus
+
+Lifecycle state của matchmaking ticket.
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| `WaitingForMembers` | 1 | Chờ tất cả member declared join |
+| `WaitingForMatch` | 2 | Đủ member, chờ matchmaking engine tìm match |
+| `WaitingForServer` | 3 | Đã có match, chờ server allocation |
+| `Matched` | 4 | Complete → pointer sang match |
+| `Canceled` | 5 | Ticket bị hủy, không produce match |
+
+---
+
+## MatchStatus
+
+Lifecycle state của match record sau khi matchmaking tạo match.
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| `WaitingForServer` | 1 | Match đã tạo nhưng server allocation chưa sẵn sàng |
+| `Matched` | 2 | Server đã sẵn sàng; app có thể tiếp tục flow connect theo backend contract |
+| `Canceled` | 3 | Match bị hủy trước khi hoàn tất |
+
+---
+
+## ExecuteResponseStatus
+
+Status CloudScript execute function.
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| `Ok` | 1 | Execute thành công |
+| `Exception` | 2 | Execute nhưng function throw exception |
+| `FunctionNameNotFound` | 3 | Function name không tồn tại trong version |
+| `VersionInvalid` | 4 | Version invalid/không execute được |
+| `Timeout` | 5 | Function vượt thời gian cho phép |
+
+---
+
+## StoreItemType
+
+Kiểu store item: mua 1 lần hay nhiều lần.
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| `NonConsumable` | 1 | Chỉ own 1 bản persistent |
+| `Consumable` | 2 | Mua lại và tiêu thụ nhiều lần |
+
+---
+
+## StoreReceiveType
+
+Cách store item được trao cho buyer.
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| `Buy` | 1 | Buy flow trong game bình thường |
+| `Present` | 2 | Present/gift flow |
+| `AppleAppStore` | 3 | Apple App Store receipt validation |
+| `FacebookStore` | 4 | Facebook Store receipt validation |
+| `GooglePlayStore` | 5 | Google Play receipt validation |
+
+---
+
+## PermissionDataItem
+
+Cách config 1 data item có thể ghi lại sau khi tạo.
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| `ReadOnly` | 1 | Read được nhưng write flow thường không ghi đè |
+| `CanOverride` | 2 | Write được, ghi đè giá trị cũ |
+
+---
+
+## FieldDataType
+
+Runtime metadata type ghi nhận bởi decorator `DataMember`. App tích hợp SDK bình thường hiếm khi cần đọc trực tiếp enum này.
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| `Boolean` | 0 | Field boolean |
+| `Number` | 1 | Field number |
+| `String` | 2 | Field string |
+| `Array` | 3 | Field array |
+| `Object` | 4 | Field class/object |

package/docs/reference/ERROR_HANDLING.md

@@ -0,0 +1,159 @@
+# Reference: Error Handling
+
+Mọi response từ GearN backend đi qua 2 tầng kiểm tra. AI consumer phải check đủ cả hai, đúng thứ tự.
+
+## Pattern bắt buộc
+
+```ts
+import { AuthenticateModels, ErrorCode, GNNetwork, ReturnCode } from "@xmobitea/gn-typescript-client";
+
+const request = new AuthenticateModels.LoginByAccountRequestData();
+request.username = username;
+request.password = password;
+request.infoRequestParam = new AuthenticateModels.InfoRequestParam();
+
+const res = await GNNetwork.authenticate.loginByAccountAsync(request);
+
+// 1. Kiểm tra returnCode (transport/gateway)
+if (res.returnCode !== ReturnCode.Ok) {
+	handleTransportFailure(res);
+	return;
+}
+
+// 2. Kiểm tra errorCode (business domain)
+if (res.errorCode !== ErrorCode.Ok) {
+	handleDomainFailure(res);
+	return;
+}
+
+// 3. Happy path: trust typed payload
+useResult(res.responseData);
+```
+
+Typed response (trả từ mọi `*Async()` và callback path) expose field `public`:
+
+- `res.returnCode: number` — tầng 1
+- `res.errorCode: number` — tầng 2 (chỉ set khi `returnCode === Ok`)
+- `res.invalidMembers: InvalidMember[]` — khi `returnCode === InvalidRequestParameters`
+- `res.debugMessage: string` — backend debug message
+- `res.responseData: T` — typed payload, chỉ set khi `returnCode === Ok`
+
+**Rule cứng:**
+
+- Không skip tầng 1 để đọc thẳng `errorCode`. Nếu `returnCode !== Ok`, `errorCode` và typed parameters **không đáng tin**.
+- Không giả định success là `0`. Success ở cả hai tầng là `1` (`ReturnCode.Ok === 1`, `ErrorCode.Ok === 1`).
+- Không hardcode số. Luôn so sánh bằng symbol `ReturnCode.*` / `ErrorCode.*`.
+- `Async` method vẫn return response object (không throw) — reject chỉ xảy ra khi transport layer lỗi thực sự (network down, serialization fail).
+
+---
+
+## Tầng 1: `ReturnCode`
+
+Kiểm tra bằng `res.returnCode`. So sánh bằng enum symbol. Giá trị numeric: [ENUMS.md § ReturnCode](ENUMS.md#returncode).
+
+| ReturnCode | Khi nào gặp | Recommended action |
+|------------|-------------|--------------------|
+| `Ok` | Happy path | Sang tầng 2 check `errorCode` |
+| `UnknownError` | Backend fail nhưng không map code cụ thể | Log + show lỗi chung; không retry tự động |
+| `OperationTimeout` | Request timeout (SDK hoặc backend) | Retry với backoff nếu operation idempotent; báo user nếu không |
+| `OperationNotAllow` | Permission rule của secret key không cho chạy operation ở target context | Sai route (`client/server/admin`) hoặc secret thiếu `selfEnable`/`otherSelfEnable`/`serverSelfEnable`/`adminSelfEnable`. Không retry — fix config. Checklist chi tiết: [RULES.md § 6](../RULES.md#6-permission-flags) |
+| `InternalServerError` | Backend crash internal | Log + show lỗi chung; có thể retry 1 lần rồi escalate |
+| `OperationInvalid` | Operation code không tồn tại / sai với request type + role | Sai namespace: kiểm tra đang gọi đúng `GNNetwork.<domain>.<method>`. Không retry |
+| `InvalidRequestParameters` | Request shape / field invalid | Đọc `res.invalidMembers`; fix field rồi gửi lại |
+| `OperationNotAuthorized` | Caller không auth với role/target resource | Kiểm tra `authToken` hợp lệ; re-login hoặc refresh token |
+| `MaxCCUReject` | Vượt concurrent user limit | Backoff + retry; escalate lên ops nếu recurring |
+| `MaxRequestReject` | Vượt rate limit | Exponential backoff retry; xem lại client usage pattern |
+| `MaxSizeRequestReject` | Payload vượt max size | Không retry; giảm size request (paginate, split) |
+| `SecretInvalid` | Secret key sai / thiếu / không khớp game | Fix cấu hình `GNServerSettingsOptions`, không retry |
+
+### Khi gặp `InvalidRequestParameters`
+
+Response expose thêm `res.invalidMembers: InvalidMember[]`:
+
+```ts
+interface InvalidMember {
+	code: string;                   // tên field (ParameterCode)
+	invalidMemberType: InvalidMemberType;
+}
+```
+
+`InvalidMemberType` xem [ENUMS.md § InvalidMemberType](ENUMS.md#invalidmembertype). Ví dụ parse:
+
+```ts
+if (res.returnCode === ReturnCode.InvalidRequestParameters) {
+	for (const im of res.invalidMembers ?? []) {
+		console.warn(`field ${im.code} invalid: type=${im.invalidMemberType}`);
+	}
+}
+```
+
+---
+
+## Tầng 2: `ErrorCode`
+
+Chỉ check sau khi `returnCode === ReturnCode.Ok`. Lấy qua `response.errorCode` (field public trên typed response class).
+
+Bảng đầy đủ 50 giá trị xem [ENUMS.md § ErrorCode](ENUMS.md#errorcode). Pattern xử lý chung:
+
+| ErrorCode family | Pattern |
+|------------------|---------|
+| `Ok` | Dùng data trong response |
+| `*NotFound` (2, 7, 9–19, 22, 24, 29, 30, 31, 39, 42, 44) | Entity không tồn tại — thường hiện message user-friendly, không retry |
+| `*Exists` / `*HadBeen*` (4, 23, 25, 36, 49, 50) | Conflict trạng thái — hiện UX "đã tồn tại" / "đã mua", không retry |
+| `*Invalid` (5, 6, 34, 35, 47, 48) | Input hoặc external data invalid — user sửa lại rồi thử lại |
+| `AccountPasswordWrong` (3), `PlayerBan` (38) | Auth fail nghiệp vụ — show rõ cho user, không retry cùng input |
+| `NotEnoughCurrency` (8), `CanNotBuyThisStoreItem` (32) | Điều kiện business không đủ — UX hướng dẫn user nạp/thử item khác |
+| `ExternalLinked*` (27, 28) | Identity conflict — UX hướng dẫn unlink/choose account |
+| `MatchmakingPlayerJoinedOtherTicket` (43), `MatchmakingTicketAlreadyCompleted` (40) | State transition không hợp lệ — poll state mới rồi retry logic |
+| `ExecuteError` (46) | CloudScript throw — đọc payload execute response để debug |
+
+---
+
+## `Return` vs `Error` — quyết định nhanh
+
+| Tình huống | Layer | Xử lý |
+|------------|-------|-------|
+| User offline, request không đến server | — (reject Promise / transport exception) | Retry với backoff |
+| SSL/cert fail | — (reject Promise) | Báo ops; không retry tự động |
+| Timeout | `ReturnCode.OperationTimeout` | Retry nếu idempotent |
+| Sai secret key | `ReturnCode.SecretInvalid` | Fix config |
+| Thiếu permission | `ReturnCode.OperationNotAllow` / `OperationNotAuthorized` | Fix route + secret permission |
+| Field invalid | `ReturnCode.InvalidRequestParameters` | Parse `invalidMembers` |
+| Username sai | `ErrorCode.AccountNotFound` | UX login fail |
+| Password sai | `ErrorCode.AccountPasswordWrong` | UX login fail |
+| Thiếu tiền | `ErrorCode.NotEnoughCurrency` | UX nạp tiền |
+
+---
+
+## Promise vs Callback
+
+Cả 2 pattern **không throw** trên business/transport error:
+
+```ts
+// Callback
+GNNetwork.authenticate.loginByAccount(data, (res) => {
+	if (res.returnCode !== ReturnCode.Ok) return;
+	if (res.errorCode !== ErrorCode.Ok) return;
+	useResult(res.responseData);
+});
+
+// Async
+try {
+	const res = await GNNetwork.authenticate.loginByAccountAsync(data);
+	if (res.returnCode !== ReturnCode.Ok) return;
+	if (res.errorCode !== ErrorCode.Ok) return;
+	useResult(res.responseData);
+} catch (e) {
+	// chỉ đến đây khi transport layer throw (network exception, serialization fail)
+}
+```
+
+Mặc định ưu tiên `*Async`.
+
+---
+
+## Liên kết
+
+- Enum đầy đủ: [ENUMS.md](ENUMS.md)
+- Route / permission: [RULES.md § 3](../RULES.md#3-route--trust-boundary-của-caller)
+- Self / other-self: [RULES.md § 4](../RULES.md#4-self-vs-other-self-chỉ-áp-dụng-trên-route-client)