@xmobitea/gn-typescript-client 2.6.13 → 2.6.14

package/docs/reference/EVENTS.md

@@ -0,0 +1,188 @@
+# Reference: Server Events
+
+SDK cung cấp 6 server event handler đẩy realtime update từ backend qua socket. Mỗi handler expose 1 static callback `onUpdate: Action1<Payload>` — subscribe bằng cách gán function vào field này.
+
+## Rule cứng
+
+- Event chỉ đến khi **socket đã connect + đã authenticate**. Xem [RULES.md § 7](../RULES.md#7-auth--socket-flow).
+- Callback là **static field** dùng chung toàn app session. Gán lần cuối ghi đè lần trước; không có mechanism multi-subscriber built-in. Nếu cần fan-out, tự wrap dispatcher.
+- Cleanup copy-safe = gán callback no-op hoặc remove listener trong wrapper dispatcher của app. Không có event nào “drain” callback khi socket disconnect.
+- Callback nhận đã-deserialized payload. Không thao tác với `OperationEvent` raw trừ khi viết handler custom.
+- Không giả định realtime tự chạy chỉ vì đã gọi method HTTP (friend, group, …). Chỉ các event liệt kê dưới đây được SDK lắng nghe mặc định.
+
+## Delivery guarantee
+
+- Best-effort. Nếu socket disconnect, event mất trong khoảng ngắt; SDK không replay.
+- Sau khi reconnect + re-auth, backend có thể gửi snapshot mới; ứng dụng nên merge idempotent theo id entity.
+
+## Bảng event
+
+| Handler | EventCode (logical) | Payload class | Trigger |
+|---------|---------------------|---------------|---------|
+| `OnGroupMessageUpdateEventHandler` | `OnGroupMessageUpdate` | `GroupMessageUpdate` | Tin nhắn group mới, edit, hoặc stream sync |
+| `OnGroupMemberUpdateEventHandler` | `OnGroupMemberUpdate` | `GroupMemberUpdate` | Member join/leave/kick/role thay đổi |
+| `OnGamePlayerFriendUpdateEventHandler` | `OnGamePlayerFriendUpdate` | `GamePlayerFriendUpdate` | Friend relation của game player hiện tại đổi |
+| `OnGamePlayerGroupUpdateEventHandler` | `OnGamePlayerGroupUpdate` | `GamePlayerGroupUpdate` | Group relation của game player hiện tại đổi |
+| `OnCharacterPlayerFriendUpdateEventHandler` | `OnCharacterPlayerFriendUpdate` | `CharacterPlayerFriendUpdate` | Friend relation của character hiện tại đổi |
+| `OnCharacterPlayerGroupUpdateEventHandler` | `OnCharacterPlayerGroupUpdate` | `CharacterPlayerGroupUpdate` | Group relation của character hiện tại đổi |
+
+---
+
+## `OnGroupMessageUpdateEventHandler`
+
+**Import:**
+```ts
+import { OnGroupMessageUpdateEventHandler } from "@xmobitea/gn-typescript-client";
+```
+
+**Subscribe shape:** `static onUpdate: Action1<GroupMessageUpdate>`
+
+**Payload `GroupMessageUpdate`:**
+
+| Field | Type | Optional | Notes |
+|-------|------|----------|-------|
+| `groupMessages` | `Array<GroupModels.GroupMessageResponseData>` | no | Batch message item mới/changed |
+| `groupId` | `string` | no | Group id có message stream đổi |
+| `characterId` | `string` | yes | Có khi update scope theo character context |
+
+**Ví dụ:**
+```ts
+import { OnGroupMessageUpdateEventHandler } from "@xmobitea/gn-typescript-client";
+
+OnGroupMessageUpdateEventHandler.onUpdate = (payload) => {
+	console.log(`group ${payload.groupId} received ${payload.groupMessages.length} messages`);
+	for (const msg of payload.groupMessages) {
+		// render msg
+	}
+};
+
+// Cleanup copy-safe
+OnGroupMessageUpdateEventHandler.onUpdate = () => {};
+```
+
+---
+
+## `OnGroupMemberUpdateEventHandler`
+
+**Import:** `import { OnGroupMemberUpdateEventHandler } from "@xmobitea/gn-typescript-client";`
+
+**Subscribe:** `static onUpdate: Action1<GroupMemberUpdate>`
+
+**Payload `GroupMemberUpdate`:**
+
+| Field | Type | Optional | Notes |
+|-------|------|----------|-------|
+| `members` | `Array<GenericModels.MemberItem>` | no | Member relation item đổi trong batch |
+| `groupId` | `string` | no | Group id có member roster đổi |
+
+**Ví dụ:**
+```ts
+OnGroupMemberUpdateEventHandler.onUpdate = (payload) => {
+	const groupId = payload.groupId;
+	for (const m of payload.members) {
+		// update member cache
+	}
+};
+```
+
+---
+
+## `OnGamePlayerFriendUpdateEventHandler`
+
+**Import:** `import { OnGamePlayerFriendUpdateEventHandler } from "@xmobitea/gn-typescript-client";`
+
+**Subscribe:** `static onUpdate: Action1<GamePlayerFriendUpdate>`
+
+**Payload `GamePlayerFriendUpdate`:**
+
+| Field | Type | Optional | Notes |
+|-------|------|----------|-------|
+| `playerFriends` | `Array<GenericModels.FriendItem>` | no | Friend relation item đổi (add/accept/remove/status) |
+| `characterId` | `string` | yes | Có khi update scope theo character context |
+
+**Ví dụ:**
+```ts
+OnGamePlayerFriendUpdateEventHandler.onUpdate = (payload) => {
+	for (const f of payload.playerFriends) {
+		// switch (f.status) { ... }
+	}
+};
+```
+
+---
+
+## `OnGamePlayerGroupUpdateEventHandler`
+
+**Import:** `import { OnGamePlayerGroupUpdateEventHandler } from "@xmobitea/gn-typescript-client";`
+
+**Subscribe:** `static onUpdate: Action1<GamePlayerGroupUpdate>`
+
+**Payload `GamePlayerGroupUpdate`:**
+
+| Field | Type | Optional | Notes |
+|-------|------|----------|-------|
+| `playerGroups` | `Array<GenericModels.GroupItem>` | no | Group relation item đổi (join/leave/status) |
+| `characterId` | `string` | yes | Có khi update scope theo character context |
+
+---
+
+## `OnCharacterPlayerFriendUpdateEventHandler`
+
+**Import:** `import { OnCharacterPlayerFriendUpdateEventHandler } from "@xmobitea/gn-typescript-client";`
+
+**Subscribe:** `static onUpdate: Action1<CharacterPlayerFriendUpdate>`
+
+**Payload `CharacterPlayerFriendUpdate`:**
+
+| Field | Type | Optional | Notes |
+|-------|------|----------|-------|
+| `characterId` | `string` | no | Character id có friend relation đổi |
+| `playerFriends` | `Array<GenericModels.FriendItem>` | no | Friend relation item đổi |
+
+---
+
+## `OnCharacterPlayerGroupUpdateEventHandler`
+
+**Import:** `import { OnCharacterPlayerGroupUpdateEventHandler } from "@xmobitea/gn-typescript-client";`
+
+**Subscribe:** `static onUpdate: Action1<CharacterPlayerGroupUpdate>`
+
+**Payload `CharacterPlayerGroupUpdate`:**
+
+| Field | Type | Optional | Notes |
+|-------|------|----------|-------|
+| `characterId` | `string` | no | Character id có group relation đổi |
+| `playerGroups` | `Array<GenericModels.GroupItem>` | no | Group relation item đổi |
+
+---
+
+## Pattern khuyến nghị
+
+- Subscribe trước khi gọi `GNNetwork.connectSocket()` để không bỏ lỡ event ngay sau handshake.
+- Callback phải nhanh; delegate work nặng sang queue/dispatcher riêng để tránh block socket loop.
+- Nếu app có nhiều consumer cho cùng event, build wrapper:
+
+```ts
+type Listener<T> = (payload: T) => void;
+const groupMessageListeners: Listener<GroupMessageUpdate>[] = [];
+
+OnGroupMessageUpdateEventHandler.onUpdate = (payload) => {
+	for (const l of groupMessageListeners) l(payload);
+};
+
+export function subscribeGroupMessage(l: Listener<GroupMessageUpdate>) {
+	groupMessageListeners.push(l);
+	return () => {
+		const i = groupMessageListeners.indexOf(l);
+		if (i >= 0) groupMessageListeners.splice(i, 1);
+	};
+}
+```
+
+---
+
+## Liên kết
+
+- Socket auth flow: [RULES.md § 7](../RULES.md#7-auth--socket-flow)
+- `FriendStatus` / `GroupStatus` giá trị numeric: [ENUMS.md](ENUMS.md)
+- API gây event: [API group guides](../guides/)

package/docs/reference/PERMISSION_RULES.md

@@ -0,0 +1,55 @@
+# Permission Rules Reference
+
+Local offline reference cho permission flags. AI Agent không cần duyệt web để map route, target và flag cơ bản.
+
+## Source Priority
+
+1. [RULES.md § 6](../RULES.md#6-permission-flags) định nghĩa semantics chung: route, target, và flag.
+2. `API_<GROUP>.md` liệt kê operation theo từng domain; dùng tên method bỏ hậu tố `Async` làm operation name.
+3. GearN Server dashboard là runtime source-of-truth cho secret key nào đang có flag nào.
+4. `https://docs.gearn.net/permissionRules` chỉ là external mirror khi cần đối chiếu online.
+
+Nếu docs và dashboard khác nhau, dashboard thắng ở runtime; docs cần được update lại.
+
+## Route To Flag Matrix
+
+| Caller | Target | Required flag |
+|---|---|---|
+| `GNNetwork.<group>.<method>Async(...)` | `self` | `selfEnable` |
+| `GNNetwork.<group>.<method>Async(...)` | `other-self` | `otherSelfEnable` |
+| `GNNetwork.<group>.server.<method>Async(...)` | any | `serverSelfEnable` |
+| `GNNetwork.<group>.admin.<method>Async(...)` | any | `adminSelfEnable` |
+
+`self` / `other-self` chỉ áp dụng cho route `client`. Với route `server` hoặc `admin`, truyền target rõ ràng theo signature của method và kiểm flag tương ứng của route.
+
+## API Group Index
+
+| Group | Operation list | Notes |
+|---|---|---|
+| Authenticate | [API_AUTHENTICATE.md](API_AUTHENTICATE.md) | Chỉ có namespace client. Login/register thường là acting-on-unauth-user; xem rule trong dashboard. |
+| Dashboard | [API_DASHBOARD.md](API_DASHBOARD.md) | Chỉ có namespace client wrapper; admin context resolve từ admin auth token. |
+| Content | [API_CONTENT.md](API_CONTENT.md) | Có client/server/admin; ownership không rõ như player entity. |
+| Multiplayer | [API_MULTIPLAYER.md](API_MULTIPLAYER.md) | Có client/server/admin; dùng HTTP, không dùng socket cho ticket lifecycle. |
+| StoreInventory | [API_STORE_INVENTORY.md](API_STORE_INVENTORY.md) | Có client/server/admin; purchase/receipt flow cần secret đúng trust boundary. |
+| Inventory | [API_INVENTORY.md](API_INVENTORY.md) | Có client/server/admin; owner có thể là master/game/character/group tùy DTO. |
+| Group | [API_GROUP.md](API_GROUP.md) | Có client/server/admin; group lifecycle một số flow nằm ở GamePlayer/CharacterPlayer. |
+| MasterPlayer | [API_MASTER_PLAYER.md](API_MASTER_PLAYER.md) | Có client/server/admin; client có thể bỏ `userId` để target current user. |
+| GamePlayer | [API_GAME_PLAYER.md](API_GAME_PLAYER.md) | Có client/server/admin; scoped theo game environment. |
+| CharacterPlayer | [API_CHARACTER_PLAYER.md](API_CHARACTER_PLAYER.md) | Có client/server/admin; thường phải truyền `characterId`. |
+| CloudScript | [API_CLOUDSCRIPT.md](API_CLOUDSCRIPT.md) | Có client/server/admin; execute/publish phải theo trust boundary. |
+
+## Diagnose `OperationNotAllow`
+
+1. Xác định namespace đang gọi: client, `.server`, hay `.admin`.
+2. Nếu là client route, xác định target là `self` hay `other-self`.
+3. Map route + target sang flag theo bảng ở trên.
+4. Lấy operation name từ API reference, ví dụ `getPlayerInformationAsync` -> `getPlayerInformation`.
+5. Kiểm secret active trong dashboard có flag đó cho operation đó không.
+
+Không retry cùng secret khi gặp `ReturnCode.OperationNotAllow`; đây là lỗi config permission. Các hướng xử lý hợp lệ:
+
+- Dùng secret khác trong `GNServerSettings` rồi restart process.
+- Truyền `overrideSecretKey` cho request cụ thể.
+- Yêu cầu backend admin bật flag còn thiếu trong GearN Dashboard cho secret hiện tại.
+
+Xem checklist đầy đủ trong [RULES.md § 6.4](../RULES.md#64-checklist-nhanh-khi-gặp-returncodeoperationnotallow) và scenario chẩn đoán trong [COOKBOOK.md](../COOKBOOK.md#scenario-16-diagnose-operationnotallow).