@xmobitea/gn-typescript-client 2.6.13 → 2.6.14

package/AGENTS.md

@@ -0,0 +1,37 @@
+# GearN TypeScript Client SDK — AI Entry Guide
+
+Entry point cho AI agent / code assistant khi làm việc với repo hoặc package.
+
+Mục tiêu:
+
+- Sinh code tích hợp SDK đúng từ đầu.
+- Không cần đọc `src/` để hiểu public contract thông thường.
+- Tránh suy diễn sai về route, secret, permission, auth/socket flow.
+
+## 1. Reading order
+
+1. [docs/AI_CHEATSHEET.md](docs/AI_CHEATSHEET.md) — one-page reference, decision tree, mandatory pattern.
+2. [docs/RULES.md](docs/RULES.md) — **canonical** cho mọi rule cross-cutting.
+3. [docs/ai-manifest.json](docs/ai-manifest.json) — machine-readable manifest (schemaVersion=3).
+4. [docs/reference/API_INDEX.md](docs/reference/API_INDEX.md) — bảng method theo 11 API group.
+5. Guide đúng domain trong [docs/guides/](docs/guides/).
+6. DTO field qua [docs/reference/dto/](docs/reference/dto/) hoặc grep [docs/reference/DTO_INDEX.md](docs/reference/DTO_INDEX.md).
+7. Public type trong `dist/**/*.d.ts` — fallback khi docs chưa cover.
+
+Bảng chọn API group theo yêu cầu: xem [docs/AI_CHEATSHEET.md § 2](docs/AI_CHEATSHEET.md#2-decision-tree-tôi-cần-làm-gì). Rule router/permission/socket: xem [docs/RULES.md](docs/RULES.md); permission operation/flag offline: [docs/reference/PERMISSION_RULES.md](docs/reference/PERMISSION_RULES.md).
+
+## 2. Khi nào được đọc `src/`
+
+Chỉ đọc `src/` khi:
+
+- Sửa chính SDK.
+- Debug behavior nội bộ repo.
+- Verify public contract mà docs + `dist` chưa mô tả đủ.
+
+Với mục tiêu tích hợp package: **không** bắt đầu từ `src/`, không trích dẫn `src/` trong integration code. Nguồn chính: `AI_CHEATSHEET.md` → `RULES.md` → guide domain → `API_<GROUP>.md` → `dist/*.d.ts`.
+
+Nếu `docs` + `dist` vẫn chưa đủ kết luận, hỏi lại con người hoặc ghi rõ giả định — không bịa behavior.
+
+## 3. Scenario end-to-end
+
+16 scenario end-to-end (init, login, socket, realtime event, matchmaking, store, cloudscript, cleanup, diagnose permission, ...): [docs/COOKBOOK.md](docs/COOKBOOK.md).

package/README.MD

@@ -1 +1,420 @@
-This is GearN-typescript-client-sdk use for GearN-server
+# GearN TypeScript Client SDK
+
+SDK TypeScript client cho GearN Server.
+
+`GNNetwork` là entrypoint duy nhất ở tầng public API. Sau `init()`, toàn bộ thao tác đi qua các nhóm API tĩnh, gồm: `GNNetwork.authenticate`, `GNNetwork.masterPlayer`, `GNNetwork.gamePlayer`, `GNNetwork.characterPlayer`, `GNNetwork.group`, `GNNetwork.inventory`, `GNNetwork.storeInventory`, `GNNetwork.content`, `GNNetwork.multiplayer`, `GNNetwork.cloudScript`, `GNNetwork.dashboard`.
+
+> **AI / code assistant:** đọc [docs/AI_CHEATSHEET.md](docs/AI_CHEATSHEET.md) trước (one-page), rồi [docs/RULES.md](docs/RULES.md) cho rule chi tiết (route, permission, self/other-self, socket, error). Machine-readable manifest: [docs/ai-manifest.json](docs/ai-manifest.json).
+
+Package publish: `@xmobitea/gn-typescript-client`. Rule canonical: [docs/RULES.md](docs/RULES.md).
+
+## 1. Yêu cầu
+
+- Node.js ≥ 20.
+- Custom DTO có decorator: bật `experimentalDecorators` + `emitDecoratorMetadata` trong `tsconfig.json`.
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+## 2. Cài đặt
+
+```bash
+npm install @xmobitea/gn-typescript-client
+```
+
+## 3. Cách SDK hoạt động
+
+Flow chuẩn:
+
+1. Tạo `GNServerSettings`.
+```ts
+const settings = new GNServerSettings();
+settings.config({
+  serverAddress: "api.example.com",
+  serverPort: 443,
+  serverSocketPort: 443,
+  useSsl: true,
+  useSocket: true,
+  useHttp: true,
+  defaultTimeoutInSeconds: 20,
+  messageType: MessageType.MsgPack,
+  sendRate: 20,
+  reconnectDelay: 5000,
+  pingInterval: 20000,
+  pingTimeout: 20000,
+  logType: LogType.Error,
+  secretKey: "<secret-key>",
+  gameId: "<game-id>",
+});
+```
+2. Gọi `GNNetwork.init(settings)` đúng 1 lần khi app chạy lần đầu tiên.
+```ts
+GNNetwork.init(settings);
+```
+3. Gọi API qua `GNNetwork.*`.
+```ts
+const infoRequestParam = new AuthenticateModels.InfoRequestParam();
+infoRequestParam.countryCode = true;
+infoRequestParam.displayName = true;
+
+const loginRequest = new AuthenticateModels.LoginByCustomIdRequestData();
+loginRequest.customId = "a custom id, store this custom id and use it to login next time";
+loginRequest.createPlayerIfNotExists = true;
+loginRequest.infoRequestParam = infoRequestParam;
+
+const loginByCustomIdResponse = await GNNetwork.authenticate.loginByCustomIdAsync(loginRequest);
+
+if (loginByCustomIdResponse.returnCode != ReturnCode.Ok || loginByCustomIdResponse.errorCode != ErrorCode.Ok) {
+  console.log("login by custom id failed because the returnCode is " + loginByCustomIdResponse.returnCode + ", errorCode is " + loginByCustomIdResponse.errorCode);
+  return;
+}
+
+console.log("Your userId: " + loginByCustomIdResponse.responseData.userId);
+console.log("Your countryCode: " + loginByCustomIdResponse.responseData.infoResponseParameters.countryCode);
+console.log("Your displayName: " + loginByCustomIdResponse.responseData.infoResponseParameters.displayName);
+```
+4. Nếu app cần realtime, sau khi đã có `authToken` → `GNNetwork.connectSocket()`, đồng thời `GearN Server` phải settings options.socketAppSettings.enable = true.
+5. Socket auto-auth nếu token đã cache; chỉ `GNNetwork.sendRequestAuthSocket()` thủ công khi cần re-auth.
+
+11 API group public:
+
+- `GNNetwork.authenticate` — player login/register/refresh. [Guide](docs/guides/AUTHENTICATE.md).
+- `GNNetwork.masterPlayer` — master player account/profile/identity. [Guide](docs/guides/MASTER_PLAYER.md).
+- `GNNetwork.gamePlayer` — game player gameplay/profile/friend/group/character. [Guide](docs/guides/GAME_PLAYER.md).
+- `GNNetwork.characterPlayer` — character-level (trong trường hợp 1 game player có nhiều nhân vật nhỏ) gameplay/social. [Guide](docs/guides/CHARACTER_PLAYER.md).
+- `GNNetwork.group` — group metadata/member/message/currency. [Guide](docs/guides/GROUP.md).
+- `GNNetwork.inventory` — inventory item metadata, statistics, log. [Guide](docs/guides/INVENTORY.md).
+- `GNNetwork.storeInventory` — store catalog, buy/present, receipt validation. [Guide](docs/guides/STORE_INVENTORY.md).
+- `GNNetwork.content` — content config, file upload/download metadata, small game asset, avatar asset. [Guide](docs/guides/CONTENT.md).
+- `GNNetwork.multiplayer` — matchmaking ticket, handle matchmaking trận đấu (HTTP, không socket). [Guide](docs/guides/MULTIPLAYER.md).
+- `GNNetwork.cloudScript` — CloudScript publish/version/execute, khi cần phải phối hợp các function lại với nhau, hoặc cần để server validate, cần phải viết cloudScript code từ `GearN Dashboard`. [Guide](docs/guides/CLOUDSCRIPT.md).
+- `GNNetwork.dashboard` — admin login + quản trị game/secret/analytics, không nên sử dụng nếu code game client. [Guide](docs/guides/DASHBOARD.md).
+
+## 4. Khởi tạo cơ bản
+
+```ts
+import {
+  GNNetwork,
+  GNServerSettings,
+  LogType,
+  MessageType,
+} from "@xmobitea/gn-typescript-client";
+
+const settings = new GNServerSettings();
+settings.config({
+  serverAddress: "127.0.0.1",          // GearN Server host / IP
+  serverPort: 2202,                    // HTTP port, dựa vào options.applicationSettings.port và options.httpAppSettings.enable của GearN Server
+  serverSocketPort: 2901,              // Socket port, dựa vào options.applicationSettings.socketPort của GearN Server
+  useSsl: false,                       // true khi public endpoint dùng HTTPS, nếu useSsl thì setup serverPort và serverSocketPort thành -1, đồng thời serverAddress là url hợp lệ
+  useSocket: true,                     // client muốn sử dụng socket để nhận các gói tin chủ động từ phía GearN Server, dựa vào options.socketAppSettings.enable của GearN Server
+  useHttp: true,                       // luôn luôn là true, dựa vào options.httpAppSettings.enable của GearN Server
+  defaultTimeoutInSeconds: 20,         // default timeout tính bằng giây, thời gian để timeout tính từ lúc bắt đầu gửi OperationRequest và chờ OperationResponse từ phía server, nếu vượt quá thời gian này, 1 mã lỗi ReturnCode.OperationTimeout sẽ được trả về
+  messageType: MessageType.MsgPack,    // browser client sẽ tự fallback JSON cho HTTP, sử dụng msgPack giúp gói tin nhỏ nhẹ hơn nếu là client hoặc server, tăng tỉ lệ gửi thành công và tránh mất nhiều bandwidth, băng thông, dựa vào options.httpAppSettings.enablePostViaMsgPack và options.httpAppSettings.enablePostViaJson của GearN Server
+  sendRate: 20,                        // tỉ lệ gửi OperationRequest mỗi giây, 20 có nghĩa là gửi 20 OperationRequest mỗi giây
+  reconnectDelay: 5000,                // khi sử dụng socket, reconnectDelay socket io
+  pingInterval: 20000,                 // khi sử dụng socket, pingInterval socket io
+  pingTimeout: 20000,                  // khi sử dụng socket, pingTimeout socket io
+  secretKey: "secret-key",             // secretKey để có thể dùng client này, lấy từ GearN Dashboard tab Settings/SecretInfo, lựa chọn secretKey với các Permission Rules phù hợp
+  gameId: "game-id",                   // game id dành cho secretKey trong settings này hoặc override lại để chọn đúng game environment phù hợp, lấy từ GearN Dashboard từ tab Settings/SecretInfo
+  logType: LogType.All,                // console log ra tất cả vấn đề thuộc loại nào
+});
+
+GNNetwork.init(settings);
+```
+
+Full field schema: [docs/reference/CONFIG.md](docs/reference/CONFIG.md). Rule route / permission / self / other-self: [docs/RULES.md](docs/RULES.md).
+
+## 5. Quick start: login bằng custom device id
+
+```ts
+import {
+  GNNetwork,
+  AuthenticateModels,
+  ReturnCode,
+  ErrorCode,
+} from "@xmobitea/gn-typescript-client";
+
+const infoRequest = new AuthenticateModels.InfoRequestParam();
+infoRequest.displayName = true;
+infoRequest.avatar = true;
+infoRequest.playerDatas = true;
+
+const request = new AuthenticateModels.LoginByCustomDeviceIdRequestData();
+request.customDeviceId = "device-000001";
+request.createPlayerIfNotExists = true;
+request.infoRequestParam = infoRequest;
+
+const res = await GNNetwork.authenticate.loginByCustomDeviceIdAsync(request);
+
+if (res.returnCode !== ReturnCode.Ok) throw new Error(res.debugMessage);
+if (res.errorCode  !== ErrorCode.Ok)  throw new Error(`Business error: ${res.errorCode}`);
+
+console.log("userId",    res.responseData.userId);
+console.log("userId",    GNNetwork.getAuthenticateStatus().getUserId());
+console.log("authToken", res.responseData.authToken);
+console.log("authToken", GNNetwork.getAuthenticateStatus().getAuthToken());
+console.log("player",    res.responseData);
+```
+
+## 6. Login bằng account
+
+```ts
+import {
+  GNNetwork,
+  AuthenticateModels,
+  ReturnCode,
+  ErrorCode,
+} from "@xmobitea/gn-typescript-client";
+
+const infoRequest = new AuthenticateModels.InfoRequestParam();
+infoRequest.displayName = true;
+infoRequest.playerStatistics = true;
+
+const request = new AuthenticateModels.LoginByAccountRequestData();
+request.username = "player001";
+request.password = "12345678";
+request.infoRequestParam = infoRequest;
+
+const res = await GNNetwork.authenticate.loginByAccountAsync(request);
+if (res.returnCode !== ReturnCode.Ok) throw new Error(res.debugMessage);
+if (res.errorCode  !== ErrorCode.Ok)  throw new Error(`Business error: ${res.errorCode}`);
+```
+
+## 7. Socket
+
+```ts
+import { GNNetwork } from "@xmobitea/gn-typescript-client";
+
+// Subscribe TRƯỚC connect để không miss event ngay sau handshake
+GNNetwork.subscriberOnConnectHandler(() => {
+  console.log("socket connected", GNNetwork.getSocketSId());
+});
+
+GNNetwork.subscriberOnDisconnectHandler(() => {
+  console.log("socket disconnected");
+});
+
+GNNetwork.setOnEventHandler((event) => {
+  console.log("eventCode", event.getEventCode());
+  console.log("parameters", event.getParameters()?.toData());
+});
+
+// Gọi sau khi đã login HTTP thành công
+GNNetwork.connectSocket();
+```
+
+Re-auth thủ công (nếu socket connect trước token hoặc token vừa đổi):
+
+```ts
+if (GNNetwork.isSocketConnected() && GNNetwork.getAuthenticateStatus().getAuthToken()) {
+  GNNetwork.sendRequestAuthSocket();
+}
+```
+
+Helper:
+
+- `GNNetwork.isSocketConnected()` — trạng thái socket session id.
+- `GNNetwork.getPing()` — ping trung bình từ active transport.
+- `GNNetwork.syncTs()` — sync local estimate server timestamp.
+
+Realtime event handler (6 handler, subscribe bằng gán `static onUpdate`): [docs/reference/EVENTS.md](docs/reference/EVENTS.md).
+
+## 8. Dashboard / admin login
+
+`DashboardApi` public wrapper đi `RequestRole.Client`. Sau `loginByAdminAccountAsync`, backend resolve admin context từ `authToken`.
+
+```ts
+import {
+  GNNetwork,
+  DashboardModels,
+  ReturnCode,
+  ErrorCode,
+} from "@xmobitea/gn-typescript-client";
+
+const request = new DashboardModels.LoginByAdminAccountRequestData();
+request.username = "gnadmin";
+request.password = "123456";
+
+const res = await GNNetwork.dashboard.loginByAdminAccountAsync(request);
+if (res.returnCode !== ReturnCode.Ok) throw new Error(res.debugMessage);
+if (res.errorCode  !== ErrorCode.Ok)  throw new Error(`Business error: ${res.errorCode}`);
+```
+
+Rule chi tiết DashboardApi: [docs/guides/DASHBOARD.md](docs/guides/DASHBOARD.md).
+
+## 9. Method signature
+
+Signature đầy đủ + bảng override param (`overrideAuthToken`, `overrideSecretKey`, `customTags`, `timeout`): [docs/RULES.md § 8](docs/RULES.md#8-method-signature--override-params).
+
+## 10. Response model
+
+Typed response có 5 public field (không getter): `returnCode`, `errorCode`, `invalidMembers`, `debugMessage`, `responseData`. Pattern check 2 tầng + full table ReturnCode/ErrorCode: [docs/reference/ERROR_HANDLING.md](docs/reference/ERROR_HANDLING.md).
+
+## 11. Auth state, gameId, health check, upload
+
+```ts
+// Auth state
+GNNetwork.getAuthenticateStatus().getAuthToken();
+GNNetwork.getAuthenticateStatus().getUserId();
+
+// trong trường hợp secret key có thể dùng cho game id nào cũng được, trường hợp muốn dùng riêng cho game id xác định thì sử dụng hàm này
+GNNetwork.getGNServerSettings().setGameId("your-game-id");
+
+// Health check
+await GNNetwork.healthCheckAsync();
+
+// Auth info
+await GNNetwork.getAuthInfoAsync("some-auth-token");
+
+// Upload file (cần authToken hợp lệ)
+const bytes = new Uint8Array([1, 2, 3, 4]);
+await GNNetwork.uploadFileAsync("file-001", bytes, "demo.bin", "application/octet-stream");
+
+// Download URL từ download token
+GNNetwork.getDownloadFileUrl("download-token-from-server");
+```
+
+## 12. Advanced: ConverterService cho custom DTO
+
+`ConverterService` là helper public để convert object typed có decorator ↔ `GNHashtable` / `GNArray`. Flow SDK bình thường không cần gọi tay (vì `GNNetwork.init()` đã tự init converter).
+
+Chỉ dùng khi tự define DTO có decorator:
+
+```ts
+import {
+  ConverterService,
+  StringDataMember,
+  NumberDataMember,
+  BooleanDataMember,
+  GNArrayDataMember,
+  GNHashtableDataMember,
+  DataMember,
+  GNHashtable,
+} from "@xmobitea/gn-typescript-client";
+
+class ProfileStats {
+  @NumberDataMember({ code: "level", defaultValue: 1, mustInt: true }) level: number;
+  @NumberDataMember({ code: "power", defaultValue: 0 }) power: number;
+}
+
+class CustomProfile {
+  @StringDataMember({ code: "displayName", mustNonNull: true }) displayName: string;
+  @NumberDataMember({ code: "age", isOptional: true, minValue: 0, mustInt: true }) age?: number;
+  @BooleanDataMember({ code: "isVip", defaultValue: false }) isVip: boolean;
+  @GNHashtableDataMember({ code: "stats" }) stats: ProfileStats;
+  @DataMember({ code: "metadata", isOptional: true }) metadata?: any;
+}
+
+const source = GNHashtable.builder()
+  .add("displayName", "Player 01")
+  .add("age", 20)
+  .add("isVip", true)
+  .add("stats", GNHashtable.builder().add("level", 12).add("power", 3456).build())
+  .build();
+
+const profile = ConverterService.deserializeObject(source, CustomProfile) as CustomProfile;
+const serialized = ConverterService.serializeObject(profile, CustomProfile);
+```
+
+Rule:
+
+- Dùng `GNNetwork.*` bình thường: không cần `ConverterService`.
+- Tự build custom DTO: dùng `deserializeObject / serializeObject / deserializeArray / serializeArray`.
+- `GNArrayDataMember` với element typed: luôn truyền `elementCls`.
+- `DataMember` generic cho payload động: data có thể là raw `GNHashtable` / `GNArray`, gọi `.toData()` để lấy plain object.
+- Không gọi `ConverterService.init()` tay nếu đã `GNNetwork.init()`.
+
+## 13. Custom operation
+
+Low-level API để bọc operation chưa expose:
+
+```ts
+import {
+  GNNetwork,
+  CustomOperationRequestAbstract,
+  CustomOperationResponseAbstract,
+  RequestRole,
+  RequestType,
+  OperationCode,
+  ParameterCode,
+  StringDataMember,
+} from "@xmobitea/gn-typescript-client";
+
+class ExampleRequestData {
+  @StringDataMember({ code: ParameterCode.Key, mustNonNull: true }) public key: string;
+}
+
+class ExampleResponseData {
+  @StringDataMember({ code: ParameterCode.Value, isOptional: true }) public value?: string;
+}
+
+class ExampleRequest extends CustomOperationRequestAbstract<ExampleRequestData> {
+  protected override operationCode: string = OperationCode.GetCustomData;
+  protected override requestType: RequestType = RequestType.CharacterPlayer;
+  protected override role: RequestRole = RequestRole.Client;
+
+  constructor(requestData: ExampleRequestData, timeout: number) {
+    super(requestData, timeout);
+    this.requestDataCls = ExampleRequestData;
+  }
+}
+
+class ExampleResponse extends CustomOperationResponseAbstract<ExampleResponseData> {
+  constructor() {
+    super();
+    this.responseDataCls = ExampleResponseData;
+  }
+}
+
+const requestData = new ExampleRequestData();
+requestData.key = "tutorial";
+
+const res = await GNNetwork.sendViaHttpTRequestTResponseAsync(
+  new ExampleRequest(requestData, 20),
+  null,
+  null,
+  null,
+  ExampleResponse,
+);
+```
+
+## 14. Browser / Node / Cocos
+
+- Detect platform: `GNSupport.getPlatformType()`.
+- Browser + HTTP + MsgPack → SDK auto-fallback JSON.
+- Cocos Creator: giữ 2 flag TS decorator nếu có custom DTO. [Integration guide](docs/guides/COCOS_CREATOR_INTEGRATION.md).
+
+## 15. Build & publish
+
+```bash
+npm run test
+npm run build:node       # CommonJS cho Node
+npm run build:udm        # UMD
+npm run build:minudm     # UMD minified
+npm run build:cocos      # Cocos
+npm run build            # tất cả output chính
+```
+
+## 16. Lỗi hay gặp
+
+Full checklist + anti-patterns: [docs/RULES.md § 10](docs/RULES.md#10-anti-patterns--pitfalls). Return/error code table: [docs/reference/ERROR_HANDLING.md](docs/reference/ERROR_HANDLING.md).
+
+## 17. File tham khảo trong repo
+
+- Entry public API: `src/runtime/GNNetwork.ts`
+- Export surface: `src/index.ts`
+- Local debug: `index.js`
+
+## 18. TL;DR
+
+1. `GNNetwork.init(settings)` 1 lần.
+2. Mọi call qua `GNNetwork.*`.
+3. Check `returnCode` trước, `errorCode` sau.
+4. Socket: login HTTP → `connectSocket()`; chỉ `sendRequestAuthSocket()` khi cần re-auth thủ công.
+5. Rule chi tiết → [docs/RULES.md](docs/RULES.md).